Merge pull request #1736 from FluidSynth/issue-1726

derselbst · web-flow · commit d8888d9c6f91 · 2026-01-25T17:28:35.000+01:00
Update API docs about possible hazards when changing no-realtime settings
diff --git a/doc/fluidsettings.xml b/doc/fluidsettings.xml
@@ -386,7 +386,7 @@ Developers:
             <min>8000.0</min>
             <max>96000.0</max>
             <desc>
-                The sample rate of the audio generated by the synthesizer. For optimal performance, make sure this value equals the native output rate of the audio driver (in case you are using any of fluidsynth's audio drivers). Some drivers, such as Oboe, will interpolate sample-rates, whereas others, such as Jack, will override this setting, if a mismatch with the native output rate is detected.
+                The sample rate of the audio generated by the synthesizer. For optimal performance, make sure this value equals the native output rate of the audio driver (in case you are using any of fluidsynth's audio drivers). Some drivers, such as Oboe, will interpolate sample-rates, whereas others, such as Jack, will override this setting, if a mismatch with the native output rate is detected. Note, that this is not a realtime setting and changing it requires to re-create the synthesizer and audio driver instance (if any).
             </desc>
         </setting>
         <setting>
diff --git a/include/fluidsynth/audio.h b/include/fluidsynth/audio.h
@@ -32,7 +32,7 @@ extern "C" {
  * The file renderer is used for fast rendering of MIDI files to
  * audio files. The audio drivers are a high-level interface to
  * connect the synthesizer with external audio sinks or to render
- * real-time audio to files.
+ * realtime audio to files.
  */
 
 /**
@@ -131,7 +131,7 @@ FLUIDSYNTH_API int fluid_audio_driver_register(const char **adrivers);
  * as possible. Please see \ref FileRenderer for a full example.
  *
  * If you are looking for a way to write audio generated
- * from real-time events (for example from an external sequencer or a MIDI controller) to a file,
+ * from realtime events (for example from an external sequencer or a MIDI controller) to a file,
  * please have a look at the \c file \ref audio_driver instead.
  *
  *
diff --git a/include/fluidsynth/synth.h b/include/fluidsynth/synth.h
@@ -334,7 +334,7 @@ FLUIDSYNTH_API int fluid_synth_tuning_dump(fluid_synth_t *synth, int bank, int p
  * but can also be used manually for custom processing of the rendered audio.
  *
  * @note Please note that all following functions block during rendering. If your goal is to
- * render real-time audio, ensure that you call these functions from a high-priority
+ * render realtime audio, ensure that you call these functions from a high-priority
  * thread with little to no other duties other than calling the rendering functions.
  *
  * @warning
@@ -344,7 +344,7 @@ FLUIDSYNTH_API int fluid_synth_tuning_dump(fluid_synth_t *synth, int bank, int p
  * synth with every call (cf. fluid_synth_get_internal_bufsize()), it will become evident when requesting larger sample chunks:
  * With larger sample chunks it will get harder for the synth to react on those spontaneously occurring events in time
  * (like events received from a MIDI driver, or directly made synth API calls).
- * In those real-time scenarios, prefer requesting smaller
+ * In those realtime scenarios, prefer requesting smaller
  * sample chunks from the synth with each call, to avoid poor quantization of your events in the synthesized audio.
  * This issue is not applicable when using the MIDI player or sequencer for event dispatching. Also
  * refer to the documentation of \setting{audio_period-size}.
diff --git a/src/bindings/fluid_cmd.c b/src/bindings/fluid_cmd.c
@@ -231,7 +231,7 @@ static const fluid_cmd_t fluid_commands[] =
     /* settings commands */
     {
         "set", "settings", fluid_handle_set,
-        "set name value             Set the value of a setting (must be a real-time setting to take effect immediately)"
+        "set name value             Set the value of a setting (must be a realtime setting to take effect immediately)"
     },
     {
         "get", "settings", fluid_handle_get,
diff --git a/src/drivers/fluid_adriver.c b/src/drivers/fluid_adriver.c
@@ -333,7 +333,9 @@ find_fluid_audio_driver(fluid_settings_t *settings)
  * completed before calling this function.
  * Thus, of all object types in use (synth, midi player, sequencer, etc.) the audio
  * driver should always be the last one to be created and the first one to be deleted!
- * Also refer to the order of object creation in the code examples.
+ * Also refer to the order of object creation in the code examples. Deleting and re-creating
+ * the audio driver is supported. However, only settings marked as realtime can reconfigure
+ * an already created \p synth.
  */
 fluid_audio_driver_t *
 new_fluid_audio_driver(fluid_settings_t *settings, fluid_synth_t *synth)
diff --git a/src/drivers/fluid_aufile.c b/src/drivers/fluid_aufile.c
@@ -19,7 +19,7 @@
 
 /* fluid_aufile.c
  *
- * Audio driver, outputs the audio to a file (non real-time)
+ * Audio driver, outputs the audio to a file (non realtime)
  *
  */
 
diff --git a/src/midi/fluid_midi.h b/src/midi/fluid_midi.h
@@ -62,7 +62,7 @@ enum fluid_midi_event_type
     MIDI_SONG_SELECT = 0xf3,
     MIDI_TUNE_REQUEST = 0xf6,
     MIDI_EOX = 0xf7,
-    /* system real-time - never in midi files */
+    /* system realtime - never in midi files */
     MIDI_SYNC = 0xf8,
     MIDI_TICK = 0xf9,
     MIDI_START = 0xfa,
diff --git a/src/rvoice/fluid_iir_filter_impl.cpp b/src/rvoice/fluid_iir_filter_impl.cpp
@@ -25,7 +25,7 @@
 #include <cmath>
 
 
-// Calculating the sine and cosine coefficients for every possible cutoff frequency is too CPU expensive and can harm real-time playback.
+// Calculating the sine and cosine coefficients for every possible cutoff frequency is too CPU expensive and can harm realtime playback.
 // Therefore, we precalculate the coefficients with a precision of CENTS_STEP and store them in a table.
 extern "C" void fluid_iir_filter_init_table(fluid_iir_sincos_t *sincos_table, fluid_real_t sample_rate)
 {
diff --git a/src/rvoice/fluid_rvoice.h b/src/rvoice/fluid_rvoice.h
@@ -155,7 +155,7 @@ struct _fluid_rvoice_buffers_t
 
 
 /*
- * Hard real-time parameters needed to synthesize a voice
+ * Hard realtime parameters needed to synthesize a voice
  */
 struct _fluid_rvoice_t
 {
diff --git a/src/rvoice/fluid_rvoice_mixer.c b/src/rvoice/fluid_rvoice_mixer.c
@@ -613,7 +613,7 @@ fluid_mixer_buffers_update_polyphony(fluid_mixer_buffers_t *buffers, int value)
 }
 
 /**
- * Update polyphony - max number of voices (NOTE: not hard real-time capable)
+ * Update polyphony - max number of voices (NOTE: not hard realtime capable)
  * @return FLUID_OK or FLUID_FAILED
  */
 DECLARE_FLUID_RVOICE_FUNCTION(fluid_rvoice_mixer_set_polyphony)
@@ -757,7 +757,7 @@ fluid_mixer_buffers_init(fluid_mixer_buffers_t *buffers, fluid_rvoice_mixer_t *m
 }
 
 /**
- * Note: Not hard real-time capable (calls malloc)
+ * Note: Not hard realtime capable (calls malloc)
  */
 DECLARE_FLUID_RVOICE_FUNCTION(fluid_rvoice_mixer_set_samplerate)
 {
@@ -1629,7 +1629,7 @@ static void delete_rvoice_mixer_threads(fluid_rvoice_mixer_t *mixer)
 /**
  * Update amount of extra mixer threads.
  * @param thread_count Number of extra mixer threads for multi-core rendering
- * @param prio_level real-time prio level for the extra mixer threads
+ * @param prio_level realtime prio level for the extra mixer threads
  */
 static int fluid_rvoice_mixer_set_threads(fluid_rvoice_mixer_t *mixer, int thread_count, int prio_level)
 {
diff --git a/src/sfloader/fluid_sfont.c b/src/sfloader/fluid_sfont.c
@@ -325,7 +325,7 @@ fluid_preset_t *fluid_sfont_get_preset(fluid_sfont_t *sfont, int bank, int prenu
  * @param mod_out A reference to a fluid_mod_t array. The provided pointer variable will be populated by fluidsynth to point to an array. The caller is responsible for freeing the array with fluid_free().
  * @return #FLUID_FAILED on error (e.g. out of memory). Otherwise it contains the number of modulators saved into the buffer. The caller must always free the buffer, even if the return value is zero!
  * @since 2.5.0
- * @note This function involves memory allocation and is therefore not real-time safe!
+ * @note This function involves memory allocation and is therefore not realtime safe!
  * @warning This function is not thread-safe. So only call this function when no synthesis thread is concurrently using this @p sfont instance!
  */
 int fluid_sfont_get_default_mod(fluid_sfont_t *sfont, fluid_mod_t **mod_out)
@@ -370,7 +370,7 @@ int fluid_sfont_get_default_mod(fluid_sfont_t *sfont, fluid_mod_t **mod_out)
  * SoundFont will be unset, causing the synth's default modulators to be added to voices again.
  * The behavior is undefined if the array @p mods contains multiple identical modulators
  * (i.e. fluid_mod_test_identity() evaluates to true).
- * Further note that this function involves memory allocation and is therefore not real-time safe!
+ * Further note that this function involves memory allocation and is therefore not realtime safe!
  *
  * @warning This function is not thread-safe. So only call this function when no synthesis thread is concurrently using this @p sfont instance!
  * @since 2.5.0
diff --git a/src/synth/fluid_synth.c b/src/synth/fluid_synth.c
@@ -134,7 +134,7 @@ static void fluid_synth_process_awe32_nrpn_LOCAL(fluid_synth_t *synth, int chan,
 
 static int fluid_parse_portamento_time_str(const char* value);
 
-/* Callback handlers for real-time settings */
+/* Callback handlers for realtime settings */
 static void fluid_synth_handle_gain(void *data, const char *name, double value);
 static void fluid_synth_handle_polyphony(void *data, const char *name, int value);
 static void fluid_synth_handle_device_id(void *data, const char *name, int value);
@@ -660,8 +660,8 @@ static FLUID_INLINE unsigned int fluid_synth_get_min_note_length_LOCAL(fluid_syn
  * @note The @p settings parameter is used directly, but the synth does not take ownership of it.
  * Hence, the caller is responsible for freeing it, when no longer needed.
  * Further note that you may modify FluidSettings of the
- * @p settings instance. However, only those FluidSettings marked as 'realtime' will
- * affect the synth immediately. See the \ref fluidsettings for more details.
+ * @p settings instance. However, only synth settings marked as realtime in \ref fluidsettings will
+ * affect the synth at runtime. fluid_settings_is_realtime() can be used to check this.
  *
  * @warning The @p settings object should only be used by a single synth at a time. I.e. creating
  * multiple synth instances with a single @p settings object causes undefined behavior. Once the
@@ -1116,7 +1116,7 @@ delete_fluid_synth(fluid_synth_t *synth)
 
     fluid_profiling_print();
 
-    /* unregister all real-time settings callback, to avoid a use-after-free when changing those settings after
+    /* unregister all realtime settings callback, to avoid a use-after-free when changing those settings after
      * this synth has been deleted*/
 
     fluid_settings_callback_num(synth->settings, "synth.gain",
@@ -3684,7 +3684,7 @@ fluid_synth_set_sample_rate_LOCAL(fluid_synth_t *synth, float sample_rate)
  * Set up an event to change the sample-rate of the synth during the next rendering call.
  * @warning This function is broken-by-design! Don't use it! Starting with fluidsynth 2.4.4 it's a no-op. Instead, specify the sample-rate when creating the synth.
  * @deprecated As of fluidsynth 2.1.0 this function has been deprecated.
- * Changing the sample-rate is generally not considered to be a real-time use-case, as it always produces some audible artifact ("click", "pop") on the dry sound and effects (because LFOs for chorus and reverb need to be reinitialized).
+ * Changing the sample-rate is generally not considered to be a realtime use-case, as it always produces some audible artifact ("click", "pop") on the dry sound and effects (because LFOs for chorus and reverb need to be reinitialized).
  * The sample-rate change may also require memory allocation deep down in the effect units.
  * However, this memory allocation may fail and there is no way for the caller to know that, because the actual change of the sample-rate is executed during rendering.
  * This function cannot (must not) do the sample-rate change itself, otherwise the synth needs to be locked down, causing rendering to block.
@@ -7747,7 +7747,7 @@ fluid_synth_get_settings(fluid_synth_t *synth)
 /**
  * Apply an offset to a SoundFont generator on a MIDI channel.
  *
- * This function allows to set an offset for the specified destination generator in real-time.
+ * This function allows to set an offset for the specified destination generator in realtime.
  * The offset will be applied immediately to all voices that are currently and subsequently playing
  * on the given MIDI channel. This functionality works equivalent to using NRPN MIDI messages to
  * manipulate synthesis parameters. See SoundFont spec, paragraph 8.1.3, for details on SoundFont
diff --git a/src/synth/fluid_voice.c b/src/synth/fluid_voice.c
@@ -738,7 +738,7 @@ calculate_hold_decay_buffers(fluid_voice_t *voice, int gen_base,
  * fluid_voice_update_param can be called during the setup of the
  * voice (to calculate the initial value for a voice parameter), or
  * during its operation (a generator has been changed due to
- * real-time parameter modifications like pitch-bend).
+ * realtime parameter modifications like pitch-bend).
  *
  * Note: The generator holds three values: The base value .val, an
  * offset caused by modulators .mod, and an offset caused by the
@@ -1566,7 +1566,7 @@ fluid_voice_add_mod_local(fluid_voice_t *voice, fluid_mod_t *mod, int mode, int
  * @return Note on unique ID
  *
  * A SoundFont loader may store pointers to voices it has created for
- * real-time control during the operation of a voice (for example: parameter
+ * realtime control during the operation of a voice (for example: parameter
  * changes in SoundFont editor). The synth uses a pool of voices internally which are
  * 'recycled' and never deallocated.
  *
diff --git a/src/utils/fluid_settings.c b/src/utils/fluid_settings.c
@@ -904,11 +904,11 @@ fluid_settings_get_hints(fluid_settings_t *settings, const char *name, int *hint
 }
 
 /**
- * Ask whether the setting is changeable in real-time.
+ * Ask whether the setting is changeable in realtime.
  *
  * @param settings a settings object
  * @param name a setting's name
- * @return TRUE if the setting is changeable in real-time, FALSE otherwise
+ * @return TRUE if the setting is changeable in realtime, FALSE otherwise
  *
  * @note Before using this function, make sure the @p settings object has already been used to create
  * a synthesizer, a MIDI driver, an audio driver, a MIDI player, or a command handler (depending on

Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@ extern "C" {`
`32`	`32`	`* The file renderer is used for fast rendering of MIDI files to`
`33`	`33`	`* audio files. The audio drivers are a high-level interface to`
`34`	`34`	`* connect the synthesizer with external audio sinks or to render`
`35`		`- * real-time audio to files.`
	`35`	`+ * realtime audio to files.`
`36`	`36`	`*/`
`37`	`37`
`38`	`38`	`/**`
`@@ -131,7 +131,7 @@ FLUIDSYNTH_API int fluid_audio_driver_register(const char **adrivers);`
`131`	`131`	`* as possible. Please see \ref FileRenderer for a full example.`
`132`	`132`	`*`
`133`	`133`	`* If you are looking for a way to write audio generated`
`134`		`- * from real-time events (for example from an external sequencer or a MIDI controller) to a file,`
	`134`	`+ * from realtime events (for example from an external sequencer or a MIDI controller) to a file,`
`135`	`135`	`* please have a look at the \c file \ref audio_driver instead.`
`136`	`136`	`*`
`137`	`137`	`*`
Original file line number	Diff line number	Diff line change
`@@ -231,7 +231,7 @@ static const fluid_cmd_t fluid_commands[] =`
`231`	`231`	`/* settings commands */`
`232`	`232`	`{`
`233`	`233`	`"set", "settings", fluid_handle_set,`
`234`		`- "set name value Set the value of a setting (must be a real-time setting to take effect immediately)"`
	`234`	`+ "set name value Set the value of a setting (must be a realtime setting to take effect immediately)"`
`235`	`235`	`},`
`236`	`236`	`{`
`237`	`237`	`"get", "settings", fluid_handle_get,`
Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@`
`19`	`19`
`20`	`20`	`/* fluid_aufile.c`
`21`	`21`	`*`
`22`		`- * Audio driver, outputs the audio to a file (non real-time)`
	`22`	`+ * Audio driver, outputs the audio to a file (non realtime)`
`23`	`23`	`*`
`24`	`24`	`*/`
`25`	`25`
Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,7 @@`
`25`	`25`	`#include <cmath>`
`26`	`26`
`27`	`27`
`28`		`-// Calculating the sine and cosine coefficients for every possible cutoff frequency is too CPU expensive and can harm real-time playback.`
	`28`	`+// Calculating the sine and cosine coefficients for every possible cutoff frequency is too CPU expensive and can harm realtime playback.`
`29`	`29`	`// Therefore, we precalculate the coefficients with a precision of CENTS_STEP and store them in a table.`
`30`	`30`	`extern "C" void fluid_iir_filter_init_table(fluid_iir_sincos_t *sincos_table, fluid_real_t sample_rate)`
`31`	`31`	`{`
Original file line number	Diff line number	Diff line change
`@@ -155,7 +155,7 @@ struct _fluid_rvoice_buffers_t`
`155`	`155`
`156`	`156`
`157`	`157`	`/*`
`158`		`- * Hard real-time parameters needed to synthesize a voice`
	`158`	`+ * Hard realtime parameters needed to synthesize a voice`
`159`	`159`	`*/`
`160`	`160`	`struct _fluid_rvoice_t`
`161`	`161`	`{`
Original file line number	Diff line number	Diff line change
`@@ -613,7 +613,7 @@ fluid_mixer_buffers_update_polyphony(fluid_mixer_buffers_t *buffers, int value)`
`613`	`613`	`}`
`614`	`614`
`615`	`615`	`/**`
`616`		`- * Update polyphony - max number of voices (NOTE: not hard real-time capable)`
	`616`	`+ * Update polyphony - max number of voices (NOTE: not hard realtime capable)`
`617`	`617`	`* @return FLUID_OK or FLUID_FAILED`
`618`	`618`	`*/`
`619`	`619`	`DECLARE_FLUID_RVOICE_FUNCTION(fluid_rvoice_mixer_set_polyphony)`
`@@ -757,7 +757,7 @@ fluid_mixer_buffers_init(fluid_mixer_buffers_t buffers, fluid_rvoice_mixer_t m`
`757`	`757`	`}`
`758`	`758`
`759`	`759`	`/**`
`760`		`- * Note: Not hard real-time capable (calls malloc)`
	`760`	`+ * Note: Not hard realtime capable (calls malloc)`
`761`	`761`	`*/`
`762`	`762`	`DECLARE_FLUID_RVOICE_FUNCTION(fluid_rvoice_mixer_set_samplerate)`
`763`	`763`	`{`
`@@ -1629,7 +1629,7 @@ static void delete_rvoice_mixer_threads(fluid_rvoice_mixer_t *mixer)`
`1629`	`1629`	`/**`
`1630`	`1630`	`* Update amount of extra mixer threads.`
`1631`	`1631`	`* @param thread_count Number of extra mixer threads for multi-core rendering`
`1632`		`- * @param prio_level real-time prio level for the extra mixer threads`
	`1632`	`+ * @param prio_level realtime prio level for the extra mixer threads`
`1633`	`1633`	`*/`
`1634`	`1634`	`static int fluid_rvoice_mixer_set_threads(fluid_rvoice_mixer_t *mixer, int thread_count, int prio_level)`
`1635`	`1635`	`{`