breakdig 0.1.0__tar.gz

breakdig-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.1.0 (2026-09-29)
+
+First release.
+
+- `breakdig index` separates each track into drums, bass, vocals and other with Demucs
+  (htdemucs_ft through audio-separator), finds downbeats with beat_this, and stores
+  per-bar stem levels in a local SQLite index. Resumable and idempotent; the same audio
+  in another format or at another path is recognised and not separated twice, and a
+  retagged, moved or renamed file keeps its analysis. `--exclude` skips files and folders
+  by name, and a second run on the same index stops rather than racing the first. Reads
+  MP3, FLAC, WAV, AIFF, M4A, AAC, OGG, Opus and WMA.
+- `breakdig find` lists bar-exact sections by what is playing: drums only, vocals only,
+  bass and drums only, anything with no drums, and so on. Filters for length, tempo and
+  words in the tags or path; sorted by how clean the section is, and `--cleaner-than`
+  sets a floor.
+  `--silence-db` loosens the silence rule when separation bleed hides sections you can hear.
+- `breakdig export` cuts sections from the original file at the bar lines, snapped to
+  the quietest point within 2 ms, as tagged WAV. `--sp404` writes 16-bit 48 kHz files named
+  BRK_0001.WAV with an index.csv, and `--sp404 sx` writes 44.1 kHz for the SX, A and
+  original 404. Exporting again overwrites or skips what is there, even
+  after the library moves, and relists clips from an export that was cut off.
+- `breakdig export --keep drums` (or `drums,bass`, and so on) exports only those stems:
+  each section is separated again with a few seconds either side and put back at the
+  source sample rate, so the drums can be taken out of bars where a bassline or pad plays
+  over them.
+- Exported WAVs have a cue point on every beat.
+- `breakdig ui` opens a local web UI to filter, audition and export sections. Previews loop
+  with no gap, ticked rows are kept across searches, and the filters, volume and loop
+  setting are remembered. Each row shows a small grid of the four stems' levels per bar,
+  and a keep menu previews and exports just the stems you pick.
+- `breakdig stats` shows what is indexed, what failed and why, and indexing speed.
+- `python -m breakdig` works as well as the `breakdig` command.
+- `find --json` includes each section's beat times and per-bar stem levels.

breakdig-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Booyaka101
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

breakdig-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md
+recursive-include tests *.py
+global-exclude __pycache__ *.py[co]

breakdig-0.1.0/PKG-INFO

@@ -0,0 +1,379 @@
+Metadata-Version: 2.4
+Name: breakdig
+Version: 0.1.0
+Summary: Find bar-exact drum breaks, acapellas and other sections in your own music library, using GPU stem separation and downbeat tracking.
+Author: Booyaka101
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Booyaka101/breakdig
+Project-URL: Issues, https://github.com/Booyaka101/breakdig/issues
+Project-URL: Changelog, https://github.com/Booyaka101/breakdig/blob/main/CHANGELOG.md
+Keywords: drum breaks,sampling,stem separation,demucs,downbeat,beat tracking,sp-404,crate digging
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: audio-separator[gpu]>=0.47
+Requires-Dist: audioread>=2.1.9
+Requires-Dist: beat-this>=1.1
+Requires-Dist: numpy>=2
+Requires-Dist: soundfile>=0.12
+Requires-Dist: soxr>=0.3
+Requires-Dist: mutagen>=1.47
+Requires-Dist: fastapi>=0.115
+Requires-Dist: starlette>=0.39
+Requires-Dist: uvicorn>=0.36
+Requires-Dist: tqdm>=4.66
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Dynamic: license-file
+
+# breakdig
+
+Find the drum breaks, acapellas and other bare sections in your own music, cut to the bar.
+
+breakdig runs every track in a folder through Demucs source separation and a downbeat
+tracker, then keeps a small index of how loud the drums, bass, vocals and everything else
+are in each bar. After that you can ask for "drums only, at least 2 bars, 85 to 100 BPM" and
+get back exact bar ranges you can audition and export from the original files.
+
+Everything runs locally. Nothing is uploaded anywhere.
+
+![breakdig UI](https://raw.githubusercontent.com/Booyaka101/breakdig/main/docs/demo.gif)
+
+## Install
+
+You need Python 3.11, ffmpeg on PATH, and for reasonable speed an NVIDIA GPU. On Windows:
+
+```
+winget install Python.Python.3.11
+winget install Gyan.FFmpeg
+```
+
+On Windows the simplest route is the zip. Download `breakdig-0.1.0-windows.zip` from the
+GitHub release, unzip it somewhere permanent, and run `install.bat`. It makes a virtual
+environment next to itself, installs breakdig into it, and swaps in the CUDA build of
+PyTorch if `nvidia-smi` is present. It prints the full path to `breakdig.bat` to use
+afterwards; add the folder to PATH to type just `breakdig`.
+
+Or with pip:
+
+```
+py -3.11 -m venv .venv
+.venv\Scripts\activate
+pip install breakdig
+pip install --force-reinstall --no-deps torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130
+```
+
+The last line matters. On Windows, pip resolves torch to the CPU-only build, and separation
+on the CPU is 10 to 30 times slower. The cu130 wheels need NVIDIA driver 580 or newer; with
+an older driver use `cu126` in the URL instead. breakdig prints a warning when it is running
+without CUDA.
+
+The first `breakdig index` downloads two models: htdemucs_ft (322 MB) into
+`%LOCALAPPDATA%\breakdig\models`, and the beat_this checkpoint (81 MB) into the PyTorch hub
+cache at `%USERPROFILE%\.cache\torch\hub\checkpoints`. If the Demucs download is cut short,
+the run stops and deletes the partial file, and the next run downloads it again.
+
+## Quick start
+
+Index a folder. This is the slow part and it only happens once per track:
+
+```
+> breakdig index D:\Music\Breaks
+Scanning 14 files...
+0 already indexed, 14 to do. Index: C:\Users\you\AppData\Local\breakdig
+Done in 189s: 14 ok.
+Separated tracks took 13.5s each on average.
+```
+
+Run it again and it only looks at what is new. Ctrl+C is safe at any point; the next run
+carries on from the track it was working on. A second `index` run on the same index while
+one is going stops straight away and says so.
+
+```
+> breakdig index D:\Music\Breaks
+Scanning 14 files...
+14 already indexed, 0 to do. Index: C:\Users\you\AppData\Local\breakdig
+Done in 0s: nothing new.
+```
+
+Find sections. With no options, `find` looks for drums alone:
+
+```
+> breakdig find
+ID          ARTIST - TITLE                               BARS     START       END    BPM  CLEAN
+-----------------------------------------------------------------------------------------------
+13:107-108  Bebop - Fidget Kaos                             2  3:15.724  3:19.403  130.2  -34.0
+14:165-166  Innyu - For The Hell Of It                      2  5:07.525  5:11.300  127.7  -30.4
+
+2 section(s). CLEAN is the loudest unwanted stem minus the target, in dB; lower is cleaner.
+```
+
+`--silence-db 25` loosens the silence rule (see below) and finds a little more:
+
+```
+> breakdig find --silence-db 25
+ID          ARTIST - TITLE                               BARS     START       END    BPM  CLEAN
+-----------------------------------------------------------------------------------------------
+13:107-109  Bebop - Fidget Kaos                             3  3:15.724  3:21.264  130.0  -29.8
+14:164-166  Innyu - For The Hell Of It                      3  5:05.649  5:11.300  127.7  -26.5
+14:7-8      Innyu - For The Hell Of It                      2  0:11.273  0:15.062  127.8  -26.4
+
+3 section(s). CLEAN is the loudest unwanted stem minus the target, in dB; lower is cleaner.
+```
+
+```
+> breakdig find --no drums --limit 5
+ID          ARTIST - TITLE                               BARS     START       END    BPM  CLEAN
+-----------------------------------------------------------------------------------------------
+7:25-28     Igor Leontyev - Remote District                 4  0:16.358  0:21.674  183.1  -55.7
+10:1-16     Zipp - Coffee Break                            16  0:01.526  0:33.507   60.3  -55.5
+2:56-57     Dog On Springs - Footloose (feat. Paul Whit~    2  1:31.346  1:34.819  137.3  -55.3
+7:4-6       Igor Leontyev - Remote District                 3  0:03.016  0:06.369  182.8  -54.9
+2:43-45     Dog On Springs - Footloose (feat. Paul Whit~    3  1:09.037  1:14.137  142.3  -52.3
+
+5 section(s). CLEAN is the loudest unwanted stem minus the target, in dB; lower is cleaner.
+```
+
+Export everything a `find` would list by giving the same filters to `export`, or pick
+sections by ID with `--pick 13:107-109 14:7-8` (the other filters are ignored then):
+
+```
+> breakdig export --silence-db 25 --out D:\Samples\breaks
+wrote   D:\Samples\breaks\Bebop - Fidget Kaos - 3 bars - 130 BPM - 03.16.wav
+wrote   D:\Samples\breaks\Innyu - For The Hell Of It - 3 bars - 128 BPM - 05.06.wav
+wrote   D:\Samples\breaks\Innyu - For The Hell Of It - 2 bars - 128 BPM - 00.11.wav
+
+3 file(s) in D:\Samples\breaks
+```
+
+Or do all of it in the browser:
+
+```
+> breakdig ui
+breakdig UI on http://127.0.0.1:8765  (Ctrl+C to stop)
+```
+
+## What you can search for
+
+`--only` names the stems that play alone, and everything else has to be silent.
+`--no` names the stems that have to be silent, and at least one of the others has to play.
+Stems are `drums`, `bass`, `vocals` and `other` (everything else: keys, guitars, pads, samples).
+
+| You want | Use |
+| --- | --- |
+| Drum breaks | `--only drums` (the default) |
+| Acapellas | `--only vocals` |
+| Bass and drums | `--only bass,drums` |
+| Anything without drums | `--no drums` |
+| Instrumentals | `--no vocals` |
+
+Other filters: `--min-bars N` (default 2), `--bpm 90` or `--bpm 85-100`, `--search "words"`
+(every word has to appear in the artist, title, album or path), `--cleaner-than -25` (only sections at least that
+clean), `--sort clean|bars|bpm|artist`, `--limit N`, `--skip-seams`, and `--json` for
+scripting.
+
+## How a bar is judged
+
+For every bar, breakdig has the mean level in dB of each separated stem and of the mix.
+
+- A stem is active in a bar if it is no more than 12 dB below the mix.
+- A stem is silent if it is more than 30 dB below the loudest active stem in that bar,
+  or below -90 dBFS.
+  Silent wins over active, so a bar of digital silence has nothing active in it.
+- A bar where a stem is neither is a grey zone and never matches. That is deliberate: it is
+  what keeps a break with a quiet bassline under it out of "drums only".
+- Consecutive matching bars become a section, and a section has to be at least `--min-bars`
+  long.
+- CLEAN is the loudest stem that should be silent minus the target stem, taken from the
+  dirtiest bar in the section. -40 is very clean, -15 means you will probably hear something
+  else in there. Results are sorted by it.
+- BPM is 60 divided by the median beat interval inside the section, so tempo drift is
+  handled per section. Bars come from detected downbeats, so 3/4 and changing meters work.
+  The bar after the last downbeat counts too, if the music carries on for a full bar past it.
+
+The 30 dB is `--silence-db` (and "Silence dB" in the UI). Demucs leaves 20 to 35 dB of bleed
+between stems on real records, so at 30 plenty of breaks you can clearly hear on the record
+will not match. Dropping it to 25 or 20 finds more at the cost of some bleed. The table's
+CLEAN column tells you how much.
+
+## Exports
+
+Clips are cut from the original file, not from the separated stems, at the bar lines. Each
+edge is moved to the quietest point within 2 ms, which gets rid of most clicks; a loud bass
+note held across the bar line can still leave a faint one. Files are WAV at the source
+sample rate: 16-bit from 8- and 16-bit sources, 24-bit from everything else,
+including MP3 and AAC, which decode to more than 16 bits. A lossy file from a loud master
+often decodes past full scale, and those clips are written as 32-bit float so the transients
+are not clipped. They are tagged with artist, title with the bar range, album and BPM, and a
+comment holds the source path, times and content key. Exporting the same section again
+overwrites its file, even after the library has moved or the track was retagged.
+Names follow `{artist} - {title} - {bars} bars - {bpm} BPM - {mm.ss}.wav`, with characters
+Windows cannot handle replaced by `_` and the name capped at 120 characters. If another
+section would get the same name, it becomes `... (2).wav`.
+
+Every clip also has a cue point on each beat, labelled `beat 1`, `beat 2` and so on, in the
+WAV's standard `cue ` chunk. Editors that read WAV cue points show them as markers to chop
+at. Plenty of software ignores them, which does no harm.
+
+`--keep drums` (or the keep menu in the UI) exports only some stems instead of the mix. Each
+section is separated again with three seconds either side, so its edges come out clean,
+and the kept stems are put back at the source sample rate. That turns a near miss into a
+usable break: search `--no vocals`, look at the Stems column in the UI to see where the
+drums are, and export those rows with `--keep drums`. `--keep drums,bass` and the rest work
+the same way. The result is only as good as Demucs, so listen before you trust it. The name
+gets the stems before the bar count (`... - drums - 4 bars - ...`), and the isolated clip
+and the full-mix clip of the same bars are separate files.
+
+`--sp404` (or SP-404 MKII in the UI's format menu) writes 16-bit 48 kHz files named
+`BRK_0001.WAV`, `BRK_0002.WAV` and so on, plus an `index.csv` that maps each file back to its
+source. `--sp404 sx` (SP-404 SX / A in the UI) does the same at 44.1 kHz for the SX, the A
+and the original 404:
+
+```
+file,artist,title,bars,bpm,start,end,source,stems
+BRK_0001.WAV,Bebop,Fidget Kaos,3,130.0,195.724,201.264,D:\Music\Breaks\SOSLP008\SOSLP008_01_BEBOP_DONT_BELIEVE_THE_HYPE-Fidget_Kaos.mp3,
+BRK_0002.WAV,Innyu,For The Hell Of It,3,127.7,305.649,311.300,D:\Music\Breaks\SOSLP008\SOSLP008_02_INNYU_DONT_BELIEVE_THE_HYPE-For_The_Hell_Of_It.mp3,
+BRK_0003.WAV,Innyu,For The Hell Of It,2,127.8,11.273,15.062,D:\Music\Breaks\SOSLP008\SOSLP008_02_INNYU_DONT_BELIEVE_THE_HYPE-For_The_Hell_Of_It.mp3,drums
+```
+
+Exporting into the same SP-404 folder again skips sections that are already there and
+numbers new ones after the highest number in the folder or the csv, so a number is never
+reused. Delete a BRK file and that section is exported again under a new number. Clips that
+would go past full scale are turned down to fit instead of being clipped. Editing
+`index.csv` in Excel is fine, including extra columns of your own and semicolon-separated
+saves, but close it before exporting again. A folder that already has clips at one rate
+refuses the other, so one card never ends up with both.
+
+## The web UI
+
+`breakdig ui` serves on http://127.0.0.1:8765 and opens your browser. Pick stems, set the
+filters and press Find. The play button loads just that section and loops it with no gap
+at the loop point, so you hear how it will loop in a sampler. Space plays or stops the
+selected row and the arrow keys move through the list. Tick rows and press Export to
+write them to the folder at the bottom, then use "reveal" to open the file in Explorer.
+Ticked rows stay ticked when you sort or search again, so one export can collect sections
+from several searches; "clear" unticks them all, and an export unticks what it handled. The
+filters, volume and loop setting are remembered for next time.
+
+The Stems column draws each bar of a section as four small cells, drums, bass, vocals and
+other from top to bottom, brighter the louder that stem is against the mix. The keep menu
+next to Export does what `--keep` does, for previews as well as exports, so you can hear the
+drums on their own before you write them out.
+
+`--port` picks another port and `--no-browser` skips opening a tab. Previews are cached in
+the index folder, up to about 500 MB, and the oldest go first.
+
+It only listens on localhost. `--host 0.0.0.0` works but prints a warning, because anyone
+who can reach the port can browse your index and write exports anywhere you can.
+
+## Configuration
+
+| Setting | Default | |
+| --- | --- | --- |
+| `--home` or `BREAKDIG_HOME` | `%LOCALAPPDATA%\breakdig` | Index folder: `index.sqlite`, per-track profiles, `index.log`, the UI's clip cache |
+| `BREAKDIG_MODELS` | `%LOCALAPPDATA%\breakdig\models` | Separation models, shared by every index |
+| `index --model` | `htdemucs_ft.yaml` | Any audio-separator Demucs model |
+| `index --shifts` | 1 | Demucs random shifts; 2 is slightly cleaner and twice as slow |
+| `index --retry-failed` | off | Try files that failed last time again |
+| `index --exclude GLOB` | none | Skip files and folders whose name matches, e.g. `"*.removed.*"` or `stems`. Repeatable |
+
+`--home` goes before or after the command: `breakdig --home D:\breakdig-index find`. For
+anything but `index`, a `--home` folder with no index in it is an error rather than an empty
+result, so a typo does not look like an empty index.
+
+## Speed
+
+Measured on an RTX 4090 with the default model:
+
+- 64 tracks, 2.5 hours of audio: 11.3 s per track, 12.6x realtime (`breakdig stats`).
+- A 50-track folder, 1.8 hours of audio, indexed unattended: 9.4 s per separated track.
+- A 21-minute MP3: 89 s.
+- Exporting with `--keep`: the first clip takes about 9 s, most of it loading the model, and
+  after that about 6x realtime. Eight sections, 7.5 minutes of audio in all, took 78 s.
+- Re-running on an indexed folder: a second or two. Files whose size and modified time have
+  not changed are not read at all, and neither are unchanged byte-for-byte copies.
+
+The index is small: about 25 KB per minute of audio, so 90 KB or so for a typical track.
+
+## Files it handles and skips
+
+MP3, FLAC, WAV, AIFF, M4A (AAC or ALAC), AAC, OGG Vorbis, Opus and WMA. Mono, 8-bit, 24-bit,
+float and odd sample rates are fine. The same audio at two paths or in two formats is only
+separated once; the copy is recorded as a duplicate and takes over if the original is deleted.
+An original on a drive that is not plugged in counts as still there.
+The exception is a raw .aac file, which does not record its encoder delay, next to the same
+track in another format. A file that moves or is renamed keeps its index entry, and so does one
+you retag. One you trim or edit is analysed again.
+
+Skipped, logged, and listed by `breakdig stats --failures`: files that will not decode,
+DRM-protected iTunes files (.m4p), and tracks with fewer than 8 downbeats (`no_grid`; mostly
+speech, ambient and very short files).
+
+Vinyl rips with crackle can go through [grooveclean](https://github.com/Booyaka101/grooveclean)
+first. Its batch mode writes a `.removed` difference file next to each cleaned side, which
+has enough of a beat to get indexed, so leave those out:
+`breakdig index D:\Rips\cleaned --exclude "*.removed.*"`.
+
+Files over 20 minutes are separated in 10-minute chunks. A section that crosses a chunk
+boundary is marked `seam` because the separation can glitch there; `--skip-seams` drops
+them.
+
+## Limitations
+
+- On most commercial records the drums are almost never truly alone for two bars. Expect a
+  handful of hits per album at the default setting, and use `--silence-db 25` and
+  `--min-bars 1` to see near misses, or `--keep drums` to take the drums out of busier bars.
+- Downbeat tracking can be wrong on rubato, very old recordings and music with no clear
+  pulse. Bars far off a track's usual length are ignored rather than exported as nonsense.
+- Separation quality is Demucs quality. Sections are judged on separated stems but cut from
+  the original mix, so what you export is exactly what was on the record, unless you ask
+  for `--keep`.
+- Tested on Windows 11 with Python 3.11. It should run on Linux; macOS will only have the
+  CPU, which is slow.
+
+## Development
+
+```
+py -3.11 -m venv .venv
+.venv\Scripts\pip install -e .[test]
+.venv\Scripts\python -m pytest -q
+```
+
+The `gpu` tests run real Demucs separation and are skipped without CUDA. Set
+`BREAKDIG_MODELS` to reuse a model folder between runs. CI runs everything else on Windows
+and Linux with the CPU build of torch.
+
+## Releasing
+
+```
+python -m build
+python packaging\make_windows_zip.py
+twine upload dist\breakdig-0.1.0-py3-none-any.whl dist\breakdig-0.1.0.tar.gz
+```
+
+`make_windows_zip.py` writes `dist\breakdig-0.1.0-windows.zip` for the GitHub release.
+
+## Credits
+
+The demo uses Creative Commons music from the Internet Archive: "Retrovision" (MIXG032,
+CC BY-NC 3.0) with tracks by Zipp, Dog On Springs, Astat, Fedorov Mark, VAD and Igor
+Leontyev, and "Dont Believe The Hype" (SOSLP008, CC BY-NC-ND 2.5 IT) with tracks by Bebop and
+Innyu.
+
+Separation is [Demucs](https://github.com/facebookresearch/demucs) through
+[audio-separator](https://github.com/nomadkaraoke/python-audio-separator). Downbeats come
+from [beat_this](https://github.com/CPJKU/beat_this).
+
+## License
+
+MIT