Teek API Documentation

Teek::SDL2::Music Class

Streaming music playback for longer audio files (MP3, OGG, WAV).

Only one Music track can play at a time (SDL2_mixer limitation). For short sound effects that can overlap, use Sound instead.

Inherits: Object

Instance Methods ↑

destroy

Free the underlying music data. Stops playback if playing.

Returns nil

View source ▼ 
static VALUE
music_destroy(VALUE self)
{
    struct sdl2_music *m;
    TypedData_Get_Struct(self, struct sdl2_music, &music_type, m);
    if (!m->destroyed && m->music) {
        Mix_HaltMusic();
        Mix_FreeMusic(m->music);
        m->music = NULL;
        m->destroyed = 1;
    }
    return Qnil;
}
GitHub

destroyed?

Whether the music has been destroyed.

Returns Boolean

View source ▼ 
static VALUE
music_destroyed_p(VALUE self)
{
    struct sdl2_music *m;
    TypedData_Get_Struct(self, struct sdl2_music, &music_type, m);
    return m->destroyed ? Qtrue : Qfalse;
}
GitHub

initialize(path)

Load a music file (MP3, OGG, WAV). Initializes the mixer automatically.

Parameters
  • path String — path to the music file
View source ▼ 
static VALUE
music_initialize(VALUE self, VALUE path)
{
    struct sdl2_music *m;
    TypedData_Get_Struct(self, struct sdl2_music, &music_type, m);

    ensure_mixer_init();

    StringValue(path);
    Mix_Music *mus = Mix_LoadMUS(StringValueCStr(path));
    if (!mus) {
        rb_raise(rb_eRuntimeError, "Mix_LoadMUS failed: %s", Mix_GetError());
    }

    m->music = mus;
    return self;
}
GitHub

pause

Pause music playback.

Returns nil

View source ▼ 
static VALUE
music_pause(VALUE self)
{
    get_music(self);
    Mix_PauseMusic();
    return Qnil;
}
GitHub

paused?

Whether music is currently paused.

Returns Boolean

View source ▼ 
static VALUE
music_paused_p(VALUE self)
{
    get_music(self);
    return Mix_PausedMusic() ? Qtrue : Qfalse;
}
GitHub

play(loops: -1, fade_ms: 0)

Start playing the music. Only one music track plays at a time.

Parameters
  • loops Integer — -1 = loop forever (default), 0 = play once, N = play N extra times
  • fade_ms Integer — fade-in duration in milliseconds (0 = no fade)

Returns nil

View source ▼ 
static VALUE
music_play(int argc, VALUE *argv, VALUE self)
{
    struct sdl2_music *m = get_music(self);
    int loops = -1;
    int fade_ms = 0;

    VALUE kwargs;
    rb_scan_args(argc, argv, ":", &kwargs);

    if (!NIL_P(kwargs)) {
        ID keys[2];
        VALUE vals[2];
        keys[0] = rb_intern("loops");
        keys[1] = rb_intern("fade_ms");

        rb_get_kwargs(kwargs, keys, 0, 2, vals);

        if (vals[0] != Qundef) {
            loops = NUM2INT(vals[0]);
        }

        if (vals[1] != Qundef) {
            fade_ms = NUM2INT(vals[1]);
        }
    }

    int result;
    if (fade_ms > 0) {
        result = Mix_FadeInMusic(m->music, loops, fade_ms);
    } else {
        result = Mix_PlayMusic(m->music, loops);
    }
    if (result < 0) {
        rb_raise(rb_eRuntimeError, "Mix_PlayMusic failed: %s", Mix_GetError());
    }

    return Qnil;
}
GitHub

playing?

Whether music is currently playing.

Returns Boolean

View source ▼ 
static VALUE
music_playing_p(VALUE self)
{
    get_music(self);
    return Mix_PlayingMusic() ? Qtrue : Qfalse;
}
GitHub

resume

Resume paused music.

Returns nil

View source ▼ 
static VALUE
music_resume(VALUE self)
{
    get_music(self);
    Mix_ResumeMusic();
    return Qnil;
}
GitHub

stop

Stop music playback.

Returns nil

View source ▼ 
static VALUE
music_stop(VALUE self)
{
    get_music(self); /* validate not destroyed */
    Mix_HaltMusic();
    return Qnil;
}
GitHub

volume

Current music volume.

Returns Integer — 0–128

View source ▼ 
static VALUE
music_get_volume(VALUE self)
{
    get_music(self);
    return INT2NUM(Mix_VolumeMusic(-1));
}
GitHub

volume=(vol)

Set the music volume.

Parameters
  • vol Integer — 0–128

Returns Integer

View source ▼ 
static VALUE
music_set_volume(VALUE self, VALUE vol)
{
    get_music(self);
    int v = NUM2INT(vol);
    if (v < 0) v = 0;
    if (v > MIX_MAX_VOLUME) v = MIX_MAX_VOLUME;
    Mix_VolumeMusic(v);
    return vol;
}
GitHub