libfluidsynth  2.2.4
MIDI Channel Messages

The MIDI channel message functions are mostly directly named after their counterpart MIDI messages. More...

Functions

int fluid_synth_all_notes_off (fluid_synth_t *synth, int chan)
 Turn off all voices that are playing on the given MIDI channel, by putting them into release phase. More...
 
int fluid_synth_all_sounds_off (fluid_synth_t *synth, int chan)
 Immediately stop all voices on the given MIDI channel (skips release phase). More...
 
int fluid_synth_bank_select (fluid_synth_t *synth, int chan, int bank)
 Set instrument bank number on a MIDI channel. More...
 
int fluid_synth_cc (fluid_synth_t *synth, int chan, int ctrl, int val)
 Send a MIDI controller event on a MIDI channel. More...
 
int fluid_synth_channel_pressure (fluid_synth_t *synth, int chan, int val)
 Set the MIDI channel pressure controller value. More...
 
int fluid_synth_get_cc (fluid_synth_t *synth, int chan, int ctrl, int *pval)
 Get current MIDI controller value on a MIDI channel. More...
 
float fluid_synth_get_gen (fluid_synth_t *synth, int chan, int param)
 Retrieve the generator NRPN offset assigned to a MIDI channel. More...
 
int fluid_synth_get_pitch_bend (fluid_synth_t *synth, int chan, int *ppitch_bend)
 Get the MIDI pitch bend controller value on a MIDI channel. More...
 
int fluid_synth_get_pitch_wheel_sens (fluid_synth_t *synth, int chan, int *pval)
 Get MIDI pitch wheel sensitivity on a MIDI channel. More...
 
int fluid_synth_get_program (fluid_synth_t *synth, int chan, int *sfont_id, int *bank_num, int *preset_num)
 Get current SoundFont ID, bank number and program number for a MIDI channel. More...
 
int fluid_synth_key_pressure (fluid_synth_t *synth, int chan, int key, int val)
 Set the MIDI polyphonic key pressure controller value. More...
 
int fluid_synth_noteoff (fluid_synth_t *synth, int chan, int key)
 Sends a note-off event to a FluidSynth object. More...
 
int fluid_synth_noteon (fluid_synth_t *synth, int chan, int key, int vel)
 Send a note-on event to a FluidSynth object. More...
 
int fluid_synth_pitch_bend (fluid_synth_t *synth, int chan, int val)
 Set the MIDI pitch bend controller value on a MIDI channel. More...
 
int fluid_synth_pitch_wheel_sens (fluid_synth_t *synth, int chan, int val)
 Set MIDI pitch wheel sensitivity on a MIDI channel. More...
 
int fluid_synth_program_change (fluid_synth_t *synth, int chan, int program)
 Send a program change event on a MIDI channel. More...
 
int fluid_synth_program_reset (fluid_synth_t *synth)
 Resend a bank select and a program change for every channel and assign corresponding instruments. More...
 
int fluid_synth_program_select (fluid_synth_t *synth, int chan, int sfont_id, int bank_num, int preset_num)
 Select an instrument on a MIDI channel by SoundFont ID, bank and program numbers. More...
 
int fluid_synth_program_select_by_sfont_name (fluid_synth_t *synth, int chan, const char *sfont_name, int bank_num, int preset_num)
 Select an instrument on a MIDI channel by SoundFont name, bank and program numbers. More...
 
int fluid_synth_set_gen (fluid_synth_t *synth, int chan, int param, float value)
 Apply an offset to a SoundFont generator on a MIDI channel. More...
 
int fluid_synth_sfont_select (fluid_synth_t *synth, int chan, int sfont_id)
 Set SoundFont ID on a MIDI channel. More...
 
int fluid_synth_sysex (fluid_synth_t *synth, const char *data, int len, char *response, int *response_len, int *handled, int dryrun)
 Process a MIDI SYSEX (system exclusive) message. More...
 
int fluid_synth_system_reset (fluid_synth_t *synth)
 Send MIDI system reset command (big red 'panic' button), turns off notes, resets controllers and restores initial basic channel configuration. More...
 
int fluid_synth_unset_program (fluid_synth_t *synth, int chan)
 Set the preset of a MIDI channel to an unassigned state. More...
 

Detailed Description

The MIDI channel message functions are mostly directly named after their counterpart MIDI messages.

They are a high-level interface to controlling the synthesizer, playing notes and changing note and channel parameters.

Function Documentation

◆ fluid_synth_all_notes_off()

int fluid_synth_all_notes_off ( fluid_synth_t synth,
int  chan 
)

Turn off all voices that are playing on the given MIDI channel, by putting them into release phase.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1), (chan=-1 selects all channels)
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Since
1.1.4

◆ fluid_synth_all_sounds_off()

int fluid_synth_all_sounds_off ( fluid_synth_t synth,
int  chan 
)

Immediately stop all voices on the given MIDI channel (skips release phase).

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1), (chan=-1 selects all channels)
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Since
1.1.4

◆ fluid_synth_bank_select()

int fluid_synth_bank_select ( fluid_synth_t synth,
int  chan,
int  bank 
)

Set instrument bank number on a MIDI channel.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
bankMIDI bank number
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Note
This function does not change the instrument currently assigned to chan, as it is usually called prior to fluid_synth_program_change(). If you still want instrument changes to take effect immediately, call fluid_synth_program_reset() after having set up the bank configuration.

◆ fluid_synth_cc()

int fluid_synth_cc ( fluid_synth_t synth,
int  chan,
int  num,
int  val 
)

Send a MIDI controller event on a MIDI channel.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
numMIDI controller number (0-127)
valMIDI controller value (0-127)
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Note
This function supports MIDI Global Controllers which will be sent to all channels of the basic channel if this basic channel is in mode OmniOff/Mono. This is accomplished by sending the CC one MIDI channel below the basic channel of the receiver. Examples: let a synthesizer with 16 MIDI channels:
  • Let a basic channel 7 in mode 3 (Omni Off, Mono). If MIDI channel 6 is disabled it could be used as CC global for all channels belonging to basic channel 7.
  • Let a basic channel 0 in mode 3. If MIDI channel 15 is disabled it could be used as CC global for all channels belonging to basic channel 0.

◆ fluid_synth_channel_pressure()

int fluid_synth_channel_pressure ( fluid_synth_t synth,
int  chan,
int  val 
)

Set the MIDI channel pressure controller value.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
valMIDI channel pressure value (0-127)
Returns
FLUID_OK on success, FLUID_FAILED otherwise

◆ fluid_synth_get_cc()

int fluid_synth_get_cc ( fluid_synth_t synth,
int  chan,
int  num,
int *  pval 
)

Get current MIDI controller value on a MIDI channel.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
numMIDI controller number (0-127)
pvalLocation to store MIDI controller value (0-127)
Returns
FLUID_OK on success, FLUID_FAILED otherwise

◆ fluid_synth_get_gen()

float fluid_synth_get_gen ( fluid_synth_t synth,
int  chan,
int  param 
)

Retrieve the generator NRPN offset assigned to a MIDI channel.

The value returned is in native units of the generator. By default, the offset is zero.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
paramSoundFont generator ID (fluid_gen_type)
Returns
Current NRPN generator offset value assigned to the MIDI channel

◆ fluid_synth_get_pitch_bend()

int fluid_synth_get_pitch_bend ( fluid_synth_t synth,
int  chan,
int *  ppitch_bend 
)

Get the MIDI pitch bend controller value on a MIDI channel.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
ppitch_bendLocation to store MIDI pitch bend value (0-16383 with 8192 being center)
Returns
FLUID_OK on success, FLUID_FAILED otherwise

◆ fluid_synth_get_pitch_wheel_sens()

int fluid_synth_get_pitch_wheel_sens ( fluid_synth_t synth,
int  chan,
int *  pval 
)

Get MIDI pitch wheel sensitivity on a MIDI channel.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
pvalLocation to store pitch wheel sensitivity value in semitones
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Since
Sometime AFTER v1.0 API freeze.

◆ fluid_synth_get_program()

int fluid_synth_get_program ( fluid_synth_t synth,
int  chan,
int *  sfont_id,
int *  bank_num,
int *  preset_num 
)

Get current SoundFont ID, bank number and program number for a MIDI channel.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
sfont_idLocation to store SoundFont ID
bank_numLocation to store MIDI bank number
preset_numLocation to store MIDI program number
Returns
FLUID_OK on success, FLUID_FAILED otherwise

◆ fluid_synth_key_pressure()

int fluid_synth_key_pressure ( fluid_synth_t synth,
int  chan,
int  key,
int  val 
)

Set the MIDI polyphonic key pressure controller value.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
keyMIDI key number (0-127)
valMIDI key pressure value (0-127)
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Since
2.0.0

◆ fluid_synth_noteoff()

int fluid_synth_noteoff ( fluid_synth_t synth,
int  chan,
int  key 
)

Sends a note-off event to a FluidSynth object.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
keyMIDI note number (0-127)
Returns
FLUID_OK on success, FLUID_FAILED otherwise (may just mean that no voices matched the note off event)
Examples:
example.c.

◆ fluid_synth_noteon()

int fluid_synth_noteon ( fluid_synth_t synth,
int  chan,
int  key,
int  vel 
)

Send a note-on event to a FluidSynth object.

This function will take care of proper legato playing. If a note on channel chan is already playing at the given key key, it will be released (even if it is sustained). In other words, overlapping notes are not allowed.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
keyMIDI note number (0-127)
velMIDI velocity (0-127, 0=noteoff)
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Examples:
example.c, fluidsynth_fx.c, and fluidsynth_simple.c.

◆ fluid_synth_pitch_bend()

int fluid_synth_pitch_bend ( fluid_synth_t synth,
int  chan,
int  val 
)

Set the MIDI pitch bend controller value on a MIDI channel.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
valMIDI pitch bend value (0-16383 with 8192 being center)
Returns
FLUID_OK on success, FLUID_FAILED otherwise

◆ fluid_synth_pitch_wheel_sens()

int fluid_synth_pitch_wheel_sens ( fluid_synth_t synth,
int  chan,
int  val 
)

Set MIDI pitch wheel sensitivity on a MIDI channel.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
valPitch wheel sensitivity value in semitones
Returns
FLUID_OK on success, FLUID_FAILED otherwise

◆ fluid_synth_program_change()

int fluid_synth_program_change ( fluid_synth_t synth,
int  chan,
int  prognum 
)

Send a program change event on a MIDI channel.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
prognumMIDI program number (0-127)
Returns
FLUID_OK on success, FLUID_FAILED otherwise

◆ fluid_synth_program_reset()

int fluid_synth_program_reset ( fluid_synth_t synth)

Resend a bank select and a program change for every channel and assign corresponding instruments.

Parameters
synthFluidSynth instance
Returns
FLUID_OK on success, FLUID_FAILED otherwise

This function is called mainly after a SoundFont has been loaded, unloaded or reloaded.

◆ fluid_synth_program_select()

int fluid_synth_program_select ( fluid_synth_t synth,
int  chan,
int  sfont_id,
int  bank_num,
int  preset_num 
)

Select an instrument on a MIDI channel by SoundFont ID, bank and program numbers.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
sfont_idID of a loaded SoundFont
bank_numMIDI bank number
preset_numMIDI program number
Returns
FLUID_OK on success, FLUID_FAILED otherwise

◆ fluid_synth_program_select_by_sfont_name()

int fluid_synth_program_select_by_sfont_name ( fluid_synth_t synth,
int  chan,
const char *  sfont_name,
int  bank_num,
int  preset_num 
)

Select an instrument on a MIDI channel by SoundFont name, bank and program numbers.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
sfont_nameName of a loaded SoundFont
bank_numMIDI bank number
preset_numMIDI program number
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Since
1.1.0

◆ fluid_synth_set_gen()

int fluid_synth_set_gen ( fluid_synth_t synth,
int  chan,
int  param,
float  value 
)

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. 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 generator parameters and valid ranges, as well as paragraph 9.6 for details on NRPN messages.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
paramSoundFont generator ID (fluid_gen_type)
valueOffset value (in native units of the generator) to assign to the MIDI channel
Returns
FLUID_OK on success, FLUID_FAILED otherwise

◆ fluid_synth_sfont_select()

int fluid_synth_sfont_select ( fluid_synth_t synth,
int  chan,
int  sfont_id 
)

Set SoundFont ID on a MIDI channel.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
sfont_idID of a loaded SoundFont
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Note
This function does not change the instrument currently assigned to chan, as it is usually called prior to fluid_synth_bank_select() or fluid_synth_program_change(). If you still want instrument changes to take effect immediately, call fluid_synth_program_reset() after having selected the soundfont.

◆ fluid_synth_sysex()

int fluid_synth_sysex ( fluid_synth_t synth,
const char *  data,
int  len,
char *  response,
int *  response_len,
int *  handled,
int  dryrun 
)

Process a MIDI SYSEX (system exclusive) message.

Parameters
synthFluidSynth instance
dataBuffer containing SYSEX data (not including 0xF0 and 0xF7)
lenLength of data in buffer
responseBuffer to store response to or NULL to ignore
response_lenIN/OUT parameter, in: size of response buffer, out: amount of data written to response buffer (if FLUID_FAILED is returned and this value is non-zero, it indicates the response buffer is too small)
handledOptional location to store boolean value if message was recognized and handled or not (set to TRUE if it was handled)
dryrunTRUE to just do a dry run but not actually execute the SYSEX command (useful for checking if a SYSEX message would be handled)
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Since
1.1.0

◆ fluid_synth_system_reset()

int fluid_synth_system_reset ( fluid_synth_t synth)

Send MIDI system reset command (big red 'panic' button), turns off notes, resets controllers and restores initial basic channel configuration.

Parameters
synthFluidSynth instance
Returns
FLUID_OK on success, FLUID_FAILED otherwise

◆ fluid_synth_unset_program()

int fluid_synth_unset_program ( fluid_synth_t synth,
int  chan 
)

Set the preset of a MIDI channel to an unassigned state.

Parameters
synthFluidSynth instance
chanMIDI channel number (0 to MIDI channel count - 1)
Returns
FLUID_OK on success, FLUID_FAILED otherwise
Since
1.1.1
Note
Channel retains its SoundFont ID and bank numbers, while the program number is set to an "unset" state. MIDI program changes may re-assign a preset if one matches.