# vgmdb-cuesplitter

> **Status:** Active
> **Category:** Audio & CUE Tools
> **Language:** Python 3
> **Script file:** `ffcuesplitter.py`

## Purpose

Recursively finds all `.cue` files under a root directory and splits each corresponding single-file audio rip into individual track files using the external `ffcuesplitter` tool. Supports parallel processing and a dry-run preview mode.

## Requirements

### Dependencies

```bash
pip install ffcuesplitter
```

| Dependency | Notes |
|------------|-------|
| [`ffcuesplitter`](https://github.com/jeanslack/ffcuesplitter) | Must be installed and available on `PATH` |
| FFmpeg | Must be installed and available on `PATH`; used by `ffcuesplitter` internally |

Python standard library: `subprocess`, `pathlib`, `concurrent.futures` (all built-in).

## Input

| Item | Description | Example |
|------|-------------|---------|
| Root directory | Path passed as the first argument; defaults to current directory | `/mnt/music/albums` |
| Worker count | Optional integer — number of parallel threads | `4` |
| `--dry` flag | Optional — preview mode, no files are written | `--dry` |

## Output

| Item | Description |
|------|-------------|
| Individual track files | Written by `ffcuesplitter` into the same folder as the CUE file (output dir `.`) |
| Console log | Per-CUE file status: `SPLIT`, `SKIP`, or `DRY RUN` |

## Usage

```bash
# Split all CUE files under a directory (single-threaded)
python ffcuesplitter.py /path/to/music

# Use parallel workers
python ffcuesplitter.py /path/to/music 4

# Dry-run — preview what would be split without doing anything
python ffcuesplitter.py /path/to/music --dry
python ffcuesplitter.py /path/to/music 4 --dry

# Use current working directory
python ffcuesplitter.py
```

## Examples

```bash
# Preview what would be processed in a music library
python ffcuesplitter.py "D:\Music\[Unsplit]" --dry

# Split everything using 4 parallel workers
python ffcuesplitter.py "D:\Music\[Unsplit]" 4

# Console output example:
# Found 7 cue files
# SPLIT → D:\Music\[Unsplit]\Artist - Album\Album.cue
# SKIP  (already split) → D:\Music\[Unsplit]\Artist - Album2\Album2.cue
# SPLIT → D:\Music\[Unsplit]\Artist - Album3\Album3.cue
```

## Notes

- A folder is considered **already split** if it contains **more than one audio file** (extensions: `.flac`, `.mp3`, `.wav`, `.ape`, `.tta`, `.m4a`). A single large image file (e.g. one `.ape` or `.flac`) is not treated as already-split, so it will be processed.
- The `--dry` flag can be placed **anywhere** in the argument list — the script checks for its presence using `"--dry" in sys.argv`.
- When using parallel workers, the worker count must be the **second positional argument** (before `--dry` if used): `python ffcuesplitter.py /path 4 --dry`.
- Output tracks are written to the **same directory** as the CUE file (the `ffcuesplitter` `-o .` flag).
- The script does not clean up the original single-file rip after splitting.
- If `ffcuesplitter` is not on `PATH`, the script will raise a `FileNotFoundError` when attempting to split.

## Related Scripts

- [vgmdb-cuefixer](vgmdb-cuefixer.md) — Fix CUE `FILE` directives before splitting
- [beets-cuemaker](beets-cuemaker.md) — Generate CUE sheets for rips that don't have one