Audio

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.

# Channel

A Channel is an interface object to one of the mixer's channels. It can be used for manipulating sound on a particular channel.

## Class Methods

#### new( number )

Creates a Channel interface object for mixer channel number.

## Play control

These are pretty self-explanatory. play plays Sound sound 1 + loops times, for a maximum time of maxtime milliseconds.

#### busy → boolean

#### pause → self

#### play( sound, loops, maxtime ) → self
play( sound, loops ) → self
play( sound ) → self

#### stop → self

#### unpause → self

## Positioning

#### reverse_stereo( reverse ) → self

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.

#### set_distance( distance ) → self

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.

#### set_panning( left, right ) → self

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.

#### set_position( angle, distance ) → self

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.

## Volume methods

#### fade_out( milliseconds )

fade_out fades the channel to silence in milliseconds milliseconds.

#### volume
volume=( loudness )

Get and set the volume of a RUDL::Channel. Volumes range from 0.0 to 1.0.

# Mixer

Mixer is the main sound class. All methods are available as class and instance methods.

## Initializers

#### destroy → self

(was Mixer.quit) Uninitializes the Mixer. If you really want to do this, then be warned that all Music objects will be destroyed too!

#### new → Mixer
new( frequency ) → Mixer
new( frequency, format ) → Mixer
new( frequency, format, stereo ) → Mixer
new( frequency, format, stereo, buffersize ) → Mixer

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!

- frequency is a number like 11025, 22050 or 44100.
- 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.
- channels is 1 (mono) or 2 (stereo.)
- 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.

## Mass Channel Operations

These work on all channels at once.

#### pause

#### stop

#### unpause

## Methods

#### busy? → boolean

Returns the number of current active channels. This is not the total channels, but the number of channels that are currently playing sound.

#### driver → String

Returns the name of the driver doing the sound output.

#### fade_out( millisecs )

Fades away all sound to silence in millisecs milliseconds.

#### find_free_channel → Channel or nil

#### find_oldest_channel → Channel or nil

Both 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.

#### format

These get the parameters that Mixer is playing at. It returns an array of [format (like AUDIO_S8), channels, frequency]. See also Mixer@init.

#### reserved=( amount ) → self

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.

# Music

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.

## Constants

#file 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`

## Initializers

#### destroy

Frees the music from memory, thereby rendering the music instance useless. Ruby will crash if you use it anyway. #file - need to fix Dokumentat for this section Events class EndOfMusicEvent This event is posted when the current music has ended.

#### new( filename )

Creates a new Music object from a MOD, XM, MIDI, MP3 or OGG file (I think.)

## Methods

#### post_end_event → boolean
post_end_event=( on_or_off ) → self

Returns, or sets whether an EndOfMusicEvent will be posted when the current music stops playing. on_or_off is true or false.

## Play control

All pretty straight forward, except that they all act on the playing music, not the current one.

#### busy?

#### pause

#### play
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.

#### restart

#### stop

#### unpause

## Volume methods

These methods work on the currently playing music.

#### fade_out( milliseconds )

fades out the currently playing music to silence in milliseconds.

#### volume → Number
volume=( loudness ) → self

volume and volume= get and set the volume. Volume ranges from 0.0 to 1.0.

# Sound

Sound is a single sample. It is loaded from a WAV file.

## Initializers

Creates a new Sound object with the sound in file filename.

#### import( sampledata )

This method imports raw sampledata. If it is not in the Mixer's format, use Mixer@convert first.

#### load_new( filename )

#### new
new( filename )

#### String.to_sound

Creates a new RUDL::Sound object with the sound (in .WAV format) in the string.

## Volume methods

#### fade_out( milliseconds )

#### format

Returns the format of the Sound, which is always the same as the Mixer's format. See Mixer.format

#### play( loops, maxtime ) → Channel or nil

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.

#### stop → self

Stops all channels playing this Sound.

#### to_s → String

Returns a string with the sampledata.

#### volume
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.