summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndre Bezerra <amelco.herman@gmail.com>2026-11-17 11:49:41 -0300
committerAndre Bezerra <amelco.herman@gmail.com>2026-11-17 11:59:21 -0300
commit4a73d76af22744179cd02826bdd405b0c32b1429 (patch)
treeed984a0654216a90e75b86d23452561c6cca050b
parentc63dcf6248d9d6dad5c78e91a434e2b8409e3f3c (diff)
add the test harness and the first test slice
Add tests/run.sh (POSIX sh, no framework, no new dependency) and a compiled WAV helper. Cover the CLI contract, the fake-model separation pipeline (single- and multi-chunk), determinism, overwrite refusal, failure cleanup, per-stem reconstruction, and a timed real-model smoke test. Print usage when playback validation fails so the invalid -p contract matches its documentation. Record the harness decision in ADR 0001 and the evidence, measurements, and findings in report 0001.
-rw-r--r--docs/adr/0001-test-harness.md82
-rw-r--r--docs/reports/0001-test-harness.md263
-rw-r--r--main.c7
-rwxr-xr-xtests/run.sh505
-rw-r--r--tests/wavtool.c664
5 files changed, 1520 insertions, 1 deletions
diff --git a/docs/adr/0001-test-harness.md b/docs/adr/0001-test-harness.md
new file mode 100644
index 0000000..3b036e0
--- /dev/null
+++ b/docs/adr/0001-test-harness.md
@@ -0,0 +1,82 @@
+# 0001 — Test harness: POSIX shell plus a compiled WAV helper
+
+- **Status:** accepted
+- **Date:** 2026-11-17
+- **Deciders:** Andre Bezerra (project owner); implemented by the coding agent
+
+## Context
+
+The repository had no automated tests, so R5 ("never claim verification you did
+not run") had nothing to lean on, and `scripts/check.sh` could only report the
+tests gate as SKIP. The tester skill fixes the shape of the harness: POSIX shell,
+no test framework, no new dependency, one PASS/FAIL line per test, a `--quick`
+mode, and builds under `build/`.
+
+The tests also need to generate deterministic WAV fixtures, inspect the exact
+WAV header the writer produces, count frames, reject NaN/Inf samples, and compare
+a float reconstruction. Shell plus `od`/`awk` can do none of that readably or
+quickly, and no audio may be committed.
+
+Two further constraints shape the design. R1 keeps every path inside the
+workspace, so the scratch directory cannot be the usual `mktemp -d` under
+`/tmp`. The task forbids modifying the program to make it testable, so the only
+way to exercise the pipeline without the 258 MB model is the existing
+`STEMSEP_TEST_FAKE_MODEL` compile-time mode.
+
+## Decision
+
+Tests live in `tests/run.sh` (POSIX `sh`) with one compiled helper,
+`tests/wavtool.c`. Each run compiles two test binaries — the real program and a
+`STEMSEP_TEST_FAKE_MODEL` build — plus the helper into the run's scratch
+directory under `build/`, with the project's warning flags plus `-Werror`, so a
+new warning fails the harness and concurrent runs cannot race on a shared
+executable. Fixtures are generated at run time as PCM16 stereo 44.1-kHz WAV
+files; the helper validates float32 stems strictly, checks each stem against its
+fake scale, and computes both the stem sum and the per-stem reconstruction
+error. Scratch output goes to `mktemp -d` under `build/`, removed by a trap on
+exit, including failure. A stub `mpv` goes first in `PATH` and
+`XDG_RUNTIME_DIR` points into the scratch, so a validation regression cannot
+block the suite by starting a real player. The real-model smoke test is the only
+model-dependent test and is skipped by `--quick`; a missing model stops a full
+run instead of silently skipping it. Output-write failure is injected with
+`RLIMIT_FSIZE` while `SIGXFSZ` is ignored, so the program's normal error path
+(and not a signal kill) exercises cleanup.
+
+## Alternatives considered
+
+- **Python or a test framework.** Rejected: a new dependency of exactly the kind
+ the project forbids, for tests that mostly start a process and read a header.
+- **Shell only, with `od` and `awk`.** Rejected: decoding little-endian float32,
+ rejecting NaN/Inf, and summing six stems in `awk` is slower, harder to review,
+ and easier to get silently wrong than 600 lines of C. `gcc` and libm are
+ already build requirements.
+- **Use the shipped `./stemsep`.** Rejected: `build.sh` writes into the source
+ tree, the binary can be stale, and the harness must build into `build/`.
+- **Scratch in `/tmp`.** Rejected: violates R1. `mktemp -d` under `build/`
+ keeps the path inside the workspace and is still removed on exit.
+- **Fixed test-binary paths under `build/`.** Rejected: a manual run and
+ `check.sh` can rewrite a binary the other is executing (ETXTBSY). Per-run
+ scratch paths remove the race.
+- **Trigger the failure cleanup with truncated input.** Rejected: the WAV and
+ MP3 readers reject truncation at open time, before the output directory
+ exists, so it does not test output cleanup.
+- **Run model tests on every invocation.** Rejected: it would make the common
+ loop slow; `--quick` keeps feedback at a few seconds while the full run stays
+ well under the ten-minute budget.
+
+## Consequences
+
+- The test suite now needs `gcc` and libm, both already required to build the
+ program. No test framework, package, or committed media is added.
+- New tests must be registered in `tests/run.sh`; there is no auto-discovery.
+- Test binaries are rebuilt on every invocation (about three seconds) so they
+ cannot go stale.
+- `tests/run.sh` must keep scratch under `build/`; using the system temp
+ directory would break R1.
+- Real-model tests fail loudly when `models/htdemucs_6s.onnx` is absent. That is
+ deliberate: a silent skip would turn a missing prerequisite into a false pass.
+- The harness exposed that invalid `-p` printed no usage block; the coordinator
+ chose to fix `main.c` so playback usage errors print it, rather than narrow
+ the criterion. The tracked MP3 hygiene failure remains a separate task.
+- `-Werror` makes a new warning in the program or the helper fail the harness,
+ not only `build.sh`.
diff --git a/docs/reports/0001-test-harness.md b/docs/reports/0001-test-harness.md
new file mode 100644
index 0000000..a564a8c
--- /dev/null
+++ b/docs/reports/0001-test-harness.md
@@ -0,0 +1,263 @@
+# 0001 — test harness and first test slice
+
+- **Tier:** architectural
+- **Commit:** this commit (the preparation commit is `558a4cf`)
+- **Date:** 2026-11-17
+
+## Request
+
+Build the `stemsep` test harness and its first slice: the CLI contract, the
+separation pipeline in fake-model mode, and one timed real-model smoke test.
+During review the coordinator approved one source fix: invalid `-p` must print
+the usage block.
+
+## SPEC
+
+```text
+SPEC
+- Request (restated): add a POSIX-shell test harness and the first tests for the
+ CLI contract, the fake-model separation pipeline (including a multi-chunk
+ input), and one timed real-model smoke test; no changes to the program except
+ the approved usage-block fix.
+- Tier: architectural (new tests/ directory and a new test entry point)
+- Acceptance criteria:
+ 1. tests/run.sh is POSIX sh, builds what it needs under build/, works from any
+ current directory reached by path, accepts --quick and a substring filter,
+ prints one PASS/FAIL line per test plus a summary, and exits non-zero on
+ failure. -> evidence: full/quick/filter runs from the root and from build/,
+ plus a forced-failure run.
+ 2. CLI contract: no arguments, --bpm with -i/-m/-p, missing -m, invalid music
+ identifiers, invalid -p letters (with the usage block), an unknown option,
+ and out-of-range -t/--bpm exit 2; a missing input exits 3; a missing model
+ exits 4. -> evidence: cli.* test lines.
+ 3. Fake-model separation writes exactly six named stereo 44.1-kHz float32
+ stems with equal frame counts, leaves no .part files, contains no NaN/Inf,
+ repeats byte-identically, refuses an existing output directory with exit 5
+ and untouched contents, leaves no output directory after a failed run, runs
+ with options in either order, and handles a two-chunk input (> 343,980
+ frames) identically. -> evidence: pipeline.fake.* test lines.
+ 4. Reconstruction in fake mode: the sum of the six stems equals 3.5 x input and
+ each named stem matches its own fake scale (1/6 .. 6/6) within a tolerance
+ derived from measurements. -> evidence: the measured errors printed by
+ pipeline.fake.reconstruction and pipeline.fake.multi-chunk.
+ 5. A 1-2 second real-model separation satisfies the same output contract and
+ its wall-clock time is reported; --quick skips exactly this test; a missing
+ model stops the full run. -> evidence: pipeline.model.smoke and the
+ missing-model guard run.
+ 6. ./scripts/check.sh no longer reports the tests gate as SKIP; the full suite
+ finishes under ten minutes; no audio committed. -> evidence: check output.
+- Out of scope: unit tests of static functions, fuzzing, sanitizers, MP3 input,
+ valid playback and metronome runs that need mpv, interrupt handling, and
+ separation quality.
+- Decisions taken (internal, reversible): scratch lives under build/ so R1 holds;
+ test binaries are built into the per-run scratch (no concurrent ETXTBSY); a
+ compiled C helper performs WAV generation/inspection; the fake build uses the
+ existing STEMSEP_TEST_FAKE_MODEL define; cleanup on write failure is injected
+ with RLIMIT_FSIZE and SIGXFSZ ignored; a stub mpv and a scratch
+ XDG_RUNTIME_DIR prevent accidental playback; test builds use -Werror.
+ The coordinator chose to fix main.c for the invalid -p usage block rather than
+ narrow the original "usage, exit 2" criterion.
+- Open questions: none blocking. The tracked MP3 hygiene failure and the
+ literal exit codes outside main.c are reported as findings.
+- Surfaces touched: tests/ (new), main.c (one approved fix), docs/adr/,
+ docs/reports/; build/ artifacts (ignored).
+- Regression risks: the test binaries duplicate the compiler flags from
+ build.sh; the real binary now needs LD_LIBRARY_PATH because it is built into
+ the scratch directory; future tests must keep scratch under build/ (R1).
+```
+
+## What changed
+
+- `main.c` — when `playback_run` reports a usage error, print the usage block
+ before returning. This is the only program change; it fixes the contract the
+ review found, and there are no test hooks or helper exposures.
+- `tests/run.sh` — the harness: path guard, argument parsing, per-run binaries,
+ stub `mpv` and `XDG_RUNTIME_DIR`, builds with `-Werror`, fixture generation,
+ per-test isolation, PASS/FAIL summary, `--quick`, filter, cleanup trap.
+- `tests/wavtool.c` — test-only helper: generates the PCM16 fixture, strictly
+ validates a float32 stereo 44.1-kHz stem (header, sizes, frame count, finite
+ samples), and measures both the stem-sum and per-stem-scale errors.
+- `tests/run.sh` (new tests) — `cli.invalid-play-selection` now asserts the
+ usage block; `cli.unknown-option`, `pipeline.fake.option-order`, and
+ `pipeline.fake.multi-chunk` were added for the review findings.
+- `docs/adr/0001-test-harness.md` — records why the harness is shell plus a
+ compiled helper and why scratch is under `build/`.
+- `docs/reports/0001-test-harness.md` — this report.
+- Preparation commit `558a4cf` — `AGENTS.md`, `.agents/`, `scripts/`, `docs/`
+ committed on their own, as requested. The deleted `musicas/*.mp3` was left as
+ an unstaged deletion.
+
+## Verification
+
+```text
+$ ./build.sh
+(no output; exit 0, warning-free)
+
+$ ./tests/run.sh
+PASS cli.no-arguments
+PASS cli.bpm-conflicts
+PASS cli.missing-identifier
+PASS cli.invalid-play-selection
+PASS cli.invalid-identifier
+PASS cli.time-signature-range
+PASS cli.bpm-range
+PASS cli.unknown-option
+PASS cli.missing-input
+PASS cli.missing-model
+PASS pipeline.fake.six-stems
+PASS pipeline.fake.wav-contract
+PASS pipeline.fake.reconstruction
+ reconstruction reconstruction_max_abs_error=1.71363354e-07 stem_scale_max_abs_error=9.93410747e-08 frames=44100 (tolerance 0.000002)
+PASS pipeline.fake.deterministic
+PASS pipeline.fake.existing-directory
+PASS pipeline.fake.failure-cleanup
+PASS pipeline.fake.option-order
+PASS pipeline.fake.multi-chunk
+ multi-chunk reconstruction reconstruction_max_abs_error=2.16066837e-07 stem_scale_max_abs_error=9.93410747e-08 frames=400000 (tolerance 0.000002)
+PASS pipeline.model.smoke
+ model separation: 6373 ms for 66150 frames, six stems
+
+19 passed, 0 failed, 0 skipped
+(exit 0; wall clock 9.9 s measured with the shell's time builtin; timings vary
+run to run, and the re-review measured 6194 ms for the model step)
+
+$ ./tests/run.sh --quick
+... same tests, model smoke skipped ...
+18 passed, 0 failed, 1 skipped
+(exit 0; wall clock 3.6 s)
+
+$ ./scripts/check.sh
+stemsep check
+
+ [PASS] R3 build is warning-free
+ [PASS] R6 non-negotiables block unchanged
+ [PASS] tests pass
+ [FAIL] no media or model weights tracked by git
+ musicas/08 Hakumei~Chiriyuku Yuri wo Mitsumenagara~ (Lareine cover).mp3
+
+1 failure(s), 0 unfinished gate(s)
+(exit 1; the tests gate is no longer SKIP; the remaining failure is the tracked
+MP3 deletion, which is a separate task)
+
+$ cd build && PATH="$PWD/../tests:$PATH" run.sh
+19 passed, 0 failed, 0 skipped
+(exit 0; PATH invocation resolves $0 to a path, so the harness works from another
+current directory)
+
+$ cd tests && sh run.sh --quick
+error: invoke run.sh by path, e.g. ./tests/run.sh
+(exit 2; the R1 guard refuses a bare name instead of changing to the parent of
+the current directory)
+```
+
+The failure path of the harness itself was checked with a throwaway copy under
+`build/` (not committed) where `cli.no-arguments` was replaced by `false`:
+
+```text
+FAIL cli.no-arguments
+...
+17 passed, 1 failed, 1 skipped
+(exit 1; no build/stemsep-tests.* scratch directory was left behind)
+```
+
+The missing-model guard was checked in a throwaway build root without
+`models/htdemucs_6s.onnx`:
+
+```text
+error: .../models/htdemucs_6s.onnx is missing
+The full suite needs the ONNX model; install it as README.md says,
+or run --quick.
+(exit 1; no tests ran, no silent skip)
+```
+
+Two concurrent `--quick` runs both finished `18 passed, 0 failed, 1 skipped`,
+which exercises the per-run binary directories.
+
+The new coverage was mutation-tested against the exact defects the review used:
+
+```text
+swapped guitar/piano in the helper's STEM_NAMES:
+ stem_scale_max_abs_error=0.124989867
+ wavtool: stem 'guitar' deviates from its fake-model scale by 0.124989867
+ (exit 1; the old sum-only check stayed green)
+
+replaced shift_overlap_buffers with a no-op, then ran the 400,000-frame input:
+ reconstruction_max_abs_error=1.88735963
+ (exit 1; the old 44,100-frame suite stayed green)
+```
+
+The tolerance was measured before it was chosen: `1.71363354e-07` at 44,100
+frames, `2.16066837e-07` at 400,000 frames (two chunks), and a per-stem scale
+error of `9.93410747e-08`. The test uses `2e-6`, about nine times the largest
+measurement, and states both measurements at the top of `tests/run.sh`.
+
+## Review
+
+The first independent review returned **fail** with **one Major, seven Minor,
+and two Nit** findings:
+
+- Major: invalid `-p` did not print the usage block, and the test accepted the
+ narrowed behaviour. Resolved by the coordinator's decision to fix `main.c`,
+ after which the test asserts the literal `Usage:` block.
+- Minor: no multi-chunk coverage -> added `pipeline.fake.multi-chunk`;
+ the mutation above now fails.
+- Minor: stem names/scales were not checked individually -> added per-stem scale
+ validation; the swapped-name mutation above now fails.
+- Minor: invalid CLI cases could reach a real `mpv` -> stub `mpv` first in
+ `PATH`, scratch `XDG_RUNTIME_DIR`, builds use `-Werror`.
+- Minor: option order and unknown option untested -> added
+ `pipeline.fake.option-order` and `cli.unknown-option`.
+- Minor: concurrent runs could race on fixed binary paths -> binaries now live
+ in the per-run scratch, and two concurrent quick runs were verified.
+- Minor: compiler warnings in test builds were not fatal -> added `-Werror`.
+- Minor: bare-name `$0` could resolve the parent of the cwd -> the harness now
+ requires a path; verified.
+- Nits: `tail -20` -> `tail -n 20`; added the float32 `_Static_assert`; the
+ report wording was corrected.
+- Nit: `date +%s%N` is GNU-specific -> deferred; the documented target is Linux.
+
+All Major and Minor findings were addressed, and the two mutations above verify
+the new coverage. The re-review returned **pass-with-findings**: no Blocker or
+Major remains, the prior findings are resolved and mutation-verified, and the
+remaining items are the deferred GNU `date` dependency and the exit-code
+coupling already listed under Findings 3; neither blocks the commit.
+
+## Not machine-verified
+
+- Separation **quality** (bleed, artefacts, "sounds right") is **not
+ machine-verified; it requires listening**. The smoke test asserts only the
+ output contract. To listen, run
+ `./build.sh && ./stemsep -i <a 1-2 s WAV> -m demo` and compare the six stems
+ against the mix, especially guitar and piano bleed as the README warns.
+- Interrupt handling: `.part` cleanup on SIGINT/SIGTERM is not tested.
+- Valid `-p` playback and `--bpm` metronome runs need `mpv` and are not run.
+
+## Findings
+
+1. **Invalid `-p` usage block — fixed.** `main.c` now prints the usage block
+ when playback validation fails. The test asserts it. This is the only source
+ change and it was explicitly approved by the coordinator.
+2. **`scripts/check.sh` still exits 1** because `musicas/08 Hakumei...mp3` is
+ deleted in the working tree but still tracked. That is the separate task the
+ request named; the tests gate itself passes.
+3. **Exit codes are not single-sourced.** `playback.c` returns literal `2`,
+ `1`, and `127`, and `metronome.c` literal `1` and `127`, while the `EXIT_*`
+ enum lives in `main.c`. The values agree for the cases tested, and `main.c`
+ now compares playback's return to `EXIT_USAGE`, but playback still produces
+ that value as a literal. The enum is not the source of truth. Suggested
+ follow-up: move the enum to a shared header.
+4. **README documents no exit codes** for input/model/output failures, so the
+ tests pin the `EXIT_*` values by observation rather than by a documented
+ contract.
+
+## Deferred
+
+- Unit tests of internal statics (resampler, overlap-add stitching, WAV writer,
+ byte readers, MP3 framing) and the `tests/unit/` layout from the tester skill.
+- Robustness tests: truncated/corrupt/adversarial inputs, sanitizers, large
+ inputs.
+- MP3 input through the pipeline; interrupt and `.part` cleanup; valid playback
+ and metronome runs (these need `mpv`).
+- The tracked MP3 removal and the exit-code enum/README findings above.
+- `date +%s%N` remains GNU-specific; the project targets Linux, so the timing
+ helper was left as is.
diff --git a/main.c b/main.c
index 1591461..39da637 100644
--- a/main.c
+++ b/main.c
@@ -1606,7 +1606,12 @@ int main(int argc, char **argv)
return metronome_run(bpm, beats);
}
if (command.play_selection != NULL) {
- return playback_run(command.identifier, command.play_selection);
+ int status = playback_run(command.identifier, command.play_selection);
+
+ if (status == EXIT_USAGE) {
+ print_usage(argv[0]);
+ }
+ return status;
}
if (!install_signal_handlers(&error)) {
exit_code = EXIT_INTERNAL;
diff --git a/tests/run.sh b/tests/run.sh
new file mode 100755
index 0000000..483274f
--- /dev/null
+++ b/tests/run.sh
@@ -0,0 +1,505 @@
+#!/bin/sh
+# stemsep test harness.
+#
+# Usage: ./tests/run.sh [--quick] [filter]
+#
+# One line per test. --quick skips tests that need the ONNX model. A filter is
+# matched as a substring of the test name. Scratch files live in a mktemp
+# directory under build/ and are removed on exit, including on failure.
+set -u
+LC_ALL=C
+export LC_ALL
+
+case $0 in
+ */*)
+ ;;
+ *)
+ printf 'error: invoke %s by path, e.g. ./tests/run.sh\n' "$0" >&2
+ exit 2
+ ;;
+esac
+cd -- "$(dirname -- "$0")/.." || exit 1
+ROOT=$(pwd -P)
+
+BUILD=$ROOT/build
+MODEL=$ROOT/models/htdemucs_6s.onnx
+
+FIXTURE_FRAMES=44100
+MODEL_FRAMES=66150
+MULTI_CHUNK_FRAMES=400000
+STEMS="drums bass other vocals guitar piano"
+# Measured max abs error: 1.71363354e-07 at 44100 frames and 2.16066837e-07 at
+# 400000 frames (two chunks). The tolerance below is 2e-6, about nine times the
+# larger measurement, and applies to both the stem sum and each stem's scale.
+RECON_TOLERANCE=0.000002
+
+quick=0
+filter=
+for argument in "$@"; do
+ case $argument in
+ --quick)
+ quick=1
+ ;;
+ -h|--help)
+ printf 'Usage: %s [--quick] [filter]\n' "$0"
+ exit 0
+ ;;
+ -*)
+ printf 'error: unknown option %s\n' "$argument" >&2
+ exit 2
+ ;;
+ *)
+ if [ -n "$filter" ]; then
+ printf 'error: more than one filter argument\n' >&2
+ exit 2
+ fi
+ filter=$argument
+ ;;
+ esac
+done
+
+if [ "$quick" -eq 0 ] && [ ! -f "$MODEL" ]; then
+ printf 'error: %s is missing\n' "$MODEL" >&2
+ printf 'The full suite needs the ONNX model; install it as README.md says,\n' >&2
+ printf 'or run --quick.\n' >&2
+ exit 1
+fi
+
+mkdir -p "$BUILD" || exit 1
+scratch=$(mktemp -d "$BUILD/stemsep-tests.XXXXXX") || exit 1
+trap 'rm -rf "$scratch"' 0
+trap 'exit 130' 1 2 15
+
+BIN_DIR=$scratch/bin
+REAL_BIN=$BIN_DIR/stemsep-tests
+FAKE_BIN=$BIN_DIR/stemsep-tests-fake
+WAVTOOL=$BIN_DIR/wavtool
+mkdir -p "$BIN_DIR" "$scratch/stub-bin" "$scratch/runtime" || exit 1
+printf '#!/bin/sh\nexit 97\n' >"$scratch/stub-bin/mpv" || exit 1
+chmod +x "$scratch/stub-bin/mpv" || exit 1
+PATH="$scratch/stub-bin:$PATH"
+export PATH
+XDG_RUNTIME_DIR=$scratch/runtime
+export XDG_RUNTIME_DIR
+LD_LIBRARY_PATH=$ROOT/third_party/onnxruntime/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
+export LD_LIBRARY_PATH
+
+fail()
+{
+ printf '%s\n' "$*" >&2
+ exit 1
+}
+
+compile()
+{
+ description=$1
+ shift
+ output=$("$@" 2>&1) || {
+ printf 'error: cannot build %s\n' "$description" >&2
+ printf '%s\n' "$output" >&2
+ return 1
+ }
+ if [ -n "$output" ]; then
+ printf '%s\n' "$output" >&2
+ fi
+ return 0
+}
+
+build_binaries()
+{
+ compile "the fake-model test binary" \
+ gcc -std=c11 -O3 -DNDEBUG -Wall -Wextra -Wpedantic -Werror \
+ -DSTEMSEP_TEST_FAKE_MODEL -Ithird_party/dr_mp3 \
+ main.c audio.c audio_wav.c audio_mp3.c playback.c metronome.c \
+ -lm -o "$FAKE_BIN" || return 1
+ compile "the real-model test binary" \
+ gcc -std=c11 -O3 -DNDEBUG -Wall -Wextra -Wpedantic -Werror \
+ -Ithird_party/onnxruntime/include -Ithird_party/dr_mp3 \
+ main.c audio.c audio_wav.c audio_mp3.c playback.c metronome.c \
+ -Lthird_party/onnxruntime/lib -Wl,--no-as-needed -lonnxruntime \
+ -lm -ldl -pthread -o "$REAL_BIN" || return 1
+ compile "the WAV fixture tool" \
+ gcc -std=c11 -O3 -DNDEBUG -Wall -Wextra -Wpedantic -Werror \
+ -o "$WAVTOOL" tests/wavtool.c -lm || return 1
+ return 0
+}
+
+if ! build_binaries; then
+ printf 'FAIL build\n'
+ exit 1
+fi
+
+fixture=$scratch/fixture.wav
+if ! "$WAVTOOL" gen "$fixture" "$FIXTURE_FRAMES" >/dev/null 2>"$scratch/fixture.log"; then
+ printf 'FAIL build\n'
+ printf 'error: cannot generate the test fixture\n' >&2
+ sed 's/^/ /' "$scratch/fixture.log" >&2
+ exit 1
+fi
+
+passed=0
+failed=0
+skipped=0
+selected=0
+
+run_test()
+{
+ name=$1
+ function_name=$2
+ needs_model=${3:-no}
+
+ case $name in
+ *"$filter"*)
+ ;;
+ *)
+ return 0
+ ;;
+ esac
+ selected=$((selected + 1))
+ if [ "$needs_model" = yes ] && [ "$quick" -eq 1 ]; then
+ printf 'SKIP %s (--quick skips tests that need the ONNX model)\n' "$name"
+ skipped=$((skipped + 1))
+ return 0
+ fi
+ case_dir=$scratch/cases/$name
+ mkdir -p "$case_dir" || {
+ printf 'FAIL %s (cannot create its case directory)\n' "$name"
+ failed=$((failed + 1))
+ return 0
+ }
+ if (cd "$case_dir" && "$function_name") \
+ >"$case_dir/stdout.log" 2>"$case_dir/stderr.log"; then
+ printf 'PASS %s\n' "$name"
+ passed=$((passed + 1))
+ if [ -f "$scratch/info.$name" ]; then
+ sed 's/^/ /' "$scratch/info.$name"
+ fi
+ else
+ printf 'FAIL %s\n' "$name"
+ failed=$((failed + 1))
+ if [ -s "$case_dir/stderr.log" ]; then
+ tail -n 20 "$case_dir/stderr.log" | sed 's/^/ /'
+ fi
+ fi
+}
+
+run_expect_usage()
+{
+ label=$1
+ shift
+ "$REAL_BIN" "$@" >stdout.log 2>stderr.log
+ status=$?
+ if [ "$status" -ne 2 ]; then
+ fail "$label: expected exit 2, got $status"
+ fi
+ if ! grep -q '^Usage:' stderr.log; then
+ fail "$label: usage text missing"
+ fi
+ if ! grep -q -e '-i <audio_file> -m <music_identifier>' stderr.log; then
+ fail "$label: separation usage line missing"
+ fi
+}
+
+separate_fake()
+{
+ "$FAKE_BIN" -i "$fixture" -m song >stdout.log 2>stderr.log
+ status=$?
+ if [ "$status" -ne 0 ]; then
+ fail "fake-model separation failed with exit $status: $(tail -n 2 stderr.log)"
+ fi
+}
+
+test_cli_no_arguments()
+{
+ "$REAL_BIN" >stdout.log 2>stderr.log
+ status=$?
+ if [ "$status" -ne 2 ]; then
+ fail "expected exit 2, got $status"
+ fi
+ grep -q '^Usage:' stderr.log || fail "usage text missing"
+ grep -q -e '-i <audio_file> -m <music_identifier>' stderr.log ||
+ fail "separation usage line missing"
+ grep -q -e "option '-m' is required" stderr.log || fail "diagnostic missing"
+}
+
+test_cli_bpm_conflicts()
+{
+ run_expect_usage "--bpm with -i" --bpm 120 -i "$fixture"
+ run_expect_usage "--bpm with -m" --bpm 120 -m song
+ run_expect_usage "--bpm with -p" --bpm 120 -p d
+}
+
+test_cli_missing_identifier()
+{
+ run_expect_usage "separation without -m" -i "$fixture"
+ run_expect_usage "playback without -m" -p d
+}
+
+test_cli_invalid_play_selection()
+{
+ for letter in x D 1; do
+ "$REAL_BIN" -m song -p "$letter" >stdout.log 2>stderr.log
+ status=$?
+ if [ "$status" -ne 2 ]; then
+ fail "-p $letter: expected exit 2, got $status"
+ fi
+ grep -q '^Usage:' stderr.log || fail "-p $letter: usage text missing"
+ grep -q 'invalid -p selection' stderr.log ||
+ fail "-p $letter: diagnostic missing"
+ done
+}
+
+test_cli_unknown_option()
+{
+ run_expect_usage "unknown option" --nope
+}
+
+test_cli_invalid_identifier()
+{
+ run_expect_usage "identifier with a slash" -m 'a/b' -p d
+ run_expect_usage "identifier with a dot" -m 'a.b' -p d
+ run_expect_usage "empty identifier" -m '' -p d
+}
+
+test_cli_time_signature_range()
+{
+ run_expect_usage "beat count below 2" --bpm 120 -t 1
+ run_expect_usage "beat count above 16" --bpm 120 -t 17
+ run_expect_usage "time signature without --bpm" -t 4
+}
+
+test_cli_bpm_range()
+{
+ run_expect_usage "tempo below 1" --bpm 0
+ run_expect_usage "tempo above 1000" --bpm 1001
+ run_expect_usage "tempo above 1000 with decimals" --bpm 1000.5
+ run_expect_usage "non-numeric tempo" --bpm fast
+}
+
+test_cli_missing_input()
+{
+ "$REAL_BIN" -i "$PWD/absent.wav" -m song >stdout.log 2>stderr.log
+ status=$?
+ if [ "$status" -ne 3 ]; then
+ fail "expected exit 3, got $status"
+ fi
+ grep -q 'cannot access input audio' stderr.log || fail "diagnostic missing"
+ [ ! -e song_stems ] || fail "an output directory was created for a missing input"
+}
+
+test_cli_missing_model()
+{
+ STEMSEP_MODEL="$PWD/absent.onnx" "$REAL_BIN" -i "$fixture" -m song \
+ >stdout.log 2>stderr.log
+ status=$?
+ if [ "$status" -ne 4 ]; then
+ fail "expected exit 4, got $status"
+ fi
+ grep -q 'ONNX model' stderr.log || fail "diagnostic missing"
+ [ ! -e song_stems ] || fail "an output directory was created without a model"
+}
+
+test_fake_six_stems()
+{
+ separate_fake
+ [ -d song_stems ] || fail "song_stems is missing"
+ expected=$(printf '%s\n' song_bass.wav song_drums.wav song_guitar.wav \
+ song_other.wav song_piano.wav song_vocals.wav | sort)
+ actual=$(ls -A song_stems | sort)
+ if [ "$actual" != "$expected" ]; then
+ fail "unexpected output files: $(printf '%s ' $actual)"
+ fi
+ if find song_stems -name '*.part' | grep -q .; then
+ fail "leftover .part files"
+ fi
+}
+
+test_fake_wav_contract()
+{
+ separate_fake
+ for stem in $STEMS; do
+ output=$("$WAVTOOL" inspect "song_stems/song_$stem.wav" "$FIXTURE_FRAMES" 2>&1) ||
+ fail "song_$stem.wav: $output"
+ expected="format=3 channels=2 rate=44100 bits=32 frames=$FIXTURE_FRAMES finite=yes"
+ if [ "$output" != "$expected" ]; then
+ fail "song_$stem.wav: $output"
+ fi
+ done
+}
+
+test_fake_reconstruction()
+{
+ separate_fake
+ output=$("$WAVTOOL" recon "$RECON_TOLERANCE" "$fixture" song_stems song 2>&1) ||
+ fail "reconstruction check failed: $output"
+ printf 'reconstruction %s (tolerance %s)\n' "$output" "$RECON_TOLERANCE" \
+ >"$scratch/info.pipeline.fake.reconstruction"
+}
+
+test_fake_deterministic()
+{
+ mkdir -p run-a run-b || fail "cannot create the run directories"
+ (cd run-a && "$FAKE_BIN" -i "$fixture" -m song >stdout.log 2>stderr.log) ||
+ fail "the first run failed"
+ (cd run-b && "$FAKE_BIN" -i "$fixture" -m song >stdout.log 2>stderr.log) ||
+ fail "the second run failed"
+ for stem in $STEMS; do
+ cmp -s "run-a/song_stems/song_$stem.wav" "run-b/song_stems/song_$stem.wav" ||
+ fail "song_$stem.wav differs between two runs"
+ done
+}
+
+test_fake_existing_directory()
+{
+ mkdir song_stems || fail "cannot create the existing output directory"
+ printf 'keep\n' >song_stems/keep.txt
+ printf 'sentinel\n' >song_stems/song_drums.wav
+ before=$(cd song_stems && cksum keep.txt song_drums.wav | sort)
+ "$FAKE_BIN" -i "$fixture" -m song >stdout.log 2>stderr.log
+ status=$?
+ if [ "$status" -ne 5 ]; then
+ fail "expected exit 5, got $status"
+ fi
+ after=$(cd song_stems && cksum keep.txt song_drums.wav | sort)
+ if [ "$before" != "$after" ]; then
+ fail "the existing output directory contents changed"
+ fi
+ entries=$(ls -A song_stems | sort)
+ expected=$(printf '%s\n' keep.txt song_drums.wav | sort)
+ if [ "$entries" != "$expected" ]; then
+ fail "the existing output directory gained or lost files"
+ fi
+ if find song_stems -name '*.part' | grep -q .; then
+ fail "leftover .part files"
+ fi
+}
+
+test_fake_failure_cleanup()
+{
+ (
+ trap '' XFSZ
+ ulimit -f 1
+ exec "$FAKE_BIN" -i "$fixture" -m song >/dev/null 2>&1
+ )
+ status=$?
+ if [ "$status" -ne 5 ]; then
+ fail "expected exit 5 after a write failure, got $status"
+ fi
+ [ ! -e song_stems ] || fail "the failed run left song_stems behind"
+}
+
+test_fake_option_order()
+{
+ "$FAKE_BIN" -m song -i "$fixture" >stdout.log 2>stderr.log
+ status=$?
+ if [ "$status" -ne 0 ]; then
+ fail "options in reverse order failed with exit $status: $(tail -n 2 stderr.log)"
+ fi
+ [ -d song_stems ] || fail "song_stems is missing"
+ count=$(ls -A song_stems | wc -l | tr -d '[:space:]')
+ if [ "$count" -ne 6 ]; then
+ fail "expected six stems, found $count"
+ fi
+}
+
+test_fake_multi_chunk()
+{
+ long_fixture=$scratch/multi-chunk.wav
+ "$WAVTOOL" gen "$long_fixture" "$MULTI_CHUNK_FRAMES" >/dev/null ||
+ fail "cannot generate the multi-chunk fixture"
+ "$FAKE_BIN" -i "$long_fixture" -m long >stdout.log 2>stderr.log
+ status=$?
+ if [ "$status" -ne 0 ]; then
+ fail "multi-chunk separation failed with exit $status: $(tail -n 3 stderr.log)"
+ fi
+ grep -q 'chunk 2/2' stderr.log || fail "a second chunk was not processed"
+ [ -d long_stems ] || fail "long_stems is missing"
+ expected=$(printf '%s\n' long_bass.wav long_drums.wav long_guitar.wav \
+ long_other.wav long_piano.wav long_vocals.wav | sort)
+ actual=$(ls -A long_stems | sort)
+ if [ "$actual" != "$expected" ]; then
+ fail "unexpected output files: $(printf '%s ' $actual)"
+ fi
+ expected_line="format=3 channels=2 rate=44100 bits=32 frames=$MULTI_CHUNK_FRAMES finite=yes"
+ for stem in $STEMS; do
+ output=$("$WAVTOOL" inspect "long_stems/long_$stem.wav" \
+ "$MULTI_CHUNK_FRAMES" 2>&1) || fail "long_$stem.wav: $output"
+ if [ "$output" != "$expected_line" ]; then
+ fail "long_$stem.wav: $output"
+ fi
+ done
+ if find long_stems -name '*.part' | grep -q .; then
+ fail "leftover .part files"
+ fi
+ output=$("$WAVTOOL" recon "$RECON_TOLERANCE" "$long_fixture" long_stems long 2>&1) ||
+ fail "multi-chunk reconstruction check failed: $output"
+ printf 'multi-chunk reconstruction %s (tolerance %s)\n' "$output" \
+ "$RECON_TOLERANCE" >"$scratch/info.pipeline.fake.multi-chunk"
+}
+
+test_model_smoke()
+{
+ [ -f "$MODEL" ] || fail "the ONNX model is missing"
+ model_fixture=$scratch/model-fixture.wav
+ "$WAVTOOL" gen "$model_fixture" "$MODEL_FRAMES" >/dev/null ||
+ fail "cannot generate the model fixture"
+ start=$(date +%s%N)
+ STEMSEP_MODEL="$MODEL" "$REAL_BIN" -i "$model_fixture" -m smoke \
+ >stdout.log 2>stderr.log
+ status=$?
+ end=$(date +%s%N)
+ milliseconds=$(( (end - start) / 1000000 ))
+ if [ "$status" -ne 0 ]; then
+ fail "model separation failed with exit $status: $(tail -n 3 stderr.log)"
+ fi
+ [ -d smoke_stems ] || fail "smoke_stems is missing"
+ expected=$(printf '%s\n' smoke_bass.wav smoke_drums.wav smoke_guitar.wav \
+ smoke_other.wav smoke_piano.wav smoke_vocals.wav | sort)
+ actual=$(ls -A smoke_stems | sort)
+ if [ "$actual" != "$expected" ]; then
+ fail "unexpected output files: $(printf '%s ' $actual)"
+ fi
+ for stem in $STEMS; do
+ output=$("$WAVTOOL" inspect "smoke_stems/smoke_$stem.wav" "$MODEL_FRAMES" 2>&1) ||
+ fail "smoke_$stem.wav: $output"
+ expected_line="format=3 channels=2 rate=44100 bits=32 frames=$MODEL_FRAMES finite=yes"
+ if [ "$output" != "$expected_line" ]; then
+ fail "smoke_$stem.wav: $output"
+ fi
+ done
+ if find smoke_stems -name '*.part' | grep -q .; then
+ fail "leftover .part files"
+ fi
+ printf 'model separation: %s ms for %s frames, six stems\n' \
+ "$milliseconds" "$MODEL_FRAMES" >"$scratch/info.pipeline.model.smoke"
+}
+
+run_test cli.no-arguments test_cli_no_arguments
+run_test cli.bpm-conflicts test_cli_bpm_conflicts
+run_test cli.missing-identifier test_cli_missing_identifier
+run_test cli.invalid-play-selection test_cli_invalid_play_selection
+run_test cli.invalid-identifier test_cli_invalid_identifier
+run_test cli.time-signature-range test_cli_time_signature_range
+run_test cli.bpm-range test_cli_bpm_range
+run_test cli.unknown-option test_cli_unknown_option
+run_test cli.missing-input test_cli_missing_input
+run_test cli.missing-model test_cli_missing_model
+run_test pipeline.fake.six-stems test_fake_six_stems
+run_test pipeline.fake.wav-contract test_fake_wav_contract
+run_test pipeline.fake.reconstruction test_fake_reconstruction
+run_test pipeline.fake.deterministic test_fake_deterministic
+run_test pipeline.fake.existing-directory test_fake_existing_directory
+run_test pipeline.fake.failure-cleanup test_fake_failure_cleanup
+run_test pipeline.fake.option-order test_fake_option_order
+run_test pipeline.fake.multi-chunk test_fake_multi_chunk
+run_test pipeline.model.smoke test_model_smoke yes
+
+printf '\n%d passed, %d failed, %d skipped\n' "$passed" "$failed" "$skipped"
+if [ "$selected" -eq 0 ]; then
+ printf 'error: no test matched filter "%s"\n' "$filter" >&2
+ exit 1
+fi
+if [ "$failed" -ne 0 ]; then
+ exit 1
+fi
+exit 0
diff --git a/tests/wavtool.c b/tests/wavtool.c
new file mode 100644
index 0000000..6a83cf6
--- /dev/null
+++ b/tests/wavtool.c
@@ -0,0 +1,664 @@
+#define _FILE_OFFSET_BITS 64
+#define _POSIX_C_SOURCE 200809L
+
+#include <errno.h>
+#include <inttypes.h>
+#include <math.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define WAV_CHANNELS 2U
+#define WAV_SAMPLE_RATE UINT32_C(44100)
+#define WAV_BLOCK_FRAMES 4096U
+#define WAV_MAX_FRAMES UINT64_C(2646000)
+#define WAV_HEADER_BYTES 44U
+#define FAKE_STEM_SUM_SCALE 3.5
+
+#ifndef M_PI
+#define M_PI 3.14159265358979323846264338327950288
+#endif
+
+_Static_assert(sizeof(float) == 4, "wavtool requires 32-bit float");
+
+static const char *const STEM_NAMES[] = {
+ "drums", "bass", "other", "vocals", "guitar", "piano"
+};
+
+typedef struct {
+ FILE *file;
+ uint16_t format_tag;
+ uint16_t channels;
+ uint32_t sample_rate;
+ uint16_t bits;
+ uint16_t block_align;
+ uint64_t frames;
+ uint64_t data_offset;
+ uint64_t data_bytes;
+ uint64_t file_size;
+} Wav;
+
+static uint16_t read_u16_le(const uint8_t *bytes)
+{
+ return (uint16_t)((uint16_t)bytes[0] | ((uint16_t)bytes[1] << 8));
+}
+
+static uint32_t read_u32_le(const uint8_t *bytes)
+{
+ return (uint32_t)bytes[0] | ((uint32_t)bytes[1] << 8) |
+ ((uint32_t)bytes[2] << 16) | ((uint32_t)bytes[3] << 24);
+}
+
+static void store_u16_le(uint8_t *bytes, uint16_t value)
+{
+ bytes[0] = (uint8_t)(value & 0xFFU);
+ bytes[1] = (uint8_t)((value >> 8) & 0xFFU);
+}
+
+static void store_u32_le(uint8_t *bytes, uint32_t value)
+{
+ bytes[0] = (uint8_t)(value & 0xFFU);
+ bytes[1] = (uint8_t)((value >> 8) & 0xFFU);
+ bytes[2] = (uint8_t)((value >> 16) & 0xFFU);
+ bytes[3] = (uint8_t)((value >> 24) & 0xFFU);
+}
+
+static bool parse_u64(const char *text, uint64_t *value)
+{
+ char *end = NULL;
+ unsigned long long parsed;
+
+ if (text == NULL || text[0] == '\0') {
+ return false;
+ }
+ errno = 0;
+ parsed = strtoull(text, &end, 10);
+ if (end == text || *end != '\0' || errno == ERANGE) {
+ return false;
+ }
+ *value = (uint64_t)parsed;
+ return true;
+}
+
+static bool parse_double(const char *text, double *value)
+{
+ char *end = NULL;
+ double parsed;
+
+ if (text == NULL || text[0] == '\0') {
+ return false;
+ }
+ errno = 0;
+ parsed = strtod(text, &end);
+ if (end == text || *end != '\0' || errno == ERANGE || !isfinite(parsed)) {
+ return false;
+ }
+ *value = parsed;
+ return true;
+}
+
+static bool wav_parse(Wav *wav, const char *path, char *message,
+ size_t message_size)
+{
+ uint8_t header[12];
+ uint8_t chunk_header[8];
+ uint8_t format_data[40];
+ uint64_t riff_end;
+ uint64_t position = 12U;
+ bool found_format = false;
+ bool found_data = false;
+
+ if (wav->file_size < sizeof(header) ||
+ fseeko(wav->file, 0, SEEK_SET) != 0 ||
+ fread(header, 1U, sizeof(header), wav->file) != sizeof(header)) {
+ (void)snprintf(message, message_size, "'%s' is too short to be a WAV file",
+ path);
+ return false;
+ }
+ if (memcmp(header, "RIFF", 4U) != 0 || memcmp(header + 8U, "WAVE", 4U) != 0) {
+ (void)snprintf(message, message_size, "'%s' is not a RIFF/WAVE file", path);
+ return false;
+ }
+ riff_end = 8U + (uint64_t)read_u32_le(header + 4U);
+ if (riff_end != wav->file_size) {
+ (void)snprintf(message, message_size,
+ "'%s': RIFF size does not match the physical file size", path);
+ return false;
+ }
+
+ while (position + 8U <= riff_end) {
+ uint32_t chunk_size;
+ uint64_t payload;
+ uint64_t next;
+
+ if (fseeko(wav->file, (off_t)position, SEEK_SET) != 0 ||
+ fread(chunk_header, 1U, sizeof(chunk_header), wav->file) !=
+ sizeof(chunk_header)) {
+ (void)snprintf(message, message_size,
+ "'%s': cannot read a chunk header", path);
+ return false;
+ }
+ chunk_size = read_u32_le(chunk_header + 4U);
+ payload = position + 8U;
+ next = payload + (uint64_t)chunk_size + (uint64_t)(chunk_size & 1U);
+ if (next > riff_end) {
+ (void)snprintf(message, message_size,
+ "'%s': a chunk extends beyond the RIFF boundary", path);
+ return false;
+ }
+ if (memcmp(chunk_header, "fmt ", 4U) == 0) {
+ size_t to_read;
+ uint16_t format_tag;
+ uint16_t channels;
+ uint32_t sample_rate;
+ uint32_t byte_rate;
+ uint16_t block_align;
+ uint16_t bits;
+
+ if (found_format) {
+ (void)snprintf(message, message_size,
+ "'%s' contains more than one fmt chunk", path);
+ return false;
+ }
+ if (chunk_size < 16U) {
+ (void)snprintf(message, message_size,
+ "'%s': fmt chunk is smaller than 16 bytes", path);
+ return false;
+ }
+ to_read = chunk_size < sizeof(format_data) ? (size_t)chunk_size :
+ sizeof(format_data);
+ if (fseeko(wav->file, (off_t)payload, SEEK_SET) != 0 ||
+ fread(format_data, 1U, to_read, wav->file) != to_read) {
+ (void)snprintf(message, message_size,
+ "'%s': cannot read the fmt chunk", path);
+ return false;
+ }
+ format_tag = read_u16_le(format_data);
+ channels = read_u16_le(format_data + 2U);
+ sample_rate = read_u32_le(format_data + 4U);
+ byte_rate = read_u32_le(format_data + 8U);
+ block_align = read_u16_le(format_data + 12U);
+ bits = read_u16_le(format_data + 14U);
+ if (format_tag != 1U && format_tag != 3U) {
+ (void)snprintf(message, message_size,
+ "'%s': unsupported WAV format tag 0x%04x", path,
+ (unsigned)format_tag);
+ return false;
+ }
+ if (format_tag == 1U && bits != 16U) {
+ (void)snprintf(message, message_size,
+ "'%s': PCM samples must be 16-bit, found %u bits", path,
+ (unsigned)bits);
+ return false;
+ }
+ if (format_tag == 3U && bits != 32U) {
+ (void)snprintf(message, message_size,
+ "'%s': float samples must be 32-bit, found %u bits", path,
+ (unsigned)bits);
+ return false;
+ }
+ if (channels != 1U && channels != 2U) {
+ (void)snprintf(message, message_size,
+ "'%s': expected one or two channels, found %u", path,
+ (unsigned)channels);
+ return false;
+ }
+ if (block_align != channels * (bits / 8U)) {
+ (void)snprintf(message, message_size,
+ "'%s': invalid block alignment", path);
+ return false;
+ }
+ if (byte_rate != sample_rate * (uint32_t)block_align) {
+ (void)snprintf(message, message_size,
+ "'%s': invalid byte rate", path);
+ return false;
+ }
+ wav->format_tag = format_tag;
+ wav->channels = channels;
+ wav->sample_rate = sample_rate;
+ wav->bits = bits;
+ wav->block_align = block_align;
+ found_format = true;
+ } else if (memcmp(chunk_header, "data", 4U) == 0) {
+ if (found_data) {
+ (void)snprintf(message, message_size,
+ "'%s' contains more than one data chunk", path);
+ return false;
+ }
+ wav->data_offset = payload;
+ wav->data_bytes = chunk_size;
+ found_data = true;
+ }
+ position = next;
+ }
+ if (position != riff_end) {
+ (void)snprintf(message, message_size,
+ "'%s' ends with an incomplete chunk header", path);
+ return false;
+ }
+ if (!found_format) {
+ (void)snprintf(message, message_size, "'%s' has no fmt chunk", path);
+ return false;
+ }
+ if (!found_data) {
+ (void)snprintf(message, message_size, "'%s' has no data chunk", path);
+ return false;
+ }
+ if (wav->data_bytes == 0U ||
+ (wav->data_bytes % (uint64_t)wav->block_align) != 0U) {
+ (void)snprintf(message, message_size,
+ "'%s': data chunk is empty or ends with a partial frame", path);
+ return false;
+ }
+ wav->frames = wav->data_bytes / (uint64_t)wav->block_align;
+ if (wav->frames > WAV_MAX_FRAMES) {
+ (void)snprintf(message, message_size, "'%s' is longer than %" PRIu64
+ " frames", path, WAV_MAX_FRAMES);
+ return false;
+ }
+ return true;
+}
+
+static bool wav_open(const char *path, Wav *wav, char *message,
+ size_t message_size)
+{
+ off_t end;
+
+ memset(wav, 0, sizeof(*wav));
+ wav->file = fopen(path, "rb");
+ if (wav->file == NULL) {
+ (void)snprintf(message, message_size, "cannot open '%s': %s", path,
+ strerror(errno));
+ return false;
+ }
+ if (fseeko(wav->file, 0, SEEK_END) != 0) {
+ (void)snprintf(message, message_size, "cannot inspect '%s': %s", path,
+ strerror(errno));
+ (void)fclose(wav->file);
+ wav->file = NULL;
+ return false;
+ }
+ end = ftello(wav->file);
+ if (end < 0) {
+ (void)snprintf(message, message_size, "cannot determine the size of '%s': %s",
+ path, strerror(errno));
+ (void)fclose(wav->file);
+ wav->file = NULL;
+ return false;
+ }
+ wav->file_size = (uint64_t)end;
+ if (!wav_parse(wav, path, message, message_size)) {
+ (void)fclose(wav->file);
+ wav->file = NULL;
+ return false;
+ }
+ return true;
+}
+
+static void wav_close(Wav *wav)
+{
+ if (wav->file != NULL) {
+ (void)fclose(wav->file);
+ wav->file = NULL;
+ }
+}
+
+static bool wav_read_frames(Wav *wav, uint64_t frame_offset, size_t frame_count,
+ float *stereo, char *message, size_t message_size)
+{
+ size_t frame_bytes = wav->block_align;
+ size_t sample_bytes = wav->bits / 8U;
+ size_t bytes = frame_count * frame_bytes;
+ uint8_t *raw;
+ size_t frame;
+ unsigned channel;
+
+ if (bytes == 0U) {
+ return true;
+ }
+ if (frame_offset + frame_count > wav->frames) {
+ (void)snprintf(message, message_size, "read beyond the end of the WAV data");
+ return false;
+ }
+ raw = malloc(bytes);
+ if (raw == NULL) {
+ (void)snprintf(message, message_size, "cannot allocate %zu bytes: %s", bytes,
+ strerror(errno));
+ return false;
+ }
+ if (fseeko(wav->file,
+ (off_t)(wav->data_offset + frame_offset * (uint64_t)frame_bytes),
+ SEEK_SET) != 0 ||
+ fread(raw, 1U, bytes, wav->file) != bytes) {
+ (void)snprintf(message, message_size, "cannot read the WAV data: %s",
+ strerror(errno));
+ free(raw);
+ return false;
+ }
+ for (frame = 0U; frame < frame_count; ++frame) {
+ for (channel = 0U; channel < wav->channels; ++channel) {
+ const uint8_t *source = raw + frame * frame_bytes + channel * sample_bytes;
+ float sample;
+ if (wav->format_tag == 1U) {
+ float value = (float)(int16_t)read_u16_le(source);
+ sample = value / 32768.0F;
+ } else {
+ uint32_t encoded = read_u32_le(source);
+ memcpy(&sample, &encoded, sizeof(sample));
+ if (!isfinite(sample)) {
+ (void)snprintf(message, message_size,
+ "WAV contains a NaN or infinite float sample");
+ free(raw);
+ return false;
+ }
+ }
+ stereo[frame * WAV_CHANNELS + channel] = sample;
+ }
+ }
+ free(raw);
+ return true;
+}
+
+static bool check_stereo(const Wav *wav, uint16_t format_tag, char *message,
+ size_t message_size)
+{
+ if (wav->format_tag != format_tag || wav->channels != WAV_CHANNELS ||
+ wav->sample_rate != WAV_SAMPLE_RATE) {
+ (void)snprintf(message, message_size,
+ "expected %s stereo %u Hz, found tag %u, %u channel(s), %u Hz",
+ format_tag == 1U ? "16-bit PCM" : "32-bit float",
+ WAV_SAMPLE_RATE, (unsigned)wav->format_tag,
+ (unsigned)wav->channels, wav->sample_rate);
+ return false;
+ }
+ return true;
+}
+
+static bool generate(const char *path, uint64_t frames)
+{
+ uint8_t header[WAV_HEADER_BYTES];
+ int16_t block[WAV_BLOCK_FRAMES * WAV_CHANNELS];
+ uint64_t frame_bytes;
+ uint64_t data_bytes;
+ FILE *file;
+ uint64_t offset = 0U;
+
+ frame_bytes = (uint64_t)WAV_CHANNELS * 2U;
+ if (frames == 0U || frames > WAV_MAX_FRAMES ||
+ frames > (UINT64_C(0xFFFFFFFF) - WAV_HEADER_BYTES) / frame_bytes) {
+ fprintf(stderr, "wavtool: invalid frame count for a generated WAV\n");
+ return false;
+ }
+ data_bytes = frames * frame_bytes;
+ memset(header, 0, sizeof(header));
+ memcpy(header, "RIFF", 4U);
+ store_u32_le(header + 4U, (uint32_t)(data_bytes + WAV_HEADER_BYTES - 8U));
+ memcpy(header + 8U, "WAVE", 4U);
+ memcpy(header + 12U, "fmt ", 4U);
+ store_u32_le(header + 16U, 16U);
+ store_u16_le(header + 20U, 1U);
+ store_u16_le(header + 22U, WAV_CHANNELS);
+ store_u32_le(header + 24U, WAV_SAMPLE_RATE);
+ store_u32_le(header + 28U, WAV_SAMPLE_RATE * WAV_CHANNELS * 2U);
+ store_u16_le(header + 32U, WAV_CHANNELS * 2U);
+ store_u16_le(header + 34U, 16U);
+ memcpy(header + 36U, "data", 4U);
+ store_u32_le(header + 40U, (uint32_t)data_bytes);
+
+ file = fopen(path, "wb");
+ if (file == NULL) {
+ fprintf(stderr, "wavtool: cannot create '%s': %s\n", path, strerror(errno));
+ return false;
+ }
+ if (fwrite(header, 1U, sizeof(header), file) != sizeof(header)) {
+ fprintf(stderr, "wavtool: cannot write '%s': %s\n", path, strerror(errno));
+ (void)fclose(file);
+ return false;
+ }
+ while (offset < frames) {
+ size_t count = (size_t)(frames - offset);
+ size_t index;
+ if (count > WAV_BLOCK_FRAMES) {
+ count = WAV_BLOCK_FRAMES;
+ }
+ for (index = 0U; index < count; ++index) {
+ uint64_t position = offset + index;
+ double seconds = (double)position / (double)WAV_SAMPLE_RATE;
+ double left = 0.5 * sin(2.0 * M_PI * 440.0 * seconds) +
+ 0.25 * sin(2.0 * M_PI * 1320.0 * seconds);
+ double right = 0.5 * sin(2.0 * M_PI * 523.25 * seconds) -
+ 0.25 * sin(2.0 * M_PI * 110.0 * seconds);
+ long quantized_left = lrint(left * 32767.0);
+ long quantized_right = lrint(right * 32767.0);
+ store_u16_le((uint8_t *)&block[index * WAV_CHANNELS],
+ (uint16_t)((uint32_t)quantized_left & 0xFFFFU));
+ store_u16_le((uint8_t *)&block[index * WAV_CHANNELS + 1U],
+ (uint16_t)((uint32_t)quantized_right & 0xFFFFU));
+ }
+ if (fwrite(block, sizeof(int16_t), count * WAV_CHANNELS, file) !=
+ count * WAV_CHANNELS) {
+ fprintf(stderr, "wavtool: cannot write '%s': %s\n", path, strerror(errno));
+ (void)fclose(file);
+ return false;
+ }
+ offset += count;
+ }
+ if (fclose(file) != 0) {
+ fprintf(stderr, "wavtool: cannot close '%s': %s\n", path, strerror(errno));
+ return false;
+ }
+ printf("frames=%" PRIu64 " rate=%u channels=%u format=1 bits=16\n", frames,
+ (unsigned)WAV_SAMPLE_RATE, (unsigned)WAV_CHANNELS);
+ return true;
+}
+
+static bool inspect(const char *path, uint64_t expected_frames)
+{
+ Wav wav;
+ char message[256] = "";
+ float block[WAV_BLOCK_FRAMES * WAV_CHANNELS];
+ uint64_t offset = 0U;
+
+ if (!wav_open(path, &wav, message, sizeof(message))) {
+ fprintf(stderr, "wavtool: %s\n", message);
+ return false;
+ }
+ if (!check_stereo(&wav, 3U, message, sizeof(message)) ||
+ wav.bits != 32U || wav.frames != expected_frames) {
+ if (message[0] == '\0') {
+ (void)snprintf(message, sizeof(message),
+ "expected %" PRIu64 " frames, found %" PRIu64,
+ expected_frames, wav.frames);
+ }
+ fprintf(stderr, "wavtool: '%s': %s\n", path, message);
+ wav_close(&wav);
+ return false;
+ }
+ if (wav.data_offset + wav.data_bytes != wav.file_size) {
+ fprintf(stderr, "wavtool: '%s': trailing bytes after the data chunk\n", path);
+ wav_close(&wav);
+ return false;
+ }
+ while (offset < wav.frames) {
+ size_t count = (size_t)(wav.frames - offset);
+ if (count > WAV_BLOCK_FRAMES) {
+ count = WAV_BLOCK_FRAMES;
+ }
+ if (!wav_read_frames(&wav, offset, count, block, message, sizeof(message))) {
+ fprintf(stderr, "wavtool: '%s': %s\n", path, message);
+ wav_close(&wav);
+ return false;
+ }
+ offset += count;
+ }
+ wav_close(&wav);
+ printf("format=3 channels=2 rate=44100 bits=32 frames=%" PRIu64 " finite=yes\n",
+ wav.frames);
+ return true;
+}
+
+static bool stem_path(char *path, size_t path_size, const char *directory,
+ const char *identifier, const char *stem)
+{
+ int written = snprintf(path, path_size, "%s/%s_%s.wav", directory, identifier,
+ stem);
+
+ if (written < 0 || (size_t)written >= path_size) {
+ fprintf(stderr, "wavtool: test output path is too long\n");
+ return false;
+ }
+ return true;
+}
+
+static bool reconstruction(const char *tolerance_text, const char *input_path,
+ const char *directory, const char *identifier)
+{
+ Wav input;
+ Wav stems[6];
+ char message[256] = "";
+ char path[4096];
+ double tolerance;
+ double maximum = 0.0;
+ double scale_maximum = 0.0;
+ unsigned worst_stem = 0U;
+ float input_block[WAV_BLOCK_FRAMES * WAV_CHANNELS];
+ float stem_block[WAV_BLOCK_FRAMES * WAV_CHANNELS];
+ double accumulated[WAV_BLOCK_FRAMES * WAV_CHANNELS];
+ uint64_t offset = 0U;
+ unsigned stem;
+ bool ok = false;
+
+ if (!parse_double(tolerance_text, &tolerance) || tolerance < 0.0) {
+ fprintf(stderr, "wavtool: invalid tolerance '%s'\n", tolerance_text);
+ return false;
+ }
+ memset(stems, 0, sizeof(stems));
+ if (!wav_open(input_path, &input, message, sizeof(message))) {
+ fprintf(stderr, "wavtool: %s\n", message);
+ return false;
+ }
+ if (!check_stereo(&input, 1U, message, sizeof(message)) ||
+ input.bits != 16U) {
+ fprintf(stderr, "wavtool: '%s': %s\n", input_path, message);
+ wav_close(&input);
+ return false;
+ }
+ for (stem = 0U; stem < 6U; ++stem) {
+ if (!stem_path(path, sizeof(path), directory, identifier, STEM_NAMES[stem])) {
+ goto cleanup;
+ }
+ if (!wav_open(path, &stems[stem], message, sizeof(message))) {
+ fprintf(stderr, "wavtool: %s\n", message);
+ goto cleanup;
+ }
+ if (!check_stereo(&stems[stem], 3U, message, sizeof(message)) ||
+ stems[stem].bits != 32U || stems[stem].frames != input.frames) {
+ if (message[0] == '\0') {
+ (void)snprintf(message, sizeof(message),
+ "expected %" PRIu64 " frames, found %" PRIu64,
+ input.frames, stems[stem].frames);
+ }
+ fprintf(stderr, "wavtool: '%s': %s\n", path, message);
+ goto cleanup;
+ }
+ }
+ while (offset < input.frames) {
+ size_t count = (size_t)(input.frames - offset);
+ size_t sample;
+ if (count > WAV_BLOCK_FRAMES) {
+ count = WAV_BLOCK_FRAMES;
+ }
+ if (!wav_read_frames(&input, offset, count, input_block, message,
+ sizeof(message))) {
+ fprintf(stderr, "wavtool: %s\n", message);
+ goto cleanup;
+ }
+ memset(accumulated, 0, count * WAV_CHANNELS * sizeof(accumulated[0]));
+ for (stem = 0U; stem < 6U; ++stem) {
+ double scale = (double)(stem + 1U) / 6.0;
+ if (!wav_read_frames(&stems[stem], offset, count, stem_block, message,
+ sizeof(message))) {
+ fprintf(stderr, "wavtool: %s\n", message);
+ goto cleanup;
+ }
+ for (sample = 0U; sample < count * WAV_CHANNELS; ++sample) {
+ double expected = scale * (double)input_block[sample];
+ double error = fabs((double)stem_block[sample] - expected);
+ if (error > scale_maximum) {
+ scale_maximum = error;
+ worst_stem = stem;
+ }
+ accumulated[sample] += (double)stem_block[sample];
+ }
+ }
+ for (sample = 0U; sample < count * WAV_CHANNELS; ++sample) {
+ double reference = FAKE_STEM_SUM_SCALE * (double)input_block[sample];
+ double error = fabs(accumulated[sample] - reference);
+ if (error > maximum) {
+ maximum = error;
+ }
+ }
+ offset += count;
+ }
+ printf("reconstruction_max_abs_error=%.9g stem_scale_max_abs_error=%.9g"
+ " frames=%" PRIu64 "\n",
+ maximum, scale_maximum, input.frames);
+ if (maximum > tolerance) {
+ fprintf(stderr,
+ "wavtool: reconstruction error %.9g exceeds the tolerance %.9g\n",
+ maximum, tolerance);
+ goto cleanup;
+ }
+ if (scale_maximum > tolerance) {
+ fprintf(stderr,
+ "wavtool: stem '%s' deviates from its fake-model scale by %.9g"
+ " (tolerance %.9g)\n",
+ STEM_NAMES[worst_stem], scale_maximum, tolerance);
+ goto cleanup;
+ }
+ ok = true;
+
+cleanup:
+ for (stem = 0U; stem < 6U; ++stem) {
+ wav_close(&stems[stem]);
+ }
+ wav_close(&input);
+ return ok;
+}
+
+static void print_usage(void)
+{
+ fprintf(stderr,
+ "Usage:\n"
+ " wavtool gen <path> <frames>\n"
+ " wavtool inspect <path> <expected_frames>\n"
+ " wavtool recon <tolerance> <input.wav> <stem_dir> <identifier>\n");
+}
+
+int main(int argc, char **argv)
+{
+ if (argc == 4 && strcmp(argv[1], "gen") == 0) {
+ uint64_t frames;
+ if (!parse_u64(argv[3], &frames)) {
+ fprintf(stderr, "wavtool: invalid frame count '%s'\n", argv[3]);
+ return 2;
+ }
+ return generate(argv[2], frames) ? 0 : 1;
+ }
+ if (argc == 4 && strcmp(argv[1], "inspect") == 0) {
+ uint64_t frames;
+ if (!parse_u64(argv[3], &frames)) {
+ fprintf(stderr, "wavtool: invalid expected frame count '%s'\n", argv[3]);
+ return 2;
+ }
+ return inspect(argv[2], frames) ? 0 : 1;
+ }
+ if (argc == 6 && strcmp(argv[1], "recon") == 0) {
+ return reconstruction(argv[2], argv[3], argv[4], argv[5]) ? 0 : 1;
+ }
+ print_usage();
+ return 2;
+}