Parse standard MIDI files and emit MIDI events. More...

Enumerations
enum	fluid_player_set_tempo_type { FLUID_PLAYER_TEMPO_INTERNAL , FLUID_PLAYER_TEMPO_EXTERNAL_BPM , FLUID_PLAYER_TEMPO_EXTERNAL_MIDI , FLUID_PLAYER_TEMPO_NBR }
	MIDI File Player tempo enum. More...

enum	fluid_player_status { FLUID_PLAYER_READY , FLUID_PLAYER_PLAYING , FLUID_PLAYER_STOPPING , FLUID_PLAYER_DONE }
	MIDI File Player status enum. More...

Lifecycle Functions for MIDI File Player_linebr@{
fluid_player_t *	new_fluid_player (fluid_synth_t *synth)
	Create a new MIDI player. More...

void	delete_fluid_player (fluid_player_t *player)
	Delete a MIDI player instance. More...

Functions
int	fluid_player_add (fluid_player_t player, const char midifile)
	Add a MIDI file to a player queue. More...

int	fluid_player_add_mem (fluid_player_t player, const void buffer, size_t len)
	Add a MIDI file to a player queue, from a buffer in memory. More...

int	fluid_player_get_bpm (fluid_player_t *player)
	Get the tempo currently used by a MIDI player. More...

int	fluid_player_get_current_tick (fluid_player_t *player)
	Get the number of tempo ticks passed. More...

int	fluid_player_get_division (fluid_player_t *player)
	Get the division currently used by a MIDI player. More...

int	fluid_player_get_midi_tempo (fluid_player_t *player)
	Get the tempo currently used by a MIDI player. More...

int	fluid_player_get_status (fluid_player_t *player)
	Get MIDI player status. More...

int	fluid_player_get_total_ticks (fluid_player_t *player)
	Looks through all available MIDI tracks and gets the absolute tick of the very last event to play. More...

int	fluid_player_join (fluid_player_t *player)
	Wait for a MIDI player until the playback has been stopped. More...

int	fluid_player_play (fluid_player_t *player)
	Activates play mode for a MIDI player if not already playing. More...

int	fluid_player_seek (fluid_player_t *player, int ticks)
	Seek in the currently playing file. More...

int	fluid_player_set_bpm (fluid_player_t *player, int bpm)
	Set the tempo of a MIDI player in beats per minute. More...

int	fluid_player_set_loop (fluid_player_t *player, int loop)
	Enable looping of a MIDI player. More...

int	fluid_player_set_midi_tempo (fluid_player_t *player, int tempo)
	Set the tempo of a MIDI player. More...

int	fluid_player_set_playback_callback (fluid_player_t player, handle_midi_event_func_t handler, void handler_data)
	Change the MIDI callback function. More...

int	fluid_player_set_tempo (fluid_player_t *player, int tempo_type, double tempo)
	Set the tempo of a MIDI player. More...

int	fluid_player_set_tick_callback (fluid_player_t player, handle_midi_tick_func_t handler, void handler_data)
	Add a listener function for every MIDI tick change. More...

int	fluid_player_stop (fluid_player_t *player)
	Pauses the MIDI playback. More...

Detailed Description

Parse standard MIDI files and emit MIDI events.

Enumeration Type Documentation

◆ fluid_player_set_tempo_type

enum fluid_player_set_tempo_type

MIDI File Player tempo enum.

Since: 2.2.0

Enumerator

FLUID_PLAYER_TEMPO_INTERNAL

Use midi file tempo set in midi file (120 bpm by default).

Multiplied by a factor

FLUID_PLAYER_TEMPO_EXTERNAL_BPM

Set player tempo in bpm, supersede midi file tempo.

FLUID_PLAYER_TEMPO_EXTERNAL_MIDI

Set player tempo in us per quarter note, supersede midi file tempo.

◆ fluid_player_status

enum fluid_player_status

MIDI File Player status enum.

Since: 1.1.0

Enumerator
FLUID_PLAYER_READY	Player is ready.
FLUID_PLAYER_PLAYING	Player is currently playing.
FLUID_PLAYER_STOPPING	Player is stopping, but hasn't finished yet (currently unused)
FLUID_PLAYER_DONE	Player is finished playing.

Function Documentation

◆ delete_fluid_player()

void delete_fluid_player ( fluid_player_t * player )

Delete a MIDI player instance.

Parameters

player MIDI player instance

Warning: Do not call when the synthesizer associated to this player renders audio, i.e. an audio driver is running or any other synthesizer thread concurrently calls fluid_synth_process() or fluid_synth_nwrite_float() or fluid_synth_write_*() !

◆ fluid_player_add()

int fluid_player_add	(	fluid_player_t *	player,
		const char *	midifile
	)

Add a MIDI file to a player queue.

Parameters

player	MIDI player instance
midifile	File name of the MIDI file to add

Returns: FLUID_OK or FLUID_FAILED

◆ fluid_player_add_mem()

int fluid_player_add_mem	(	fluid_player_t *	player,
		const void *	buffer,
		size_t	len
	)

Add a MIDI file to a player queue, from a buffer in memory.

Parameters

player	MIDI player instance
buffer	Pointer to memory containing the bytes of a complete MIDI file. The data is copied, so the caller may free or modify it immediately without affecting the playlist.
len	Length of the buffer, in bytes.

Returns: FLUID_OK or FLUID_FAILED

◆ fluid_player_get_bpm()

int fluid_player_get_bpm ( fluid_player_t * player )

Get the tempo currently used by a MIDI player.

The player can be controlled by internal tempo coming from MIDI file tempo change or controlled by external tempo see fluid_player_set_tempo().

Parameters

player MIDI player instance. Must be a valid pointer.

Returns: MIDI player tempo in BPM or FLUID_FAILED if error.

Since: 1.1.7

◆ fluid_player_get_current_tick()

int fluid_player_get_current_tick ( fluid_player_t * player )

Get the number of tempo ticks passed.

Parameters

player MIDI player instance

Returns: The number of tempo ticks passed

Since: 1.1.7

◆ fluid_player_get_division()

int fluid_player_get_division ( fluid_player_t * player )

Get the division currently used by a MIDI player.

The player can be controlled by internal tempo coming from MIDI file tempo change or controlled by external tempo see fluid_player_set_tempo().

Parameters

player MIDI player instance. Must be a valid pointer.

Returns: MIDI player division or FLUID_FAILED if error.

Since: 2.3.2

◆ fluid_player_get_midi_tempo()

int fluid_player_get_midi_tempo ( fluid_player_t * player )

Get the tempo currently used by a MIDI player.

The player can be controlled by internal tempo coming from MIDI file tempo change or controlled by external tempo see fluid_player_set_tempo().

Parameters

player MIDI player instance. Must be a valid pointer.

Returns: Tempo of the MIDI player (in microseconds per quarter note, as per MIDI file spec) or FLUID_FAILED if error.

Since: 1.1.7

◆ fluid_player_get_status()

int fluid_player_get_status ( fluid_player_t * player )

Get MIDI player status.

Parameters

player MIDI player instance

Returns: Player status (fluid_player_status)

Since: 1.1.0

◆ fluid_player_get_total_ticks()

int fluid_player_get_total_ticks ( fluid_player_t * player )

Looks through all available MIDI tracks and gets the absolute tick of the very last event to play.

Parameters

player MIDI player instance

Returns: Total tick count of the sequence

Since: 1.1.7

◆ fluid_player_join()

int fluid_player_join ( fluid_player_t * player )

Wait for a MIDI player until the playback has been stopped.

Parameters

player MIDI player instance

Returns: Always FLUID_OK

Warning: The player may still be used by a concurrently running synth context. Hence it is not safe to immediately delete the player afterwards. Also refer to delete_fluid_player().

◆ fluid_player_play()

int fluid_player_play ( fluid_player_t * player )

Activates play mode for a MIDI player if not already playing.

Parameters

player MIDI player instance

Returns: FLUID_OK on success, FLUID_FAILED otherwise

If the list of files added to the player has completed its requested number of loops, the playlist will be restarted from the beginning with a loop count of 1.

◆ fluid_player_seek()

int fluid_player_seek	(	fluid_player_t *	player,
		int	ticks
	)

Seek in the currently playing file.

Parameters

player	MIDI player instance
ticks	the position to seek to in the current file

Returns: FLUID_FAILED if ticks is negative or after the latest tick of the file [or, since 2.1.3, if another seek operation is currently in progress], FLUID_OK otherwise.

The actual seek will be performed when the synth calls back the player (i.e. a few levels above the player's callback set with fluid_player_set_playback_callback()). If the player's status is FLUID_PLAYER_PLAYING and a previous seek operation has not been completed yet, FLUID_FAILED is returned.

Since: 2.0.0

◆ fluid_player_set_bpm()

int fluid_player_set_bpm	(	fluid_player_t *	player,
		int	bpm
	)

Set the tempo of a MIDI player in beats per minute.

Parameters

player	MIDI player instance
bpm	Tempo in beats per minute

Returns: Always returns FLUID_OK

Note: Tempo change events contained in the MIDI file can override the specified BPM at any time!

Deprecated:: Use fluid_player_set_tempo() instead.

◆ fluid_player_set_loop()

int fluid_player_set_loop	(	fluid_player_t *	player,
		int	loop
	)

Enable looping of a MIDI player.

Parameters

player	MIDI player instance
loop	Times left to loop the playlist. -1 means loop infinitely.

Returns: Always returns FLUID_OK

For example, if you want to loop the playlist twice, set loop to 2 and call this function before you start the player.

Since: 1.1.0

◆ fluid_player_set_midi_tempo()

int fluid_player_set_midi_tempo	(	fluid_player_t *	player,
		int	tempo
	)

Set the tempo of a MIDI player.

Parameters

player	MIDI player instance
tempo	Tempo to set playback speed to (in microseconds per quarter note, as per MIDI file spec)

Returns: Always returns FLUID_OK

Note: Tempo change events contained in the MIDI file can override the specified tempo at any time!

Deprecated:: Use fluid_player_set_tempo() instead.

◆ fluid_player_set_playback_callback()

int fluid_player_set_playback_callback	(	fluid_player_t *	player,
		handle_midi_event_func_t	handler,
		void *	handler_data
	)

Change the MIDI callback function.

Parameters

player	MIDI player instance
handler	Pointer to callback function
handler_data	Parameter sent to the callback function

Returns: FLUID_OK

This is usually set to fluid_synth_handle_midi_event(), but can optionally be changed to a user-defined function instead, for intercepting all MIDI messages sent to the synth. You can also use a midi router as the callback function to modify the MIDI messages before sending them to the synth.

Since: 1.1.4

◆ fluid_player_set_tempo()

int fluid_player_set_tempo	(	fluid_player_t *	player,
		int	tempo_type,
		double	tempo
	)

Set the tempo of a MIDI player.

The player can be controlled by internal tempo coming from MIDI file tempo change or controlled by external tempo expressed in BPM or in micro seconds per quarter note.

Parameters

player	MIDI player instance. Must be a valid pointer.
tempo_type	Must a be value of fluid_player_set_tempo_type and indicates the meaning of tempo value and how the player will be controlled, see below.
tempo	Tempo value or multiplier.

FLUID_PLAYER_TEMPO_INTERNAL, the player will be controlled by internal MIDI file tempo changes. If there are no tempo change in the MIDI file a default value of 120 bpm is used. The tempo parameter is used as a multiplier factor that must be in the range (0.001 to 1000). For example, if the current MIDI file tempo is 120 bpm and the multiplier value is 0.5 then this tempo will be slowed down to 60 bpm. At creation, the player is set to be controlled by internal tempo with a multiplier factor set to 1.0.

FLUID_PLAYER_TEMPO_EXTERNAL_BPM, the player will be controlled by the external tempo value provided by the tempo parameter in bpm (i.e in quarter notes per minute) which must be in the range (1 to 60000000).

FLUID_PLAYER_TEMPO_EXTERNAL_MIDI, similar as FLUID_PLAYER_TEMPO_EXTERNAL_BPM, but the tempo parameter value is in micro seconds per quarter note which must be in the range (1 to 60000000). Using micro seconds per quarter note is convenient when the tempo value is derived from MIDI clock realtime messages.

Note: When the player is controlled by an external tempo (FLUID_PLAYER_TEMPO_EXTERNAL_BPM or FLUID_PLAYER_TEMPO_EXTERNAL_MIDI) it continues to memorize the most recent internal tempo change coming from the MIDI file so that next call to fluid_player_set_tempo() with FLUID_PLAYER_TEMPO_INTERNAL will set the player to follow this internal tempo.

Warning: If the function is called when no MIDI file is loaded or currently playing, it would have caused a division by zero in fluidsynth 2.2.7 and earlier. Starting with 2.2.8, the new tempo change will be stashed and applied later.

Returns: FLUID_OK if success or FLUID_FAILED otherwise (incorrect parameters).

Since: 2.2.0

◆ fluid_player_set_tick_callback()

int fluid_player_set_tick_callback	(	fluid_player_t *	player,
		handle_midi_tick_func_t	handler,
		void *	handler_data
	)

Add a listener function for every MIDI tick change.

Parameters

player	MIDI player instance
handler	Pointer to callback function
handler_data	Opaque parameter to be sent to the callback function

Returns: FLUID_OK

This callback is not set by default, but can optionally be changed to a user-defined function for intercepting all MIDI tick changes and react to them with precision.

Since: 2.2.0

◆ fluid_player_stop()

int fluid_player_stop ( fluid_player_t * player )

Pauses the MIDI playback.

Parameters

player MIDI player instance

Returns: Always returns FLUID_OK

It will not rewind to the beginning of the file, use fluid_player_seek() for this purpose.

◆ new_fluid_player()

fluid_player_t* new_fluid_player ( fluid_synth_t * synth )

Create a new MIDI player.

Parameters

synth Fluid synthesizer instance to create player for

Returns: New MIDI player instance or NULL on error (out of memory)

Enumerations

Lifecycle Functions for MIDI File Player_linebr@{

Functions

Detailed Description

Enumeration Type Documentation

◆ fluid_player_set_tempo_type

◆ fluid_player_status

Function Documentation

◆ delete_fluid_player()

◆ fluid_player_add()

◆ fluid_player_add_mem()

◆ fluid_player_get_bpm()

◆ fluid_player_get_current_tick()

◆ fluid_player_get_division()

◆ fluid_player_get_midi_tempo()

◆ fluid_player_get_status()

◆ fluid_player_get_total_ticks()

◆ fluid_player_join()

◆ fluid_player_play()

◆ fluid_player_seek()

◆ fluid_player_set_bpm()

◆ fluid_player_set_loop()

◆ fluid_player_set_midi_tempo()

◆ fluid_player_set_playback_callback()

◆ fluid_player_set_tempo()

◆ fluid_player_set_tick_callback()

◆ fluid_player_stop()

◆ new_fluid_player()