TclMixer

SDL_mixer bindings for Tcl.

COMMANDS INDEX

tclmixer::sound fileName

tclmixer::music fileName

tclmixer::free soundOrMusicId

tclmixer::play ?-loop times? ?-channel number? ?-fadein time? soundOrMusicId

tclmixer::stop channelOrMUSIC ?delay?

tclmixer::volume soundIdOrMUSIC ?volume?

tclmixer::fadeOut channelOrMUSIC time

tclmixer::fading channelOrMUSIC

tclmixer::playing channelOrMUSIC

tclmixer::paused channelOrMUSIC

tclmixer::balance channel leftVolume rightVolume

tclmixer::distance channel distance

tclmixer::position channel angle distance

tclmixer::playPosition position

tclmixer::rewind

tclmixer::musicType ?musicId?

tclmixer::mixConfig option value ?option value ... ?

INTRODUCTION

TclMixer extension brings SDL_mixer power into Tcl evirnoment. It allows to play multiple sounds at the same time using built-in software mixer. It supports following sound formats: WAV/RIFF, MP3, OGG, MID (midi), MOD (including standart MOD modules, but also S3M, IT, XM). There are basic effects implemented, which would be very useful, such as 3D sound positioning, stereo balance, fading in/out and sound source distance. All these goodies closed in well known, simple Tcl syntax. To make this extension work, end-user has to got installed SDL (in version 1.2.x) and SDL_mixer (in version 1.2.x).

Common (in this document) syntax key-words are MUSIC and SOUND. They means that word (string) 'MUSIC' or 'music' and 'SOUND' or 'sound' can be used as argument of command. For example you can write:

puts [tclmixer::fading 0]

and you may also:

puts [tclmixer::fading music]

but this will fail:

puts [tclmixer::fading something]

SOUNDS VS. MUSICS

There are two kind of objects:

SOUND

Sounds are loaded from WAV / RIFF / MP3 / OGG files (only these are supported for sounds!) and they are usually

short, like gun shot, or something else. Sounds are loaded directly into memory, so they should be small. TclMixer can play many of these objects at same time.

MUSIC

Musics are loaded from any TclMixer supported formats (including SOUND formats and MOD and MID). They aren't loaded into memory, but readed piece by piece from hard disc (to allow using very big music files) while playing. Only one MUSIC object can be played at time, but while playing music, SOUND objects still can be played.

MIXER CHANNELS

To mix SOUND objects and play them simultaneously, TclMixer (SDL_mixer) uses channels. You can play on each channel any SOUND object and if you want to play many objects simultaneously, you have to play them on different channels. At the begining TclMixer allocates 16 channels, which should be enough but if you want, you can change it by command tclmixer::setChanneld, but if you allocate big number of channels (very big), it may segfoult, becouse of out of memory (just as SDL_mixer docs say).

COMMANDS DESCRIPTION

tclmixer::sound fileName

Creates sound object and returns its identifier. The identifier format is: sound#N where N is first unused integer, starting from 0. Sound objects can be played later with command tclmixer::play, but also manipulated by other TclMixer commands.

tclmixer::music fileName

Creates music object and returns its identifier. The identifier format is: music#N where N is first unused integer, starting from 0. Music objects also can be played later with command tclmixer::play, but also manipulated by other TclMixer commands.

tclmixer::free soundOrMusicId

Deletes given object (SOUND or MUSIC) and frees their memory. Returns empty string.

tclmixer::play ?-loop times? ?-channel number? ?-fadein time? soundOrMusicId

Starts playback of given object. If -loop option is given, the object will be played as many times, as given argument for -loop. NOTE: times argument starts from -1, where -1 means to loop object forever (until tclmixer::stop or Tcl exit), 0 means to play object once, 1 means to play object twice, etc. If -channel option will be given, then object will be played on given channel number. You may specify -1 as the channel number, to play on first unused channel (which is equal to ommit -channel option). If -fadein option is given, object will be played starting from silence and going to normal volume in time miliseconds. Very small values of time seems to make no effect (about 1-30ms). Returns channel number, which object is played on.

tclmixer::stop channelOrMUSIC ?delay?

Stops playback on given channel or music playback. Delay argument is ignored for MUSIC objects, but for SOUND objects it tells TclMixer to wait delay miliseconds befor stopping. Returns empty string.

tclmixer::volume soundIdOrMUSIC ?volume?

Returns current volume of SOUND object, channel, or music playback (integer, from 0 to 128). If volume argument is given, then TclMixer also sets new volume to given value, but it's done AFTER current volume value has been read.

tclmixer::fadeOut channelOrMUSIC time

Applies fade out effect to given channel or music playback. Fade out effect decreases volume from normal value, to silence in time miliseconds. Command returns number of channels that effect has been applied (channel -1 will apply it to all channels) or empty string for MUSIC.

tclmixer::fading channelOrMUSIC

Returns in, out, or no, which means that channel or music playback is already fading in, fading out, or it isn't fading.

tclmixer::playing channelOrMUSIC

Returns 1 if channel or music playback is already playing and 0 otherwise.

tclmixer::paused channelOrMUSIC

Returns 1 if channel or music playback is already paused and 0 otherwise.

tclmixer::balance channel leftVolume rightVolume

Sets independent channel volume values for left and right side. Volume values are integers betwean 0 and 255. Returns empty string.

tclmixer::distance channel distance

Sets sound source distance (kind of volume) for channel. Distance is integer, from 0 (close/loud) to 255 (far/quiet). Returns empty string.

tclmixer::position channel angle distance

This command is used to simple 3D sound source positioning. It sets position of sound source for channel at angle degrees and distance away. Angle is integer value betwean 0 and 360, where:

0 is directly in front,

90 is on the right side,

180 is behind,

270 is on the left side.

Distance argument has same meaning and value as in tclmixer::distance command.

tclmixer::playPosition position

Seeks music during playback (doesn't work while paused/halted!). Position is double value. Works only for OGG / MP3 / MOD formats and for each format it has another meaning. Here's what SDL_mixer documentation says:

For MOD it casts double into integer and jumps to given pattern number in module.

For MP3 it jumps for given number of seconds from current position.

For OGG it jumps for given number of seconds from begining of song.

Returns empty string.

tclmixer::rewind

Sets music playback position to start. It works even if playback is halted or paused. Returns empty string.

tclmixer::musicType ?musicId?

Returns type of music currently being played, or given music object. Return values may be:

CMD for external music player (this one is unavailable in TclMixer, becouse Tcl can use external player just using [exec])

WAV for WAV/RIFF format.

MOD for MOD, S3M, IT, XM module formats.

MID for midi file.

OGG for OGG vorbis format.

MP3 for Mpeg Layer 3 format.

NONE for no music currently played and no music argument given.

UNKNOWN for unknown format – should never happens.

tclmixer::mixConfig option value ?option value ... ?

Sets configuration values. There are four valid options to configure:

-channels

Number of channels to alocate.

-sound

Defines procedure name to be used as a callback when any sound playback has finished. The procedure should take one argument – channel number, the playback has finished on.

-music

Defines procedure name to be used as callback when music playback has finished. The procedure should not take any arguments.

-reserve

Reserve given channels number from being used when playing sounds when passing in -1 (or ommiting -channel option) as a channel number to tclmixer::play command.

CALLBACK PROCEDURES

There is no other way to determinate when sound/music playback has finished than using callback procedures. These procedures are called each time, when playback has finished.

There are two different callback procedures: for SOUND objects playback and for MUSIC objects playback. The first one takes as argument number of channel, which SOUND object was played on (it can be resolved from tclmixer::play return value). The second one takes no arguments.

EXAMPLES

package require TclMixer 1.2

namespace import tclmixer::*

proc soundCallback {chan} {

puts "Playback finished at channel $chan"

}

mixConfig -sound soundCallback

set snd [sound some_file.ogg]

button .b -text "Play" -command "play $snd"

pack .b