summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorAndre Bezerra <amelco.herman@gmail.com>2026-11-17 13:09:49 -0300
committerAndre Bezerra <amelco.herman@gmail.com>2026-11-17 13:09:49 -0300
commit719c62b10468985c76b39e1002dc861b1f654a53 (patch)
tree1b68b1dec9251baa00336a155dfbbc1ab696eed2 /docs
parent433cc1890a77e6c16583e1d65ad71645c7463826 (diff)
Replace the hand-written WAV reader and writer with dr_wavmaster
Vendor dr_wav 0.14.7 at ebfea72a, keep the strict RIFF/sample checks, extract wav_writer for stem and metronome output, and leave mpv and MP3 unchanged.
Diffstat (limited to 'docs')
-rw-r--r--docs/adr/0002-dr-wav.md85
-rw-r--r--docs/reports/0002-dr-wav.md199
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.