# DAW verification — track-scope capture over a multi-track selection

What a DAW pass must establish for the multi-track track capture, and the exact numbers
or strings to read off. Nothing below can be closed by a unit test: every item depends on
what REAPER actually does with a render request.

**Build to use.** Release, installed into `UserPlugins/`, REAPER restarted — extensions
load at startup only. Set the docked panel's tail toggle to **None** before every cell;
Auto adds an 8 s window and Manual a fixed one, and both would invalidate the frame-count
readings.

**Project to use.** One saved project, project sample rate pinned to 48000. Two audio
tracks, `A` and `B`, each holding one item at least 30 s long, with *audibly different*
content (a tone on `A`, a drum loop on `B`). One folder track `F` with `A` and `B` as its
children, used only in §5.

---

## 1. The regression floor — single-track track capture is unchanged

Select **track `A` only**. Make a time selection from **10.000 s to 12.000 s**. Run
*ReaSampler: capture selected track(s)*.

Read off:

- A file appears in the project's bank folder, and one new card appears on the panel.
- The card's length reads **2.000 s**; its frame count is **96000** (`round(12.0 × 48000)
  − round(10.0 × 48000)`). The backend refuses the capture with `BoundsMismatch` if the
  render is more than one frame off that, so a landed capture already proves the number
  to ±1 — what you are confirming here is that it landed at all.
- The REAPER console shows **no** `ReaSampler capture failed:` line.
- Track `A` is still the only selected track afterwards.
- **Content, not just length.** Listen to the landed file. `A` and `B` carry *audibly
  different* content by the project setup above (tone vs. drum loop), so this is a by-ear
  check, not a null test: the capture must be the tone alone, with **no** drum-loop bleed.
  Expected: pure tone, matching `A` soloed. Failing: any trace of `B`'s drum loop audible
  in the file. This is not a tautology check — the SDK header's own `RENDER_SETTINGS` line
  admits a second reading, `(&(1|2)==0)=master mix`, under which a single-track track
  capture could render the **whole master mix** (both `A` and `B`) rather than `A` alone;
  drum-loop bleed here is exactly what that misreading would produce, and this is the
  cheapest place in the whole doc to catch it.

**This is the byte-identical floor.** If either cell now refuses, the change is wrong —
the refusal must fire only above one track.

## 2. The defect cell — two selected tracks now refuse

Select **`A` and `B` together**. Time selection 10.000–12.000 s. Run *capture selected
track(s)*.

Read off:

- The console prints exactly:
  `ReaSampler capture failed: A track capture renders the selected tracks through the
  master, and more than one track cannot land as a single file. Capture one track at a
  time, or route them into a folder/bus track and capture that (a folder's own output is
  its children summed).`
- **No** new card on the panel, and **no** new `.wav` in the bank folder (check the folder
  directly — a stray file with nothing indexing it would mean the refusal fired too late).
- `A` and `B` are both still selected, both still unmuted, and neither track's fader, pan,
  or FX-bypass state changed. The refusal returns before any guard is constructed, so
  there should be nothing to restore — this reading is what confirms that.

Repeat with a **razor area spanning both tracks** and no time selection: identical
readings. Note that the track *selection* is what the refusal counts — a razor over two
tracks with only `A` selected is a one-track capture and must still succeed (§1).

## 3. The decisive observation — what `&128` actually writes

**This is the one that retires an inference, and it is the reason `docs/TODO.md` still
carries an entry.** The refusal in §2 rests on reading the SDK header's single-file bit
`&(4<<16)` as applying to item/razor sources only, never to `&128` — so N selected tracks
are believed to produce N files. That has never been observed.

Drive REAPER's own Render dialog by hand, with the extension out of the loop:

1. Select `A` and `B`.
2. File → Render. **Source:** *Selected tracks via master* — the dialog wording for `&128`
   (SDK header ~3041). Do **not** pick *Stems (selected tracks)* — that is `&2`, a
   different source bit that unambiguously writes one file per track and would confirm
   nothing about `&128`.
   **Bounds:** *Custom time range*, 10.000 to 12.000 s.
3. **File name:** a literal stem with **no wildcards at all** — e.g. `stemprobe`. Clear
   `$track` / `$item` / anything else from the pattern; the extension writes exactly one
   literal stem, so the probe must too.
4. Render to an empty scratch folder.

Read off — **the file count in that folder**:

- **Two files** (however REAPER disambiguated them, or one file that visibly got
  overwritten): the inference holds, the §2 refusal is correct, and the `docs/TODO.md`
  entry can be closed by writing this observation into `src/shell/capture/CLAUDE.md` as
  fact.
- **One file containing `A` and `B` summed** (confirm by ear, or by nulling it against a
  master render of the same range with only `A` and `B` unmuted): the inference is wrong,
  the §2 refusal costs a working capture, and the track-scope half should be narrowed back
  per the `docs/TODO.md` entry. The item-scope half stays either way.

Also record **what REAPER named the files** — that decides whether a future correct
multi-track capture could ever be built on this source at all.

## 4. Recapture replays the same answer

Take a **single-track** track capture that carries provenance (capture a range on `A`
whose source item is itself a bank sample, so `detectParent` fires), select its card, and
run *re-capture from source*. It must regenerate — same audio, same 96000 frames.

Then construct the multi-track case: a recorded recipe whose `trackGuids` names two
tracks. The reachable way to get one is to have captured it before this change; if no such
entry exists in any project, record that this cell was **not exercised** rather than
inventing one. When it is exercised, read off:

- `ReaSampler re-capture failed:` followed by the **same** message text as §2.
- The bank entry is untouched — same file, same hash, same card.

## 5. The way out actually works

Route `A` and `B` into folder `F`. Select **`F` only**, time selection 10.000–12.000 s,
capture track scope.

Read off: one card, 2.000 s, and the audio contains **both** `A` and `B`. This is what the
refusal message tells the user to do, so it has to be true.

## 6. Realtime still accepts a multi-track selection

Select `A` and `B`. Run *ReaSampler: capture selected track(s) in realtime* over the same
range. Read off: **one** card, and its audio contains both tracks. Realtime taps each
source track with a send into one temp track, so it sums where the offline render cannot —
the divergence from §2 is deliberate and this cell is what confirms it is real.

## 7. Mono collapse — what is and is not reachable

Capture a range on a track whose content is dead-center (a mono source panned center, or
a duplicated-channel file), using time selection **10.000 s to 12.000 s** (2.000 s, 96000
frames at 48000 Hz — the §1 convention, so the resulting file size is exact). The panel has
no channel-count readout anywhere (`Sample::channelCount` is not drawn by
`src/shell/panel/panel_render.cpp`), so read the proxy instead:

- Check the landed `.wav`'s size on disk (Explorer → Properties, or a directory listing). A
  successful collapse is the extension's own rebuild — canonical 44-byte header + 96000 ×
  4 bytes = **384,044 bytes**. A file near double that (~768,044 bytes, plus whatever
  REAPER's own render adds for `bext`/metadata chunks) means the collapse did not fire —
  recheck the source is genuinely dead-center before treating this as a defect.
- The console shows **no** `the lossless mono collapse ... already reached the bank; only
  the size win from the collapse was lost.` line.

**Not DAW-reachable:** the collapse's *failure* branch. It fires only if the captured file
cannot be read, or its temporary rewrite cannot be written or renamed, inside the same
call that just rendered the file — there is no manual way to inject that fault between the
render and the rename. The branch is covered only at its reporting seam
(`tests/test_wav_codec.cpp`, `testCollapseOutcomeSuffixesAreDistinctStrings`), and its console line
has never been seen in a running REAPER. If you ever do see it, the render already reached
the bank — the report only tells you the collapse's size win was lost, not that the bytes
were verified (see `docs/TODO.md`'s 0-byte-render entry).
