---
name: Tag Album
description: Rename track files and set ID3 tags based on album-info.md metadata.
version: 1
mode: agentic
triggers:
  - type: directory
inputs:
  artist_name:
    type: string
    description: Artist name
    autofill: entry_name
  album_name:
    type: string
    description: Album name
    autofill: entry_name
---

# Tag Album

You are given an artist name and album name. Your job is to rename audio files and set proper ID3 tags using the metadata from `album-info.md` in the target directory.

## Prerequisites

The target directory (from Context) must contain:
- Audio files (`.mp3`)
- An `album-info.md` file (produced by the fetch-album-info task)
- Optionally a cover image (`cover.jpg`, `cover.png`, `front.jpg`, or similar)

If `album-info.md` does not exist, stop and report that the album info must be fetched first.

## Process

### 1. Read album-info.md

Parse the `album-info.md` file to extract:
- **Artist** (canonical name from the metadata table)
- **Album** title (canonical name from the metadata table)
- **Year** (from the metadata table)
- **Genre** (from the metadata table)
- **Tracklist** — track numbers, titles, and disc numbers (if multi-disc)

### 2. Inventory existing files

List all `.mp3` files in the target directory (and `Disc N/` subdirectories for multi-disc albums).

Match each existing file to a track in the tracklist. Use track number, partial title match, or positional order to establish the mapping. If the album has multiple discs, match within each `Disc N/` subdirectory.

### 3. Rename files

Rename each audio file to the standardized format:

```
NNN - Track Title.mp3
```

Where:
- `NNN` is the track number zero-padded to 3 digits (e.g. `001`, `012`)
- `Track Title` is the canonical title from `album-info.md`

**Filename safety rules** — these characters are illegal on Windows and must be replaced:
- `:` → ` -` (space dash)
- `?` → removed
- `"` → removed
- `*`, `<`, `>`, `|`, `\`, `/` → removed

Use `mv` to rename. Work within each disc subdirectory if the album is multi-disc.

### 4. Set ID3 tags

Use the `mutagen` tool to write tags on each track. Required tags:

| Tag | Value |
|-----|-------|
| TIT2 | Track title (from tracklist, NO track number prefix) |
| TPE1 | Artist name (use the `artist_name` input exactly as provided) |
| TPE2 | Same as TPE1 |
| TALB | Album title |
| TRCK | `track/total` (e.g. `3/12`) |
| TDRC | Release year (4-digit) |
| TCON | Genre(s) from album-info |

For multi-disc albums, also set:
| TPOS | `disc/total` (e.g. `1/2`) |

Use the `mutagen` tool's `write` action. Example:

```
mutagen write --path "001 - Track Name.mp3" --tags '{"TIT2": "Track Name", "TPE1": "Artist", "TPE2": "Artist", "TALB": "Album", "TRCK": "1/12", "TDRC": "1967", "TCON": "Rock"}'
```

### 5. Embed cover art

If a cover image exists in the target directory (check for `cover.jpg`, `cover.png`, `front.jpg`, `Front.jpg`, `Cover/Cover.jpg`, or any image file that looks like album art), embed it into every track using the `mutagen` tool's `embed_cover` action:

```
mutagen embed_cover --path "001 - Track Name.mp3" --image "cover.jpg"
```

### 6. Verify

After all files are renamed and tagged, read back the tags of the first and last track using `mutagen read` to confirm the tags were written correctly. Report a summary of what was done:
- Number of tracks processed
- Any files that could not be matched or tagged
- Whether cover art was embedded

## Important

- Always read `album-info.md` as the source of truth for metadata — do NOT use web search.
- Do NOT modify the audio content, only metadata and filenames.
- Preserve disc subdirectory structure for multi-disc albums.
- If a track file cannot be matched to a tracklist entry, skip it and report it.
- Track titles in TIT2 must NOT include track numbers (e.g. "Song Name", not "01 - Song Name").
- Use the `artist_name` input parameter exactly as provided for TPE1 and TPE2 — do NOT reformat it or use the artist name from `album-info.md`. The user organizes their library alphabetically by this value.
- Use the canonical album title from `album-info.md` for TALB.
