diff --git a/doc/Doxyfile b/doc/Doxyfile index bd44143f..8ce12644 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -88,12 +88,13 @@ WARN_LOGFILE = INPUT = \ ../doc/fluidsynth-v20-devdoc.txt \ ../doc/recent_changes.txt \ +../doc/usage \ ../include \ ../include/fluidsynth \ ../src INPUT_ENCODING = UTF-8 -FILE_PATTERNS = *.c *.h +FILE_PATTERNS = *.c *.h *.txt RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = NO diff --git a/doc/Doxyfile.cmake b/doc/Doxyfile.cmake index d9d12b99..0250a439 100644 --- a/doc/Doxyfile.cmake +++ b/doc/Doxyfile.cmake @@ -88,6 +88,7 @@ WARN_LOGFILE = INPUT = \ @CMAKE_SOURCE_DIR@/doc/fluidsynth-v20-devdoc.txt \ @CMAKE_SOURCE_DIR@/doc/recent_changes.txt \ +@CMAKE_SOURCE_DIR@/doc/usage \ @CMAKE_SOURCE_DIR@/include \ @CMAKE_SOURCE_DIR@/include/fluidsynth \ @CMAKE_SOURCE_DIR@/src \ @@ -95,7 +96,7 @@ INPUT = \ @CMAKE_BINARY_DIR@/doc/fluidsettings.txt INPUT_ENCODING = UTF-8 -FILE_PATTERNS = *.c *.h +FILE_PATTERNS = *.c *.h *.txt RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = NO diff --git a/doc/fluidsynth-v20-devdoc.txt b/doc/fluidsynth-v20-devdoc.txt index 57f81e0a..831b65aa 100644 --- a/doc/fluidsynth-v20-devdoc.txt +++ b/doc/fluidsynth-v20-devdoc.txt @@ -40,614 +40,6 @@ What is FluidSynth? - FluidSynth is open source, in active development. For more details, take a look at http://www.fluidsynth.org -\page UsageGuide Usage Guide - - \subpage CreatingSettings - - \subpage CreatingSynth - - \subpage LoadingSoundfonts - - \subpage CreatingAudioDriver - - \subpage UsingSynth - - \subpage SendingMIDI - - \subpage RealtimeMIDI - - \subpage MIDIPlayer - - \subpage FileRenderer - - \subpage MIDIPlayerMem - - \subpage MIDIRouter - - \subpage Sequencer - - \subpage Shell - - \subpage Multi-channel - - \subpage synth-context - - \subpage Advanced - - -\page CreatingSettings Creating and changing the settings - -Before you can use the synthesizer, you have to create a settings object. The settings objects is used by many components of the FluidSynth library. It gives a unified API to set the parameters of the audio drivers, the midi drivers, the synthesizer, and so forth. A number of default settings are defined by the current implementation. - -All settings have a name that follows the "dotted-name" notation. For example, "synth.polyphony" refers to the number of voices (polyphony) allocated by the synthesizer. The settings also have a type. There are currently three types: strings, numbers (double floats), and integers. You can change the values of a setting using the fluid_settings_setstr(), fluid_settings_setnum(), and fluid_settings_setint() functions. For example: - -\code -#include - -int main(int argc, char** argv) -{ - fluid_settings_t* settings = new_fluid_settings(); - fluid_settings_setint(settings, "synth.polyphony", 128); - /* ... */ - delete_fluid_settings(settings); - return 0; -} -\endcode - -The API contains the functions to query the type, the current value, the default value, the range and the "hints" of a setting. The range is the minimum and maximum value of the setting. The hints gives additional information about a setting. For example, whether a string represents a filename. Or whether a number should be interpreted on on a logarithmic scale. Check the settings.h API documentation for a description of all functions. - -\page CreatingSynth Creating the synthesizer - -To create the synthesizer, you pass it the settings object, as in the following example: - -\code -#include - -int main(int argc, char** argv) -{ - fluid_settings_t* settings; - fluid_synth_t* synth; - settings = new_fluid_settings(); - synth = new_fluid_synth(settings); - - /* Do useful things here */ - - delete_fluid_synth(synth); - delete_fluid_settings(settings); - return 0; -} -\endcode - -For a full list of available synthesizer settings, please refer to the \ref settings_synth documentation. - - - -\page CreatingAudioDriver Creating the audio driver - -The synthesizer itself does not write any audio to the audio output. This allows application developers to manage the audio output themselves if they wish. The next section describes the use of the synthesizer without an audio driver in more detail. - -Creating the audio driver is straightforward: set the audio.driver settings and create the driver object. Because the FluidSynth has support for several audio systems, you may want to change which one you want to use. The list below shows the audio systems that are currently supported. It displays the name, as used by the fluidsynth library, and a description. - -- jack: JACK Audio Connection Kit (Linux, Mac OS X, Windows) -- alsa: Advanced Linux Sound Architecture (Linux) -- oss: Open Sound System (Linux, Unix) -- pulseaudio: PulseAudio (Linux, Mac OS X, Windows) -- coreaudio: Apple CoreAudio (Mac OS X) -- dsound: Microsoft DirectSound (Windows) -- portaudio: PortAudio Library (Mac OS 9 & X, Windows, Linux) -- sndman: Apple SoundManager (Mac OS Classic) -- dart: DART sound driver (OS/2) -- opensles: OpenSL ES (Android) -- oboe: Oboe (Android) -- waveout: Microsoft WaveOut, alternative to DirectSound (Windows CE x86, Windows Mobile 2003 for ARMv5, Windows 98 SE, Windows NT 4.0, Windows XP and later) -- file: Driver to output audio to a file -- sdl2*: Simple DirectMedia Layer (Linux, Windows, Mac OS X, iOS, Android, FreeBSD, Haiku, etc.) - -The default audio driver depends on the settings with which FluidSynth was compiled. You can get the default driver with fluid_settings_getstr_default(). To get the list of available drivers use the fluid_settings_foreach_option() function. Finally, you can set the driver with fluid_settings_setstr(). In most cases, the default driver should work out of the box. - -Additional options that define the audio quality and latency are "audio.sample-format", "audio.period-size", and "audio.periods". The details are described later. - -You create the audio driver with the new_fluid_audio_driver() function. This function takes the settings and synthesizer object as arguments. For example: - -\code -void init() -{ - fluid_settings_t* settings; - fluid_synth_t* synth; - fluid_audio_driver_t* adriver; - settings = new_fluid_settings(); - - /* Set the synthesizer settings, if necessary */ - synth = new_fluid_synth(settings); - - fluid_settings_setstr(settings, "audio.driver", "jack"); - adriver = new_fluid_audio_driver(settings, synth); -} -\endcode - -As soon as the audio driver is created, it will start playing. The audio driver creates a separate thread that uses the synthesizer object to generate the audio. - -There are a number of general audio driver settings. The audio.driver settings define the audio subsystem that will be used. The audio.periods and audio.period-size settings define the latency and robustness against scheduling delays. There are additional settings for the audio subsystems used. For a full list of available audio driver settings, please refer to the \ref settings_audio documentation. - -*Note: In order to use sdl2 as audio driver, the application is responsible for initializing SDL (e.g. with SDL_Init()). This must be done before the first call to new_fluid_settings()! Also make sure to call SDL_Quit() after all fluidsynth instances have been destroyed. - -\page UsingSynth Using the synthesizer without an audio driver - -It is possible to use the synthesizer object without creating an audio driver. This is desirable if the application using FluidSynth manages the audio output itself. The synthesizer has several API functions that can be used to obtain the audio output: - -fluid_synth_write_s16() fills two buffers (left and right channel) with samples coded as signed 16 bits (the endian-ness is machine dependent). fluid_synth_write_float() fills a left and right audio buffer with 32 bits floating point samples. The function fluid_synth_process() is the generic interface for synthesizing audio, which is also capable of multi channel audio output. - -\page LoadingSoundfonts Loading and managing SoundFonts - -Before any sound can be produced, the synthesizer needs a SoundFont. - -SoundFonts are loaded with the fluid_synth_sfload() function. The function takes the path to a SoundFont file and a boolean to indicate whether the presets of the MIDI channels should be updated after the SoundFont is loaded. When the boolean value is TRUE, all MIDI channel bank and program numbers will be refreshed, which may cause new instruments to be selected from the newly loaded SoundFont. - -The synthesizer can load any number of SoundFonts. The loaded SoundFonts are treated as a stack, where each new loaded SoundFont is placed at the top of the stack. When selecting presets by bank and program numbers, SoundFonts are searched beginning at the top of the stack. In the case where there are presets in different SoundFonts with identical bank and program numbers, the preset from the most recently loaded SoundFont is used. The fluid_synth_program_select() can be used for unambiguously selecting a preset or bank offsets could be applied to each SoundFont with fluid_synth_set_bank_offset(), to try and ensure that each preset has unique bank and program numbers. - -The fluid_synth_sfload() function returns the unique identifier of the loaded SoundFont, or -1 in case of an error. This identifier is used in subsequent management functions: fluid_synth_sfunload() removes the SoundFont, fluid_synth_sfreload() reloads the SoundFont. When a SoundFont is reloaded, it retains it's ID and position on the SoundFont stack. - -Additional API functions are provided to get the number of loaded SoundFonts and to get a pointer to the SoundFont. - -\page SendingMIDI Sending MIDI events - -Once the synthesizer is up and running and a SoundFont is loaded, most people will want to do something useful with it. Make noise, for example. MIDI messages can be sent using the fluid_synth_noteon(), fluid_synth_noteoff(), fluid_synth_cc(), fluid_synth_pitch_bend(), fluid_synth_pitch_wheel_sens(), and fluid_synth_program_change() functions. For convenience, there's also a fluid_synth_bank_select() function (the bank select message is normally sent using a control change message). - -The following example show a generic graphical button that plays a note when clicked: - -\code -class SoundButton : public SomeButton -{ -public: - - SoundButton() : SomeButton() { - if (!_synth) { - initSynth(); - } - } - - static void initSynth() { - _settings = new_fluid_settings(); - _synth = new_fluid_synth(_settings); - _adriver = new_fluid_audio_driver(_settings, _synth); - } - - /* ... */ - - virtual int handleMouseDown(int x, int y) { - /* Play a note on key 60 with velocity 100 on MIDI channel 0 */ - fluid_synth_noteon(_synth, 0, 60, 100); - } - - virtual int handleMouseUp(int x, int y) { - /* Release the note on key 60 */ - fluid_synth_noteoff(_synth, 0, 60); - } - -protected: - - static fluid_settings_t* _settings; - static fluid_synth_t* _synth; - static fluid_audio_driver_t* _adriver; -}; -\endcode - -\page RealtimeMIDI Creating a real-time MIDI driver - -FluidSynth can process real-time MIDI events received from hardware MIDI ports or other applications. To do so, the client must create a MIDI input driver. It is a very similar process to the creation of the audio driver: you initialize some properties in a settings instance and call the new_fluid_midi_driver() function providing a callback function that will be invoked when a MIDI event is received. The following MIDI drivers are currently supported: - -- jack: JACK Audio Connection Kit MIDI driver (Linux, Mac OS X) -- oss: Open Sound System raw MIDI (Linux, Unix) -- alsa_raw: ALSA raw MIDI interface (Linux) -- alsa_seq: ALSA sequencer MIDI interface (Linux) -- winmidi: Microsoft Windows MM System (Windows) -- midishare: MIDI Share (Linux, Mac OS X) -- coremidi: Apple CoreMIDI (Mac OS X) - -\code -#include - -int handle_midi_event(void* data, fluid_midi_event_t* event) -{ - printf("event type: %d\n", fluid_midi_event_get_type(event)); -} - -int main(int argc, char** argv) -{ - fluid_settings_t* settings; - fluid_midi_driver_t* mdriver; - settings = new_fluid_settings(); - mdriver = new_fluid_midi_driver(settings, handle_midi_event, NULL); - /* ... */ - delete_fluid_midi_driver(mdriver); - return 0; -} -\endcode - -There are a number of general MIDI driver settings. The midi.driver setting -defines the MIDI subsystem that will be used. There are additional settings for -the MIDI subsystems used. For a full list of available midi driver settings, please refer to the \ref settings_midi documentation. - - - -\page MIDIPlayer Loading and playing a MIDI file - -FluidSynth can be used to play MIDI files, using the MIDI File Player interface. It follows a high level implementation, though its implementation is currently incomplete. After initializing the synthesizer, create the player passing the synth instance to new_fluid_player(). Then, you can add some SMF file names to the player using fluid_player_add(), and finally call fluid_player_play() to start the playback. You can check if the player has finished by calling fluid_player_get_status(), or wait for the player to terminate using fluid_player_join(). - -\code -#include - -int main(int argc, char** argv) -{ - int i; - fluid_settings_t* settings; - fluid_synth_t* synth; - fluid_player_t* player; - fluid_audio_driver_t* adriver; - settings = new_fluid_settings(); - synth = new_fluid_synth(settings); - player = new_fluid_player(synth); - /* process command line arguments */ - for (i = 1; i < argc; i++) { - if (fluid_is_soundfont(argv[i])) { - fluid_synth_sfload(synth, argv[1], 1); - } - if (fluid_is_midifile(argv[i])) { - fluid_player_add(player, argv[i]); - } - } - /* start the synthesizer thread */ - adriver = new_fluid_audio_driver(settings, synth); - /* play the midi files, if any */ - fluid_player_play(player); - /* wait for playback termination */ - fluid_player_join(player); - /* cleanup */ - delete_fluid_audio_driver(adriver); - delete_fluid_player(player); - delete_fluid_synth(synth); - delete_fluid_settings(settings); - return 0; -} -\endcode - - -A list of available MIDI player settings can be found in the \ref settings_player documentation. - - - -\page FileRenderer Fast file renderer for non-realtime MIDI file rendering - -Instead of creating an audio driver as described in section \ref MIDIPlayer one may chose to use the file renderer, which is the fastest way to synthesize MIDI files. - -\code -fluid_settings_t* settings; -fluid_synth_t* synth; -fluid_player_t* player; -fluid_file_renderer_t* renderer; - -settings = new_fluid_settings(); - -// specify the file to store the audio to -// make sure you compiled fluidsynth with libsndfile to get a real wave file -// otherwise this file will only contain raw s16 stereo PCM -fluid_settings_setstr(settings, "audio.file.name", "/path/to/output.wav"); - -// use number of samples processed as timing source, rather than the system timer -fluid_settings_setstr(settings, "player.timing-source", "sample"); - -// since this is a non-realtime scenario, there is no need to pin the sample data -fluid_settings_setint(settings, "synth.lock-memory", 0); - -synth = new_fluid_synth(settings); - -// *** loading of a soundfont omitted *** - -player = new_fluid_player(synth); -fluid_player_add(player, "/path/to/midifile.mid"); -fluid_player_play(player); - -renderer = new_fluid_file_renderer (synth); - -while (fluid_player_get_status(player) == FLUID_PLAYER_PLAYING) -{ - if (fluid_file_renderer_process_block(renderer) != FLUID_OK) - { - break; - } -} - -// just for sure: stop the playback explicitly and wait until finished -fluid_player_stop(player); -fluid_player_join(player); - -delete_fluid_file_renderer(renderer); -delete_fluid_player(player); -delete_fluid_synth(synth); -delete_fluid_settings(settings); -\endcode - -Various output files types are supported, if compiled with libsndfile. Those can be specified via the \c settings object as well. Refer to the \ref settings_audio documentation for more \c audio.file\.\* options. - - -\page MIDIPlayerMem Playing a MIDI file from memory - -FluidSynth can be also play MIDI files directly from a buffer in memory. If you need to play a file from a stream (such as stdin, a network, or a high-level file interface), you can load the entire file into a buffer first, and then use this approach. Use the same technique as above, but rather than calling fluid_player_add(), load it into memory and call fluid_player_add_mem() instead. Once you have passed a buffer to fluid_player_add_mem(), it is copied, so you may use it again or free it immediately (it is your responsibility to free it if you allocated it). - -\code -#include -#include -#include - -/* An example midi file */ -const char MIDIFILE[] = { - 0x4d, 0x54, 0x68, 0x64, 0x00, 0x00, 0x00, 0x06, - 0x00, 0x01, 0x00, 0x01, 0x01, 0xe0, 0x4d, 0x54, - 0x72, 0x6b, 0x00, 0x00, 0x00, 0x20, 0x00, 0x90, - 0x3c, 0x64, 0x87, 0x40, 0x80, 0x3c, 0x7f, 0x00, - 0x90, 0x43, 0x64, 0x87, 0x40, 0x80, 0x43, 0x7f, - 0x00, 0x90, 0x48, 0x64, 0x87, 0x40, 0x80, 0x48, - 0x7f, 0x83, 0x60, 0xff, 0x2f, 0x00 -}; - -int main(int argc, char** argv) -{ - int i; - void* buffer; - size_t buffer_len; - fluid_settings_t* settings; - fluid_synth_t* synth; - fluid_player_t* player; - fluid_audio_driver_t* adriver; - settings = new_fluid_settings(); - synth = new_fluid_synth(settings); - player = new_fluid_player(synth); - adriver = new_fluid_audio_driver(settings, synth); - /* process command line arguments */ - for (i = 1; i < argc; i++) { - if (fluid_is_soundfont(argv[i])) { - fluid_synth_sfload(synth, argv[1], 1); - } - } - /* queue up the in-memory midi file */ - fluid_player_add_mem(player, MIDIFILE, sizeof(MIDIFILE)); - /* play the midi file */ - fluid_player_play(player); - /* wait for playback termination */ - fluid_player_join(player); - /* cleanup */ - delete_fluid_audio_driver(adriver); - delete_fluid_player(player); - delete_fluid_synth(synth); - delete_fluid_settings(settings); - return 0; -} -\endcode - - -\page MIDIRouter Real-time MIDI router - -The MIDI router is one more processing layer directly behind the MIDI input. It processes incoming MIDI events and generates control events for the synth. It can be used to filter or modify events prior to sending them to the synthesizer. When created, the MIDI router is transparent and simply passes all MIDI events. Router "rules" must be added to actually make use of its capabilities. - -Some examples of MIDI router usage: - -- Filter messages (Example: Pass sustain pedal CCs only to selected channels) -- Split the keyboard (Example: noteon with notenr < x: to ch 1, >x to ch 2) -- Layer sounds (Example: for each noteon received on ch 1, create a noteon on ch1, ch2, ch3,...) -- Velocity scaling (Example: for each noteon event, scale the velocity by 1.27) -- Velocity switching (Example: v <= 100: "Angel Choir"; v > 100: "Hell's Bells") -- Get rid of aftertouch - -The MIDI driver API has a clean separation between the midi thread and the synthesizer. That opens the door to add a midi router module. - -MIDI events coming from the MIDI player do not pass through the MIDI router. - -\code -#include - -int main(int argc, char** argv) -{ - fluid_settings_t* settings; - fluid_synth_t* synth; - fluid_midi_router_t* router; - fluid_midi_router_rule_t* rule; - - settings = new_fluid_settings(); - synth = new_fluid_synth(settings); - - /* Create the MIDI router and pass events to the synthesizer */ - router = new_fluid_midi_router (settings, fluid_synth_handle_midi_event, synth); - - /* Clear default rules */ - fluid_midi_router_clear_rules (router); - - /* Add rule to map all notes < MIDI note #60 on any channel to channel 4 */ - rule = new_fluid_midi_router_rule (); - fluid_midi_router_rule_set_chan (rule, 0, 15, 0.0, 4); /* Map all to channel 4 */ - fluid_midi_router_rule_set_param1 (rule, 0, 59, 1.0, 0); /* Match notes < 60 */ - fluid_midi_router_add_rule (router, rule, FLUID_MIDI_ROUTER_RULE_NOTE); - - /* Add rule to map all notes >= MIDI note #60 on any channel to channel 5 */ - rule = new_fluid_midi_router_rule (); - fluid_midi_router_rule_set_chan (rule, 0, 15, 0.0, 5); /* Map all to channel 5 */ - fluid_midi_router_rule_set_param1 (rule, 60, 127, 1.0, 0); /* Match notes >= 60 */ - fluid_midi_router_add_rule (router, rule, FLUID_MIDI_ROUTER_RULE_NOTE); - - /* Add rule to reverse direction of pitch bender on channel 7 */ - rule = new_fluid_midi_router_rule (); - fluid_midi_router_rule_set_chan (rule, 7, 7, 1.0, 0); /* Match channel 7 only */ - fluid_midi_router_rule_set_param1 (rule, 0, 16383, -1.0, 16383); /* Reverse pitch bender */ - fluid_midi_router_add_rule (router, rule, FLUID_MIDI_ROUTER_RULE_PITCH_BEND); - - /* ... Create audio driver, process events, etc ... */ - - /* cleanup */ - delete_fluid_midi_router(router); - delete_fluid_synth(synth); - delete_fluid_settings(settings); - return 0; -} -\endcode - - - -\page Sequencer Using the MIDI sequencer - -FluidSynth's 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. - -The client program should first initialize the sequencer instance using the function new_fluid_sequencer2(). There is a complementary function delete_fluid_sequencer() to delete it. After creating the sequencer instance, the destinations can be registered using fluid_sequencer_register_fluidsynth() for the synthesizer destination, and optionally using fluid_sequencer_register_client() for the client destination providing a suitable callback function. It can be unregistered using fluid_sequencer_unregister_client(). After the initialization, events can be sent with fluid_sequencer_send_now() and scheduled to the future with fluid_sequencer_send_at(). The registration functions return identifiers, that can be used as destinations of an event using fluid_event_set_dest(). - -The function fluid_sequencer_get_tick() returns the current playing position. A program may choose a new timescale in milliseconds using fluid_sequencer_set_time_scale(). - -The following example uses the fluidsynth sequencer to implement a sort of music box. FluidSynth internal clock is used to schedule repetitive sequences of notes. The next sequence is scheduled on advance before the end of the current one, using a timer event that triggers a callback function. The scheduling times are always absolute values, to avoid slippage. - -\code -#include "fluidsynth.h" - -fluid_synth_t* synth; -fluid_audio_driver_t* adriver; -fluid_sequencer_t* sequencer; -short synthSeqID, mySeqID; -unsigned int now; -unsigned int seqduration; - -// prototype -void seq_callback(unsigned int time, fluid_event_t* event, fluid_sequencer_t* seq, void* data); - -void createsynth() -{ - fluid_settings_t* settings; - settings = new_fluid_settings(); - fluid_settings_setint(settings, "synth.reverb.active", 0); - fluid_settings_setint(settings, "synth.chorus.active", 0); - synth = new_fluid_synth(settings); - adriver = new_fluid_audio_driver(settings, synth); - sequencer = new_fluid_sequencer2(0); - - // register synth as first destination - synthSeqID = fluid_sequencer_register_fluidsynth(sequencer, synth); - - // register myself as second destination - mySeqID = fluid_sequencer_register_client(sequencer, "me", seq_callback, NULL); - - // the sequence duration, in ms - seqduration = 1000; -} - -void deletesynth() -{ - delete_fluid_sequencer(sequencer); - delete_fluid_audio_driver(adriver); - delete_fluid_synth(synth); -} - -void loadsoundfont() -{ - int fluid_res; - // put your own path here - fluid_res = fluid_synth_sfload(synth, "Inside:VintageDreamsWaves-v2.sf2", 1); -} - -void sendnoteon(int chan, short key, unsigned int date) -{ - int fluid_res; - fluid_event_t *evt = new_fluid_event(); - fluid_event_set_source(evt, -1); - fluid_event_set_dest(evt, synthSeqID); - fluid_event_noteon(evt, chan, key, 127); - fluid_res = fluid_sequencer_send_at(sequencer, evt, date, 1); - delete_fluid_event(evt); -} - -void schedule_next_callback() -{ - int fluid_res; - // I want to be called back before the end of the next sequence - unsigned int callbackdate = now + seqduration/2; - fluid_event_t *evt = new_fluid_event(); - fluid_event_set_source(evt, -1); - fluid_event_set_dest(evt, mySeqID); - fluid_event_timer(evt, NULL); - fluid_res = fluid_sequencer_send_at(sequencer, evt, callbackdate, 1); - delete_fluid_event(evt); -} - -void schedule_next_sequence() { - // Called more or less before each sequence start - // the next sequence start date - now = now + seqduration; - - // the sequence to play - - // the beat : 2 beats per sequence - sendnoteon(0, 60, now + seqduration/2); - sendnoteon(0, 60, now + seqduration); - - // melody - sendnoteon(1, 45, now + seqduration/10); - sendnoteon(1, 50, now + 4*seqduration/10); - sendnoteon(1, 55, now + 8*seqduration/10); - - // so that we are called back early enough to schedule the next sequence - schedule_next_callback(); -} - -/* sequencer callback */ -void seq_callback(unsigned int time, fluid_event_t* event, fluid_sequencer_t* seq, void* data) { - schedule_next_sequence(); -} - -int main(void) { - createsynth(); - loadsoundfont(); - - // initialize our absolute date - now = fluid_sequencer_get_tick(sequencer); - schedule_next_sequence(); - - sleep(100000); - deletesynth(); - return 0; -} -\endcode - - -\page Shell Shell interface - -The shell interface allows you to send simple textual commands to the synthesizer, to parse a command file, or to read commands from the stdin or other input streams. To find the list of currently supported commands, type @c help in the fluidsynth command line shell. For a full list of available command line settings, please refer to the \ref settings_shell documentation. - - -\page Multi-channel Multi-channel audio rendering - -FluidSynth is capable of rendering all audio and all effects from all MIDI channels to separate stereo buffers. Refer to the documentation of fluid_synth_process() and review the different use-cases in the example file for information on how to do that: \ref fluidsynth_process.c - -The following chart illustrates how the voices (produced by MIDI NoteOns) are dispatched or mapped to their dry/effects audio buffers. - -\htmlonly - -FluidSynth Mixer Chart - -\endhtmlonly - - -\page synth-context Understanding the "synthesis context" - -When reading through the functions exposed via our API, you will often read the note: "May or may not be called from synthesis context." - -The reason for this is that some functions are intentionally not thread-safe. Or they require to be called from this context to behave correctly. - -FluidSynth's rendering engine is implemented by using the "Dispatcher Thread Pattern". This means that a certain thread @c A which calls one of FluidSynth's rendering functions, namely - -- fluid_synth_process() -- fluid_synth_nwrite_float() -- fluid_synth_write_float() -- fluid_synth_write_s16() - -automatically becomes the "synthesis thread". The terms "synthesis context" and "synthesis thread" are equivalent. A few locations in our API provide hooks that allow you to interfere this "synthesis context". At those locations you can register your own custom functions that will always be called by thread @c A. For this use-case, the following functions are of interest: - -- new_fluid_audio_driver2() -- fluid_player_set_playback_callback() -- fluid_sequencer_register_client() - - -\page Advanced Advanced features - -The following features are not yet fully documented. Some information can be -found in the API reference and in the GitHub Wiki. - -- Accessing low-level voice parameters -- Reverb settings -- Chorus settings -- Interpolation settings (set_gen, get_gen, NRPN) -- Voice overflow settings -- LADSPA effects unit -- MIDI tunings - - /*! \example example.c Example producing short random music with FluidSynth diff --git a/doc/usage/_overview.txt b/doc/usage/_overview.txt new file mode 100644 index 00000000..103c4279 --- /dev/null +++ b/doc/usage/_overview.txt @@ -0,0 +1,21 @@ +/*! + +\page UsageGuide Usage Guide + - \subpage CreatingSettings + - \subpage CreatingSynth + - \subpage LoadingSoundfonts + - \subpage CreatingAudioDriver + - \subpage UsingSynth + - \subpage SendingMIDI + - \subpage RealtimeMIDI + - \subpage MIDIPlayer + - \subpage FileRenderer + - \subpage MIDIPlayerMem + - \subpage MIDIRouter + - \subpage Sequencer + - \subpage Shell + - \subpage Multi-channel + - \subpage synth-context + - \subpage Advanced + +*/ diff --git a/doc/usage/advanced.txt b/doc/usage/advanced.txt new file mode 100644 index 00000000..4259058b --- /dev/null +++ b/doc/usage/advanced.txt @@ -0,0 +1,16 @@ +/*! + +\page Advanced Advanced features + +The following features are not yet fully documented. Some information can be +found in the API reference and in the GitHub Wiki. + +- Accessing low-level voice parameters +- Reverb settings +- Chorus settings +- Interpolation settings (set_gen, get_gen, NRPN) +- Voice overflow settings +- LADSPA effects unit +- MIDI tunings + +*/ diff --git a/doc/usage/audio_driver.txt b/doc/usage/audio_driver.txt new file mode 100644 index 00000000..5007e374 --- /dev/null +++ b/doc/usage/audio_driver.txt @@ -0,0 +1,82 @@ +/*! + +\page CreatingAudioDriver Creating the audio driver + +The synthesizer itself does not write any audio to the audio output. This +allows application developers to manage the audio output themselves if they +wish. The next section describes the use of the synthesizer without an audio +driver in more detail. + +Creating the audio driver is straightforward: set the +audio.driver settings and create the driver object. Because the +FluidSynth has support for several audio systems, you may want to change +which one you want to use. The list below shows the audio systems that are +currently supported. It displays the name, as used by the fluidsynth library, +and a description. + +- jack: JACK Audio Connection Kit (Linux, Mac OS X, Windows) +- alsa: Advanced Linux Sound Architecture (Linux) +- oss: Open Sound System (Linux, Unix) +- pulseaudio: PulseAudio (Linux, Mac OS X, Windows) +- coreaudio: Apple CoreAudio (Mac OS X) +- dsound: Microsoft DirectSound (Windows) +- portaudio: PortAudio Library (Mac OS 9 & X, Windows, Linux) +- sndman: Apple SoundManager (Mac OS Classic) +- dart: DART sound driver (OS/2) +- opensles: OpenSL ES (Android) +- oboe: Oboe (Android) +- waveout: Microsoft WaveOut, alternative to DirectSound (Windows CE x86, + Windows Mobile 2003 for ARMv5, Windows 98 SE, Windows NT 4.0, Windows XP + and later) +- file: Driver to output audio to a file +- sdl2*: Simple DirectMedia Layer (Linux, Windows, Mac OS X, iOS, Android, + FreeBSD, Haiku, etc.) + +The default audio driver depends on the settings with which FluidSynth was +compiled. You can get the default driver with +fluid_settings_getstr_default(). To get the list of available drivers use the +fluid_settings_foreach_option() function. Finally, you can set the driver +with fluid_settings_setstr(). In most cases, the default driver should work +out of the box. + +Additional options that define the audio quality and latency are +"audio.sample-format", "audio.period-size", and "audio.periods". The details +are described later. + +You create the audio driver with the new_fluid_audio_driver() function. This +function takes the settings and synthesizer object as arguments. For example: + +\code +void init() +{ + fluid_settings_t* settings; + fluid_synth_t* synth; + fluid_audio_driver_t* adriver; + settings = new_fluid_settings(); + + /* Set the synthesizer settings, if necessary */ + synth = new_fluid_synth(settings); + + fluid_settings_setstr(settings, "audio.driver", "jack"); + adriver = new_fluid_audio_driver(settings, synth); +} +\endcode + +As soon as the audio driver is created, it will start playing. The audio +driver creates a separate thread that uses the synthesizer object to generate +the audio. + +There are a number of general audio driver settings. The audio.driver +settings define the audio subsystem that will be used. The audio.periods and +audio.period-size settings define the latency and robustness against +scheduling delays. There are additional settings for the audio subsystems +used. For a full list of available audio driver settings, +please refer to the \ref settings_audio documentation. + +*Note: In order to use sdl2 as audio driver, the application +is responsible for initializing SDL (e.g. with SDL_Init()). This must be done +before the first call to new_fluid_settings()! +Also make sure to call SDL_Quit() after all fluidsynth instances have been +destroyed. + +*/ diff --git a/doc/usage/creating_settings.txt b/doc/usage/creating_settings.txt new file mode 100644 index 00000000..df4b27d9 --- /dev/null +++ b/doc/usage/creating_settings.txt @@ -0,0 +1,24 @@ +/*! + +\page CreatingSettings Creating and changing the settings + +Before you can use the synthesizer, you have to create a settings object. The settings objects is used by many components of the FluidSynth library. It gives a unified API to set the parameters of the audio drivers, the midi drivers, the synthesizer, and so forth. A number of default settings are defined by the current implementation. + +All settings have a name that follows the "dotted-name" notation. For example, "synth.polyphony" refers to the number of voices (polyphony) allocated by the synthesizer. The settings also have a type. There are currently three types: strings, numbers (double floats), and integers. You can change the values of a setting using the fluid_settings_setstr(), fluid_settings_setnum(), and fluid_settings_setint() functions. For example: + +\code +#include + +int main(int argc, char** argv) +{ + fluid_settings_t* settings = new_fluid_settings(); + fluid_settings_setint(settings, "synth.polyphony", 128); + /* ... */ + delete_fluid_settings(settings); + return 0; +} +\endcode + +The API contains the functions to query the type, the current value, the default value, the range and the "hints" of a setting. The range is the minimum and maximum value of the setting. The hints gives additional information about a setting. For example, whether a string represents a filename. Or whether a number should be interpreted on on a logarithmic scale. Check the settings.h API documentation for a description of all functions. + +*/ diff --git a/doc/usage/creating_synth.txt b/doc/usage/creating_synth.txt new file mode 100644 index 00000000..26475c2a --- /dev/null +++ b/doc/usage/creating_synth.txt @@ -0,0 +1,29 @@ +/*! + +\page CreatingSynth Creating the synthesizer + +To create the synthesizer, you pass it the settings object, as in the +following example: + +\code +#include + +int main(int argc, char** argv) +{ + fluid_settings_t* settings; + fluid_synth_t* synth; + settings = new_fluid_settings(); + synth = new_fluid_synth(settings); + + /* Do useful things here */ + + delete_fluid_synth(synth); + delete_fluid_settings(settings); + return 0; +} +\endcode + +For a full list of available synthesizer settings, please +refer to the \ref settings_synth documentation. + +*/ diff --git a/doc/usage/file_renderer.txt b/doc/usage/file_renderer.txt new file mode 100644 index 00000000..d52a9995 --- /dev/null +++ b/doc/usage/file_renderer.txt @@ -0,0 +1,60 @@ +/*! + +\page FileRenderer Fast file renderer for non-realtime MIDI file rendering + +Instead of creating an audio driver as described in section \ref MIDIPlayer +one may chose to use the file renderer, which is the fastest way to +synthesize MIDI files. + +\code +fluid_settings_t* settings; +fluid_synth_t* synth; +fluid_player_t* player; +fluid_file_renderer_t* renderer; + +settings = new_fluid_settings(); + +// specify the file to store the audio to +// make sure you compiled fluidsynth with libsndfile to get a real wave file +// otherwise this file will only contain raw s16 stereo PCM +fluid_settings_setstr(settings, "audio.file.name", "/path/to/output.wav"); + +// use number of samples processed as timing source, rather than the system timer +fluid_settings_setstr(settings, "player.timing-source", "sample"); + +// since this is a non-realtime scenario, there is no need to pin the sample data +fluid_settings_setint(settings, "synth.lock-memory", 0); + +synth = new_fluid_synth(settings); + +// *** loading of a soundfont omitted *** + +player = new_fluid_player(synth); +fluid_player_add(player, "/path/to/midifile.mid"); +fluid_player_play(player); + +renderer = new_fluid_file_renderer (synth); + +while (fluid_player_get_status(player) == FLUID_PLAYER_PLAYING) +{ + if (fluid_file_renderer_process_block(renderer) != FLUID_OK) + { + break; + } +} + +// just for sure: stop the playback explicitly and wait until finished +fluid_player_stop(player); +fluid_player_join(player); + +delete_fluid_file_renderer(renderer); +delete_fluid_player(player); +delete_fluid_synth(synth); +delete_fluid_settings(settings); +\endcode + +Various output files types are supported, if compiled with libsndfile. Those +can be specified via the \c settings object as well. Refer to the \ref +settings_audio documentation for more \c audio.file\.\* options. + +*/ diff --git a/doc/usage/loading_soundfonts.txt b/doc/usage/loading_soundfonts.txt new file mode 100644 index 00000000..cdc6f4e4 --- /dev/null +++ b/doc/usage/loading_soundfonts.txt @@ -0,0 +1,34 @@ +/*! + +\page LoadingSoundfonts Loading and managing SoundFonts + +Before any sound can be produced, the synthesizer needs a SoundFont. + +SoundFonts are loaded with the fluid_synth_sfload() function. The function +takes the path to a SoundFont file and a boolean to indicate whether the +presets of the MIDI channels should be updated after the SoundFont is loaded. +When the boolean value is TRUE, all MIDI channel bank and program numbers +will be refreshed, which may cause new instruments to be selected from the +newly loaded SoundFont. + +The synthesizer can load any number of SoundFonts. The loaded SoundFonts are +treated as a stack, where each new loaded SoundFont is placed at the top of +the stack. When selecting presets by bank and program numbers, SoundFonts are +searched beginning at the top of the stack. In the case where there are +presets in different SoundFonts with identical bank and program numbers, the +preset from the most recently loaded SoundFont is used. The +fluid_synth_program_select() can be used for unambiguously selecting a preset +or bank offsets could be applied to each SoundFont with +fluid_synth_set_bank_offset(), to try and ensure that each preset has unique +bank and program numbers. + +The fluid_synth_sfload() function returns the unique identifier of the loaded +SoundFont, or -1 in case of an error. This identifier is used in subsequent +management functions: fluid_synth_sfunload() removes the SoundFont, +fluid_synth_sfreload() reloads the SoundFont. When a SoundFont is reloaded, +it retains it's ID and position on the SoundFont stack. + +Additional API functions are provided to get the number of loaded SoundFonts +and to get a pointer to the SoundFont. + +*/ diff --git a/doc/usage/manual_rendering.txt b/doc/usage/manual_rendering.txt new file mode 100644 index 00000000..228b5589 --- /dev/null +++ b/doc/usage/manual_rendering.txt @@ -0,0 +1,17 @@ +/*! + +\page UsingSynth Using the synthesizer without an audio driver + +It is possible to use the synthesizer object without creating an audio +driver. This is desirable if the application using FluidSynth manages the +audio output itself. The synthesizer has several API functions that can be +used to obtain the audio output: + +fluid_synth_write_s16() fills two buffers (left and right channel) with +samples coded as signed 16 bits (the endian-ness is machine dependent). +fluid_synth_write_float() fills a left and right audio buffer with 32 bits +floating point samples. The function fluid_synth_process() is the generic +interface for synthesizing audio, which is also capable of multi channel +audio output. + +*/ diff --git a/doc/usage/midi_player.txt b/doc/usage/midi_player.txt new file mode 100644 index 00000000..ba8bdc76 --- /dev/null +++ b/doc/usage/midi_player.txt @@ -0,0 +1,55 @@ +/*! + +\page MIDIPlayer Loading and playing a MIDI file + +FluidSynth can be used to play MIDI files, using the MIDI File Player +interface. It follows a high level implementation, though its implementation +is currently incomplete. After initializing the synthesizer, create the +player passing the synth instance to new_fluid_player(). Then, you can add +some SMF file names to the player using fluid_player_add(), and finally call +fluid_player_play() to start the playback. You can check if the player has +finished by calling fluid_player_get_status(), or wait for the player to +terminate using fluid_player_join(). + +\code +#include + +int main(int argc, char** argv) +{ + int i; + fluid_settings_t* settings; + fluid_synth_t* synth; + fluid_player_t* player; + fluid_audio_driver_t* adriver; + settings = new_fluid_settings(); + synth = new_fluid_synth(settings); + player = new_fluid_player(synth); + /* process command line arguments */ + for (i = 1; i < argc; i++) { + if (fluid_is_soundfont(argv[i])) { + fluid_synth_sfload(synth, argv[1], 1); + } + if (fluid_is_midifile(argv[i])) { + fluid_player_add(player, argv[i]); + } + } + /* start the synthesizer thread */ + adriver = new_fluid_audio_driver(settings, synth); + /* play the midi files, if any */ + fluid_player_play(player); + /* wait for playback termination */ + fluid_player_join(player); + /* cleanup */ + delete_fluid_audio_driver(adriver); + delete_fluid_player(player); + delete_fluid_synth(synth); + delete_fluid_settings(settings); + return 0; +} +\endcode + + +A list of available MIDI player settings can be found in the +\ref settings_player documentation. + +*/ diff --git a/doc/usage/midi_player_mem.txt b/doc/usage/midi_player_mem.txt new file mode 100644 index 00000000..c2d3baaf --- /dev/null +++ b/doc/usage/midi_player_mem.txt @@ -0,0 +1,64 @@ +/*! + +\page MIDIPlayerMem Playing a MIDI file from memory + +FluidSynth can be also play MIDI files directly from a buffer in memory. If +you need to play a file from a stream (such as stdin, a network, or a +high-level file interface), you can load the entire file into a buffer first, +and then use this approach. Use the same technique as above, but rather than +calling fluid_player_add(), load it into memory and call +fluid_player_add_mem() instead. Once you have passed a buffer to +fluid_player_add_mem(), it is copied, so you may use it again or free it +immediately (it is your responsibility to free it if you allocated it). + +\code +#include +#include +#include + +/* An example midi file */ +const char MIDIFILE[] = { + 0x4d, 0x54, 0x68, 0x64, 0x00, 0x00, 0x00, 0x06, + 0x00, 0x01, 0x00, 0x01, 0x01, 0xe0, 0x4d, 0x54, + 0x72, 0x6b, 0x00, 0x00, 0x00, 0x20, 0x00, 0x90, + 0x3c, 0x64, 0x87, 0x40, 0x80, 0x3c, 0x7f, 0x00, + 0x90, 0x43, 0x64, 0x87, 0x40, 0x80, 0x43, 0x7f, + 0x00, 0x90, 0x48, 0x64, 0x87, 0x40, 0x80, 0x48, + 0x7f, 0x83, 0x60, 0xff, 0x2f, 0x00 +}; + +int main(int argc, char** argv) +{ + int i; + void* buffer; + size_t buffer_len; + fluid_settings_t* settings; + fluid_synth_t* synth; + fluid_player_t* player; + fluid_audio_driver_t* adriver; + settings = new_fluid_settings(); + synth = new_fluid_synth(settings); + player = new_fluid_player(synth); + adriver = new_fluid_audio_driver(settings, synth); + /* process command line arguments */ + for (i = 1; i < argc; i++) { + if (fluid_is_soundfont(argv[i])) { + fluid_synth_sfload(synth, argv[1], 1); + } + } + /* queue up the in-memory midi file */ + fluid_player_add_mem(player, MIDIFILE, sizeof(MIDIFILE)); + /* play the midi file */ + fluid_player_play(player); + /* wait for playback termination */ + fluid_player_join(player); + /* cleanup */ + delete_fluid_audio_driver(adriver); + delete_fluid_player(player); + delete_fluid_synth(synth); + delete_fluid_settings(settings); + return 0; +} +\endcode + +*/ diff --git a/doc/usage/midi_router.txt b/doc/usage/midi_router.txt new file mode 100644 index 00000000..9e014d0c --- /dev/null +++ b/doc/usage/midi_router.txt @@ -0,0 +1,76 @@ +/*! + +\page MIDIRouter Real-time MIDI router + +The MIDI router is one more processing layer directly behind the MIDI input. +It processes incoming MIDI events and generates control events for the synth. +It can be used to filter or modify events prior to sending them to the +synthesizer. When created, the MIDI router is transparent and simply passes +all MIDI events. Router "rules" must be added to actually make use of its +capabilities. + +Some examples of MIDI router usage: + +- Filter messages (Example: Pass sustain pedal CCs only to selected channels) +- Split the keyboard (Example: noteon with notenr < x: to ch 1, >x to ch 2) +- Layer sounds (Example: for each noteon received on ch 1, create a noteon on + ch1, ch2, ch3,...) +- Velocity scaling (Example: for each noteon event, scale the velocity by + 1.27) +- Velocity switching (Example: v <= 100: "Angel Choir"; v > 100: "Hell's + Bells") +- Get rid of aftertouch + +The MIDI driver API has a clean separation between the midi thread and the +synthesizer. That opens the door to add a midi router module. + +MIDI events coming from the MIDI player do not pass through the MIDI router. + +\code +#include + +int main(int argc, char** argv) +{ + fluid_settings_t* settings; + fluid_synth_t* synth; + fluid_midi_router_t* router; + fluid_midi_router_rule_t* rule; + + settings = new_fluid_settings(); + synth = new_fluid_synth(settings); + + /* Create the MIDI router and pass events to the synthesizer */ + router = new_fluid_midi_router (settings, fluid_synth_handle_midi_event, synth); + + /* Clear default rules */ + fluid_midi_router_clear_rules (router); + + /* Add rule to map all notes < MIDI note #60 on any channel to channel 4 */ + rule = new_fluid_midi_router_rule (); + fluid_midi_router_rule_set_chan (rule, 0, 15, 0.0, 4); /* Map all to channel 4 */ + fluid_midi_router_rule_set_param1 (rule, 0, 59, 1.0, 0); /* Match notes < 60 */ + fluid_midi_router_add_rule (router, rule, FLUID_MIDI_ROUTER_RULE_NOTE); + + /* Add rule to map all notes >= MIDI note #60 on any channel to channel 5 */ + rule = new_fluid_midi_router_rule (); + fluid_midi_router_rule_set_chan (rule, 0, 15, 0.0, 5); /* Map all to channel 5 */ + fluid_midi_router_rule_set_param1 (rule, 60, 127, 1.0, 0); /* Match notes >= 60 */ + fluid_midi_router_add_rule (router, rule, FLUID_MIDI_ROUTER_RULE_NOTE); + + /* Add rule to reverse direction of pitch bender on channel 7 */ + rule = new_fluid_midi_router_rule (); + fluid_midi_router_rule_set_chan (rule, 7, 7, 1.0, 0); /* Match channel 7 only */ + fluid_midi_router_rule_set_param1 (rule, 0, 16383, -1.0, 16383); /* Reverse pitch bender */ + fluid_midi_router_add_rule (router, rule, FLUID_MIDI_ROUTER_RULE_PITCH_BEND); + + /* ... Create audio driver, process events, etc ... */ + + /* cleanup */ + delete_fluid_midi_router(router); + delete_fluid_synth(synth); + delete_fluid_settings(settings); + return 0; +} +\endcode + +*/ diff --git a/doc/usage/multi_channel.txt b/doc/usage/multi_channel.txt new file mode 100644 index 00000000..0c136c11 --- /dev/null +++ b/doc/usage/multi_channel.txt @@ -0,0 +1,19 @@ +/*! + +\page Multi-channel Multi-channel audio rendering + +FluidSynth is capable of rendering all audio and all effects from all MIDI +channels to separate stereo buffers. Refer to the documentation of +fluid_synth_process() and review the different use-cases in the example file +for information on how to do that: \ref fluidsynth_process.c + +The following chart illustrates how the voices (produced by MIDI NoteOns) are +dispatched or mapped to their dry/effects audio buffers. + +\htmlonly + +FluidSynth Mixer Chart + +\endhtmlonly + +*/ diff --git a/doc/usage/realtime_midi.txt b/doc/usage/realtime_midi.txt new file mode 100644 index 00000000..b37018e6 --- /dev/null +++ b/doc/usage/realtime_midi.txt @@ -0,0 +1,47 @@ +/*! + +\page RealtimeMIDI Creating a real-time MIDI driver + +FluidSynth can process real-time MIDI events received from hardware MIDI +ports or other applications. To do so, the client must create a MIDI input +driver. It is a very similar process to the creation of the audio driver: you +initialize some properties in a settings instance and call the +new_fluid_midi_driver() function providing a callback function that will be +invoked when a MIDI event is received. The following MIDI drivers are +currently supported: + +- jack: JACK Audio Connection Kit MIDI driver (Linux, Mac OS X) +- oss: Open Sound System raw MIDI (Linux, Unix) +- alsa_raw: ALSA raw MIDI interface (Linux) +- alsa_seq: ALSA sequencer MIDI interface (Linux) +- winmidi: Microsoft Windows MM System (Windows) +- midishare: MIDI Share (Linux, Mac OS X) +- coremidi: Apple CoreMIDI (Mac OS X) + +\code +#include + +int handle_midi_event(void* data, fluid_midi_event_t* event) +{ + printf("event type: %d\n", fluid_midi_event_get_type(event)); +} + +int main(int argc, char** argv) +{ + fluid_settings_t* settings; + fluid_midi_driver_t* mdriver; + settings = new_fluid_settings(); + mdriver = new_fluid_midi_driver(settings, handle_midi_event, NULL); + /* ... */ + delete_fluid_midi_driver(mdriver); + return 0; +} +\endcode + +There are a number of general MIDI driver settings. The midi.driver setting +defines the MIDI subsystem that will be used. There are additional settings +for the MIDI subsystems used. For a full list of available +midi driver settings, please refer to the \ref settings_midi +documentation. + +*/ diff --git a/doc/usage/sending_midi.txt b/doc/usage/sending_midi.txt new file mode 100644 index 00000000..19e7c9d9 --- /dev/null +++ b/doc/usage/sending_midi.txt @@ -0,0 +1,53 @@ +/*! + +\page SendingMIDI Sending MIDI events + +Once the synthesizer is up and running and a SoundFont is loaded, most people +will want to do something useful with it. Make noise, for example. MIDI +messages can be sent using the fluid_synth_noteon(), fluid_synth_noteoff(), +fluid_synth_cc(), fluid_synth_pitch_bend(), fluid_synth_pitch_wheel_sens(), +and fluid_synth_program_change() functions. For convenience, there's also a +fluid_synth_bank_select() function (the bank select message is normally sent +using a control change message). + +The following example show a generic graphical button that plays a note when +clicked: + +\code +class SoundButton : public SomeButton +{ +public: + + SoundButton() : SomeButton() { + if (!_synth) { + initSynth(); + } + } + + static void initSynth() { + _settings = new_fluid_settings(); + _synth = new_fluid_synth(_settings); + _adriver = new_fluid_audio_driver(_settings, _synth); + } + + /* ... */ + + virtual int handleMouseDown(int x, int y) { + /* Play a note on key 60 with velocity 100 on MIDI channel 0 */ + fluid_synth_noteon(_synth, 0, 60, 100); + } + + virtual int handleMouseUp(int x, int y) { + /* Release the note on key 60 */ + fluid_synth_noteoff(_synth, 0, 60); + } + +protected: + + static fluid_settings_t* _settings; + static fluid_synth_t* _synth; + static fluid_audio_driver_t* _adriver; +}; +\endcode + +*/ diff --git a/doc/usage/sequencer.txt b/doc/usage/sequencer.txt new file mode 100644 index 00000000..30351b9b --- /dev/null +++ b/doc/usage/sequencer.txt @@ -0,0 +1,142 @@ +/*! + +\page Sequencer Using the MIDI sequencer + +FluidSynth's 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. + +The client program should first initialize the sequencer instance using the +function new_fluid_sequencer2(). There is a complementary function +delete_fluid_sequencer() to delete it. After creating the sequencer instance, +the destinations can be registered using +fluid_sequencer_register_fluidsynth() for the synthesizer destination, and +optionally using fluid_sequencer_register_client() for the client destination +providing a suitable callback function. It can be unregistered using +fluid_sequencer_unregister_client(). After the initialization, events can be +sent with fluid_sequencer_send_now() and scheduled to the future with +fluid_sequencer_send_at(). The registration functions return identifiers, +that can be used as destinations of an event using fluid_event_set_dest(). + +The function fluid_sequencer_get_tick() returns the current playing position. +A program may choose a new timescale in milliseconds using +fluid_sequencer_set_time_scale(). + +The following example uses the fluidsynth sequencer to implement a sort of +music box. FluidSynth internal clock is used to schedule repetitive sequences +of notes. The next sequence is scheduled on advance before the end of the +current one, using a timer event that triggers a callback function. The +scheduling times are always absolute values, to avoid slippage. + +\code +#include "fluidsynth.h" + +fluid_synth_t* synth; +fluid_audio_driver_t* adriver; +fluid_sequencer_t* sequencer; +short synthSeqID, mySeqID; +unsigned int now; +unsigned int seqduration; + +// prototype +void seq_callback(unsigned int time, fluid_event_t* event, fluid_sequencer_t* seq, void* data); + +void createsynth() +{ + fluid_settings_t* settings; + settings = new_fluid_settings(); + fluid_settings_setint(settings, "synth.reverb.active", 0); + fluid_settings_setint(settings, "synth.chorus.active", 0); + synth = new_fluid_synth(settings); + adriver = new_fluid_audio_driver(settings, synth); + sequencer = new_fluid_sequencer2(0); + + // register synth as first destination + synthSeqID = fluid_sequencer_register_fluidsynth(sequencer, synth); + + // register myself as second destination + mySeqID = fluid_sequencer_register_client(sequencer, "me", seq_callback, NULL); + + // the sequence duration, in ms + seqduration = 1000; +} + +void deletesynth() +{ + delete_fluid_sequencer(sequencer); + delete_fluid_audio_driver(adriver); + delete_fluid_synth(synth); +} + +void loadsoundfont() +{ + int fluid_res; + // put your own path here + fluid_res = fluid_synth_sfload(synth, "Inside:VintageDreamsWaves-v2.sf2", 1); +} + +void sendnoteon(int chan, short key, unsigned int date) +{ + int fluid_res; + fluid_event_t *evt = new_fluid_event(); + fluid_event_set_source(evt, -1); + fluid_event_set_dest(evt, synthSeqID); + fluid_event_noteon(evt, chan, key, 127); + fluid_res = fluid_sequencer_send_at(sequencer, evt, date, 1); + delete_fluid_event(evt); +} + +void schedule_next_callback() +{ + int fluid_res; + // I want to be called back before the end of the next sequence + unsigned int callbackdate = now + seqduration/2; + fluid_event_t *evt = new_fluid_event(); + fluid_event_set_source(evt, -1); + fluid_event_set_dest(evt, mySeqID); + fluid_event_timer(evt, NULL); + fluid_res = fluid_sequencer_send_at(sequencer, evt, callbackdate, 1); + delete_fluid_event(evt); +} + +void schedule_next_sequence() { + // Called more or less before each sequence start + // the next sequence start date + now = now + seqduration; + + // the sequence to play + + // the beat : 2 beats per sequence + sendnoteon(0, 60, now + seqduration/2); + sendnoteon(0, 60, now + seqduration); + + // melody + sendnoteon(1, 45, now + seqduration/10); + sendnoteon(1, 50, now + 4*seqduration/10); + sendnoteon(1, 55, now + 8*seqduration/10); + + // so that we are called back early enough to schedule the next sequence + schedule_next_callback(); +} + +/* sequencer callback */ +void seq_callback(unsigned int time, fluid_event_t* event, fluid_sequencer_t* seq, void* data) { + schedule_next_sequence(); +} + +int main(void) { + createsynth(); + loadsoundfont(); + + // initialize our absolute date + now = fluid_sequencer_get_tick(sequencer); + schedule_next_sequence(); + + sleep(100000); + deletesynth(); + return 0; +} +\endcode + +*/ diff --git a/doc/usage/shell.txt b/doc/usage/shell.txt new file mode 100644 index 00000000..e22bafce --- /dev/null +++ b/doc/usage/shell.txt @@ -0,0 +1,12 @@ +/*! + +\page Shell Shell interface + +The shell interface allows you to send simple textual commands to the +synthesizer, to parse a command file, or to read commands from the stdin or +other input streams. To find the list of currently supported commands, type +@c help in the fluidsynth command line shell. For a full list of available +command line settings, please refer to the \ref +settings_shell documentation. + +*/ diff --git a/doc/usage/synth_context.txt b/doc/usage/synth_context.txt new file mode 100644 index 00000000..9c57a004 --- /dev/null +++ b/doc/usage/synth_context.txt @@ -0,0 +1,22 @@ +/*! + +\page synth-context Understanding the "synthesis context" + +When reading through the functions exposed via our API, you will often read the note: "May or may not be called from synthesis context." + +The reason for this is that some functions are intentionally not thread-safe. Or they require to be called from this context to behave correctly. + +FluidSynth's rendering engine is implemented by using the "Dispatcher Thread Pattern". This means that a certain thread @c A which calls one of FluidSynth's rendering functions, namely + +- fluid_synth_process() +- fluid_synth_nwrite_float() +- fluid_synth_write_float() +- fluid_synth_write_s16() + +automatically becomes the "synthesis thread". The terms "synthesis context" and "synthesis thread" are equivalent. A few locations in our API provide hooks that allow you to interfere this "synthesis context". At those locations you can register your own custom functions that will always be called by thread @c A. For this use-case, the following functions are of interest: + +- new_fluid_audio_driver2() +- fluid_player_set_playback_callback() +- fluid_sequencer_register_client() + +*/