---
name: track-tag
description: Auto-fill MP3/M4A/FLAC ID3 metadata using Shazam (via shazamio). Detects the song from each file, then writes title, artist, album, year, genre, track number, and embeds high-res cover art. Folder-aware: tags every audio file in a directory in one pass. Skip already-tagged files with --skip-tagged. Use when the user has a folder of untagged audio dumps, asks to "tag these mp3s", "fill in metadata", "add cover art to these tracks", "fix my music library", or wants to clean up a rip/dump folder for Apple Music/Spotify uploads.
---


# track-tag

Untagged audio dump → fully tagged library with cover art. No manual data entry.

## Single file

```bash
python3 ~/.claude/skills/track-tag/scripts/tag.py --input track.mp3
# → writes ID3v2 tags + embedded cover, in-place
```

## Whole folder

```bash
python3 ~/.claude/skills/track-tag/scripts/tag.py --input ~/music_dump --recursive
# tags every mp3/m4a/flac/wav, in-place
```

## Skip already-tagged files

```bash
python3 ~/.claude/skills/track-tag/scripts/tag.py --input ~/library --recursive --skip-tagged
# only touches files where title or artist is missing
```

## Don't write — just preview

```bash
python3 ~/.claude/skills/track-tag/scripts/tag.py --input track.mp3 --dry-run
# prints what would be written, doesn't modify the file
```

## What gets tagged

- **Title** (TIT2)
- **Artist** (TPE1)
- **Album** (TALB)
- **Album artist** (TPE2)
- **Year** (TDRC)
- **Genre** (TCON)
- **Track number** (TRCK)
- **Cover art** (APIC, embedded as JPEG)
- **Comment** (TXXX:source) — `Shazam:<track_id>` so you can tell what's auto-tagged later

Works for `.mp3`, `.m4a`, `.aac`, `.flac`, `.ogg`, `.wav` (LIST chunk only — limited).

## Flags

- `--input` — file or folder
- `--recursive` — descend into subfolders
- `--skip-tagged` — skip files that already have title + artist
- `--dry-run` — print, don't write
- `--no-cover` — skip embedded cover art
- `--cover-size` — `400` (default) or `1400` for hi-res
- `--rename` — also rename file to `{artist} - {title}.{ext}`
- `--threads` — parallel file workers (default 3 — Shazam rate-limits)

## First-run install

Auto-installs `shazamio`, `mutagen`, `requests`. ffmpeg expected on PATH for non-mp3 fallback.

## Pairs well with

- `shazam-clip` — same engine; track-tag uses it under the hood for batch
- `sample-pack` — tag your sample sources before building a pack
- `loudness-fix` — tag, then master, then upload