Sound_Player

Tells the player where the listener is, so sounds with a position can be panned and softened by distance.

update_listener(.{0, 1.7, 0}, .{0, 0, 0, 1});

The loudness a stream should have for the listener's position, from the master volume, the stream's own scales and distance.

Sets the volume of everything the player plays, as a factor of the original: 1 is unchanged, 0 is silent.

Reads a sound file. The result has loaded set when it worked.

sound := load_audio_file("music.ogg");
if !sound.loaded return;

Reads a sound from memory. The result has loaded set when it worked.

sound := load_audio_data("junk", "this is not audio");
assert(!sound.loaded);

Stops every stream that plays data, frees the bytes it was loaded from and clears it, so that nothing points into it any more.

samples: [64] s16;
data := Sound_Data.{ loaded = true, type = .LINEAR_SAMPLE_ARRAY, samples = samples.data, nsamples_times_nchannels = samples.count };
data.buffer = copy_string("stands in for the file bytes");

release_sound_data(*data);
assert(!data.loaded && data.buffer.count == 0);

Swaps in a new sound for data without moving it: the streams playing the old one are stopped, its bytes are freed and replacement takes its place. Anything that holds the *Sound_Data keeps a valid pointer and gets the new sound from the next make_stream on. This is how to hot-reload a sound.

first := load_audio_data("first", copy_string("not audio"));
assert(!first.loaded); // too short to be a sound; its bytes are still ours
free(first.buffer.data);

samples: [64] s16;
data := Sound_Data.{ loaded = true, type = .LINEAR_SAMPLE_ARRAY, samples = samples.data, nsamples_times_nchannels = samples.count };
data.buffer = copy_string("old bytes");

louder: [64] s16;
louder[0] = 100;
replacement := Sound_Data.{ loaded = true, type = .LINEAR_SAMPLE_ARRAY, samples = louder.data, nsamples_times_nchannels = louder.count };
replacement.buffer = copy_string("new bytes");

assert(replace_sound_data(*data, replacement));
assert(data.samples == louder.data && data.buffer == "new bytes");
release_sound_data(*data);

The audio outputs the system offers.

for get_devices() print("%\n", it.name);

The sampling rate of the output in hertz, or 0 before sound_player_init.

assert(get_audio_sampling_rate() == 0);

Opens the audio output and starts mixing. Returns false if there is no usable device. Calling it again after it worked does nothing.

if !sound_player_init(.{}) print("no audio\n");

Stops every stream, closes the output and frees what the player holds. sound_player_init can be called again after it.

Makes a stream to play data. Returns null when the sound is not loaded or has more channels than a stream can take.

samples: [64] s16;
sound := Sound_Data.{ loaded = true, type = .LINEAR_SAMPLE_ARRAY, nchannels = 1, samples = samples.data, nsamples_times_nchannels = samples.count };

stream := make_stream(*sound, .UI);
assert(stream != null);

not_loaded: Sound_Data;
assert(make_stream(*not_loaded) == null);

Gives stream to the player, which plays it from the start and frees it once it ends. Do nothing before sound_player_init.

The playing stream with this entity_id and manager_id, or null. Set those on a stream to find it later.

sound := load_audio_file("jump.wav");
stream := make_stream(*sound);
stream.entity_id = 7;
start_playing(stream);
assert(find(7, 0) == stream);

Stops every stream whose entity_id is id, with no fade.

stop_stream_abruptly(7);

Stops every stream that has this manager_id, with no fade.

Works out how fast a stream plays from its sound's sampling rate, the output rate and rate_scale.

Makes a stream loop, or stops it from looping.

sound := load_audio_file("jump.wav");
stream := make_stream(*sound, .MUSIC);
set_repeating(stream, true);
start_playing(stream);

The first half of update: marks streams that have reached their end. Call it and post_entity_update instead of update when you need to touch streams between the two.

The second half of update: ends streams that were not kept alive, and refreshes the pitch and panning of the rest. dt is the seconds since the last frame.

Advances the player by one frame. Call it once per frame. dt is the seconds since the last call; leave it out to have the player measure it.

while true {
    update();
    // ... draw and handle input ...
}

Mixes the next stretch of every stream into the output buffer. The audio thread calls it.

Fills the output with the audio thread's mixing step, or with the main thread's when update_from_a_thread is off.

The body of the audio thread.

A speaker of the output, as laid out by the player.

Where a channel of a sound belongs in the room. load_audio_file sets these from the channel count; change Sound_Data.source_directions before starting a stream to override them.

A group of sounds. A stream's category sets its default flags (a .MUSIC stream is music).

A loaded sound. loaded says whether loading worked. volume_scale scales every stream of it, and buffer holds the bytes the sound was read from. Make a Sound_Stream from it to play it.

samples: [8] s16;
sound := Sound_Data.{ loaded = true, type = .LINEAR_SAMPLE_ARRAY, nchannels = 1, samples = samples.data, nsamples_times_nchannels = samples.count };
assert(sound.sampling_rate == 44100);

One playing instance of a sound. make_stream creates it and start_playing hands it to the player, which owns it from then on. Set user_volume_scale, rate_scale, position and the user_flags before starting it, or any time while it plays.

sound := load_audio_file("jump.wav");
stream := make_stream(*sound);
stream.user_volume_scale = 0.5;
stream.rate_scale = 1.2;  // a little higher in pitch
start_playing(stream);

What the audio backend settled on: the channel count and the output sampling rate.

An audio output that get_devices found.

Settings for sound_player_init. The default works: it mixes on its own thread and keeps sounds playing when the window loses focus only if audible_when_window_is_not_in_focus is set. release_asset is called when a stream ends, so the program can free what the stream used.

config: Sound_Player_Config;
config.update_from_a_thread = false;  // mix inside update() instead
config.audible_when_window_is_not_in_focus = true;
assert(sound_player_init(config));