Teek API Documentation

Teek::SDL2::Sound Class

A short audio sample loaded from a WAV file.

Sound wraps SDL2_mixer’s Mix_Chunk for fire-and-forget playback of sound effects. The audio mixer is initialized automatically on first use.

Inherits: Object

Instance Methods ↑

destroy

Free the underlying audio data. Further method calls will raise.

Returns nil

View source ▼ 
static VALUE
sound_destroy(VALUE self)
{
    struct sdl2_sound *s;
    TypedData_Get_Struct(self, struct sdl2_sound, &sound_type, s);
    if (!s->destroyed && s->chunk) {
        Mix_FreeChunk(s->chunk);
        s->chunk = NULL;
        s->destroyed = 1;
    }
    return Qnil;
}
GitHub

destroyed?

Whether the sound has been destroyed.

Returns Boolean

View source ▼ 
static VALUE
sound_destroyed_p(VALUE self)
{
    struct sdl2_sound *s;
    TypedData_Get_Struct(self, struct sdl2_sound, &sound_type, s);
    return s->destroyed ? Qtrue : Qfalse;
}
GitHub

initialize(path)

Load a sound effect from a file. Initializes the audio mixer automatically.

Parameters
  • path String — path to a WAV, OGG, or other supported audio file
View source ▼ 
static VALUE
sound_initialize(VALUE self, VALUE path)
{
    struct sdl2_sound *s;
    TypedData_Get_Struct(self, struct sdl2_sound, &sound_type, s);

    ensure_mixer_init();

    StringValue(path);
    Mix_Chunk *chunk = Mix_LoadWAV(StringValueCStr(path));
    if (!chunk) {
        rb_raise(rb_eRuntimeError, "Mix_LoadWAV failed: %s", Mix_GetError());
    }

    s->chunk = chunk;
    return self;
}
GitHub

play(volume: nil, loops: 0, fade_ms: 0)

Play the sound on the next available channel.

Parameters
  • volume Integer, nil — playback volume (0–128, nil = current)
  • loops Integer — 0 = play once, N = play N extra times, -1 = loop forever
  • fade_ms Integer — fade-in duration in milliseconds (0 = no fade)

Returns Integer — channel number used (pass to SDL2.halt to stop)

View source ▼ 
static VALUE
sound_play(int argc, VALUE *argv, VALUE self)
{
    struct sdl2_sound *s = get_sound(self);
    int loops = 0;
    int fade_ms = 0;

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

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

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

        if (vals[0] != Qundef) {
            int vol = NUM2INT(vals[0]);
            if (vol < 0) vol = 0;
            if (vol > MIX_MAX_VOLUME) vol = MIX_MAX_VOLUME;
            Mix_VolumeChunk(s->chunk, vol);
        }

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

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

    int channel;
    if (fade_ms > 0) {
        channel = Mix_FadeInChannel(-1, s->chunk, loops, fade_ms);
    } else {
        channel = Mix_PlayChannel(-1, s->chunk, loops);
    }
    if (channel < 0) {
        rb_raise(rb_eRuntimeError, "Mix_PlayChannel failed: %s", Mix_GetError());
    }

    return INT2NUM(channel);
}
GitHub

volume

Current volume for this sound.

Returns Integer — 0–128

View source ▼ 
static VALUE
sound_get_volume(VALUE self)
{
    struct sdl2_sound *s = get_sound(self);
    /* Passing -1 queries without changing */
    return INT2NUM(Mix_VolumeChunk(s->chunk, -1));
}
GitHub

volume=(vol)

Set the volume for this sound.

Parameters
  • vol Integer — 0–128

Returns Integer

View source ▼ 
static VALUE
sound_set_volume(VALUE self, VALUE vol)
{
    struct sdl2_sound *s = get_sound(self);
    int v = NUM2INT(vol);
    if (v < 0) v = 0;
    if (v > MIX_MAX_VOLUME) v = MIX_MAX_VOLUME;
    Mix_VolumeChunk(s->chunk, v);
    return vol;
}
GitHub