Module: SDL2::Mixer

Defined in:
ext/sdl2_ext/mixer.c,
ext/sdl2_ext/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 =

Initialize Ogg flac loader

UINT2NUM(MIX_INIT_FLAC)
INIT_MOD =

Initialize MOD loader

UINT2NUM(MIX_INIT_MOD)
INIT_MP3 =

Initialize MP3 loader

UINT2NUM(MIX_INIT_MP3)
INIT_OGG =

Initialize Ogg vorbis loader

UINT2NUM(MIX_INIT_OGG)
INIT_MODPLUG =

Initialize libmodplug

UINT2NUM(MIX_INIT_MODPLUG)
INIT_FLUIDSYNTH =

Initialize fluidsynth

UINT2NUM(MIX_INIT_FLUIDSYNTH)
INIT_MID =

Initialize mid

UINT2NUM(MIX_INIT_MID)
FORMAT_U8 =

Unsiged 8-bit sample format. Used by open

UINT2NUM(AUDIO_U8)
FORMAT_S8 =

Siged 8-bit sample format. Used by open

UINT2NUM(AUDIO_S8)
FORMAT_U16LSB =

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

UINT2NUM(AUDIO_U16LSB)
FORMAT_S16LSB =

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

UINT2NUM(AUDIO_S16LSB)
FORMAT_U16MSB =

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

UINT2NUM(AUDIO_U16MSB)
FORMAT_S16MSB =

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

UINT2NUM(AUDIO_S16MSB)
FORMAT_U16SYS =

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

UINT2NUM(AUDIO_U16SYS)
FORMAT_S16SYS =

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

UINT2NUM(AUDIO_S16SYS)
DEFAULT_FREQUENCY =

Default frequency. 22050 (Hz)

UINT2NUM(MIX_DEFAULT_FREQUENCY)
DEFAULT_FORMAT =

:FORMAT_S16SYS}.

Default sample format. Same as {Mixer
DEFAULT_CHANNELS =

Default number of channels. 2.

INT2FIX(MIX_DEFAULT_CHANNELS)
MAX_VOLUME =

Max volume value. 128.

INT2FIX(MIX_MAX_VOLUME)
NO_FADING =

This constants represents that the channel is not fading in and fading out.

INT2FIX(MIX_NO_FADING)
FADING_OUT =

This constants represents that the channel is fading out.

INT2FIX(MIX_FADING_OUT)
FADING_IN =

This constants 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) 


184
185
186
187
188
 
# File 'ext/sdl2_ext/mixer.c', line 184

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) 


124
125
126
127
128
129
130
131
 
# File 'ext/sdl2_ext/mixer.c', line 124

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:



167
168
169
170
171
172
173
174
175
176
177
 
# File 'ext/sdl2_ext/mixer.c', line 167

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 ⇒ [Integer, Integer, Integer, Integer]

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.



202
203
204
205
206
207
208
209
210
 
# File 'ext/sdl2_ext/mixer.c', line 202

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