preframr-audio

SID audio rendering, render-fidelity gates, and audio fingerprinting for the preframr research codebase, built on pyresidfp. Published standalone so the audio path installs without the training stack.

This README is the API reference for the package and the reference for programming the SID through it: the chip-behavior facts the renderer and the fidelity gates rely on are each pinned by a unit test in tests/ (see SID programming facts).

Install

pip install preframr-audio

System dependencies: ALSA + libasound2 for the real-time driver (offline rendering to WAV/PCM works without ALSA).

Import contract

Everything public is re-exported from the package root (from preframr_audio import compare_renders). Resolution is lazy (PEP 562): import preframr_audio does not pull in pyresidfp/scipy — those load on first access of a render-backed symbol, so the render-free path (compare_renders, mel_features, …) works without them.

The SID register model

Registers are addressed 0..24 (MAX_REG = 24). Per voice v (0..2) the base is v * 7 (VOICE_REG_SIZE = 7):

Globals: 21 = filter cutoff lo (FC_LO_REG), 22 = cutoff hi, 23 = resonance/filter routing, 24 = mode/volume (MODE_VOL_REG). VOICE_CTRL_REG = {0: 4, 1: 11, 2: 18}; voice_of_reg(reg) maps a register to its owning voice (None for globals/markers). The 16-bit frequency is always (reg[v*7+1] << 8) | reg[v*7] — never read a lo or hi byte in isolation.

Input DataFrame and frame timing

The render entry points consume a prepared-for-audio DataFrame (produced by preframr_tokens.prepare_df_for_audio: literal reg/val writes plus marker rows, with a delay column in seconds). Two negative marker registers drive frame packetization:

• FRAME_REG = -128 — frame boundary; its delay carries the frame remainder.
• DELAY_REG = -127 — multi-frame gap (silence packets).

A PAL frame is 19656 clock cycles (~50.12 Hz) at clock_frequency = 985248; sidq(sid) returns seconds-per-cycle (1 / sid.clock_frequency). Each register write is clocked individually with its own delay_cycles dwell (FrameOp(reg, val, delay_cycles)) — per-write clocking is mandatory: collapsed timing (clock once per frame) masks write-placement effects that are audible on the chip (see the facts table). Negative delay_cycles offsets prior positive dwell in the same frame rather than being clamped (test_audio_driver.py::TestNegativeDelayCarry).

Render pipeline

prepared df ──df_to_packets──> FramePacket stream ──ResidWorker──> int16 PCM ──> sink
                                                       (pyresidfp)        WavSampleSink / SampleRing / ALSA / ASID

reg_start (default: max sustain, 50% PWM, volume 15) primes the chip before the first frame. mute_voices zeroes the listed voices' control output while keeping their oscillators running.

Real-time sinks (not part of the offline API, pragma: no cover): ResidAlsaDriver (PortAudio), AsidMidiDriver/AsidWorker (delta-encoded ASID SysEx over MIDI; only changed registers are sent per frame), AsidServer (receives ASID, renders on a local SID for round-trip validation), and play_via_aplay / play_via_wav subprocess players. The ASID codec itself is pure and tested: encode_asid_update({reg: val}) -> sysex_body, decode_asid_update(body) -> {reg: val}, bijective over all 25 registers.

AudioRenderBuffer(max_frames=200) is the thread-safe FIFO between producer and renderer: push_frame (blocks when full), pop_frame, and replace_frame(frame_id, ops) which edits a still-queued frame and returns False once the playhead has passed it.

Fidelity gates

Two levels, both rendering through the same pipeline:

Strict (per-frame RMS). compare_renders(a, b, sample_rate, tolerance=0.05, max_frame_drift=1) aligns by cross-correlation lag and compares per-PAL-frame relative RMS, returning a frozen AudioFidelityResult(passed, shape, diagnostic, lag_samples, worst_frame_rel_rms, n_frames_compared). shape classifies the divergence (PASS, DURATION_MISMATCH, FRAME_CADENCE_BREAK, INITIAL_STATE_DIVERGENCE, DRIFTING_DIVERGENCE, CONSTANT_DIVERGENCE, SAMPLE_RATE_MISMATCH, NO_INFO). per_frame_rel_rms returns the full per-frame timeline to pinpoint divergent frames; compare_renders_per_voice runs the gate over render_per_voice maps. dfs_render_equivalent(df_a, df_b) renders both dfs in memory and compares; assert_dfs_render_equivalent is the raising variant (renders via render_df_to_wav, which requires preframr-tokens for prepare_df_for_audio). Tolerance floor: FRAME_RMS_TOLERANCE = 0.05.

Perceptual. perceptual_distance(a, b, sample_rate, win_s=1.0) returns the worst-window distance plus the per-window array; per window the metric is a 32-band linear band-power log-envelope (band_power_features) plus scaled spectral_features. Linear bands (not mel) are deliberate: a sub-band-width detune (≤50 cents) is invisible, while waveform/filter/envelope/voice-drop changes are large — calibrated INERT/BAD separation ≥ 2× around PERCEPTUAL_DISTANCE_THRESHOLD = 0.257 (tests/test_perceptual_fidelity.py::test_separation_margin; reproduce with python -m preframr_audio.fidelity, the calibrate() entry point). dfs_perceptually_equivalent / assert_dfs_perceptually_equivalent are the df-level gate and raising variant, returning PerceptualFidelityResult.

Use the strict gate for must-be-inaudible rewrites (augmentation, tokenizer canonicalization A/B); use the perceptual gate for lossy-tier changes that may move samples but must not move the music.

Features and fingerprinting

features extractors are pure numpy, deterministic, fixed-length: mel_features (time-pooled log-mel mean+std, (2*n_mels,)), spectral_features (centroid, bandwidth, rolloff-95, ZCR, RMS), band_power_features (32 equal-width linear bands 0–8 kHz, pitch-tolerant), raw_pcm_features. Registry: FEATURE_FNS.

fingerprint_writes(test_writes, irq=19656, feature="mel", …) wraps raw (clock, reg, val) writes in canonical_scaffold (chip init + a default 3-voice triad + silence pre/post frames, irq stored in df.attrs), renders, and returns the feature vector. fingerprint_batch(sequences, n_workers=-1) parallelizes over a spawn pool and returns the stacked (N, dim) matrix (parallel == sequential within the chip's nondeterminism floor, test_fingerprint.py).

batch mirrors this for whole dfs: render_batch, verify_equivalent_batch, verify_perceptually_equivalent_batch — all order-preserving, workers return only the small result objects.

SID programming facts (backed by unit tests)

The renderer and every canonicalization decision in the tokenizer rest on the following chip behaviors, each pinned by a deterministic pyresidfp test in this repo. The test is the citation; if a fact needs revisiting, change the test.

Envelope (ADSR) mechanism — tests/test_gate_adsr_reference.py

The envelope rate prescaler is a free-running 15-bit LFSR compared for equality against the active nibble's rate period; every envelope step resets it. Consequences, each a test:

Write-liveness matrix — tests/test_adsr_write_liveness_matrix.py

Which ADSR nibble writes are audible in which envelope phase (a write is relocatable iff neither value-live nor phase-live):

Sustain hold is itself an equality compare: raising S above the clamped counter kills the note (test_raising_sustain_kills_the_note).

Release-write placement — tests/test_release_write_position.py

R-nibble writes are foldable to the note onset across a gate=1 span, never across gate=0: a live release tail re-rates audibly, and even over a provably dead gap the changed compare stalls the next attack. S is live, not relocatable.

Write order and audibility — tests/test_register_canonicalization.py, tests/test_freq_write_audibility.py

Two distinct "hard restart" mechanisms — don't conflate them:

1. ADSR/envelope hard restart (gate-based): force the prior epoch's compare small ~2 frames before the next gate-on so the ADSR-bug window elapses. No TEST bit involved; freq stays audible during those release frames.
2. TEST-bit oscillator reset (CTRL bit 3): silences and resets the oscillator; freq on the TEST frame is the only near-don't-care.

Players also exploit the bug deliberately ("sexy start": AD+SR written before GATE with big R/small A to arm the ~32 ms attack delay) — write placement around the gate edge is musical content, which is why the tokenizer records gate-edge side per nibble instead of normalizing it.

Scope

These tests and the renderer target single-speed, non-digi tunes (one player call per IRQ frame). Multi-speed (~5%) and digi (~3%) playback are out of scope.

Testing

./run_tests.sh   # black, pylint, pyright, pytest with coverage gate >= 85%

The chip-fact suites run pyresidfp deterministically (fixed write scripts, ENV3 reads, ±8-count nondeterminism floor). A/B audibility tests are write-count matched so the comparison isolates placement, not write count.

Used by

• preframr (training/inference): render_to_wav, sidq, play_samples.
• preframr-tokens: assert_dfs_render_equivalent (transform gates), play_via_aplay, LiveAnimator.
• preframr-xpt (research): render_df_to_wav, compare_renders, fingerprint_batch, df_to_packets.

Stability

Library follows semver from v1.0. Pre-1.0 releases may break API as the preframr codebase evolves. The root re-exports above are the supported surface; _reg_mappers.FreqMapper and _sid_constants are internal but currently imported by sibling repos.

License

Apache 2.0. See LICENSE.