# Music File Renamer

Build a safe rename and folder-move plan for music files from pasted tag dumps, templates, and filesystem rules.

## Run it

- **CLI:** `gizza tool music-file-renamer "file,artist,album,track,title
track01.mp3,Tame Impala,Currents,1,Let It Happen
track02.mp3,Tame Impala,Currents,2,Nangs"`
- **Web:** https://gizza.ai/tools/music-file-renamer/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/music-file-renamer/tool.json

## Inputs

- `tracks` — Music tag dump _(field)_
- `input_format` — Input format _(field)_
- `pattern` — Target path pattern _(field)_
- `base_dir` — Destination root _(field)_
- `track_padding` — Track number padding _(field)_
- `on_missing` — Missing tag behavior _(field)_
- `unknown_text` — Missing tag placeholder _(field)_
- `charset` — Filename safety _(field)_
- `replace_char` — Illegal character replacement _(field)_
- `space_style` — Spaces _(field)_
- `case_style` — Case style _(field)_
- `max_component` — Max component length _(field)_
- `keep_extension` — Keep current extension _(field)_
- `format` — Output format _(field)_

## Output

- Rename plan (text)

## Query parameters

Open the tool pre-filled and auto-run via URL:

- `tracks` — Music tag dump
- `input_format` — Input format
- `pattern` — Target path pattern
- `base_dir` — Destination root
- `track_padding` — Track number padding
- `on_missing` — Missing tag behavior
- `unknown_text` — Missing tag placeholder
- `charset` — Filename safety
- `replace_char` — Illegal character replacement
- `space_style` — Spaces
- `case_style` — Case style
- `max_component` — Max component length
- `keep_extension` — Keep current extension
- `format` — Output format

Example: `https://gizza.ai/tools/music-file-renamer/?tracks=file%2Cartist%2Calbum%2Ctrack%2Ctitle%0Atrack01.mp3%2CTame%20Impala%2CCurrents%2C1%2CLet%20It%20Happen%0Atrack02.mp3%2CTame%20Impala%2CCurrents%2C2%2CNangs&input_format=auto&pattern=%7Bartist%7D%2F%7Balbum%7D%2F%7Btrack%7D%20%7Btitle%7D&base_dir=%2FMusic%2FLibrary&track_padding=2&on_missing=unknown&unknown_text=Unknown&charset=windows&replace_char=_&space_style=keep&case_style=keep&max_component=100&keep_extension=true&format=table`

---

## About this tool

Music File Renamer turns exported audio metadata into a rename and folder-move plan. Paste rows from a tag editor, `ffprobe`, `exiftool`, or a music-library script; choose a pattern such as `{artist}/{album}/{track} {title}`; then review every proposed `current -> new` path before doing anything on disk.

The tool is preview-only. It does not read folders, upload tracks, rewrite tags, or move files. That makes it safe for planning a cleanup, sharing a proposed library layout, or generating a shell script you can inspect before running locally.

## Input formats

CSV and TSV inputs need a header row. JSON inputs can be an array of objects, a single object, or a wrapper such as `{ "tracks": [...] }` or an `ffprobe`-style `{ "format": { "filename": "...", "tags": { ... } } }` object. Key/value inputs accept blank-line-separated blocks such as `filename=track01.mp3` and `TAG:artist=Tame Impala`.

Common field names are normalized: `file`, `filename`, `path`, and `SourceFile` all identify the current path; `album artist`, `albumartist`, `TPE2`, and `band` map to `{albumartist}`. Unknown columns are still available as tokens after normalizing their names, so an `ISRC` column can be used as `{isrc}`.

## Worked example

Input:

```csv
file,artist,album,track,title
track01.mp3,Tame Impala,Currents,1,Let It Happen
track02.mp3,Tame Impala,Currents,2,Nangs
```

Pattern:

```text
{artist}/{album}/{track} {title}
```

Output:

```text
2 tracks, 2 renames, 0 unchanged, 0 collisions, 0 skipped

track01.mp3  ->  Tame Impala/Currents/01 Let It Happen.mp3
track02.mp3  ->  Tame Impala/Currents/02 Nangs.mp3
```

## Pattern tokens and safety options

Use `{token}` to insert a tag value and `{albumartist|artist|Unknown}` to try fallbacks from left to right. Slash characters in the pattern create folders. `{track}` is normalized and zero-padded with the `track_padding` setting; `{year}` takes the first four-digit year from date-like fields.

`charset=windows` is the default because it is safe across Windows, macOS, Linux, NTFS, exFAT, and most sync tools. `charset=unix` only removes path separators and NUL-like characters. `charset=ascii` also folds common accented Latin characters before sanitizing. Collisions are detected case-insitively so a plan that would create the same destination twice is flagged before you move anything.

## Output formats

`table` is easiest to review in the browser. `list` is compact for notes. `csv` works well for spreadsheets. `json` is the machine-readable form for scripts. `sh` emits a conservative `/bin/sh` plan with `mkdir -p` and `mv -n`; review it before running and execute it from the folder that contains the current paths.

## Limits and edge cases

- The maximum batch size is 5000 records per run; 5001 records returns an error instead of trying to render an unreviewable plan.
- The tool computes paths only. It cannot inspect a music folder, fetch missing tags, fingerprint audio, or delete emptied folders.
- Missing tags follow `on_missing`: substitute `unknown_text`, skip the file, or keep its original path unchanged.
- `max_component` limits each folder or file-name component to 8-255 characters. If `keep_extension` is enabled, the extension is reattached after truncation.
- Windows reserved device names such as `CON`, `PRN`, and `LPT1` are defused when using the Windows or ASCII charset.

## FAQ

<details>
<summary>Can this rename files directly?</summary>

No. It intentionally outputs a plan only. Use the `sh` output if you want a script, review it, and run it yourself in a local shell.

</details>

<details>
<summary>How do I get the tag dump?</summary>

Export CSV/TSV from a tag editor, run `ffprobe -show_format`, run `exiftool`, or use a music metadata library to write JSON. The tool accepts all of those shapes as pasted text.

</details>

<details>
<summary>What is the difference between count, padding, and track numbers like 3/12?</summary>

`track_padding` controls how `{track}` is rendered. Values such as `3`, `03`, and `3/12` all use the first track number and can become `03` with the default two-digit padding.

</details>

<details>
<summary>Why did a file show as a collision?</summary>

Two or more records produced the same target path after token replacement, sanitizing, case handling, and extension handling. Change the pattern or include another distinguishing tag such as `{disc}` or `{filename}`.

</details>

## Related tools

- [Strip Audio Metadata](https://gizza.ai/tools/audio-metadata-stripper/): Remove ID3 tags, comments, chapters, and cover art from MP3, FLAC, OGG, M4A, WAV, and other audio files in your browser. Stream-copy audio, no upload.
- [Audio Waveform Video Generator](https://gizza.ai/tools/audio-waveform-video/): Turn audio into an animated waveform MP4 in your browser. Pick mirror, bars or wave styles, colors, gradient, size and fps. Nothing uploaded.
- [iTunes Library XML Parser](https://gizza.ai/tools/itunes-library-parser/): Parse an iTunes or Music Library.xml in your browser and export playlists and track metadata as CSV, TSV, JSON, M3U or a library summary.
- [Convert AIFF to FLAC](https://gizza.ai/tools/aiff-to-flac/): Convert AIFF or AIF audio to lossless FLAC in your browser — preserve samples and textual tags, choose FLAC compression level 0-12, and download the result.
- [Convert AIFF to WAV](https://gizza.ai/tools/aiff-to-wav/): Free AIFF to WAV converter that runs in your browser. Choose the PCM bit depth, sample rate and channel layout — at a matching depth the samples are identical.