✨ tiddl3 (#194)

2026-06-13 04:05:08 +03:00 · 2025-11-08 15:18:44 +01:00
parent c255d42283
commit b87888536e
80 changed files with 4029 additions and 2204 deletions
@@ -0,0 +1,118 @@
+# 📝 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)