# beets-cuemaker

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

## Purpose

Generates a `.cue` sheet file from a single-file audio rip and a plain-text track listing. Designed for creating CUE sheets for album rips sourced from VGMdb or similar databases, where track timecodes are pasted in from a track listing page.

## Requirements

### Dependencies

Python standard library only — no `pip` installs required.

```
re, os, glob  (all built-in)
```

## Input

| Item | Description | Example |
|------|-------------|---------|
| Audio file | One supported audio file in the working directory | `Artist - Album Title.flac` |
| `input.txt` | Plain-text track listing with timecodes, one track per line | See format below |

### Audio filename format

The script parses the audio filename to extract album metadata. The filename must follow the pattern:

```
Artist Name - Album Title.ext
```

If no ` - ` separator is present, the entire basename is used as the album title and the performer field is left blank.

### Supported audio extensions

`.m4a`, `.flac`, `.wav`, `.mp3`, `.aac`

### `input.txt` format

Two timecode formats are accepted and automatically normalised to `MM:SS:FF`:

```
MM:SS  Track Title
MM:SS:FF  Track Title
```

The script also handles beets-style multi-line track blocks (track number, title, and metadata on separate lines). Track 1 is always assigned index `00:00:00`.

## Output

| Item | Description |
|------|-------------|
| `<audio_basename>.cue` | CUE sheet written alongside the audio file |

The CUE file contains global `PERFORMER`, `TITLE`, and `FILE` directives, followed by numbered `TRACK` blocks each with their own `PERFORMER`, `TITLE`, and `INDEX 01` entries.

Example output structure:

```
FILE "Artist - Album Title.flac" WAVE
PERFORMER "Artist Name"
TITLE "Album Title"
  TRACK 01 AUDIO
    PERFORMER "Track Artist"
    TITLE "Track Title"
    INDEX 01 00:00:00
  TRACK 02 AUDIO
    PERFORMER "Track Artist"
    TITLE "Second Track"
    INDEX 01 03:42:00
```

## Usage

```bash
# Run from the folder containing the audio file and input.txt
python beets-cuemaker.py
```

The script uses the current working directory. Place both the audio file and `input.txt` in the same folder before running.

## Examples

```bash
# Typical workflow — cd into an album folder and run
cd "Artist - Album Title"
python /path/to/beets-cuemaker.py

# Example input.txt contents
# 00:00  Opening Theme
# 03:42  Main Theme
# 07:15  Battle Theme
```

Console output confirms the result:

```
CUE created: Artist - Album Title.cue
Detected Album Artist: Artist
Detected Album Name: Album Title
Tracks written: 12
```

## Notes

- The script picks the **first** audio file found if multiple are present — ensure only one audio file exists in the folder before running.
- Timecodes with hours (e.g. `1:23:45`) are converted: hours are rolled into minutes (`83:45:00`).
- Frames (`FF`) in the output are always `00` — sub-second precision from the input is not preserved.
- Track artist is parsed from `Artist - Title` lines in `input.txt`; if no ` - ` separator is present, the performer field is left blank for that track.
- The script has no `--dry-run` mode; it writes the CUE file immediately.

## Related Scripts

- [vgmdb-cuefixer](vgmdb-cuefixer.md) — Fix incorrect `FILE` directives in existing CUE sheets
- [vgmdb-cuesplitter](vgmdb-cuesplitter.md) — Split single-file rips into individual tracks using a CUE sheet