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.
Files changed (66) hide show
  1. seamsplit-1.2.0/LICENSE +21 -0
  2. seamsplit-1.2.0/PKG-INFO +155 -0
  3. seamsplit-1.2.0/README.md +115 -0
  4. seamsplit-1.2.0/pyproject.toml +92 -0
  5. seamsplit-1.2.0/setup.cfg +11 -0
  6. seamsplit-1.2.0/src/seamsplit/__init__.py +3 -0
  7. seamsplit-1.2.0/src/seamsplit/__main__.py +7 -0
  8. seamsplit-1.2.0/src/seamsplit/anchor.py +286 -0
  9. seamsplit-1.2.0/src/seamsplit/audio.py +486 -0
  10. seamsplit-1.2.0/src/seamsplit/audio_io.py +560 -0
  11. seamsplit-1.2.0/src/seamsplit/audition.py +320 -0
  12. seamsplit-1.2.0/src/seamsplit/backends.py +419 -0
  13. seamsplit-1.2.0/src/seamsplit/checks.py +151 -0
  14. seamsplit-1.2.0/src/seamsplit/choices.py +225 -0
  15. seamsplit-1.2.0/src/seamsplit/cli.py +711 -0
  16. seamsplit-1.2.0/src/seamsplit/cli_jobs.py +260 -0
  17. seamsplit-1.2.0/src/seamsplit/crossfade.py +570 -0
  18. seamsplit-1.2.0/src/seamsplit/cutpoints.py +388 -0
  19. seamsplit-1.2.0/src/seamsplit/dsp.py +282 -0
  20. seamsplit-1.2.0/src/seamsplit/gui.py +957 -0
  21. seamsplit-1.2.0/src/seamsplit/job.py +342 -0
  22. seamsplit-1.2.0/src/seamsplit/manifest.py +101 -0
  23. seamsplit-1.2.0/src/seamsplit/matching.py +210 -0
  24. seamsplit-1.2.0/src/seamsplit/merger.py +463 -0
  25. seamsplit-1.2.0/src/seamsplit/pairing.py +319 -0
  26. seamsplit-1.2.0/src/seamsplit/plan.py +175 -0
  27. seamsplit-1.2.0/src/seamsplit/py.typed +0 -0
  28. seamsplit-1.2.0/src/seamsplit/report.py +160 -0
  29. seamsplit-1.2.0/src/seamsplit/services.py +189 -0
  30. seamsplit-1.2.0/src/seamsplit/splitopts.py +277 -0
  31. seamsplit-1.2.0/src/seamsplit/splitter.py +597 -0
  32. seamsplit-1.2.0/src/seamsplit/static/audition.js +375 -0
  33. seamsplit-1.2.0/src/seamsplit/static/audition_page.html +100 -0
  34. seamsplit-1.2.0/src/seamsplit/static/index.html +684 -0
  35. seamsplit-1.2.0/src/seamsplit/status.py +214 -0
  36. seamsplit-1.2.0/src/seamsplit.egg-info/PKG-INFO +155 -0
  37. seamsplit-1.2.0/src/seamsplit.egg-info/SOURCES.txt +65 -0
  38. seamsplit-1.2.0/src/seamsplit.egg-info/dependency_links.txt +1 -0
  39. seamsplit-1.2.0/src/seamsplit.egg-info/entry_points.txt +2 -0
  40. seamsplit-1.2.0/src/seamsplit.egg-info/requires.txt +14 -0
  41. seamsplit-1.2.0/src/seamsplit.egg-info/top_level.txt +1 -0
  42. seamsplit-1.2.0/tests/test_anchor.py +479 -0
  43. seamsplit-1.2.0/tests/test_audio.py +506 -0
  44. seamsplit-1.2.0/tests/test_audio_limits.py +412 -0
  45. seamsplit-1.2.0/tests/test_audio_vs_pydub.py +102 -0
  46. seamsplit-1.2.0/tests/test_audition.py +441 -0
  47. seamsplit-1.2.0/tests/test_backends.py +450 -0
  48. seamsplit-1.2.0/tests/test_bars.py +327 -0
  49. seamsplit-1.2.0/tests/test_benchmarks.py +382 -0
  50. seamsplit-1.2.0/tests/test_build_info.py +59 -0
  51. seamsplit-1.2.0/tests/test_choices.py +217 -0
  52. seamsplit-1.2.0/tests/test_cli_anchor.py +214 -0
  53. seamsplit-1.2.0/tests/test_cutpoints.py +391 -0
  54. seamsplit-1.2.0/tests/test_gui.py +911 -0
  55. seamsplit-1.2.0/tests/test_gui_anchor.py +294 -0
  56. seamsplit-1.2.0/tests/test_jobs.py +762 -0
  57. seamsplit-1.2.0/tests/test_merge_stages.py +108 -0
  58. seamsplit-1.2.0/tests/test_merger.py +1548 -0
  59. seamsplit-1.2.0/tests/test_module_layout.py +85 -0
  60. seamsplit-1.2.0/tests/test_pairing.py +515 -0
  61. seamsplit-1.2.0/tests/test_roundtrip.py +824 -0
  62. seamsplit-1.2.0/tests/test_services.py +245 -0
  63. seamsplit-1.2.0/tests/test_splitter.py +303 -0
  64. seamsplit-1.2.0/tests/test_status.py +253 -0
  65. seamsplit-1.2.0/tests/test_untrusted_input.py +328 -0
  66. seamsplit-1.2.0/tests/test_version.py +51 -0
@@ -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.
@@ -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
+ [![CI](https://github.com/ndhn27/seamsplit/actions/workflows/ci.yml/badge.svg)](https://github.com/ndhn27/seamsplit/actions/workflows/ci.yml)
48
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
49
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](pyproject.toml)
50
+ [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
51
+
52
+ Drag-and-drop page ยท Command line ยท Runs on your computer ยท No FFmpeg to install
53
+
54
+ ![SeamSplit's drag-and-drop page after splitting a 48 s demo track into five overlapping chunks](docs/images/gui.png)
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
+ [![CI](https://github.com/ndhn27/seamsplit/actions/workflows/ci.yml/badge.svg)](https://github.com/ndhn27/seamsplit/actions/workflows/ci.yml)
8
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
9
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](pyproject.toml)
10
+ [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
11
+
12
+ Drag-and-drop page ยท Command line ยท Runs on your computer ยท No FFmpeg to install
13
+
14
+ ![SeamSplit's drag-and-drop page after splitting a 48 s demo track into five overlapping chunks](docs/images/gui.png)
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"
@@ -0,0 +1,11 @@
1
+ [flake8]
2
+ max-line-length = 100
3
+ extend-ignore = E203, W503
4
+ exclude = .git,__pycache__,build,dist,*.egg-info,.venv,venv
5
+ per-file-ignores =
6
+ benchmarks/bench/report.py: E501
7
+
8
+ [egg_info]
9
+ tag_build =
10
+ tag_date = 0
11
+
@@ -0,0 +1,3 @@
1
+ """SeamSplit โ€” split audio for AI stem separation, merge back with crossfade."""
2
+
3
+ __version__ = "1.2.0"
@@ -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())