自定义 AudioStream

前言

AudioStream是所有音频发射对象的基类.AudioStreamPlayer绑定到AudioStream以将PCM数据发送到管理音频驱动程序的AudioServer.

所有音频资源都需要两个基于音频的类:AudioStream和AudioStreamPlayback. 作为数据容器,AudioStream包含资源并将其自身暴露给GDScript.AudioStream引用其自己的内部自定义AudioStreamPlayback, 该AudioStreamPlayback将AudioStream转换为PCM数据.

本指南假设读者知道如何创建C++模块. 如果没有, 请参考该指南 自定义 C++ 模块.

参考：

可以做什么？

  • 绑定外部库(如Wwise, FMOD等).

  • 添加自定义音频队列

  • 添加对更多音频格式的支持

创建 AudioStream

AudioStream由三个组件组成: 数据容器, 流名称和AudioStreamPlayback朋友类生成器. 音频数据可以通过多种方式加载, 例如使用用于音调发生器的内部计数器, 内部/外部缓冲区, 或文件引用.

某些AudioStream需要是无状态的, 例如从ResourceLoader加载的对象.ResourceLoader加载一次并引用同一对象, 而不管在该特定资源上调用了多少次 load. 因此, 播放状态必须被包含在AudioStreamPlayback中.

  1. /* audiostream_mytone.h */
  3. #include "core/reference.h"
  4. #include "core/resource.h"
  5. #include "servers/audio/audio_stream.h"
  7. class AudioStreamMyTone : public AudioStream {
  8.         GDCLASS(AudioStreamMyTone, AudioStream)
  10. private:
  11.         friend class AudioStreamPlaybackMyTone;
  12.         uint64_t pos;
  13.         int mix_rate;
  14.         bool stereo;
  15.         int hz;
  17. public:
  18.         void reset();
  19.         void set_position(uint64_t pos);
  20.         virtual Ref<AudioStreamPlayback> instance_playback();
  21.         virtual String get_stream_name() const;
  22.         void gen_tone(int16_t *pcm_buf, int size);
  23.         virtual float get_length() const { return 0; } // if supported, otherwise return 0
  24.         AudioStreamMyTone();
  26. protected:
  27.         static void _bind_methods();
  28. };
  1. /* audiostream_mytone.cpp */
  3. #include "audiostream_mytone.h"
  5. AudioStreamMyTone::AudioStreamMyTone()
  6.                 : mix_rate(44100), stereo(false), hz(639) {
  7. }
  9. Ref<AudioStreamPlayback> AudioStreamMyTone::instance_playback() {
  10.         Ref<AudioStreamPlaybackMyTone> talking_tree;
  11.         talking_tree.instance();
  12.         talking_tree->base = Ref<AudioStreamMyTone>(this);
  13.         return talking_tree;
  14. }
  16. String AudioStreamMyTone::get_stream_name() const {
  17.         return "MyTone";
  18. }
  19. void AudioStreamMyTone::reset() {
  20.         set_position(0);
  21. }
  22. void AudioStreamMyTone::set_position(uint64_t p) {
  23.         pos = p;
  24. }
  25. void AudioStreamMyTone::gen_tone(int16_t *pcm_buf, int size) {
  26.         for (int i = 0; i < size; i++) {
  27.                 pcm_buf[i] = 32767.0 * sin(2.0 * Math_PI * double(pos + i) / (double(mix_rate) / double(hz)));
  28.         }
  29.         pos += size;
  30. }
  31. void AudioStreamMyTone::_bind_methods() {
  32.         ClassDB::bind_method(D_METHOD("reset"), &AudioStreamMyTone::reset);
  33.         ClassDB::bind_method(D_METHOD("get_stream_name"), &AudioStreamMyTone::get_stream_name);
  34. }

参考：

创建 AudioStreamPlayback

AudioStreamPlayer使用 mix 回调来获取PCM数据. 回调必须与采样率匹配并填充缓冲区.

由于AudioStreamPlayback由音频线程控制, 因此禁止进行i/o和动态内存分配.

  1. /*  audiostreamplayer_mytone.h */
  3. #include "core/reference.h"
  4. #include "core/resource.h"
  5. #include "servers/audio/audio_stream.h"
  7. class AudioStreamPlaybackMyTone : public AudioStreamPlayback {
  8.         GDCLASS(AudioStreamPlaybackMyTone, AudioStreamPlayback)
  9.         friend class AudioStreamMyTone;
  11. private:
  12.         enum {
  13.                 PCM_BUFFER_SIZE = 4096
  14.         };
  15.         enum {
  16.                 MIX_FRAC_BITS = 13,
  17.                 MIX_FRAC_LEN = (1 << MIX_FRAC_BITS),
  18.                 MIX_FRAC_MASK = MIX_FRAC_LEN - 1,
  19.         };
  20.         void *pcm_buffer;
  21.         Ref<AudioStreamMyTone> base;
  22.         bool active;
  24. public:
  25.         virtual void start(float p_from_pos = 0.0);
  26.         virtual void stop();
  27.         virtual bool is_playing() const;
  28.         virtual int get_loop_count() const; // times it looped
  29.         virtual float get_playback_position() const;
  30.         virtual void seek(float p_time);
  31.         virtual void mix(AudioFrame *p_buffer, float p_rate_scale, int p_frames);
  32.         virtual float get_length() const; // if supported, otherwise return 0
  33.         AudioStreamPlaybackMyTone();
  34.         ~AudioStreamPlaybackMyTone();
  35. };
  1. /* audiostreamplayer_mytone.cpp */
  3. #include "audiostreamplayer_mytone.h"
  5. #include "core/math/math_funcs.h"
  6. #include "core/print_string.h"
  8. AudioStreamPlaybackMyTone::AudioStreamPlaybackMyTone()
  9.                 : active(false) {
  10.         AudioServer::get_singleton()->lock();
  11.         pcm_buffer = AudioServer::get_singleton()->audio_data_alloc(PCM_BUFFER_SIZE);
  12.         zeromem(pcm_buffer, PCM_BUFFER_SIZE);
  13.         AudioServer::get_singleton()->unlock();
  14. }
  15. AudioStreamPlaybackMyTone::~AudioStreamPlaybackMyTone() {
  16.         if(pcm_buffer) {
  17.                 AudioServer::get_singleton()->audio_data_free(pcm_buffer);
  18.                 pcm_buffer = NULL;
  19.         }
  20. }
  21. void AudioStreamPlaybackMyTone::stop() {
  22.         active = false;
  23.         base->reset();
  24. }
  25. void AudioStreamPlaybackMyTone::start(float p_from_pos) {
  26.         seek(p_from_pos);
  27.         active = true;
  28. }
  29. void AudioStreamPlaybackMyTone::seek(float p_time) {
  30.         float max = get_length();
  31.         if (p_time < 0) {
  32.                         p_time = 0;
  33.         }
  34.         base->set_position(uint64_t(p_time * base->mix_rate) << MIX_FRAC_BITS);
  35. }
  36. void AudioStreamPlaybackMyTone::mix(AudioFrame *p_buffer, float p_rate, int p_frames) {
  37.         ERR_FAIL_COND(!active);
  38.         if (!active) {
  39.                         return;
  40.         }
  41.         zeromem(pcm_buffer, PCM_BUFFER_SIZE);
  42.         int16_t *buf = (int16_t *)pcm_buffer;
  43.         base->gen_tone(buf, p_frames);
  45.         for(int i = 0; i < p_frames; i++) {
  46.                 float sample = float(buf[i]) / 32767.0;
  47.                 p_buffer[i] = AudioFrame(sample, sample);
  48.         }
  49. }
  50. int AudioStreamPlaybackMyTone::get_loop_count() const {
  51.         return 0;
  52. }
  53. float AudioStreamPlaybackMyTone::get_playback_position() const {
  54.         return 0.0;
  55. }
  56. float AudioStreamPlaybackMyTone::get_length() const {
  57.         return 0.0;
  58. }
  59. bool AudioStreamPlaybackMyTone::is_playing() const {
  60.         return active;
  61. }

重采样

Godot的AudioServer目前使用44100Hz采样率. 当需要其他采样率如48000时, 要么提供一个, 要么使用AudioStreamPlaybackResampled.Godot为音频重采样提供立方插值.

AudioStreamPlaybackResampled不是重载 mix , 而是使用 _mix_internal 来查询AudioFrames, 并使用 get_stream_sampling_rate 来查询当前的混合率.

  1. #include "core/reference.h"
  2. #include "core/resource.h"
  3. #include "servers/audio/audio_stream.h"
  5. class AudioStreamMyToneResampled;
  7. class AudioStreamPlaybackResampledMyTone : public AudioStreamPlaybackResampled {
  8.         GDCLASS(AudioStreamPlaybackResampledMyTone, AudioStreamPlaybackResampled)
  9.         friend class AudioStreamMyToneResampled;
  11. private:
  12.         enum {
  13.                 PCM_BUFFER_SIZE = 4096
  14.         };
  15.         enum {
  16.                 MIX_FRAC_BITS = 13,
  17.                 MIX_FRAC_LEN = (1 << MIX_FRAC_BITS),
  18.                 MIX_FRAC_MASK = MIX_FRAC_LEN - 1,
  19.         };
  20.         void *pcm_buffer;
  21.         Ref<AudioStreamMyToneResampled> base;
  22.         bool active;
  24. protected:
  25.         virtual void _mix_internal(AudioFrame *p_buffer, int p_frames);
  27. public:
  28.         virtual void start(float p_from_pos = 0.0);
  29.         virtual void stop();
  30.         virtual bool is_playing() const;
  31.         virtual int get_loop_count() const; // times it looped
  32.         virtual float get_playback_position() const;
  33.         virtual void seek(float p_time);
  34.         virtual float get_length() const; // if supported, otherwise return 0
  35.         virtual float get_stream_sampling_rate();
  36.         AudioStreamPlaybackResampledMyTone();
  37.         ~AudioStreamPlaybackResampledMyTone();
  38. };
  1. #include "mytone_audiostream_resampled.h"
  3. #include "core/math/math_funcs.h"
  4. #include "core/print_string.h"
  6. AudioStreamPlaybackResampledMyTone::AudioStreamPlaybackResampledMyTone()
  7.                 : active(false) {
  8.         AudioServer::get_singleton()->lock();
  9.         pcm_buffer = AudioServer::get_singleton()->audio_data_alloc(PCM_BUFFER_SIZE);
  10.         zeromem(pcm_buffer, PCM_BUFFER_SIZE);
  11.         AudioServer::get_singleton()->unlock();
  12. }
  13. AudioStreamPlaybackResampledMyTone::~AudioStreamPlaybackResampledMyTone() {
  14.         if (pcm_buffer) {
  15.                 AudioServer::get_singleton()->audio_data_free(pcm_buffer);
  16.                 pcm_buffer = NULL;
  17.         }
  18. }
  19. void AudioStreamPlaybackResampledMyTone::stop() {
  20.         active = false;
  21.         base->reset();
  22. }
  23. void AudioStreamPlaybackResampledMyTone::start(float p_from_pos) {
  24.         seek(p_from_pos);
  25.         active = true;
  26. }
  27. void AudioStreamPlaybackResampledMyTone::seek(float p_time) {
  28.         float max = get_length();
  29.         if (p_time < 0) {
  30.                         p_time = 0;
  31.         }
  32.         base->set_position(uint64_t(p_time * base->mix_rate) << MIX_FRAC_BITS);
  33. }
  34. void AudioStreamPlaybackResampledMyTone::_mix_internal(AudioFrame *p_buffer, int p_frames) {
  35.         ERR_FAIL_COND(!active);
  36.         if (!active) {
  37.                 return;
  38.         }
  39.         zeromem(pcm_buffer, PCM_BUFFER_SIZE);
  40.         int16_t *buf = (int16_t *)pcm_buffer;
  41.         base->gen_tone(buf, p_frames);
  43.         for(int i = 0;  i < p_frames; i++) {
  44.                 float sample = float(buf[i]) / 32767.0;
  45.                         p_buffer[i] = AudioFrame(sample, sample);
  46.         }
  47. }
  48. float AudioStreamPlaybackResampledMyTone::get_stream_sampling_rate() {
  49.         return float(base->mix_rate);
  50. }
  51. int AudioStreamPlaybackResampledMyTone::get_loop_count() const {
  52.         return 0;
  53. }
  54. float AudioStreamPlaybackResampledMyTone::get_playback_position() const {
  55.         return 0.0;
  56. }
  57. float AudioStreamPlaybackResampledMyTone::get_length() const {
  58.         return 0.0;
  59. }
  60. bool AudioStreamPlaybackResampledMyTone::is_playing() const {
  61.         return active;
  62. }

参考：