loopcutter 0.3.0__py3-none-any.whl

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.
loopcutter/cli.py ADDED
@@ -0,0 +1,768 @@
1
+ """Command line interface.
2
+
3
+ loopcutter init ~/loops-workspace private workspace with its folders
4
+ loopcutter prep lossless working masters
5
+ loopcutter scan --app rekordbox grid, phase, key and doubts per track
6
+ loopcutter import --from rekordbox your marked loops, snapped, as a manifest
7
+ loopcutter resolve manifests/set.csv fill and snap hand-typed rows
8
+ loopcutter stems "<track_id>" separate a master into aligned stems
9
+ loopcutter cut manifests/set.csv cut, verify, tag and file
10
+ loopcutter keys library.xlsx plan session keys
11
+ loopcutter inspect loop.aiff --bpm 128 length in beats and bars
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import argparse
17
+ import csv
18
+ import importlib.util
19
+ import math
20
+ import os
21
+ import shutil
22
+ import statistics
23
+ import tempfile
24
+ import subprocess
25
+ import sys
26
+ from collections import defaultdict
27
+ from dataclasses import replace
28
+ from datetime import datetime
29
+ from pathlib import Path
30
+
31
+ import soundfile as _sf
32
+
33
+ from .cut import cut_loop, cut_oneshot
34
+ from .keyreport import load_keys, render, render_histogram, render_sweep
35
+ from .keys import (COMFORT_SEMITONES, MAX_POSSIBLE_SEMITONES, KeyParseError, parse_key,
36
+ plan_sessions, sweep)
37
+ from .manifest import ManifestError, load_manifest
38
+ from .model import TrackRecord
39
+ from .naming import build_filename, copies_of, library_subdir, loop_code, same_name
40
+ from .timing import parse_position, rates_that_tile, tiling_error_ms, tiling_error_samples
41
+ from .trackdb import load_tracks, save_tracks, track_id_for
42
+ from .verify import Check, verify_cut
43
+ from .workspace import DIRS, WorkspaceError, find_workspace, init_workspace
44
+
45
+ LIVE_INFERS_BARS = {1, 2, 4, 8, 16}
46
+
47
+
48
+ def _stamp() -> str:
49
+ return datetime.now().strftime("%Y%m%d-%H%M%S")
50
+
51
+
52
+ def _workspace_or_exit():
53
+ ws = find_workspace()
54
+ if ws is None:
55
+ print("error: not inside a loopcutter workspace - run `loopcutter init DIR` and cd into it",
56
+ file=sys.stderr)
57
+ raise SystemExit(2)
58
+ return ws
59
+
60
+
61
+ def _tiling_warnings(specs) -> list[str]:
62
+ """Variation sets whose rounded lengths don't divide evenly. A warning only: DAWs
63
+ that warp clips re-sync them, but it is worth knowing before stacking them."""
64
+ groups = defaultdict(list)
65
+ for spec in specs:
66
+ groups[(str(spec.source), spec.label, spec.start_seconds)].append(spec)
67
+ messages = []
68
+ for members in groups.values():
69
+ members = [m for m in members if m.kind == "loop"] # one-shots have no tempo to tile
70
+ if len(members) < 2:
71
+ continue
72
+ try:
73
+ rate = _sf.info(str(members[0].source)).samplerate
74
+ except RuntimeError:
75
+ continue
76
+ longest = max(members, key=lambda s: s.bars)
77
+ for spec in (m for m in members if m is not longest):
78
+ drift = tiling_error_samples(longest.bars, spec.bars, spec.bpm, rate, spec.beats_per_bar)
79
+ if drift:
80
+ ms = tiling_error_ms(longest.bars, spec.bars, spec.bpm, rate, spec.beats_per_bar)
81
+ exact = [r for r in rates_that_tile(spec.bars, spec.bpm, spec.beats_per_bar) if r != rate]
82
+ hint = f" Exact at {exact[0]} Hz." if exact else ""
83
+ messages.append(f"{spec.slug}: drifts {drift} sample(s) ({ms:.3f} ms) per "
84
+ f"{longest.bars:g}-bar cycle at {spec.bpm:g} BPM / {rate} Hz; DAWs "
85
+ f"that warp clips re-sync it.{hint}")
86
+ return messages
87
+
88
+
89
+ def _cmd_init(args) -> int:
90
+ try:
91
+ ws = init_workspace(args.directory)
92
+ except WorkspaceError as exc:
93
+ print(f"error: {exc}", file=sys.stderr)
94
+ return 2
95
+ print(f"workspace ready at {ws.root}")
96
+ for sub in DIRS:
97
+ print(f" {sub}/")
98
+ return 0
99
+
100
+
101
+ def _known_id(records, track_id: str) -> str:
102
+ """The id tracks.csv already uses for this master, matched as a case-insensitive
103
+ filesystem would; else the given one."""
104
+ return next((k for k in records if k.casefold() == track_id.casefold()), track_id)
105
+
106
+
107
+ def _rebuild_master(source, master_file, ws, headroom, replaced_dir):
108
+ """Build the lossless master beside the masters, carry the old one's tags over, keep a copy
109
+ of the old one, then swap the new one in under the old name. Until the swap, nothing in
110
+ masters/ has changed, so an interrupted rebuild loses nothing. Returns the copy's path."""
111
+ from . import prep
112
+ from .tags import copy_all_tags, copy_basic_tags
113
+
114
+ building = Path(tempfile.mkdtemp(dir=ws.masters, prefix=".building-"))
115
+ try:
116
+ result = prep.prepare_master(source, building, rate=int(ws.setting("audio", "sample_rate", 48000)),
117
+ subtype=ws.setting("audio", "subtype", "PCM_24"), gain_db=-headroom)
118
+ copy_basic_tags(source, result.master)
119
+ aside = None
120
+ if master_file.exists():
121
+ copy_all_tags(master_file, result.master)
122
+ aside = prep.set_aside(master_file, replaced_dir)
123
+ result.master.replace(master_file)
124
+ finally:
125
+ shutil.rmtree(building, ignore_errors=True)
126
+ clip = f" CLIPPED {result.clipped} sample(s)" if result.clipped else ""
127
+ gain = f" {result.gain_db:+.1f} dB" if result.gain_db else ""
128
+ print(f" {master_file.name} {result.source_rate} -> {result.rate} Hz{gain}{clip}")
129
+ return aside
130
+
131
+
132
+ def _cmd_prep(args) -> int:
133
+ from .prep import choose_sources, find_sources, is_lossless, master_path, prepare_master, same_track
134
+ from .tags import copy_basic_tags
135
+
136
+ ws = _workspace_or_exit()
137
+ replaced_dir = Path(ws.setting("prep", "replaced_dir", "masters/.replaced")).expanduser()
138
+ replaced_dir = replaced_dir if replaced_dir.is_absolute() else ws.root / replaced_dir
139
+ own = [ws.masters.resolve(), replaced_dir.resolve()] # the workspace's masters are never sources
140
+ sources = [s for s in find_sources(args.sources or ws.setting("sources", "paths", []))
141
+ if not any(s.resolve().is_relative_to(d) for d in own)]
142
+ if not sources:
143
+ print("no audio found - pass files or folders, or set [sources] paths in loopcutter.toml "
144
+ "(the workspace's own masters are never sources)", file=sys.stderr)
145
+ return 2
146
+ try:
147
+ headroom = float(ws.setting("audio", "headroom_db", 0.0))
148
+ except (TypeError, ValueError):
149
+ headroom = -1.0
150
+ if not math.isfinite(headroom) or headroom < 0:
151
+ print("error: [audio] headroom_db must be a number of dB to take off, 0 or more", file=sys.stderr)
152
+ return 2
153
+ try:
154
+ sources, skipped = choose_sources(sources, ws.masters)
155
+ except ValueError as exc:
156
+ print(f"error: {exc}", file=sys.stderr)
157
+ return 2
158
+ for lossy, lossless in skipped:
159
+ print(f" SKIP {lossy.name}: the lossless {lossless.name} makes this master")
160
+ records = load_tracks(ws.tracks_csv)
161
+ made = stale = unbuilt = 0
162
+ for source in sources:
163
+ source = Path(source)
164
+ track_id = _known_id(records, track_id_for(master_path(source, ws.masters)))
165
+ earlier = records.get(track_id)
166
+ moved_from = earlier is not None and Path(earlier.source).resolve() != source.resolve()
167
+ master_file = ws.masters / f"{track_id}.aiff" # the name the row and your DJ app know
168
+ if moved_from and is_lossless(earlier.source) and is_lossless(source) is False:
169
+ if master_file.exists():
170
+ print(f" KEPT {master_file.name}: built from the lossless {Path(earlier.source).name}; "
171
+ f"the lossy {source.name} is ignored")
172
+ else:
173
+ print(f" KEPT {master_file.name}: its master is missing - run prep with "
174
+ f"{earlier.source} to rebuild it; the lossy {source.name} is ignored")
175
+ unbuilt += 1
176
+ continue
177
+ upgrade = (moved_from and is_lossless(source) is True and is_lossless(earlier.source) is False
178
+ and same_track(source, earlier.duration))
179
+ if moved_from and not upgrade and not master_file.exists():
180
+ print(f" CHANGED {master_file.name}: tracks.csv has it from {earlier.source}; not built "
181
+ "from this source - delete its tracks.csv row if this is the track you want")
182
+ unbuilt += 1
183
+ continue
184
+ if upgrade:
185
+ made += 1
186
+ aside = _rebuild_master(source, master_file, ws, headroom, replaced_dir)
187
+ kept = f"; a copy of the old master is in {aside}" if aside else ""
188
+ print(f" REBUILT {master_file.name}: from the lossless {source.name} "
189
+ f"(was {Path(earlier.source).name}){kept}. Run `loopcutter scan` for it again, "
190
+ "and re-analyse it in your DJ app: its cues were placed on the old audio")
191
+ info = _sf.info(str(master_file))
192
+ records[track_id] = TrackRecord(track_id=track_id, source=str(source.resolve()),
193
+ master=str(master_file), sample_rate=info.samplerate,
194
+ duration=info.frames / info.samplerate, bpm=0.0, phase=0.0,
195
+ bar_phase=0, override_bpm=earlier.override_bpm,
196
+ override_phase_ms=earlier.override_phase_ms)
197
+ if earlier.override_phase_ms is not None:
198
+ print(f" check override_phase_ms for {track_id}: the new audio may start at a "
199
+ "slightly different point")
200
+ save_tracks(ws.tracks_csv, records) # the master has changed; the row must follow now
201
+ continue
202
+ result = prepare_master(source, ws.masters, rate=int(ws.setting("audio", "sample_rate", 48000)),
203
+ subtype=ws.setting("audio", "subtype", "PCM_24"), gain_db=-headroom)
204
+ if result.stale:
205
+ stale += 1
206
+ print(f" STALE {result.master.name}: its source changed; delete the master to rebuild it")
207
+ if not result.reused:
208
+ copy_basic_tags(source, result.master)
209
+ made += 1
210
+ clip = f" CLIPPED {result.clipped} sample(s)" if result.clipped else ""
211
+ gain = f" {result.gain_db:+.1f} dB" if result.gain_db else ""
212
+ print(f" {result.master.name} {result.source_rate} -> {result.rate} Hz{gain}{clip}")
213
+ if earlier is None:
214
+ records[track_id] = TrackRecord(track_id=track_id, source=str(source.resolve()),
215
+ master=str(result.master), sample_rate=result.rate,
216
+ duration=result.frames / result.rate,
217
+ bpm=0.0, phase=0.0, bar_phase=0)
218
+ elif moved_from:
219
+ print(f" CHANGED {result.master.name}: built from {earlier.source}; delete the master "
220
+ "and its tracks.csv row to rebuild it from this source")
221
+ save_tracks(ws.tracks_csv, records)
222
+ print(f"{made} master(s) written, {len(sources) - made - unbuilt} already there, {unbuilt} not built "
223
+ f"({stale} stale), in {ws.masters}")
224
+ return 0
225
+
226
+
227
+ def _app_beats(app):
228
+ if app == "serato":
229
+ from .markers import serato_beats
230
+
231
+ return lambda record: serato_beats(record.source)
232
+ if app == "rekordbox":
233
+ from .markers import open_rekordbox, rekordbox_beats
234
+
235
+ db = open_rekordbox()
236
+ return lambda record: rekordbox_beats(db, record.master)
237
+ return None
238
+
239
+
240
+ def _cmd_scan(args) -> int:
241
+ from .analyse import scan_tracks
242
+
243
+ ws = _workspace_or_exit()
244
+ report = scan_tracks(ws.tracks_csv, only=set(args.tracks) or None, force=args.force,
245
+ app=args.app or "", app_beats_for=_app_beats(args.app),
246
+ beats_dir=ws.beats_dir)
247
+ text = report.text()
248
+ print(text)
249
+ ws.reports.mkdir(parents=True, exist_ok=True)
250
+ (ws.reports / f"scan-{_stamp()}.txt").write_text(text + "\n")
251
+ return 1 if report.errors else 0
252
+
253
+
254
+ def _beats_for(ws):
255
+ from .grid import load_beats
256
+
257
+ def load(record):
258
+ path = ws.beats_dir / f"{record.track_id}.npz"
259
+ return load_beats(path) if path.exists() else None
260
+ return load
261
+
262
+
263
+ def _cmd_import(args) -> int:
264
+ from .markers import from_rekordbox_db, from_rekordbox_xml, from_serato
265
+ from .snap import markers_to_rows, write_manifest
266
+
267
+ ws = _workspace_or_exit()
268
+ tracks = load_tracks(ws.tracks_csv)
269
+ playlist = args.playlist or ws.setting("marking", "playlist", "")
270
+ args.source = args.source or ws.setting("marking", "app", "rekordbox")
271
+ if args.source not in {"rekordbox", "rekordbox-xml", "serato"}:
272
+ print(f"error: [marking] app must be rekordbox, rekordbox-xml or serato, got {args.source!r}",
273
+ file=sys.stderr)
274
+ return 2
275
+ try:
276
+ if args.source == "serato":
277
+ paths = [Path(p) for p in args.files] or [Path(r.source) for r in tracks.values()]
278
+ markers = from_serato(paths)
279
+ elif args.source == "rekordbox":
280
+ if not playlist:
281
+ raise ValueError("name the playlist with --playlist or [marking] playlist")
282
+ markers = from_rekordbox_db(playlist)
283
+ else:
284
+ if not args.xml:
285
+ raise ValueError("--from rekordbox-xml needs --xml FILE")
286
+ markers = from_rekordbox_xml(Path(args.xml), playlist or None)
287
+ except (ValueError, OSError) as exc:
288
+ print(f"error: {exc}", file=sys.stderr)
289
+ return 2
290
+ result = markers_to_rows(markers, tracks, beats_for=_beats_for(ws),
291
+ max_shift_ms=(args.max_shift_ms if args.max_shift_ms is not None else ws.setting("snap", "max_shift_ms", 60)))
292
+ out = Path(args.out) if args.out else ws.manifests / f"import-{args.source}-{_stamp()}.csv"
293
+ try:
294
+ write_manifest(result.rows, out)
295
+ except FileExistsError as exc:
296
+ print(f"error: {exc}", file=sys.stderr)
297
+ return 2
298
+ print(f"{len(markers)} marker(s) -> {len(result.rows)} row(s) in {out}")
299
+ if result.moves_ms:
300
+ moves = result.moves_ms
301
+ print(f" moved onto the grid: median {statistics.median(moves):+.1f} ms, "
302
+ f"range {min(moves):+.1f} to {max(moves):+.1f} ms")
303
+ for problem in result.problems:
304
+ print(f" SKIP {problem}", file=sys.stderr)
305
+ return 1 if result.problems else 0
306
+
307
+
308
+ def _cmd_resolve(args) -> int:
309
+ from .snap import SnapError, grid_at, snap_time
310
+
311
+ ws = _workspace_or_exit()
312
+ tracks = load_tracks(ws.tracks_csv)
313
+ beats_for = _beats_for(ws)
314
+ path = Path(args.manifest)
315
+ with path.open(newline="", encoding="utf-8-sig") as handle:
316
+ reader = csv.DictReader(handle, restkey="_extra", restval="")
317
+ fields, rows = list(reader.fieldnames or []), list(reader)
318
+ ragged = [n for n, row in enumerate(rows, start=2) if "_extra" in row]
319
+ if ragged:
320
+ for number in ragged:
321
+ print(f" FAIL row {number}: more cells than the header - quote any value "
322
+ "that contains a comma", file=sys.stderr)
323
+ print(f"{path} left unchanged", file=sys.stderr)
324
+ return 2
325
+ for column in ("source", "bpm", "key", "snap", "notes"):
326
+ if column not in fields:
327
+ fields.append(column)
328
+ limit = (args.max_shift_ms if args.max_shift_ms is not None else ws.setting("snap", "max_shift_ms", 60))
329
+ failures = changed = 0
330
+ for number, row in enumerate(rows, start=2):
331
+ track_id = row.get("track_id")
332
+ mode = (row.get("snap") or "").strip().lower()
333
+ if not track_id:
334
+ if mode:
335
+ print(f" FAIL row {number}: snap needs a track_id", file=sys.stderr)
336
+ failures += 1
337
+ continue
338
+ record = tracks.get(track_id)
339
+ if record is None:
340
+ print(f" FAIL row {number}: {track_id!r} is not in tracks.csv", file=sys.stderr)
341
+ failures += 1
342
+ continue
343
+ try:
344
+ if mode not in {"", "beat", "bar"}:
345
+ raise ValueError("snap must be beat, bar or empty")
346
+ if mode and not row.get("start"):
347
+ raise ValueError("snap needs a start")
348
+ done = not mode and row.get("bpm") and row.get("source")
349
+ if not row.get("start") and not row.get("bpm") and "grid-fit" in record.flags.split(";"):
350
+ raise ValueError("this track's tempo moves, so give a start (or a bpm) for this row")
351
+ at = row.get("start") or row.get("downbeat")
352
+ start = parse_position(at) if at else 0.0
353
+ grid, bpm = (None, 0.0) if done else grid_at(record, start, beats_for)
354
+ if mode and "phase" in record.flags.split(";") and record.override_phase_ms is None:
355
+ raise ValueError("this track's grid phase isn't confident - set override_phase_ms "
356
+ "in tracks.csv, or mark it in rekordbox and import")
357
+ moved = snap_time(start, grid, mode, limit) if mode else None
358
+ except (SnapError, ValueError) as exc:
359
+ print(f" FAIL row {number}: {exc}", file=sys.stderr)
360
+ failures += 1
361
+ continue
362
+ row["source"] = row.get("source") or record.master
363
+ row["bpm"] = row.get("bpm") or f"{bpm:g}"
364
+ row["key"] = row.get("key") or record.key
365
+ if moved is not None:
366
+ row["start"], row["snap"] = f"{moved.snapped:.6f}", ""
367
+ row["notes"] = (row.get("notes", "") + f" resolved {moved.shift_ms:+.1f} ms").strip()
368
+ print(f" row {number}: start moved {moved.shift_ms:+.1f} ms onto the {mode}")
369
+ changed += 1
370
+ ws.reports.mkdir(parents=True, exist_ok=True)
371
+ shutil.copy2(path, ws.reports / f"{path.stem}.{_stamp()}.bak.csv")
372
+ temp = path.with_suffix(".partial.csv")
373
+ with temp.open("w", newline="", encoding="utf-8") as handle:
374
+ writer = csv.DictWriter(handle, fieldnames=fields)
375
+ writer.writeheader()
376
+ writer.writerows(rows)
377
+ temp.replace(path)
378
+ print(f"{changed} row(s) resolved in {path}; backup in {ws.reports}")
379
+ return 1 if failures else 0
380
+
381
+
382
+ def _cmd_stems(args) -> int:
383
+ from .stems import DEFAULT_MODEL, conform_stems, separate
384
+
385
+ ws = _workspace_or_exit()
386
+ tracks = load_tracks(ws.tracks_csv)
387
+ model = args.model or (DEFAULT_MODEL if args.engine == "audio-separator" else "htdemucs_6s")
388
+ failures = 0
389
+ for track_id in args.tracks:
390
+ record = tracks.get(track_id)
391
+ if record is None:
392
+ print(f" FAIL {track_id}: not in tracks.csv", file=sys.stderr)
393
+ failures += 1
394
+ continue
395
+ try:
396
+ raw = separate(record.master, ws.stems, engine=args.engine, model=model)
397
+ stems = conform_stems(raw, record.master, ws.stems / track_id)
398
+ except ImportError as exc:
399
+ print(f"error: {exc.name or exc} isn't installed - install loopcutter[stems]", file=sys.stderr)
400
+ return 2
401
+ except (RuntimeError, OSError, subprocess.CalledProcessError) as exc:
402
+ print(f" FAIL {track_id}: {exc}", file=sys.stderr)
403
+ failures += 1
404
+ continue
405
+ clipped = sum(getattr(stems, "clipped", {}).values())
406
+ level = f"{getattr(stems, 'gain_db', 0.0):+.2f} dB against the master"
407
+ print(f" {track_id}: " + ", ".join(sorted(stems)) + f" ({level}"
408
+ + (f", {clipped} sample(s) clipped" if clipped else "") + ")")
409
+ return 1 if failures else 0
410
+
411
+
412
+ def _tag(result, spec, extra=None) -> None:
413
+ from .tags import write_loop_tags
414
+
415
+ try:
416
+ key = parse_key(spec.key) if spec.key else None
417
+ except KeyParseError:
418
+ key = None
419
+ length = "oneshot" if spec.kind == "oneshot" else f"{spec.bars:g}bar"
420
+ write_loop_tags(result.output, bpm=spec.bpm or None, key=key, stem=spec.stem,
421
+ title=f"{spec.track or spec.source.stem} [{spec.label}][{length}]",
422
+ artist=spec.artist, comment=spec.label, extra=extra)
423
+
424
+
425
+ def _provenance_tags(spec, code, source_file) -> dict[str, str]:
426
+ from .provenance import source_text
427
+
428
+ return {"PROVENANCE_CODE": code, "SOURCE": source_text(spec, source_file)}
429
+
430
+
431
+ def _cmd_cut(args) -> int:
432
+ ws = find_workspace()
433
+ tracks_csv = args.tracks or (ws.tracks_csv if ws else None)
434
+ tracks = load_tracks(tracks_csv) if tracks_csv else {}
435
+ try:
436
+ specs = load_manifest(args.manifest, args.audio_root)
437
+ except ManifestError as exc:
438
+ print(f"manifest error: {exc}", file=sys.stderr)
439
+ return 2
440
+ out_root = Path(args.out) if args.out else (ws.loops / args.format if ws else Path("loops"))
441
+ layout = args.layout or ("library" if ws else "flat")
442
+ tagging = args.tag if args.tag is not None else (ws is not None and args.format == "aiff")
443
+ coding = args.code if args.code is not None else ws is not None
444
+ if tagging and args.format == "flac":
445
+ print("error: --tag writes ID3 tags, which FLAC files don't use", file=sys.stderr)
446
+ return 2
447
+
448
+ print(f"{len(specs)} loop(s) in {args.manifest}")
449
+ if importlib.util.find_spec("librosa") is None:
450
+ print(" note: librosa isn't installed, so beat_alignment can't be judged; "
451
+ "install loopcutter[verify]")
452
+ for line in _tiling_warnings(specs):
453
+ print(f" note: {line}")
454
+ for spec in specs:
455
+ if spec.kind == "loop" and spec.bars not in LIVE_INFERS_BARS:
456
+ print(f" note: {spec.slug}: Live infers tempo only for 1, 2, 4, 8 and 16-bar clips; "
457
+ f"set this one to {spec.bpm:g} BPM by hand")
458
+ if args.dry_run:
459
+ for spec in specs:
460
+ print(f" row {spec.row_number}: {spec.slug} {spec.bars:g} bars @ {spec.bpm:g} BPM "
461
+ f"from {spec.start_seconds:.6f}s <- {spec.source.name}")
462
+ return 0
463
+
464
+ from .provenance import index_row, update_index
465
+
466
+ failures, indexed = 0, []
467
+ for spec in specs:
468
+ named = spec # naming and identity come from the row, before a stem swaps the source
469
+ code = loop_code(named)
470
+ timing_source = None
471
+ if spec.stem and spec.stem != "full" and spec.track_id and ws is not None:
472
+ stem_file = ws.stems / spec.track_id / f"{spec.stem}.aiff"
473
+ if not stem_file.exists():
474
+ print(f" FAIL row {spec.row_number}: no {spec.stem} stem yet - run "
475
+ f"`loopcutter stems \"{spec.track_id}\"`", file=sys.stderr)
476
+ failures += 1
477
+ continue
478
+ # keep the track's name: the file is now bass.aiff, but the loop is still this track's
479
+ timing_source = spec.source
480
+ spec = replace(spec, source=stem_file, track=spec.track or spec.source.stem)
481
+ elif spec.stem and spec.stem != "full":
482
+ print(f" note: row {spec.row_number}: the {spec.stem} row is cut from its source as given; "
483
+ "give it a track_id in a workspace to cut it from separated stems")
484
+ record = tracks.get(spec.track_id) if spec.track_id else None
485
+ out_dir = out_root / library_subdir(spec) if layout == "library" else out_root
486
+ source_file = (record.source if record is not None and record.source else None) or named.source
487
+ filename = build_filename(spec, args.format, code=code if coding else None)
488
+ try:
489
+ if spec.kind == "oneshot":
490
+ result = cut_oneshot(spec, out_dir=out_dir, fmt=args.format, subtype=args.subtype,
491
+ snap_ms=args.snap_ms, trim_db=args.trim_db, filename=filename)
492
+ else:
493
+ result = cut_loop(spec, out_dir=out_dir, fmt=args.format, subtype=args.subtype,
494
+ snap_ms=args.snap_ms, fade_ms=args.fade_ms, trim_db=args.trim_db,
495
+ xfade_ms=args.xfade_ms if spec.xfade_ms is None else spec.xfade_ms,
496
+ filename=filename)
497
+ except (FileNotFoundError, ValueError) as exc:
498
+ print(f" FAIL row {spec.row_number}: {exc}", file=sys.stderr)
499
+ failures += 1
500
+ continue
501
+ result.timing_source = timing_source
502
+ # A track whose tempo moves has no single tempo to check against; measure the audio.
503
+ steady = record is not None and ("grid-fit" not in record.flags.split(";") or record.override_bpm)
504
+ # The tempo scan proposed, which import and resolve write: machine-made tracks are rounded
505
+ # to a whole BPM when the fit is within 0.01, and the check holds rows to that proposal.
506
+ reference = (record.override_bpm or record.bpm or record.bpm_fitted) if steady else None
507
+ report = verify_cut(result, check_bpm=args.check_bpm or record is not None,
508
+ reference_bpm=reference)
509
+ if record is not None and not steady and spec.kind == "loop":
510
+ from .snap import same_tempo
511
+
512
+ track_bpm = record.bpm_fitted or record.bpm
513
+ if track_bpm and not same_tempo(spec.bpm, track_bpm):
514
+ report.checks.append(Check("bpm_match", False,
515
+ f"declared {spec.bpm:g}, the track runs at {track_bpm:.2f}: "
516
+ "a half- or double-time reading of the beats"))
517
+ if args.lenient:
518
+ for check in report.checks:
519
+ if check.name == "beat_alignment" and not check.passed:
520
+ check.passed, check.warn = True, True
521
+ if tagging and report.ok:
522
+ _tag(result, spec, extra=_provenance_tags(named, code, source_file))
523
+ if _sf.info(str(result.output)).frames != result.length_samples:
524
+ report.checks.append(Check("tagging", False, "tagging changed the audio length"))
525
+ if not report.ok:
526
+ failures += 1
527
+ result.output.unlink(missing_ok=True) # a loop that failed its checks never reaches the library
528
+ print(f" FAIL {result.output.name} (not kept)", file=sys.stderr)
529
+ for check in report.failures:
530
+ print(f" {check.name}: {check.detail}", file=sys.stderr)
531
+ continue
532
+ indexed.append(index_row(named, code, result.output, out_root, source_file, args.manifest))
533
+ if coding: # an uncoded or stale-coded copy is the same loop: replace it
534
+ for older in copies_of(result.output.parent, spec, args.format):
535
+ if not os.path.samefile(older, result.output): # never the file just written (on APFS an
536
+ older.unlink() # NFD spelling of its name is that file)
537
+ snap = f" snap {result.snap_offset_samples:+d}" if result.snap_offset_samples else ""
538
+ print(f" ok {result.output.relative_to(out_root)} {result.length_samples} samples{snap}")
539
+ for check in report.warnings:
540
+ print(f" warn {check.name}: {check.detail}")
541
+
542
+ if indexed:
543
+ update_index(out_root, indexed)
544
+ if failures:
545
+ print(f"\n{failures} of {len(specs)} failed", file=sys.stderr)
546
+ return 1
547
+ print(f"\nall {len(specs)} loops written to {out_root}")
548
+ return 0
549
+
550
+
551
+ def _cmd_provenance(args) -> int:
552
+ """Codes, SOURCE tags and index rows for loops already cut (by a version without codes)."""
553
+ from .provenance import index_row, update_index
554
+ from .tags import write_extra_tags
555
+
556
+ ws = find_workspace()
557
+ tracks = load_tracks(ws.tracks_csv) if ws else {}
558
+ out_root = Path(args.out) if args.out else (ws.loops / args.format if ws else Path("loops"))
559
+ layout = args.layout or ("library" if ws else "flat")
560
+ rows, missing = [], 0
561
+ for manifest in args.manifests:
562
+ try:
563
+ specs = load_manifest(manifest, args.audio_root)
564
+ except ManifestError as exc:
565
+ print(f"manifest error: {exc}", file=sys.stderr)
566
+ return 2
567
+ for spec in specs:
568
+ code = loop_code(spec)
569
+ out_dir = out_root / library_subdir(spec) if layout == "library" else out_root
570
+ coded = out_dir / build_filename(spec, args.format, code=code)
571
+ found = copies_of(out_dir, spec, args.format)
572
+ if not found:
573
+ missing += 1
574
+ print(f" not cut yet: row {spec.row_number} {build_filename(spec, args.format)}")
575
+ continue
576
+ path = next((p for p in found if same_name(p.name, coded.name)), found[0])
577
+ if not same_name(path.name, coded.name) and not args.keep_names and not args.dry_run:
578
+ os.replace(path, coded) # uncoded, or coded from another spelling of the row
579
+ path = coded
580
+ record = tracks.get(spec.track_id) if spec.track_id else None
581
+ source_file = (record.source if record is not None and record.source else None) or spec.source
582
+ if not args.dry_run and args.format == "aiff":
583
+ write_extra_tags(path, _provenance_tags(spec, code, source_file))
584
+ rows.append(index_row(spec, code, path, out_root, source_file, manifest))
585
+ print(f" {code} {path.relative_to(out_root)}")
586
+ if rows and not args.dry_run:
587
+ update_index(out_root, rows)
588
+ print(f"\n{len(rows)} loop(s) recorded in {out_root / 'provenance.csv'}" + (f", {missing} not cut yet" if missing else ""))
589
+ return 0
590
+
591
+
592
+ def build_parser() -> argparse.ArgumentParser:
593
+ parser = argparse.ArgumentParser(prog="loopcutter")
594
+ sub = parser.add_subparsers(dest="command", required=True)
595
+
596
+ init = sub.add_parser("init", help="create a private workspace (masters, manifests, loops ...)")
597
+ init.add_argument("directory", nargs="?", default=".")
598
+ init.set_defaults(func=_cmd_init)
599
+
600
+ prep = sub.add_parser("prep", help="make lossless working masters at the workspace rate")
601
+ prep.add_argument("sources", nargs="*", help="files or folders (default: [sources] paths)")
602
+ prep.set_defaults(func=_cmd_prep)
603
+
604
+ scan = sub.add_parser("scan", help="analyse masters: grid, phase, key, app cross-check")
605
+ scan.add_argument("tracks", nargs="*", help="track_ids to analyse (default: all pending)")
606
+ scan.add_argument("--app", choices=["serato", "rekordbox"], default=None)
607
+ scan.add_argument("--force", action="store_true", help="re-analyse tracks already done")
608
+ scan.set_defaults(func=_cmd_scan)
609
+
610
+ imp = sub.add_parser("import", help="turn loops marked in DJ software into a resolved manifest")
611
+ imp.add_argument("--from", dest="source", default=None, choices=["rekordbox", "rekordbox-xml", "serato"],
612
+ help="default: [marking] app in loopcutter.toml")
613
+ imp.add_argument("files", nargs="*", help="Serato: audio files (default: every source)")
614
+ imp.add_argument("--playlist", default=None)
615
+ imp.add_argument("--xml", default=None, help="rekordbox XML export (for rekordbox-xml)")
616
+ imp.add_argument("--out", default=None)
617
+ imp.add_argument("--max-shift-ms", type=float, default=None)
618
+ imp.set_defaults(func=_cmd_import)
619
+
620
+ res = sub.add_parser("resolve", help="fill rows from tracks.csv and snap starts marked snap=beat|bar")
621
+ res.add_argument("manifest")
622
+ res.add_argument("--max-shift-ms", type=float, default=None)
623
+ res.set_defaults(func=_cmd_resolve)
624
+
625
+ cut = sub.add_parser("cut", help="cut every loop in a resolved manifest")
626
+ cut.add_argument("manifest")
627
+ cut.add_argument("--out", default=None, help="default: loops/<format> in a workspace, else ./loops")
628
+ cut.add_argument("--audio-root", default=None,
629
+ help="base directory for relative source paths "
630
+ "(defaults to the current working directory)")
631
+ cut.add_argument("--tracks", default=None, help="tracks.csv for the tempo check (default: the workspace's)")
632
+ cut.add_argument("--layout", choices=["flat", "library"], default=None,
633
+ help="library files loops as <stem>/<tempo band>/ (default in a workspace)")
634
+ cut.add_argument("--tag", action=argparse.BooleanOptionalAction, default=None,
635
+ help="write BPM, key and stem tags (default: on for AIFF in a workspace)")
636
+ cut.add_argument("--format", default="aiff", choices=["aiff", "wav", "flac"])
637
+ cut.add_argument("--subtype", default="PCM_24")
638
+ cut.add_argument("--snap-ms", type=float, default=2.0)
639
+ cut.add_argument("--fade-ms", type=float, default=0.5)
640
+ cut.add_argument("--trim-db", type=float, default=0.0, help="gain for every loop, e.g. -1.0")
641
+ cut.add_argument("--xfade-ms", type=float, default=0.0,
642
+ help="crossfade the loop's tail into the audio before its start (a row's xfade_ms wins)")
643
+ cut.add_argument("--check-bpm", action="store_true",
644
+ help="measure the tempo from the audio (automatic for analysed tracks)")
645
+ cut.add_argument("--lenient", action="store_true",
646
+ help="report beat_alignment failures as warnings (for unsteady material)")
647
+ cut.add_argument("--dry-run", action="store_true")
648
+ cut.add_argument("--code", action=argparse.BooleanOptionalAction, default=None,
649
+ help="end each name with a provenance code [LC-...] (default in a workspace)")
650
+ cut.set_defaults(func=_cmd_cut)
651
+
652
+ prov = sub.add_parser("provenance", help="add codes, SOURCE tags and provenance.csv rows to loops already cut")
653
+ prov.add_argument("manifests", nargs="+")
654
+ prov.add_argument("--out", default=None, help="default: loops/<format> in a workspace, else ./loops")
655
+ prov.add_argument("--audio-root", default=None)
656
+ prov.add_argument("--layout", choices=["flat", "library"], default=None)
657
+ prov.add_argument("--format", default="aiff", choices=["aiff", "wav", "flac"])
658
+ prov.add_argument("--keep-names", action="store_true", help="tag and index, but don't add the code to names")
659
+ prov.add_argument("--dry-run", action="store_true")
660
+ prov.set_defaults(func=_cmd_provenance)
661
+
662
+ stems = sub.add_parser("stems", help="separate masters into stems at the master's rate")
663
+ stems.add_argument("tracks", nargs="+", help="track_ids from tracks.csv")
664
+ stems.add_argument("--engine", choices=["audio-separator", "demucs"], default="audio-separator")
665
+ stems.add_argument("--model", default=None)
666
+ stems.set_defaults(func=_cmd_stems)
667
+
668
+ keys = sub.add_parser(
669
+ "keys",
670
+ help="work out the best session key(s) for a library of loops")
671
+ keys.add_argument("path", help="CSV, XLSX or manifest with a key column")
672
+ keys.add_argument("--keys", type=int, default=3,
673
+ help="how many session keys to plan for (default 3)")
674
+ keys.add_argument("--semitones", type=int, default=3,
675
+ help="transposition limit either way, 0-6 (default 3). "
676
+ "4 and 5 are past the usual comfort zone but are "
677
+ "guidance, not physics")
678
+ keys.add_argument("--comfort", type=int, default=COMFORT_SEMITONES,
679
+ help="shifts beyond this are flagged for audition "
680
+ f"(default {COMFORT_SEMITONES})")
681
+ keys.add_argument("--sweep", action="store_true",
682
+ help="tabulate coverage at every limit from 0 to 6")
683
+ keys.add_argument("--relative", action="store_true",
684
+ help="also allow relative major/minor as a free match")
685
+ keys.add_argument("--sheet", default=None,
686
+ help="worksheet name, for multi-sheet xlsx files")
687
+ keys.add_argument("--histogram", action="store_true",
688
+ help="also print the key distribution")
689
+ keys.add_argument("-v", "--verbose", action="store_true",
690
+ help="list every loop and its transposition")
691
+ keys.set_defaults(func=_cmd_keys)
692
+
693
+ inspect = sub.add_parser("inspect", help="print audio file facts")
694
+ inspect.add_argument("path")
695
+ inspect.add_argument("--bpm", type=float, default=None)
696
+ inspect.set_defaults(func=_cmd_inspect)
697
+
698
+ return parser
699
+
700
+
701
+ def _cmd_inspect(args: argparse.Namespace) -> int:
702
+ import soundfile as sf
703
+
704
+ info = sf.info(args.path)
705
+ print(f"{args.path}")
706
+ print(f" {info.samplerate} Hz, {info.channels} ch, {info.subtype}")
707
+ print(f" {info.frames} frames, {info.duration:.3f} s")
708
+ if args.bpm:
709
+ beats = info.duration * args.bpm / 60.0
710
+ print(f" at {args.bpm} BPM that is {beats:.4f} beats "
711
+ f"({beats / 4:.4f} bars)")
712
+ return 0
713
+
714
+
715
+ def _cmd_keys(args: argparse.Namespace) -> int:
716
+ try:
717
+ load = load_keys(args.path, sheet=args.sheet)
718
+ except (FileNotFoundError, ValueError, ImportError) as exc:
719
+ print(f"error: {exc}", file=sys.stderr)
720
+ return 2
721
+
722
+ if not load.entries:
723
+ print("No readable keys found.", file=sys.stderr)
724
+ return 1
725
+
726
+ if not 0 <= args.semitones <= MAX_POSSIBLE_SEMITONES:
727
+ print(f"error: --semitones must be 0 to {MAX_POSSIBLE_SEMITONES}. "
728
+ "A tritone is the furthest two keys can be; past that you are "
729
+ "travelling the other way round the circle.", file=sys.stderr)
730
+ return 2
731
+
732
+ plan = plan_sessions(
733
+ load.entries,
734
+ max_keys=args.keys,
735
+ max_semitones=args.semitones,
736
+ allow_relative=args.relative,
737
+ total_rows=load.total_rows,
738
+ )
739
+ print(render(plan, load, verbose=args.verbose, comfort=args.comfort))
740
+
741
+ if args.sweep:
742
+ print()
743
+ print(render_sweep(
744
+ sweep(load.entries, max_keys=args.keys,
745
+ allow_relative=args.relative, comfort=args.comfort),
746
+ max_keys=args.keys, comfort=args.comfort))
747
+
748
+ if args.histogram:
749
+ print()
750
+ print(render_histogram(load.entries))
751
+ return 0
752
+
753
+
754
+ def main(argv: list[str] | None = None) -> int:
755
+ args = build_parser().parse_args(argv)
756
+ try:
757
+ return args.func(args)
758
+ except BrokenPipeError:
759
+ # Piped into head or less and the reader went away. Not an error.
760
+ try:
761
+ sys.stdout.close()
762
+ except BrokenPipeError:
763
+ pass
764
+ return 0
765
+
766
+
767
+ if __name__ == "__main__":
768
+ raise SystemExit(main())