173 lines
8.0 KiB
Markdown
173 lines
8.0 KiB
Markdown
# DAW verification — bank-package transfer across machines
|
||
|
||
What a DAW pass must establish for `.rsbank` export and import, and the exact strings or
|
||
counts to read off. The unit corpus (`tests/fixtures/package_compat/`) already proves the
|
||
version ladder, the truncation verdicts and the hostile-name refusals against frozen
|
||
bytes. **Nothing below is covered by it**: every cell here depends on a real REAPER
|
||
session, a real file dialog, or a genuine second machine.
|
||
|
||
**Build to use.** Release, installed into `UserPlugins/`, REAPER restarted — extensions
|
||
load at startup only. Note the version the *About*/version action reports; §5 needs it.
|
||
|
||
**Machines to use.** Two: **A** (the source) and **B** (the destination). B must be a
|
||
different machine, or at minimum a different user account with its own REAPER resource
|
||
path and its own projects folder — the point is that no absolute path from A can resolve
|
||
on B. A USB stick, a network share, or a cloud folder are all acceptable transports.
|
||
|
||
**Projects to use.** On A: one **saved** project with a bank holding at least **three**
|
||
samples, at least one of them audibly distinct from the others, and at least one whose
|
||
display name carries a non-ASCII character (e.g. `Café hit`). On B: one **saved**,
|
||
otherwise empty project.
|
||
|
||
---
|
||
|
||
## 1. Export writes one file and touches nothing else
|
||
|
||
On A, right-click the bank's header in the docked panel → **Export as package...** (or
|
||
run *ReaSampler: export active bank as package*). Accept the suggested file name.
|
||
|
||
Read off:
|
||
|
||
- The console shows `ReaSampler export: wrote 3 entry/entries (N bytes) to <path>`, with
|
||
the entry count matching the bank.
|
||
- A single `.rsbank` file exists at that path. **No `.rsbanktmp` sibling remains** — a
|
||
leftover temp file means the atomic rename did not complete.
|
||
- The bank's card count, the bank folder's file count, and the project's dirty flag are
|
||
all **unchanged**. An export writes no ext state and opens no undo point, so REAPER
|
||
must not consider the project modified by it alone.
|
||
- Nothing was added to the arrange view.
|
||
|
||
## 2. The transfer itself — the claim no unit test can make
|
||
|
||
Copy the `.rsbank` to B by whatever transport you chose. Do **not** copy the project, the
|
||
bank folder, or anything else.
|
||
|
||
On B, open the empty saved project. Panel bank menu → **Import bank package...** (or run
|
||
*ReaSampler: import bank package (.rsbank)*), and choose the transferred file.
|
||
|
||
Read off:
|
||
|
||
- A message box: `Imported 3 sample(s) into a new bank: "<bank name>".`
|
||
- The console block repeats that line and ends with `One undo removes the imported bank
|
||
and its entries. It does NOT delete the imported files ...`.
|
||
- The panel shows a **new** bank with the same display name and the same number of cards,
|
||
**in the same order** as on A.
|
||
- B's bank folder holds three new files. The non-ASCII display name from A renders
|
||
correctly on the card — a mangled name here means the UTF-8 path/name conversion broke
|
||
in transit.
|
||
- **Audition each card.** They must sound like their counterparts on A. This is the whole
|
||
claim: the audio survived a machine boundary with no shared path.
|
||
- Press **Ctrl-Z once**. The imported bank and its entries disappear in one step. The
|
||
three files remain in B's bank folder (that is stated in the console block above, and is
|
||
the designed behaviour — a prune reclaims them). Redo to continue.
|
||
|
||
## 3. Re-importing the same package never overwrites
|
||
|
||
Still on B, import the **same** file a second time.
|
||
|
||
Read off:
|
||
|
||
- A second new bank appears, named with a suffix (`<bank name> 2`), and the box's
|
||
`(a bank named "<bank name>" already exists in this project)` clause appears in the
|
||
console block.
|
||
- B's bank folder now holds **six** files, not three. The console reports
|
||
`3 file(s) landed under a freshly minted name (the package's own name was already taken
|
||
in the bank folder). An existing bank file is never overwritten.`
|
||
- The first imported bank's cards still audition correctly — nothing was replaced under it.
|
||
|
||
## 4. Round trip back to the source
|
||
|
||
On B, export the imported bank (§1) to a second `.rsbank`. Carry it back to A and import
|
||
it into A's original project.
|
||
|
||
Read off:
|
||
|
||
- The import succeeds and lands as a new bank beside the original.
|
||
- The original bank on A is untouched: same card count, same names, same audio.
|
||
- Compare the two `.rsbank` files' **sizes**. They will usually differ — entry names,
|
||
sample ids and the export timestamp are all legitimately re-minted across a trip. The
|
||
payload bytes are what must survive, and that half is closed by
|
||
`tests/test_package_round_trip.cpp` against frozen bytes; do **not** treat a size
|
||
difference here as a defect.
|
||
|
||
## 5. The too-new refusal, with the message read verbatim
|
||
|
||
This is the direction a user hits when a collaborator is ahead of them, and the message is
|
||
the only actionable output. Produce it by hand:
|
||
|
||
1. Copy the `.rsbank` from §1 to a scratch name.
|
||
2. Open the copy in a hex editor. Bytes 0–3 are `RSBK`; bytes 4–7 are `formatVersion`
|
||
little-endian; bytes **8–11** are `minReaderVersion` little-endian.
|
||
3. Change byte **8** from `01` to `02`, and byte **4** from `01` to `02` (a writer cannot
|
||
require a reader newer than the format it wrote — leaving `formatVersion` at 1 makes
|
||
the file incoherent and it will be refused as malformed instead, which is a different
|
||
cell). Save.
|
||
4. Import the edited copy.
|
||
|
||
Read off — the message box, all four lines:
|
||
|
||
```
|
||
Cannot import this bank package.
|
||
It was written by ReaSampler <the version noted at the top> and needs package format 2 or newer.
|
||
This build (<the same version>) reads package format 1.
|
||
Nothing was imported. Install ReaSampler <the same version> or newer and try again.
|
||
```
|
||
|
||
- The writer version named is the one **this** build stamped in §1 (the hex edit does not
|
||
touch the semver), so the second and fourth lines will name your own version. That is
|
||
expected — what is being verified is that all three facts are present and the box
|
||
appears at all.
|
||
- **No** new bank, **no** new files in the bank folder, **no** undo point.
|
||
|
||
## 6. The truncated-download refusal is a different message
|
||
|
||
Copy the §1 package again and delete the last few hundred bytes (any hex editor, or
|
||
`head -c` / `fsutil` — the exact count does not matter as long as the file is shorter).
|
||
Import it.
|
||
|
||
Read off:
|
||
|
||
- The message box reads exactly: `This file is not a readable bank package (corrupt or
|
||
truncated). Nothing was imported.`
|
||
- It is **not** the §5 message. Crossing these two is the failure this cell exists to
|
||
catch — "install a newer build" does not fix a partial download.
|
||
- No new bank, no new files.
|
||
|
||
## 7. Corruption in the middle is caught before anything lands
|
||
|
||
Copy the §1 package again and flip a single byte **well past the halfway point** (inside a
|
||
payload, not the header). Import it.
|
||
|
||
Read off:
|
||
|
||
- The message box names the offending entry:
|
||
`This bank package is damaged (entry "<name>" failed its integrity check). Nothing was
|
||
imported.`
|
||
- The bank folder gained **no** files at all — not even the entries before the damaged
|
||
one. Verification runs to completion before the first write, so a damaged package costs
|
||
no rollback.
|
||
|
||
## 8. The unsaved-project refusals
|
||
|
||
- On B, File → New Project (do not save). Try to import. Read off:
|
||
`Save the project before importing a bank package -- an unsaved project has no bank
|
||
folder to import into.` The file picker must **not** have opened first.
|
||
- On A, in an unsaved project with no bank, try to export. Read off the console:
|
||
`ReaSampler export: save the project first -- an unsaved project has no bank folder to
|
||
read from.`
|
||
|
||
## 9. Drag-and-drop reaches the same verb
|
||
|
||
On B, drag a `.rsbank` from the file manager onto the docked ReaSampler panel.
|
||
|
||
Read off: the same import box as §2, and the same new bank. A `.rsbank` is a whole bank,
|
||
not audio — it must never land as an item in the arrange view.
|
||
|
||
---
|
||
|
||
## Recording the result
|
||
|
||
For each section, record **pass**, **fail with the string actually seen**, or **not
|
||
exercised**. §2 and §4 are the load-bearing ones: they are the only cells in this document
|
||
that involve a real machine boundary, and no unit test can stand in for them.
|