Byte Engine Docs

Audio

Look up the output format, the sample formats Byte Engine accepts, the audio graph functions and their limits, playback timing, and the sample pool.

Audio mixes procedural generators and audio graphs into the platform device. This page specifies what the device receives, which sample files bake, what an audio graph can express, and the capacities of the audio worker and the sample pool.

Output

PropertyValue
Device request48 kHz, one channel, 16-bit. The device may answer with a 16-bit or 32-bit float stream, mono or stereo; a stereo stream receives the mono mix on both channels.
MixingEvery source adds into one 32-bit float mono buffer per device period, then the buffer converts to the stream format.
No deviceWhen the device can't open, the engine logs a warning and plays nothing. Headless builds compile and validate graphs but never play them.
UnderrunsCounted by the device and reported in the log.

Sources

A generator is a procedural source that renders samples on request at the output sample rate and reports when it's done. Generators add into the mix and end when they report done.

An audio graph is a baked sample with processing around it. An application publishes a graph on the world; the graph compiles on the publishing thread and plays once its sample is resident. Deleting the graph's handle stops it. Publishing a new graph on an existing handle replaces the old one.

The audio worker holds at most 64 graphs that are playing or loading; a graph past that limit is dropped and reported in the log.

Sample formats

Baking accepts these files as Audio resources:

SourceAcceptedStored
WAVRIFF PCM, or extensible with a PCM subformat; 1 or 2 channels; 8, 16, 24, or 32 bits per sample; any positive sample rate.The interleaved little-endian PCM as authored.
OGG Vorbis1 or 2 channels; the stream's sample rate.16-bit PCM.

A file with another channel count, a zero sample rate, no frames, or a payload that isn't a whole number of frames fails to bake.

At play time, a stereo sample mixes down to mono as an equal average while it decodes, and plays at the device rate with exact rational resampling and linear interpolation. A looping sample interpolates across the wrap; a sample played once holds its last frame, then finishes.

Audio graph functions

A graph is a tree of functions that ends in one output. Each function below is a node; a function that takes a graph takes it as its input.

FunctionParameterEffect
sampleA non-empty Audio resource IDPlays the sample once.
round_robinOne or more graphsEach time the graph is published, plays the next input in order. A single input is used directly.
randomOne or more graphsEach time the graph is published, plays one input, never the same input twice in a row.
loopA graphPlays the input until the handle is deleted.
gainA finite factor of zero or moreMultiplies the signal. A gain of zero mutes the graph; a gain of one is removed.
varispeedA finite rate in [0.25, 4.0]Changes speed and pitch together. A rate of one is removed.
pitch_shiftA finite ratio in [0.5, 2.0]Changes pitch and keeps the duration. A ratio of one is removed.
customA function of the block time and the sample blockRuns on the audio worker for every block. It must not allocate, block, lock, or perform I/O.

A graph is valid when it has at least one node and at most 64 after the removals above, its output and every input belong to the graph, every node reaches the output, it has no cycle, every selector has an input, and no selectable path holds more than one varispeed or more than one pitch_shift. An invalid graph is rejected when it's published.

Each publication plays exactly one sample, the one the selectors chose, with the processors between it and the output in order. Adjacent gains combine into one. A selector's position advances only when the publication succeeds, and a nested selector advances only on the path that was chosen.

Playback timing

Every graph playback has its own timeline that starts at zero when the graph begins to render and counts rendered samples at the output rate, including the tail that processors drain after the sample ends. A custom function receives the index of the first sample of its block and the output sample rate. A graph is finished when its sample has ended and the drain tail has played out; a muted looping graph never finishes on its own.

Pitch shiftValue
Window1,024 samples, Hann
Hop128 samples
Added tail1,024 samples, about 21 ms at 48 kHz

Sample pool

Decoded samples live in one arena sized by a byte budget.

PropertyValue
Default budget64 MiB
Slots64
EvictionLeast recently used samples that no graph holds.
Sample larger than the budgetThe graph fails to load.
No roomThe load waits and retries when a sample is released.

Limits

LimitValue
Nodes in a graph64
Graphs playing or loading64
Decoded sample channels1 or 2, mixed to 1
Master gainNone. Set gain per graph.

Rust API

On this page