loopcutter 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. loopcutter-0.3.0/LICENSE +21 -0
  2. loopcutter-0.3.0/PKG-INFO +664 -0
  3. loopcutter-0.3.0/README.md +622 -0
  4. loopcutter-0.3.0/pyproject.toml +55 -0
  5. loopcutter-0.3.0/setup.cfg +4 -0
  6. loopcutter-0.3.0/src/loopcutter/__init__.py +13 -0
  7. loopcutter-0.3.0/src/loopcutter/analyse.py +153 -0
  8. loopcutter-0.3.0/src/loopcutter/audio_io.py +46 -0
  9. loopcutter-0.3.0/src/loopcutter/cli.py +768 -0
  10. loopcutter-0.3.0/src/loopcutter/cut.py +197 -0
  11. loopcutter-0.3.0/src/loopcutter/grid.py +205 -0
  12. loopcutter-0.3.0/src/loopcutter/keydetect.py +77 -0
  13. loopcutter-0.3.0/src/loopcutter/keyreport.py +236 -0
  14. loopcutter-0.3.0/src/loopcutter/keys.py +346 -0
  15. loopcutter-0.3.0/src/loopcutter/manifest.py +245 -0
  16. loopcutter-0.3.0/src/loopcutter/markers.py +175 -0
  17. loopcutter-0.3.0/src/loopcutter/model.py +114 -0
  18. loopcutter-0.3.0/src/loopcutter/naming.py +95 -0
  19. loopcutter-0.3.0/src/loopcutter/onsets.py +117 -0
  20. loopcutter-0.3.0/src/loopcutter/prep.py +188 -0
  21. loopcutter-0.3.0/src/loopcutter/provenance.py +64 -0
  22. loopcutter-0.3.0/src/loopcutter/snap.py +215 -0
  23. loopcutter-0.3.0/src/loopcutter/stems.py +197 -0
  24. loopcutter-0.3.0/src/loopcutter/tags.py +135 -0
  25. loopcutter-0.3.0/src/loopcutter/timing.py +144 -0
  26. loopcutter-0.3.0/src/loopcutter/trackdb.py +77 -0
  27. loopcutter-0.3.0/src/loopcutter/verify.py +200 -0
  28. loopcutter-0.3.0/src/loopcutter/workspace.py +119 -0
  29. loopcutter-0.3.0/src/loopcutter.egg-info/PKG-INFO +664 -0
  30. loopcutter-0.3.0/src/loopcutter.egg-info/SOURCES.txt +50 -0
  31. loopcutter-0.3.0/src/loopcutter.egg-info/dependency_links.txt +1 -0
  32. loopcutter-0.3.0/src/loopcutter.egg-info/entry_points.txt +2 -0
  33. loopcutter-0.3.0/src/loopcutter.egg-info/requires.txt +25 -0
  34. loopcutter-0.3.0/src/loopcutter.egg-info/top_level.txt +1 -0
  35. loopcutter-0.3.0/tests/test_analyse.py +101 -0
  36. loopcutter-0.3.0/tests/test_cli.py +538 -0
  37. loopcutter-0.3.0/tests/test_cut.py +196 -0
  38. loopcutter-0.3.0/tests/test_grid.py +136 -0
  39. loopcutter-0.3.0/tests/test_keys.py +180 -0
  40. loopcutter-0.3.0/tests/test_markers.py +147 -0
  41. loopcutter-0.3.0/tests/test_model.py +26 -0
  42. loopcutter-0.3.0/tests/test_oneshot_xfade.py +82 -0
  43. loopcutter-0.3.0/tests/test_onsets.py +49 -0
  44. loopcutter-0.3.0/tests/test_prep.py +152 -0
  45. loopcutter-0.3.0/tests/test_provenance.py +174 -0
  46. loopcutter-0.3.0/tests/test_snap.py +215 -0
  47. loopcutter-0.3.0/tests/test_stems.py +234 -0
  48. loopcutter-0.3.0/tests/test_tags.py +52 -0
  49. loopcutter-0.3.0/tests/test_timing.py +94 -0
  50. loopcutter-0.3.0/tests/test_trackdb.py +137 -0
  51. loopcutter-0.3.0/tests/test_verify.py +123 -0
  52. loopcutter-0.3.0/tests/test_workspace.py +46 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Aaron Smiles
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,664 @@
1
+ Metadata-Version: 2.4
2
+ Name: loopcutter
3
+ Version: 0.3.0
4
+ Summary: Cut sample-accurate loops out of full tracks, driven by a manifest, for live loop-based sets
5
+ Author: Aaron Smiles
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/aaronlsmiles/loopcutter
8
+ Project-URL: Issues, https://github.com/aaronlsmiles/loopcutter/issues
9
+ Keywords: audio,loops,sampling,dj,ableton,live-performance
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: End Users/Desktop
13
+ Classifier: Operating System :: MacOS
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
18
+ Classifier: Topic :: Multimedia :: Sound/Audio :: Editors
19
+ Requires-Python: >=3.12
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: numpy>=1.24
23
+ Requires-Dist: soundfile>=0.12
24
+ Requires-Dist: soxr>=0.3
25
+ Requires-Dist: mutagen>=1.47
26
+ Provides-Extra: analysis
27
+ Requires-Dist: beat-this>=1.1; extra == "analysis"
28
+ Requires-Dist: librosa>=0.10; extra == "analysis"
29
+ Provides-Extra: markers
30
+ Requires-Dist: pyrekordbox>=0.4; extra == "markers"
31
+ Requires-Dist: serato-tools>=4.0; extra == "markers"
32
+ Provides-Extra: verify
33
+ Requires-Dist: librosa>=0.10; extra == "verify"
34
+ Provides-Extra: stems
35
+ Requires-Dist: audio-separator[cpu]>=0.47; extra == "stems"
36
+ Requires-Dist: audioread>=3.0; extra == "stems"
37
+ Provides-Extra: sheets
38
+ Requires-Dist: openpyxl>=3.1; extra == "sheets"
39
+ Provides-Extra: dev
40
+ Requires-Dist: pytest>=7.0; extra == "dev"
41
+ Dynamic: license-file
42
+
43
+ # loopcutter
44
+
45
+ Cut sample-accurate loops out of full tracks, driven by a plain-text manifest.
46
+
47
+ loopcutter is for live sets built from many short loops played at once, in the
48
+ spirit of Richie Hawtin's DE9 mixes. When eight loops run together for a
49
+ minute, a loop that is three samples too long drifts audibly. loopcutter
50
+ derives every loop's length from its tempo and bar count and rounds once. It
51
+ finds each track's beat grid, puts every start on a beat, and checks every
52
+ file before it calls a run a success.
53
+
54
+ The manifest is the source of truth. Keep it in version control and every
55
+ loop on disk can be rebuilt from one CSV file.
56
+
57
+ ## Features
58
+
59
+ - **Exact lengths.** `samples = round(bars × beats_per_bar × sample_rate × 60 / bpm)`,
60
+ rounded once at the end, never taken from a second timecode.
61
+ - **A beat grid per track.** `scan` fits a constant-tempo grid to the beats
62
+ that [beat_this](https://github.com/CPJKU/beat_this) detects, finds which
63
+ beat is the one, and moves the grid onto the audio's own attacks.
64
+ - **Mark loops by ear.** Set memory loops in rekordbox (or cues and saved loops
65
+ in Serato) on a waveform, then `import` them. Each start is snapped onto the
66
+ grid after the DJ app's own timing offset is removed, and every shift is
67
+ reported.
68
+ - **Click-free edges.** The start moves back to the nearest zero crossing
69
+ within 2 ms, never forward, so the attack is never clipped. The end moves
70
+ with it, so the length never changes.
71
+ - **Roll variations.** One manifest row can produce 4, 2, 1 and ½-bar versions
72
+ from the same start, ready to stack in a clip launcher for beat-division rolls.
73
+ - **Checks that can fail.** Every file is checked for exact length, sample
74
+ rate, headroom against its source, silence and DC offset. The loop's own
75
+ audio is checked for where its attacks sit against its beats, and its tempo
76
+ against the analysis.
77
+ - **Tagged and filed.** AIFF loops carry BPM, key and stem tags (ID3v2.3) and
78
+ are filed by stem and tempo band, ready for a sample browser.
79
+ - **Traceable.** Every loop's name ends with a short provenance code
80
+ (`[LC-1a2b3c4d]`), its tags say which recording it came from and where, and
81
+ `provenance.csv` next to the loops lists them all. A loop used in a set, a
82
+ collected project or a sampler can be traced back to its source, which is
83
+ what you need when it comes to clearing samples.
84
+ - **Stems and one-shots.** `stems` separates a master into drums, bass,
85
+ vocals and more at the master's own rate, and stem rows are cut from them.
86
+ One-shot rows cut a phrase or stab from a start to an end.
87
+ - **Seamless tonal loops.** An optional pre-roll crossfade blends a loop's
88
+ tail into the audio just before its start, so a pad wraps without a dip.
89
+ - **Session key planning.** From a list of keys, works out which one to three
90
+ session keys cover the most loops within a transposition limit, and the
91
+ exact shift each loop needs.
92
+
93
+ ## Status
94
+
95
+ Version 0.3. The beat grid, the DJ-app import, stems, one-shots and the
96
+ checks are in place, tested, and proven on a real library. See
97
+ [Roadmap](#roadmap) for what's next and [Known issues](#known-issues).
98
+
99
+ ## Install
100
+
101
+ Needs Python 3.12 or later. Install the `loopcutter` command with
102
+ [pipx](https://pipx.pypa.io) (or `uv tool install`), choosing the extras you
103
+ need:
104
+
105
+ ```bash
106
+ pipx install "loopcutter[analysis,markers,verify]"
107
+ loopcutter --help
108
+ ```
109
+
110
+ To work on the code instead:
111
+
112
+ ```bash
113
+ git clone https://github.com/aaronlsmiles/loopcutter.git
114
+ cd loopcutter
115
+ python3 -m venv .venv
116
+ source .venv/bin/activate
117
+ pip install -e ".[dev,analysis,markers,verify]"
118
+ pytest -q
119
+ ```
120
+
121
+ Optional extras:
122
+
123
+ | Extra | Adds | For |
124
+ |---|---|---|
125
+ | `analysis` | beat_this, librosa | `scan`: beat grids, attack phase |
126
+ | `markers` | pyrekordbox, serato-tools | `import` and the DJ-app grid cross-check |
127
+ | `verify` | librosa | the `beat_alignment` and measured-tempo checks in `cut` |
128
+ | `sheets` | openpyxl | reading XLSX key lists |
129
+ | `stems` | audio-separator, onnxruntime, audioread | the `stems` command |
130
+
131
+ beat_this runs on PyTorch and uses the Apple GPU when there is one; its model
132
+ weights download on first use.
133
+
134
+ Audio is read with libsndfile, which handles WAV, AIFF, FLAC and MP3. `prep`
135
+ reads AAC, M4A and anything else through [ffmpeg](https://ffmpeg.org/), so
136
+ install it if your sources include those. Key cross-checks use
137
+ [keyfinder-cli](https://github.com/EvanPurkhiser/keyfinder-cli) when it is on
138
+ your `PATH`.
139
+
140
+ ## Workspace
141
+
142
+ Your masters, analysis and loops are private working data, so they live in a
143
+ workspace outside this repository:
144
+
145
+ ```bash
146
+ loopcutter init ~/loops-workspace
147
+ cd ~/loops-workspace
148
+ ```
149
+
150
+ `init` refuses to create a workspace inside a git repository that has a
151
+ remote, so private audio can't end up pushed by accident. Every command finds
152
+ the workspace the way git finds a repository, by walking up from the current
153
+ directory to the folder holding `loopcutter.toml`.
154
+
155
+ | Folder | Holds |
156
+ |---|---|
157
+ | `masters/` | Lossless working copies, one per source, all at one rate. |
158
+ | `analysis/` | `tracks.csv` (one row per track) and `beats/`, the cached beats. |
159
+ | `manifests/` | Your manifests. |
160
+ | `reports/` | Scan reports and manifest backups. |
161
+ | `loops/aiff/`, `loops/wav/` | Cut loops, filed as `<stem>/<tempo band>/`. |
162
+ | `stems/` | Separated stems. |
163
+
164
+ `loopcutter.toml` settings:
165
+
166
+ | Key | Default | What it does |
167
+ |---|---|---|
168
+ | `[audio] sample_rate` | `48000` | The rate of every master. A cut never resamples. |
169
+ | `[audio] subtype` | `"PCM_24"` | The masters' sample format. |
170
+ | `[audio] headroom_db` | `3.0` (0 if absent) | Gain taken off every master, so overs from decoding and resampling loud sources fit instead of clipping. Changing it only affects masters made afterwards. |
171
+ | `[prep] replaced_dir` | `"masters/.replaced"` | Where a copy of a master built from a lossy file is kept when a lossless copy replaces it. Point it outside `masters/` if you drag that whole folder into a DJ app. |
172
+ | `[sources] paths` | `[]` | Folders or files that `prep` reads when given none. |
173
+ | `[snap] max_shift_ms` | `60` | The furthest a start may be moved onto the grid. |
174
+ | `[marking] app` | `"rekordbox"` | What `import` reads when `--from` isn't given: `rekordbox`, `rekordbox-xml` or `serato`. |
175
+ | `[marking] playlist` | `""` | The rekordbox playlist that holds your masters. |
176
+
177
+ ## Quick start
178
+
179
+ 1. Make masters and analyse them:
180
+
181
+ ```bash
182
+ loopcutter prep ~/Music/sources
183
+ loopcutter scan
184
+ ```
185
+
186
+ 2. Mark loops in rekordbox (see [Marking loops in DJ software](#marking-loops-in-dj-software))
187
+ and import them, or write a manifest by hand. [manifests/example.csv](https://github.com/aaronlsmiles/loopcutter/blob/main/manifests/example.csv)
188
+ shows the common columns.
189
+
190
+ 3. Check that every row resolves, then cut:
191
+
192
+ ```bash
193
+ loopcutter cut manifests/session.csv --dry-run
194
+ loopcutter cut manifests/session.csv
195
+ ```
196
+
197
+ 4. Spot-check an output. The bar count must come back whole:
198
+
199
+ ```bash
200
+ loopcutter inspect "loops/aiff/full/125-129/Some Artist - Some Track [A1][128][4bar][8A].aiff" --bpm 128
201
+ # at 128.0 BPM that is 16.0000 beats (4.0000 bars)
202
+ ```
203
+
204
+ If it reads 3.9996 bars, something upstream is using timecode arithmetic.
205
+
206
+ Prove the pipeline on a three-row manifest first. Load those loops into your
207
+ DAW, set them looping and listen for a full minute, because drift and seam
208
+ clicks only show on repeat. Then scale up. A batch that fails on row 280 has
209
+ wasted a lot of time that three rows would have saved.
210
+
211
+ ## The manifest
212
+
213
+ | Column | Required | Notes |
214
+ |---|---|---|
215
+ | `source` | yes | Path to the full track, normally its master. |
216
+ | `label` | yes | Your cue or ID reference, such as `A1` or `16.2`. |
217
+ | `bars` | yes | Loop length in bars. |
218
+ | `bpm` | yes | The track's tempo. |
219
+ | `start` | one of | `M:SS.mmm`, `H:MM:SS.mmm` or bare seconds. |
220
+ | `downbeat` + `start_bar` | one of | A precise downbeat time plus a 1-based bar number counted from it. |
221
+ | `kind` | no | `loop` (the default) or `oneshot`. |
222
+ | `end` | one-shots | Where a one-shot ends. A one-shot needs `source`, `label`, `start` and `end`, not `bars` or `bpm`. |
223
+ | `xfade_ms` | no | Pre-roll crossfade length for this loop; overrides `--xfade-ms`. |
224
+ | `track_id` | no | The track's row in `tracks.csv`. `resolve` fills `source`, `bpm` and `key` from it. |
225
+ | `snap` | no | `beat` or `bar` asks `resolve` to move `start` onto the grid. Must be empty before `cut`. |
226
+ | `variations` | no | Extra bar lengths from the same start, such as `"2,1,0.5"`. |
227
+ | `beats_per_bar` | no | Defaults to 4. |
228
+ | `artist`, `track` | no | Used to build the output filename. |
229
+ | `stem` | no | Written into the filename and the tags, and picks the library folder. |
230
+ | `key` | no | Written into the filename and the tags, and read by the key planner. |
231
+ | `notes` | no | Ignored by the tool. For you. |
232
+
233
+ Give either `start` or `downbeat` plus `start_bar`, never both. The loader
234
+ rejects rows that give both, rows with no start, rows that still say
235
+ `snap=beat` or `snap=bar`, and manifests whose rows would produce the same
236
+ filename, and it names the row number every time. Relative `source` paths
237
+ resolve against the current directory. Use `--audio-root` to point somewhere
238
+ else.
239
+
240
+ For rows you type by hand, give a `track_id`, a rough `start` and
241
+ `snap=beat`, then run `loopcutter resolve manifests/set.csv`. It backs the
242
+ manifest up to `reports/`, fills the missing columns from `tracks.csv`, snaps
243
+ each start and reports how far it moved. A start further than `max_shift_ms`
244
+ from the nearest beat is refused, and the row is named along with the beats
245
+ and bar either side of it.
246
+
247
+ ## Getting the start right
248
+
249
+ `cut` cuts exactly where the manifest says. It never moves a start by more
250
+ than the 2 ms zero-crossing search, and it never runs a model. Placement
251
+ happens earlier, in `import` and `resolve`, where every move is reported.
252
+
253
+ - **Mark on the master.** DJ apps decode MP3s with different padding, so a cue
254
+ read off an MP3 can sit tens of milliseconds from the same moment in the
255
+ audio this tool decodes. Marking on the lossless masters that `prep` makes
256
+ removes that offset. For marks made on the original files, `scan --app`
257
+ measures the app's offset per track and `import` removes it.
258
+ - **Give milliseconds.** A time typed to the whole second lands anywhere up to
259
+ half a second from the downbeat, which at 125 BPM is the wrong beat about
260
+ half the time.
261
+ - **Get the tempo exact.** A 4-bar loop cut at 134 BPM from a 136 BPM track is
262
+ 105 ms too long on every repeat. `scan` measures each track's tempo; the
263
+ `bpm_match` check catches a manifest that disagrees.
264
+
265
+ ## Marking loops in DJ software
266
+
267
+ 1. **`loopcutter prep`** makes 24-bit masters at the workspace rate from your
268
+ sources. Existing masters are not overwritten, because Mixed In Key or a
269
+ DJ app may have written tags to them; the one exception is below. A changed
270
+ source is reported instead; delete the master to rebuild it.
271
+ 2. **Import the masters into rekordbox** as one playlist, name it in
272
+ `loopcutter.toml` under `[marking] playlist`, and fix any grid whose first
273
+ beat is wrong.
274
+ 3. **Mark memory loops** with quantise on. Hot cues are ignored, so they stay
275
+ free for performing. Comment each loop with its label, then its stem, then
276
+ any roll lengths: `A1 bass 2,1` is loop A1, cut from the bass stem, with
277
+ extra 2 and 1-bar versions. A memory cue with no loop gets the default
278
+ length of 4 bars. Close rekordbox before importing.
279
+ 4. **`loopcutter scan --app rekordbox`** analyses each master and compares the
280
+ grid with rekordbox's.
281
+ 5. **`loopcutter import --from rekordbox --playlist NAME`** reads the marks,
282
+ snaps them and writes a resolved manifest to `manifests/`, reporting the
283
+ median and range of the moves. Serato users run `import --from serato`;
284
+ `--from rekordbox-xml --xml FILE` reads a rekordbox XML export instead of
285
+ the database. Marks that can't be placed are skipped and named, and the
286
+ command exits 1 so they can't be missed.
287
+ 6. **Review the manifest.** Every row's `notes` say where the mark was and how
288
+ far it moved.
289
+ 7. **`loopcutter cut`** the manifest.
290
+
291
+ ## Commands
292
+
293
+ ### `init`
294
+
295
+ ```bash
296
+ loopcutter init [DIR]
297
+ ```
298
+
299
+ Creates a workspace with its folders and a default `loopcutter.toml`. Running
300
+ it again keeps your edits.
301
+
302
+ ### `prep`
303
+
304
+ ```bash
305
+ loopcutter prep [FILES OR FOLDERS ...]
306
+ ```
307
+
308
+ Decodes each source once, resamples it once, takes `headroom_db` off, and
309
+ writes a 24-bit AIFF master, adding a row to `tracks.csv`. Folders are
310
+ searched recursively, skipping hidden folders and the workspace's own masters.
311
+ Masters are named after the source file, so a lossless
312
+ file and a lossy copy with the same name make the same master: the lossless
313
+ file wins, and the lossy one is skipped with a note (names are
314
+ compared as a case-insensitive filesystem sees them, an `.m4a` counts as
315
+ lossless only if it holds ALAC, and the two must be the same length to within
316
+ 0.25 s). A master already built from a lossy file is rebuilt when a lossless
317
+ copy of the same track appears; a different track that shares a name is
318
+ reported as CHANGED and left alone. The rebuild happens beside the masters
319
+ and swaps in under the old master's name only when it's complete: a copy of
320
+ the old master is kept in `replaced_dir`, its tags (except DJ-app cue data)
321
+ are copied onto the new one, your `override_*` columns are kept, and the rest
322
+ of the track's analysis is left for `scan`. Re-analyse the track in your DJ
323
+ app too, because its cues were placed on the old audio. Any other pair of sources that would
324
+ make the same master is refused before anything is written. Loud MP3s
325
+ decode above full scale; the headroom keeps those peaks, and any sample still
326
+ over is clipped and counted.
327
+
328
+ ### `scan`
329
+
330
+ ```bash
331
+ loopcutter scan [TRACK_ID ...] [--app serato|rekordbox] [--force]
332
+ ```
333
+
334
+ Analyses each master once: tempo, bar phase, attack phase, key, and with
335
+ `--app` the DJ app's tempo and offset. It writes them to `tracks.csv` with a
336
+ flag for anything doubtful:
337
+
338
+ | Flag | Means |
339
+ |---|---|
340
+ | `grid-fit` | Under 90% of the detected beats fit one steady grid: a tempo change, a long break or a swung rhythm. Snapping uses the whole-track grid wherever it still fits the beats around a mark, and a local grid only where one fits clearly better (a real tempo change). |
341
+ | `bar-phase` | The downbeats disagree about which beat is the one. |
342
+ | `phase` | The attacks don't agree on where the beat sits. Only rekordbox marks made on the master are kept as they are. |
343
+ | `key` | The key tag and keyfinder disagree. |
344
+ | `app-bpm` | The DJ app's tempo differs by more than 0.05 BPM. |
345
+ | `half-beat` | The DJ app's grid sits half a beat from ours. |
346
+ | `app-offset` | On a lossless file, the app's grid sits more than 20 ms from ours. |
347
+
348
+ `override_bpm` and `override_phase_ms` in `tracks.csv` are yours: `scan` never
349
+ touches them, and snapping uses them when set. Tracks already analysed are
350
+ skipped unless you pass `--force`. A report of each run goes in `reports/`.
351
+
352
+ ### `import`
353
+
354
+ ```bash
355
+ loopcutter import [--from rekordbox|rekordbox-xml|serato] [FILES ...] [--playlist NAME] [--xml FILE] [--out FILE] [--max-shift-ms N]
356
+ ```
357
+
358
+ Turns marked loops into a resolved manifest. `--from` defaults to `[marking]
359
+ app`. An existing file is never overwritten.
360
+
361
+ ### `resolve`
362
+
363
+ ```bash
364
+ loopcutter resolve MANIFEST [--max-shift-ms N]
365
+ ```
366
+
367
+ Fills rows from `tracks.csv` and snaps starts marked `snap=beat` or
368
+ `snap=bar`, after backing the manifest up.
369
+
370
+ ### `stems`
371
+
372
+ ```bash
373
+ loopcutter stems TRACK_ID ... [--engine audio-separator|demucs] [--model NAME]
374
+ ```
375
+
376
+ Separates each master with [audio-separator](https://github.com/nomadkaraoke/python-audio-separator)
377
+ (Demucs `htdemucs_6s` by default: drums, bass, vocals, guitar, piano and
378
+ other), or with the Demucs command line as a fallback. Separators work at
379
+ 44.1 kHz, so each stem is resampled to the master's rate and written to
380
+ `stems/<track_id>/<stem>.aiff`, and the stems' sum is proven to line up with
381
+ the master to the sample before any loop is cut from them. Raw output is
382
+ cached, so a second run is instant.
383
+
384
+ ### `cut`
385
+
386
+ ```bash
387
+ loopcutter cut MANIFEST [options]
388
+ ```
389
+
390
+ | Option | Default | What it does |
391
+ |---|---|---|
392
+ | `--out DIR` | `loops/<format>` in a workspace, else `loops` | Output directory. |
393
+ | `--layout` | `library` in a workspace, else `flat` | `library` files loops as `<stem>/<tempo band>/`. |
394
+ | `--tag`, `--no-tag` | on for AIFF in a workspace | Writes BPM, key and stem tags. |
395
+ | `--tracks FILE` | the workspace's `tracks.csv` | Analysis used for the tempo check. |
396
+ | `--audio-root DIR` | current directory | Base for relative `source` paths. |
397
+ | `--format` | `aiff` | `aiff`, `wav` or `flac`. |
398
+ | `--subtype` | `PCM_24` | Any libsndfile subtype. |
399
+ | `--snap-ms` | `2.0` | Zero-crossing search radius (backwards only). |
400
+ | `--fade-ms` | `0.5` | Edge fade length. |
401
+ | `--trim-db` | `0.0` | Gain for every loop, for example `-1.0`. |
402
+ | `--xfade-ms` | `0.0` | Crossfades each loop's tail into the audio before its start (a row's `xfade_ms` wins). |
403
+ | `--check-bpm` | off | Measures the tempo from the audio. Automatic for analysed tracks. |
404
+ | `--lenient` | off | Reports `beat_alignment` failures as warnings, for unsteady material. |
405
+ | `--dry-run` | off | Resolves every row without writing audio. |
406
+ | `--code`, `--no-code` | on in a workspace | Ends each name with its provenance code. |
407
+
408
+ 32-bit float isn't the default because many CDJs won't play it.
409
+
410
+ **Provenance.** The code is `LC-` plus 8 hex of a hash of what the loop is:
411
+ track, label, length, stem and kind, but not the start, so re-marking a loop
412
+ keeps its code. Tagged loops also carry `TXXX:PROVENANCE_CODE` and
413
+ `TXXX:SOURCE` (artist and track, the source file, the start, bars at BPM, stem
414
+ and label), and every cut updates `provenance.csv` in the output folder, one
415
+ row per code. Re-cutting a row that was cut before codes existed replaces the
416
+ old, uncoded file.
417
+
418
+ ### `provenance`
419
+
420
+ ```bash
421
+ loopcutter provenance MANIFEST [MANIFEST ...] [--keep-names] [--dry-run]
422
+ ```
423
+
424
+ Adds codes, `SOURCE` tags and `provenance.csv` rows to loops that are already
425
+ cut, without cutting them again. By default it renames each file to its coded
426
+ name; `--keep-names` tags and indexes only. Renaming moves files that a set or
427
+ sampler project may point at, so run it before the loops are in use, or
428
+ re-point the set afterwards.
429
+
430
+ ### `inspect`
431
+
432
+ ```bash
433
+ loopcutter inspect FILE [--bpm N]
434
+ ```
435
+
436
+ Prints sample rate, channels, format, length, and the length in beats and bars
437
+ at the given tempo.
438
+
439
+ ### `keys`
440
+
441
+ See [Session key planning](#session-key-planning).
442
+
443
+ ## Output files
444
+
445
+ Files are named `Artist - Track [label][bpm][bars][key][stem].aiff`, for
446
+ example `Some Artist - Some Track [A1][128][4bar][8A][bass].aiff`. The brackets
447
+ make a library easy to sort and search in any browser. In a workspace they are
448
+ filed by stem and tempo band, such as `loops/aiff/bass/125-129/`; loops without
449
+ a stem go under `full/`, and one-shots under `<stem>/oneshots/`, named
450
+ `Artist - Track [label][oneshot].aiff`.
451
+
452
+ A row that names a `stem` and a `track_id` is cut from that track's separated
453
+ stem, while its timing is still checked on the full mix, where the attacks
454
+ are. `cut` names any stem that hasn't been separated yet. A `stem` row without
455
+ a `track_id` is cut from its `source` as given, with a note, so point `source`
456
+ at the stem file if you separated it yourself.
457
+
458
+ AIFF loops are tagged with BPM, key, stem (as the grouping), title, artist and
459
+ a comment holding the Camelot key and label. WAV loops are left untagged by
460
+ default, because some hardware samplers reject the tag chunk; pass `--tag` to
461
+ tag them anyway.
462
+
463
+ Ableton Live doesn't read the BPM in a filename. It assumes a clip is 1, 2, 4,
464
+ 8 or 16 bars long and sets the clip's tempo from its length, so loops of those
465
+ lengths land on tempo because the lengths are exact. For any other length,
466
+ such as ½-bar rolls or 3-bar loops, `cut` prints a note: set that clip's tempo
467
+ by hand.
468
+
469
+ To make two copies of the same cuts, run the manifest twice: once as AIFF for
470
+ your DAW, and once with `--format wav` for a hardware sampler.
471
+
472
+ ### Roll variations
473
+
474
+ A `variations` cell such as `"2,1,0.5"` turns one row into several loops that
475
+ share a start. Put them in one clip-launcher column, for example Ableton's
476
+ Session view played from a Launchpad. Set the clips to Legato launch so
477
+ switching keeps phase, and pressing down the column gives a roll that stays
478
+ locked. Each one is a real file cut to an exact sample count.
479
+
480
+ ### Sample rates and tiling
481
+
482
+ Sample counts are whole numbers, so a sub-bar variation doesn't always divide
483
+ its parent exactly. Whether it does depends on the tempo as well as the rate:
484
+
485
+ | Rate | Common tempos where half bars tile exactly |
486
+ |---|---|
487
+ | 48 kHz | 120, 125, 128, 144, 150, 160 BPM |
488
+ | 44.1 kHz | 120, 125, 126, 135, 140, 144, 147, 150, 160 BPM |
489
+
490
+ Neither rate is always better. At other tempos a variation drifts by a few
491
+ samples per cycle: up to 4 for a half bar against 4 bars, and up to 8 against
492
+ 8 or 16 bars, under 0.2 ms. `cut` reports each drifting variation set
493
+ and, when the other rate would be exact, names it. DAWs that warp clips
494
+ re-sync them every cycle anyway. loopcutter never resamples at cut time, so
495
+ the rate is chosen once, when `prep` makes the masters.
496
+
497
+ ## Verification
498
+
499
+ An agent can't hear the output, and neither can a batch run, so every file is
500
+ checked before a run reports success. Every check has a test proving it can
501
+ fail.
502
+
503
+ - **`sample_count`, `sample_rate`:** the file is exactly the declared length at
504
+ the source's rate.
505
+ - **`peak_headroom`:** the loop is no louder than its source, after any
506
+ `--trim-db`. A master that already peaks at full scale passes; a trim that
507
+ would push a loop past full scale fails.
508
+ - **`not_silent`, `dc_offset`.**
509
+ - **`beat_alignment`:** finds the strongest attack within 60 ms of each of the
510
+ loop's beats, in the source around the loop (the full mix, for a stem).
511
+ - *Placement* is where those attacks sit. It passes from −3 to +8 ms, warns
512
+ out to −10 or +15 ms, and fails beyond. An attack before the start means
513
+ the start cuts into it.
514
+ - *Drift* is how the attacks move from the loop's first beat to its last,
515
+ which is what a wrong tempo looks like. It warns above 4 ms and fails
516
+ above 10 ms.
517
+ - When under half the beats share a steady attack (breaks, pads, swung
518
+ material), it reports *not judged* rather than guessing.
519
+ - `--lenient` turns its failures into warnings.
520
+ - One-shots have no beats to align and no tempo to match, so they get the
521
+ length, rate, headroom, silence and DC checks only.
522
+ - **`bpm_match`:** how far the loop's end lands from where the next bar
523
+ begins. Against the tempo `scan` proposed it fails above 2 ms. On a
524
+ `grid-fit` track, and with `--check-bpm` on an unanalysed one, it measures
525
+ the tempo from the audio instead and fails above 5 ms; on a `grid-fit`
526
+ track a half- or double-time tempo fails outright.
527
+
528
+ A failed check names the file and the reason, and the run exits with an error.
529
+
530
+ ## Session key planning
531
+
532
+ Key detection is unreliable on short loops. Analyse the full source tracks
533
+ instead: `scan` reads the key your DJ software or Mixed In Key wrote to each
534
+ master, cross-checks it with keyfinder-cli, and carries it into the manifest's
535
+ `key` column. Every slice inherits its parent's key.
536
+
537
+ Then work out what to build the set around:
538
+
539
+ ```bash
540
+ loopcutter keys library.xlsx --histogram
541
+ loopcutter keys library.xlsx --keys 3 --semitones 3 -v
542
+ loopcutter keys library.xlsx --sweep
543
+ ```
544
+
545
+ `keys` reads CSV, XLSX or a manifest, using a column called `key`, `camelot`
546
+ or `initial key`, so exports from Mixed In Key, Serato and rekordbox work as
547
+ they are. It accepts Camelot (`8A`) and named keys (`Am`, `F# minor`, `Bb`).
548
+ It rejects Open Key rather than misreading it, because Open Key numbers sit
549
+ five places away from Camelot's.
550
+
551
+ The model is transposition, not harmonic mixing: a loop is usable in a session
552
+ key if you can pitch it there within the limit. It picks the key that covers
553
+ the most loops, then the best key for what's left, and reports the exact
554
+ semitone shift for each loop.
555
+
556
+ | Flag | Default | What it does |
557
+ |---|---|---|
558
+ | `--keys N` | 3 | How many session keys to plan for. |
559
+ | `--semitones N` | 3 | Transposition limit either way, 0 to 6. |
560
+ | `--comfort N` | 3 | Shifts beyond this are flagged for audition in the verbose listing. |
561
+ | `--sweep` | off | Tabulates coverage at every limit from 0 to 6. |
562
+ | `--relative` | off | Counts relative major/minor as a free match. |
563
+ | `--histogram` | off | Prints the key distribution as a bar chart. |
564
+ | `--sheet NAME` | first sheet | Worksheet to read in a multi-sheet XLSX. |
565
+ | `-v`, `--verbose` | off | Lists every loop with its Camelot key and shift. |
566
+
567
+ Read the sweep's "keys to cover all" column first. Relaxing the limit by one
568
+ semitone can drop you from three session keys to two, which changes how a set
569
+ is built far more than a few percent of coverage does. The best session key
570
+ is often not the most common one: a key between two clusters can reach more
571
+ material than the biggest cluster.
572
+
573
+ ## Stems and seamless loops
574
+
575
+ One 4-bar window across six stems gives six loops you can EQ and launch apart:
576
+ run `loopcutter stems "<track_id>"` for the track, then give the rows a
577
+ `stem`. Comment a rekordbox memory loop `A1 bass` and `import` fills it in.
578
+
579
+ Edge fades stop a loop clicking, but on a sustained pad they dip to silence
580
+ at every wrap. `--xfade-ms 20` (or a row's `xfade_ms`) instead fades the
581
+ loop's tail into the audio just before its start, so the wrap plays exactly
582
+ what the source played there. The length doesn't change, and because the two
583
+ sides are similar audio, the linear blend never exceeds the source's peak.
584
+
585
+ ## Known issues
586
+
587
+ - **rekordbox's database format changes between versions.** If
588
+ `import --from rekordbox` can't read yours, export the collection as XML
589
+ from rekordbox and use `--from rekordbox-xml --xml FILE`.
590
+ - **Tempo-changing tracks get local grids.** A track whose beats don't fit one
591
+ steady grid is flagged `grid-fit`. Each mark is snapped to the whole-track
592
+ grid where that still fits the nearby beats, and otherwise to a grid fitted
593
+ to the 64 beats around it, provided that grid fits clearly better and its
594
+ tempo isn't a half- or double-time reading. A mark where neither holds is
595
+ refused. On a tempo-changing track the `tracks.csv` tempo is only an
596
+ average, so `cut` checks those loops against the tempo measured from the
597
+ audio.
598
+ - **Odd bar lengths need their tempo set in Live by hand** (see
599
+ [Output files](#output-files)).
600
+ - **Starts in beatless passages can't be judged.** `beat_alignment` reports
601
+ *not judged* there, so a hand-typed start in a breakdown relies on the grid
602
+ alone.
603
+
604
+ ## Roadmap
605
+
606
+ - An audition page: each master's waveform with the cutter's own bar lines,
607
+ where a click previews the exact loop and a key accepts it into a manifest.
608
+ - Ableton integration: the right tempo for odd-length and half-bar clips, and
609
+ a generated Live Set with each loop family in one Launchpad column.
610
+
611
+ ## Development
612
+
613
+ ```bash
614
+ pytest -q # unit tests: synthetic audio only, no model weights
615
+ pytest -q -m slow # the real beat detector and ffmpeg
616
+ ```
617
+
618
+ ```
619
+ src/loopcutter/
620
+ model.py shared data types: Grid, TrackRecord, Marker, SnapResult
621
+ onsets.py the one onset detector that the grid, the analysis and the checks share
622
+ timing.py sample arithmetic, no file I/O
623
+ workspace.py finding and creating workspaces
624
+ audio_io.py reading any audio file (libsndfile, else ffmpeg)
625
+ prep.py lossless working masters
626
+ grid.py beat-grid fit, bar phase, attack phase, local grids
627
+ keydetect.py key from tags, cross-checked with keyfinder-cli
628
+ trackdb.py tracks.csv
629
+ analyse.py scan: one analysis per master
630
+ markers.py reading marks and grids from rekordbox and Serato
631
+ snap.py app-offset correction, snapping, marks to manifest rows
632
+ manifest.py CSV to LoopSpec; all validation lives here
633
+ cut.py extraction, zero-crossing snap, edge fades
634
+ verify.py objective checks on every output
635
+ tags.py ID3v2.3 tags on AIFF and WAV loops
636
+ naming.py output filename convention and library layout
637
+ keys.py key parsing and session-cover arithmetic, no file I/O
638
+ keyreport.py spreadsheet loading and report rendering
639
+ stems.py separation, resampling to the master, alignment proof
640
+ cli.py command-line entry point
641
+ ```
642
+
643
+ The code keeps a few rules:
644
+
645
+ - Loop length always comes from tempo and bar count, rounded once.
646
+ `tests/test_timing.py` guards this against a well-meant "simplification".
647
+ - Analysis proposes and `cut` disposes: `scan` writes `tracks.csv`, only
648
+ `import` and `resolve` move a start (reporting every move), and `cut` never
649
+ moves a start or runs a model.
650
+ - Shared types go in `model.py`, and every part that looks for attacks uses
651
+ `onsets.py`, so the grid and the checks can't disagree about where a beat is.
652
+ - `timing.py` and `keys.py` do arithmetic only, so they stay testable without
653
+ audio fixtures.
654
+ - Failures are loud and name the manifest row. The tool never writes a short,
655
+ silent or wrong-length file.
656
+ - Nothing is fixed silently: no trimming to fit, no resampling at cut time, no
657
+ padding.
658
+
659
+ ## Licence
660
+
661
+ MIT. See [LICENSE](https://github.com/aaronlsmiles/loopcutter/blob/main/LICENSE).
662
+
663
+ Loops cut from commercial releases are for your own practice and performance.
664
+ Releasing anything built from them needs the rights holders' clearance.