GSI_COMMANDS(3)

NAME
gsi_commands (GSI_CMD_*) - sound commands recognized by gsi_server (part of GSI - general sound interface) + associated events and data types.

COMMANDS
N.B. at the moment, this file is out of date. to be sure, check gsi_commands.h Notation: after a command are denoted the arguments and how many bytes are used for the command and each argument. Note that 16 and 32 bit quantities must be sent MSB first. Note that only the commands that are implemented or important but not yet implemented are mentioned here. Others can be found in the header file gsi_commands.h. __________________CONTROL COMMANDS___________________
--    Meta commands
GSI_CMD_SYNC 1; process all input, send any events (erors..), then send a GSI_EV_SYNC event and hard_flush the status.
GSI_CMD_PAUSE_ALL 1
 => pause all sound for the given application
GSI_CMD_CONTINUE_ALL 1
--    Server control
GSI_CMD_ENABLE_EVENTS <mask> 1 4; set given bits in the mask which determines the events to be sent.
GSI_CMD_DISABLE_EVENTS <mask> 1 4; clear given bits.
--    Devices
The following commands to change PCM settings will go into effect the next time the PCM settings are set for the client (i.e. at a GSI_CMD_GRAB_PCM if the client owns the PCM, when another client releases the PCM, or at the next sound after a silence when using GSI_CMD_AUTO_PCM.
GSI_CMD_SET_PCM_SAMPLERATE <samplerate> 1 4
GSI_CMD_SET_PCM_CHANNELS <channels> 1 1
GSI_CMD_SET_PCM_TYPE <type> 1 1
 => pass GSI_8BIT, GSI_16BIT, or GSI_8BIT_MULAW (later also GSI_24BIT).
GSI_CMD_SET_PCM_FRAGSIZE <size> 1 1; 0-3 mean the program will find a suitable value for quick response + 0,1,2,3 (man (3) gsi) itself, higher values are as requested.
GSI_CMD_USE_BEST_PCM_SETTINGS 1
 => e.g. when there are no sounds playing, and a new sound is started, pcm settings are set to those of the sound to be played, settings are not changed when a new sound is started that uses a superset (e.g. stereo instead of mono) as this might cause pop/clicks etc).
GSI_CMD_GRAB_PCM 1
 => grabs the PCM device (if not already grabbed) and sets the samplerate, channels etc. as set by earlier commands (if pcm was free). Sending this when the PCM device is already grabbed will set the pcm to the new settings (if any were set). NB: switches 'auto_pcm' off.
GSI_CMD_RELEASE_PCM 1
 => also switches 'auto_pcm' off
GSI_CMD_AUTO_PCM 1
 => automatically grabs the PCM when it receives a play command, releases it when all sounds have been played; particularly useful for apps that only want to emit beeps and such and don't want to hog the PCM device.
GSI_CMD_GRAB_SYNTH 1
GSI_CMD_RELEASE_SYNTH 1
GSI_CMD_GRAB_CD 1
GSI_CMD_SHARE_CD 1
GSI_CMD_RELEASE_CD 1
GSI_CMD_SET_BASE_WIDTH <width =0-256> 1 2 Mixer commands:
GSI_CMD_SET_MIXER_VOLUME <mixer_ch> <mixer_vol> 1 1 1; mixer volumes are 0-255
GSI_CMD_GET_MIXER_VOLUME <mch> 1 1; => GSI_EV_MIXER_STATUS> <mixer_ch> <mixer_vol> 1 1 1 GSI_CMD_MUTE_MIXER
1
GSI_CMD_UNMUTE_MIXER 1 GSI_CMD_SET_MIXER_BALANCE <balance> 1 2
GSI_CMD_SET_APPLICATION_VOLUME
Sound dir, sound file, load sounds, free sounds etc.:
GSI_CMD_LOAD_SOUND_LIST <filename> 1 strlen+1
 => Loads a bunch of filenames for slots
GSI_CMD_LOAD_ALL 1
 => load all sounds that have valid names
GSI_CMD_FREE_ALL 1
 => free all sounds (names are still loaded, so GSI_CMD_LOAD_SOUND will reload a slot)
GSI_CMD_LOAD_SOUND <slot> 1 1
 => load slot with a filename as set earlier by eg. GSI_CMD_LOAD_SOUND_FILE.
GSI_CMD_FREE_SOUND <slot> 1 1
GSI_CMD_LOAD_SOUND_FROM_FILE <slot> <string> <offset> 1 1 strlen+1 4
 => The string gives the file path (string ends with a 0)
GSI_CMD_LOAD_SOUND_DATA <slot> <samplerate> <type> <channels> <data_length> <data> 1 1 4 1 1 4 data_length
GSI_CMD_LOAD_SOUND_DATA_FROM_FILE <slot> <string> <offset> <length> <samplerate> <type> <channels> 1 1 strlen+1 4 4 4 1 1
GSI_CMD_GET_SLOT_INFO <slot> 1 1
 => returns the info to the program via an event:
GSI_EV_SLOT_INFO <slot> <samplerate> <type> <channels> <size> 1 1 4 1 1 4
GSI_CMD_SET_SOUND_DIR <string> 1 strlen+1
 => all sounds with a relative path are loaded from this path.
GSI_CMD_AUTO_FREE_SOUND <slot> 1 1 [ NOT YET IMPLEMENTED ]
 => Free memory used for a sound when it is not playing on any channel (load again when needed) -- Streaming sound:
GSI_CMD_CONFIGURE_SLOT <slot> <samplerate> <channels> <type> <num_samples> 1 1 4 1 1 4; GSI_CMD_STREAM <chn> <slot> 1 1 1; start playing a stream on the given channel using the data streamed into 'slot'. (rename: GSI_CMD_PLAY_STREAM ?). NB. The channel will remain in a playing state until it is killed. GSI_CMD_SEND_SLOT_DATA <slot> <length> <data> 1 1 4 length;
Instrument loading
GSI_CMD_LOAD_INSTRUMENT_DATA <bank> <len> <data> 1 1 4 len [ NOT YET IMPLEMENTED ]
GSI_CMD_LOAD_INSTRUMENT_FILE <bank> <string> 1 1 strlen+1 [ NOT YET IMPLEMENTED ] Midi loading
GSI_CMD_LOAD_SONG_DATA <len> <data> 1 4 len
GSI_CMD_LOAD_SONG_FILE <string> 1 strlen+1
GSI_CMD_SET_SPEED_OF_SOUND <speed> 1 2
 => the representation of mach 1, default=256.0 (8 bit fraction =65536) ________________SAMPLE PLAYING COMMANDS___________________
GSI_CMD_PLAY <ch> <slot> 1 1 1
 => play a sound on a channel
GSI_CMD_OVERWRITE <ch> <slot> 1 1 1
GSI_CMD_REPEAT <ch> <slot> 1 1 1
GSI_CMD_OVERWRITE_REPEAT <ch> <slot> 1 1 1
GSI_CMD_KILL_ALL 1
__________________SONG PLAYING COMMANDS___________________
GSI_CMD_PLAY_SONG 1
GSI_CMD_STOP_SONG 1
GSI_CMD_CONTINUE_SONG 1
GSI_CMD_MIDI_CONTROL <action | chn> <parm> 1 1 1 [ NOT YET IMPLEMENTED ]
-- This controls midi parameters for a channel (0-15)
-- action is a MIDI controller:
GSI_CMD_MIDI_SET_BANK_SELECT
GSI_CMD_MIDI_SET_MODWHEEL
GSI_CMD_MIDI_SET_BREATH
GSI_CMD_MIDI_SET_FOOT
GSI_CMD_MIDI_SET_PORTAMENTO_TIME
GSI_CMD_MIDI_SET_DATA_ENTRY
GSI_CMD_MIDI_SET_MAIN_VOLUME
GSI_CMD_MIDI_SET_BALANCE
GSI_CMD_MIDI_SET_PAN
GSI_CMD_MIDI_SET_EXPRESSION
________________SOUND MODIFICATION COMMANDS____________
You can 'OR' GSI_CMD_CURRENT with a command to refer to the last accessed channel. When using threads (locks not yet done) only use this inside a locked section. GSI_CMD_KILL <ch> 1 1
GSI_CMD_PAUSE <ch> 1 1
GSI_CMD_CONTINUE <ch> 1 1
GSI_CMD_SET_VOLUME <ch> <vol> 1 1 1
 => set volume of last sound playing on ch.
Between brackets are the arguments when using GSI_CMD_CURRENT (i.e. no <slot>):
GSI_CMD_SET_X <ch> <x> 1 1 2 [ <x> 1 2 ]
GSI_CMD_SET_Z <ch> <z> 1 1 2 [ <z> 1 2 ]
GSI_CMD_SET_Y <ch> <y> 1 1 2 [ <z> 1 2 ]
GSI_CMD_ADJUST_X <ch> <x> 1 1 2 [ <x> 1 2 ]
GSI_CMD_ADJUST_Z <ch> <z> 1 1 2 [ <z> 1 2 ]
GSI_CMD_ADJUST_Y <ch> <y> 1 1 2 [ <z> 1 2 ]
GSI_CMD_SET_DX <ch> <dx> 1 1 2 [ <dx> 1 2 ]
GSI_CMD_SET_DZ <ch> <dz> 1 1 2 [ <dz> 1 2 ]
GSI_CMD_SET_DY <ch> <dy> 1 1 2 [ <dz> 1 2 ]
GSI_CMD_SET_ANGLE <ch> <angle> 1 1 1 [ <angle> 1 1 ]
GSI_CMD_SET_ANGLE_R <ch> <angle> <r> 1 1 1 2 [ <angle> 1 1 2 ]
GSI_CMD_SET_ANGLE_DEFAULT_R <ch> <angle> 1 1 1 [ <angle> 1 1 ]
GSI_CMD_SET_PAN <ch> <pan position> 1 1 2
 => -256 gives a sound fully left, 0 centered, 256 fully right. This disables 3d effects for the given sound (doppler, motion)
GSI_CMD_DOPPLER_ON <ch> 1 1
GSI_CMD_DOPPLER_OFF <ch> 1 1

-- Observer settings [ NOT YET USED ]:
GSI_CMD_SET_OBSERVER_X <x> 1 2
GSI_CMD_SET_OBSERVER_Z <z> 1 2
GSI_CMD_SET_OBSERVER_Y <y> 1 2
GSI_CMD_SET_OBSERVER_ANGLE <fi> 1 1
GSI_CMD_SET_OBSERVER_FI <fi> 1 1; alias for ANGLE
GSI_CMD_SET_OBSERVER_THETA <th> 1 1
GSI_CMD_SET_OBSERVER_R <r> 1 2
GSI_CMD_ADJUST_OBSERVER_X <x> 1 2
GSI_CMD_ADJUST_OBSERVER_Z <z> 1 2
GSI_CMD_ADJUST_OBSERVER_Y <y> 1 2
GSI_CMD_ADJUST_OBSERVER_ANGLE <fi> 1 1
GSI_CMD_ADJUST_OBSERVER_FI <fi> 1 1; alias for ANGLE
GSI_CMD_ADJUST_OBSERVER_THETA <th> 1 1
GSI_CMD_ADJUST_OBSERVER_R <r> 1 2 GSI_CMD_SET_OBSERVER_DX <dx> 1 2
GSI_CMD_SET_OBSERVER_DZ <dz> 1 2
GSI_CMD_SET_OBSERVER_DY <dy> 1 2
GSI_CMD_OBSERVER_DOPPLER_ON 1
GSI_CMD_OBSERVER_DOPPLER_OFF 1

BITMASKS
________________SOUND MODIFICATION BITS________________
--    Bits denoting what effects may/must influence a sound (must be sent to the server [ NOT YET IMPLEMENTED ]):
GSI_EFFECTMASK_SET_X
GSI_EFFECTMASK_SET_Z
GSI_EFFECTMASK_SET_Y
GSI_EFFECTMASK_ADJUST_X
GSI_EFFECTMASK_ADJUST_Z
GSI_EFFECTMASK_ADJUST_Y
GSI_EFFECTMASK_SET_OBSERVER_X
GSI_EFFECTMASK_SET_OBSERVER_Z
GSI_EFFECTMASK_SET_OBSERVER_Y
GSI_EFFECTMASK_SET_OBSERVER_ANGLE
GSI_EFFECTMASK_CHANNEL_DOPPLER

ARGUMENTS
--    Dsp mode (& sample format)
GSI_8BIT_ALAW
GSI_8BIT_MULAW
GSI_8BIT
GSI_16BIT
GSI_24BIT
GSI_3BIT_ADPCM (sample format only)
GSI_4BIT_ADPCM (sample format only)
GSI_5BIT_ADPCM (sample format only)
GSI_8BIT_SIGNED
GSI_16BIT_LE
GSI_24BIT_LE
--    Dsp channels
GSI_MONO (=1)
GSI_STEREO (=2)
GSI_3CHANNEL (=3) (Left, Right, Middle)
GSI_QUAD (=4) (front L,R, rear L,R)
GSI_SURROUND4 (=5) (L, M, R, surround)
GSI_SURROUND6 (=6) (L, LM, M, R, RM, surround)
--    Mixer channels
-- 1. output
GSI_MASTER
GSI_PCM
GSI_SYNTH
GSI_CD
-- 2. input (&recording):
GSI_MICROPHONE
GSI_LINE_IN

OTHER STUFF
________________PROGRAM SIDE C/C++ STRUCTURE__________
This struct is not used at the moment. A function gsi_play(struct gsi_sound_item *s, int effect_bits) can easily be added to allow starting or changing a sound using such structs. Also, gsi_update (struct gsi_sound_item *s, int effect_bits) to update selected parts would be needed.
GSI_SOUNDMASK_VOLUME
GSI_SOUNDMASK_PAN
GSI_SOUNDMASK_SET set position ('OR' with others).
GSI_SOUNDMASK_ADJUST adjust position ('OR' with others).
GSI_SOUNDMASK_X
GSI_SOUNDMASK_Y
GSI_SOUNDMASK_Z
GSI_SOUNDMASK_DX
GSI_SOUNDMASK_DY
GSI_SOUNDMASK_DZ
GSI_SOUNDMASK_DOPPLER
GSI_SOUNDMASK_NEW_SOUND Start a new sound with GSI_CMD_PLAY etc.
GSI_SOUNDMASK_ADJUST_SOUND Adjust some parameters of a playing sound.
typedef struct gsi_sound_item {
    int channel; /* -1=automatic channel allocation from one that's not used. */
    byte type; /* sample, wave (4x), midi */
    byte sample_no;
    uint16 freq;
    byte volume_l; /* primary volume adjustments */
    byte volume_r;
    int pan; /* -256 =full left, 256=full right */
    int stereo_x; /* 16 bit+8 bit fraction */
    int dist_z; /* 16 bit+8 bit fraction */
    int height_y; /* 16 bit+8 bit fraction */
    /* Distances travelled in 1/32 s: */
    int stereo_dx; /* 8 bit+8 bit fraction */
    int dist_dz; /* 8 bit+8 bit fraction */
    int height_dy; /* 8 bit+8 bit fraction */
    int doppler; /* y/n */
    int echo; /* y/n -> effect_bits? */
    int echo_dt;
    int stereo_flip; /* y/n */
    int envelope; /* number, -1=none. Separate volume/freq envelopes? */
    int effect_flags; /* which (observer?) transforms affect the sound? */
} gsi_sound_item;

DESCRIPTION
Some info:
  current 3d defaults: x=0, z=64, y=0

SEE ALSO
gsi(3), gsi_events(3)

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