bwf-analyser/CLAUDE.md

BWF Analyser

Reads and edits BWF (Broadcast Wave) metadata for production sound: scene, take, timecode, track names, plus export, split, combine and a sound report. Two things get built from one source tree:

• index.html at the root: a single self-contained page, no server, no network, opens in a browser.
• mac-app/: a native macOS app (Tauri v2 + Rust) that wraps the same page and adds real file access, a Rust audio engine and a Rust WAV writer.

Build

python3 build/build.py            # writes ./index.html
python3 build/build.py --tauri    # writes ./mac-app/dist/index.html

Both, every time: a change to shared code affects both pages, and a feature wired into only one looks exactly like a broken feature (a visible button that does nothing). There is a test for that specific trap.

The Mac app is built by double-clicking mac-app/Build BWF Analyser.command. That script regenerates the page, touches main.rs so the page is re-embedded (cargo does not reliably notice a changed dist/), compiles, assembles and signs the bundle.

Test

node build/test.js           # the browser page, in jsdom
node build/test-tauri.js     # the Mac page against a stubbed engine
node build/test-export.js    # every export/split/combine/format combination
node build/test-play.js      # playback maths, peaks, spectrogram, meters
node build/test-restore.js   build/test-framerate.js   build/test-pdf.js
BWF_TINY_CHUNKS=1 node build/test-tauri.js   # tiny-read paths

All of them should pass before anything ships. Roughly 370 checks.

How the build works, and its traps

build/build.py inlines CSS and JS into one HTML file. The app's JavaScript (build/src/bwf-analyser-app.js) is vendored from a WordPress plugin and is kept pristine: changes to it are made as exact-string patches in lists in build.py (SHARED_APP_JS_PATCHES, APP_JS_PATCHES, PLAYER_PATCHES, SPECTRO_PATCHES, MIXER_PATCHES). Each patch asserts its anchor is found exactly once, so a stale anchor fails the build loudly rather than silently doing nothing.

• Patch strings are Python non-raw triple-quoted strings, so tabs in the JavaScript are written \t. Get this wrong and the anchor never matches.
• SHARED_* patches apply to both builds; the others only to --tauri.
• When inserting into the page, use the last </body>, not the first: the page contains inlined JavaScript that writes HTML, and the first match is inside a string literal.

The Rust side

mac-app/src-tauri/src/:

• main.rs — the commands the page calls (bwf_scan, bwf_export, bwf_combine, bwf_peaks, bwf_spectrogram, bwf_play, bwf_gains, …).
• convert.rs — RIFF/BWF parsing and writing, peaks, spectrogram, FFT.
• play.rs — the audio engine. cpal, one engine thread owning the stream (cpal::Stream is !Send on macOS), a reader thread streaming blocks over bounded channels, per-channel gains and meters as atomics read in the callback. Playback deliberately does not use Web Audio: the webview's audio would die after a while and no JavaScript could recover it.

build/wav-convert.js is a line-for-line Node mirror of the Rust converter, and the tests drive both. Anything added to the Rust side that has maths in it should be mirrored and tested, including the rounding: Rust's f64::round and JavaScript's Math.round disagree on negative ties.

Conventions worth keeping

Mutation-test every new test. Break the thing on purpose, confirm the test fails with a message that names the problem, put it back. Several tests in this suite passed for the wrong reason until this caught them.

jsdom has no layout engine. Nothing here can see that a button has no hit area, that a grid is scrambled, or that an element collapsed to zero width. Every one of those has shipped at least once. Layout changes need a screenshot from the user; keep them small and ask.

Two pages, one behaviour. If a feature only makes sense on the Mac build, it still needs to not look broken on the other one.

The page stamps itself. window.BWFA_BUILD holds the build time, also on data-bwfa-build on the app root. Use it to settle "is the app running the page I just built" rather than guessing.

There is an in-app log. Cmd-Shift-L opens it (build/diagnostics.js): it captures console output and errors from before the app starts, traces clicks with what was actually hit, and measures the controls' boxes against elementFromPoint. This is the fastest route to a diagnosis when a control looks fine and does nothing. Devtools are compiled in too (right-click → Inspect Element).

Text lives in build/l10n.json, including the hover hints, keyed by data attribute.

Where things are

build/
  build.py            assembles both pages, holds all the patches
  body.html           markup
  overrides.css       the app's own styling on top of the plugin's
  l10n.json           every string, plus hints
  diagnostics.js      the in-app log
  src/                the vendored plugin (JS + CSS), kept pristine
  wav-convert.js      Node mirror of the Rust converter, for tests
  test*.js            the suites
mac-app/
  src-tauri/src/      the Rust
  dist/index.html     generated
  Build BWF Analyser.command