seamsplit 1.2.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.
seamsplit/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """SeamSplit — split audio for AI stem separation, merge back with crossfade."""
2
+
3
+ __version__ = "1.2.0"
seamsplit/__main__.py ADDED
@@ -0,0 +1,7 @@
1
+ """``python -m seamsplit ...`` is the same as the ``seamsplit`` command."""
2
+
3
+ import sys
4
+
5
+ from .cli import main
6
+
7
+ sys.exit(main())
seamsplit/anchor.py ADDED
@@ -0,0 +1,286 @@
1
+ """
2
+ Merging against the original chunks, and merging both stems of a service as one.
3
+
4
+ **Why.** Without it, ``merge`` only ever compares a chunk with its neighbour, in the few
5
+ seconds they share. That is a *relative* measurement: what one chunk is corrected by
6
+ depends on the one before it, so a small bias at every seam (a separator that gives a
7
+ chunk a little less level near its edges, say) adds up along the track, and where the
8
+ overlaps do not correspond (a vocals stem that is silent in the overlap) there is nothing
9
+ to measure at all. But the original chunks are on this computer: they are what was sent
10
+ to the service. Comparing each processed chunk with *its own original* gives an
11
+ **absolute** reference for where it belongs in time and, if the service gives back both
12
+ stems, for how loud it should be, because the two stems add up to (about) the original::
13
+
14
+ vocals + instrumental ~ original chunk
15
+
16
+ *Time.* The offset of ``processed`` against ``original`` is measured with the same
17
+ cross-correlation as between neighbours, and cancelled (zeros are put in front of a
18
+ chunk whose start was trimmed, and the silence a service put in front of one is
19
+ dropped). Every chunk then sits where the manifest says it was cut, however its
20
+ neighbours came out, and the first chunk is aligned too.
21
+
22
+ *Level.* One gain per chunk, the least-squares amplitude at which the sum of the stems
23
+ reproduces the original, applied to **both** stems so their balance is untouched. It
24
+ cannot be taken from one stem: an instrumental alone is quieter than the mix it came
25
+ from by exactly what the voice carried, so matching it to the original would make it
26
+ too loud. With one stem only the timing is anchored, and the level is left to the
27
+ neighbour matching. The correction is skipped (and said so) for a chunk whose
28
+ stems do not add up to the original (correlation below ``ANCHOR_GAIN_MIN_CORRELATION``)
29
+ or that would need more than ``ANCHOR_MAX_GAIN_DB``, where it would be a guess.
30
+
31
+ *Quality.* What is left of the original after the best offset and gain, ``recon_db``,
32
+ is how well the stems account for it. It is a consistency check, **not** a separation
33
+ score: a separator can reproduce the mix perfectly and still leave the voice in the
34
+ instrumental, and one that is not meant to conserve energy can separate well and reproduce
35
+ it badly. What it does catch is a chunk where the service did something to the audio
36
+ that is neither of the two (a different normalization of each stem, a dropout, a
37
+ different take of the material), so that chunk is the first to listen to. The 15 dB
38
+ default threshold is a heuristic, like ``--seam-warn-db``: look at your service's
39
+ typical value first.
40
+
41
+ *Both stems, one set of decisions.* Merged one at a time, the two stems would each get
42
+ their own offsets, gains and fade positions from their own overlaps, and what they
43
+ measure differs (a stem that is silent for a while measures nothing there). The stems
44
+ are therefore merged **together**: the two are stacked as the channels of one
45
+ multi-channel signal for :func:`seamsplit.crossfade._crossfade_merge`, which measures
46
+ on the average of all channels (the sum of the stems, i.e. the music) and applies
47
+ what it finds to all of them. Both outputs then have the same timing, the same gains
48
+ and the same fades, and add up to the same thing the original did.
49
+ """
50
+
51
+ from __future__ import annotations
52
+
53
+ import math
54
+ import os
55
+ from dataclasses import dataclass
56
+ from typing import List, Optional, Sequence, Tuple
57
+
58
+ import numpy as np
59
+ from .audio import AudioSegment
60
+
61
+ from .dsp import (
62
+ _DTYPES,
63
+ LEVEL_DEADBAND_DB,
64
+ MIN_ALIGN_CORRELATION,
65
+ _to_int_array,
66
+ anchor_fit,
67
+ )
68
+ from .report import ChunkInfo, MergeReport, _emit
69
+
70
+ # Seconds from the middle of a chunk used to find its offset (see ``anchor_fit``).
71
+ ANCHOR_LAG_WINDOW_S = 20.0
72
+
73
+ # The level of a chunk is taken from the original only when its stems add up to the
74
+ # original at least this well (normalized correlation of the sum with the original).
75
+ ANCHOR_GAIN_MIN_CORRELATION = 0.9
76
+
77
+ # The largest level correction taken from the original, dB in either direction. Larger
78
+ # than ``--max-gain-db``, which limits the *difference between neighbours*: a service
79
+ # that normalizes every chunk to a peak can be far from the original, and the same
80
+ # distance from it at every chunk is exactly what this puts right.
81
+ ANCHOR_MAX_GAIN_DB = 24.0
82
+
83
+ # A chunk whose stems add up to the original less well than this (dB) is flagged. An
84
+ # unvalidated heuristic: it only flags, it never changes audio.
85
+ DEFAULT_RECON_WARN_DB = 15.0
86
+
87
+
88
+ @dataclass
89
+ class AnchorOptions:
90
+ """What :func:`prepare_chunk` is to do. ``max_lag_ms`` 0 leaves the timing alone
91
+ (``--no-align``); ``level`` False leaves the level alone (``--no-match-level``)."""
92
+
93
+ max_lag_ms: float = 50.0
94
+ level: bool = True
95
+ recon_warn_db: Optional[float] = DEFAULT_RECON_WARN_DB
96
+
97
+
98
+ def other_output_path(output_path: str, other_match: str) -> str:
99
+ """Where the second stem goes when none was named: next to ``output_path``, with
100
+ the word that identified it added (``song.mp3`` + ``vocals`` -> ``song_vocals.mp3``)."""
101
+ word = "".join(c if c.isalnum() or c in "-." else "_" for c in other_match.strip())
102
+ word = word.strip("._-") or "other"
103
+ root, ext = os.path.splitext(output_path)
104
+ return f"{root}_{word}{ext}"
105
+
106
+
107
+ def _frames(seg: AudioSegment) -> np.ndarray:
108
+ """The samples of ``seg`` as float64, one row per frame."""
109
+ return _to_int_array(seg).astype(np.float64).reshape(-1, seg.channels)
110
+
111
+
112
+ def _conform(seg: AudioSegment, like: AudioSegment) -> AudioSegment:
113
+ """``seg`` in the format of ``like`` (levels compared across different sample
114
+ widths would not mean anything)."""
115
+ if seg.sample_width != like.sample_width:
116
+ seg = seg.set_sample_width(like.sample_width)
117
+ if seg.frame_rate != like.frame_rate:
118
+ seg = seg.set_frame_rate(like.frame_rate)
119
+ if seg.channels != like.channels:
120
+ seg = seg.set_channels(like.channels)
121
+ return seg
122
+
123
+
124
+ def _pad_rows(x: np.ndarray, rows: int) -> np.ndarray:
125
+ return x if len(x) >= rows else np.concatenate([x, np.zeros((rows - len(x), x.shape[1]))])
126
+
127
+
128
+ def _shift(x: np.ndarray, lag: int) -> np.ndarray:
129
+ """Cancel an offset: ``x[k] ~ original[k + lag]`` becomes ``out[k] ~ original[k]``,
130
+ by putting ``lag`` frames of silence in front (the service trimmed the start) or
131
+ dropping ``-lag`` of them (it put silence there)."""
132
+ if lag > 0:
133
+ return np.concatenate([np.zeros((lag, x.shape[1])), x])
134
+ if lag < 0:
135
+ return x[-lag:]
136
+ return x
137
+
138
+
139
+ def _pack(blocks: Sequence[np.ndarray], like: AudioSegment) -> Tuple[AudioSegment, int]:
140
+ """The blocks side by side as the channels of one segment in the sample type of
141
+ ``like``, and how many samples did not fit and were clipped."""
142
+ dtype = np.dtype(_DTYPES.get(like.array_type, np.int16))
143
+ lo, hi = float(np.iinfo(dtype).min), float(np.iinfo(dtype).max)
144
+ joined = np.hstack(blocks) if len(blocks) > 1 else blocks[0]
145
+ clipped = int(np.count_nonzero((joined > hi + 0.5) | (joined < lo - 0.5)))
146
+ data = np.clip(np.rint(joined), lo, hi).astype(dtype).tobytes()
147
+ seg = AudioSegment(
148
+ data=data,
149
+ sample_width=like.sample_width,
150
+ frame_rate=like.frame_rate,
151
+ channels=joined.shape[1],
152
+ )
153
+ return seg, clipped
154
+
155
+
156
+ def split_stems(merged: AudioSegment, channels: int) -> Tuple[AudioSegment, AudioSegment]:
157
+ """Undo the stacking: the first ``channels`` channels of ``merged`` are the main
158
+ stem, the rest the other one."""
159
+ dtype = np.dtype(_DTYPES.get(merged.array_type, np.int16))
160
+ rows = np.frombuffer(merged.raw_data, dtype=dtype).reshape(-1, merged.channels)
161
+ parts = []
162
+ for block in (rows[:, :channels], rows[:, channels:]):
163
+ parts.append(
164
+ AudioSegment(
165
+ data=np.ascontiguousarray(block).tobytes(),
166
+ sample_width=merged.sample_width,
167
+ frame_rate=merged.frame_rate,
168
+ channels=channels,
169
+ )
170
+ )
171
+ return parts[0], parts[1]
172
+
173
+
174
+ def _anchor(
175
+ part: int,
176
+ blocks: List[np.ndarray],
177
+ original: np.ndarray,
178
+ sr: int,
179
+ both: bool,
180
+ options: AnchorOptions,
181
+ report: Optional[MergeReport],
182
+ ) -> Tuple[List[np.ndarray], ChunkInfo]:
183
+ """Cancel the offset of the processed chunk (whose stems are ``blocks``) against
184
+ ``original`` and, with both stems, bring it to the original's level."""
185
+ info = ChunkInfo(part)
186
+ reply = np.sum(blocks, axis=0).mean(axis=1) # the stems added up, as mono
187
+ max_lag = int(round(options.max_lag_ms / 1000.0 * sr))
188
+ fit = anchor_fit(original.mean(axis=1), reply, max_lag, window=int(ANCHOR_LAG_WINDOW_S * sr))
189
+ info.correlation = fit.correlation
190
+ if not np.any(reply) or not np.any(original):
191
+ return blocks, info # silence: nothing to measure
192
+
193
+ if fit.correlation < MIN_ALIGN_CORRELATION:
194
+ _emit(
195
+ report,
196
+ f"part {part}: the processed chunk barely correlates with the original "
197
+ f"({fit.correlation:.2f}), so it was not anchored to it",
198
+ )
199
+ return blocks, info
200
+
201
+ if max_lag > 0:
202
+ if abs(fit.lag) >= max_lag:
203
+ _emit(
204
+ report,
205
+ f"part {part}: offset to the original reached the search limit "
206
+ f"({1000.0 * fit.lag / sr:+.1f} ms); try a larger --max-lag-ms",
207
+ )
208
+ info.lag_ms = 1000.0 * fit.lag / sr
209
+ blocks = [_shift(b, fit.lag) for b in blocks]
210
+
211
+ if not both:
212
+ return blocks, info # one stem says nothing about the level of the mix
213
+
214
+ info.recon_db = fit.recon_db
215
+ if options.recon_warn_db is not None and fit.recon_db < options.recon_warn_db:
216
+ info.flagged = True
217
+ _emit(
218
+ report,
219
+ f"part {part}: the stems add up to the original only to {fit.recon_db:.1f} dB "
220
+ f"(threshold {options.recon_warn_db:g} dB) — worth a listen",
221
+ )
222
+ if not options.level:
223
+ return blocks, info
224
+
225
+ gain_db = 20.0 * math.log10(fit.gain) if fit.gain > 0 else math.inf
226
+ reason = None
227
+ if fit.correlation < ANCHOR_GAIN_MIN_CORRELATION:
228
+ reason = f"the stems do not add up to it (correlation {fit.correlation:.2f})"
229
+ elif abs(gain_db) > ANCHOR_MAX_GAIN_DB:
230
+ reason = f"it would take {gain_db:+.1f} dB (limit {ANCHOR_MAX_GAIN_DB:g} dB)"
231
+ if reason is not None:
232
+ info.flagged = True
233
+ _emit(report, f"part {part}: the level was not taken from the original: {reason}")
234
+ return blocks, info
235
+
236
+ info.gain_db = 0.0
237
+ if abs(gain_db) >= LEVEL_DEADBAND_DB:
238
+ info.gain_db = gain_db
239
+ blocks = [b * fit.gain for b in blocks]
240
+ return blocks, info
241
+
242
+
243
+ def prepare_chunk(
244
+ part: int,
245
+ main: AudioSegment,
246
+ other: Optional[AudioSegment],
247
+ original: Optional[AudioSegment],
248
+ options: AnchorOptions,
249
+ report: Optional[MergeReport] = None,
250
+ length_tolerance_ms: float = 60.0,
251
+ extra_db: float = 0.0,
252
+ ) -> Tuple[AudioSegment, int]:
253
+ """One chunk made ready for the merge: ``main`` (the stem being merged), with the
254
+ ``other`` stem stacked behind it as more channels when there is one, both shifted
255
+ and scaled to ``original`` when that is given (see the module docstring), and
256
+ ``extra_db`` more on top of that. ``part`` is 1-based and names the chunk in
257
+ warnings; what was found is added to ``report.chunks``. Returns the chunk and how
258
+ many of its samples had to be clipped (a chunk brought to the level of an original
259
+ that peaks at full scale can go a few samples over)."""
260
+ blocks = [_frames(main)]
261
+ if other is not None:
262
+ other = _conform(other, main)
263
+ difference_ms = 1000.0 * abs(len(other.raw_data) - len(main.raw_data))
264
+ difference_ms /= main.frame_width * main.frame_rate
265
+ if difference_ms > length_tolerance_ms:
266
+ _emit(
267
+ report,
268
+ f"part {part}: the two stems differ in length by {difference_ms:.0f} ms; "
269
+ "the shorter one was padded with silence",
270
+ )
271
+ blocks.append(_frames(other))
272
+ rows = max(len(b) for b in blocks)
273
+ blocks = [_pad_rows(b, rows) for b in blocks]
274
+
275
+ if original is not None:
276
+ orig = _frames(_conform(original, main))
277
+ blocks, info = _anchor(
278
+ part, blocks, orig, main.frame_rate, other is not None, options, report
279
+ )
280
+ if report is not None:
281
+ report.chunks.append(info)
282
+ if extra_db:
283
+ blocks = [b * 10.0 ** (extra_db / 20.0) for b in blocks]
284
+ if original is None and other is None and not extra_db:
285
+ return main, 0
286
+ return _pack(blocks, main)