diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h index 4886f86f97..9b7cd87bf4 100644 --- a/include/SDL3/SDL_audio.h +++ b/include/SDL3/SDL_audio.h @@ -703,33 +703,40 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, * \sa SDL_PutAudioStreamData * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamAvailable - * \sa SDL_SetAudioStreamSpeed + * \sa SDL_SetAudioStreamFrequencyRatio */ extern DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); /** - * Get the playback speed of an audio stream. + * Get the frequency ratio of an audio stream. * * \param stream the SDL_AudioStream to query. - * \returns the playback speed of the stream, or 0.0 on error + * \returns the frequency ratio of the stream, or 0.0 on error * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * * \since This function is available since SDL 3.0.0. * - * \sa SDL_SetAudioStreamSpeed + * \sa SDL_SetAudioStreamFrequencyRatio */ -extern DECLSPEC float SDLCALL SDL_GetAudioStreamSpeed(SDL_AudioStream *stream); +extern DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStream *stream); /** - * Change the playback speed of an audio stream. - * - * \param stream The stream the speed is being changed - * \param speed The new speed. 1.0 is normal speed, 1.2 is 20% faster, etc. - * Must be between 0.01 and 100. + * Change the frequency ratio of an audio stream. + * + * The frequency ratio is used to adjust the rate at which input data is consumed. + * Changing this effectively modifies the speed and pitch of the audio. + * A value greater than 1.0 will play the audio faster, and at a higher pitch. + * A value less than 1.0 will play the audio slower, and at a lower pitch. + * + * This is applied during SDL_GetAudioStreamData, and can be continuously changed + * to create various effects. + * + * \param stream The stream the frequency ratio is being changed + * \param ratio The frequency ratio. 1.0 is normal speed. Must be between 0.01 and 100. * \returns 0 on success, or -1 on error. * * \threadsafety It is safe to call this function from any thread, as it holds @@ -737,11 +744,10 @@ extern DECLSPEC float SDLCALL SDL_GetAudioStreamSpeed(SDL_AudioStream *stream); * * \since This function is available since SDL 3.0.0. * - * \sa SDL_GetAudioStreamSpeed + * \sa SDL_GetAudioStreamFrequencyRatio * \sa SDL_SetAudioStreamFormat */ -extern DECLSPEC int SDLCALL SDL_SetAudioStreamSpeed(SDL_AudioStream *stream, - float speed); +extern DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); /** * Add data to be converted/resampled to the stream. diff --git a/src/audio/SDL_audiocvt.c b/src/audio/SDL_audiocvt.c index 6757becbd5..7d9120e941 100644 --- a/src/audio/SDL_audiocvt.c +++ b/src/audio/SDL_audiocvt.c @@ -1063,7 +1063,7 @@ static int GetAudioSpecFrameSize(const SDL_AudioSpec* spec) static Sint64 GetStreamResampleRate(SDL_AudioStream* stream, int src_freq) { - src_freq = (int)((float)src_freq * stream->speed); + src_freq = (int)((float)src_freq * stream->freq_ratio); return GetResampleRate(src_freq, stream->dst_spec.freq); } @@ -1101,7 +1101,7 @@ SDL_AudioStream *SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_ return NULL; } - retval->speed = 1.0f; + retval->freq_ratio = 1.0f; retval->queue = CreateAudioQueue(4096); retval->track_changed = SDL_TRUE; @@ -1242,7 +1242,7 @@ int SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_s return 0; } -float SDL_GetAudioStreamSpeed(SDL_AudioStream *stream) +float SDL_GetAudioStreamFrequencyRatio(SDL_AudioStream *stream) { if (!stream) { SDL_InvalidParamError("stream"); @@ -1250,30 +1250,30 @@ float SDL_GetAudioStreamSpeed(SDL_AudioStream *stream) } SDL_LockMutex(stream->lock); - float speed = stream->speed; + float freq_ratio = stream->freq_ratio; SDL_UnlockMutex(stream->lock); - return speed; + return freq_ratio; } -int SDL_SetAudioStreamSpeed(SDL_AudioStream *stream, float speed) +int SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float freq_ratio) { if (!stream) { return SDL_InvalidParamError("stream"); } // Picked mostly arbitrarily. - static const float min_speed = 0.01f; - static const float max_speed = 100.0f; + static const float min_freq_ratio = 0.01f; + static const float max_freq_ratio = 100.0f; - if (speed < min_speed) { - return SDL_SetError("Speed is too low"); - } else if (speed > max_speed) { - return SDL_SetError("Speed is too high"); + if (freq_ratio < min_freq_ratio) { + return SDL_SetError("Frequency ratio is too low"); + } else if (freq_ratio > max_freq_ratio) { + return SDL_SetError("Frequency ratio is too high"); } SDL_LockMutex(stream->lock); - stream->speed = speed; + stream->freq_ratio = freq_ratio; SDL_UnlockMutex(stream->lock); return 0; diff --git a/src/audio/SDL_sysaudio.h b/src/audio/SDL_sysaudio.h index eceb80efd7..ce50835739 100644 --- a/src/audio/SDL_sysaudio.h +++ b/src/audio/SDL_sysaudio.h @@ -170,7 +170,7 @@ struct SDL_AudioStream SDL_AudioSpec src_spec; SDL_AudioSpec dst_spec; - float speed; + float freq_ratio; SDL_AudioQueue* queue; diff --git a/src/dynapi/SDL_dynapi.sym b/src/dynapi/SDL_dynapi.sym index dec0257720..b122296f44 100644 --- a/src/dynapi/SDL_dynapi.sym +++ b/src/dynapi/SDL_dynapi.sym @@ -902,8 +902,8 @@ SDL3_0.0.0 { SDL_WriteS64BE; SDL_GDKGetDefaultUser; SDL_SetWindowFocusable; - SDL_GetAudioStreamSpeed; - SDL_SetAudioStreamSpeed; + SDL_GetAudioStreamFrequencyRatio; + SDL_SetAudioStreamFrequencyRatio; # extra symbols go here (don't modify this line) local: *; }; diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h index faa73153a7..e78911a93d 100644 --- a/src/dynapi/SDL_dynapi_overrides.h +++ b/src/dynapi/SDL_dynapi_overrides.h @@ -927,5 +927,5 @@ #define SDL_WriteS64BE SDL_WriteS64BE_REAL #define SDL_GDKGetDefaultUser SDL_GDKGetDefaultUser_REAL #define SDL_SetWindowFocusable SDL_SetWindowFocusable_REAL -#define SDL_GetAudioStreamSpeed SDL_GetAudioStreamSpeed_REAL -#define SDL_SetAudioStreamSpeed SDL_SetAudioStreamSpeed_REAL +#define SDL_GetAudioStreamFrequencyRatio SDL_GetAudioStreamFrequencyRatio_REAL +#define SDL_SetAudioStreamFrequencyRatio SDL_SetAudioStreamFrequencyRatio_REAL diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h index d0778b87ee..5ddb0a24e2 100644 --- a/src/dynapi/SDL_dynapi_procs.h +++ b/src/dynapi/SDL_dynapi_procs.h @@ -973,5 +973,5 @@ SDL_DYNAPI_PROC(SDL_bool,SDL_WriteS64BE,(SDL_RWops *a, Sint64 b),(a,b),return) SDL_DYNAPI_PROC(int,SDL_GDKGetDefaultUser,(XUserHandle *a),(a),return) #endif SDL_DYNAPI_PROC(int,SDL_SetWindowFocusable,(SDL_Window *a, SDL_bool b),(a,b),return) -SDL_DYNAPI_PROC(float,SDL_GetAudioStreamSpeed,(SDL_AudioStream *a),(a),return) -SDL_DYNAPI_PROC(int,SDL_SetAudioStreamSpeed,(SDL_AudioStream *a, float b),(a,b),return) +SDL_DYNAPI_PROC(float,SDL_GetAudioStreamFrequencyRatio,(SDL_AudioStream *a),(a),return) +SDL_DYNAPI_PROC(int,SDL_SetAudioStreamFrequencyRatio,(SDL_AudioStream *a, float b),(a,b),return) diff --git a/test/testaudiostreamdynamicresample.c b/test/testaudiostreamdynamicresample.c index 3094f4b119..f95512a8ef 100644 --- a/test/testaudiostreamdynamicresample.c +++ b/test/testaudiostreamdynamicresample.c @@ -143,7 +143,7 @@ static void skip_audio(float amount) SDL_LockAudioStream(stream); - speed = SDL_GetAudioStreamSpeed(stream); + speed = SDL_GetAudioStreamFrequencyRatio(stream); SDL_GetAudioStreamFormat(stream, NULL, &dst_spec); /* Gimme that crunchy audio */ @@ -151,7 +151,7 @@ static void skip_audio(float amount) new_spec.channels = 1; new_spec.freq = 4000; - SDL_SetAudioStreamSpeed(stream, 100.0f); + SDL_SetAudioStreamFrequencyRatio(stream, 100.0f); SDL_SetAudioStreamFormat(stream, NULL, &new_spec); num_frames = (int)(new_spec.freq * ((speed * amount) / 100.0f)); @@ -163,7 +163,7 @@ static void skip_audio(float amount) } SDL_SetAudioStreamFormat(stream, NULL, &dst_spec); - SDL_SetAudioStreamSpeed(stream, speed); + SDL_SetAudioStreamFrequencyRatio(stream, speed); SDL_UnlockAudioStream(stream); @@ -287,7 +287,7 @@ static void loop(void) if (sliders[0].changed) { sliders[0].changed = SDL_FALSE; - SDL_SetAudioStreamSpeed(stream, sliders[0].value); + SDL_SetAudioStreamFrequencyRatio(stream, sliders[0].value); } if (SDL_GetAudioStreamFormat(stream, &src_spec, &dst_spec) == 0) {