README
¶
algo-tom
A physically modelled double-headed tom, and the objective it is fitted with.
Two modal banks coupled through a lumped air cavity, Berger tension nonlinearity, Hunt–Crossley contact and a three-band stochastic attack layer — plus the nine-term perceptual distance that scores a candidate drum against a recording, the feature extraction it is built on, and the tooling that measures how far either can be trusted.
Live demo → — the model running in the browser next to the objective, with the matching drawn rather than described.
What this is
This started as one experimental voice inside
algo-drum, an algorithmic drum machine,
and outgrew it. What lives here is a research line with its own measurement
discipline: an evidence record in docs/, a committed calibration fixture that
every structural change is diffed against, a set of adoption gates measured from
the objective's own reproducibility, and a working paper.
algo-drum still ships the voice, and now consumes this module to do it.
Quick start
just # list every recipe
just dev # build the WASM, then run the demo's dev server
just test # the Go suite
just ci # the full local gate — run this before pushing
The demo needs bun; the offline tools need only Go 1.25.
What is in here
| Package | |
|---|---|
physical/ |
The model: modal banks, the two-head + cavity + Berger real-time solve, the attack layer, a versioned SI config, and an offline continuous-time reference solve |
physical/match/ |
The objective: feature extraction, decay fitting on a stationary noise floor, the nine-term distance, and subband ESPRIT for checking the fast estimator |
physical/analysis/ |
Offline report and suite generation; backs the committed calibration fixture |
physical/series/ |
Rank correlation over take series |
tomparams/ |
The normalized-knob → SI mapping. The only correct spelling of it — algo-drum imports this rather than keeping its own |
wavio/ |
Mono 16-bit PCM WAV export |
| Command | |
|---|---|
cmd/fit-physical |
Fits the parameter bank to one or more recordings (Mayfly) |
cmd/measure-objective |
Measures the objective's own reproducibility floor and proposes the gates the weights invert |
cmd/measure-tom |
Turns recordings into the committable tables the protocol asks for |
cmd/compare-fits |
Asks of the search what measure-objective asks of the objective: does it agree with itself? |
cmd/analyze-physical |
The analysis report and the CI-diffed calibration fixture |
cmd/render-physical |
Renders the voice to a WAV for offline auditioning |
cmd/wasm |
The AlgoTom browser API |
cmd/gen-tomparams |
Generates the demo's mirror of the parameter table |
Three things worth knowing before quoting a number
A total is a property of a weight set. Every weight is the reciprocal of a measured adoption gate, so a term divided by its gate is its additive contribution and the nine ratios sum to the total. A term below 1.0 is inside the objective's own measured noise and has not moved in any sense that means anything — and two totals scored under different gate sets are not comparable. This repository has made that mistake, which is why reports carry a fingerprint of the weights they were scored under.
A free parameter pinned against a stop is a bound, not a fit. fit-physical
and compare-fits both flag it. Read it as evidence that the shipped range
excludes the optimum.
A fitted per-take velocity is not a measurement. Two searches over the same sixteen takes returned velocity vectors correlating ρ = +0.15 with each other. Velocity is a nuisance parameter this objective does not identify. What does carry the reference series' dynamic ramp is the recordings themselves — crest factor over the first 50 ms runs ρ = +0.91 against the file index.
docs/physical-objective-validation.md is the evidence record, and it carries the results that have been superseded as well as the ones that stand. Read it before quoting any fit number or gate.
Versioning
v0.x. Nothing here is behind internal/, because algo-drum needs physical
and tomparams and hiding match would mean only this module's own commands
could ever score anything. Treat every exported name as movable until v1.
Licence
MIT, except the committed reference recordings under reference/, which are
CC BY 4.0 — see reference/CREDITS.md for provenance and
attribution.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
analyze-physical
command
Command analyze-physical emits deterministic calibration metrics for the experimental physical drum without involving the browser audio pipeline.
|
Command analyze-physical emits deterministic calibration metrics for the experimental physical drum without involving the browser audio pipeline. |
|
compare-fits
command
Command compare-fits asks of the *search* the question cmd/measure-objective asks of the objective: does it agree with itself?
|
Command compare-fits asks of the *search* the question cmd/measure-objective asks of the objective: does it agree with itself? |
|
fit-physical
command
Command fit-physical searches the physical Tom's parameter bank for the settings that come closest to a recorded hit.
|
Command fit-physical searches the physical Tom's parameter bank for the settings that come closest to a recorded hit. |
|
gen-tomparams
command
Command gen-tomparams writes the TypeScript mirror of the physical Tom's parameter table.
|
Command gen-tomparams writes the TypeScript mirror of the physical Tom's parameter table. |
|
measure-objective
command
Command measure-objective measures the fitting objective's disagreement with itself, and derives the adoption gates from it.
|
Command measure-objective measures the fitting objective's disagreement with itself, and derives the adoption gates from it. |
|
measure-tom
command
Command measure-tom turns recordings of a real drum into the derived tables docs/physical-measurement-protocol.md asks for: partial frequencies with levels, their ratios to the fundamental, per-partial T60 and the damping ratio that follows from it, the scatter across repeated hits, and — given a resonant-head-off and a resonant-head-on take — the (0,1) doublet that Cavity.StiffnessScale is fitted to.
|
Command measure-tom turns recordings of a real drum into the derived tables docs/physical-measurement-protocol.md asks for: partial frequencies with levels, their ratios to the fundamental, per-partial T60 and the damping ratio that follows from it, the scatter across repeated hits, and — given a resonant-head-off and a resonant-head-on take — the (0,1) doublet that Cavity.StiffnessScale is fitted to. |
|
render-physical
command
Command render-physical renders the experimental double-headed physical tom through its batter-side pickup to a mono 16-bit PCM WAV file for offline auditioning.
|
Command render-physical renders the experimental double-headed physical tom through its batter-side pickup to a mono 16-bit PCM WAV file for offline auditioning. |
|
wasm
command
Command wasm registers the AlgoTom API on the worker's global scope.
|
Command wasm registers the AlgoTom API on the worker's global scope. |
|
Package physical implements reduced physical models of acoustic drums.
|
Package physical implements reduced physical models of acoustic drums. |
|
analysis
Package analysis provides offline calibration and regression measurements for the real-time physical drum model.
|
Package analysis provides offline calibration and regression measurements for the real-time physical drum model. |
|
match
Package match turns a drum hit — recorded or rendered — into a small set of perceptual features, and scores two of them against each other.
|
Package match turns a drum hit — recorded or rendered — into a small set of perceptual features, and scores two of them against each other. |
|
series
Package series relates the measurements of one take to the measurements of the others.
|
Package series relates the measurements of one take to the measurements of the others. |
|
Package tomparams is the normalized knob bank for the physical Tom, and the mapping from it to the SI-valued configuration the model consumes.
|
Package tomparams is the normalized knob bank for the physical Tom, and the mapping from it to the SI-valued configuration the model consumes. |
|
Package wavio writes mono 16-bit PCM WAV files for offline auditioning.
|
Package wavio writes mono 16-bit PCM WAV files for offline auditioning. |