zdoom/fluidsynth
0
0
Fork 0
mirror of https://github.com/ZDoom/fluidsynth.git synced 2025-02-18 18:11:05 +00:00
Code Issues Projects Releases Packages Wiki Activity

MIDI Seqencer documentation

Browse source
This commit is contained in:
Marcus Weseloh 2020-11-11 22:09:43 +01:00
parent 4185b25d6f
commit 39ae70793a
5 changed files with 75 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
include/fluidsynth/event.h
View file

@ -26,10 +26,10 @@ extern "C" {
#endif
/**
* @defgroup SequencerEvents Sequencer Events
* @brief Sequencer event functions and defines.
* @defgroup sequencer_events Sequencer Events
* @ingroup sequencer
*
* Functions and constants for creating/processing sequencer events.
* Create, modify, query and destroy sequencer events.
*
* @{
*/
@ -61,9 +61,9 @@ enum fluid_seq_event_type
FLUID_SEQ_KEYPRESSURE, /**< Polyphonic aftertouch event @since 2.0.0 */
FLUID_SEQ_SYSTEMRESET, /**< System reset event @since 1.1.0 */
FLUID_SEQ_UNREGISTERING, /**< Called when a sequencer client is being unregistered. @since 1.1.0 */
#ifndef __DOXYGEN__
FLUID_SEQ_LASTEVENT /**< @internal Defines the count of events enums @warning This symbol is not part of the public API and ABI stability guarantee and may change at any time! */
#endif
FLUID_SEQ_LASTEVENT /**< @internal Defines the count of events enums @warning This symbol
is not part of the public API and ABI stability guarantee and
may change at any time! */
};
/* Event alloc/free */
@ -128,7 +128,6 @@ FLUIDSYNTH_API unsigned int fluid_event_get_duration(fluid_event_t *evt);
FLUIDSYNTH_API short fluid_event_get_bank(fluid_event_t *evt);
FLUIDSYNTH_API int fluid_event_get_pitch(fluid_event_t *evt);
FLUIDSYNTH_API unsigned int fluid_event_get_sfont_id(fluid_event_t *evt);
/* @} */
#ifdef __cplusplus

12
include/fluidsynth/seq.h
View file

@ -26,14 +26,21 @@ extern "C" {
#endif
/**
* @defgroup Sequencer Sequencer
* @brief MIDI event sequencer.
* @defgroup sequencer MIDI Sequencer
*
* MIDI event sequencer.
*
* The MIDI sequencer can be used to play MIDI events in a more flexible way than
* using the MIDI file player, which expects the events to be stored as
* Standard MIDI Files. Using the sequencer, you can provide the events one by
* one, with an optional timestamp for scheduling.
*
* @{
*/
/**
* Event callback prototype for destination clients.
*
* @param time Current sequencer tick value (see fluid_sequencer_get_tick()).
* @param event The event being received
* @param seq The sequencer instance
@ -65,7 +72,6 @@ void fluid_sequencer_remove_events(fluid_sequencer_t *seq, fluid_seq_id_t source
FLUIDSYNTH_API unsigned int fluid_sequencer_get_tick(fluid_sequencer_t *seq);
FLUIDSYNTH_API void fluid_sequencer_set_time_scale(fluid_sequencer_t *seq, double scale);
FLUIDSYNTH_API double fluid_sequencer_get_time_scale(fluid_sequencer_t *seq);
/* @} */
#ifdef __cplusplus

6
include/fluidsynth/seqbind.h
View file

@ -28,18 +28,14 @@ extern "C" {
#endif
/**
* @defgroup SequencerBind Sequencer Binding
* @ingroup Sequencer
* @brief Functions for binding sequencer objects to other subsystems.
* @addtogroup sequencer
*
* @{
*/
FLUIDSYNTH_API
fluid_seq_id_t fluid_sequencer_register_fluidsynth(fluid_sequencer_t *seq, fluid_synth_t *synth);
FLUIDSYNTH_API int
fluid_sequencer_add_midi_event_to_buffer(void *data, fluid_midi_event_t *event);
/* @} */
#ifdef __cplusplus

43
src/midi/fluid_seq.c
View file

@ -82,10 +82,13 @@ typedef struct _fluid_sequencer_client_t
/* API implementation */
/**
* Create a new sequencer object which uses the system timer. Use
* new_fluid_sequencer2() to specify whether the system timer or
* fluid_sequencer_process() is used to advance the sequencer.
* Create a new sequencer object which uses the system timer.
*
* @return New sequencer instance
*
* Use new_fluid_sequencer2() to specify whether the system timer or
* fluid_sequencer_process() is used to advance the sequencer.
*
* @deprecated As of fluidsynth 2.1.1 the use of the system timer has been deprecated.
*/
fluid_sequencer_t *
@ -96,12 +99,15 @@ new_fluid_sequencer(void)
/**
* Create a new sequencer object.
*
* @param use_system_timer If TRUE, sequencer will advance at the rate of the
* system clock. If FALSE, call fluid_sequencer_process() to advance
* the sequencer.
* @return New sequencer instance
* @since 1.1.0
*
* @note As of fluidsynth 2.1.1 the use of the system timer has been deprecated.
*
* @since 1.1.0
*/
fluid_sequencer_t *
new_fluid_sequencer2(int use_system_timer)
@ -142,8 +148,10 @@ new_fluid_sequencer2(int use_system_timer)
/**
* Free a sequencer object.
* @note Before fluidsynth 2.1.1 registered sequencer clients may not be fully freed by this function.
*
* @param seq Sequencer to delete
*
* @note Before fluidsynth 2.1.1 registered sequencer clients may not be fully freed by this function.
*/
void
delete_fluid_sequencer(fluid_sequencer_t *seq)
@ -165,10 +173,13 @@ delete_fluid_sequencer(fluid_sequencer_t *seq)
/**
* Check if a sequencer is using the system timer or not.
*
* @param seq Sequencer object
* @return TRUE if system timer is being used, FALSE otherwise.
* @since 1.1.0
*
* @deprecated As of fluidsynth 2.1.1 the usage of the system timer has been deprecated.
*
* @since 1.1.0
*/
int
fluid_sequencer_get_use_system_timer(fluid_sequencer_t *seq)
@ -183,6 +194,7 @@ fluid_sequencer_get_use_system_timer(fluid_sequencer_t *seq)
/**
* Register a sequencer client.
*
* @param seq Sequencer object
* @param name Name of sequencer client
* @param callback Sequencer client callback or NULL for a source client.
@ -235,9 +247,10 @@ fluid_sequencer_register_client(fluid_sequencer_t *seq, const char *name,
/**
* Unregister a previously registered client.
*
* The client's callback function will receive a FLUID_SEQ_UNREGISTERING event right before it is being unregistered.
* @param seq Sequencer object
* @param id Client ID as returned by fluid_sequencer_register_client().
*
* The client's callback function will receive a FLUID_SEQ_UNREGISTERING event right before it is being unregistered.
*/
void
fluid_sequencer_unregister_client(fluid_sequencer_t *seq, fluid_seq_id_t id)
@ -287,6 +300,7 @@ fluid_sequencer_unregister_client(fluid_sequencer_t *seq, fluid_seq_id_t id)
/**
* Count a sequencers registered clients.
*
* @param seq Sequencer object
* @return Count of sequencer clients.
*/
@ -303,6 +317,7 @@ fluid_sequencer_count_clients(fluid_sequencer_t *seq)
/**
* Get a client ID from its index (order in which it was registered).
*
* @param seq Sequencer object
* @param index Index of register client
* @return Client ID or #FLUID_FAILED if not found
@ -329,6 +344,7 @@ fluid_seq_id_t fluid_sequencer_get_client_id(fluid_sequencer_t *seq, int index)
/**
* Get the name of a registered client.
*
* @param seq Sequencer object
* @param id Client ID
* @return Client name or NULL if not found. String is internal and should not
@ -360,6 +376,7 @@ fluid_sequencer_get_client_name(fluid_sequencer_t *seq, fluid_seq_id_t id)
/**
* Check if a client is a destination client.
*
* @param seq Sequencer object
* @param id Client ID
* @return TRUE if client is a destination client, FALSE otherwise or if not found
@ -390,6 +407,7 @@ fluid_sequencer_client_is_dest(fluid_sequencer_t *seq, fluid_seq_id_t id)
/**
* Send an event immediately.
*
* @param seq Sequencer object
* @param evt Event to send (not copied, used directly)
*/
@ -434,6 +452,7 @@ fluid_sequencer_send_now(fluid_sequencer_t *seq, fluid_event_t *evt)
/**
* Schedule an event for sending at a later time.
*
* @param seq Sequencer object
* @param evt Event to send (will be copied into internal queue)
* @param time Time value in ticks (in milliseconds with the default time scale of 1000).
@ -479,6 +498,7 @@ fluid_sequencer_send_at(fluid_sequencer_t *seq, fluid_event_t *evt,
/**
* Remove events from the event queue.
*
* @param seq Sequencer object
* @param source Source client ID to match or -1 for wildcard
* @param dest Destination client ID to match or -1 for wildcard
@ -517,6 +537,7 @@ fluid_sequencer_get_tick_LOCAL(fluid_sequencer_t *seq, unsigned int cur_msec)
/**
* Get the current tick of the sequencer scaled by the time scale currently set.
*
* @param seq Sequencer object
* @return Current tick value
*/
@ -528,6 +549,7 @@ fluid_sequencer_get_tick(fluid_sequencer_t *seq)
/**
* Set the time scale of a sequencer.
*
* @param seq Sequencer object
* @param scale Sequencer scale value in ticks per second
* (default is 1000 for 1 tick per millisecond)
@ -563,6 +585,7 @@ fluid_sequencer_set_time_scale(fluid_sequencer_t *seq, double scale)
/**
* Get a sequencer's time scale.
*
* @param seq Sequencer object.
* @return Time scale value in ticks per second.
*/
@ -576,11 +599,13 @@ fluid_sequencer_get_time_scale(fluid_sequencer_t *seq)
/**
* Advance a sequencer.
*
* @param seq Sequencer object
* @param msec Time to advance sequencer to (absolute time since sequencer start).
*
* If you have registered the synthesizer as client (fluid_sequencer_register_fluidsynth()), the synth
* will take care of calling fluid_sequencer_process(). Otherwise it is up to the user to
* advance the sequencer manually.
* @param seq Sequencer object
* @param msec Time to advance sequencer to (absolute time since sequencer start).
*
* @since 1.1.0
*/
void

46
src/midi/fluid_seqbind.c
View file

@ -78,6 +78,10 @@ delete_fluid_seqbind(fluid_seqbind_t *seqbind)
/**
* Registers a synthesizer as a destination client of the given sequencer.
*
* @param seq Sequencer instance
* @param synth Synthesizer instance
* @returns Sequencer client ID, or #FLUID_FAILED on error.
*
* A convenience wrapper function around fluid_sequencer_register_client(), that allows you to
* easily process and render enqueued sequencer events with fluidsynth's synthesizer.
* The client being registered will be named @c fluidsynth.
@ -85,26 +89,23 @@ delete_fluid_seqbind(fluid_seqbind_t *seqbind)
* @note Implementations are encouraged to explicitly unregister this client either by calling
* fluid_sequencer_unregister_client() or by sending an unregistering event to the sequencer. Before
* fluidsynth 2.1.1 this was mandatory to avoid memory leaks.
@code{.cpp}
fluid_seq_id_t seqid = fluid_sequencer_register_fluidsynth(seq, synth);
// ... do work
fluid_event_t* evt = new_fluid_event();
fluid_event_set_source(evt, -1);
fluid_event_set_dest(evt, seqid);
fluid_event_unregistering(evt);
// unregister the "fluidsynth" client immediately
fluid_sequencer_send_now(seq, evt);
delete_fluid_event(evt);
delete_fluid_synth(synth);
delete_fluid_sequencer(seq);
@endcode
*
* @param seq Sequencer instance
* @param synth Synthesizer instance
* @returns Sequencer client ID, or #FLUID_FAILED on error.
* @code{.cpp}
* fluid_seq_id_t seqid = fluid_sequencer_register_fluidsynth(seq, synth);
*
* // ... do work
*
* fluid_event_t* evt = new_fluid_event();
* fluid_event_set_source(evt, -1);
* fluid_event_set_dest(evt, seqid);
* fluid_event_unregistering(evt);
*
* // unregister the "fluidsynth" client immediately
* fluid_sequencer_send_now(seq, evt);
* delete_fluid_event(evt);
* delete_fluid_synth(synth);
* delete_fluid_sequencer(seq);
* @endcode
*/
fluid_seq_id_t
fluid_sequencer_register_fluidsynth(fluid_sequencer_t *seq, fluid_synth_t *synth)
@ -352,12 +353,15 @@ static fluid_seq_id_t get_fluidsynth_dest(fluid_sequencer_t *seq)
}
/**
* Transforms an incoming midi event (from a midi driver or midi router) to a
* Transforms an incoming MIDI event (from a MIDI driver or MIDI router) to a
* sequencer event and adds it to the sequencer queue for sending as soon as possible.
* The signature of this function is of type #handle_midi_event_func_t.
*
* @param data The sequencer, must be a valid #fluid_sequencer_t
* @param event MIDI event
* @return #FLUID_OK or #FLUID_FAILED
*
* The signature of this function is of type #handle_midi_event_func_t.
*
* @since 1.1.0
*/
int