playbit / docs

Audio

#include <playbit/audio.h>

PBAudio

typedef struct {
    PBSysHandle handle;
} PBAudio;

PBAudioBuffer

typedef struct {
    PBSysAudioBuffer id;
} PBAudioBuffer;

PBAudioSound

typedef struct {
    PBSysAudioSound id;
} PBAudioSound;

PBAudioMain

PBAudio PBAudioMain();

Call this to get the main audio handle. Also calls PBAudioInit exactly once if it has not yet been called.

PBAudioInit

bool PBAudioInit();

Inits the audio output backend for sound playback (globally).

PBAudioSetVolume

void PBAudioSetVolume(PBAudio audio,
                      f32     volume);

Sets the global volume of the sound mixer.

PBAudioBufferCreate

PBAudioBuffer PBAudioBufferCreate(PBAudio     audio,
                                  const void* data,
                                  usize       dataSize,
                                  u32         numChannels,
                                  u32         sampleRate,
                                  u32         totalSampleCount);

Creates an audio buffer from a interleaved 2-channel f32 buffer at 44100 hz. At the present moment, that is the only format that is supported. This function will be extended in the future to support more formats.

PBAudioBufferCreateFromFile

PBAudioBuffer PBAudioBufferCreateFromFile(PBAudio     audio,
                                          const void* data,
                                          usize       dataSize);

PBAudioBufferDestroy

PBSysErr PBAudioBufferDestroy(PBAudio       audio,
                              PBAudioBuffer buffer);

PBAudioBufferPlay

PBAudioSound PBAudioBufferPlay(PBAudio       audio,
                               PBAudioBuffer buffer);

Starts playing an instance of an audio buffer at 1x speed.

PBAudioBufferPlayAfter

PBAudioSound PBAudioBufferPlayAfter(PBAudio       audio,
                                    PBAudioBuffer buffer,
                                    PBAudioSound  playingSound);

PBAudioBufferUpload

PBSysErr PBAudioBufferUpload(PBAudio       audio,
                             PBAudioBuffer buffer,
                             const void*   data,
                             usize         dataSize,
                             u32           numChannels,
                             u32           sampleRate,
                             u32           totalSampleCount);

Replaces the sample data of an existing, no-longer-playing audio buffer in place, without allocating a new buffer. Intended for a small fixed ring of buffers used to stream audio, where each buffer is refilled and re-queued (via PBAudioBufferPlayAfter) only after PBAudioSoundIsPlaying reports its previous sound has finished.

It is a caller error to upload into a buffer that a currently-playing (or not-yet-finished, queued) sound still references.

PBAudioSoundResume

PBSysErr PBAudioSoundResume(PBAudio      audio,
                            PBAudioSound sound,
                            bool         loop);

Resumes a paused (or still-playing) sound. If loop is true, playback restarts from the beginning when the end of the sound is reached; otherwise playback stops at the end. Fails if the sound has ended (its handle has expired) — start a new instance with PBAudioBufferPlay in that case.

PBAudioSoundPause

PBSysErr PBAudioSoundPause(PBAudio      audio,
                           PBAudioSound sound);

Pauses a playing sound. Resume with PBAudioSoundResume.

PBAudioSoundTell

f32 PBAudioSoundTell(PBAudio      audio,
                     PBAudioSound sound);

Returns the current playback position, normalized to [0.0-1.0]. 1.0 means the sound ended (an expired sound handle also reads as 1.0).

PBAudioSoundSeek

void PBAudioSoundSeek(PBAudio      audio,
                      PBAudioSound sound,
                      f32          position);

Sets the playback position, normalized and clamped to [0.0-1.0]. Seeking a sound that already ended is a no-op.

PBAudioSoundGetPosition

u64 PBAudioSoundGetPosition(PBAudio      audio,
                            PBAudioSound sound);

Returns the current playback position, in sample frames, of sound within its buffer. This reflects what the mixer has actually consumed as of the last audio callback, i.e. what's truly audible right now -- not merely queued or rendered ahead of time.

Returns 0 if sound is invalid or hasn't started playing yet.

PBAudioSoundIsPlaying

bool PBAudioSoundIsPlaying(PBAudio      audio,
                           PBAudioSound sound);

Returns true if sound is the one currently being mixed into the output right now, according to the mixer itself -- not a locally-predicted end time. A sound that hasn't started yet (waiting on a PBAudioBufferPlayAfter predecessor) or that has already finished playing both report false.

Intended for driving gapless streaming playback: poll this instead of guessing when a queued buffer will finish, and recycle/refill it (see PBAudioBufferUpload) once it reports false.