Next: , Previous: TrueType, Up: Top   [Contents][Index]


9 Audio

Procedure: open-audio [freq [format [stereo [chunksize]]]]

Open the mixer with a certain audio format. Optional args freq (number), format (number), stereo (boolean) and chunksize (number) specify those aspects of the device. Return #t if successful.

Procedure: allocated-channels numchans

Dynamically change the number of channels managed by the mixer to numchans. If decreasing the number of channels, the upper channels are stopped. Return the new number of allocated channels.

Procedure: device-ffc

Return audio device parameters as three values: frequency (Hz), format (number of bits) and channels (number of allocated channels).

Procedure: query-spec

NB: This procedure is obsoleted by device-ffc and will be removed after 2013-12-31.

Return audio device parameters as an alist, or #f if the audio has not yet been opened. Keys are freq (frequency), format, and channels (the number of allocated channels).

Procedure: load-music filename

Load music data (.mod .s3m .it .xm) from filename. Return a new music object if successful, otherwise #f.

Procedure: load-wave filename

Load wave data from filename. Return a new audio object if succesful, otherwise #f.

Procedure: reserve-channels num

Reserve the first num channels (0 through num-1) for the application. In other words don’t allocate them dynamically to the next sample if requested with a -1 value below. Return the number of reserved channels.

Procedure: group-channel channel [tag]

Attach to channel a tag. A tag can be assigned to several mixer channels, to form groups of channels. If tag is not specified, or is -1, the tag is removed (actually -1 is the tag used to represent the group of all the channels). Return #t if successful.

Procedure: group-channels from to [tag]

Assign channels in the range from through to to the default group. Optional arg tag specifies the group to use. Return #t if successful.

Procedure: group-available [tag]

Return the first available channel in the default group of channels. Optional arg tag specifies the group to check.

Procedure: group-count [tag]

Return the number of channels in the default group. Optional arg tag specifies the group to check.

Procedure: group-oldest [tag]

Return the "oldest" sample playing in the default group of channels. Optional arg tag specifies the group to check.

Procedure: group-newer [tag]

Return the "most recent" (i.e. last) sample playing in the default group of channels. Optional arg tag specifies the group to check.

Procedure: play-channel chunk [channel [loops [ticks [fade]]]]

Play an audio chunk on a specific channel. If the channel is unspecified or is -1, play on the first free channel. If loops is specified and greater than zero, loop the sound that many times. If loops is -1, loop infinitely (~65000 times). If ticks is specified, stop after that number of ticks. If fade is specified, fade in over that number of milliseconds. Return which channel was used to play the sound.

Procedure: play-music music [loops [fade]]

Play a music track. Optional args loops and fade are as in play-channel.

Procedure: volume [volume [which]]

Return the current volume on the default channel. Optional arg volume (a number in the range 0-128) means set the volume to volume and return the original volume. Optional second arg which specifies a chunk or channel to check (or modify) instead of the default. If volume is non-#f and which is #f, modify all channels.

[Here is the original (perhaps clearer) docstring. —ttn]

Set the volume in the range of 0-128 of a specific channel or chunk. If the channel is unspecified or is -1, set volume for all channels. Return the original volume. If the volume is unspecified or is -1, just return the current volume.

Procedure: music-volume [volume]

Return the current volume. Optional arg volume (a number in the range 0-128) means set the volume to volume.

Procedure: halt-channel [channel]

Halt playing of the default channel. Optional arg channel specifies a channel to halt.

Procedure: halt-group [tag]

Halt playing of the default group. Optional arg tag specifies the group to halt.

Procedure: halt-music

Halt playing of the music.

Procedure: expire-channel [channel [ticks]]

Turn off expiration for the default channel. Optional arg channel specifies a channel to change. Optional arg ticks (a number) means set the expiration delay to that many milliseconds, rather than turning it off.

Procedure: fade-out-channel [which [ms]]

Halt a channel, fading it out progressively until silent. Optional arg which specifies a channel to halt. Second optional arg ms specifies the number of milliseconds the fading will take (default 0).

Procedure: fade-out-group [tag [ms]]

Halt a group, fading it out progressively until silent. Optional arg tag specifies a group to halt. Second optional arg ms specifies the number of milliseconds the fading will take (default 0).

Procedure: fade-out-music [ms]

Halt the music, fading it out progressively until silent. Optional arg ms specifies the number of milliseconds the fading will take (default 0).

Procedure: fading-music

Return the fading status of the music, one of the symbols: no, out, in.

Procedure: fading-channel [which]

Return the fading status (a symbol, see fading-music) of the default channel. Optional arg which selects which channel to check.

Procedure: pause [channel]

Pause the default channel. Optional arg channel selects which channel to pause.

Procedure: resume [channel]

Resume (unpause) the default channel. Optional arg channel selects which channel to resume.

Procedure: paused? [channel]

Return #t if the default channel is paused. Optional arg channel selects a which channel to check.

Procedure: pause-music

Pause the music.

Procedure: resume-music

Resume (unpause) the music.

Procedure: rewind-music

Rewind the music.

Procedure: paused-music?

Return #t if the music is currently paused.

Procedure: playing? [channel]

Return #t iff the default channel is playing. Optional arg channel selects which channel to check.

Procedure: playing-music?

Return #t iff the music is currently playing.

Procedure: set-music-command command

Stop music and set external music playback command to command, a string. As a special case, if command is #f, arrange to use internal playback, instead.

FWIW, the C header file for the following panning, distance and position procs says:

Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and the panning will be done to the final mixed stream before passing it on to the audio device.

Procedure: set-panning channel l r

Set panning for (stereo) channel with l and r. Both l and r are integers 0–255, inclusive, where 0 is quietest and 255 is loudest.

To get “true” panning, use (set-panning CH N (- 255 N)).

Procedure: set-distance channel distance

Set the “distance” of channel to distance (integer, 0–255). This controls the location of the sound with respect to the listener.

Distance 0 is overlapping the listener, and 255 is as far away as possible. A distance of 255 does not guarantee silence; in such a case, you might want to try changing the chunk’s volume, or just cull the sample from the mixing process with halt-channel.

For efficiency, the precision of this effect may be limited (distances 1 through 7 might all produce the same effect, 8 through 15 are equal, etc).

Setting (distance) to 0 unregisters this effect, since the data would be unchanged.

Procedure: set-position channel angle distance

Set the “position” of channel to angle, distance. In this polar coordinate, angle is in degrees (integer modulo 360), and distance is an integer 0–255 (and is treated as in proc set-distance – see notes there).

Angle 0 is due north, and rotates clockwise as the value increases. For efficiency, the precision of this effect may be limited (angles 1 through 7 might all produce the same effect, 8 through 15 are equal, etc).

Setting angle and distance to 0 unregisters this effect, since the data would be unchanged.

Additionally, the C header says:

If the audio device is configured for mono output, then you won’t get any effectiveness from the angle; however, distance attenuation on the channel will still occur. While this effect will function with stereo voices, it makes more sense to use voices with only one channel of sound, so when they are mixed through this effect, the positioning will sound correct. You can convert them to mono through SDL before giving them to the mixer in the first place if you like.

Procedure: close-audio

Close the mixer, halting all playing audio.


Next: , Previous: TrueType, Up: Top   [Contents][Index]