Intro: understanding sound
==========================

Sound is played via an external sound-server.
There can be played more sounds at the same time together.

Supported are wave-files, audio-files, midi-files and mp3-files.
Because playing midi-files or mp3-files invokes subprocesses
(modified Timidity++ resp. mpg123), this is more cpu-expensive
than playing wave-files or audio-files.

In order to be able to play sound, there must be support for one of:
 - OSS (open sound system - Linux and FreeBSD)
 - ALSA 0.9+ (Linux)
 - SUN AUDIO (OpenBSD, NetBSD, Solaris)


Sound formats

Wave-files must have an extension of       ".wav" or ".wave".
Sun-audio-files must have an extension of  ".au".
Midi-files must have an extension of       ".mid" or ".midi".
MP3-files must have an extension of        ".mp3".


Steps to play a sound

At first start the sound-server with vg_sound_startserver().
To play a sound-file, attach the sound-file to the sound-server (load it),
and give it a nickname (a "sound-name").
For all other operations you refer to this sound-file with its sound-name.
The sound-name must begin with "s-", must not have more than 15 characters,
and may contain letters, digits, underscores (_) and hyphens (-).

Example:
  You want to play "woodpecker.wav".
  Call vg_sound_attach() to load this file and pass as sound-name
  e.g. "s-wood_p1".
  To play it, call vg_sound_play() and pass "s-wood_p1" rather than the
  filename "woodpecker.wav".
  To pause, continue, stop, restart it, always refer to it with "s-wood_p1".


Grouping sounds together

You can create group-names beginning with "g-" and add sound-names to them,
grouping these sounds together in a group.
If you want to pause, continue, stop or change volume for these sounds,
you can pass the group-name instead of the single sound-names to the function.
This can be useful for stopping specific sound-effects or to stop the
background music without knowing exactly which one of the music-files
is actually playing.
There is a builtin group "ALL", which refers to all sounds.
Grouping functions are vg_sound_gclr(), vg_sound_gadd() and vg_sound_gdel().


Pausing a sound at its end

You can send a "pause-at-end" (vg_sound_pate()) to a playing sound,
which has the effect, that the sound will be paused, when it reaches its end.
Sending a "continue-at-beginning" (vg_sound_catb()) starts the sound again.
Of course this is only useful, if the sound is playing in a loop.
E.g. fireing a machine-gun plays an endless sound, releasing the key shall
pause the sound not immediatelly, but when it reached the end of the current
loop, and when the key is pressed again, the paused sound shall be continued.


Setting volume

With vg_sound_volm() you can set the volume
for a single sound-name, a group-name or the main system volume.



FUNCTIONS

vg_sound_startserver()
vg_sound_endserver()
vg_sound_attach()
vg_sound_play()
vg_sound_paus()
vg_sound_cont()
vg_sound_pate()
vg_sound_catb()
vg_sound_stop()
vg_sound_gclr()
vg_sound_gadd()
vg_sound_gdel()
vg_sound_volm()
vg_sound_volumename()

Back to Index