# 📝 File Templating

Templates are text strings that describe folder and file structure.
They use placeholders (in `{curly_braces}`) that get replaced with actual metadata values from:

- **Track / Video** → `item`
- **Album** → `album`
- **Playlist** → `playlist`
- Plus any **custom fields**

A template like:

```
{album.artist}/{album.title}/{item.title}
```

becomes this:

```
Daft Punk/Discovery/Harder Better Faster Stronger
```

---

## 🧩 Template Variables

Each object type exposes fields you can use inside templates.

### `item` (Track or Video)

| Field                        | Description                     | Example                         |
| ---------------------------- | ------------------------------- | ------------------------------- |
| `item.id`                    | Track/Video ID                  | `123456`                        |
| `item.title`                 | Title                           | `Harder Better Faster Stronger` |
| `item.title_version`         | Title + version (if present)    | `One More Time (Radio Edit)`    |
| `item.number`                | Track number                    | `3`                             |
| `item.volume`                | Disc/volume number              | `1`                             |
| `item.version`               | Version string (track only)     | `Remastered`                    |
| `item.copyright`             | Copyright info (track only)     | `© 2023 Sony Music`             |
| `item.bpm`                   | Beats per minute (if available) | `120`                           |
| `item.isrc`                  | ISRC code (track only)          | `USQX91501234`                  |
| `item.quality`               | Audio/video quality             | `HIGH`                          |
| `item.artist`                | Primary artist name             | `Daft Punk`                     |
| `item.artists`               | All main artists                | `Daft Punk, Pharrell Williams`  |
| `item.features`              | Featured artists                | `Pharrell Williams`             |
| `item.artists_with_features` | Main + featured artists         | `Daft Punk, Pharrell Williams`  |

---

### `album`

| Field           | Description               | Example      |
| --------------- | ------------------------- | ------------ |
| `album.id`      | Album ID                  | `98765`      |
| `album.title`   | Album title               | `Discovery`  |
| `album.artist`  | Primary artist            | `Daft Punk`  |
| `album.artists` | All main artists          | `Daft Punk`  |
| `album.date`    | Release date (`datetime`) | `2001-03-13` |

---

### `playlist`

| Field              | Description                    | Example               |
| ------------------ | ------------------------------ | --------------------- |
| `playlist.uuid`    | Playlist unique ID             | `b8f1d9f8-...`        |
| `playlist.title`   | Playlist name                  | `My Favorites`        |
| `playlist.index`   | Track index within playlist    | `5`                   |
| `playlist.created` | Creation date (`datetime`)     | `2024-01-15 10:42:00` |
| `playlist.updated` | Last updated date (`datetime`) | `2024-03-02 09:00:00` |

---

### `extra` and `custom` fields

You can also use:

- `now` → current datetime
- Any key passed as `extra` in code.

---

## 🧼 Sanitization

All template segments are sanitized:

- Invalid filesystem characters are removed or replaced.
- Empty placeholders are skipped cleanly.
- Each path component is treated separately (split by `/`).

---

## ⚙️ Configuration Example

Your `[templates]` section in `config.toml` defines templates per media type.

```toml
[templates]
default = "{album.artist}/{album.title}/{item.title}"
track = "tracks/{item.id}"
video = "videos/{item.title}"
album = "artists/{album.artist}/{album.title}/{item.title}"
playlist = "{playlist.title}/{playlist.index}. {item.artist} - {item.title}"
mix = "mixes/{mix_id}/{item.artist} - {item.title}"
```

If no specific template is set, the `default` one is used.

---

## 🧠 Tips

- You can format datetime fields, e.g. `{album.date:%Y-%m-%d}`.
- You can build nested folders safely using `/` separators.

## 🖥️ Source Code

Source code is located at [`/tiddl/core/utils/format.py`](/tiddl/core/utils/format.py)