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 +3 -0
- seamsplit/__main__.py +7 -0
- seamsplit/anchor.py +286 -0
- seamsplit/audio.py +486 -0
- seamsplit/audio_io.py +560 -0
- seamsplit/audition.py +320 -0
- seamsplit/backends.py +419 -0
- seamsplit/checks.py +151 -0
- seamsplit/choices.py +225 -0
- seamsplit/cli.py +711 -0
- seamsplit/cli_jobs.py +260 -0
- seamsplit/crossfade.py +570 -0
- seamsplit/cutpoints.py +388 -0
- seamsplit/dsp.py +282 -0
- seamsplit/gui.py +957 -0
- seamsplit/job.py +342 -0
- seamsplit/manifest.py +101 -0
- seamsplit/matching.py +210 -0
- seamsplit/merger.py +463 -0
- seamsplit/pairing.py +319 -0
- seamsplit/plan.py +175 -0
- seamsplit/py.typed +0 -0
- seamsplit/report.py +160 -0
- seamsplit/services.py +189 -0
- seamsplit/splitopts.py +277 -0
- seamsplit/splitter.py +597 -0
- seamsplit/static/audition.js +375 -0
- seamsplit/static/audition_page.html +100 -0
- seamsplit/static/index.html +684 -0
- seamsplit/status.py +214 -0
- seamsplit-1.2.0.dist-info/METADATA +155 -0
- seamsplit-1.2.0.dist-info/RECORD +36 -0
- seamsplit-1.2.0.dist-info/WHEEL +5 -0
- seamsplit-1.2.0.dist-info/entry_points.txt +2 -0
- seamsplit-1.2.0.dist-info/licenses/LICENSE +21 -0
- seamsplit-1.2.0.dist-info/top_level.txt +1 -0
seamsplit/__init__.py
ADDED
seamsplit/__main__.py
ADDED
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)
|