diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/adr/0002-dr-wav.md | 85 | ||||
| -rw-r--r-- | docs/reports/0002-dr-wav.md | 199 |
2 files changed, 284 insertions, 0 deletions
diff --git a/docs/adr/0002-dr-wav.md b/docs/adr/0002-dr-wav.md new file mode 100644 index 0000000..1bc1cbe --- /dev/null +++ b/docs/adr/0002-dr-wav.md @@ -0,0 +1,85 @@ +# 0002 — WAV I/O through dr_wav + +- **Status:** accepted +- **Date:** 2026-11-17 +- **Deciders:** Andre Bezerra (project owner); implemented by the coding agent + +## Context + +The WAV reader in `audio_wav.c` and the WAV writer in `main.c` were written in +house: about 442 and 200 lines respectively, plus a separate header writer in +`metronome.c`. The reader duplicated the format parsing and sample conversion +that a mature single-header library already provides, and the writer duplicated +the same 56-byte header layout in two places. + +The user asked whether dr_libs and miniaudio could simplify the audio code. The +exploration established that MP3 input already uses dr_mp3; miniaudio cannot +replace mpv without losing the documented speed and pitch controls; and neither +library can encode MP3. The user chose the smaller option: keep mpv, and use +dr_libs for WAV I/O only. + +## Decision + +Vendor **dr_wav 0.14.7** at dr_libs commit +`ebfea72a291322bf26ce4eb393c98a0262b9b561` (SHA-256 +`7c9660d75361ad6175e6217c63a1075c9512445c06bc951197fc479179f76b39`), and use it +for both sides of WAV I/O: + +- `audio_wav.c` keeps a small RIFF pre-scan for structural validation, then + hands format parsing and sample conversion to dr_wav. The existing accepted + formats, rejection rules, mono-to-stereo duplication, and NaN/Inf rejection + are preserved. dr_wav is compiled with `DRWAV_MAX_SAMPLE_RATE 1000000`, above + the project's 768 kHz bound, so its default 384 kHz ceiling does not narrow + the documented 8 kHz–768 kHz range and the reader's own check can report + 768001 Hz specifically. `WAVE_FORMAT_EXTENSIBLE` is validated against the + full 16-byte subtype GUID rather than only its low 16-bit tag. +- A new `wav_writer.c/.h` owns float32 WAV output through dr_wav's sequential + writer. `main.c` keeps the `.part`/rename publication policy; `metronome.c` + uses the same module for its bar file. +- The CLI, the stem path contract, the mpv invocation, and the 44.1-kHz stereo + float32 output contract are unchanged. The output header changes from 56 + bytes with a `fact` chunk to dr_wav's 44-byte header without it. + +## Alternatives considered + +- **Keep the in-house reader and writer.** Rejected: it leaves the hand-written + format/conversion surface and the duplicated header writer in place. +- **miniaudio for WAV I/O.** Rejected for this task: a 4.2 MB header and a + broader API for the same WAV encode/decode work, while the playback path still + needs mpv. +- **dr_wav without a pre-scan.** Rejected: dr_wav does not enforce the + RIFF/chunk boundaries or the duplicate-chunk rules the reader documents. The + pre-scan rejects truncated data through those bounds before dr_wav is + initialized. `onTell` is NULL, so dr_wav's own file-size clamp is disabled; + the `dataChunkDataPos`/`dataChunkDataSize` check is only a consistency guard. +- **MP3 stems.** Rejected in the exploration: neither dr_mp3 nor miniaudio + encodes MP3; it would need LAME, add a dependency, lose the current + reconstruction guarantee, and change the output contract. + +## Consequences + +- The repository gains one vendored, pinned single-header dependency with the + same public-domain/MIT-0 license as dr_mp3. It is compiled in, so the portable + bundle gains no runtime dependency; `package.sh` adds the license notice. +- `main.c` loses the WAV writer, resolving that piece of the known debt in the + architect map. The new module is shared with the metronome. +- The reader's strict validation is preserved, but `validBitsPerSample` below + the container bit depth is no longer masked by the reader: dr_wav relies on + conforming files (zero padding) to decode identically. Files with non-zero + padding in unused low bits may decode differently; that is recorded here and + in the report. +- The output header layout changes while the documented output contract stays + the same. `tests/wavtool.c` was extended to generate and read PCM 8/16/24/32, + float32, mono/stereo, and `WAVE_FORMAT_EXTENSIBLE` input, to generate the + 8 kHz/768 kHz/768001 Hz and bogus-GUID cases, to assert the 44-byte output + header, and to inspect a mono metronome bar. +- dr_wav's parser rejects some nonconforming layouts the in-house parser + accepted (for example, a data chunk before the fmt chunk, or an unusual fmt + chunk size). These are tightenings on undocumented input; the accepted set is + otherwise unchanged. +- Per the dependency policy, this ADR records the follow-up obligation to + re-evaluate dr_wav when the WAV validation surface shrinks. The library is + vendored, not system-linked, so removal later is a source change only. +- `dr_wav.h`, `LICENSE`, and the pinned README live in `third_party/dr_wav/`; + `audio_wav.c` is the single translation unit that defines + `DR_WAV_IMPLEMENTATION`. diff --git a/docs/reports/0002-dr-wav.md b/docs/reports/0002-dr-wav.md new file mode 100644 index 0000000..8b4e079 --- /dev/null +++ b/docs/reports/0002-dr-wav.md @@ -0,0 +1,199 @@ +# 0002 — WAV I/O through dr_wav + +- **Tier:** architectural +- **Commit:** this commit +- **Date:** 2026-11-17 + +## Request + +"I want you to make only the option 2 change. We won't remove mpv for now." + +Option 2 was: replace the hand-written WAV reader and writer with the vendored +dr_wav library, keeping the CLI, the output contract, the strict input checks, +and mpv. miniaudio, MP3 output, and playback changes are out of scope. + +## SPEC + +```text +SPEC +- Request (restated): replace the in-house WAV reader and writer with dr_wav, + add a shared wav_writer module, keep every documented input/output behaviour + and mpv, and leave miniaudio out. +- Tier: architectural (new dependency, new module, WAV header layout change). +- Acceptance criteria: + 1. WAV input is decoded through dr_wav. PCM 8/16/24/32, IEEE float32, + WAVE_FORMAT_EXTENSIBLE PCM/float, mono and stereo, 8 kHz and 768 kHz are + accepted; 768001 Hz, RF64, RIFX, compressed formats, 3+ channels, a bogus + extensible GUID, empty/partial/truncated data, duplicate fmt/data chunks, + and NaN/Inf are rejected. -> evidence: pipeline.fake.input-formats, + pipeline.fake.sample-rates, and pipeline.fake.wav-errors. + 2. Mono input is duplicated to stereo as before; the stem pipeline still + reconstructs the fake-model input within the existing 2e-6 tolerance. + -> evidence: the reconstruction lines for all seven input formats. + 3. Stem output is still stereo 44.1-kHz IEEE float32 WAV with the exact frame + count, finite samples, deterministic bytes, and the current .part/rename + and failure-cleanup behaviour. The header layout changes to dr_wav's + 44-byte header, asserted by wavtool's data-offset check. -> evidence: + pipeline.fake.wav-contract, pipeline.fake.deterministic, + pipeline.fake.existing-directory, pipeline.fake.failure-cleanup, + pipeline.fake.multi-chunk. + 4. The metronome still writes one mono 44.1-kHz float32 bar to + $XDG_RUNTIME_DIR/stemsep-metronome.wav and hands that path plus + --loop-file=inf to mpv. -> evidence: metronome.bar. + 5. The build is warning-free under the project flags; the quick and full test + suites and scripts/check.sh pass. -> evidence: pasted below. + 6. No miniaudio, mpv, MP3, resampler, overlay-add, or ONNX changes. + 7. The new dependency is pinned with license/hash/README, appears in the + bundle licenses and README, has an ADR, and the module map is updated. +- Out of scope: miniaudio, MP3 encoding, playback controls, output-format + flags, resampler changes. +- Decisions taken (internal, reversible): keep a RIFF pre-scan for structural + validation and truncation/duplicate rejection; define + DRWAV_MAX_SAMPLE_RATE 1000000 (above the project's 768 kHz bound) so dr_wav's + 384 kHz default does not narrow the documented range and 768001 Hz gets the + specific diagnostic; validate the full 16-byte extensible subtype GUID; use + dr_wav's sequential writer so sizes are written up front; extract + wav_writer.c/.h; use it for the metronome bar; keep the contract error style. +- Open questions: none. +- Surfaces touched: WAV input, WAV output header layout (contract unchanged), + build, tests, bundle licenses, README, ADR, module map. +- Regression risks: dr_wav edge-case parsing, validBits handling, writer + finalization on short writes, metronome bar layout, output header consumers. +``` + +## What changed + +- `third_party/dr_wav/` — vendored dr_wav 0.14.7 at commit + `ebfea72a291322bf26ce4eb393c98a0262b9b561` (header SHA-256 + `7c9660d75361ad6175e6217c63a1075c9512445c06bc951197fc479179f76b39`), its + MIT-0/public-domain license, and a pinned README. +- `audio_wav.c` — RIFF pre-scan plus dr_wav parsing/conversion, with the + existing channel, rate, bit-depth, valid-bit, block-alignment, channel-mask, + data-size, truncation, duplicate-chunk, and NaN/Inf checks; + `DRWAV_MAX_SAMPLE_RATE 1000000` keeps dr_wav above the project's 768 kHz + ceiling, and the full 16-byte extensible subtype GUID is checked. +- `wav_writer.c` / `wav_writer.h` — new module; dr_wav sequential float32 + writing, finite-sample and frame-count checks, finalization and abort. +- `main.c` — the old writer and header patching are gone; `OutputFile` keeps + the `.part`/rename publication policy and calls the writer module. +- `metronome.c` — writes the bar through the writer module; the temp path, the + mono float32 format, and the mpv invocation are unchanged. +- `build.sh`, `tests/run.sh` — dr_wav include path and the new source. +- `tests/wavtool.c` — generates and reads PCM 8/16/24/32, float32, + mono/stereo, and extensible fixtures; generates 8 kHz/768 kHz/768001 Hz, + RIFX, and bogus-GUID cases; asserts the 44-byte output header; inspects mono + output. +- `tests/run.sh` — `pipeline.fake.input-formats`, + `pipeline.fake.sample-rates`, `pipeline.fake.wav-errors`, and + `metronome.bar`; the mpv stub records its argv so the bar path is checked. +- `package.sh`, `README.md`, `AGENTS.md`, `.agents/skills/architect.md` — + dr_wav license/notice, module map, and known-debt update. +- `docs/adr/0002-dr-wav.md` — the dependency and design decision. + +## Verification + +```text +$ ./build.sh +(no output; exit 0) + +$ ./tests/run.sh --quick +... +PASS pipeline.fake.input-formats + pcm16 reconstruction_max_abs_error=1.71363354e-07 stem_scale_max_abs_error=9.93410747e-08 frames=44100 + pcm8-mono reconstruction_max_abs_error=1.11758709e-07 stem_scale_max_abs_error=5.96046448e-08 frames=44100 + pcm24 reconstruction_max_abs_error=1.63912773e-07 stem_scale_max_abs_error=9.93410747e-08 frames=44100 + pcm32 reconstruction_max_abs_error=1.86264515e-07 stem_scale_max_abs_error=9.93410747e-08 frames=44100 + float32 reconstruction_max_abs_error=1.86264515e-07 stem_scale_max_abs_error=9.93410747e-08 frames=44100 + ext-pcm16 reconstruction_max_abs_error=1.71363354e-07 stem_scale_max_abs_error=9.93410747e-08 frames=44100 + ext-float32 reconstruction_max_abs_error=1.86264515e-07 stem_scale_max_abs_error=9.93410747e-08 frames=44100 +PASS pipeline.fake.wav-errors +PASS pipeline.fake.sample-rates + rate8000 input_rate=8000 output_frames=243101 + rate768000 input_rate=768000 output_frames=2532 +PASS metronome.bar + metronome bar: format=3 channels=1 rate=44100 bits=32 frames=88200 finite=yes +SKIP pipeline.model.smoke (--quick skips tests that need the ONNX model) +22 passed, 0 failed, 1 skipped + +$ ./tests/run.sh +... +PASS pipeline.model.smoke + model separation: 5848 ms for 66150 frames, six stems +23 passed, 0 failed, 0 skipped + +$ ./scripts/check.sh +stemsep check + + [PASS] R3 build is warning-free + [PASS] R6 non-negotiables block unchanged + [PASS] tests pass + [PASS] no build outputs, media, or model weights in the repository + +0 failure(s), 0 unfinished gate(s) +``` + +## Review + +First independent review: **fail**, with two Major findings and several Minor +ones. All were addressed before the commit: + +- Major: dr_wav's default 384 kHz ceiling rejected 768 kHz input. Defined + `DRWAV_MAX_SAMPLE_RATE 1000000`; added 8000/768000 acceptance and 768001 + rejection tests, with the specific 768001 diagnostic asserted. +- Major: the 16-byte extensible subtype GUID was not validated, so a bogus GUID + could decode as PCM. Added the full subtype/GUID check and bad-GUID fixtures. +- Minor: the pre-scan rationale did not match `onTell = NULL`; ADR and report + corrected. +- Minor: the 44-byte header was not asserted; `wavtool inspect` now requires a + 44-byte data offset. +- Minor: evidence gaps for 8 kHz/768 kHz/768001 Hz, RIFX, and extensible float; + new fixtures and tests. +- Minor: writer ownership was implicit; documented in `wav_writer.h`. +- Nit: nonconforming-layout tightening recorded in the ADR; the 4 GiB pre-check + now uses the 44-byte header size; the mpv stub records and checks its argv. + +Re-review verdict: **pass-with-findings**. The remaining findings were +addressed before the commit: + +- The sample-rate test no longer trusts the program's stderr for the frame + count: it asserts the input `Input: ... 8000/768000 Hz` line and the fixed + output frame counts (243101 and 2532). +- An `inf` fixture was added to the NaN/Inf rejection matrix. +- The line-count figures below were corrected. +- dr_wav's ceiling is now above the project bound, so 768001 Hz reaches the + specific `unsupported WAV sample rate` message and the test asserts it. +- The writer ownership comment now names `finish()`/`abort()`. +- The writer's finite-sample guard remains defensive; the orchestrator's + pre-check and the output inspection cover the observable contract. + +## Not machine-verified + +- The metronome's audible click was not listened to. The bar file's format, + channel count, sample rate, frame count, and finiteness are machine-checked; + listening is still required for perceived click tone/level. +- `validBitsPerSample` below the container depth is not masked by dr_wav. + Conforming files with zero padding decode identically; malformed files with + non-zero low bits may differ from the old reader. This is an intentional + consequence of handing conversion to the library and is recorded in the ADR. +- The playback path was not changed and still depends on mpv; its existing + "requires listening" status is unchanged. + +## Deferred + +- **Line count.** Production code did not shrink overall: `audio_wav.c` lost + 18 lines, `main.c` 95, and `metronome.c` 27, but the new `wav_writer` module + (including its header) adds 250 lines, for +110 net. The + simplification is that WAV parsing, conversion, header writing, and size + accounting now belong to a maintained library, and `main.c` no longer owns + the writer. If line count is the deciding goal, a follow-up can remove the + RIFF pre-scan and the duplicate/truncation guarantees, which would reduce + more but weaken validation. +- **Dependency policy.** The architect requires a follow-up task to re-evaluate + a new dependency; `docs/adr/0002-dr-wav.md` records it. dr_wav is vendored + and compiled in, so removal later is a source change only. +- **Test helper growth.** `tests/wavtool.c` grew substantially to generate and + validate the format matrix. It remains test-only code. +- **Nonconforming layouts.** dr_wav rejects some inputs the in-house parser + accepted (data before fmt, unusual fmt chunk sizes). These were never + documented and are now recorded in the ADR; no valid/documented format was + lost. |
