Renamed AudioStreamSpeed to AudioStreamFrequencyRatio

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.
+ * Change the frequency ratio of an audio stream.
  * 
- * \param stream The stream the speed is being changed
+ * The frequency ratio is used to adjust the rate at which input data is consumed.
- * \param speed The new speed. 1.0 is normal speed, 1.2 is 20% faster, etc.
+ * Changing this effectively modifies the speed and pitch of the audio.
- *              Must be between 0.01 and 100.
+ * 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,
+extern DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio);
-                                                    float speed);
 
 /**
  * Add data to be converted/resampled to the stream.

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 min_freq_ratio = 0.01f;
-    static const float max_speed = 100.0f;
+    static const float max_freq_ratio = 100.0f;
 
-    if (speed < min_speed) {
+    if (freq_ratio < min_freq_ratio) {
-        return SDL_SetError("Speed is too low");
+        return SDL_SetError("Frequency ratio is too low");
-    } else if (speed > max_speed) {
+    } else if (freq_ratio > max_freq_ratio) {
-        return SDL_SetError("Speed is too high");
+        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;

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;
 

src/dynapi/SDL_dynapi.sym

@@ -902,8 +902,8 @@ SDL3_0.0.0 {
     SDL_WriteS64BE;
     SDL_GDKGetDefaultUser;
     SDL_SetWindowFocusable;
-    SDL_GetAudioStreamSpeed;
+    SDL_GetAudioStreamFrequencyRatio;
-    SDL_SetAudioStreamSpeed;
+    SDL_SetAudioStreamFrequencyRatio;
     # extra symbols go here (don't modify this line)
   local: *;
 };

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_GetAudioStreamFrequencyRatio SDL_GetAudioStreamFrequencyRatio_REAL
-#define SDL_SetAudioStreamSpeed SDL_SetAudioStreamSpeed_REAL
+#define SDL_SetAudioStreamFrequencyRatio SDL_SetAudioStreamFrequencyRatio_REAL

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(float,SDL_GetAudioStreamFrequencyRatio,(SDL_AudioStream *a),(a),return)
-SDL_DYNAPI_PROC(int,SDL_SetAudioStreamSpeed,(SDL_AudioStream *a, float b),(a,b),return)
+SDL_DYNAPI_PROC(int,SDL_SetAudioStreamFrequencyRatio,(SDL_AudioStream *a, float b),(a,b),return)

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) {