Linux Sound Programming Code

/*! \mainpage FluidSynth 1.1 Developer Documentation \author Peter Hanappe \author Conrad Berhörster \author Antoine Schmitt \author Pedro López-Cabanillas \author Josh Green \author David Henningsson \author Copyright &copy; 2003-2011 Peter Hanappe, Conrad Berhörster, Antoine Schmitt, Pedro López-Cabanillas, Josh Green, David Henningsson \version Revision 1.1.4 \date 2011-07-22 All the source code examples in this document are in the public domain; you can use them as you please. This document is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ . The FluidSynth library is distributed under the GNU Library General Public License. A copy of the GNU Library General Public License is contained in the FluidSynth package; if not, visit http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. \section Abstract <a href="http://www.fluidsynth.org">FluidSynth</a> is a software synthesizer based on the <a href="http://en.wikipedia.org/wiki/SoundFont">SoundFont 2</a> specifications. The synthesizer is available as a shared object that can easily be reused in any application that wants to use wave-table synthesis. This document explains the basic usage of FluidSynth. Some of the more advanced features are not yet discussed but will be added in future versions. \section Contents Table of Contents - \ref Disclaimer - \ref Introduction - \ref NewIn1_1_6 - \ref NewIn1_1_5 - \ref NewIn1_1_4 - \ref NewIn1_1_3 - \ref NewIn1_1_2 - \ref NewIn1_1_1 - \ref NewIn1_1_0 - \ref CreatingSettings - \ref CreatingSynth - \ref CreatingAudioDriver - \ref UsingSynth - \ref LoadingSoundfonts - \ref SendingMIDI - \ref RealtimeMIDI - \ref MIDIPlayer - \ref MIDIPlayerMem - \ref MIDIRouter - \ref Sequencer - \ref Shell - \ref Advanced \section Disclaimer This documentation, in its current version, is incomplete. As always, the source code is the final reference. SoundFont(R) is a registered trademark of E-mu Systems, Inc. \section Introduction What is FluidSynth? - FluidSynth is a software synthesizer based on the SoundFont 2 specifications. The synthesizer is available as a shared object (a concept also named Dynamic Linking Library, or DLL) that can be easily reused in any application for wave-table synthesis. This document explains the basic usage of FluidSynth. - FluidSynth provides a Command Line Interface program ready to be used from the console terminal, offering most of the library functionalities to end users, among them the ability of render and play Standard MIDI Files, receive real-time MIDI events from external hardware ports and other applications, perform advanced routing of such events, enabling at the same time a local shell as well as a remote server commands interface. - FluidSynth is an API (Application Programming Interface) relieving programmers from a lot of details of reading SoundFont and MIDI events and files, and sending the digital audio output to a Sound Card. These tasks can be accomplished using a small set of functions. This document explains most of the API functions and gives short examples about them. - FluidSynth uses instrument samples contained in standard SF2 (SoundFont 2) files, having a file structure based on the RIFF format. The specification can be obtained here: http://connect.creativelabs.com/developer/SoundFont/Forms/AllItems.aspx but most users don't need to know any details of the format. - FluidSynth can easily be embedded in an application. It has a main header file, fluidsynth.h, and one dynamically linkable library. FluidSynth runs on Linux, Mac OS X, and the Windows platforms, and support for OS/2 and OpenSolaris is experimental. It has audio and midi drivers for all mentioned platforms but you can use it with your own drivers if your application already handles MIDI and audio input/output. This document explains the basic usage of FluidSynth and provides examples that you can reuse. - FluidSynth is open source, in active development. For more details, take a look at http://www.fluidsynth.org \section NewIn1_1_6 Whats new in 1.1.6? Changes in FluidSynth 1.1.6 concerning developers: - The player will not continue to the next song until all EOT (end of track events) have been reached. - Enable long arguments on all platforms where getopt.h is available - Windows: Fluidsynth.pc (pkg-config spec) is now installed. - Mac OS X Lion: A build failure was fixed. - For a full list of bug fixes, see http://sourceforge.net/apps/trac/fluidsynth/wiki/ChangeLog1_1_6 \section NewIn1_1_5 Whats new in 1.1.5? Changes in FluidSynth 1.1.5 concerning developers: - A change in the Jack driver might require a newer Jack version compared to 1.1.4. - For a full list of bug fixes, see http://sourceforge.net/apps/trac/fluidsynth/wiki/ChangeLog1_1_5 \section NewIn1_1_4 Whats new in 1.1.4? Changes in FluidSynth 1.1.4 concerning developers: - You can now play MIDI files that reside in memory (instead of specifying a filename). See \ref MIDIPlayerMem for an example. - A hook can be inserted for MIDI file playback, at playback time. This is done through the new fluid_player_set_playback_callback API function. You can use this to both inspect and modify MIDI events as they are being played (or add a MIDI router), just as you can for MIDI input drivers. - Channel 10 used to be the one and only drum channel, this can now be changed using the fluid_synth_set_channel_type. - fluid_synth_all_sounds_off and fluid_synth_all_notes_off are new public API functions. You can use them to turn notes off (i e releasing all keys, voices advance to release phase) or sounds off (more like pressing the mute button), for one channel or all channels. - For Mac OS X users: The CoreAudio driver has been adapted to use AuHAL, and the default build style has changed to "FluidSynth.framework". - For a full list of other enhancements and bug fixes, see http://sourceforge.net/apps/trac/fluidsynth/wiki/ChangeLog1_1_4 \section NewIn1_1_3 Whats new in 1.1.3? Changes in FluidSynth 1.1.3 concerning developers: - There are no new API additions in 1.1.3, this is a pure bug-fix release. For a list of bugs fixed, see https://sourceforge.net/apps/trac/fluidsynth/wiki/ChangeLog1_1_3 \section NewIn1_1_2 Whats new in 1.1.2? Changes in FluidSynth 1.1.2 concerning developers: - Build system has switched from autotools to CMake. For more information, see README.cmake. The autotools build system is still working, but it is deprecated. The "winbuild" and "macbuild" directories have been dropped in favor of CMake's ability to create project files on demand. - Thread safety has been reworked to overcome the limitations and bugs in version 1.1.0 and 1.1.1. There are two new settings controlling the thread safety, synth.threadsafe-api and synth.parallel-render. More information about these settings is in the \ref CreatingSettings section. Please look them through and set them appropriately according to your use case. - Voice overflow, i e what voice to kill when polyphony is exceeded, is now configurable. - Possibility to update polyphony and sample rate real-time. Note that updating polyphony is not hard real-time safe, and updating sample rate will kill all currently sounding voices. - MIDI Bank Select handling is now configurable. See the synth.midi-bank-select setting in the \ref CreatingSettings section for more information. - Can use RealTimeKit (on Linux) to get real-time priority, if the original attempt fails. Note that you'll need development headers for DBus to enable this functionality. - Shell commands for pitch bend and pitch bend range. - PulseAudio driver: two new settings allows you to specify media role, and control whether pulseaudio can adjust latency. \section NewIn1_1_1 Whats n