Skip to content
Get in touch

A mix is a few dozen numbers

Design notes on the audio package: a mix held as plain data, one renderer for desktop, phone and small boards and a second for the browser, a loudness meter to the broadcast standard, placement on headphones from a measured head. What it depends on, what was measured, what it does not do.

By Bogdan Vladoiu, 2026-11-18

This is a design document for the audio package of the ComputeShack codebase, written when the mixer settled in November 2026. It records what the package is, which other packages it is built from, what was measured, where it stops and what it borrows. The source is public in the same repository as the machine package: git clone https://computeshack.com/git/computeshack.git.

Scope

Open a game whose sound you like, go to its pause menu and drag the music slider. A number changed. That is most of what a mix is: a few dozen numbers somebody tuned for months. Music at minus 8. Music drops 9 dB when someone speaks. Nothing goes over minus 1.

In most audio code those numbers live inside objects: to change one you find a node or a bus handle, hold on to it, and change it on the right thread at the right moment. This package keeps the numbers as the numbers. It is a mixer, a device seam and a small player. It is not a plugin host and not an audio engine for a game.

Terms

Term Meaning
Mixer A description of a mix and the signal code that renders it. It has a name, never a handle.
Strip One channel of the mix: a source or a bus. A strip is a key prefix (music.gain), not a class.
Props The map that holds the whole mix: music.gain = -8, master.limit = -1.
Plan What the props compile to: a finished, immutable set of buffers and coefficients.
Quantum The block the mixer renders: 128 samples, 2.667 ms at 48 kHz.
Output An open device rendering one mixer.

Components

The mix as data

Mixer("game") {
    strip("music", gain = -8f)
    strip("voice")
    duck("music", key = "voice", depth = 9f)
    limit(ceiling = -1f)
    commit()
}

Underneath, that is a map. Compressor, duck, limiter, sends and groups are functions with defaulted arguments over those keys. Nothing is heard until commit(), which compiles the props into a plan off the audio thread and swaps it in between two quanta.

Three things follow from the mix being a name and some rows. It fits in a message, so setting music.gain from another machine is the same change as the line of code. It can be stored and restored with one call. And a second renderer needs no class hierarchy ported, only the keys read.

The cost is stated in the package's notes: a typo in a key is silent. Compiling warns about routing that leads nowhere, and the tool front refuses a row that is not part of a mix.

The renderers

On the JVM, Android and every native target the same Kotlin signal code renders the plan. In a browser the same description becomes Web Audio nodes. In the game it maps onto the engine's own buses: four strips into a master, a duck keyed by voice, a limiter.

The audio thread belongs to the platform. It calls one function and that function allocates nothing, takes no lock, starts nothing and logs nothing. Two callers cannot leave a mix half changed, because the thread only ever sees a finished plan.

The output

A device is opened by name on a mixer and reports its own latency. Where a platform has a callback it is used; where it has none, a pump writes blocks. The native output is miniaudio.

Loudness

The meter follows ITU-R BS.1770, with the standard's own filter formulas. It reads momentary and integrated loudness on any strip, after the fader or before it. The same meter runs offline over files.

Placement and the direct path

A strip can be placed around the listener: degrees to the side and above, and a distance. By default that is a set of cheap cues for speakers. For headphones it can render through a measured head, kept as data in the package, so nothing is linked or learned at runtime.

A separate small model answers how much of a sound gets from a source to the listener through air, walls and floors, per frequency band. Valve's Steam Audio was the reference it was checked against: its documented material figures are used and none of its code.

The player

A sixteen-voice sequencer, a sampler, a one-line pattern notation and a writer of standard MIDI files. It was extracted from a terminal tool that played real pieces, not designed ahead of them.

The tool front

The package is also an interface on the machine it runs on: list mixers, read one, set rows, list outputs, open one, close one. Six tools, the same words a person uses in code. A model small enough to run on a laptop set a level, opened a device and re-routed a strip through them without inventing a function that was not there. How it did, task by task, is in the package's notes.

Dependencies

Package What the audio package takes from it
execution The places work runs. Every write to a mixer goes through one band, which is the exclusion: there are no locks and no atomics.
time The named durations used for attack, release and hold, and the clock.
store, fs, io Keeping a mix in a table or a file, and its wire form.
machine The daemon recipe, so a mixer on another machine is operated with the same words.
errors, log One error channel and one log per process.

Measurements

Taken in November 2026 on a workstation and on a Jetson Orin Nano. The full tables are in audio_benchmarks.md in the package.

What Result
A game-sized desk (four buses, a duck, a limiter), one quantum, workstation 6.3 µs native, 3.4 µs on the JVM, of a budget of 2,667
The same on the Jetson 24.6 µs
Sixteen strips with filters, three EQ bands, a compressor and a send each, plus buses 100 µs, 3.75% of the budget
Memory allocated while rendering none over 100,000 quanta
A gain change, from commit() to the new plan in place median 2.4 ms, worst of thirty 5.1 ms
Loudness of the standard's reference tones (-20.00 and -23.01 LUFS expected) -19.95 and -23.05 integrated
Loudness of 2,531 audio files of a game all measured in 53 s; one music loop stood 11 LU above the rest
A scripted firefight on the Jetson, worst single quantum 1,399 µs, 52% of the budget, about one quantum in ten thousand

Known limits

  • Stereo only. No 5.1 or 7.1 output.
  • The limiter has no lookahead.
  • In the browser there is no reverb, no loudness reading and no placement, and only the first duck on a strip applies.
  • Removing a mixer from the pool does not close an output that is open on it.
  • The measured head costs about eleven times the cheap cues, so it is for bakes and a handful of live sources.
  • macOS builds and links; its device has not been measured. iOS is written and not built.
  • A source that throws ends the pump. The guard that would catch it is not allowed on the audio thread.

What it borrows

  • The measured head is SADIE II subject 002 (University of York), in the third-order form Resonance Audio distributes, both under the Apache License 2.0.
  • The reverb's tunings are Freeverb's, which is in the public domain.
  • The material and air figures are Steam Audio's documented values.
  • The loudness weighting is ITU-R BS.1770's; the filters are the Audio EQ Cookbook's.
  • The native output is miniaudio, public domain or MIT No Attribution.

Next

The game's own mix is to be rendered from the same description the benches use, so that a level set on a bench is the level heard in the game. Loudness and placement are to reach the browser renderer.

ComputeShack

Small, good solutions.

[email protected]

Privacy policy · © 2026 ComputeShack