# include/fluidsynth/midi.h File Reference

Go to the source code of this file.

## Typedefs

typedef int(* | handle_midi_event_func_t )(void *data, fluid_midi_event_t *event)
| Generic callback function for MIDI events.

## Functions

FLUIDSYNTH_API fluid_midi_event_t * | new_fluid_midi_event (void)
| Create a MIDI event structure.
FLUIDSYNTH_API int | delete_fluid_midi_event (fluid_midi_event_t *event)
| Delete MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_set_type (fluid_midi_event_t *evt, int type)
| Set the event type field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_get_type (fluid_midi_event_t *evt)
| Get the event type field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_set_channel (fluid_midi_event_t *evt, int chan)
| Set the channel field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_get_channel (fluid_midi_event_t *evt)
| Get the channel field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_get_key (fluid_midi_event_t *evt)
| Get the key field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_set_key (fluid_midi_event_t *evt, int key)
| Set the key field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_get_velocity (fluid_midi_event_t *evt)
| Get the velocity field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_set_velocity (fluid_midi_event_t *evt, int vel)
| Set the velocity field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_get_control (fluid_midi_event_t *evt)
| Get the control number of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_set_control (fluid_midi_event_t *evt, int ctrl)
| Set the control field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_get_value (fluid_midi_event_t *evt)
| Get the value field from a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_set_value (fluid_midi_event_t *evt, int val)
| Set the value field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_get_program (fluid_midi_event_t *evt)
| Get the program field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_set_program (fluid_midi_event_t *evt, int val)
| Set the program field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_get_pitch (fluid_midi_event_t *evt)
| Get the pitch field of a MIDI event structure.
FLUIDSYNTH_API int | fluid_midi_event_set_pitch (fluid_midi_event_t *evt, int val)
| Set the pitch field of a MIDI event structure.
FLUIDSYNTH_API fluid_midi_router_t * | new_fluid_midi_router (fluid_settings_t *settings, handle_midi_event_func_t handler, void *event_handler_data)
| Create a new midi router.
FLUIDSYNTH_API int | delete_fluid_midi_router (fluid_midi_router_t *handler)
| Delete a MIDI router instance.
FLUIDSYNTH_API int | fluid_midi_router_handle_midi_event (void *data, fluid_midi_event_t *event)
| Handle a MIDI event through a MIDI router instance.
FLUIDSYNTH_API int | fluid_midi_dump_prerouter (void *data, fluid_midi_event_t *event)
| MIDI event callback function to display event information to stdout.
FLUIDSYNTH_API int | fluid_midi_dump_postrouter (void *data, fluid_midi_event_t *event)
| MIDI event callback function to display event information to stdout.
FLUIDSYNTH_API fluid_midi_driver_t * | new_fluid_midi_driver (fluid_settings_t *settings, handle_midi_event_func_t handler, void *event_handler_data)
| Create a new MIDI driver instance.
FLUIDSYNTH_API void | delete_fluid_midi_driver (fluid_midi_driver_t *driver)
| Delete a MIDI driver instance.
FLUIDSYNTH_API fluid_player_t * | new_fluid_player (fluid_synth_t *synth)
| Create a new MIDI player.
FLUIDSYNTH_API int | delete_fluid_player (fluid_player_t *player)
| Delete a MIDI player instance.
FLUIDSYNTH_API int | fluid_player_add (fluid_player_t *player, char *midifile)
FLUIDSYNTH_API int | fluid_player_play (fluid_player_t *player)
| Activates play mode for a MIDI player if not already playing.
FLUIDSYNTH_API int | fluid_player_stop (fluid_player_t *player)
| Stops a MIDI player.
FLUIDSYNTH_API int | fluid_player_join (fluid_player_t *player)
| Wait for a MIDI player to terminate (when done playing).
FLUIDSYNTH_API int | fluid_player_set_loop (fluid_player_t *player, int loop)
| Enable looping of a MIDI player (DOCME - Does this actually work?).
FLUIDSYNTH_API int | fluid_player_set_midi_tempo (fluid_player_t *player, int tempo)
| Set the tempo of a MIDI player.
FLUIDSYNTH_API int | fluid_player_set_bpm (fluid_player_t *player, int bpm)
| Set the tempo of a MIDI player in beats per minute.

## Detailed Description

Functions for MIDI events, drivers and MIDI file playback.

Definition in file midi.h.

## Typedef Documentation

typedef int(* handle_midi_event_func_t)(void *data, fluid_midi_event_t *event)

Generic callback function for MIDI events.

Parameters:

  | data | User defined data pointer
  | event | The MIDI event

Returns:
  DOCME

Will be used between

- MIDI driver and MIDI router
- MIDI router and synth to communicate events. In the not-so-far future...

Definition at line 66 of file midi.h.

## Function Documentation

FLUIDSYNTH_API fluid_midi_event_t* new_fluid_midi_event | ( | void |  | ) |

Create a MIDI event structure.

Returns:
  New MIDI event structure or NULL when out of memory.

Definition at line 673 of file fluid_midi.c.

References FLUID_ERR, and new_fluid_midi_event().

Referenced by new_fluid_midi_event().

FLUIDSYNTH_API int delete_fluid_midi_event | ( | fluid_midi_event_t * | evt | ) |

Delete MIDI event structure.

Parameters:

  | evt | MIDI event structure

Returns:
  Always returns 0

Definition at line 695 of file fluid_midi.c.

References delete_fluid_midi_event().

Referenced by delete_fluid_midi_event().

FLUIDSYNTH_API int fluid_midi_event_set_type | ( | fluid_midi_event_t * | evt,
|  | int | type |
| ) |  |  |

Set the event type field of a MIDI event structure.

DOCME - Event type enum appears to be internal (fluid_midi.h)

Parameters:

  | evt | MIDI event structure
  | type | Event type field

Returns:
  Always returns 0

Definition at line 726 of file fluid_midi.c.

References fluid_midi_event_set_type().

Referenced by fluid_midi_event_set_type(), and fluid_midi_router_handle_midi_event().

FLUIDSYNTH_API int fluid_midi_event_get_type | ( | fluid_midi_event_t * | evt | ) |

Get the event type field of a MIDI event structure.

DOCME - Event type enum appears to be internal (fluid_midi.h)

Parameters:

  | evt | MIDI event structure

Returns:
  Event type field

Definition at line 714 of file fluid_midi.c.

References fluid_midi_event_get_type().

Referenced by fluid_midi_event_get_type().

FLUIDSYNTH_API int fluid_midi_event_set_channel | ( | fluid_midi_event_t * | evt,
|  | int | chan |
| ) |  |  |

Set the channel field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure
  | chan | MIDI channel field

Returns:
  Always returns 0

Definition at line 748 of file fluid_midi.c.

References fluid_midi_event_set_channel().

Referenced by fluid_midi_event_set_channel(), and fluid_midi_router_handle_midi_event().

FLUIDSYNTH_API int fluid_midi_event_get_channel | ( | fluid_midi_event_t * | evt | ) |

Get the channel field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure

Returns:
  Channel field

Definition at line 737 of file fluid_midi.c.

References fluid_midi_event_get_channel().

Referenced by fluid_midi_event_get_channel().

FLUIDSYNTH_API int fluid_midi_event_get_key | ( | fluid_midi_event_t * | evt | ) |

Get the key field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure

Returns:
  MIDI note number (0-127)

Definition at line 759 of file fluid_midi.c.

References fluid_midi_event_get_key().

Referenced by fluid_midi_event_get_key().

FLUIDSYNTH_API int fluid_midi_event_set_key | ( | fluid_midi_event_t * | evt,
|  | int | v |
| ) |  |  |

Set the key field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure
  | v | MIDI note number (0-127)

Returns:
  Always returns 0

Definition at line 770 of file fluid_midi.c.

References fluid_midi_event_set_key().

Referenced by fluid_midi_event_set_key().

FLUIDSYNTH_API int fluid_midi_event_get_velocity | ( | fluid_midi_event_t * | evt | ) |

Get the velocity field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure

Returns:
  MIDI velocity number (0-127)

Definition at line 781 of file fluid_midi.c.

References fluid_midi_event_get_velocity().

Referenced by fluid_midi_event_get_velocity().

FLUIDSYNTH_API int fluid_midi_event_set_velocity | ( | fluid_midi_event_t * | evt,
|  | int | v |
| ) |  |  |

Set the velocity field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure
  | v | MIDI velocity value

Returns:
  Always returns 0

Definition at line 792 of file fluid_midi.c.

References fluid_midi_event_set_velocity().

Referenced by fluid_midi_event_set_velocity().

FLUIDSYNTH_API int fluid_midi_event_get_control | ( | fluid_midi_event_t * | evt | ) |

Get the control number of a MIDI event structure.

Parameters:

  | evt | MIDI event structure

Returns:
  MIDI control number

Definition at line 803 of file fluid_midi.c.

References fluid_midi_event_get_control().

Referenced by fluid_midi_event_get_control().

FLUIDSYNTH_API int fluid_midi_event_set_control | ( | fluid_midi_event_t * | evt,
|  | int | v |
| ) |  |  |

Set the control field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure
  | v | MIDI control number

Returns:
  Always returns 0

Definition at line 814 of file fluid_midi.c.

References fluid_midi_event_set_control().

Referenced by fluid_midi_event_set_control().

FLUIDSYNTH_API int fluid_midi_event_get_value | ( | fluid_midi_event_t * | evt | ) |

Get the value field from a MIDI event structure.

Parameters:

  | evt | MIDI event structure

Returns:
  Value field

Definition at line 825 of file fluid_midi.c.

References fluid_midi_event_get_value().

Referenced by fluid_midi_event_get_value().

FLUIDSYNTH_API int fluid_midi_event_set_value | ( | fluid_midi_event_t * | evt,
|  | int | v |
| ) |  |  |

Set the value field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure
  | v | Value to assign

Returns:
  Always returns 0

Definition at line 836 of file fluid_midi.c.

References fluid_midi_event_set_value().

Referenced by fluid_midi_event_set_value().

FLUIDSYNTH_API int fluid_midi_event_get_program | ( | fluid_midi_event_t * | evt | ) |

Get the program field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure

Returns:
  MIDI program number (0-127)

Definition at line 847 of file fluid_midi.c.

References fluid_midi_event_get_program().

Referenced by fluid_midi_event_get_program().

FLUIDSYNTH_API int fluid_midi_event_set_program | ( | fluid_midi_event_t * | evt,
|  | int | val |
| ) |  |  |

Set the program field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure
  | val | MIDI program number (0-127)

Returns:
  Always returns 0

Definition at line 858 of file fluid_midi.c.

References fluid_midi_event_set_program().

Referenced by fluid_midi_event_set_program().

FLUIDSYNTH_API int fluid_midi_event_get_pitch | ( | fluid_midi_event_t * | evt | ) |

Get the pitch field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure

Returns:
  Pitch value (DOCME units?)

Definition at line 869 of file fluid_midi.c.

References fluid_midi_event_get_pitch().

Referenced by fluid_midi_event_get_pitch().

FLUIDSYNTH_API int fluid_midi_event_set_pitch | ( | fluid_midi_event_t * | evt,
|  | int | val |
| ) |  |  |

Set the pitch field of a MIDI event structure.

Parameters:

  | evt | MIDI event structure
  | val | Pitch value (DOCME units?)

Returns:
  Always returns 0

Definition at line 880 of file fluid_midi.c.

References fluid_midi_event_set_pitch().

Referenced by fluid_midi_event_set_pitch().

FLUIDSYNTH_API fluid_midi_router_t* new_fluid_midi_router | ( | fluid_settings_t * | settings,
|  | handle_midi_event_func_t | handler,
|  | void * | event_handler_data |
| ) |  |  |

Create a new midi router.

Parameters:

  | settings | Settings used to configure MIDI router
  | handler | MIDI event callback
  | event_handler_data | Caller defined data pointer which gets passed to 'handler'

Returns:
  New MIDI router instance or NULL on error

A midi handler connects to a midi input device and forwards incoming midi events to the synthesizer.

Definition at line 40 of file fluid_midi_router.c.

References FLUID_ERR, and new_fluid_midi_router().

Referenced by new_fluid_midi_router().

FLUIDSYNTH_API int delete_fluid_midi_router | ( | fluid_midi_router_t * | router | ) |

Delete a MIDI router instance.

Parameters:

  | router | MIDI router to delete

Returns:
  Always returns 0

Definition at line 85 of file fluid_midi_router.c.

References delete_fluid_midi_router().

Referenced by delete_fluid_midi_router().

FLUIDSYNTH_API int fluid_midi_router_handle_midi_event | ( | void * | data,
|  | fluid_midi_event_t * | event |
| ) |  |  |

Handle a MIDI event through a MIDI router instance.

Parameters:

  | data | MIDI router instance fluid_midi_router_t (DOCME why is it a void *?)
  | event | MIDI event to handle

Returns:
  0 on success, -1 otherwise

Purpose: The midi router is called for each event, that is received via the 'physical' midi input. Each event can trigger an arbitrary number of generated events.

In default mode, a noteon event is just forwarded to the synth's 'noteon' function, a 'CC' event to the synth's 'CC' function and so on.

The router can be used to

- filter messages (for example: Pass sustain pedal CCs only to selected channels),
- split the keyboard (noteon with notenr < x: to ch 1, >x to ch 2),
- layer sounds (for each noteon received on ch 1, create a noteon on ch1, ch2, ch3,...)
- velocity scaling (for each noteon event, scale the velocity by 1.27 to give DX7 users a chance)
- velocity switching ("v <=100: Angel Choir; V > 100: Hell's Bells")
- get rid of aftertouch
- ...

Definition at line 276 of file fluid_midi_router.c.

References fluid_midi_event_set_channel(), fluid_midi_event_set_type(), and fluid_midi_router_handle_midi_event().

Referenced by fluid_midi_dump_prerouter(), and fluid_midi_router_handle_midi_event().

FLUIDSYNTH_API int fluid_midi_dump_prerouter | ( | void * | data,
|  | fluid_midi_event_t * | event |
| ) |  |  |

MIDI event callback function to display event information to stdout.

Parameters:

  | data | MIDI router instance
  | event | MIDI event data

Returns:
  0 on success, -1 otherwise

An implementation of the handle_midi_event_func_t function type, used for displaying MIDI event information between the MIDI driver and router to stdout. Useful for adding into a MIDI router chain for debugging MIDI events.

Definition at line 813 of file fluid_midi_router.c.

References fluid_midi_dump_prerouter(), and fluid_midi_router_handle_midi_event().

Referenced by fluid_midi_dump_prerouter().

FLUIDSYNTH_API int fluid_midi_dump_postrouter | ( | void * | data,
|  | fluid_midi_event_t * | event |
| ) |  |  |

MIDI event callback function to display event information to stdout.

Parameters:

  | data | MIDI router instance
  | event | MIDI event data

Returns:
  0 on success, -1 otherwise

An implementation of the handle_midi_event_func_t function type, used for displaying MIDI event information between the MIDI driver and router to stdout. Useful for adding into a MIDI router chain for debugging MIDI events.

Definition at line 857 of file fluid_midi_router.c.

References fluid_midi_dump_postrouter().

Referenced by fluid_midi_dump_postrouter().

FLUIDSYNTH_API fluid_midi_driver_t* new_fluid_midi_driver | ( | fluid_settings_t * | settings,
|  | handle_midi_event_func_t | handler,
|  | void * | event_handler_data |
| ) |  |  |

Create a new MIDI driver instance.

Parameters:

  | settings | Settings used to configure new MIDI driver.
  | handler | MIDI handler callback (for example: fluid_midi_router_handle_midi_event() for MIDI router)
  | event_handler_data | Caller defined data to pass to 'handler'

Returns:
  New MIDI driver instance or NULL on error

Definition at line 162 of file fluid_mdriver.c.

References FLUID_DBG, FLUID_ERR, and new_fluid_midi_driver().

Referenced by new_fluid_midi_driver().

FLUIDSYNTH_API void delete_fluid_midi_driver | ( | fluid_midi_driver_t * | driver | ) |

Delete a MIDI driver instance.

Parameters:

  | driver | MIDI driver to delete

Definition at line 185 of file fluid_mdriver.c.

References delete_fluid_midi_driver().

Referenced by delete_fluid_midi_driver().

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

Definition at line 1118 of file fluid_midi.c.

References FLUID_ERR, and new_fluid_player().

Referenced by new_fluid_player().

FLUIDSYNTH_API int delete_fluid_player | ( | fluid_player_t * | player | ) |

Delete a MIDI player instance.

Parameters:

  | player | MIDI player instance

Returns:
  Always returns 0

Definition at line 1149 of file fluid_midi.c.

References delete_fluid_player(), and fluid_player_stop().

Referenced by delete_fluid_player().

FLUIDSYNTH_API 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:
  0 on success, -1 on failure

Definition at line 1316 of file fluid_midi.c.

References fluid_player_play().

Referenced by fluid_player_play().

FLUIDSYNTH_API int fluid_player_stop | ( | fluid_player_t * | player | ) |

Stops a MIDI player.

Parameters:

  | player | MIDI player instance

Returns:
  Always returns 0

Definition at line 1341 of file fluid_midi.c.

References fluid_player_stop().

Referenced by delete_fluid_player(), and fluid_player_stop().

FLUIDSYNTH_API int fluid_player_join | ( | fluid_player_t * | player | ) |

Wait for a MIDI player to terminate (when done playing).

Parameters:

  | player | MIDI player instance

Returns:
  0 on success, -1 otherwise

Definition at line 1402 of file fluid_midi.c.

References fluid_player_join().

Referenced by fluid_player_join().

FLUIDSYNTH_API int fluid_player_set_loop | ( | fluid_player_t * | player,
|  | int | loop |
| ) |  |  |

Enable looping of a MIDI player (DOCME - Does this actually work?).

Parameters:

  | player | MIDI player instance
  | loop | Value for looping (DOCME - What would this value be, boolean/time index?)

Returns:
  Always returns 0

Definition at line 1359 of file fluid_midi.c.

References fluid_player_set_loop().

Referenced by fluid_player_set_loop().

FLUIDSYNTH_API 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 (DOCME - Units?)

Returns:
  Always returns 0

Definition at line 1372 of file fluid_midi.c.

References FLUID_DBG, and fluid_player_set_midi_tempo().

Referenced by fluid_player_set_bpm(), and fluid_player_set_midi_tempo().

FLUIDSYNTH_API 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 0

Definition at line 1391 of file fluid_midi.c.

References fluid_player_set_bpm(), and fluid_player_set_midi_tempo().

Referenced by fluid_player_set_bpm().