seamsplit 1.2.0__tar.gz
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-1.2.0/LICENSE +21 -0
- seamsplit-1.2.0/PKG-INFO +155 -0
- seamsplit-1.2.0/README.md +115 -0
- seamsplit-1.2.0/pyproject.toml +92 -0
- seamsplit-1.2.0/setup.cfg +11 -0
- seamsplit-1.2.0/src/seamsplit/__init__.py +3 -0
- seamsplit-1.2.0/src/seamsplit/__main__.py +7 -0
- seamsplit-1.2.0/src/seamsplit/anchor.py +286 -0
- seamsplit-1.2.0/src/seamsplit/audio.py +486 -0
- seamsplit-1.2.0/src/seamsplit/audio_io.py +560 -0
- seamsplit-1.2.0/src/seamsplit/audition.py +320 -0
- seamsplit-1.2.0/src/seamsplit/backends.py +419 -0
- seamsplit-1.2.0/src/seamsplit/checks.py +151 -0
- seamsplit-1.2.0/src/seamsplit/choices.py +225 -0
- seamsplit-1.2.0/src/seamsplit/cli.py +711 -0
- seamsplit-1.2.0/src/seamsplit/cli_jobs.py +260 -0
- seamsplit-1.2.0/src/seamsplit/crossfade.py +570 -0
- seamsplit-1.2.0/src/seamsplit/cutpoints.py +388 -0
- seamsplit-1.2.0/src/seamsplit/dsp.py +282 -0
- seamsplit-1.2.0/src/seamsplit/gui.py +957 -0
- seamsplit-1.2.0/src/seamsplit/job.py +342 -0
- seamsplit-1.2.0/src/seamsplit/manifest.py +101 -0
- seamsplit-1.2.0/src/seamsplit/matching.py +210 -0
- seamsplit-1.2.0/src/seamsplit/merger.py +463 -0
- seamsplit-1.2.0/src/seamsplit/pairing.py +319 -0
- seamsplit-1.2.0/src/seamsplit/plan.py +175 -0
- seamsplit-1.2.0/src/seamsplit/py.typed +0 -0
- seamsplit-1.2.0/src/seamsplit/report.py +160 -0
- seamsplit-1.2.0/src/seamsplit/services.py +189 -0
- seamsplit-1.2.0/src/seamsplit/splitopts.py +277 -0
- seamsplit-1.2.0/src/seamsplit/splitter.py +597 -0
- seamsplit-1.2.0/src/seamsplit/static/audition.js +375 -0
- seamsplit-1.2.0/src/seamsplit/static/audition_page.html +100 -0
- seamsplit-1.2.0/src/seamsplit/static/index.html +684 -0
- seamsplit-1.2.0/src/seamsplit/status.py +214 -0
- seamsplit-1.2.0/src/seamsplit.egg-info/PKG-INFO +155 -0
- seamsplit-1.2.0/src/seamsplit.egg-info/SOURCES.txt +65 -0
- seamsplit-1.2.0/src/seamsplit.egg-info/dependency_links.txt +1 -0
- seamsplit-1.2.0/src/seamsplit.egg-info/entry_points.txt +2 -0
- seamsplit-1.2.0/src/seamsplit.egg-info/requires.txt +14 -0
- seamsplit-1.2.0/src/seamsplit.egg-info/top_level.txt +1 -0
- seamsplit-1.2.0/tests/test_anchor.py +479 -0
- seamsplit-1.2.0/tests/test_audio.py +506 -0
- seamsplit-1.2.0/tests/test_audio_limits.py +412 -0
- seamsplit-1.2.0/tests/test_audio_vs_pydub.py +102 -0
- seamsplit-1.2.0/tests/test_audition.py +441 -0
- seamsplit-1.2.0/tests/test_backends.py +450 -0
- seamsplit-1.2.0/tests/test_bars.py +327 -0
- seamsplit-1.2.0/tests/test_benchmarks.py +382 -0
- seamsplit-1.2.0/tests/test_build_info.py +59 -0
- seamsplit-1.2.0/tests/test_choices.py +217 -0
- seamsplit-1.2.0/tests/test_cli_anchor.py +214 -0
- seamsplit-1.2.0/tests/test_cutpoints.py +391 -0
- seamsplit-1.2.0/tests/test_gui.py +911 -0
- seamsplit-1.2.0/tests/test_gui_anchor.py +294 -0
- seamsplit-1.2.0/tests/test_jobs.py +762 -0
- seamsplit-1.2.0/tests/test_merge_stages.py +108 -0
- seamsplit-1.2.0/tests/test_merger.py +1548 -0
- seamsplit-1.2.0/tests/test_module_layout.py +85 -0
- seamsplit-1.2.0/tests/test_pairing.py +515 -0
- seamsplit-1.2.0/tests/test_roundtrip.py +824 -0
- seamsplit-1.2.0/tests/test_services.py +245 -0
- seamsplit-1.2.0/tests/test_splitter.py +303 -0
- seamsplit-1.2.0/tests/test_status.py +253 -0
- seamsplit-1.2.0/tests/test_untrusted_input.py +328 -0
- seamsplit-1.2.0/tests/test_version.py +51 -0
seamsplit-1.2.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ndhn27
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
seamsplit-1.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: seamsplit
|
|
3
|
+
Version: 1.2.0
|
|
4
|
+
Summary: Split audio into overlapping chunks for AI stem separation, then merge them back with a crossfade.
|
|
5
|
+
Author: ndhn27
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/ndhn27/seamsplit
|
|
8
|
+
Project-URL: Documentation, https://github.com/ndhn27/seamsplit/tree/main/docs
|
|
9
|
+
Project-URL: Changelog, https://github.com/ndhn27/seamsplit/blob/main/CHANGELOG.md
|
|
10
|
+
Project-URL: Source, https://github.com/ndhn27/seamsplit
|
|
11
|
+
Project-URL: Issues, https://github.com/ndhn27/seamsplit/issues
|
|
12
|
+
Keywords: audio,crossfade,stem-separation,vocal-remover,pyav,ffmpeg
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Operating System :: OS Independent
|
|
22
|
+
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
|
|
23
|
+
Classifier: Environment :: Console
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.10
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
License-File: LICENSE
|
|
28
|
+
Requires-Dist: numpy>=1.24
|
|
29
|
+
Requires-Dist: av>=14.0
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pydub>=0.25.1; extra == "dev"
|
|
32
|
+
Requires-Dist: audioop-lts>=0.2.1; python_version >= "3.13" and extra == "dev"
|
|
33
|
+
Requires-Dist: playwright>=1.40; extra == "dev"
|
|
34
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
35
|
+
Requires-Dist: pytest-cov>=4.0; extra == "dev"
|
|
36
|
+
Requires-Dist: black<27,>=26; extra == "dev"
|
|
37
|
+
Requires-Dist: flake8>=7.0; extra == "dev"
|
|
38
|
+
Requires-Dist: mypy>=1.8; extra == "dev"
|
|
39
|
+
Dynamic: license-file
|
|
40
|
+
|
|
41
|
+
<div align="center">
|
|
42
|
+
|
|
43
|
+
# SeamSplit
|
|
44
|
+
|
|
45
|
+
**Split a long song into overlapping chunks for AI stem separators, then merge the results back with a real crossfade instead of a naive concatenation.**
|
|
46
|
+
|
|
47
|
+
[](https://github.com/ndhn27/seamsplit/actions/workflows/ci.yml)
|
|
48
|
+
[](LICENSE)
|
|
49
|
+
[](pyproject.toml)
|
|
50
|
+
[](https://github.com/psf/black)
|
|
51
|
+
|
|
52
|
+
Drag-and-drop page ยท Command line ยท Runs on your computer ยท No FFmpeg to install
|
|
53
|
+
|
|
54
|
+

|
|
55
|
+
|
|
56
|
+
</div>
|
|
57
|
+
|
|
58
|
+
## โก Quick start
|
|
59
|
+
|
|
60
|
+
Python 3.10 or newer. Audio is read and written inside the process by [PyAV](https://pyav.org/), whose wheels carry FFmpeg, so there is no `ffmpeg` to put on your `PATH`.
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
git clone https://github.com/ndhn27/seamsplit.git && cd seamsplit
|
|
64
|
+
pip install .
|
|
65
|
+
seamsplit gui # opens a page in your browser: drop a track, press Split
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Send the chunks to your AI separator, drop what it returns on the second card, press *Merge*. Prefer a terminal?
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
seamsplit split song.mp3 --limit 59 --out chunks/ # chunks + manifest.json
|
|
72
|
+
# run each chunk through your separator and save the results in processed/
|
|
73
|
+
seamsplit merge processed/ --manifest chunks/manifest.json --match instrumental --out song_instrumental_full.mp3
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
More: [Installation](docs/installation.md) ยท [One-file programs](docs/packaging.md) (no Python needed).
|
|
77
|
+
|
|
78
|
+
## ๐ก Why
|
|
79
|
+
|
|
80
|
+
Browser-based vocal/instrumental separators usually cap an upload at about a minute, so a full song goes through in pieces. Two things decide how the pieces sound once they are back together:
|
|
81
|
+
|
|
82
|
+
1. **Where you cut.** A cut at a single noisy minimum, rather than in a sustained quiet passage, leaves the model its least stable context on either side, so its output tends to diverge right at that edge.
|
|
83
|
+
2. **How you rejoin.** Gluing processed chunks together (`ffmpeg -f concat`) blends nothing: each chunk was processed on its own, so a small difference in level or phase at the boundary is an audible click.
|
|
84
|
+
|
|
85
|
+
`split` looks for cut points in a smoothed loudness curve, favouring sustained quiet passages, and gives every chunk an overlap into its neighbours. `merge` measures and cancels the timing offset between neighbouring chunks, matches their levels, crossfades across each overlap, and warns about any seam that looks wrong.
|
|
86
|
+
|
|
87
|
+
## ๐ How it works
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
song.mp3
|
|
91
|
+
โ
|
|
92
|
+
โผ seamsplit split
|
|
93
|
+
chunks/part01.flac, chunks/part02.flac, ... + chunks/manifest.json
|
|
94
|
+
โ
|
|
95
|
+
โผ run each chunk through your AI separator (keep the order; renaming is fine)
|
|
96
|
+
processed/part01_instrumental.mp3, processed/part02_instrumental.mp3, ...
|
|
97
|
+
โ
|
|
98
|
+
โผ seamsplit merge
|
|
99
|
+
song_instrumental_full.mp3
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Or keep everything in one folder that can be left and picked up again ([Jobs and local separation](docs/jobs-and-backends.md)):
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
seamsplit run song.mp3 --service xminus # split, then wait for the results
|
|
106
|
+
seamsplit status song.job # which chunks are still missing?
|
|
107
|
+
seamsplit run --job song.job # merge, once they are all there
|
|
108
|
+
|
|
109
|
+
seamsplit run song.mp3 --backend demucs # or separate on this computer: no limit, no upload
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## โจ Features
|
|
113
|
+
|
|
114
|
+
- **Smart cuts.** Quiet passages rather than a single noisy minimum; optionally judged by activity in the voice band and snapped to the beat or the bar. Chunks are sized to your service's limit, can be lossless (`flac`/`wav`), and there are presets for known services. โ [Splitting a track](docs/splitting.md)
|
|
115
|
+
- **A merge that blends.** Timing alignment, level matching, an adaptive crossfade, and a report that flags the seams worth a listen. โ [Merging the results](docs/merging.md), [How the merge works](docs/how-the-merge-works.md)
|
|
116
|
+
- **Files may come back renamed.** Paired by name, by order, and checked against the original chunks by sound. โ [Which file is which chunk](docs/merging.md#which-file-is-which-chunk)
|
|
117
|
+
- **Anchoring and a listening kit.** Compare every chunk with the original it was made from, merge both stems together, and listen to the seams on a blind listening page. โ [Anchoring and the listening kit](docs/anchoring-and-listening.md)
|
|
118
|
+
- **One folder per job.** `run` and `status` resume where you left off, and can separate locally with Demucs or audio-separator. โ [Jobs and local separation](docs/jobs-and-backends.md)
|
|
119
|
+
- **A drag-and-drop page** (English and Vietnamese) that serves only `127.0.0.1`. โ [Drag-and-drop interface](docs/gui.md)
|
|
120
|
+
|
|
121
|
+
### How much of this is measured
|
|
122
|
+
|
|
123
|
+
The [benchmark](benchmarks/README.md) separated real chunks with a real model and compared every way of joining them, and it supports less than the list above suggests. It is small: five short songs (10โ30 s), chunks of 8 s, one separation model. A real chunk is closer to 59 s, which it did not test.
|
|
124
|
+
|
|
125
|
+
- **Overlap is what helps:** 4.7 dB better at the seams than cutting without overlap.
|
|
126
|
+
- **The crossfade on top** adds under 1 dB at the median, and the 95 % interval of its mean gain includes 0 on every set of chunks. `linear` and the default `adaptive` score the same; `equalpower` is a median 16 dB *worse* than a hard cut (the page does not offer it).
|
|
127
|
+
- **No measurable gain** from `--seam-search`, `--anchor` or cutting by the voice band, on clean chunks. Quiet cuts do lower the click measure at the join, but not the error against the whole-song separation.
|
|
128
|
+
- **Not tested on real services:** timing alignment and level matching matter a lot against *simulated* damage (a shifted or re-leveled chunk), and nothing here shows that real services do that.
|
|
129
|
+
- **The model dominates:** the separator's own error against the true stems (about 11 dB) is far larger than anything the joining changes.
|
|
130
|
+
|
|
131
|
+
## ๐ Documentation
|
|
132
|
+
|
|
133
|
+
| Page | What is in it |
|
|
134
|
+
| --- | --- |
|
|
135
|
+
| [Drag-and-drop interface](docs/gui.md) | The browser page: split, merge, listen; where files go; how it is kept local |
|
|
136
|
+
| [Splitting a track](docs/splitting.md) | Every `split` option, choosing where to cut, lossless chunks, service presets |
|
|
137
|
+
| [Merging the results](docs/merging.md) | Pairing files with chunks, every `merge` option, the seam report |
|
|
138
|
+
| [How the merge works](docs/how-the-merge-works.md) | Timing alignment, level matching, crossfade curves, seam search |
|
|
139
|
+
| [Anchoring and the listening kit](docs/anchoring-and-listening.md) | Comparing with the original chunks, both stems, listening to the seams |
|
|
140
|
+
| [Jobs and local separation](docs/jobs-and-backends.md) | `run` and `status`, the job folder, Demucs and audio-separator backends |
|
|
141
|
+
| [Installation](docs/installation.md) | What gets installed, and why FFmpeg comes with it |
|
|
142
|
+
| [One-file programs](docs/packaging.md) | PyInstaller builds for Linux, Windows and macOS |
|
|
143
|
+
| [Development](docs/development.md) | Tests, linters, and a map of the modules |
|
|
144
|
+
| [Benchmarks](benchmarks/README.md) | Method and numbers, and what they do not show |
|
|
145
|
+
| [Contributing](CONTRIBUTING.md) ยท [Security](SECURITY.md) | How to help; how to report a problem privately |
|
|
146
|
+
|
|
147
|
+
## ๐ Benchmarks
|
|
148
|
+
|
|
149
|
+
Measured on five real songs separated by a real model (UVR MDX-Net, on the CPU). Against the same song separated in one go, the signal-to-error ratio at the seams rose from 21.2 dB with no overlap to 25.9 dB with 2 s of overlap; crossfading the overlap beat a hard cut at most seams (not all), by under a dB at the median. Local model, short clips, no listening test: the [benchmark README](benchmarks/README.md) says what the numbers do and do not show, and the results are in [`benchmarks/results/RESULTS.md`](benchmarks/results/RESULTS.md).
|
|
150
|
+
|
|
151
|
+
## ๐ License
|
|
152
|
+
|
|
153
|
+
[MIT](LICENSE) ยฉ 2026 ndhn27.
|
|
154
|
+
|
|
155
|
+
PyAV's FFmpeg is built with GPL-licensed libx264 and libx265. SeamSplit uses it only for audio, but a program that bundles those libraries has to follow their licences: see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# SeamSplit
|
|
4
|
+
|
|
5
|
+
**Split a long song into overlapping chunks for AI stem separators, then merge the results back with a real crossfade instead of a naive concatenation.**
|
|
6
|
+
|
|
7
|
+
[](https://github.com/ndhn27/seamsplit/actions/workflows/ci.yml)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
[](pyproject.toml)
|
|
10
|
+
[](https://github.com/psf/black)
|
|
11
|
+
|
|
12
|
+
Drag-and-drop page ยท Command line ยท Runs on your computer ยท No FFmpeg to install
|
|
13
|
+
|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
</div>
|
|
17
|
+
|
|
18
|
+
## โก Quick start
|
|
19
|
+
|
|
20
|
+
Python 3.10 or newer. Audio is read and written inside the process by [PyAV](https://pyav.org/), whose wheels carry FFmpeg, so there is no `ffmpeg` to put on your `PATH`.
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
git clone https://github.com/ndhn27/seamsplit.git && cd seamsplit
|
|
24
|
+
pip install .
|
|
25
|
+
seamsplit gui # opens a page in your browser: drop a track, press Split
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Send the chunks to your AI separator, drop what it returns on the second card, press *Merge*. Prefer a terminal?
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
seamsplit split song.mp3 --limit 59 --out chunks/ # chunks + manifest.json
|
|
32
|
+
# run each chunk through your separator and save the results in processed/
|
|
33
|
+
seamsplit merge processed/ --manifest chunks/manifest.json --match instrumental --out song_instrumental_full.mp3
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
More: [Installation](docs/installation.md) ยท [One-file programs](docs/packaging.md) (no Python needed).
|
|
37
|
+
|
|
38
|
+
## ๐ก Why
|
|
39
|
+
|
|
40
|
+
Browser-based vocal/instrumental separators usually cap an upload at about a minute, so a full song goes through in pieces. Two things decide how the pieces sound once they are back together:
|
|
41
|
+
|
|
42
|
+
1. **Where you cut.** A cut at a single noisy minimum, rather than in a sustained quiet passage, leaves the model its least stable context on either side, so its output tends to diverge right at that edge.
|
|
43
|
+
2. **How you rejoin.** Gluing processed chunks together (`ffmpeg -f concat`) blends nothing: each chunk was processed on its own, so a small difference in level or phase at the boundary is an audible click.
|
|
44
|
+
|
|
45
|
+
`split` looks for cut points in a smoothed loudness curve, favouring sustained quiet passages, and gives every chunk an overlap into its neighbours. `merge` measures and cancels the timing offset between neighbouring chunks, matches their levels, crossfades across each overlap, and warns about any seam that looks wrong.
|
|
46
|
+
|
|
47
|
+
## ๐ How it works
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
song.mp3
|
|
51
|
+
โ
|
|
52
|
+
โผ seamsplit split
|
|
53
|
+
chunks/part01.flac, chunks/part02.flac, ... + chunks/manifest.json
|
|
54
|
+
โ
|
|
55
|
+
โผ run each chunk through your AI separator (keep the order; renaming is fine)
|
|
56
|
+
processed/part01_instrumental.mp3, processed/part02_instrumental.mp3, ...
|
|
57
|
+
โ
|
|
58
|
+
โผ seamsplit merge
|
|
59
|
+
song_instrumental_full.mp3
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Or keep everything in one folder that can be left and picked up again ([Jobs and local separation](docs/jobs-and-backends.md)):
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
seamsplit run song.mp3 --service xminus # split, then wait for the results
|
|
66
|
+
seamsplit status song.job # which chunks are still missing?
|
|
67
|
+
seamsplit run --job song.job # merge, once they are all there
|
|
68
|
+
|
|
69
|
+
seamsplit run song.mp3 --backend demucs # or separate on this computer: no limit, no upload
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## โจ Features
|
|
73
|
+
|
|
74
|
+
- **Smart cuts.** Quiet passages rather than a single noisy minimum; optionally judged by activity in the voice band and snapped to the beat or the bar. Chunks are sized to your service's limit, can be lossless (`flac`/`wav`), and there are presets for known services. โ [Splitting a track](docs/splitting.md)
|
|
75
|
+
- **A merge that blends.** Timing alignment, level matching, an adaptive crossfade, and a report that flags the seams worth a listen. โ [Merging the results](docs/merging.md), [How the merge works](docs/how-the-merge-works.md)
|
|
76
|
+
- **Files may come back renamed.** Paired by name, by order, and checked against the original chunks by sound. โ [Which file is which chunk](docs/merging.md#which-file-is-which-chunk)
|
|
77
|
+
- **Anchoring and a listening kit.** Compare every chunk with the original it was made from, merge both stems together, and listen to the seams on a blind listening page. โ [Anchoring and the listening kit](docs/anchoring-and-listening.md)
|
|
78
|
+
- **One folder per job.** `run` and `status` resume where you left off, and can separate locally with Demucs or audio-separator. โ [Jobs and local separation](docs/jobs-and-backends.md)
|
|
79
|
+
- **A drag-and-drop page** (English and Vietnamese) that serves only `127.0.0.1`. โ [Drag-and-drop interface](docs/gui.md)
|
|
80
|
+
|
|
81
|
+
### How much of this is measured
|
|
82
|
+
|
|
83
|
+
The [benchmark](benchmarks/README.md) separated real chunks with a real model and compared every way of joining them, and it supports less than the list above suggests. It is small: five short songs (10โ30 s), chunks of 8 s, one separation model. A real chunk is closer to 59 s, which it did not test.
|
|
84
|
+
|
|
85
|
+
- **Overlap is what helps:** 4.7 dB better at the seams than cutting without overlap.
|
|
86
|
+
- **The crossfade on top** adds under 1 dB at the median, and the 95 % interval of its mean gain includes 0 on every set of chunks. `linear` and the default `adaptive` score the same; `equalpower` is a median 16 dB *worse* than a hard cut (the page does not offer it).
|
|
87
|
+
- **No measurable gain** from `--seam-search`, `--anchor` or cutting by the voice band, on clean chunks. Quiet cuts do lower the click measure at the join, but not the error against the whole-song separation.
|
|
88
|
+
- **Not tested on real services:** timing alignment and level matching matter a lot against *simulated* damage (a shifted or re-leveled chunk), and nothing here shows that real services do that.
|
|
89
|
+
- **The model dominates:** the separator's own error against the true stems (about 11 dB) is far larger than anything the joining changes.
|
|
90
|
+
|
|
91
|
+
## ๐ Documentation
|
|
92
|
+
|
|
93
|
+
| Page | What is in it |
|
|
94
|
+
| --- | --- |
|
|
95
|
+
| [Drag-and-drop interface](docs/gui.md) | The browser page: split, merge, listen; where files go; how it is kept local |
|
|
96
|
+
| [Splitting a track](docs/splitting.md) | Every `split` option, choosing where to cut, lossless chunks, service presets |
|
|
97
|
+
| [Merging the results](docs/merging.md) | Pairing files with chunks, every `merge` option, the seam report |
|
|
98
|
+
| [How the merge works](docs/how-the-merge-works.md) | Timing alignment, level matching, crossfade curves, seam search |
|
|
99
|
+
| [Anchoring and the listening kit](docs/anchoring-and-listening.md) | Comparing with the original chunks, both stems, listening to the seams |
|
|
100
|
+
| [Jobs and local separation](docs/jobs-and-backends.md) | `run` and `status`, the job folder, Demucs and audio-separator backends |
|
|
101
|
+
| [Installation](docs/installation.md) | What gets installed, and why FFmpeg comes with it |
|
|
102
|
+
| [One-file programs](docs/packaging.md) | PyInstaller builds for Linux, Windows and macOS |
|
|
103
|
+
| [Development](docs/development.md) | Tests, linters, and a map of the modules |
|
|
104
|
+
| [Benchmarks](benchmarks/README.md) | Method and numbers, and what they do not show |
|
|
105
|
+
| [Contributing](CONTRIBUTING.md) ยท [Security](SECURITY.md) | How to help; how to report a problem privately |
|
|
106
|
+
|
|
107
|
+
## ๐ Benchmarks
|
|
108
|
+
|
|
109
|
+
Measured on five real songs separated by a real model (UVR MDX-Net, on the CPU). Against the same song separated in one go, the signal-to-error ratio at the seams rose from 21.2 dB with no overlap to 25.9 dB with 2 s of overlap; crossfading the overlap beat a hard cut at most seams (not all), by under a dB at the median. Local model, short clips, no listening test: the [benchmark README](benchmarks/README.md) says what the numbers do and do not show, and the results are in [`benchmarks/results/RESULTS.md`](benchmarks/results/RESULTS.md).
|
|
110
|
+
|
|
111
|
+
## ๐ License
|
|
112
|
+
|
|
113
|
+
[MIT](LICENSE) ยฉ 2026 ndhn27.
|
|
114
|
+
|
|
115
|
+
PyAV's FFmpeg is built with GPL-licensed libx264 and libx265. SeamSplit uses it only for audio, but a program that bundles those libraries has to follow their licences: see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "seamsplit"
|
|
7
|
+
version = "1.2.0"
|
|
8
|
+
description = "Split audio into overlapping chunks for AI stem separation, then merge them back with a crossfade."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "ndhn27" }
|
|
15
|
+
]
|
|
16
|
+
keywords = ["audio", "crossfade", "stem-separation", "vocal-remover", "pyav", "ffmpeg"]
|
|
17
|
+
classifiers = [
|
|
18
|
+
"Development Status :: 5 - Production/Stable",
|
|
19
|
+
"Intended Audience :: End Users/Desktop",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.10",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Programming Language :: Python :: 3.13",
|
|
25
|
+
"Programming Language :: Python :: 3.14",
|
|
26
|
+
"Operating System :: OS Independent",
|
|
27
|
+
"Topic :: Multimedia :: Sound/Audio :: Analysis",
|
|
28
|
+
"Environment :: Console",
|
|
29
|
+
"Typing :: Typed",
|
|
30
|
+
]
|
|
31
|
+
dependencies = [
|
|
32
|
+
"numpy>=1.24",
|
|
33
|
+
"av>=14.0", # PyAV: its wheels carry FFmpeg, so there is nothing else to install
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
[project.optional-dependencies]
|
|
37
|
+
dev = [
|
|
38
|
+
# pydub (and audioop on Python 3.13+) only for tests/test_audio_vs_pydub.py, which
|
|
39
|
+
# compares seamsplit.audio with pydub; the test skips without them
|
|
40
|
+
"pydub>=0.25.1",
|
|
41
|
+
"audioop-lts>=0.2.1; python_version>='3.13'",
|
|
42
|
+
# drives a real browser in tests/test_audition.py (the listening page); the test skips
|
|
43
|
+
# without it and, run by CI, fails: see _browser() there
|
|
44
|
+
"playwright>=1.40",
|
|
45
|
+
"pytest>=7.0",
|
|
46
|
+
"pytest-cov>=4.0",
|
|
47
|
+
"black>=26,<27", # same major as .pre-commit-config.yaml: its style only changes yearly
|
|
48
|
+
"flake8>=7.0",
|
|
49
|
+
"mypy>=1.8",
|
|
50
|
+
]
|
|
51
|
+
|
|
52
|
+
[project.urls]
|
|
53
|
+
Homepage = "https://github.com/ndhn27/seamsplit"
|
|
54
|
+
Documentation = "https://github.com/ndhn27/seamsplit/tree/main/docs"
|
|
55
|
+
Changelog = "https://github.com/ndhn27/seamsplit/blob/main/CHANGELOG.md"
|
|
56
|
+
Source = "https://github.com/ndhn27/seamsplit"
|
|
57
|
+
Issues = "https://github.com/ndhn27/seamsplit/issues"
|
|
58
|
+
|
|
59
|
+
[project.scripts]
|
|
60
|
+
seamsplit = "seamsplit.cli:main"
|
|
61
|
+
|
|
62
|
+
[tool.setuptools.packages.find]
|
|
63
|
+
where = ["src"]
|
|
64
|
+
|
|
65
|
+
[tool.setuptools.package-data]
|
|
66
|
+
seamsplit = ["py.typed", "static/*.html", "static/*.js"]
|
|
67
|
+
|
|
68
|
+
[tool.black]
|
|
69
|
+
line-length = 100
|
|
70
|
+
target-version = ["py310"]
|
|
71
|
+
|
|
72
|
+
[tool.pytest.ini_options]
|
|
73
|
+
testpaths = ["tests"]
|
|
74
|
+
|
|
75
|
+
[tool.coverage.run]
|
|
76
|
+
source = ["seamsplit"]
|
|
77
|
+
|
|
78
|
+
[tool.coverage.report]
|
|
79
|
+
show_missing = true
|
|
80
|
+
exclude_lines = ["pragma: no cover", "if __name__ == .__main__.:"]
|
|
81
|
+
|
|
82
|
+
[tool.mypy]
|
|
83
|
+
files = ["src"]
|
|
84
|
+
check_untyped_defs = true
|
|
85
|
+
warn_unused_ignores = true
|
|
86
|
+
warn_redundant_casts = true
|
|
87
|
+
|
|
88
|
+
[[tool.mypy.overrides]]
|
|
89
|
+
module = ["av", "av.*"]
|
|
90
|
+
ignore_missing_imports = true
|
|
91
|
+
# newer PyAV ships type information, older does not; the code must check the same either way
|
|
92
|
+
follow_imports = "skip"
|