jamly-audio-sep 0.1.1__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.
- jamly_audio_sep-0.1.1/DESIGN.md +170 -0
- jamly_audio_sep-0.1.1/LICENSE.md +21 -0
- jamly_audio_sep-0.1.1/MANIFEST.in +3 -0
- jamly_audio_sep-0.1.1/PKG-INFO +279 -0
- jamly_audio_sep-0.1.1/README.md +248 -0
- jamly_audio_sep-0.1.1/browser/extension/jamly_client.js +72 -0
- jamly_audio_sep-0.1.1/browser/extension/jamly_extension_bg.js +43 -0
- jamly_audio_sep-0.1.1/browser/extension/jamly_options.html +27 -0
- jamly_audio_sep-0.1.1/browser/extension/jamly_options.js +29 -0
- jamly_audio_sep-0.1.1/browser/extension/jamly_popup.html +37 -0
- jamly_audio_sep-0.1.1/browser/extension/jamly_popup.js +197 -0
- jamly_audio_sep-0.1.1/browser/extension/manifest.json +29 -0
- jamly_audio_sep-0.1.1/browser/userscripts/jamly.user.js +90 -0
- jamly_audio_sep-0.1.1/pyproject.toml +82 -0
- jamly_audio_sep-0.1.1/setup.cfg +4 -0
- jamly_audio_sep-0.1.1/src/jamly/__init__.py +3 -0
- jamly_audio_sep-0.1.1/src/jamly/audio.py +140 -0
- jamly_audio_sep-0.1.1/src/jamly/bootstrap.py +167 -0
- jamly_audio_sep-0.1.1/src/jamly/companion.py +219 -0
- jamly_audio_sep-0.1.1/src/jamly/companion_ui.py +133 -0
- jamly_audio_sep-0.1.1/src/jamly/config.py +224 -0
- jamly_audio_sep-0.1.1/src/jamly/core.py +240 -0
- jamly_audio_sep-0.1.1/src/jamly/demucs_worker.py +64 -0
- jamly_audio_sep-0.1.1/src/jamly/logging.py +95 -0
- jamly_audio_sep-0.1.1/src/jamly/models.py +112 -0
- jamly_audio_sep-0.1.1/src/jamly/naming.py +70 -0
- jamly_audio_sep-0.1.1/src/jamly/normalize.py +125 -0
- jamly_audio_sep-0.1.1/src/jamly/outputs.py +159 -0
- jamly_audio_sep-0.1.1/src/jamly/run.py +400 -0
- jamly_audio_sep-0.1.1/src/jamly/runtime.py +49 -0
- jamly_audio_sep-0.1.1/src/jamly/server.py +777 -0
- jamly_audio_sep-0.1.1/src/jamly/service.py +197 -0
- jamly_audio_sep-0.1.1/src/jamly/watch_queue.py +240 -0
- jamly_audio_sep-0.1.1/src/jamly/web/app.css +42 -0
- jamly_audio_sep-0.1.1/src/jamly/web/app.js +323 -0
- jamly_audio_sep-0.1.1/src/jamly/web/index.html +94 -0
- jamly_audio_sep-0.1.1/src/jamly_audio_sep.egg-info/PKG-INFO +279 -0
- jamly_audio_sep-0.1.1/src/jamly_audio_sep.egg-info/SOURCES.txt +69 -0
- jamly_audio_sep-0.1.1/src/jamly_audio_sep.egg-info/dependency_links.txt +1 -0
- jamly_audio_sep-0.1.1/src/jamly_audio_sep.egg-info/entry_points.txt +6 -0
- jamly_audio_sep-0.1.1/src/jamly_audio_sep.egg-info/requires.txt +6 -0
- jamly_audio_sep-0.1.1/src/jamly_audio_sep.egg-info/top_level.txt +1 -0
- jamly_audio_sep-0.1.1/tests/test_audio.py +86 -0
- jamly_audio_sep-0.1.1/tests/test_bootstrap.py +42 -0
- jamly_audio_sep-0.1.1/tests/test_companion.py +55 -0
- jamly_audio_sep-0.1.1/tests/test_core.py +77 -0
- jamly_audio_sep-0.1.1/tests/test_core_extra.py +88 -0
- jamly_audio_sep-0.1.1/tests/test_logging.py +42 -0
- jamly_audio_sep-0.1.1/tests/test_naming.py +108 -0
- jamly_audio_sep-0.1.1/tests/test_native_audio.py +395 -0
- jamly_audio_sep-0.1.1/tests/test_normalize.py +161 -0
- jamly_audio_sep-0.1.1/tests/test_queue.py +197 -0
- jamly_audio_sep-0.1.1/tests/test_run.py +295 -0
- jamly_audio_sep-0.1.1/tests/test_server.py +385 -0
- jamly_audio_sep-0.1.1/tests/test_service.py +129 -0
- jamly_audio_sep-0.1.1/tools/Jamly.spec +79 -0
- jamly_audio_sep-0.1.1/tools/browser_smoke.mjs +265 -0
- jamly_audio_sep-0.1.1/tools/build_companion.py +230 -0
- jamly_audio_sep-0.1.1/tools/bundle_smoke.py +293 -0
- jamly_audio_sep-0.1.1/tools/desktop_entry.py +53 -0
- jamly_audio_sep-0.1.1/tools/generate_icons.py +210 -0
- jamly_audio_sep-0.1.1/tools/jamly.icns +0 -0
- jamly_audio_sep-0.1.1/tools/jamly.ico +0 -0
- jamly_audio_sep-0.1.1/tools/native-sources.json +30 -0
- jamly_audio_sep-0.1.1/tools/native_audio.py +218 -0
- jamly_audio_sep-0.1.1/tools/package_render.py +58 -0
- jamly_audio_sep-0.1.1/tools/render_aur.py +97 -0
- jamly_audio_sep-0.1.1/tools/render_homebrew.py +78 -0
- jamly_audio_sep-0.1.1/tools/render_winget.py +88 -0
- jamly_audio_sep-0.1.1/tools/version.py +183 -0
- jamly_audio_sep-0.1.1/uv.lock +1234 -0
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# Current design
|
|
2
|
+
|
|
3
|
+
## Product boundary
|
|
4
|
+
|
|
5
|
+
Jamly is a local exporter with a companion interface and an optional browser extension.
|
|
6
|
+
It accepts individual media URLs or local audio files and produces reusable stem pairs (`drums`/`no_drums`
|
|
7
|
+
by default, or `vocals`/`no_vocals` for karaoke, `bass`, `guitar`, `piano`, `other`, or `all` individual stems).
|
|
8
|
+
The companion works without an extension; the extension is a convenience for submitting the current page.
|
|
9
|
+
A static showcase website lives under `site/` for GitHub Pages and is excluded from Python wheels,
|
|
10
|
+
browser extension exports, and desktop companion archives.
|
|
11
|
+
|
|
12
|
+
A lightweight practice player with synchronized playback, A-B loops, speed adjustment and a count-in
|
|
13
|
+
is a possible later direction, **not implemented or scheduled**. Browser-only inference is descoped.
|
|
14
|
+
Cloud accounts, a full practice platform, additional engines and marketplace publication are not part
|
|
15
|
+
of this release.
|
|
16
|
+
|
|
17
|
+
## Pipeline
|
|
18
|
+
|
|
19
|
+
`run.process_one` validates one media item (fetching remote metadata and audio through the installed
|
|
20
|
+
interpreter's yt-dlp, or probing local audio files directly via ffprobe/soundfile without network
|
|
21
|
+
access), invokes an isolated Demucs worker, and publishes the requested stem exports. Collections,
|
|
22
|
+
remote `file://` hosts, and active live streams are rejected before download. Deno is resolved from
|
|
23
|
+
the same Python environment.
|
|
24
|
+
|
|
25
|
+
`demucs_worker` uses the Demucs API, emits chunk-level progress percentages, and writes its raw
|
|
26
|
+
estimates as float32 WAV with soundfile. There is no per-stem rescaling or clamping. `models` defines
|
|
27
|
+
three presets: Balanced (`htdemucs`, default), Higher quality (`htdemucs_ft`), and 6-stem
|
|
28
|
+
(`htdemucs_6s`). All three use the same pipeline and output contract. `htdemucs_ft` runs the
|
|
29
|
+
fine-tuned model bag and takes approximately four times longer; `htdemucs_6s` separates six sources
|
|
30
|
+
(`drums`, `bass`, `other`, `vocals`, `guitar`, `piano`) so guitar/piano targets can be isolated and
|
|
31
|
+
any complement track sums the remaining five stems. Model and stem choices are captured in each
|
|
32
|
+
job, survive retries and are recorded in its manifest.
|
|
33
|
+
|
|
34
|
+
`audio` validates matching frame count, sample rate and channels, then sums every complement stem
|
|
35
|
+
for the selected target (`--stem`, defaulting to `drums`, or `vocals` for karaoke, `bass`, `guitar`,
|
|
36
|
+
`piano`, `other`, or `all` individual stems).
|
|
37
|
+
It processes these files in blocks, rejects non-finite samples, and applies one shared gain to
|
|
38
|
+
all final outputs. WAV remains float32. MP3 uses 320 kbps encoding and a decoded, 4x-oversampled
|
|
39
|
+
peak check targeting -1 dBFS; any additional attenuation is shared and re-encoded from the raw stems.
|
|
40
|
+
|
|
41
|
+
## Output transaction
|
|
42
|
+
|
|
43
|
+
Exported audio files live directly in `<output>/` (`Artist - Song [id]_<stem>.<ext>`, with ` [<model>]`
|
|
44
|
+
appended when a non-default model preset is selected), while internal manifests (`metadata.json`,
|
|
45
|
+
including a generation id and SHA-256 checksums) live under `<output>/.jamly/<stable-id>/<model>/[<stem>/]<format>/`.
|
|
46
|
+
|
|
47
|
+
A per-track/model/format lock prevents overlapping publishers. All output files are completed in a
|
|
48
|
+
sibling staging directory under `.jamly/`, then atomically published into `<output>/` alongside the
|
|
49
|
+
manifest swap. Replacement backs up any superseded manifest and audio files before swapping the new
|
|
50
|
+
generation into place; a failed swap restores the backup, and an interrupted swap is recovered before
|
|
51
|
+
the next attempt.
|
|
52
|
+
|
|
53
|
+
Readers never receive a mixture of files from a partially published directory. During replacement
|
|
54
|
+
there can be a short interval with no directory. Authenticated downloads check the generation
|
|
55
|
+
under the same lock and return 409 if the result is being replaced or superseded.
|
|
56
|
+
|
|
57
|
+
Existing outputs are reusable only when their processing version, identity, model, format and checksums
|
|
58
|
+
match. Cache lookup precedes network/model work. Metadata and audio are published together. Selecting
|
|
59
|
+
another preset neither reuses nor replaces the first preset's files. Older layouts remain untouched.
|
|
60
|
+
|
|
61
|
+
## Queue and lifecycle
|
|
62
|
+
|
|
63
|
+
The CLI or backend holds an exclusive process lock for the lifetime of queue ownership. Concurrent
|
|
64
|
+
standalone CLI/backend writers are refused rather than silently overwriting one another. Revision
|
|
65
|
+
checks also reject stale direct saves.
|
|
66
|
+
|
|
67
|
+
Job records retain the stable id, source URL, options, status, attempts, error and output generation.
|
|
68
|
+
States are `pending`, `running`, `done`, `skipped`, `error`, and `cancelled`. A legacy JSON done-set
|
|
69
|
+
is readable, but new error records are not treated as successful completions.
|
|
70
|
+
|
|
71
|
+
Explicit submission requeues terminal jobs and captures the requested settings. Pending/running
|
|
72
|
+
duplicates are ignored. Server errors require explicit retry; interrupted running jobs resume after
|
|
73
|
+
restart. CLI invocation without inputs retries failed jobs once, not in an infinite loop.
|
|
74
|
+
|
|
75
|
+
The backend persists `running` before starting expensive work. Progress stages remain in memory.
|
|
76
|
+
Subprocesses run in owned process groups; cancellation terminates the owned tree, cleans staging
|
|
77
|
+
files and returns interrupted work to the queue. Shutdown joins the worker before releasing ownership.
|
|
78
|
+
Queue persistence errors are exposed, not converted into successful acceptance.
|
|
79
|
+
|
|
80
|
+
## Companion, local API and browser
|
|
81
|
+
|
|
82
|
+
API version 3 uses finite JSON snapshots. The backend owns all durable state. The local companion page
|
|
83
|
+
polls while visible; the extension service worker handles requests on demand and its popup polls while
|
|
84
|
+
open. Neither browser page owns the inference process.
|
|
85
|
+
|
|
86
|
+
`companion` serializes launches, checks for the authenticated backend associated with its queue,
|
|
87
|
+
and reconnects or starts a separate process. The backend publishes a private instance descriptor.
|
|
88
|
+
Before sending its pairing credential, the launcher verifies a fresh HMAC challenge bound to the
|
|
89
|
+
backend address and queue. A stale port occupied by another application cannot collect the token.
|
|
90
|
+
Closing a page or the short-lived launcher does not stop jobs. Quit invokes orderly shutdown;
|
|
91
|
+
SIGTERM also cancels processing and preserves unfinished work for restart.
|
|
92
|
+
|
|
93
|
+
Saved UI preferences are validated and atomically persisted separately from the queue. They override
|
|
94
|
+
installation configuration; explicit backend CLI arguments override saved preferences at startup.
|
|
95
|
+
An accepted job retains its original settings even if the defaults change.
|
|
96
|
+
|
|
97
|
+
A private per-user token or a companion session is required for jobs, status and downloads. The unauthenticated health probe
|
|
98
|
+
contains no paths or credentials. Origin and Host checks are independent of authentication. Result
|
|
99
|
+
URLs refer to known completed artifacts, never arbitrary client-supplied filesystem paths.
|
|
100
|
+
|
|
101
|
+
Automatic pairing delivers a two-minute, single-use launch ticket in a private local HTML file.
|
|
102
|
+
The browser submits it in a POST body, receives a 24-hour session token, and stores that token in
|
|
103
|
+
tab-scoped sessionStorage. The launch file is removed after use; stale tickets cannot be replayed.
|
|
104
|
+
No credential is put in a URL, command line, log or cookie. Static UI assets expose no secrets.
|
|
105
|
+
Manual pairing remains available for advanced clients.
|
|
106
|
+
|
|
107
|
+
Native web downloads POST the session token in a hidden form so large files do not need to be held
|
|
108
|
+
in a JavaScript Blob. UI pages use a same-origin referrer policy to retain the Origin header for these
|
|
109
|
+
POSTs, a restrictive CSP, and frame blocking. Only the ticket-exchange endpoint permits a null
|
|
110
|
+
file-origin; other browser origins remain restricted. Desktop actions are limited to loopback servers.
|
|
111
|
+
|
|
112
|
+
The extension renders server text with DOM text APIs, shows failed HTTP requests, and uses the
|
|
113
|
+
browser download manager with an Authorization header. Tokens are not placed in result URLs.
|
|
114
|
+
The optional userscript is a limited status/enqueue helper, not a second full application.
|
|
115
|
+
|
|
116
|
+
## Installed environment
|
|
117
|
+
|
|
118
|
+
Companion, CLI, backend, doctor and service commands share configuration helpers. Defaults use per-user
|
|
119
|
+
application data and `~/Music/jamly`, not whichever directory launched the service.
|
|
120
|
+
|
|
121
|
+
`service` renders OS-specific registration definitions around the exact installed Python executable.
|
|
122
|
+
Windows uses a per-user logon task, macOS a LaunchAgent, and Linux a user systemd unit. Browser assets
|
|
123
|
+
are included in the wheel and can be copied to a stable directory for unpacked loading.
|
|
124
|
+
|
|
125
|
+
Development and CI use `uv.lock`. Fast tests exercise error/recovery contracts without downloading a
|
|
126
|
+
model; explicit integration checks exercise the installed pipeline and Chrome with generated audio.
|
|
127
|
+
|
|
128
|
+
## Desktop packages
|
|
129
|
+
|
|
130
|
+
`runtime` centralizes executable, asset and tool discovery. Source installs invoke interpreter-local
|
|
131
|
+
modules. Frozen installs dispatch a small allowlist through the bundled console runtime rather than
|
|
132
|
+
treating the GUI executable as a Python interpreter. The GUI launcher and worker share a PyInstaller
|
|
133
|
+
onedir runtime; there is no onefile extraction or source-checkout dependency at launch.
|
|
134
|
+
|
|
135
|
+
`tools/native_audio.py` builds ffmpeg, ffprobe and a minimal shared libsndfile from checksum-pinned
|
|
136
|
+
sources. FFmpeg links the pinned LAME and OpenSSL statically, with GPL/nonfree features disabled.
|
|
137
|
+
The source-built libsndfile replaces the soundfile wheel's opaque codec bundle and handles PCM;
|
|
138
|
+
encoded input decoding uses Demucs' sphn/FFmpeg path, and MP3 output uses FFmpeg. Corresponding sources,
|
|
139
|
+
build instructions, native configuration, package notices and checksums accompany the desktop artifacts.
|
|
140
|
+
The project code remains MIT; bundled components retain their own terms.
|
|
141
|
+
|
|
142
|
+
The locked `bundle` dependency group provides PyInstaller and the Python-notice archive reader.
|
|
143
|
+
Builds use uv-managed Python and collect its native dependency notices from the matching,
|
|
144
|
+
checksum-verified python-build-standalone release. Native dependencies and Deno are included,
|
|
145
|
+
and all state/exports stay outside the application. Model weights download into their upstream user
|
|
146
|
+
caches on first use and are not included in the application. Updates replace the application manually.
|
|
147
|
+
|
|
148
|
+
The packaging workflow builds native archives on macOS ARM64/Intel, Windows x64, and Linux x64.
|
|
149
|
+
Linux builds target Ubuntu 22.04's glibc baseline. The package check extracts into a new path containing
|
|
150
|
+
spaces, clears PATH and Python environment overrides, checks runtime/assets/pairing, and processes
|
|
151
|
+
generated compressed audio with both real model presets. macOS binaries are also checked for external
|
|
152
|
+
non-system library references.
|
|
153
|
+
|
|
154
|
+
Artifacts are unsigned previews, not a signed/notarized public distribution. Release signing credentials,
|
|
155
|
+
store submission and an automatic updater are not configured.
|
|
156
|
+
|
|
157
|
+
## Versioning and releases
|
|
158
|
+
|
|
159
|
+
Release versions follow Semantic Versioning (`MAJOR.MINOR.PATCH`, starting at `0.1.0`). Pre-`1.0`
|
|
160
|
+
releases increment `MINOR` for new features, presets, or contract changes and `PATCH` for bug fixes
|
|
161
|
+
and dependency updates. `tools/version.py` keeps `src/jamly/__init__.py`, `pyproject.toml`, `uv.lock`,
|
|
162
|
+
`browser/extension/manifest.json`, `browser/userscripts/jamly.user.js`, and `tools/Jamly.spec` in
|
|
163
|
+
strict lockstep; CI and tests enforce that all six match. Output cache schema (`PROCESSING_VERSION`)
|
|
164
|
+
and loopback control protocol (`api_version`) are versioned independently from the release number.
|
|
165
|
+
|
|
166
|
+
To cut a release, run `uv run --locked python tools/version.py --set X.Y.Z`, run the test and lint
|
|
167
|
+
suites, commit on `main`, and push an annotated `vX.Y.Z` tag. Tag pushes trigger `companions.yml`,
|
|
168
|
+
which verifies the tag against `tools/version.py`, builds and smoke-tests the four desktop companion
|
|
169
|
+
archives alongside their corresponding native source archives, packages the browser extension and
|
|
170
|
+
userscript, writes `SHA256SUMS.txt`, and publishes the GitHub Release.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kurt Galiatsatos
|
|
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,279 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: jamly-audio-sep
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Split media URLs or local audio into drums/drumless, karaoke, or multi-stem tracks locally with Demucs.
|
|
5
|
+
Author: Kurt Galiatsatos
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://kurtisnotcurtis.github.io/jamly/
|
|
8
|
+
Project-URL: Repository, https://github.com/kurtisnotcurtis/jamly
|
|
9
|
+
Project-URL: Releases, https://github.com/kurtisnotcurtis/jamly/releases
|
|
10
|
+
Project-URL: Issues, https://github.com/kurtisnotcurtis/jamly/issues
|
|
11
|
+
Keywords: audio,demucs,stem-separation,yt-dlp
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Multimedia :: Sound/Audio
|
|
20
|
+
Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
|
|
21
|
+
Requires-Python: <3.13,>=3.11
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE.md
|
|
24
|
+
Requires-Dist: demucs<5,>=4.1
|
|
25
|
+
Requires-Dist: filelock>=3.16
|
|
26
|
+
Requires-Dist: numpy<2,>=1.26
|
|
27
|
+
Requires-Dist: platformdirs>=4
|
|
28
|
+
Requires-Dist: soundfile>=0.13
|
|
29
|
+
Requires-Dist: yt-dlp[default,deno]>=2026.10.26
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
<p align="center">
|
|
33
|
+
<img src="site/jamly-mark.svg" alt="Jamly Logo" width="84" height="84" />
|
|
34
|
+
</p>
|
|
35
|
+
|
|
36
|
+
<h1 align="center">Jamly</h1>
|
|
37
|
+
|
|
38
|
+
<p align="center">
|
|
39
|
+
<a href="https://kurtisnotcurtis.github.io/jamly/">Website & Setup Guide</a> ·
|
|
40
|
+
<a href="https://github.com/kurtisnotcurtis/jamly/releases">Download Releases</a> ·
|
|
41
|
+
<a href="DESIGN.md">Architecture (DESIGN.md)</a>
|
|
42
|
+
</p>
|
|
43
|
+
|
|
44
|
+
Split any song or video into isolated **drums** and **drumless** practice tracks—or **karaoke** (`vocals` + `no_vocals`), **bass**, **guitar**, **piano**, or **all individual stems**—100% locally on your computer.
|
|
45
|
+
|
|
46
|
+
- **Practice, karaoke, or transcribe**: Mute the drums (or vocals/bass/guitar) to play or sing along, solo any stem to learn parts note-for-note, or export the full multi-track stem pack.
|
|
47
|
+
- **URLs or local audio**: Pass a media URL supported by `yt-dlp` or drop in local `.wav`, `.mp3`, `.flac`, `.m4a`, `.ogg`, or `.opus` files.
|
|
48
|
+
- **Phase-accurate & private**: Runs Meta's Hybrid Transformer Demucs v4 models locally on your CPU or GPU with shared peak-safe gain staging—no cloud uploads, subscriptions, or per-minute limits.
|
|
49
|
+
|
|
50
|
+
> *Note: Stem separation is an estimate and can contain bleed or artifacts depending on the mix; "drumless" is not a guarantee of perfect removal.*
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Quick Start
|
|
55
|
+
|
|
56
|
+
### Option A: Desktop Companion (No Python setup required)
|
|
57
|
+
|
|
58
|
+
Self-contained archives for **macOS** (Apple Silicon & Intel), **Windows x64**, and **Linux x64** bundle Python, Demucs, `yt-dlp`, Deno, `ffmpeg`, and `ffprobe` out of the box.
|
|
59
|
+
|
|
60
|
+
1. Download the archive for your OS from [Releases](https://github.com/kurtisnotcurtis/jamly/releases) (or the **Companion packages** GitHub Actions workflow).
|
|
61
|
+
2. Launch the companion:
|
|
62
|
+
- **macOS 13+**: Extract the zip, move `Jamly.app` to `Applications`, and open it.
|
|
63
|
+
- **Windows**: Install via WinGet (`winget install kurtisnotcurtis.Jamly` and run `jamly`), or extract the **entire** zip and run `Jamly.exe` (keep all files in the extracted folder together).
|
|
64
|
+
- **Linux (glibc 2.35+)**: Extract the `.tar.gz` and run `./Jamly` inside the extracted folder.
|
|
65
|
+
3. Jamly opens your browser to the local companion page automatically:
|
|
66
|
+
- Paste a track URL or local file path—or click **Choose files** to upload audio from your computer.
|
|
67
|
+
- Pick a **Preset** and **Format** (`MP3` or `WAV`), then click **Split drums**.
|
|
68
|
+
- Click **Show files** to open the folder on disk, or **Save a copy** to download directly in your browser.
|
|
69
|
+
|
|
70
|
+
*(Closing the browser tab does not interrupt running jobs; reopen `Jamly` anytime to reconnect, or click **Quit companion** to stop the background worker. Note: preview builds are unsigned, so macOS Gatekeeper or Windows SmartScreen may prompt on first launch.)*
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
### Option B: CLI & Python Install (via `uv`)
|
|
75
|
+
|
|
76
|
+
If you prefer the command line or already use Python (3.11 or 3.12), install [uv](https://docs.astral.sh/uv/getting-started/installation/) and `ffmpeg`:
|
|
77
|
+
|
|
78
|
+
```text
|
|
79
|
+
macOS: brew install ffmpeg
|
|
80
|
+
Debian/Ubuntu: sudo apt install ffmpeg
|
|
81
|
+
Windows: winget install Gyan.FFmpeg
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Then install Jamly and verify your environment:
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
uv tool install --python 3.12 git+https://github.com/kurtisnotcurtis/jamly.git
|
|
88
|
+
jamly-doctor
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
From there, you can launch the local web companion or split tracks directly from your terminal:
|
|
92
|
+
|
|
93
|
+
```sh
|
|
94
|
+
# Open the local web companion UI
|
|
95
|
+
jamly-companion
|
|
96
|
+
|
|
97
|
+
# Or split directly from the CLI
|
|
98
|
+
jamly -i "https://youtu.be/VIDEO_ID"
|
|
99
|
+
jamly -i "https://youtu.be/VIDEO_ID" --stem vocals
|
|
100
|
+
jamly -i "/path/to/song.flac" --model htdemucs_ft --audio-format wav
|
|
101
|
+
jamly -i "/path/to/song.flac" --model htdemucs_6s --stem guitar
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Separation Presets & Output Layout
|
|
107
|
+
|
|
108
|
+
| Preset | CLI Flag | How It Works & Tradeoff |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| **Balanced** *(default)* | `--model htdemucs` | Fast 4-stem Hybrid Transformer Demucs; computes `no_drums` by phase-aligned residual subtraction (`mix - drums`). |
|
|
111
|
+
| **Higher quality** | `--model htdemucs_ft` | Fine-tuned 4-stem ensemble; cleaner transient isolation, takes **~4× longer** and downloads larger weights on first use. |
|
|
112
|
+
| **6-stem (HTDemucs)** | `--model htdemucs_6s` | 6-stem Demucs (`drums`, `bass`, `guitar`, `piano`, `vocals`, `other`); single-pass speed and sums all 5 non-drum stems. |
|
|
113
|
+
|
|
114
|
+
Model weights download automatically on first use of each preset. Completed exports are saved directly in `~/Music/jamly` by default (with internal cache manifests tucked inside a hidden `.jamly/` folder so your music folder stays clean):
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
~/Music/jamly/
|
|
118
|
+
Artist - Song [id]_drums.mp3
|
|
119
|
+
Artist - Song [id]_no_drums.mp3
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Re-running a track with a new preset or format keeps your earlier exports intact alongside the new one.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Guides & Reference
|
|
127
|
+
|
|
128
|
+
<details>
|
|
129
|
+
<summary><strong>Optional Browser Extension & Userscript (One-click from YouTube)</strong></summary>
|
|
130
|
+
|
|
131
|
+
<br>
|
|
132
|
+
|
|
133
|
+
The companion works out of the box by pasting URLs or picking local files, but you can also add the unpacked Chrome/Edge extension to send the active tab in one click:
|
|
134
|
+
|
|
135
|
+
1. In the companion UI, expand **Optional Chrome / Edge extension** and click **Prepare extension**.
|
|
136
|
+
2. Open `chrome://extensions` (or `edge://extensions`), enable **Developer mode**, click **Load unpacked**, and select the displayed folder.
|
|
137
|
+
3. Open the extension's **Pair / settings** page and paste the displayed backend URL (`http://127.0.0.1:8765`) and private pairing token.
|
|
138
|
+
4. Click the Jamly toolbar icon on a YouTube video and select **Use current page** → **Split drums**.
|
|
139
|
+
|
|
140
|
+
**CLI-only setup**: Run `jamly-server`, then run `jamly-service browser` (prints the unpacked extension folder) and `jamly-service token` (prints the pairing token).
|
|
141
|
+
|
|
142
|
+
**Optional Userscript**: Run `jamly-service userscript` to export a lightweight YouTube / YouTube Music button for Tampermonkey or Violentmonkey. Use its **Pair Jamly** menu command to set your token.
|
|
143
|
+
|
|
144
|
+
</details>
|
|
145
|
+
|
|
146
|
+
<details>
|
|
147
|
+
<summary><strong>Full CLI Reference & Caching Rules</strong></summary>
|
|
148
|
+
|
|
149
|
+
<br>
|
|
150
|
+
|
|
151
|
+
```sh
|
|
152
|
+
jamly -i "https://youtu.be/VIDEO_ID"
|
|
153
|
+
jamly -i "/path/to/local_song.wav"
|
|
154
|
+
jamly -i URL -i ANOTHER_URL --audio-format wav
|
|
155
|
+
jamly -i URL --model htdemucs_ft
|
|
156
|
+
jamly -i URL --model htdemucs_6s
|
|
157
|
+
jamly -i URL --replace-existing
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
- **Piped inputs**: Newline-separated URLs, IDs, or file paths can be piped via `stdin`. For a bare ID starting with `-`, pass `-i=-VIDEO_ID`.
|
|
161
|
+
- **Single-recording policy**: Playlists, search results, multi-item pages, and live/upcoming streams are rejected; pass individual recordings. Cookie/account login is not used.
|
|
162
|
+
- **Resume & retry**: Running `jamly` with no `-i` arguments processes any pending items and retries failed CLI jobs once.
|
|
163
|
+
- **Smart cache**: Checksum-valid exports are reused without re-downloading or re-separating unless `--replace-existing` is passed.
|
|
164
|
+
|
|
165
|
+
| Option | Default | Description |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| `-o`, `--output-dir DIR` | `~/Music/jamly` | Directory for exported audio files |
|
|
168
|
+
| `--stem {drums,vocals,bass,guitar,piano,other,all}` | `drums` | Target stem pair (`<stem>` + `no_<stem>`), such as `vocals` for karaoke, or `all` for every individual stem |
|
|
169
|
+
| `--audio-format {mp3,wav}` | `mp3` | `320 kbps` MP3 (checked with 1 dB decoded peak headroom) or `float32` WAV |
|
|
170
|
+
| `--model {htdemucs,htdemucs_ft,htdemucs_6s}` | `htdemucs` | Demucs v4 preset (`guitar` and `piano` require `htdemucs_6s`) |
|
|
171
|
+
| `--device {auto,cpu,cuda,mps}` | `auto` | Inference device selection |
|
|
172
|
+
| `-t`, `--threads N` | `0` | Parallel Demucs worker threads (higher values use more RAM) |
|
|
173
|
+
| `--state-dir DIR` / `--queue FILE` | Per-user app data | Override state directory or queue file path |
|
|
174
|
+
| `--dry-run` | `false` | Preview what would be processed without modifying state |
|
|
175
|
+
|
|
176
|
+
</details>
|
|
177
|
+
|
|
178
|
+
<details>
|
|
179
|
+
<summary><strong>Background Login Service & Updating</strong></summary>
|
|
180
|
+
|
|
181
|
+
<br>
|
|
182
|
+
|
|
183
|
+
### Start a CLI installation automatically at login
|
|
184
|
+
|
|
185
|
+
```sh
|
|
186
|
+
jamly-service install
|
|
187
|
+
jamly-service status
|
|
188
|
+
jamly-service restart
|
|
189
|
+
jamly-service stop
|
|
190
|
+
jamly-service uninstall
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
`jamly-service install` registers a per-user `systemd` unit on Linux, a `LaunchAgent` on macOS, or a user logon task on Windows using absolute paths and your detected `ffmpeg` location. Pass `--dry-run` to preview the generated service definition, or pass pipeline defaults during install:
|
|
194
|
+
|
|
195
|
+
```sh
|
|
196
|
+
jamly-service install --audio-format wav --output-dir "/path/to/music" --port 8765
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### Updating Jamly
|
|
200
|
+
|
|
201
|
+
- **Desktop package**: Click **Quit companion**, replace the extracted folder/`Jamly.app` with the new release archive, and launch it again. Your queue, settings, and exports are stored outside the application directory and are preserved.
|
|
202
|
+
- **CLI install**:
|
|
203
|
+
```sh
|
|
204
|
+
uv tool upgrade jamly-audio-sep
|
|
205
|
+
jamly-doctor
|
|
206
|
+
jamly-service browser
|
|
207
|
+
jamly-service restart
|
|
208
|
+
```
|
|
209
|
+
Reload the unpacked browser extension in `chrome://extensions` after exporting updated assets.
|
|
210
|
+
|
|
211
|
+
</details>
|
|
212
|
+
|
|
213
|
+
<details>
|
|
214
|
+
<summary><strong>Local HTTP API</strong></summary>
|
|
215
|
+
|
|
216
|
+
<br>
|
|
217
|
+
|
|
218
|
+
The local backend speaks **API version 3** on `127.0.0.1`. All job, settings, upload, and download endpoints require `Authorization: Bearer <token>`.
|
|
219
|
+
|
|
220
|
+
| Endpoint | Purpose |
|
|
221
|
+
|---|---|
|
|
222
|
+
| `GET /healthz` | Public health & `api_version` check (exposes no paths or credentials) |
|
|
223
|
+
| `GET /status` (or `/items`) | Queue counts, active stage + percentage progress, and job records with download URLs |
|
|
224
|
+
| `POST /add` | `{"inputs":["URL_OR_PATH"],"model":"htdemucs_ft","stem":"vocals","audio_format":"wav","replace_existing":false}` |
|
|
225
|
+
| `POST /app/upload?name=song.wav` | Stream raw audio bytes (`audio/*` or `application/octet-stream`) into private state and return its local path |
|
|
226
|
+
| `POST /settings` | Persist default `model`, `stem`, `audio_format`, and `output_dir` |
|
|
227
|
+
| `POST /retry/<id>` | `{"replace_existing":false}` |
|
|
228
|
+
| `GET /outputs/<id>/<kind>?generation=...` | Download an exported stem (`drums`, `no_drums`, `vocals`, `no_vocals`, etc.) or `metadata` for a completed generation |
|
|
229
|
+
|
|
230
|
+
</details>
|
|
231
|
+
|
|
232
|
+
<details>
|
|
233
|
+
<summary><strong>Development, Testing & Packaging</strong></summary>
|
|
234
|
+
|
|
235
|
+
<br>
|
|
236
|
+
|
|
237
|
+
### Local development & tests
|
|
238
|
+
|
|
239
|
+
Requires Python 3.11–3.12, [uv](https://docs.astral.sh/uv/), `ffmpeg`/`ffprobe`, and Node 24+:
|
|
240
|
+
|
|
241
|
+
```sh
|
|
242
|
+
uv sync --locked
|
|
243
|
+
uv run --locked python tools/version.py --check
|
|
244
|
+
uv run --locked pytest
|
|
245
|
+
uv run --locked python -m unittest discover -s tests
|
|
246
|
+
uv run --locked ruff check .
|
|
247
|
+
node --test browser/extension/jamly_client_test.js browser/extension/jamly_extension_bg_test.js browser/extension/jamly_popup_test.js
|
|
248
|
+
uv build
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
To run the end-to-end integration and headless Chrome smoke checks with real Demucs separation on synthesized audio:
|
|
252
|
+
|
|
253
|
+
```sh
|
|
254
|
+
uv run --locked python -m unittest discover -s tests -p integration_pipeline.py
|
|
255
|
+
node tools/browser_smoke.mjs
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Building native desktop archives
|
|
259
|
+
|
|
260
|
+
Build on the target OS with `uv`-managed Python 3.12 and a C/C++ toolchain (`build-essential pkg-config perl` on Linux, Xcode CLT + `pkg-config` on macOS, or MSYS2 `MINGW64` on Windows):
|
|
261
|
+
|
|
262
|
+
```sh
|
|
263
|
+
export UV_PROJECT_ENVIRONMENT=.venv-bundle
|
|
264
|
+
uv sync --locked --group bundle --managed-python --python 3.12
|
|
265
|
+
uv run --no-sync python tools/build_companion.py
|
|
266
|
+
uv run --no-sync python tools/bundle_smoke.py --real-models
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
See [DESIGN.md](DESIGN.md) for architecture, security boundaries, and release versioning details, and [AGENTS.md](AGENTS.md) for contributor guidelines.
|
|
270
|
+
|
|
271
|
+
</details>
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## License
|
|
276
|
+
|
|
277
|
+
Jamly is licensed under the [MIT License](LICENSE.md), covering the `jamly` application code (`src/jamly/`) and browser extension/userscript assets (`browser/`). Third-party runtime dependencies—including Demucs (`htdemucs`), PyTorch, `ffmpeg`/`ffprobe`, `yt-dlp`, Deno, and bundled native libraries—retain their own licenses.
|
|
278
|
+
|
|
279
|
+
*Only download or process media you are authorized to use, and follow the source site's terms of service.*
|