Calibration

Calibration measures how well SampleToNES reconstructs a fixed set of reference sounds. It converts each sound with each spectrum method, scores every result against the original, and writes a page you listen to the results on.

Use it to:

• See which spectrum method suits which kind of sound.
• Check whether a new version or a changed setting reconstructs better or worse.
• Hear what a score means before trusting it.

From a copy of the source code:

make calibration

In an installed copy:

sampletones calibration

The run takes a while, because it reconstructs every reference sound once for each variant. A first run also builds the instruction libraries it needs.

With no options, the run measures the program's default settings under the packaged suite:

• Every spectrum method: fft, logfft and cqt.
• The channels pulse 1, triangle and noise.
• Every other setting at its default value.

A variant is one configuration the run measured, named after its distinguishing settings. For example, cqt-pe1 is the cqt method at perceptual exponent 1. A render is one reference sound as a variant reconstructed it.

The reference sounds are identical on every run, so figures from different versions compare.

The results go into a new folder inside the calibration folder of your SampleToNES folder. The folder is named by the date and time the run started, for example run-20260915-124501. When the run ends, the command prints a link to the report and opens the listening page.

The audio is FLAC, which is lossless and about a third of the size the same audio takes as WAV. A default run writes about 35 MB. A run of four channels writes more, because a reconstruction of four channels is cut into fourteen combinations and one of three channels into six.

Every run writes index.html and opens it when it ends. The page has one row per reference sound and one column per variant. Each cell has:

• play, which sounds the whole reconstruction from its beginning.
• The score under it. The line below the score says how much of the distance between silence and the recording the reconstruction covers, or past silence where silence scores closer than the reconstruction does.
• One bar per channel, showing the frames that channel plays, in the channel's own color.

Beside each bar, S plays that channel alone and M plays every other channel. You hear what one channel contributes and what the rest sound like without it. Both are separate recordings the run wrote, so switching between them is exact.

Space pauses and resumes, ← and → move across one sound's versions, and ↑ and ↓ move to another sound.

The page is drawn in the program's own colors. --palette NAME draws it in another of the program's palettes, and --no-open leaves it closed and prints its link alone.

A render plays at the same level as its recording, so a quieter render sounds quieter. You can also play any file in the run folder in an audio player of your own.

Beside each render, a JSON file of the same name has:

• judgments: every referee's score for the render, with the readings behind it.
• silence: what complete silence would score against the same recording.
• timelines: one character per frame for each channel, 1 where that channel plays.

A render that scores worse than silence is a sign to listen before trusting the number.

A referee is a method that scores a reconstruction against its original: zero for identical signals, higher for a larger audible difference. How it judges describes them.

report.md has one section per referee. Each section starts with a table: one row per variant, one column per category of reference sound, and the overall mean last. Lower is better.

The mr-loudness-dB section adds a table for each of its readings:

• missing: content the original has and the reconstruction lacks. A high value sounds dull.
• added: content the reconstruction brings in. A high value sounds buzzy or noisy.
• level: how much louder the reconstruction plays than the original, in decibels. A negative value means quieter.

The score is missing plus added. level is reported separately.

Each option replaces one part of the default run. The rest stays as the suite sets it.

Lists are comma separated. Several lists multiply: --methods fft,cqt --perceptual-exponents 0.5,1 measures four variants, and the run takes about four times as long as one variant.

From a copy of the source code, put uv run in front: uv run sampletones calibration --methods cqt.

1. Run calibration into a folder of its own, for example -o before.
2. Change what you want to compare: install another version, or pass another --config.
3. Run calibration again into another folder, for example -o after.
4. Build one page over both:

sampletones calibration --board before after -o comparison

The page holds one tab per variant, with the runs side by side and the change between them in the last column. It carries the audio it plays, so the comparison folder moves as one piece. Without -o the page lands in a timestamped folder under calibration/pages.

--board reads finished runs and measures nothing, so it takes none of the options that measure.

To compare two versions of the source code, run each version from its own copy of the repository, for example a git worktree, into its own folder.

The reference sounds

The reference sounds are short synthetic clips, generated the same way on every run. Each category tests one kind of decision:

The referees

Referees score in their own way, separate from the reconstruction's own scoring, so a comparison stays fair when that scoring is what changed.

Both built-in referees split each signal into bands spaced the way hearing spaces pitch, at several time resolutions, and compare the energy in each band in decibels.

• mr-auditory-dB averages the difference over every band equally. It reads the balance of tone against noise across the whole spectrum. An empty band counts as much as a full one, so a clip that adds noise to a lone tone scores worse than silence. The report lists this referee first.
• mr-loudness-dB weighs each band by how loud it plays, so the parts you hear carry the score and silent bands barely count. It first brings the reconstruction to the original's level and reports the level difference on its own. Silence scores worst, and a clip with the right tone and some added noise scores between.
• zimtohrli is a model of human hearing from Google. It joins the other two where it is installed. See dependencies.