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/__init__.py ADDED
@@ -0,0 +1,13 @@
1
+ """Sample-accurate loop extraction from a manifest."""
2
+
3
+ __version__ = "0.3.0"
4
+
5
+ from .cut import cut_loop
6
+ from .manifest import LoopSpec, load_manifest
7
+ from .keys import Key, parse_key, plan_sessions
8
+ from .verify import verify_cut
9
+
10
+ __all__ = [
11
+ "cut_loop", "load_manifest", "LoopSpec", "verify_cut",
12
+ "Key", "parse_key", "plan_sessions",
13
+ ]
loopcutter/analyse.py ADDED
@@ -0,0 +1,153 @@
1
+ """scan: analyse each master once, record grid, phase, key and doubts in tracks.csv,
2
+ and cache the raw beats so snapping can fit local grids without re-running the model."""
3
+
4
+ from __future__ import annotations
5
+
6
+ from dataclasses import dataclass, field, replace
7
+ from pathlib import Path
8
+ from typing import Callable
9
+
10
+ from .audio_io import AudioReadError, read_audio
11
+ from .grid import (MIN_PHASE_AGREEMENT, Detector, GridError, analyse_grid, compare_grids,
12
+ nominal_bpm, save_beats)
13
+ from .keydetect import KeyResult, detect_key, key_from_keyfinder
14
+ from .model import Grid, TrackRecord
15
+ from .trackdb import load_tracks, save_tracks
16
+
17
+ LOSSLESS = {".wav", ".aif", ".aiff", ".flac"}
18
+ APP_FLAGS = ("app-bpm", "half-beat", "app-offset")
19
+ MIN_APP_AGREEMENT = 0.5 # below this the app's beats scatter against ours, so its offset means nothing
20
+
21
+
22
+ @dataclass
23
+ class ScanReport:
24
+ analysed: list[str] = field(default_factory=list)
25
+ compared: list[str] = field(default_factory=list)
26
+ skipped: list[str] = field(default_factory=list)
27
+ flagged: dict[str, list[str]] = field(default_factory=dict)
28
+ warnings: dict[str, str] = field(default_factory=dict)
29
+ errors: dict[str, str] = field(default_factory=dict)
30
+
31
+ def text(self) -> str:
32
+ lines = [f"{len(self.analysed)} analysed, {len(self.compared)} compared with the app, "
33
+ f"{len(self.skipped)} already done, {len(self.flagged)} flagged, "
34
+ f"{len(self.errors)} failed"]
35
+ lines += [f" FLAG {tid}: {', '.join(f)}" for tid, f in sorted(self.flagged.items())]
36
+ lines += [f" WARN {tid}: {w}" for tid, w in sorted(self.warnings.items())]
37
+ lines += [f" FAIL {tid}: {e}" for tid, e in sorted(self.errors.items())]
38
+ return "\n".join(lines)
39
+
40
+
41
+ def flags_for(grid: Grid, key: KeyResult, app: dict, lossless: bool) -> list[str]:
42
+ flags = []
43
+ if grid.inlier_ratio < 0.9:
44
+ flags.append("grid-fit")
45
+ if grid.bar_agreement < 0.8:
46
+ flags.append("bar-phase")
47
+ if grid.phase_agreement < MIN_PHASE_AGREEMENT:
48
+ flags.append("phase")
49
+ if key.disagrees:
50
+ flags.append("key")
51
+ return flags + _app_flags(grid.bpm, app, lossless)
52
+
53
+
54
+ def _app_flags(bpm: float, app: dict, lossless: bool) -> list[str]:
55
+ if not app:
56
+ return []
57
+ flags = ["app-bpm"] if abs(app["app_bpm"] - bpm) > 0.05 else []
58
+ if app.get("app_agreement", 1.0) < MIN_APP_AGREEMENT:
59
+ return flags
60
+ if app["half_beat"]:
61
+ flags.append("half-beat")
62
+ elif lossless and abs(app["app_offset_ms"]) > 20:
63
+ flags.append("app-offset")
64
+ return flags
65
+
66
+
67
+ def _app_fields(app: str, compared: dict) -> dict:
68
+ trusted = compared.get("app_agreement", 1.0) >= MIN_APP_AGREEMENT
69
+ return {"app": app if compared else "", "app_bpm": compared.get("app_bpm"),
70
+ "app_offset_ms": compared.get("app_offset_ms") if compared and trusted else None}
71
+
72
+
73
+ def _app_file_is_lossless(record: TrackRecord, app: str) -> bool:
74
+ """rekordbox is compared on the master; Serato on the source file it has tagged."""
75
+ measured = record.master if app.startswith("rekordbox") else record.source
76
+ return Path(measured).suffix.lower() in LOSSLESS
77
+
78
+
79
+ def _compare(grid: Grid, app_beats) -> dict:
80
+ return compare_grids(grid, app_beats) if app_beats is not None and len(app_beats) > 1 else {}
81
+
82
+
83
+ def compare_app(record: TrackRecord, app: str, app_beats) -> TrackRecord:
84
+ """Only the DJ-app cross-check, for a track already analysed: no model, no audio."""
85
+ grid = Grid(period=60.0 / (record.bpm_fitted or record.bpm), phase=record.phase,
86
+ bar_phase=record.bar_phase, beats_per_bar=record.beats_per_bar)
87
+ compared = _compare(grid, app_beats)
88
+ kept = [f for f in record.flags.split(";") if f and f not in APP_FLAGS]
89
+ flags = kept + _app_flags(grid.bpm, compared, _app_file_is_lossless(record, app))
90
+ return replace(record, **_app_fields(app, compared), flags=";".join(flags))
91
+
92
+
93
+ def analyse_record(record: TrackRecord, *, detector: Detector | None = None,
94
+ keyfinder: Callable = key_from_keyfinder, app_beats=None, app: str = "",
95
+ beats_dir=None) -> TrackRecord:
96
+ audio, sr = read_audio(record.master)
97
+ mono = audio.mean(axis=1)
98
+ grid, beats, downbeats = analyse_grid(mono, sr, detector=detector)
99
+ if beats_dir is not None:
100
+ save_beats(Path(beats_dir) / f"{record.track_id}.npz", beats, downbeats)
101
+ key = detect_key(record.master, keyfinder=keyfinder)
102
+ compared = _compare(grid, app_beats)
103
+ flags = flags_for(grid, key, compared, _app_file_is_lossless(record, app))
104
+ return replace(
105
+ record, sample_rate=sr, duration=len(mono) / sr, bpm=nominal_bpm(grid.bpm),
106
+ bpm_fitted=grid.bpm, phase=grid.phase, bar_phase=grid.bar_phase,
107
+ beats_per_bar=grid.beats_per_bar, inlier_ratio=grid.inlier_ratio,
108
+ bar_agreement=grid.bar_agreement, phase_agreement=grid.phase_agreement,
109
+ phase_offset_ms=grid.phase_offset * 1000,
110
+ key=key.key.camelot if key.key else "", key_source=key.source,
111
+ key_alt=key.alternative.camelot if key.alternative else "",
112
+ **_app_fields(app, compared), flags=";".join(flags))
113
+
114
+
115
+ def scan_tracks(tracks_csv, *, only: set[str] | None = None, force: bool = False,
116
+ detector: Detector | None = None, keyfinder: Callable = key_from_keyfinder,
117
+ app: str = "", app_beats_for: Callable | None = None, beats_dir=None) -> ScanReport:
118
+ records = load_tracks(tracks_csv)
119
+ report = ScanReport()
120
+ for track_id, record in sorted(records.items()):
121
+ if only and track_id not in only:
122
+ continue
123
+ done = bool(record.bpm) and not force
124
+ if done and not (app_beats_for and not record.app):
125
+ report.skipped.append(track_id)
126
+ continue
127
+ beats = None
128
+ if app_beats_for:
129
+ try:
130
+ beats = app_beats_for(record)
131
+ except Exception as exc: # a malformed tag in one file mustn't stop the scan
132
+ report.warnings[track_id] = f"can't read the {app} grid ({type(exc).__name__}: {exc})"
133
+ if done and beats is None:
134
+ report.skipped.append(track_id)
135
+ continue
136
+ try:
137
+ if done:
138
+ updated = compare_app(record, app, beats)
139
+ else:
140
+ updated = analyse_record(record, detector=detector, keyfinder=keyfinder,
141
+ app_beats=beats, app=app, beats_dir=beats_dir)
142
+ except (GridError, AudioReadError, OSError) as exc:
143
+ report.errors[track_id] = str(exc)
144
+ continue
145
+ except Exception as exc: # one bad file mustn't stop the other tracks
146
+ report.errors[track_id] = f"{type(exc).__name__}: {exc}"
147
+ continue
148
+ records[track_id] = updated
149
+ (report.compared if done else report.analysed).append(track_id)
150
+ if updated.flags:
151
+ report.flagged[track_id] = updated.flags.split(";")
152
+ save_tracks(tracks_csv, records)
153
+ return report
loopcutter/audio_io.py ADDED
@@ -0,0 +1,46 @@
1
+ """Read any audio file as float32 frames x channels.
2
+
3
+ soundfile handles WAV, AIFF, FLAC and MP3 (gapless-correct). AAC, M4A and the
4
+ rest go through ffmpeg.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import shutil
11
+ import subprocess
12
+ from pathlib import Path
13
+
14
+ import numpy as np
15
+ import soundfile as sf
16
+
17
+
18
+ class AudioReadError(RuntimeError):
19
+ """Raised when neither soundfile nor ffmpeg can read a file."""
20
+
21
+
22
+ def read_audio(path: str | Path) -> tuple[np.ndarray, int]:
23
+ path = Path(path)
24
+ try:
25
+ audio, sr = sf.read(str(path), dtype="float32", always_2d=True)
26
+ return audio, int(sr)
27
+ except sf.LibsndfileError:
28
+ return _read_with_ffmpeg(path)
29
+
30
+
31
+ def _read_with_ffmpeg(path: Path) -> tuple[np.ndarray, int]:
32
+ ffmpeg, ffprobe = shutil.which("ffmpeg"), shutil.which("ffprobe")
33
+ if not ffmpeg or not ffprobe:
34
+ raise AudioReadError(f"{path.name}: soundfile can't read it and ffmpeg isn't installed")
35
+ probe = subprocess.run(
36
+ [ffprobe, "-v", "error", "-select_streams", "a:0",
37
+ "-show_entries", "stream=sample_rate,channels", "-of", "json", str(path)],
38
+ capture_output=True, text=True, check=True)
39
+ streams = json.loads(probe.stdout).get("streams") or []
40
+ if not streams:
41
+ raise AudioReadError(f"{path.name}: no audio stream")
42
+ sr, channels = int(streams[0]["sample_rate"]), int(streams[0]["channels"])
43
+ raw = subprocess.run(
44
+ [ffmpeg, "-v", "error", "-i", str(path), "-f", "f32le", "-acodec", "pcm_f32le",
45
+ "-ac", str(channels), "-ar", str(sr), "-"], capture_output=True, check=True).stdout
46
+ return np.frombuffer(raw, dtype="<f4").reshape(-1, channels).copy(), sr