From 02919e38e6549c83fad2efe1c4ddb0cc9c9055a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oskar=20Dudzi=C5=84ski?= <56404247+oskvr37@users.noreply.github.com> Date: Mon, 17 Nov 2025 14:40:28 +0100 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Added=20`{album.master}`=20template?= =?UTF-8?q?=20(#225)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * add `MediaMetadataTags` literal * add `album.master` template * add docs --- docs/templating.md | 68 +++++++++++++++--------------- tiddl/core/api/models/resources.py | 6 ++- tiddl/core/utils/format.py | 10 +++-- 3 files changed, 45 insertions(+), 39 deletions(-) diff --git a/docs/templating.md b/docs/templating.md index 0751353..3345e7a 100644 --- a/docs/templating.md +++ b/docs/templating.md @@ -28,37 +28,38 @@ 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` | -| `item.explicit` | Explicit content | `E` | -| `item.dolby:(Dolby Atmos)` | Dolby Atmos (track only) | `(Dolby Atmos)` | +| 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` | +| `item.explicit` | Explicit content | `E` | +| `item.dolby:(Dolby Atmos)` | Dolby Atmos (track only, `UserFormat`) | `(Dolby Atmos)` | --- ### `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` | -| `album.explicit` | Explicit content | `clean` | +| 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` | +| `album.explicit` | Explicit content | `clean` | +| `album.master:[MAX]` | Is album max quality (`UserFormat`) | `[MAX]` | --- @@ -82,15 +83,16 @@ Each object type exposes fields you can use inside templates. | `.explicit:long` | explicit | | | `.explicit:full` | explicit | clean | -### Dolby Atmos +### User Format -Dolby Atmos is only available in tracks. Format it like this: `item.dolby:`. +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 | | +| 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 diff --git a/tiddl/core/api/models/resources.py b/tiddl/core/api/models/resources.py index 1e7aff1..5a45f89 100644 --- a/tiddl/core/api/models/resources.py +++ b/tiddl/core/api/models/resources.py @@ -7,6 +7,8 @@ TrackQuality = Literal["LOW", "HIGH", "LOSSLESS", "HI_RES_LOSSLESS"] # audio_only is not stable VideoQuality = Literal["AUDIO_ONLY", "LOW", "MEDIUM", "HIGH"] +MediaMetadataTags = Literal["LOSSLESS", "HIRES_LOSSLESS", "DOLBY_ATMOS"] + class Track(BaseModel): @@ -24,7 +26,7 @@ class Track(BaseModel): videoCover: Optional[str] = None class MediaMetadata(BaseModel): - tags: list[str] + tags: list[MediaMetadataTags] id: int title: str @@ -107,7 +109,7 @@ class Album(BaseModel): picture: Optional[str] = None class MediaMetadata(BaseModel): - tags: List[Literal["LOSSLESS", "HIRES_LOSSLESS", "DOLBY_ATMOS"]] + tags: List[MediaMetadataTags] id: int title: str diff --git a/tiddl/core/utils/format.py b/tiddl/core/utils/format.py index 6ee08eb..0c5d557 100644 --- a/tiddl/core/utils/format.py +++ b/tiddl/core/utils/format.py @@ -35,7 +35,7 @@ class Explicit: return base -class DolbyAtmos: +class UserFormat: def __init__(self, value: bool) -> None: self.value = value @@ -51,6 +51,7 @@ class AlbumTemplate: artists: str date: datetime explicit: Explicit + master: UserFormat @dataclass(slots=True) @@ -70,7 +71,7 @@ class ItemTemplate: features: str artists_with_features: str explicit: Explicit - dolby: DolbyAtmos + dolby: UserFormat @dataclass(slots=True) @@ -105,13 +106,13 @@ def generate_template_data( copyright_ = item.copyright or "" bpm = item.bpm or 0 isrc = item.isrc or "" - dolby = DolbyAtmos("DOLBY_ATMOS" in item.mediaMetadata.tags) + dolby = UserFormat("DOLBY_ATMOS" in item.mediaMetadata.tags) else: # Video version = "" copyright_ = "" bpm = 0 isrc = "" - dolby = DolbyAtmos(False) + dolby = UserFormat(False) item_template = ItemTemplate( id=item.id, @@ -143,6 +144,7 @@ def generate_template_data( ), date=album.releaseDate, explicit=Explicit(getattr(album, "explicit", None)), + master=UserFormat("HIRES_LOSSLESS" in album.mediaMetadata.tags), ) playlist_template = None