Module: SDL2::Mixer

Defined in:
mixer.c,
mixer.c

Overview

Sound mixing module.

With this module, you can play many kinds of sound files such as:

  • WAVE/RIFF (.wav)

  • AIFF (.aiff)

  • VOC (.voc)

  • MOD (.mod .xm .s3m .669 .it .med etc.)

  • MIDI (.mid)

  • OggVorbis (.ogg)

  • MP3 (.mp3)

  • FLAC (.flac)

Before playing sounds, you need to initialize this module by Mixer.init and open a sound device by Mixer.open.

This module mixes multiple sound sources in parallel. To play a sound source, you assign the source to a “channel” and this module mixes all sound sources assigned to the channels.

In this module, there are two types of sound sources: Chunk and Music. And there are two corresponding types of channels: Channels and MusicChannel.

Channels module plays Chunk objects, through multiple (default eight) channels. This module is suitable for the sound effects. The number of channels is variable with Channels.allocate.

MusicChannel module plays Music objects. This module has only one playing channel, and you cannot play multiple music in parallel. However an Music object is more efficient for memory, and this module supports more file formats than Channels. This module is suitable for playing “BGMs” of your application.

Defined Under Namespace

Modules: Channels, MusicChannel Classes: Chunk, Music

Constant Summary collapse

INIT_FLAC =

Returns bitmask which means initialization of Ogg flac loader.

Returns:

  • (Integer) —

    bitmask which means initialization of Ogg flac loader

UINT2NUM(MIX_INIT_FLAC)
INIT_MOD =

Returns bitmask which means initialization of MOD loader.

Returns:

  • (Integer) —

    bitmask which means initialization of MOD loader

UINT2NUM(MIX_INIT_MOD)
INIT_MP3 =

Returns bitmask which means initialization of MP3 loader.

Returns:

  • (Integer) —

    bitmask which means initialization of MP3 loader

UINT2NUM(MIX_INIT_MP3)
INIT_OGG =

Returns bitmask which means initialization of Ogg vorbis loader.

Returns:

  • (Integer) —

    bitmask which means initialization of Ogg vorbis loader

UINT2NUM(MIX_INIT_OGG)
INIT_MODPLUG =

Returns bitmask which means initialization of libmodplug.

Returns:

  • (Integer) —

    bitmask which means initialization of libmodplug

UINT2NUM(MIX_INIT_MODPLUG)
INIT_FLUIDSYNTH =

Returns bitmask which means initialization of fluidsynth.

Returns:

  • (Integer) —

    bitmask which means initialization of fluidsynth

UINT2NUM(MIX_INIT_FLUIDSYNTH)
INIT_MID =

Returns bitmask which means initialization of mid.

Returns:

  • (Integer) —

    bitmask which means initialization of mid

UINT2NUM(MIX_INIT_MID)
FORMAT_U8 =

Returns the value representing Unsiged 8-bit sample format. Used by open.

Returns:

  • (Integer) —

    the value representing Unsiged 8-bit sample format. Used by open

UINT2NUM(AUDIO_U8)
FORMAT_S8 =

Returns the value representing Siged 8-bit sample format. Used by open.

Returns:

  • (Integer) —

    the value representing Siged 8-bit sample format. Used by open

UINT2NUM(AUDIO_S8)
FORMAT_U16LSB =

Returns the value representing Unsiged 16-bit little-endian sample format. Used by open.

Returns:

  • (Integer) —

    the value representing Unsiged 16-bit little-endian sample format. Used by open

UINT2NUM(AUDIO_U16LSB)
FORMAT_S16LSB =

Returns the value representing Siged 16-bit little-endian sample format. Used by open.

Returns:

  • (Integer) —

    the value representing Siged 16-bit little-endian sample format. Used by open

UINT2NUM(AUDIO_S16LSB)
FORMAT_U16MSB =

Returns the value representing Unsiged 16-bit big-endian sample format. Used by open.

Returns:

  • (Integer) —

    the value representing Unsiged 16-bit big-endian sample format. Used by open

UINT2NUM(AUDIO_U16MSB)
FORMAT_S16MSB =

Returns the value representing Unsiged 16-bit big-endian sample format. Used by open.

Returns:

  • (Integer) —

    the value representing Unsiged 16-bit big-endian sample format. Used by open

UINT2NUM(AUDIO_S16MSB)
FORMAT_U16SYS =

Returns the value representing Unsiged 16-bit sample format. Endian is same as system byte order. Used by open.

Returns:

  • (Integer) —

    the value representing Unsiged 16-bit sample format. Endian is same as system byte order. Used by open

UINT2NUM(AUDIO_U16SYS)
FORMAT_S16SYS =

Returns the value representing Siged 16-bit sample format. Endian is same as system byte order. Used by open.

Returns:

  • (Integer) —

    the value representing Siged 16-bit sample format. Endian is same as system byte order. Used by open

UINT2NUM(AUDIO_S16SYS)
DEFAULT_FREQUENCY =

Returns Default frequency. 22050 (Hz).

Returns:

  • (Integer) —

    Default frequency. 22050 (Hz)

UINT2NUM(MIX_DEFAULT_FREQUENCY)
DEFAULT_FORMAT =

Returns Default sample format. Same as FORMAT_S16SYS.

Returns:

UINT2NUM(MIX_DEFAULT_FORMAT)
DEFAULT_CHANNELS =

Returns Default number of channels. 2.

Returns:

  • (Integer) —

    Default number of channels. 2.

INT2FIX(MIX_DEFAULT_CHANNELS)
MAX_VOLUME =

Returns Max volume value. 128.

Returns:

  • (Integer) —

    Max volume value. 128.

INT2FIX(MIX_MAX_VOLUME)
NO_FADING =

Returns the value represents that the channel is not fading in and fading out.

Returns:

  • (Integer) —

    the value represents that the channel is not fading in and fading out.

INT2FIX(MIX_NO_FADING)
FADING_OUT =

Returns the value represents that the channel is fading out.

Returns:

  • (Integer) —

    the value represents that the channel is fading out.

INT2FIX(MIX_FADING_OUT)
FADING_IN =

Returns the value represents that the channel is fading in.

Returns:

  • (Integer) —

    the value represents that the channel is fading in.

INT2FIX(MIX_FADING_IN)

Class Method Summary collapse

Class Method Details

.close ⇒ nil

Close the audio device.

Returns:

  • (nil) 


190
191
192
193
194
 
# File 'mixer.c', line 190

static VALUE Mixer_s_close(VALUE self)
{
    Mix_CloseAudio();
    return Qnil;
}

.init(flags) ⇒ nil

Initialize the mixer library.

This module function load dynamically-linked libraries for sound file formats such as ogg and flac.

You can give the initialized libraries (file formats) with OR’d bits of the following constants:

  • SDL2::Mixer::INIT_FLAC

  • SDL2::Mixer::INIT_MOD

  • SDL2::Mixer::INIT_MODPLUG

  • SDL2::Mixer::INIT_MP3

  • SDL2::Mixer::INIT_OGG

  • SDL2::Mixer::INIT_FLUIDSYNTH

Parameters:

  • flags (Integer) —

    intialized sublibraries

Returns:

  • (nil) 


130
131
132
133
134
135
136
137
 
# File 'mixer.c', line 130

static VALUE Mixer_s_init(VALUE self, VALUE f)
{
    int flags = NUM2INT(f);
    if ((Mix_Init(flags) & flags) != flags) 
        rb_raise(eSDL2Error, "Couldn't initialize SDL_mixer");
    
    return Qnil;
}

.open(freq = 22050, format = SDL2::Mixer::DEFAULT_FORMAT, channels = 2, chunksize = 1024) ⇒ nil

Open a sound device.

Before calling loading/playing methods in the mixer module, this method must be called. Before calling this method, SDL2.init must be called with SDL2::INIT_AUDIO.

Parameters:

  • freq (Integer) (defaults to: 22050) —

    output sampling frequency in Hz. Normally 22050 or 44100 is used. 44100 is CD audio rate. SDL2::Mixer::DEFAULT_FREQUENCY(22050) is best for many kinds of game because 44100 requires too much CPU power on older computers.

  • format (Integer) (defaults to: SDL2::Mixer::DEFAULT_FORMAT) —

    output sample format

  • channels (defaults to: 2) —

    1 is for mono, and 2 is for stereo.

  • chunksize (defaults to: 1024) —

    bytes used per output sample

Returns:

  • (nil)

Raises:

  • (SDL2::Error) —

    raised when a device cannot be opened

See Also:



173
174
175
176
177
178
179
180
181
182
183
 
# File 'mixer.c', line 173

static VALUE Mixer_s_open(int argc, VALUE* argv, VALUE self)
{
    VALUE freq, format, channels, chunksize;
    rb_scan_args(argc, argv, "04", &freq, &format, &channels, &chunksize);
    HANDLE_MIX_ERROR(Mix_OpenAudio((freq == Qnil) ? MIX_DEFAULT_FREQUENCY : NUM2INT(freq),
                                   (format == Qnil) ? MIX_DEFAULT_FORMAT : NUM2UINT(format),
                                   (channels == Qnil) ? 2 : NUM2INT(channels),
                                   (chunksize == Qnil) ? 1024 : NUM2INT(chunksize)));
    playing_chunks = rb_ary_new();
    return Qnil;
}

.query ⇒ Array(Integer, Integer, Integer, Integer)

Query a sound device spec.

This method returns the most suitable setting for open the device.

Returns:

  • (Array(Integer, Integer, Integer, Integer)) —

    the suitable frequency in Hz, the suitable format, the suitable number of channels (1 for mono, 2 for stereo), and the number of call of open.



208
209
210
211
212
213
214
215
216
 
# File 'mixer.c', line 208

static VALUE Mixer_s_query(VALUE self)
{
    int frequency = 0, channels = 0, num_opened;
    Uint16 format = 0;

    num_opened = Mix_QuerySpec(&frequency, &format, &channels);
    return rb_ary_new3(4, INT2NUM(frequency), UINT2NUM(format),
                       INT2NUM(channels), INT2NUM(num_opened));
}