Output & Naming¶

This page explains where unshackle writes finished downloads and how it names them. You control naming with output templates (the filename) and folder templates (the directory the file lands in), using a set of {variable} placeholders that unshackle fills in from the media it just downloaded. It also covers muxing options, release-group tagging, Unicode filenames, and how to relocate unshackle's working directories.

If you have not configured unshackle.yaml yet, read Configuration File first. Everything below lives in that file.

How an output path is assembled¶

When a download finishes muxing, unshackle builds the final path from three pieces:

<output directory> / <folder template> / <filename template><extension>

Output directory: directories.downloads from your config, or whatever you pass to -o/--output on the command line for a single run.
Folder template: an optional per-title subfolder. TV episodes and music tracks are always placed in a folder; movies only get one if you define a movies folder template, or a single-string folder template that applies to all title kinds (see Folder templates).
Filename template: the output_template for the title kind (movie, series, or song).
Extension: chosen by the muxer: .mkv for video, .mka for audio-only, .mks for subtitle-only.

A typical episode path

/home/user/Downloads/
  └─ Show Name S01 1080p EXAMPLE WEB-DL DDP5.1 H.264/
     └─ Show.Name.S01E01.Pilot.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv

The folder name comes from the series folder template and the file from the series output template.

Two command-line flags change this layout for a single run:

Flag	Effect
`-o`, `--output`	Use this directory instead of `directories.downloads`.
`--no-folder`	Skip the per-title subfolder; write the file directly into the output directory.
`--no-source`	Omit the service source tag from both the filename and folder (the `{source}` variable resolves to empty).

Output templates¶

Filename templates live under the output_template key, keyed by title kind. Each value is a format string built from {variable} placeholders.

unshackle.yaml

output_template:
  movies: "{title}.{year}.{quality}.{source}.WEB-DL.{audio_full}.{video}-{tag}"
  series: "{title}.{season_episode}.{episode_name?}.{quality}.{source}.WEB-DL.{audio_full}.{video}-{tag}"
  songs: "{track_number}. {title}"

The recognized kinds are:

Kind	Applies to	Default when unset
`movies`	Movies	(required for movie downloads to be named, no built-in default)
`series`	TV episodes	(required for episode downloads to be named)
`songs`	Music tracks	`"{track_number}. {title}"`
`albums`	Album folders only (see below)	-

Note

movies and series have no hardcoded filename fallback. If you download those title types, define their templates. songs falls back to "{track_number}. {title}" when omitted.

Required vs. optional variables¶

{variable}: required. If it is missing from the download's context, formatting raises an error. (Note that most variables are always present in context but resolve to an empty string when not applicable, so being "present but empty" is different from "missing".)
{variable?}: optional. A trailing ? marks the variable conditional. When it resolves to empty, unshackle removes the placeholder and one adjacent separator (., -, or space), so the surrounding text collapses cleanly.

Use ? for anything that isn't always there

Episode names, editions, tags, HDR labels and audio extras aren't present on every title. Mark them optional so you never get doubled dots or dangling separators:

series: "{title}.{season_episode}.{episode_name?}.{quality}.{hdr?}.{source}-{tag?}"

For an episode with no on-screen name, {episode_name?} and its adjacent dot simply disappear.

Separator style (dots vs. spaces)¶

unshackle looks at the characters you place between variables to decide the filename's separator style. If spaces outnumber dots in your template, it sanitizes with spaces; otherwise it uses dots (the scene-style default). This is also applied to the auto-generated date separators for daily/dated content.

Scene style (dots)Readable style (spaces)

output_template:
  movies: "{title}.{year}.{quality}.{source}.WEB-DL.{audio_full}.{video}-{tag}"

The.Movie.2024.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv

output_template:
  movies: "{title} ({year}) {quality} {source} WEB-DL {audio_full} {video}"

The Movie (2024) 1080p EXAMPLE WEB-DL DDP5.1 H.264.mkv

Template variables¶

Every variable below is valid in both output and folder templates. Values are derived from the downloaded media (via MediaInfo), from the title metadata, or from your config. Variables that don't apply to a given title resolve to an empty string.

Common / video¶

Variable	Meaning	Example
`title`	Title name (movie/show/song name; `$` is rendered as `S`)	`The Show`
`year`	Release year	`2024`
`source`	Service tag / class name (empty with `--no-source`)	`EXAMPLE`
`quality`	Resolution with scan suffix	`1080p`, `2160p`, `576i`
`resolution`	Resolution number only	`1080`
`video`	Video codec	`H.264`, `H.265`
`hdr`	Dynamic-range label	`HDR`, `HDR10P`, `DV`, `DV.HDR10`, `HLG`
`hfr`	High frame rate marker (frame rate > 30)	`HFR`
`edition`	Edition label from the track, if any	`Directors Cut`
`tag`	Release-group tag (from `config.tag` or `--tag`)	`TAG`
`repack`	`REPACK` when the `--repack` flag is used	`REPACK`
`lang_tag`	Result of your `language_tags` rules, if configured	`MULTi`

How language_tags rules match

Rules are tried in order, but language comparison is fuzzy: a rule condition of en matches en-US, en-GB, and any other en-* variant. Within a single rule, all conditions must match (AND logic) for it to apply. The first rule that fully matches wins; if none match, {lang_tag?} is removed from the filename cleanly.

Episode-specific¶

Variable	Meaning	Example
`season`	Zero-padded season (`S%02d`)	`S01`
`episode`	Zero-padded episode (`E%02d`)	`E05`
`season_episode`	Combined	`S01E05`
`episode_name`	Episode title	`Pilot`
`date`	ISO air date for daily/dated content	`2024-06-01`

Daily & sports content

When an episode has an air date, unshackle switches to date-based naming automatically: season and season_episode become the formatted air date, episode and year are cleared, and {date} holds the ISO date. The date's internal separator (dots or spaces) follows your series template style.

Audio¶

Variable	Meaning	Example
`audio`	Audio codec	`DDP`, `DD`, `AAC`
`audio_channels`	Channel layout	`5.1`, `2.0`
`audio_full`	Codec + channels combined	`DDP5.1`
`atmos`	`Atmos` when any track carries JOC	`Atmos`
`dual`	`DUAL` for exactly two distinct audio languages	`DUAL`
`multi`	`MULTi` for more than two audio languages	`MULTi`

Music-specific¶

Variable	Meaning
`track_number`	Zero-padded track number
`artist` / `album_artist`	Artist / album artist (falls back to artist)
`album`	Album name
`disc`	Disc number (only shown when greater than 1)
`track_total` / `disc_total`	Totals
`release_type`	`album`, `single`, `ep`, etc.
`genre`	Genre
`explicit`	`Explicit` when flagged
`isrc` / `upc` / `label`	ISRC, UPC and record label

Unknown variables are ignored, not errors

If you use a variable that isn't in the list above, unshackle emits a warning at startup but continues. Double-check spelling. A typo'd {quailty} will simply be left in the filename literally or dropped, not filled in.

Folder templates¶

Folder templates are nested under a special folder key inside output_template. This key is handled separately from the filename kinds. You can give it a single string (used for all title kinds) or a per-kind map.

Single folder templatePer-kind folder templates

unshackle.yaml

output_template:
  movies: "{title}.{year}.{quality}.{source}-{tag}"
  series: "{title}.{season_episode}.{quality}.{source}-{tag}"
  folder: "{title}.{year}"

unshackle.yaml

output_template:
  movies: "{title}.{year}.{quality}.{source}-{tag}"
  series: "{title}.{season_episode}.{quality}.{source}-{tag}"
  folder:
    movies: "{title} ({year})"
    series: "{title} ({year})/Season {season}"
    albums: "{artist} - {album} ({year})"

The per-kind folder keys are movies, series, songs, and albums. Any other key produces a startup warning. Path separators (/ or \) are allowed in folder templates. Each segment is formatted independently, so you can build nested directory structures like Show/Season 01.

Fallback behavior:

A per-kind folder template wins if present; otherwise the single folder string is used; otherwise unshackle falls back to a built-in default.
Built-in defaults when no folder template is set: movies get no folder at all unless a movies folder template (or a single-string folder template) exists; series fall back to a folder derived from the series output template (stripping {episode}, {episode_name}, and collapsing {season_episode} down to {season}); music albums fall back to {artist} - {album} ({year}).

Movies are flat by default

Episodes and songs are always foldered. Movies are written directly into the output directory unless you define a movies folder template (or a single-string folder template, which folders every kind). Set one if you want each movie in its own directory.

Muxing options¶

Muxing (combining video, audio, subtitle, chapter and attachment tracks into a single Matroska file with mkvmerge) is configured under the muxing key.

unshackle.yaml

muxing:
  set_title: true
  merge_video: false
  merge_audio: true
  default_language:
    audio: en
    subtitle: en

Key	Type	Default	Effect
`set_title`	bool	`true`	Write the title name into the MKV container title with `--title`. Set to `false` to omit it.
`merge_video`	bool	`false`	Group video tracks that share the same resolution, range, and codec into one file so only language varies inside it.
`merge_audio`	bool	`true`	Merge audio tracks of the same kind so multiple languages sit in one file.
`default_language`	map	(unset)	Preferred language per track type (`video` / `audio` / `subtitle`). A track in the preferred language is flagged as the default track.

When no preferred language is matched, unshackle applies sensible defaults: the video default falls back to the title language / original-language track / first track; the audio default is the original-language track; and the subtitle default is a forced track matching the first audio's language.

default_language only sets the default-track flag

default_language controls which track carries the MKV --default-track flag. Nothing else. It does not change track selection (that stays with -l/--alang and friends), and it does not touch which track is marked as original: --original-flag still tags the true original-audio track. That is the point: you can make your player default to, say, Polish audio on an English-original title without altering the original marker. When the configured language isn't present in the manifest, each track type falls back to its normal default rule described above.

merge_video collapses only the language dimension

merge_video groups video tracks by (resolution, range, codec) and merges them so that only language differs within a single file, with no re-encode and no concatenation. Different resolutions, ranges (SDR / HDR10 / HDR10+ / DV / HYBRID), and codecs (H.264 / H.265) always land in separate files. So -r HYBRID,DV,HDR10,SDR --merge-video produces one file per range (never a single fused file), whereas English + French video of identical resolution, range, and codec yields one file containing both video tracks. merge_audio works the same way for audio languages.

A few muxing behaviors are automatic and not configurable:

--no-date is always passed for privacy (no timestamps embedded).
Descriptive audio gets the visually-impaired flag; SDH subtitles get the hearing-impaired flag; forced subtitles get the forced flag.
Chapters are written from the title's chapter list (see Chapters below).

The --no-mux flag skips muxing entirely and writes the individual track files, each with a track-type suffix, into the same output/folder structure.

Tags & group naming¶

The release-group tag is the -TAG portion at the end of scene-style names, produced by the {tag} variable.

unshackle.yaml

tag: "MYGROUP"
tag_group_name: true
tag_imdb_tmdb: true

Key	Type	Default	Effect
`tag`	str	`""`	The release-group tag used for `{tag}`.
`tag_group_name`	bool	`true`	Write the group name (`config.tag`) into the MKV `Group` metadata tag.
`tag_imdb_tmdb`	bool	`true`	Look up and embed IMDb / TMDB / TVDB external-ID tags in the MKV metadata (uses `tmdb_api_key` / `simkl_client_id` when available).

You can override the tag per run without editing config:

unshackle dl --tag OTHERGROUP EXAMPLE "..."

The --repack flag adds the REPACK marker (surfaced through the {repack} variable) to the filename for that run:

unshackle dl --repack EXAMPLE "..."

Empty tags collapse cleanly

If config.tag is empty and your template ends with -{tag?}, the trailing - and the placeholder are both removed. Use the optional form {tag?} if you sometimes download without a tag set.

Unicode filenames¶

By default unshackle transliterates non-ASCII characters (Korean, Japanese, Chinese, accented Latin, etc.) into ASCII equivalents, which is safest for older tools, DDL, and P2P sharing. Set unicode_filenames to keep the native characters.

unshackle.yaml

unicode_filenames: true

Value	Result
`false` (default)	`기생충` → transliterated ASCII; accents stripped.
`true`	Native characters preserved in filenames and folders.

Regardless of this setting, a set of filesystem-unsafe and structural characters is always removed or replaced during sanitization (for example / and ; become &, and characters like \ * ! ? , ' " < > | $ # ~ are stripped). This is why you should never put path-unsafe characters directly in a template. unshackle warns about templates containing < > : " / \ | ? * at startup (folder templates are checked per path segment, so / is allowed there as a directory separator).

Directory & filename configuration¶

The directories key relocates unshackle's working folders. Only the folders listed here can be moved; core package paths are protected and silently ignored if you try to override them.

unshackle.yaml

directories:
  downloads: "~/Media/unshackle"
  temp: "/mnt/fast/unshackle-temp"
  cache: "~/.cache/unshackle"
  cookies: "~/.config/unshackle/cookies"
  logs: "~/.config/unshackle/logs"

Name	Purpose
`downloads`	Default output directory for finished files.
`temp`	Working directory for in-progress downloads, muxing, and intermediate files.
`cache`	Title/HTTP cache and update-check state.
`cookies`	Per-service cookie files.
`logs`	Log files.
`exports`	Export JSONs.
`services`, `vaults`, `fonts`, `commands`	Search paths for services, key-vault backends, bundled fonts, and CLI commands.
`wvds`, `prds`, `dcsl`	Widevine devices, PlayReady devices, and DCSL data.

Paths support ~ expansion. The names app_dirs, core_dir, namespace_dir, user_configs, and data are protected and cannot be changed.

Filename patterns¶

The filenames key overrides the naming patterns for a handful of internal files. These are not your media output names. They are logs, temp files, and per-service configs.

unshackle.yaml

filenames:
  log: "unshackle_{name}_{time}.log"
  chapters: "Chapters_{title}_{random}.txt"
  subtitle: "Subtitle_{id}_{language}.srt"

Name	Default	Where
`log`	`unshackle_{name}_{time}.log`	`directories.logs`
`debug_log`	`unshackle_debug_{service}_{time}.jsonl`	`directories.logs`
`config`	`config.yaml`	per-service directory
`root_config`	`unshackle.yaml`	main config filename
`chapters`	`Chapters_{title}_{random}.txt`	`directories.temp`
`subtitle`	`Subtitle_{id}_{language}.srt`	`directories.temp`

Chapters naming¶

When a title has chapters, they are written to an OGM chapters file (filenames.chapters) and passed to the muxer. Unnamed chapters use the chapter_fallback_name template:

unshackle.yaml

chapter_fallback_name: "Chapter {i:02}"

The fallback supports two placeholders: {i} (chapter number, starting at 1) and {j} (which increments only for unnamed chapters). Standard format directives like {i:02} are allowed.

Removed & migrated options¶

scene_naming was removed

The old scene_naming option no longer exists. If it is present in your config, unshackle exits immediately with an error asking you to configure output_template instead. Migrate any scene-naming setup to the templates described on this page.

Worked examples¶

MoviesTV seriesMusic

output_template:
  movies: "{title}.{year}.{edition?}.{quality}.{source}.WEB-DL.{audio_full}.{atmos?}.{video}.{hdr?}-{tag?}"
  folder:
    movies: "{title} ({year})"

The Movie (2024)/
  └─ The.Movie.2024.1080p.EXAMPLE.WEB-DL.DDP5.1.Atmos.H.265.HDR-TAG.mkv

output_template:
  series: "{title}.{season_episode}.{episode_name?}.{quality}.{source}.WEB-DL.{audio_full}.{video}-{tag}"
  folder:
    series: "{title} ({year})/Season {season}"

The Show (2023)/Season S02/
  └─ The.Show.S02E04.The.Reckoning.2160p.EXAMPLE.WEB-DL.DDP5.1.H.265-TAG.mkv

output_template:
  songs: "{track_number}. {title}"
  folder:
    albums: "{album_artist} - {album} ({year})"

The Artist - The Album (2024)/
  └─ 01. Opening Track.mka

Output & Naming¶

How an output path is assembled¶

Output templates¶

Required vs. optional variables¶

Separator style (dots vs. spaces)¶

Template variables¶

Common / video¶

Episode-specific¶

Audio¶

Music-specific¶

Folder templates¶

Muxing options¶

Tags & group naming¶

Unicode filenames¶

Directory & filename configuration¶

Filename patterns¶

Chapters naming¶

Removed & migrated options¶

Worked examples¶

See also¶