fade_out volume volume= busy pause unpause play stop set_panning set_position set_distance reverse_stereo
new load_new import convert to_sound
fade_out volume volume= play stop to_s format
new destroy fade_out find_free_channel find_oldest_channel find_free_channel find_oldest_channel busy? num_channels num_channels= num_channels num_channels= pause unpause stop pause unpause stop reserved= driver format
volume volume= fade_out play stop pause unpause busy? restart post_end_event post_end_event= destroy
On this page, there are various classes for sound output. The system consists of a mixer that will mix several sounds, and one piece of music.
The Sound class represents a particular sound sample. It can be played on any Channel of the Mixer.
The Mixer has a certain amount of Channels. Channels can be told to play a certain Sound. It is not possible to play more Sounds at once than there are Channels.
A separate Channel is kept by the Mixer for playing Music files. Since it's only one channel, only one song can play at a time.
This is a wrapper around SDL_mixer.
A Channel is an interface object to one of the mixer's channels. It can be used for manipulating sound on a particular channel.
Channel.new( number )Creates a Channel interface object for mixer channel number.
Channel#fade_out( milliseconds )Channel#volumeChannel#volume=( loudness )These are volume methods. fade_out fades the channel to silence in milliseconds milliseconds. volume returns the current volume. volume= sets the volume to loudness. Volumes range from 0.0 to 1.0.
Channel#busyChannel#pauseChannel#unpauseChannel#play( sound, loops, maxtime )Channel#play( sound, loops )Channel#play( sound )Channel#stopThese are pretty self-explanatory.
play plays Sound sound 1+loops times, for a maximum time of maxtime milliseconds.
Channel#set_panning( left, right )Set the panning of a channel. The left and right channels are specified as numbers between 0.0 and 1.0, quietest to loudest, respectively. Technically, this is just individual volume control for a sample with two (stereo) channels, so it can be used for more than just panning. If you want real panning, call it like this:
channel.set_panning(left, 1.0-left);
...which isn't so hard.
Returns self.
Channel#set_position( angle, distance )Set the position of a channel. angle is an number from 0 to 360, that specifies the location of the sound in relation to the listener. angle will be reduced as neccesary (540 becomes 180 degrees, -100 becomes 260). 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).
distance is a number between 0.0 and 1.0 that specifies the space between the sound and the listener. The larger the number, the further away the sound is. Using 1.0 does not guarantee that the channel will be culled from the mixing process or be completely silent. For efficiency, the precision of this effect may be limited (distance 0 through 0.1 might all produce the same effect, 0.1 through 0.2 are equal, etc). Setting angle and distance to 0 unregisters this effect, since the data would be unchanged.
Returns self.
Channel#set_distance( distance )distance is a number between 0.0 and 1.0 that specifies the space between the sound and the listener. The larger the number, the further away the sound is. Using 1.0 does not guarantee that the channel will be culled from the mixing process or be completely silent. For efficiency, the precision of this effect may be limited (distance 0 through 0.1 might all produce the same effect, 0.1 through 0.2 are equal, etc). Setting distance to 0 unregisters this effect, since the data would be unchanged.
Returns self.
Channel#reverse_stereo( reverse )Causes a channel to reverse its stereo. This is handy if the user has his speakers hooked up backwards, or you would like to have a minor bit of psychedelia in your sound code. :) Calling this function with reverse set to true reverses the chunks's usual channels. If reverse is false, the effect is unregistered.
Returns self.
Sound is a single sample. It is loaded from a WAV file.
Sound.newSound.new( filename )Sound.load_new( filename )Creates a new Sound object with the sound in file filename.
Sound.import( sampledata )This method imports raw sampledata.
If it is not in the Mixer's format, use Mixer.convert first.
Sound.convert( sample, source_format, destination_format )Returns a string with the string sample with sampledata in it, assumed to be in source_format, converted to the destination_format.
A format is an array with these contents: [frequency, format (like AUDIO_S8), channels].
String.to_soundCreates a new Sound object with the sound (in .WAV format) in the string.
Sound#fade_out( milliseconds )Sound#volumeSound#volume=( loudness )These are volume methods. fade_out fades all instances of this sound that are playing to silence in milliseconds milliseconds. volume returns the current volume. volume= sets the volume to loudness. Volumes range from 0.0 to 1.0.
Sound#play( loops, maxtime )Starts playing a song on an available channel. If no channels are available, it will not play and return nil. Loops controls how many extra times the sound will play, a negative loop will play indefinitely, it defaults to 0. Maxtime is the number of total milliseconds that the sound will play. It defaults to forever (-1).
Returns a channel object for the channel that is selected to play the sound.
Returns nil if for some reason no channel is found.
Sound#stopStops all channels playing this Sound.
Sound#to_sReturns a string with the sampledata.
Sound#formatReturns the format of the Sound, which is always the same as the Mixer's format.
See Mixer.format
Mixer is the main sound class.
Mixer.newMixer.new( frequency )Mixer.new( frequency, format )Mixer.new( frequency, format, stereo )Mixer.new( frequency, format, stereo, buffersize )Initializes the sound system.
This call is not neccesary, the mixer will call Mixer.new when it is needed.
When you disagree with the defaults (at the time of writing: 16 bit, 22kHz, stereo, 4096)
you can set them yourself, but do this before using any sound related method!
format is AUDIO_S8 for 8 bit samples or AUDIO_S16SYS for 16 bit samples.
Other possibilities are listed at the bottom of this page.
buffersize is how many samples are calculated in one go.
4096 by default. Set higher if your sound stutters.
Mixer.new will return a Mixer object, but if you don't want it, you can
discard it and use class methods instead.
Mixer.destroyMixer#destroy(was Mixer.quit) Uninitializes the Mixer. If you really want to do this, then be warned that all Music objects will be destroyed too!
Mixer.fade_out( millisecs )Mixer#fade_out( millisecs )Fades away all sound to silence in millisecs milliseconds.
Mixer.find_free_channelMixer.find_oldest_channelMixer#find_free_channelMixer#find_oldest_channelBoth functions search for a channel that can be used to play new sounds on. find_free_channel finds a channel that is not playing anything and returns nil if there is no such channel. find_oldest_channel finds the channel that has been playing for the longest time.
Mixer.busy?Mixer#busy?Returns the number of current active channels. This is not the total channels, but the number of channels that are currently playing sound.
Mixer.num_channelsMixer.num_channels=( amount )Mixer#num_channelsMixer#num_channels=( amount )Gets or sets the current number of channels available for the mixer. This value defaults to 8 when the mixer is first initialized. RUDL imposes a channel limit of 256.
These channels are not the same thing as in Mixer.init.
Mixer.pauseMixer.unpauseMixer.stopMixer#pauseMixer#unpauseMixer#stopThese work on all channels at once.
Mixer.reserved=( amount )Mixer#reserved=( amount )This sets aside the first amount channels. They can only be played on by directly creating a Channel object and playing on it. No other function will take these channels for playing.
Mixer.driverMixer#driverReturns the name of the driver doing the sound output.
Mixer.formatMixer#formatThese get the parameters that Mixer is playing at.
It returns an array of [format (like AUDIO_S8), channels, frequency].
See also Mixer.init.
This encapsulates a song. For some reason, SDL will only play one song at a time, and even though most of the Music methods are instance methods, some will act on the playing Music only.
Music.new( filename )Creates a new Music object from a MOD, XM, MIDI, MP3 or OGG file (I think.)
Music#volumeMusic#volume=( loudness )Music#fade_out( milliseconds )Volume methods: fade_out fades out the currently playing music to silence in milliseconds milliseconds. volume and volume= get and set the volume. Volume ranges from 0.0 to 1.0. These methods work on the currently playing music.
Music#playMusic#play( loops )Plays this piece of music, stopping the previously playing one. Plays the music one time, or loops+1 times if you pass loops.
Music#stopMusic#pauseMusic#unpauseMusic#busy?Music#restartAll pretty straight forward, except that they all act on the playing music, not the current one.
Music#post_end_eventMusic#post_end_event=( onOrOff )Returns, or sets whether an EndOfMusicEvent will be posted when the current music stops playing. onOrOff is true or false.
Music#destroyFrees the music from memory, thereby rendering the music instance useless.
This event is posted when the current music has ended.
These are for indicating an audio format: AUDIO_U8, AUDIO_S8, AUDIO_U16LSB, AUDIO_S16LSB, AUDIO_U16MSB, AUDIO_S16MSB, AUDIO_U16, AUDIO_S16, AUDIO_U16SYS, AUDIO_S16SYS
Back to index