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/onsets.py ADDED
@@ -0,0 +1,117 @@
1
+ """Onsets: where attacks start, to within a millisecond, and how strong they are.
2
+
3
+ Spectral flux on 64 mel bands at a 32-sample hop, peak-picked and backtracked
4
+ to the start of each attack; on clicks the bias measured +0.02 ms. The grid,
5
+ the analysis and the checks all use this one detector.
6
+
7
+ Dense masters give 10-20 onsets a second, so "the onset nearest a beat" is
8
+ noise. What locates a beat is the *strongest* onset near it, and the
9
+ strength-weighted median of those across many beats.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import warnings
15
+ from dataclasses import dataclass
16
+
17
+ import numpy as np
18
+
19
+ HOP = 32
20
+ CHUNK_S = 60.0
21
+
22
+
23
+ def onset_envelope(mono, sr: int) -> np.ndarray:
24
+ import librosa
25
+
26
+ with warnings.catch_warnings():
27
+ warnings.filterwarnings("ignore", message="Empty filters detected")
28
+ return librosa.onset.onset_strength(y=np.ascontiguousarray(mono, dtype=np.float32), sr=sr,
29
+ hop_length=HOP, n_fft=512, n_mels=64)
30
+
31
+
32
+ def _track_envelope(mono: np.ndarray, sr: int, chunk_s: float) -> np.ndarray:
33
+ """The onset envelope of the whole track, built from overlapping chunks so a
34
+ long track never needs a full-resolution spectrogram in memory at once. Chunk
35
+ edges sit on the hop grid, so the pieces join into one frame grid."""
36
+ total = 1 + mono.size // HOP
37
+ step = max(HOP, int(chunk_s * sr) // HOP * HOP)
38
+ pad = max(HOP, sr // HOP * HOP)
39
+ envelope = np.empty(total, dtype=np.float32)
40
+ for start in range(0, mono.size, step):
41
+ lo = max(0, start - pad)
42
+ piece = onset_envelope(mono[lo : start + step + pad], sr)
43
+ first = start // HOP
44
+ last = total if start + step >= mono.size else (start + step) // HOP
45
+ envelope[first:last] = piece[first - lo // HOP : last - lo // HOP]
46
+ return envelope
47
+
48
+
49
+ def detect_onsets(mono, sr: int, chunk_s: float = CHUNK_S) -> tuple[np.ndarray, np.ndarray]:
50
+ """Onset times in seconds (sorted) and each onset's strength (the flux at its peak).
51
+
52
+ Peaks are picked once, on the whole track's envelope: onset_detect scales an
53
+ envelope by its own maximum, so picking per chunk would make weak onsets come
54
+ and go with the chunk size."""
55
+ import librosa
56
+
57
+ mono = np.asarray(mono, dtype=np.float32)
58
+ if mono.size == 0:
59
+ return np.array([]), np.array([])
60
+ envelope = _track_envelope(mono, sr, chunk_s)
61
+ peaks = librosa.onset.onset_detect(onset_envelope=envelope, sr=sr, hop_length=HOP, units="frames")
62
+ if peaks.size == 0:
63
+ return np.array([]), np.array([])
64
+ starts = librosa.onset.onset_backtrack(peaks, envelope)
65
+ return librosa.frames_to_time(starts, sr=sr, hop_length=HOP), envelope[peaks]
66
+
67
+
68
+ @dataclass(frozen=True)
69
+ class Attacks:
70
+ """The strongest onset within a window of each target time (usually each beat)."""
71
+
72
+ index: np.ndarray # which target each attack belongs to
73
+ offset: np.ndarray # seconds, attack minus target
74
+ strength: np.ndarray
75
+
76
+ def __len__(self) -> int:
77
+ return int(self.index.size)
78
+
79
+ @property
80
+ def placement(self) -> float:
81
+ """Strength-squared-weighted median offset: where the beats' attack sits."""
82
+ order = np.argsort(self.offset)
83
+ weights = np.cumsum(self.strength[order] ** 2)
84
+ return float(self.offset[order][np.searchsorted(weights, weights[-1] / 2)])
85
+
86
+ def agreement(self, targets: int, tolerance: float = 0.005) -> float:
87
+ """Share of all targets whose attack sits within `tolerance` of the placement."""
88
+ if not len(self):
89
+ return 0.0
90
+ return float(np.sum(np.abs(self.offset - self.placement) <= tolerance) / targets)
91
+
92
+ def drift(self, targets: int, tolerance: float = 0.008) -> float | None:
93
+ """How far the attack moves from the first target to the last, in seconds, fitted
94
+ only through attacks near the placement (the kick train)."""
95
+ near = np.abs(self.offset - self.placement) <= tolerance
96
+ if near.sum() < 4:
97
+ return None
98
+ slope = np.polyfit(self.index[near], self.offset[near], 1, w=self.strength[near])[0]
99
+ return float(slope * targets)
100
+
101
+
102
+ def attacks_near(times, strengths, targets, window: float) -> Attacks:
103
+ """For each target, the strongest onset within +-window of it. `times` must be sorted."""
104
+ times = np.asarray(times, dtype=float)
105
+ strengths = np.asarray(strengths, dtype=float)
106
+ targets = np.asarray(targets, dtype=float)
107
+ index, offset, strength = [], [], []
108
+ lo = np.searchsorted(times, targets - window, side="left")
109
+ hi = np.searchsorted(times, targets + window, side="right")
110
+ for i, (a, b) in enumerate(zip(lo, hi)):
111
+ if b > a:
112
+ j = a + int(np.argmax(strengths[a:b]))
113
+ index.append(i)
114
+ offset.append(times[j] - targets[i])
115
+ strength.append(strengths[j])
116
+ return Attacks(np.array(index, dtype=int), np.array(offset, dtype=float),
117
+ np.array(strength, dtype=float))
loopcutter/prep.py ADDED
@@ -0,0 +1,188 @@
1
+ """Working masters: decode once, resample once, write 24-bit AIFF at one rate.
2
+
3
+ Every DJ app then reads identical PCM, so markers carry no decoder offset.
4
+ Masters are never overwritten in place, because Mixed In Key or a DJ app may
5
+ have written tags to them. The one exception is a master built from a lossy
6
+ file when a lossless copy of the same track appears: a copy of the old master
7
+ is kept and its tags carried over (see `cli`). A changed source is otherwise
8
+ reported; delete the master to rebuild it. Headroom can be taken off first,
9
+ and any sample still over full scale is clipped and counted.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import shutil
15
+ import subprocess
16
+ from collections import defaultdict
17
+ from dataclasses import dataclass
18
+ from datetime import date
19
+ from pathlib import Path
20
+
21
+ import numpy as np
22
+ import soundfile as sf
23
+ import soxr
24
+
25
+ from .audio_io import read_audio
26
+ from .naming import sanitise
27
+
28
+ LOSSLESS_SUFFIXES = {".wav", ".aif", ".aiff", ".flac"}
29
+ CONTAINER_SUFFIXES = {".m4a", ".mp4"} # lossless only when they hold ALAC
30
+ SAME_TRACK_S = 0.25 # a lossless copy of a lossy file is this close in length
31
+ AUDIO_SUFFIXES = {".wav", ".aif", ".aiff", ".flac", ".mp3", ".m4a", ".mp4", ".aac",
32
+ ".ogg", ".opus"}
33
+
34
+
35
+ @dataclass(frozen=True)
36
+ class PrepResult:
37
+ source: Path
38
+ master: Path
39
+ source_rate: int | None
40
+ rate: int
41
+ frames: int
42
+ reused: bool
43
+ clipped: int = 0
44
+ stale: bool = False
45
+ gain_db: float = 0.0
46
+
47
+
48
+ def master_path(source, masters_dir) -> Path:
49
+ return Path(masters_dir) / f"{sanitise(Path(source).stem)}.aiff"
50
+
51
+
52
+ def find_sources(paths) -> list[Path]:
53
+ found: list[Path] = []
54
+ for item in (Path(p).expanduser() for p in paths):
55
+ if item.is_dir():
56
+ found.extend(sorted(p for p in item.rglob("*")
57
+ if p.suffix.lower() in AUDIO_SUFFIXES
58
+ and not any(part.startswith(".") for part in p.relative_to(item).parts)
59
+ and not p.name.endswith(".partial.aiff")))
60
+ elif item.suffix.lower() in AUDIO_SUFFIXES and not item.name.startswith("."):
61
+ found.append(item)
62
+ return found
63
+
64
+
65
+ def _codec(path) -> str | None:
66
+ ffprobe = shutil.which("ffprobe")
67
+ if not ffprobe:
68
+ return None
69
+ try:
70
+ run = subprocess.run([ffprobe, "-v", "error", "-select_streams", "a:0", "-show_entries",
71
+ "stream=codec_name", "-of", "default=nw=1:nk=1", str(path)],
72
+ capture_output=True, text=True, timeout=60)
73
+ except subprocess.TimeoutExpired:
74
+ return None
75
+ return (run.stdout.strip() or None) if run.returncode == 0 else None
76
+
77
+
78
+ def is_lossless(path) -> bool | None:
79
+ """True or False, or None when it can't be told (an .m4a whose codec can't be read)."""
80
+ suffix = Path(path).suffix.lower()
81
+ if suffix in LOSSLESS_SUFFIXES:
82
+ return True
83
+ if suffix in CONTAINER_SUFFIXES:
84
+ codec = _codec(path)
85
+ return None if codec is None else codec == "alac"
86
+ return False
87
+
88
+
89
+ def choose_sources(sources, masters_dir) -> tuple[list[Path], list[tuple[Path, Path]]]:
90
+ """One source per master. A lossless file always wins over lossy copies of the same
91
+ track; returns the sources to use and (skipped, used instead) pairs. Masters are
92
+ grouped as a case-insensitive filesystem sees them, and a path given twice counts
93
+ once. Any other clash (two lossless files, two lossy ones, or a file whose kind
94
+ can't be told) needs a human and is refused."""
95
+ ordered, seen = [], set()
96
+ for source in map(Path, sources):
97
+ if source.resolve() not in seen:
98
+ seen.add(source.resolve())
99
+ ordered.append(source)
100
+ by_master = defaultdict(list)
101
+ for source in ordered:
102
+ by_master[master_path(source, masters_dir).name.casefold()].append(source)
103
+ winners, skipped, clashes = {}, [], {}
104
+ for key, candidates in by_master.items():
105
+ kinds = [is_lossless(c) for c in candidates]
106
+ if len(candidates) == 1:
107
+ winners[key] = candidates[0]
108
+ elif (kinds.count(True) == 1 and kinds.count(False) == len(kinds) - 1
109
+ and all(_same_length(c, candidates[kinds.index(True)]) for c in candidates)):
110
+ winner = candidates[kinds.index(True)]
111
+ winners[key] = winner
112
+ skipped += [(c, winner) for c in candidates if c is not winner]
113
+ else:
114
+ clashes[key] = candidates
115
+ if clashes:
116
+ lines = [f"{master_path(srcs[0], masters_dir).name} <- " + ", ".join(str(s) for s in srcs)
117
+ for srcs in clashes.values()]
118
+ raise ValueError("two sources would write the same master:\n " + "\n ".join(lines))
119
+ kept = [s for s in ordered if winners[master_path(s, masters_dir).name.casefold()] is s]
120
+ return kept, skipped
121
+
122
+
123
+ def source_seconds(path) -> float | None:
124
+ try:
125
+ info = sf.info(str(path))
126
+ return info.frames / info.samplerate
127
+ except (RuntimeError, sf.LibsndfileError):
128
+ pass
129
+ ffprobe = shutil.which("ffprobe")
130
+ if not ffprobe:
131
+ return None
132
+ try:
133
+ run = subprocess.run([ffprobe, "-v", "error", "-show_entries", "format=duration",
134
+ "-of", "default=nw=1:nk=1", str(path)], capture_output=True,
135
+ text=True, timeout=60)
136
+ return float(run.stdout.strip())
137
+ except (subprocess.TimeoutExpired, ValueError):
138
+ return None
139
+
140
+
141
+ def _same_length(a, b) -> bool:
142
+ """Whether two files are plausibly one track: lengths within SAME_TRACK_S."""
143
+ seconds = source_seconds(b)
144
+ return seconds is not None and same_track(a, seconds)
145
+
146
+
147
+ def same_track(source, master_seconds: float) -> bool:
148
+ """Whether a source is plausibly the audio a master of this length was made from."""
149
+ seconds = source_seconds(source)
150
+ return seconds is not None and abs(seconds - master_seconds) <= SAME_TRACK_S
151
+
152
+
153
+ def set_aside(master: Path, replaced_dir: Path) -> Path:
154
+ """Keep a copy of a master before it's replaced, as <name>_<date>.aiff. A copy, not a
155
+ move: the master stays in place until its replacement is ready to swap in."""
156
+ replaced_dir.mkdir(parents=True, exist_ok=True)
157
+ stamp = date.today().isoformat()
158
+ dest = replaced_dir / f"{master.name}_{stamp}{master.suffix}"
159
+ count = 2
160
+ while dest.exists():
161
+ dest = replaced_dir / f"{master.name}_{stamp}-{count}{master.suffix}"
162
+ count += 1
163
+ shutil.copy2(master, dest)
164
+ return dest
165
+
166
+
167
+ def prepare_master(source, masters_dir, rate: int = 48000, subtype: str = "PCM_24",
168
+ gain_db: float = 0.0) -> PrepResult:
169
+ """`gain_db` (usually negative) is applied before writing, so decoding and resampling
170
+ overs above full scale fit."""
171
+ source = Path(source)
172
+ dest = master_path(source, masters_dir)
173
+ if dest.exists():
174
+ info = sf.info(str(dest))
175
+ return PrepResult(source, dest, None, info.samplerate, info.frames, reused=True,
176
+ stale=source.stat().st_mtime > dest.stat().st_mtime)
177
+ audio, source_rate = read_audio(source)
178
+ if source_rate != rate:
179
+ audio = soxr.resample(audio, source_rate, rate, quality="VHQ")
180
+ if gain_db:
181
+ audio = audio * 10.0 ** (gain_db / 20.0)
182
+ clipped = int(np.count_nonzero(np.abs(audio) > 1.0))
183
+ dest.parent.mkdir(parents=True, exist_ok=True)
184
+ temp = dest.with_name(dest.stem + ".partial.aiff")
185
+ sf.write(str(temp), np.clip(audio, -1.0, 1.0), rate, format="AIFF", subtype=subtype)
186
+ temp.replace(dest)
187
+ return PrepResult(source, dest, source_rate, rate, len(audio), reused=False, clipped=clipped,
188
+ gain_db=gain_db)
@@ -0,0 +1,64 @@
1
+ """Where each loop came from: the code in its name, TXXX tags, and a provenance.csv next to the loops.
2
+
3
+ `cut` writes all three for every loop that passes its checks; `loopcutter provenance` does the same for loops
4
+ cut before codes existed. The index is keyed on the code and rewritten in place, so it always lists each loop once.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import csv
10
+ import os
11
+ import re
12
+ import time
13
+ import unicodedata
14
+ from pathlib import Path
15
+
16
+ INDEX = "provenance.csv"
17
+ CODE_IN_NAME = re.compile(r"\[LC-[0-9a-f]{8}\](?=\.[A-Za-z0-9]+$)")
18
+ FIELDS = ["code", "file", "artist", "track", "label", "kind", "bars", "bpm", "stem", "key", "start_seconds",
19
+ "source_file", "manifest", "row", "cut_at"]
20
+
21
+
22
+ def source_text(spec, source_file) -> str:
23
+ """One line for the SOURCE tag: what, from where, at which point."""
24
+ who = " - ".join(p for p in (spec.artist, spec.track) if p) or Path(source_file).stem
25
+ if getattr(spec, "kind", "loop") == "oneshot":
26
+ span = "one-shot"
27
+ else:
28
+ span = f"{float(spec.bars):g} bars @ {float(spec.bpm):g} BPM"
29
+ stem = f", {spec.stem} stem" if spec.stem else ""
30
+ return f"{who} | {source_file} | from {spec.start_seconds:.6f} s, {span}{stem} | label {spec.label}"
31
+
32
+
33
+ def index_row(spec, code: str, path: Path, out_root: Path, source_file, manifest) -> dict[str, str]:
34
+ return {"code": code, "file": path.relative_to(out_root).as_posix(), "artist": spec.artist or "",
35
+ "track": spec.track or "", "label": spec.label, "kind": getattr(spec, "kind", "loop"),
36
+ "bars": f"{float(spec.bars):g}", "bpm": f"{float(spec.bpm):g}", "stem": spec.stem or "",
37
+ "key": spec.key or "", "start_seconds": f"{spec.start_seconds:.6f}", "source_file": str(source_file),
38
+ "manifest": Path(manifest).name, "row": str(spec.row_number),
39
+ "cut_at": time.strftime("%Y-%m-%dT%H:%M:%S")}
40
+
41
+
42
+ def update_index(out_root: Path, rows: list[dict[str, str]]) -> Path:
43
+ """Upsert rows by code into out_root/provenance.csv (written whole, then swapped in)."""
44
+ path = Path(out_root) / INDEX
45
+ current: dict[str, dict[str, str]] = {}
46
+ if path.exists():
47
+ with open(path, newline="") as f:
48
+ current = {r["code"]: r for r in csv.DictReader(f)}
49
+ def loop_key(file): # the same loop whatever its code (or lack of one) and spelling
50
+ return CODE_IN_NAME.sub("", unicodedata.normalize("NFC", file))
51
+
52
+ for row in rows:
53
+ key = loop_key(row["file"])
54
+ for code in [c for c, r in current.items() if c != row["code"] and loop_key(r["file"]) == key]:
55
+ del current[code] # indexed under a stale code; rows of deleted loops stay
56
+ current[row["code"]] = row
57
+ path.parent.mkdir(parents=True, exist_ok=True)
58
+ tmp = path.with_suffix(".partial.csv")
59
+ with open(tmp, "w", newline="") as f:
60
+ w = csv.DictWriter(f, fieldnames=FIELDS)
61
+ w.writeheader()
62
+ w.writerows(sorted(current.values(), key=lambda r: r["file"]))
63
+ os.replace(tmp, path)
64
+ return path
loopcutter/snap.py ADDED
@@ -0,0 +1,215 @@
1
+ """Snap starts onto the analysed grid, and turn DJ-app markers into manifest rows.
2
+
3
+ The DJ app says roughly where and which beat; the grid says exactly when. The
4
+ app's measured offset is removed first, every shift is reported, and shifts
5
+ beyond the limit are refused rather than applied. Rows come out resolved, so
6
+ `cut` never has to move a start.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import csv
12
+ import math
13
+ from dataclasses import dataclass, field, replace
14
+ from pathlib import Path
15
+ from typing import Callable
16
+
17
+ from .grid import GridError, local_grid, local_inliers, nominal_bpm
18
+ from .markers import parse_note
19
+ from .model import Grid, Marker, SnapResult, TrackRecord
20
+ from .trackdb import find_record
21
+
22
+ COMMON_BARS = (0.25, 0.5, 1, 2, 3, 4, 6, 8, 12, 16, 32)
23
+ BAR_TOLERANCE = 0.03
24
+ FILE_START_SLACK_S = 0.005
25
+ LOCAL_FIT = 0.9 # the share of nearby beats that must sit on the whole-track grid
26
+ LOCAL_MARGIN = 0.1 # how much better a local grid must fit to be used instead
27
+ MIN_WHOLE_FIT = 0.5 # below this the whole-track grid is no fallback
28
+ TEMPO_RANGE = (0.8, 1.25) # a local tempo outside this share of the track's is a half- or double-time misreading
29
+ MANIFEST_FIELDS = ["source", "track_id", "label", "artist", "track", "bars", "bpm", "start",
30
+ "snap", "variations", "stem", "key", "notes"]
31
+
32
+
33
+ class SnapError(ValueError):
34
+ """Raised when a start is further from the grid than the limit allows."""
35
+
36
+
37
+ @dataclass
38
+ class ImportResult:
39
+ rows: list[dict] = field(default_factory=list)
40
+ moves_ms: list[float] = field(default_factory=list)
41
+ problems: list[str] = field(default_factory=list)
42
+
43
+
44
+ def track_grid(record: TrackRecord) -> Grid:
45
+ """The track's grid at its fitted tempo (not the rounded one), unless you've overridden it."""
46
+ bpm = record.override_bpm or record.bpm_fitted or record.bpm
47
+ grid = Grid(period=60.0 / bpm, phase=record.phase, bar_phase=record.bar_phase,
48
+ beats_per_bar=record.beats_per_bar, inlier_ratio=record.inlier_ratio,
49
+ bar_agreement=record.bar_agreement, phase_agreement=record.phase_agreement)
50
+ return grid.shifted(record.override_phase_ms / 1000) if record.override_phase_ms else grid
51
+
52
+
53
+ def same_tempo(bpm: float, track_bpm: float) -> bool:
54
+ """Whether a local tempo is plausibly the track's own, not a half- or double-time reading."""
55
+ lo, hi = TEMPO_RANGE
56
+ return lo <= bpm / track_bpm <= hi
57
+
58
+
59
+ def grid_at(record: TrackRecord, t: float,
60
+ beats_for: Callable[[TrackRecord], tuple | None] | None = None) -> tuple[Grid, float]:
61
+ """The grid to snap against near time t, and the tempo a loop starting there has.
62
+
63
+ A track whose beats don't fit one steady grid (flagged grid-fit) gets a grid
64
+ fitted to the cached beats around t, moved onto the attack by the track's
65
+ measured offset and your override, as the whole-track grid was.
66
+ """
67
+ if not (record.override_bpm or record.bpm_fitted or record.bpm):
68
+ raise SnapError("not analysed yet - run `loopcutter scan`")
69
+ if beats_for is None or "grid-fit" not in record.flags.split(";") or record.override_bpm:
70
+ return track_grid(record), record.override_bpm or record.bpm
71
+ cached = beats_for(record)
72
+ if cached is None:
73
+ raise SnapError("its beats don't fit one steady grid and there is no beat cache - "
74
+ f"run `loopcutter scan --force \"{record.track_id}\"`")
75
+ whole = track_grid(record)
76
+ detected = replace(record, override_phase_ms=None) # the grid the raw beats were fitted to
77
+ detected = track_grid(detected).shifted(-record.phase_offset_ms / 1000)
78
+ whole_fit = local_inliers(detected, cached[0], t)
79
+ if whole_fit >= LOCAL_FIT:
80
+ # Flagged for a break or an intro elsewhere; here the whole-track grid, fitted to far
81
+ # more beats, still holds, and its tempo is the more accurate.
82
+ return whole, record.bpm
83
+ try:
84
+ grid = local_grid(*cached, t=t)
85
+ except GridError as exc:
86
+ if whole_fit > 0:
87
+ return whole, record.bpm
88
+ raise SnapError(str(exc)) from None
89
+ if not same_tempo(grid.bpm, record.bpm_fitted or record.bpm):
90
+ # The detector followed eighths or half-notes here. The whole-track grid is the better
91
+ # guess only if it still catches a fair share of these beats.
92
+ if whole_fit < MIN_WHOLE_FIT:
93
+ raise SnapError(f"the beats here read at {grid.bpm:.1f} BPM (half or double time) and "
94
+ f"don't fit the track's {record.bpm:g} BPM grid - set override_bpm or add "
95
+ "the row by hand")
96
+ return whole, record.bpm
97
+ if grid.inlier_ratio < whole_fit + LOCAL_MARGIN:
98
+ # Stray detections around the mark, not a tempo change: a grid fitted to them is
99
+ # no better, and its tempo is worse.
100
+ return whole, record.bpm
101
+ shift = (record.phase_offset_ms + (record.override_phase_ms or 0.0)) / 1000
102
+ return (grid.shifted(shift) if shift else grid), nominal_bpm(grid.bpm)
103
+
104
+
105
+ def snap_time(t: float, grid: Grid, mode: str = "beat", max_shift_ms: float = 60.0) -> SnapResult:
106
+ if mode == "off":
107
+ n = grid.beat_index(t)
108
+ return SnapResult(t, t, n, grid.is_bar_start(n))
109
+ target = grid.nearest_bar(t) if mode == "bar" else grid.nearest_beat(t)
110
+ n = grid.beat_index(target)
111
+ if target < 0:
112
+ # The first beat can sit a hair before the file because the grid leads the attack.
113
+ if target < -FILE_START_SLACK_S:
114
+ raise SnapError(f"{t:.3f}s snaps to {target:.3f}s, before the start of the file")
115
+ target = 0.0
116
+ result = SnapResult(t, target, n, grid.is_bar_start(n))
117
+ if abs(result.shift_ms) > max_shift_ms:
118
+ before = grid.beat_time(math.floor((t - grid.phase) / grid.period))
119
+ raise SnapError(f"{t:.3f}s is {result.shift_ms:+.0f} ms from the nearest {mode} "
120
+ f"(limit {max_shift_ms:.0f} ms); nearby beats {before:.3f}s and "
121
+ f"{before + grid.period:.3f}s, nearest bar {grid.nearest_bar(t):.3f}s")
122
+ return result
123
+
124
+
125
+ def bars_from_length(seconds: float, grid: Grid) -> float | None:
126
+ bars = seconds / (grid.period * grid.beats_per_bar)
127
+ best = min(COMMON_BARS, key=lambda b: abs(b - bars))
128
+ return best if abs(bars - best) <= BAR_TOLERANCE * best else None
129
+
130
+
131
+ def _fmt(value: float) -> str:
132
+ return str(int(value)) if float(value).is_integer() else f"{value:g}"
133
+
134
+
135
+ def _same_file(a, b) -> bool:
136
+ return Path(a).expanduser().resolve() == Path(b).expanduser().resolve()
137
+
138
+
139
+ def _app_correction(record: TrackRecord, marker: Marker) -> float:
140
+ """The app's measured offset, for marks on the file it was measured on (rekordbox reads
141
+ the master; Serato the source it tagged)."""
142
+ flags = set(record.flags.split(";"))
143
+ same_app = record.app and marker.app.startswith(record.app)
144
+ measured_on = record.master if record.app.startswith("rekordbox") else record.source
145
+ if (same_app and _same_file(marker.path, measured_on) and record.app_offset_ms is not None
146
+ and not flags & {"half-beat", "app-bpm"}):
147
+ return record.app_offset_ms / 1000
148
+ return 0.0
149
+
150
+
151
+ def markers_to_rows(markers: list[Marker], tracks: dict[str, TrackRecord], *,
152
+ default_bars: float = 4.0, max_shift_ms: float = 60.0,
153
+ beats_for: Callable[[TrackRecord], tuple | None] | None = None) -> ImportResult:
154
+ result = ImportResult()
155
+ counters: dict[str, int] = {}
156
+ for marker in markers:
157
+ record = find_record(tracks, marker.path)
158
+ if record is None:
159
+ result.problems.append(f"{marker.path.name}: not in tracks.csv - run `loopcutter prep` and `scan`")
160
+ continue
161
+ where = f"{marker.path.name} at {marker.start:.3f}s"
162
+ flags = set(record.flags.split(";"))
163
+ t = marker.start - _app_correction(record, marker)
164
+ try:
165
+ grid, bpm = grid_at(record, t, beats_for)
166
+ except SnapError as exc:
167
+ result.problems.append(f"{where}: {exc}")
168
+ continue
169
+ unsure = "phase" in flags and record.override_phase_ms is None
170
+ if unsure and marker.app.startswith("rekordbox") and _same_file(marker.path, record.master):
171
+ # rekordbox reads the master's own samples, so its quantised mark is the best phase we have
172
+ snap = SnapResult(marker.start, marker.start, grid.beat_index(marker.start), False)
173
+ elif unsure:
174
+ result.problems.append(f"{where}: this track's grid phase isn't confident - mark it in "
175
+ "rekordbox on the master with quantise on, or set override_phase_ms")
176
+ continue
177
+ else:
178
+ try:
179
+ snap = snap_time(t, grid, "beat", max_shift_ms)
180
+ except SnapError as exc:
181
+ result.problems.append(f"{where}: {exc}")
182
+ continue
183
+ bars = bars_from_length(marker.end - marker.start, grid) if marker.end else default_bars
184
+ if bars is None:
185
+ length = (marker.end - marker.start) / (grid.period * grid.beats_per_bar)
186
+ result.problems.append(f"{where}: the loop is {length:.2f} bars, not a standard "
187
+ "length - fix it in the app or add the row by hand")
188
+ continue
189
+ note = parse_note(marker.name)
190
+ counters[record.track_id] = counters.get(record.track_id, 0) + 1
191
+ artist, _, title = Path(record.master).stem.partition(" - ")
192
+ move_ms = (snap.snapped - marker.start) * 1000
193
+ result.rows.append({
194
+ "source": record.master, "track_id": record.track_id,
195
+ "label": note.label or f"M{counters[record.track_id]}",
196
+ "artist": artist if title else "", "track": title or artist,
197
+ "bars": _fmt(bars), "bpm": _fmt(bpm), "start": f"{snap.snapped:.6f}", "snap": "",
198
+ "variations": ",".join(_fmt(v) for v in note.variations if v != bars),
199
+ "stem": note.stem or "", "key": record.key,
200
+ "notes": f"{marker.app} mark at {marker.start:.3f}s, moved {move_ms:+.1f} ms"
201
+ + (" (kept: grid phase not confident)" if unsure else ""),
202
+ })
203
+ result.moves_ms.append(move_ms)
204
+ return result
205
+
206
+
207
+ def write_manifest(rows: list[dict], path) -> None:
208
+ path = Path(path)
209
+ if path.exists():
210
+ raise FileExistsError(f"{path} exists; choose another name")
211
+ path.parent.mkdir(parents=True, exist_ok=True)
212
+ with path.open("w", newline="", encoding="utf-8") as handle:
213
+ writer = csv.DictWriter(handle, fieldnames=MANIFEST_FIELDS, extrasaction="ignore")
214
+ writer.writeheader()
215
+ writer.writerows(rows)