docs: correct drift in user docs + stale rate comments - #137
Merged
Conversation
The audio-quality and mic sections had drifted from the code: - Default sample_rate is 12000 Hz, not 8 kHz; the CIA #2 Timer A latch is derived from sample_rate, so higher rates keep pitch correct and are rejected at load past the ~13.6 kHz NTSC handler ceiling (they do not "play at the wrong pitch"). The live pipeline underruns around ~12.5 kHz. - Bit depth is set by [audio].dac_curve, not the rate: the "auto" default already uses the Mahoney ~6-7-bit $D418 technique on the U64's emulated SID, and U64 video audio defaults to the off-bus sampler, not the DAC. - noise_gate only applies when [dsp].enabled = false; point the mic advice at the [dsp] downward expander (expander_threshold_db), which is ON by default and replaces the hard gate.
- ~10.5 kHz → 12 kHz default; replace the "different rate just plays at the wrong pitch / nothing resamples" claim with the pitch-adaptive CIA timer + load-reject ceiling behavior. - Add the [audio].dac_curve nuance: "auto" default uses the Mahoney ~6-7-bit $D418 technique on the U64's emulated SID (and --calibrate-dac for a physical SID); 4-bit linear is only the uncalibrated fallback. - Replace "noise_gate/mic_sensitivity are the only shaping knobs" with the [dsp] chain (ON by default, expander replaces the hard gate); noise_gate only applies when [dsp].enabled = false.
- Catalogs: "7 scene types" → 10; mcm mode is 80×50 char via an uploaded 2×2 charset (was 40×25 text); generative sources 3 → 20; add the `blur` effect and the per-scene `pre_emphasis`. - Extras table: add tr, vision, camera, yt, wled. - Config sections: add [hardware], [teensyrom], [dsp], top-level [color], and [midi_control]; reconcile [ultimate64] with the [hardware].backend split (+ sid_model); [audio] gains dac_curve/sampler_clock_hz, reframes noise_gate as superseded by [dsp], and points at the pitch/tempo/reu knobs. - CLI table: -v/-vv both enable DEBUG (default INFO); -d takes index/name/ VID:PID.
- Generative feature bullet: ~20 procedural sources (was plasma/tunnel/ fire), add the blur effect. - Display+audio summary: soften "4-bit $D418 DAC" to note the Mahoney ~6-7-bit companding path. - Make targets: sync to actual `make` output (add sync/fmt/doctor; fix test/coverage descriptions).
The [audio].sample_rate default is 12000 Hz, but several comments still referenced 8 kHz / 10.5 kHz as the operating rate. Comment/docstring only — no behavior change. - audio.py: module docstring 10.5 kHz → 12 kHz (Nyquist ~6.0 kHz); correct the load-bearing derived figures to the 12 kHz default (STOMP guard ms, sample-tap FFT floor, servo time constant, REU-mic bootstrap latency, MAX_QUEUED_SAMPLES cap); drop drift-prone "@ 8 kHz" duration color from fixed byte-size constants (ring, half-ring margin, mic ring); generalize the consumer-rate prose to "the configured sample_rate". - audio_marker.py: marker Nyquist note → 12 kHz; note DEFAULT_PLAYBACK_RATE no longer tracks the app default; generalize the staircase docstring. - dsp.py: perf note "At 8 kHz" → "At the DAC sample rate". Deliberately kept: the CIA-latch worked examples (NTSC@8kHz: latch=127), the historical 6581 PWM/badline measurements, the REU-pump 8 kHz special case (framed as historical), and dac_calibration.py's own pinned NMI_RATE = 8000 (a fixed calibration rate, not the app default).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User-facing docs (
README.md,docs/) had drifted from the code. This corrects the drift across five independently-reviewable commits, plus a sweep of stale audio-rate references in code comments. Docs + comments only — no behavior change; the full test suite (2633 tests) andmake lintare green.Phases
docs/troubleshooting.md— audio symptom sections: default rate 8 kHz→12 kHz; the CIA docs: document scripts/c64cast.sh launcher #2 Timer A latch is derived fromsample_rateso higher rates keep pitch correct and are rejected at load past the ~13.6 kHz NTSC handler ceiling (not "wrong pitch"); bit depth is[audio].dac_curve(Mahoney ~6-7-bit by default on the U64, not flat 4-bit); mic "no audio" advice now points at the[dsp]downward expander (noise_gateonly applies when[dsp].enabled = false).docs/caveats.md— "Audio is intentionally lo-fi": ~10.5 kHz→12 kHz, same pitch/dac_curve corrections,[dsp]chain (ON by default) supersedes the old "noise_gate/mic_sensitivity are the only shaping knobs" claim.docs/usage.md— "7 scene types"→10;mcmis 80×50 multicolor char via an uploaded 2×2 charset (was 40×25 text); generative sources 3→20 + theblureffect + per-scenepre_emphasis; extras table gainstr/vision/camera/yt/wled; new[hardware]/[teensyrom]/[dsp]/[color]/[midi_control]config sections +[ultimate64]reconciled with the[hardware].backendsplit;[audio]gainsdac_curve/sampler_clock_hz; CLI table fixes (-v/-vvboth DEBUG;-dtakes index/name/VID:PID).README.md— generative "~20 procedural sources"; audio DAC Mahoney note;maketarget list synced to actual output (sync/fmt/doctor).audio.py,audio_marker.py,dsp.py) — stale 8/10.5 kHz references corrected to the 12 kHz default (load-bearing figures recomputed; drift-prone "@ 8 kHz" duration color removed). Deliberately kept: the CIA-latch worked examples, the historical 6581 PWM/badline measurements, anddac_calibration.py's own intentionally-pinnedNMI_RATE = 8000.Every corrected catalog was cross-checked against the introspection commands (
--list-scenes/--list-modes,--describe scene:generative|mode:mcm|section:dsp|section:color|section:audio).Not in this PR
A full
docs/architecture.mdaudit (it has its own stale rate refs + per-module narratives to verify) is deferred as a tracked follow-up.