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

DEFAULT_FREQUENCY = 
UINT2NUM(MIX_DEFAULT_FREQUENCY)
DEFAULT_FORMAT = 
UINT2NUM(MIX_DEFAULT_FORMAT)
DEFAULT_CHANNELS = 
INT2FIX(MIX_DEFAULT_CHANNELS)
MAX_VOLUME = 
INT2FIX(MIX_MAX_VOLUME)
NO_FADING = 
INT2FIX(MIX_NO_FADING)
FADING_OUT = 
INT2FIX(MIX_FADING_OUT)
FADING_IN = 
INT2FIX(MIX_FADING_IN)

Class Method Summary (collapse)

Class Method Details

+ (nil) close

Close the audio device.

Returns:

  • (nil) 


183
184
185
186
187
 
# File 'mixer.c', line 183

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

+ (nil) init(flags)

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) 


123
124
125
126
127
128
129
130
 
# File 'mixer.c', line 123

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;
}

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

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:



166
167
168
169
170
171
172
173
174
175
176
 
# File 'mixer.c', line 166

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;
}

+ ([Integer, Integer, Integer, Integer]) query

Query a sound device spec.

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

Returns:

  • ([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.



201
202
203
204
205
206
207
208
209
 
# File 'mixer.c', line 201

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));
}