Add "Explicit" in line on file name

[VaporyCoder]

I think it would be a nice feature to add that when you download the explicit album/track, the track/album would add "[Explicit]" in the title since navidrome can pick up on that name distinction and tag it as such. Just a thought. I know there isnt an Explicit audio tag so putting it in the file/folder name would be nice.

[VaporyCoder]

Example:
"/Music/Artist/Album 1 [Explicit]/Track 1, Track 2, Track 3,"
or if possible
"/Music/Artist/Album 1 [Explicit]/Track 1, Track 2 [Explicit], Track 3,"

[cstaelen]

Hi @VaporyCoder

Thanks for submitting 👍

Path templating is part of Tiddl perimeter.
You should request the feature on the project itself.

[VaporyCoder]

So i looked further into it and adding explicit to the file name would not make navidrome read it as explicit but rather if the audio file tag "ITUNESADVISORY" with a value of "0" (clean) or "1" (explicit). Is there maybe way to add that function into beets you think? If song is explicit on tidal then add custom tag "ITUNESADVISORY" with a value of "1" otherwise make it "0"

[cstaelen]

I don't know how to do that now.
I will investigate but I haven't enough time those days. It could take a while.

If you manage to make it work, please share ! Or maybe someone in the community

[VaporyCoder]

I got it working by writing a custom post script. I set the tidarr to add "explicit" in line on the file name and then utilized beets and mutagen to automatically process files and read which ones have the word "explicit" in them and tag them as such otherwise tag them as not explicit. This is nice cause when I use Feishin, it can read the tag and make things just look more official and add the E to song names :D

[cstaelen]

Glad you have it working 🙌

Could you please share your script ?
It would be great to have some ready-to-use scripts in the wiki !

[VaporyCoder]

Tidarr Post Script Tagging: ITUNESADVISORY + RELEASETYPE (album/ep/single)

This guide adds two automatic metadata tags to music downloaded via Tidarr using Tidarr's custom post-processing script hook.

What this does

1) Explicit advisory

• Sets ITUNESADVISORY = 1 if the filename contains an explicit marker (examples: - explicit, - E, (E), [E])
• Sets ITUNESADVISORY = 0 otherwise

2) Release type

• Sets RELEASETYPE = album | ep | single based on TIDAL album metadata
• Release type is resolved from tiddl’s local API cache (/shared/.tiddl/api_cache.sqlite) so no additional API calls are required.

---

Requirements

• Tidarr container with a writable /shared volume.
• Python available in the container.
• mutagen available in the container (commonly already present in Tidarr images).
• Album folder naming ends with [{album_id}] so the post script can extract the ID.

---

Recommended Docker Compose settings

These settings help avoid root-owned 755 folders and ensure group-writable library output.

Important

• Use PGID, not GUID.
• Use UMASK=0002 so files default to 664 and folders to 775.

services:
  tidarr:
    image: cstaelen/tidarr
    container_name: tidarr
    environment:
      - PUID={set your value here}            # e.g. 999
      - PGID={set your value here}            # e.g. 10
      - UMASK=0002
      - NAVIDROME_URL={set your value here}
      - NAVIDROME_USER={set your value here}
      - NAVIDROME_PASSWORD={set your value here}
    volumes:
      - {set your host tidarr config path here}:/shared
      - {set your host music library path here}:/music
    ports:
      - "{set your port here}:8484"
    restart: unless-stopped

---

Files you need (place in /shared)

Put these files in your Tidarr config folder (the one mounted to /shared in the container):

• /shared/custom-post-script.sh
• /shared/set_itunesadvisory_from_filename.py
• /shared/get_releasetype_from_cache.py

Then mark them executable:

chmod +x /shared/custom-post-script.sh
chmod +x /shared/set_itunesadvisory_from_filename.py
chmod +x /shared/get_releasetype_from_cache.py

Script changes do not require a container restart; they are read/executed at post-processing time.

---

1) custom-post-script.sh

This post script:

• reads Tidarr env vars: DESTINATION_PATH and FOLDERS_MOVED
• extracts the album ID from the moved folder name (the trailing [123456789])
• resolves releasetype from the tiddl cache
• calls the tagger script with:
  • arg1 = moved folder path
  • arg2 = album|ep|single (may be empty if not found)

Create /shared/custom-post-script.sh:

#!/bin/sh
set -eu

TAGGER="/shared/set_itunesadvisory_from_filename.py"

echo "[custom-post] VERSION={set your version string here}"
echo "[custom-post] DESTINATION_PATH=${DESTINATION_PATH:-}"
echo "[custom-post] FOLDERS_MOVED=${FOLDERS_MOVED:-}"
echo "[custom-post] ITEM_TYPE=${ITEM_TYPE:-}"
echo "[custom-post] ITEM_URL=${ITEM_URL:-}"

process_path() {
  p="$1"
  rt="${2:-}"
  [ -e "$p" ] || { echo "[custom-post] missing path: $p"; return 0; }

  if [ -f "$TAGGER" ]; then
    python3 "$TAGGER" "$p" "$rt" || true
  else
    echo "[custom-post] tagger not found at $TAGGER"
  fi
}

if [ -n "${FOLDERS_MOVED:-}" ] && [ -n "${DESTINATION_PATH:-}" ]; then
  IFS=','

  for rel in $FOLDERS_MOVED; do
    # Safe trim (does not interpret quotes)
    rel="$(printf '%s' "$rel" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')"
    [ -n "$rel" ] || continue

    full="${DESTINATION_PATH}/${rel}"
    echo "[custom-post] processing: $full"

    # Extract trailing [123456789] album id
    album_id="$(printf '%s' "$full" | sed -n 's/.*\[\([0-9][0-9]*\)\]$/\1/p')"

    # Resolve release type from tiddl cache (album/ep/single)
    releasetype="$(python3 /shared/get_releasetype_from_cache.py "$album_id" 2>/dev/null || true)"
    echo "[custom-post] releasetype=${releasetype:-unknown} album_id=${album_id:-none}"

    process_path "$full" "$releasetype"
  done
else
  echo "[custom-post] FOLDERS_MOVED/DESTINATION_PATH not set; falling back to /music"
  process_path "/music" ""
fi

echo "[custom-post] done"

---

2) set_itunesadvisory_from_filename.py

This script:

• walks all supported audio files in the provided folder/file
• sets ITUNESADVISORY based on filename markers
• sets RELEASETYPE if provided as argument 2 (album|ep|single)
• logs to /shared/beets-hook.log for debugging

Create /shared/set_itunesadvisory_from_filename.py:

#!/usr/bin/env python3
import os
import sys

from mutagen.flac import FLAC
from mutagen.id3 import ID3, TXXX
from mutagen.mp4 import MP4

AUDIO_EXTS = {".flac", ".mp3", ".m4a", ".mp4"}
LOGFILE = "/shared/beets-hook.log"

RELEASETYPE = (sys.argv[2].strip().lower() if len(sys.argv) > 2 else "")
if RELEASETYPE not in ("album", "ep", "single"):
    RELEASETYPE = ""

def log(msg: str) -> None:
    try:
        with open(LOGFILE, "a", encoding="utf-8") as f:
            f.write(msg + "\n")
    except Exception:
        pass

def advisory_value_from_filename(path: str) -> int:
    name = os.path.basename(path).lower()
    stem = os.path.splitext(name)[0].rstrip()

    # Tidarr commonly uses "- explicit"
    if "explicit" in name:
        return 1

    # Optional additional markers:
    # " - E", "(E)", "[E]"
    if stem.endswith(" - e") or stem.endswith("(e)") or stem.endswith("[e]"):
        return 1

    return 0

def set_tags(path: str, advisory: int, releasetype: str) -> None:
    ext = os.path.splitext(path)[1].lower()

    if ext == ".flac":
        tags = FLAC(path)
        tags["ITUNESADVISORY"] = [str(advisory)]
        if releasetype:
            tags["RELEASETYPE"] = [releasetype]
        tags.save()
        return

    if ext == ".mp3":
        tags = ID3(path)
        tags.delall("TXXX:ITUNESADVISORY")
        tags.add(TXXX(encoding=3, desc="ITUNESADVISORY", text=[str(advisory)]))

        if releasetype:
            tags.delall("TXXX:RELEASETYPE")
            tags.add(TXXX(encoding=3, desc="RELEASETYPE", text=[releasetype]))

        tags.save(v2_version=3)
        return

    if ext in (".m4a", ".mp4"):
        tags = MP4(path)
        tags["rtng"] = [advisory]  # 0=clean/none, 1=explicit
        tags["----:com.apple.iTunes:ITUNESADVISORY"] = [str(advisory).encode("utf-8")]

        if releasetype:
            tags["----:com.apple.iTunes:RELEASETYPE"] = [releasetype.encode("utf-8")]

        tags.save()
        return

def walk_targets(root: str):
    if os.path.isfile(root):
        yield root
        return
    for r, _, files in os.walk(root):
        for f in files:
            if os.path.splitext(f)[1].lower() in AUDIO_EXTS:
                yield os.path.join(r, f)

def main():
    target = sys.argv[1] if len(sys.argv) > 1 else "."
    changed = 0

    for f in walk_targets(target):
        advisory = advisory_value_from_filename(f)
        try:
            set_tags(f, advisory, RELEASETYPE)
            changed += 1
            msg = f"[beets-hook] ITUNESADVISORY={advisory} RELEASETYPE={RELEASETYPE or 'n/a'} -> {f}"
            print(msg)
            log(msg)
        except Exception as e:
            err = f"[beets-hook] FAILED {f}: {e}"
            print(err, file=sys.stderr)
            log(err)

    done = f"[beets-hook] done. processed {changed} file(s)."
    print(done)
    log(done)
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

---

3) get_releasetype_from_cache.py

tiddl stores API responses in /shared/.tiddl/api_cache.sqlite as Python pickles.
This script:

• scans cached responses,
• unpickles each response,
• searches embedded JSON payloads for ALBUM|EP|SINGLE,
• and writes a small local mapping cache to /shared/.tiddl/releasetype_cache.json for speed.

Create /shared/get_releasetype_from_cache.py:

#!/usr/bin/env python3
import json
import os
import pickle
import re
import sqlite3
import sys
from typing import Any, Optional

DB = "/shared/.tiddl/api_cache.sqlite"
CACHE_FILE = "/shared/.tiddl/releasetype_cache.json"

VALID = {"ALBUM": "album", "EP": "ep", "SINGLE": "single"}

def load_local_cache() -> dict:
    try:
        with open(CACHE_FILE, "r", encoding="utf-8") as f:
            return json.load(f)
    except Exception:
        return {}

def save_local_cache(d: dict) -> None:
    try:
        tmp = CACHE_FILE + ".tmp"
        with open(tmp, "w", encoding="utf-8") as f:
            json.dump(d, f, ensure_ascii=False, indent=2)
        os.replace(tmp, CACHE_FILE)
    except Exception:
        pass

def find_release(obj: Any) -> Optional[str]:
    if isinstance(obj, dict):
        for k, v in obj.items():
            lk = str(k).lower()
            if lk in ("release", "releasetype", "albumtype", "type"):
                if isinstance(v, str) and v.upper() in VALID:
                    return v.upper()
            r = find_release(v)
            if r:
                return r
    elif isinstance(obj, list):
        for it in obj:
            r = find_release(it)
            if r:
                return r
    return None

def looks_like_json(s: str) -> bool:
    s = s.lstrip()
    return s.startswith("{") or s.startswith("[")

def extract_json_strings(x: Any):
    if isinstance(x, dict):
        for v in x.values():
            yield from extract_json_strings(v)
    elif isinstance(x, (list, tuple, set)):
        for it in x:
            yield from extract_json_strings(it)
    elif isinstance(x, (bytes, bytearray)):
        try:
            s = x.decode("utf-8", "ignore")
        except Exception:
            return
        if looks_like_json(s):
            yield s
    elif isinstance(x, str):
        if looks_like_json(x):
            yield x

def object_contains_id(x: Any, album_id: str) -> bool:
    if isinstance(x, dict):
        return any(object_contains_id(v, album_id) for v in x.values()) or any(album_id in str(k) for k in x.keys())
    if isinstance(x, (list, tuple, set)):
        return any(object_contains_id(v, album_id) for v in x)
    if isinstance(x, (bytes, bytearray)):
        try:
            return album_id.encode() in x
        except Exception:
            return False
    if isinstance(x, str):
        return album_id in x
    return False

def main():
    if len(sys.argv) < 2:
        print("")
        return 0

    album_id = sys.argv[1].strip()
    if not re.fullmatch(r"\d+", album_id):
        print("")
        return 0

    local = load_local_cache()
    if album_id in local:
        print(local[album_id])
        return 0

    con = sqlite3.connect(DB)
    cur = con.cursor()

    for _key, blob in cur.execute("SELECT key, value FROM responses"):
        if not blob:
            continue
        b = blob if isinstance(blob, (bytes, bytearray)) else bytes(blob)
        try:
            obj = pickle.loads(b)
        except Exception:
            continue

        if not object_contains_id(obj, album_id):
            continue

        # Prefer JSON blobs containing the album id
        for s in extract_json_strings(obj):
            if album_id not in s:
                continue
            try:
                j = json.loads(s)
            except Exception:
                continue
            rt = find_release(j)
            if rt and rt in VALID:
                out = VALID[rt]
                local[album_id] = out
                save_local_cache(local)
                print(out)
                return 0

        # Fallback: any JSON blob in the object
        for s in extract_json_strings(obj):
            try:
                j = json.loads(s)
            except Exception:
                continue
            rt = find_release(j)
            if rt and rt in VALID:
                out = VALID[rt]
                local[album_id] = out
                save_local_cache(local)
                print(out)
                return 0

    print("")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

---

Verify

Check Tidarr logs

You should see lines like:

• [custom-post] releasetype=single album_id=400403507
• [beets-hook] ITUNESADVISORY=1 RELEASETYPE=single -> ...

Check tags on a FLAC track (inside container)

python3 -c 'from mutagen.flac import FLAC; t=FLAC("{set your file path here}"); print(t.get("ITUNESADVISORY"), t.get("RELEASETYPE"))'

Expected:

• ITUNESADVISORY: ["0"] or ["1"]
• RELEASETYPE: ["album"] / ["ep"] / ["single"]

Debug log file

The tagger also writes to:

• /shared/beets-hook.log

---

Notes / Differences by user

• {set your host tidarr config path here} is typically something like:
  • /volume1/docker/tidarr/config
• {set your host music library path here} is typically something like:
  • /volume1/Plex/Music
• Folder naming must end in [{album_id}] for album id extraction to work.
  If your naming differs, update the sed line in custom-post-script.sh.

---

Performance

get_releasetype_from_cache.py scans tiddl’s cache the first time it sees a new album id, then stores results in:

• /shared/.tiddl/releasetype_cache.json

Future lookups are instant.

Edit: Cleaned up instruction and added "releasetype" tagging for a cleaner artist discography

[cstaelen]

Thank you so much for your custom script, I added it in the wiki :)

I close the discussion but feel free to open a new one if needed