GSI(7)

NAME
gsi_overview - introduction to GSI - general sound interface.

INTRODUCTION
  The mission: To provide extremely easy access to all sound devices (mixer, pcm, midi or other hardware music devices, cd's) for simple tasks and still allow full control over every detail of sound playing.
  This is done by allowing almost all functions to be controlled with simple serially encoded commands while using convenience functions for 'easy access' to the available features. The commands that aren't available directly via convenience functions are still quite easy to use even though the commands & data must be sent as a string of bytes.
  The serial encoding used has the advantage of very easy interfacing with other languages than C (this isn't so easy, or at the very least messy, with the use of structs and stuff and an essentially invisible communications layer in e.g. NAS; e.g. C callbacks are an extreme nuisance to handle in Eiffel).
  To minimize network load, the server commands use only the minimally needed information, and samples are loaded directly by the server if wanted, so these need not be sent via the network (but must then be mirrored on the local machine where the server runs, i.e. where sound output is). GSI consists of the following components:

Server:
    gsi_server (plays samples, music, cd's, sets mixer volumes etc for clients)

Libraries:
    libgsi (a client's interface to the server)
    libgsif (file loading, identifying, conversion)
    libgsipcm (device independent PCM access). libgsimixer (device independent MIXER access). libgsisynth (device independent SYNTH access). libgsicd (device independent CD access).
    Planned:libgsicddb: cd database functions (add entry, get entry etc.)

Applications:
    gsifile (music & sample file information and format conversion)
    gsiplay (client to gsi_server; sends commands to play music, samples, cd's, and set the mixer)

STARTING THE SERVER
Enter gsi_server & (see gsi_server(8) for more information). Note that the server needs a configuration file; see gsi.conf(5) ). Now you can use gsiplay(3) to play samples, music, and cd's.

ENVIRONMENT VARIABLES
If you want to run gsi_server remotely, use the environment variable GSI_HOST to set the name of the machine you want sound output on before starting the server. See gsi(3) for more detailed information.

IMPLEMENTATION
Server commands : Almost all commands work asynchronously, which means that errors or returned information are not received from the function calls themselves. This is necessitated by virtue of the fact that the sound playing system is a separate process and that synchronously returning values on such a system means 2 task switches in which the program using the sound system would have to wait. Hence, the program is informed of errors and information with callbacks (will be replaced by events (like in X11), which is more flexible). PCM : sounds (samples) are loaded into slots, and played on channels. These channels are really virtual channels, they are mixed together into one sound that's sent to the sound card (don't confuse this with the number of output channels of the pcm device, which is 1 for mono, 2 for stereo, 3 or higher for surround etc.). In case of hardware (with relevant drivers) that supports such virtual channels in hardware, this will be used instead of software mixing. The settings for the device itself, are those of the first client to grab the device (if that clients releases the pcm device, the next client will get it and its settings will be used). CD : cd playing works with a track-start event at the start of playing, and one each time a new track starts, and a track-end event when the last track finishes. CD playing is shared (anyone may send commands). MUSIC : song playing on synthesizer (which can also be an external midi device, or at some point in time, PCM emulation of a synthesizer) is limited to one owner who grabs the synthesizer. Pausing a song, releasing the synth, and then grabbing it and continuing the song will be possible soon (the application will have to resend any custom instruments).

DEVICES
see gsi(3).

SEE ALSO
gsi(3), gsi_server(8), gsi.conf(5), gsi_commands(3), gsi_events(3), gsif(3), gsiplay(1)

AUTHOR
Wouter Scholten email: whs@xs4all.nl
WWW page: http://www.xs4all.nl/~whs/