[6uclz1]

Stacked on #128, which is stacked on #127. Merge those first; this PR's base then moves down.

Bug fix: session capture never honored --start

capture_session moved the playhead while the transport was stopped, which Live ignores. It then fired the clip and pressed play, so each capture began wherever the previous stop left the playhead. Firing from a stopped transport restarts the song at beat 0.

Back-to-back captures drifted through the song. On the Phase Trance set:

• A Kick capture was silent for its first 13 s.
• Perc, Sub, Bass and Lead captures were silent throughout.
• The Remote Script already notes this ("Live ignores a playhead moved while stopped … the CLI re-applies it once playback runs"). transport play re-applies the playhead; capture_session called transport_play directly and never did.

Fix:

• Start playback, move the playhead one bar before --start, then fire. Live's 1-bar launch quantization begins the recording exactly at --start. Verified in Live: a capture at beat 252 had the kick enter 1.8 s in, matching the arrangement.
• Verify afterwards: recorded_start_beat = stop position − file length (from the WAV header). If it is more than half a beat from --start (e.g. launch quantization ≠ 1 Bar), the command fails with step: verify_recorded_start.
• Contract change: --start is now required and must be at least one bar, because the pre-roll needs a bar before it. session capture's old default of 0 can no longer be honored.

New commands

• audio spectrum shares --stem LABEL=PATH … reports, per band:
  • each stem's level
  • shares_pct: each stem's share of the band's summed energy
  • dominant: the stem with the largest share
  • band_totals_dbfs: the summed level
  • with --focus LABEL, focus.margin_db: the focus stem minus the loudest other stem (negative = gap to close)
  • --resolution third-octave uses the 29 ISO bands from 25 Hz to 16 kHz.
• session capture-tracks --start B --track-index N … captures each track on its own:
  • Solos each track and captures it into a temporary audio track (Resampling, volume 0), which it deletes afterwards.
  • --bypass-main-devices turns off active main devices for the capture.
  • Solos, the temporary track and bypassed devices are restored in finally blocks, even when a capture fails.
  • Refuses to run while a track is soloed.
  • --analyze, --resolution, --focus feed spectrum shares, with labels from track names (index:name when names repeat).
• Band measurement: every band now runs in one ffmpeg pass (asplit into named astats@bN instances, joined by amix), with a 16384-point FFT so the 22–28 Hz third-octave band holds more than one bin.

Public contract impact (intentional)

• New commands: audio spectrum shares, session capture-tracks.
• session capture: --start is required (≥ one bar), and the result adds recorded_start_beat.
• Command-surface and public-contract snapshots are regenerated (additions, plus the required option). README, SKILL.md and docs/mastering.md are updated.

Tests

• tests/test_capture.py: call order (play before playhead before fire), pre-roll per time signature, pre-roll validation, recorded-start mismatch, and existing behaviors on the new flow.
• tests/test_capture_tracks.py: solo/temporary-track sequence, device bypass and restore, restore on failure, duplicate labels, --analyze wiring, validation (empty, duplicate, unknown, already soloed, --focus without --analyze, bad resolution before capturing), --read-only blocking.
• tests/test_spectrum_shares.py: share math, silent bands, focus margins, third-octave bands, validation, CLI --stem parsing and report, missing file; plus real ffmpeg (an 80/20 split of a tone at half amplitude).
• tests/test_audio_spectrum_bands.py: single-pass graph, custom bands, readings found by instance name.

Validation

• ruff check, ruff format --check, dev_checks: 1432 passed
• Quality harness: exit 0, 0 failures
• Live (Phase Trance, Live 12.4):
  • Drop and breakdown capture-tracks produced audio for the full window on every track, with solos, the temporary track and main devices restored.
  • Master session capture --start 192 reported recorded_start_beat: 192.0.

Known limit: shares average the whole window, so a track that rests for part of it reads low. The docs say to check its level while it plays.

🤖 Generated with Claude Code