Custom AudioStreams

    All audio resources require two audio based classes: AudioStream and AudioStreamPlayback. As a data container, AudioStream contains the resource and exposes itself to GDScript. AudioStream references its own internal custom AudioStreamPlayback which translates AudioStream into PCM data.

    This guide assumes the reader knows how to create C++ modules. If not, refer to this guide .

    • Adding custom audio queues

    • Adding support for more audio formats

    An AudioStream consists of three components: data container, stream name, and an AudioStreamPlayback friend class generator. Audio data can be loaded in a number of ways such as with an internal counter for a tone generator, internal/external buffer, or a file reference.

    Some AudioStreams need to be stateless such as objects loaded from ResourceLoader. ResourceLoader loads once and references the same object regardless how many times is called on a specific resource. Therefore, playback state must be self-contained in AudioStreamPlayback.

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

    Since AudioStreamPlayback is controlled by the audio thread, i/o and dynamic memory allocation are forbidden.

    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.         pcm_buffer = AudioServer::get_singleton()->audio_data_alloc(PCM_BUFFER_SIZE);
    11.         zeromem(pcm_buffer, PCM_BUFFER_SIZE);
    12.         AudioServer::get_singleton()->unlock();
    13. }
    14. AudioStreamPlaybackMyTone::~AudioStreamPlaybackMyTone() {
    15.         if(pcm_buffer) {
    16.                 AudioServer::get_singleton()->audio_data_free(pcm_buffer);
    17.                 pcm_buffer = NULL;
    19. }
    20. void AudioStreamPlaybackMyTone::stop() {
    21.         active = false;
    22.         base->reset();
    23. }
    24. void AudioStreamPlaybackMyTone::start(float p_from_pos) {
    25.         seek(p_from_pos);
    26.         active = true;
    27. }
    28. void AudioStreamPlaybackMyTone::seek(float p_time) {
    29.         float max = get_length();
    30.         if (p_time < 0) {
    31.                         p_time = 0;
    32.         }
    33.         base->set_position(uint64_t(p_time * base->mix_rate) << MIX_FRAC_BITS);
    34. }
    35. void AudioStreamPlaybackMyTone::mix(AudioFrame *p_buffer, float p_rate, int p_frames) {
    36.         ERR_FAIL_COND(!active);
    37.         if (!active) {
    38.                         return;
    39.         }
    40.         zeromem(pcm_buffer, PCM_BUFFER_SIZE);
    41.         int16_t *buf = (int16_t *)pcm_buffer;
    42.         base->gen_tone(buf, p_frames);
    44.         for(int i = 0; i < p_frames; i++) {
    45.                 float sample = float(buf[i]) / 32767.0;
    46.                 p_buffer[i] = AudioFrame(sample, sample);
    47.         }
    48. }
    49. int AudioStreamPlaybackMyTone::get_loop_count() const {
    50.         return 0;
    51. }
    52. float AudioStreamPlaybackMyTone::get_playback_position() const {
    53.         return 0.0;
    54. }
    55. float AudioStreamPlaybackMyTone::get_length() const {
    56.         return 0.0;
    57. }
    58. bool AudioStreamPlaybackMyTone::is_playing() const {
    59.         return active;
    60. }

    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.

    Instead of overloading mix, AudioStreamPlaybackResampled uses _mix_internal to query AudioFrames and get_stream_sampling_rate to query current mix rate.

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