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
