v2.0.0 audit remediation: parent tracking issue #12

Tracking issue for the findings from a full audit of the codebase at v2.0.0 (39e90eb).

How the audit was done

• Read every file: visualmic.py, tests, Dockerfiles, CI, README, design doc.
• Ran ruff (0.15.7 and 0.16.9) and the test suite: 28 passed, 7 GPU tests skipped.
• Built a synthetic vibrating-surface generator with exact sub-pixel Fourier-shift motion and a known audio signal at 2200 fps, and scored recovered audio against the truth for different motion directions, drift and noise.
• No GPU was available. extract_audio_gpu was run end to end on a CPU PyTorch build (torch 2.14 with pytorch_wavelets HEAD) with the device patched to CPU. This tests its logic and numbers, but not CUDA speed or VRAM use.

Headline findings

• Vertical motion recovers poorly. Correlation with the true audio is 0.85-0.91, against 0.998 with sign-aware, bounded-lag alignment, because half the DTCWT orientations see the motion inverted.
• Default settings fail on realistic footage. 0.3 px of drift cuts the in-band level by 12 dB (correlation 0.26).
• The GPU path drops up to batch_size − 1 final frames when the container over-reports its frame count.
• Filter edge cases crash after processing (-fl 0, 13-27-frame clips), and a wrong container fps (30 instead of 2200) isn't caught.
• CI will fail on its next run (ruff 0.16: 11 errors), and it never runs pytest.
• On the positive side, the CPU and GPU paths agree to a correlation of 1.000.

Phase 1: correctness of recovered audio (≈ 2-3 days)

• Sub-band alignment ignores sign: anti-phase orientations are misaligned or cancel (recovery drops to r≈0.85-0.91 for vertical motion) #13 Sub-band alignment ignores sign; unbounded lag; np.roll wraps around
• With default settings (no filter), slow drift swamps the audio: 0.3 px of drift cuts in-band level by 12 dB #14 No filter by default, so drift swamps the audio
• Measuring phase against frame 0 wraps once the surface drifts; use frame-to-frame differences plus a cumulative sum #17 Phase measured against frame 0 wraps under drift; use frame-to-frame differences plus a cumulative sum
• GPU path drops the last partial batch when the container over-reports frames; CPU path drops frames when it under-reports #16 GPU drops the last partial batch; both paths drop frames when the count is under-reported
• Filter and fps checks: -fl 0 and short clips crash, -fl above Nyquist silently skips the filter, a wrong container fps is not caught #15 Filter and fps validation: crashes, silent skips, wrong container fps

Phase 2: engineering baseline (≈ 1-2 days)

• CI will fail on its next run: ruff is unpinned and 0.16 changed its default rules (11 errors) #18 CI will fail on its next run: ruff unpinned
• CI never runs pytest; the GPU job builds a multi-GB PyTorch image just to lint; the GPU code is never exercised #19 CI never runs pytest; heavy GPU job; run the GPU code on CPU torch in CI
• Tests: nothing checks that sound is actually recovered; add a synthetic vibrating-surface test with known ground truth #20 Tests: add a synthetic ground-truth recovery test (generator included)
• CLI robustness: output path checked only after processing, errors go to stdout, GPU hard-coded to device 0 #21 CLI robustness: output path checked last, errors to stdout, no --device
• Docs don't match behaviour: "start with default settings", filter description, sample rate, CPU/GPU differences, versions #24 Docs don't match behaviour

Phase 3: scale and maintenance

• Performance: the CPU path takes about 78 min for the Chips1 sample; parallelise across frames and vectorise the phase maths #22 Performance: ≈ 78 min on CPU for Chips1; parallelise and vectorise
• Build reproducibility: pin pytorch_wavelets, recheck the PyTorch 2.1.2 pin, lock dependencies, fix Docker user handling #23 Build reproducibility: pin pytorch_wavelets, recheck the torch 2.1.2 pin, lock dependencies, Docker user

Suggested order

#18 and #19 first, so CI is green and runs the tests. Then #20's ground-truth test, so each algorithm fix can be measured. Then #13, #14 and #17, which change the output and should go in a single release (v3.0.0) with before/after numbers in the CHANGELOG.