自定义音频流

简介

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

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

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

参考：

可以做什么？

  • 绑定外部库（如Wwise、FMOD等）。
  • 添加自定义音频队列
  • 添加对更多音频格式的支持

创建一个音频流

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’s AudioServer currently uses 44100 Hz sample rate. When other sample rates are needed such as 48000, either provide one or use AudioStreamPlaybackResampled. Godot provides cubic interpolation for audio resampling.

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. }

参考：