Voice
voice is a program that plays music and sounds based on
commands it reads from stdin. It writes status information on its
stdout that can be used for more sophisticated control. It's intended to be
a way for simple games or programs to play audio without having to deal
with more complicated sound APIs, possibly used together with software
like plumb and animator.
Command line arguments
- -v key value - set variable to a single token
- -v key token1 token2 ... . - set variable to multiple tokens (end list with a single period)
Syntax
voice reads input line by line. One line can contain zero or more
commands. Commands are composed of tokens separated by whitespace. If there are
multiple commands given in a single line, they must be separated by a
semicolon ';'. A hash character '#' starts a comment where
the rest of the line is ignored.
Tokens are strings that can be given in one of three ways:
- word - the string "word".
- $varname - replaced by the token or tokens specified on the command line for variable varname
- "string literal" - can specify a string containing spaces or special characters as a single token. Backslashes '\' can be used to specify special characters (backslashes, double quotes, endlines as \n, or any byte as \xFF).
Commands
Music
voice supports any music format that the sdl_mixer library supports (like .ogg or tracker formats like .xm and .mod depending on how the library was compiled). Multiple music files can be loaded at once, but only one track can be played.
- mus:load id path - load music file at path under the given ID. When loading succeeds, the string MUSLOAD id is printed on stdout, otherwise MUSLOADERROR id path reason is printed and voice exits. The id can be any string.
- mus:free id - unload track under id. Can be used to conserve memory.
- mus:play id [loops] - play music with the given id, repeated loops times. loops is an optional integer, if omitted the music track is repeated indefinitely.
- mus:fadein id fadein-ms [loops] - same as mus:play, but the track is faded in over fadein-ms milliseconds.
- mus:volume volume - set music volume to volume, a decimal number in the range of 0 to 1.
- mus:pause - music playback is paused.
- mus:resume - music playback is resumed.
- mus:rewind - the track is rewound to the beginning.
- mus:pos position - set playback position to position, a decimal number. The interpretation of the number depends on the music format. For details, see here.
Sound effects
voice supports any sound format that the sdl_mixer library supports. Multiple sounds can be loaded and played at once, sound effects can be looped and their simulated position (over stereo channels) can be controlled.
- load id path - load sound effect at path under the given ID. When loading succeeds, the string LOAD id is printed on stdout, otherwise LOADERROR id path reason is printed and voice exits. The id can be any string.
- samplevol id volume - set the volume of the sound effect under id to the given volume, a decimal in the range of 0 to 1. This applies for any future playback of the same sound effect. The default volume is 1.
- play id [loops] - play the sound effect with the given id. The effect is repated loops times (optional, default 1), or indefinitely if -1 is given.
- playpos id angle distance [loops] - play the sound effect with the given id. The effect comes from the direction of angle, an integer, specified in degrees in clockwise, where 0 is ahead and 90 is to the right. distance controls simulated distance, as an integer in the range of 0 to 255. 0 plays at full volume, 255 is silent. The effect is repeated loops times (optional, default 1), or indefinitely if -1 is given.
- play:id id [loops] - same as play, but emits PLAY id channel on stdout, where channel is the channel (integer) used for playback.
- playpos:id id angle distance [loops] - same as playpos, but emits PLAY id channel on stdout, where channel is the channel (integer) used for playback.
- pos channel angle distance - control the angle and distance of the sound effect currently being played on the given channel (integer). The interpretation of angle and distance are the same as with playpos and playpos:id.
- halt channel - halt the playback of the sound effect currently being played on the given channel (integer).
- volume channel volume - control the volume of the sound effect currently being played on the given channel (integer). volume is a decimal in the range of 0 to 1.
Control
- echo string - the given string is printed on stdout on a single line. Useful to confirm that a series of load commands have been processed.