mirror of
https://github.com/oskvr37/tiddl.git
synced 2026-06-13 04:05:08 +03:00
Oskar Dudziński
119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
# 📝 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)
|