scripts/dataset: document the pair-building rules
Browse files- scripts/dataset/README.md +50 -0
scripts/dataset/README.md
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Dataset preparation
|
| 2 |
+
|
| 3 |
+
LTX's trainer takes a dataset; it does not help you *build* one. For an audio
|
| 4 |
+
IC-LoRA the dataset is the whole problem — the model learns a transformation, so
|
| 5 |
+
every item must be the same performance twice, once dry and once through a real
|
| 6 |
+
acoustic treatment, aligned and gain-matched. These are the scripts that built
|
| 7 |
+
the AKUSPACE set (266 pairs, 14 sources × 19 cells).
|
| 8 |
+
|
| 9 |
+
Set `AKUSPACE_DATASET` to your dataset root, or run from the repo and the
|
| 10 |
+
relative default applies.
|
| 11 |
+
|
| 12 |
+
| Script | Does |
|
| 13 |
+
|---|---|
|
| 14 |
+
| `build_v5_rooms.py` | dry/wet room pairs at three levels per room |
|
| 15 |
+
| `build_v5_outdoor.py` | outdoor beds; projects the dry out before rebuilding |
|
| 16 |
+
| `build_v5_sfx.py` | Eurorack modular-delay pairs |
|
| 17 |
+
| `build_eurorack_dry.py` | assembles the dry side fed through the hardware |
|
| 18 |
+
| `make_manifest_v5.py` | writes the training CSV with captions and splits |
|
| 19 |
+
| `verify_dataset.py` | checks every pair: length, rate, ceiling, alignment |
|
| 20 |
+
| `check_limiting.py` | catches limiting/clipping introduced by a render chain |
|
| 21 |
+
| `check_clips.py` | duration and sample-rate conformance |
|
| 22 |
+
| `wetdry.py` | measures the wet/dry relationship of a rendered pair |
|
| 23 |
+
| `slice_ableton_stems.py` | cuts long recordings into per-source clips |
|
| 24 |
+
|
| 25 |
+
## The rules these encode
|
| 26 |
+
|
| 27 |
+
Each one cost real time to learn.
|
| 28 |
+
|
| 29 |
+
**Never normalise dry and wet independently.** Apply the same gain to both, or
|
| 30 |
+
the pair no longer describes a transformation and the model learns loudness
|
| 31 |
+
instead of acoustics.
|
| 32 |
+
|
| 33 |
+
**Normalise by active loudness, not peak.** Sparse material — handclaps
|
| 34 |
+
especially — reads ~13 dB quiet on peak-based normalisation and ends up
|
| 35 |
+
mismatched against sustained sources.
|
| 36 |
+
|
| 37 |
+
**An ambience bed is not a reverb tail.** A tail is part of the signal and
|
| 38 |
+
scales cleanly; a bed is a separate recording, so boosting it amplifies its own
|
| 39 |
+
noise floor. Scale beds down only, and only a little. This is why the outdoor
|
| 40 |
+
cells ship two levels while rooms and SFX ship three.
|
| 41 |
+
|
| 42 |
+
**Check the dry fit before trusting any ambience measurement.** `R = wet − dry`
|
| 43 |
+
assumes the render carries the dry at exactly 1.00×. When it does not, a
|
| 44 |
+
negative ghost of the dry hides inside R and dominates every derived number —
|
| 45 |
+
which produced months of misleading ambience statistics here before
|
| 46 |
+
`verify_dataset.py` caught it. Confirm fit ≈ 1.000 first.
|
| 47 |
+
|
| 48 |
+
**The trigger word belongs in preprocessing, not the manifest.** It is prepended
|
| 49 |
+
to training captions by the preprocessor and must appear in inference prompts;
|
| 50 |
+
storing it in the CSV double-applies it.
|