mirror of
https://github.com/oskvr37/tiddl.git
synced 2026-06-13 12:15:13 +03:00
Oskar Dudziński
152 lines
6.6 KiB
Markdown
152 lines
6.6 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 | Type |
|
|
| ---------------------------- | -------------------------------------- | ------------------------------- | ---- |
|
|
| `item.id` | Track/Video ID | `123456` | int |
|
|
| `item.title` | Title | `Harder Better Faster Stronger` | str |
|
|
| `item.title_version` | Title + version (if present) | `One More Time (Radio Edit)` | str |
|
|
| `item.number` | Track number | `3` | int |
|
|
| `item.volume` | Disc/volume number | `1` | int |
|
|
| `item.version` | Version string (track only) | `Remastered` | str |
|
|
| `item.copyright` | Copyright info (track only) | `© 2023 Sony Music` | str |
|
|
| `item.bpm` | Beats per minute (if available) | `120` | int |
|
|
| `item.isrc` | ISRC code (track only) | `USQX91501234` | str |
|
|
| `item.quality` | Audio/video quality | `HIGH` | str |
|
|
| `item.artist` | Primary artist name | `Daft Punk` | str |
|
|
| `item.artists` | All main artists | `Daft Punk, Pharrell Williams` | str |
|
|
| `item.features` | Featured artists | `Pharrell Williams` | str |
|
|
| `item.artists_with_features` | Main + featured artists | `Daft Punk, Pharrell Williams` | str |
|
|
| `item.explicit` | Explicit content | `E` | str |
|
|
| `item.dolby:(Dolby Atmos)` | Dolby Atmos (track only, `UserFormat`) | `(Dolby Atmos)` | str |
|
|
|
|
---
|
|
|
|
### `album`
|
|
|
|
| Field | Description | Example | Type |
|
|
| -------------------- | ----------------------------------- | ----------------- | -------- |
|
|
| `album.id` | Album ID | `98765` | int |
|
|
| `album.title` | Album title | `Discovery` | str |
|
|
| `album.artist` | Primary artist | `Daft Punk` | str |
|
|
| `album.artists` | All main artists | `Daft Punk` | str |
|
|
| `album.date` | Release date | `2001-03-13` | datetime |
|
|
| `album.explicit` | Explicit content | `clean` | str |
|
|
| `album.master:[MAX]` | Is album max quality (`UserFormat`) | `[MAX]` | str |
|
|
| `album.release` | Release type | `ALBUM/EP/SINGLE` | str |
|
|
|
|
---
|
|
|
|
### `playlist`
|
|
|
|
| Field | Description | Example | Type |
|
|
| ------------------ | ------------------------------ | --------------------- | -------- |
|
|
| `playlist.uuid` | Playlist unique ID | `b8f1d9f8-...` | str |
|
|
| `playlist.title` | Playlist name | `My Favorites` | str |
|
|
| `playlist.index` | Track index within playlist | `5` | int |
|
|
| `playlist.created` | Creation date (`datetime`) | `2024-01-15 10:42:00` | datetime |
|
|
| `playlist.updated` | Last updated date (`datetime`) | `2024-03-02 09:00:00` | datetime |
|
|
|
|
> [!NOTE]
|
|
> Tidal API does not provide full album data for playlist tracks,
|
|
> if you are downloading a playlist with template that contains `{album...}`,
|
|
> then `tiddl` is making additional request to the API to fetch album data for a track.
|
|
> The download may take a little longer but it's not a big deal - just one more request for every playlist track.
|
|
> If there are multiple tracks from the same album, then the album data is cached locally,
|
|
> and there is only one request per album. Related issue: #217
|
|
|
|
---
|
|
|
|
### Explicit
|
|
|
|
| Format | True Value | False Value |
|
|
| ---------------- | ---------- | ----------- |
|
|
| `.explicit` | E | |
|
|
| `.explicit:long` | explicit | |
|
|
| `.explicit:full` | explicit | clean |
|
|
|
|
### User Format
|
|
|
|
You can format `UserFormat` fields how you want:
|
|
|
|
| Format | True Value | False Value |
|
|
| ---------------------------- | ------------- | ----------- |
|
|
| `item.dolby:D` | D | |
|
|
| `item.dolby:DOLBY` | DOLBY | |
|
|
| `item.dolby:dolby` | dolby | |
|
|
| `album.master:(Max Quality)` | [Max Quality] | |
|
|
|
|
### `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.
|
|
- You can format string and integer fields, [learn more](https://www.pythonmorsels.com/string-formatting/#floating-point-numbers-and-integers)
|
|
|
|
## 🖥️ Source Code
|
|
|
|
Source code is located at [`/tiddl/core/utils/format.py`](/tiddl/core/utils/format.py)
|