# Output & Naming

This page tells you 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). Both take `{variable}` placeholders that unshackle fills in from the downloaded media. This page 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](../getting-started/configuration-file.md) first. Everything below lives in that file.

## How unshackle assembles an output path

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

```text
<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. unshackle **always** puts TV episodes and songs 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](#folder-templates)).
- **Filename template**: the `output_template` for the title kind (movie, series, or song).
- **Extension**: chosen by the muxer for a movie or an episode: `.mkv` for video, `.mka` for audio-only, `.mks` for subtitle-only, `.mp4` for [DTS:X Profile 2 and MPEG-H audio](#dtsx-profile-2-and-mpeg-h-output). unshackle does not mux a song. It remuxes a song into the container of its codec, such as `.flac`, `.opus`, or `.m4a`. Read [Music output files](#music-output-files).

!!! example "A typical episode path"
    ```text
    /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` config key, keyed by title kind. Each value is a format string built from `{variable}` placeholders.

```yaml title="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. A variable that does not apply becomes an *empty string*, so "present but empty" is different from "missing".
- `{variable?}`: **optional**. A trailing `?` marks the variable conditional. When it is empty, unshackle removes the placeholder *and* one adjacent separator (`.`, `-`, or space), so the surrounding text collapses cleanly.

!!! tip "Use `?` for anything that is not always there"
    Episode names, editions, tags, HDR labels and audio extras are not present on every title. Mark them optional so you never get doubled dots or dangling separators:

    ```yaml
    series: "{title}.{season_episode}.{episode_name?}.{quality}.{hdr?}.{source}-{tag?}"
    ```
    For an episode with no on-screen name, `{episode_name?}` and its adjacent dot 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 sanitises with spaces. If not, it uses dots (the scene-style default). unshackle also applies this style to the auto-generated date separators of daily content, and to every segment of a nested folder template.

=== "Scene style (dots)"

    ```yaml
    output_template:
      movies: "{title}.{year}.{quality}.{source}.WEB-DL.{audio_full}.{video}-{tag}"
    ```
    ```text
    The.Movie.2024.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv
    ```

=== "Readable style (spaces)"

    ```yaml
    output_template:
      movies: "{title} ({year}) {quality} {source} WEB-DL {audio_full} {video}"
    ```
    ```text
    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. unshackle takes the values from the downloaded media (through MediaInfo), from the title metadata, or from your config. A variable that does not apply to a title becomes an empty string.

### Common / video

| Variable | Meaning | Example |
|---|---|---|
| `title` | Title name (movie/show/song name; `$` is rendered as `S`) | `The Show` |
| `title_type` | Media kind of the title | `movie`, `series`, `music` |
| `year` | Release year | `2024` |
| `source` | Service tag / class name (empty with `--no-source`) | `EXAMPLE` |
| `quality` | Standard resolution with scan suffix | `1080p`, `2160p`, `576i` |
| `resolution` | Standard resolution number only | `1080` |
| `video` | Video codec | `H.264`, `H.265` |
| `hdr` | Dynamic-range label | `HDR`, `HDR10P`, `DV`, `DV.HDR`, `DV.HDR10P`, `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` |

!!! note "`quality` and `resolution` use the standard height"
    unshackle names a video by the nearest standard height (4320, 2160, 1440, 1080, 720, 576, 540,
    480, 360 or 240) when it is within 10%. It measures the short side and the height that a 16:9
    picture of the same width has, and uses the larger one. So a cropped 1920x800, a padded
    1920x1088 and a 1080x1920 portrait video are all `1080p`. A short side within 16 lines of
    2160, 1440 or 1080 gives that height, so an ultrawide 2560x1080 is `1080p`. A size with no
    standard height near it, such as 1600x900, keeps its own height. `dl -q` and the
    `dl --export` file name use the same rule.

!!! note "How `language_tags` rules match"
    unshackle tries the rules in order, and they compare languages with the same [matching rules](downloading.md#exact-vs-fuzzy-matching) as `-l`: a rule condition of `en` matches `en-US`, `en-GB`, and any other `en-*` form, but `es-419` matches only `es-419`. Within a single rule, **all** conditions must match (AND logic) for it to apply. The first rule that fully matches wins. If none match, unshackle removes `{lang_tag?}` 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` |
| `part` | Part index of a [split episode](#split-episodes), empty otherwise | `2` |
| `absolute` | Absolute episode number, zero-padded to 3 digits, empty when unknown | `007` |
| `date` | ISO air date, empty when the episode has none | `2024-06-01` |

!!! note "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, unshackle clears `episode` and `year`, and `{date}` holds the ISO date. The date's internal separator (dots or spaces) follows your `series` template style.

### Split episodes {#split-episodes}

A few services split one episode into several separately playable videos. Where a service reports that, unshackle folds the part index into `{episode}` and `{season_episode}`, so the stock `series` template names it with no change to your config.

```text
Show.Name.S01E01.Part.2.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv
```

The part token sits immediately after the episode token, before the quality tags, and the group tag stays last. Its separator follows your template's own style, the same way daily content does, so a spaced template gives `S01E01 Part 2` instead.

The part is left out of the folder name, so every part of an episode lands in the same season folder:

```text
The.Show.S01.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG/
  ├─ The.Show.S01E01.Part.1.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv
  ├─ The.Show.S01E01.Part.2.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv
  └─ The.Show.S01E02.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv
```

The same holds for a folder template of your own: `{season}` never picks up the part, and `{season_episode}` drops it inside a folder template. unshackle names an episode with no part like any other episode.

!!! note "What media servers do with the part token"
    The form above follows scene practice for genuinely split episodes. Kodi stacks the parts back into one playable episode automatically. Jellyfin lists two versions of S01E01, still correct and playable, because its stacking pattern expects the part marker at the end of the name. Plex uses a closed-source scanner, so what it does with text after the part token is not known.

For custom templates there is also a standalone [`{part}`](../reference/configuration/output.md#output_template) variable. You rarely want it, see the caveat on that page.

### Sports events {#sports-events}

A service can mark an episode as a sports event. That episode then uses the `sports` output template and the `sports` folder template, if you set them. Without them it uses the `series` templates, as before.

```yaml title="unshackle.yaml"
output_template:
  sports: "{title}.{year?}.{date?}.{episode_name}.{quality}.{source}.WEB-DL.{audio_full}.{video}-{tag}"
  folder:
    sports: "{title}.{year?}"
```

A `sports` template can use every series variable, with two differences:

- `{date}` holds the air date in the separator style of the template (`2026.11.01`), and is empty when the event has no air date.
- `{year}` is empty when the event has an air date, because the date holds the year.

An event with a year and no air date, and an event with an air date:

```text
League.2026/
  └─ League.2026.City.Grand.Prix.Practice.One.1080p.EXAMPLE.WEB-DL.AAC2.0.H.264-TAG.mkv
Club.League.2026/
  └─ Club.League.2026.11.01.Home.Club.vs.Away.Club.1080p.EXAMPLE.WEB-DL.AAC2.0.H.264-TAG.mkv
```

A `sports` folder template groups by `{year}`, or by the air year when the event has no year. `{season}`, `{episode}` and `{season_episode}` are not useful in a `sports` template. Use `-w S01E02` to select an event: the season and episode numbers stay on the title.

### Audio

| Variable | Meaning | Example |
|---|---|---|
| `audio` | Audio codec; rename it with [`codec_names`](../reference/configuration/output.md#codec_names) | `DDP`, `DD`, `AAC`, `DTS-X` |
| `audio_channels` | Channel layout; bed.LFE.heights when the track has height channels | `5.1`, `2.0`, `5.1.4` |
| `audio_full` | Codec + channels combined; a name that ends in a digit gets a separator | `DDP5.1`, `DTS-X.5.1.4`, `AC-4.2.0` |
| `atmos` | `Atmos` when any track carries JOC | `Atmos` |
| `dual` | `DUAL` for two audio languages (see [`dual_multi_mode`](../reference/configuration/download.md#dual_multi_mode)) | `DUAL` |
| `multi` | `MULTi` for more than two audio languages | `MULTi` |
| `dubbed` | `DUBBED` for a single audio language that is not the original (strict mode only) | `DUBBED` |

### 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`, or another type the service supplies |
| `genre` | Genre |
| `explicit` | `Explicit` when flagged |
| `isrc` / `upc` / `label` | ISRC, UPC and record label |

!!! warning "Unknown variables are ignored, not errors"
    If you use a variable that is not in the list above, unshackle gives a warning at startup but continues. Double-check spelling. A typo'd `{quailty}` stays in the filename literally, or unshackle drops it. unshackle does not fill it in.

## Folder templates

Folder templates sit under a special `folder` config key inside `output_template`. unshackle reads this config key separately from the filename kinds. You can give it a single string (for all title kinds) or a per-kind map.

=== "Single folder template"

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

=== "Per-kind folder templates"

    ```yaml title="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 config keys are `movies`, `series`, `sports`, `songs`, and `albums`. Any other config key gives a startup warning. Folder templates permit path separators (`/` or `\`). unshackle formats each segment independently, so you can assemble nested directory structures like `Show/Season 01`. unshackle reads the separator style from the whole template, so it spaces every segment alike.

**Fallback behaviour:**

- A per-kind folder template wins if present. If there is none, unshackle uses the single `folder` string. If there is no `folder` string either, 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}`). A sports event with no `sports` folder template uses the `series` folder template, or derives its folder from the `sports` output template when there is no folder template. Music albums fall back to `{artist} - {album} ({year})`. If the song has no year, the folder name is only `{artist} - {album}`.

!!! note "Movies are flat by default"
    Episodes and songs are always foldered. unshackle writes movies 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.

## Music output files

A song does not go through the muxer. Music services deliver audio in a fragmented MP4, which is
not a music file. Its header states a length of zero, so a player stops after the first fragment.
FLAC inside an MP4 is also not a FLAC stream. A rename cannot correct either fault, so unshackle
remuxes each downloaded audio track into the container of its codec, then moves the file to its
final path.

| Codec | Extension |
|---|---|
| FLAC | `.flac` |
| Opus | `.opus` |
| Vorbis | `.ogg` |
| MP3 | `.mp3` |
| AAC, ALAC, and all other codecs | `.m4a` |

unshackle re-encodes FLAC in this step. The audio does not change, but the new file states its
true length. A plain copy cannot, because it keeps the source header and the zero in it.

unshackle writes no `.mkv` file for music, and the [muxing options](#muxing-options) below do not
apply.

The `songs` output template names the file. The `albums` folder template names the folder
around it.

```text
/home/user/Downloads/
  └─ The Artist - The Album (2024)/
     ├─ 01. First Track.flac
     └─ 02. Second Track.flac
```

### Music metadata

After the file moves, unshackle writes the metadata into the audio file. It uses Vorbis
comments for FLAC and Ogg, ID3 frames for MP3, and MP4 atoms for M4A. The tags hold the
track title, artist, album artist, track and disc numbers, date, genre, ISRC, UPC,
copyright, and record label. When `tag` and `tag_group_name` are set, unshackle also writes the group
name into a `GROUP` tag.

unshackle embeds cover art when the service gives an artwork URL. It downloads the image
and puts it in the file.

unshackle writes lyrics when the service supplies them: a `LYRICS` Vorbis comment for FLAC, a
`USLT` frame for MP3, and a `©lyr` atom for M4A. Ogg uses the same `LYRICS` field as
FLAC. unshackle does not write synchronized lyrics (`SYLT`).

The embedded lyrics are plain text. A service can also save timed lyrics in a file beside
the audio, for example `08.Get.Lucky.lrc` next to `08.Get.Lucky.m4a`. A music player reads
the timed lines from that file. The file also comes back to the client from a remote server.

A metadata fault does not stop the run. The file is already in place, so unshackle writes a
warning and continues.

!!! warning "`--no-mux` leaves music files untagged"
    [`--no-mux`](cli-reference.md#output-muxing-files) moves each downloaded track file to the output path without the tagging step. A music file from such a run holds only the metadata that the service put in it.

## Muxing options

!!! note "Height channels"
    A track with height channels is named bed.LFE.heights, such as `5.1.4`.

### Track names and language tags

When the service gives a track no name, unshackle names it with the English name of its language,
such as `English`, `Portuguese (Portugal)` or `Spanish (Latin America)`. The name leaves out the
region that is the default for the language, so `en-US` is `English` and `pt-BR` is `Portuguese`,
but `en-GB` is `English (United Kingdom)`. A name from the service is kept as is. unshackle adds the SDH, CC, Forced or Descriptive label after either name.

A subtitle in a language with more than one script gets the script from its region:

| Service tag | Tag in the file | Track name |
|-------------|-----------------|------------|
| `zh-TW` | `zh-Hant-TW` | Chinese (Traditional) |
| `zh-HK` | `zh-Hant-HK` | Chinese (Traditional, Hong Kong) |
| `zh-CN` | `zh-Hans-CN` | Chinese (Simplified) |
| `sr-ME` | `sr-Latn-ME` | Serbian (Latin, Montenegro) |
| `zh` | `zh` | Chinese |

A tag without a region, such as `zh`, gets no script because the region is what tells the script.
unshackle writes audio tags as the service gives them, because a script applies only to written text.
Track selection, `--list` tags and file names use the service tag.

A service that knows the spoken language, such as Mandarin or Cantonese, gives the title language and
the audio a region and no script, and gives the subtitles a script:

| Tracks | Mandarin, Taiwan | Cantonese, Hong Kong |
|--------|------------------|----------------------|
| Title language and audio | `cmn-TW` | `yue-HK` |
| Subtitles | `zh-Hant` or `cmn-Hant` | `yue-Hant` |

With these tags, `-l orig` selects the audio and `-sl orig` selects the Traditional subtitles. Do not
mix the forms. A bare `cmn` implies Simplified Chinese, so a `cmn` title language makes `-sl orig`
select Simplified subtitles. A `zh-TW` title language with `cmn` audio selects no audio, because
`zh-TW` implies Traditional Chinese. Cantonese and Chinese never match, so `-sl orig` on a `yue-HK`
title does not select `zh-Hant` subtitles; select them with `-sl zh-Hant`.

The `{dual}`, `{multi}` and `{dubbed}` file name tags count `cmn` as `zh` and keep `yue` separate
(see [`dual_multi_mode`](../reference/configuration/download.md#dual_multi_mode)).

Set `muxing.track_names` to `native` to name each track in its own language. The same rules apply
to the script and the region:

```yaml title="unshackle.yaml"
muxing:
  track_names: native
```

| Service tag | Track name |
|-------------|------------|
| `zh-TW` subtitle | 中文（繁體） |
| `zh-HK` subtitle | 中文（繁體，香港） |
| `pt-PT` | Português (Portugal) |
| `es-419` | Español (Latinoamérica) |
| `ja-JP` | 日本語 |

Set `muxing.track_names` to `none` to leave a track unnamed when the service gives it no name. An
SDH, CC, Forced or Descriptive track then has only that label as its name.

The option also changes the names in `--list` and in the `track_name` field of the REST API.

Set `muxing.original_label` to add a label after the name of each audio and subtitle track in the
title's original language. unshackle also sets the Matroska original flag on these tracks, but some
players show only the name. MP4 output has no original flag, so there the label is the only marker:

```yaml title="unshackle.yaml"
muxing:
  original_label: "[Original]"
```

| Track | Track name |
|-------|------------|
| Japanese audio, original language | Japanese [Original] |
| Japanese SDH subtitle, original language | Japanese [Original] (SDH) |
| Korean subtitle | Korean |

The label can be any text, for example `"| Original"` or a label in another language. Put it in
quotes: YAML reads an unquoted `[Original]` as a list, and an unquoted `| Original` stops the config
from loading. unshackle ignores a value that is not text.

The label also applies to a name that the service sets, and to audio that a service keeps inside the
video file. unshackle does not add the label when the name already contains its words, so a service
name `Original` or `Japanese (original)` stays as it is.

!!! tip "Use an English label with Jellyfin 12"
    Jellyfin 12 adds its own "Original" to an original-language audio track from the flag, unless the
    name already contains the word. It adds none to a subtitle. A label in another language, such as `[원어]`, then shows next to Jellyfin's
    "Original".

!!! note "Players that show the language next to the name"
    Some players, such as Jellyfin, show the track name and the language name together. They leave
    out the language when the name already contains it, so an English name shows once. A native name
    such as `日本語` shows next to `Japanese` in an English interface.

### DTS:X Profile 2 and MPEG-H output

A title whose audio holds a `dtsx` or `dtsy` sample entry (DTS:X Profile 2, DTS-UHD), or an
MPEG-H sample entry (`mha1`, `mha2`, `mhm1`, `mhm2`), muxes to MP4 with
[MP4Box](../getting-started/installation.md), because Matroska has no CodecID for it.
Without MP4Box installed the mux stops.

DTS:X Profile 1 is DTS-HD Master Audio and muxes to MKV as usual.

An MP4 title loses:

- the default, forced, hearing-impaired and original track flags
- attachments, such as subtitle fonts
- SubStation Alpha (`.ass`) subtitles
- container tags (`mkvpropedit`)

You configure muxing (the combination of video, audio, subtitle, chapter and attachment tracks into a single Matroska file with `mkvmerge`) under the `muxing` config key. unshackle muxes only movies and episodes. Read [Music output files](#music-output-files) for what a music download does instead.

```yaml title="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. |
| `default_subtitle_type` | str or list | *(unset)* | The subtitle types that can take the default flag, in order: `forced`, `normal`, `sdh` (CC counts as SDH). The first subtitle track of the first type that the title has gets the flag. |

When no track has the preferred language, unshackle applies sensible defaults. The video default falls back to the title language, then the original-language track, then the first track. The audio default is the original-language track. The subtitle default is a forced track in the language of the default audio track.

Set `default_subtitle_type` to give the subtitle default to a different type. `default_subtitle_type: normal` with `default_language.subtitle: pl` puts the flag on the full Polish track when the title also has a forced Polish track. Without `default_language.subtitle`, the first track of the type in file order gets the flag, and a forced track counts only in the language of the default audio track. When the title has no track of a listed type, the rules above apply.

!!! tip "Use `normal` for players that read the forced flag"
    A forced track always carries the Matroska forced flag. A player that reads it, such as mpv or Jellyfin in its Smart mode, shows the forced track when the audio is in your subtitle language and the default track when it is not. `default_subtitle_type: forced` puts the default flag on the forced track, and such a player then shows it in place of the full track.

!!! note "`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`/`--a-lang` and friends). It also does not touch which track carries the original flag: `--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 is not present in the manifest, each track type falls back to its normal default rule described above.

!!! warning "`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` gives one file *per range*, never a single fused file. English and French video of identical resolution, range, and codec gives one file that holds 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.
- unshackle writes the chapters from the title's chapter list (see [Chapters](#chapters-naming) 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.

## Sample files

[`--sample`](cli-reference.md#output-muxing-files) and `--include-sample` write a sample into a
`Sample` folder inside the output folder of the title. The sample keeps the filename of the
title, with a `SAMPLE` tag at the end. The tag uses the separator of the output template.

```text title="A movie with --include-sample"
Some.Movie.2026.1080p.EXAMPLE.WEB-DL.H.264-TAG/
├── Some.Movie.2026.1080p.EXAMPLE.WEB-DL.H.264-TAG.mkv
└── Sample/
    └── Some.Movie.2026.1080p.EXAMPLE.WEB-DL.H.264-TAG.SAMPLE.mkv
```

With `--sample`, the `Sample` folder holds the only output file. If the run makes no title
folder, the `Sample` folder is in the downloads directory.

## Tags & group naming

The release-group tag is the `-TAG` portion at the end of scene-style names, which the `{tag}` variable gives.
You can swap it per release with [`tag_rules`](../reference/configuration/output.md#tag_rules): ordered rules whose
conditions read the release-attribute variables only (`quality`, `resolution`, `hdr`, `source`, `lang_tag`,
`title_type`, and so on), and the first rule that matches wins. `tag_rules` cannot read the title's own fields,
such as `title` and `season_episode`. See the [reference page](../reference/configuration/output.md#tag_rules) for the exact list.

```yaml title="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` / `tvdb_api_key` / `simkl_client_id` when available). |

unshackle writes the IDs as the Matroska `IMDB`, `TMDB`, and `TVDB2` tags. `TVDB2` values carry the
entity prefix the [Matroska tagging spec](https://www.matroska.org/technical/tagging.html)
requires: `series/73871` for a show, `movies/113` for a film.

You can override the tag per run without editing config:

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

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

```bash
unshackle dl --repack EXAMPLE "..."
```

!!! note "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 into ASCII equivalents. Korean, Japanese, Chinese, and accented Latin are examples. This is safest for older tools, DDL, and P2P sharing. Set `unicode_filenames` to keep the native characters.

```yaml title="unshackle.yaml"
unicode_filenames: true
```

| Value | Result |
|---|---|
| `false` (default) | `기생충` → transliterated ASCII; accents stripped. |
| `true` | Native characters preserved in filenames and folders, with the vowel and tone marks of languages such as Thai, Hindi and Bengali. |

With each value, unshackle first normalises the name to Unicode NFC. A title that a service sends in composed form and in decomposed form gives the same name.

Regardless of this setting, unshackle always removes or replaces a set of filesystem-unsafe and structural characters during sanitisation. For example, `/` and `;` become ` & `, and unshackle removes characters like `\ * ! ? , ' " < > | $ # ~`. This is why you must never put path-unsafe characters directly in a template.

unshackle warns at startup about a template that contains `< > : " / \ | ? *`. It examines a folder template per path segment, so you can use `/` there as a directory separator.

## Directory & filename configuration

The `directories` config key relocates unshackle's working folders. You can move only the folders in the table below. unshackle protects the core package paths and silently ignores them if you try to override them.

```yaml title="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 can hold a `~` for expansion. unshackle protects the names `app_dirs`, `core_dir`, `namespace_dir`, `user_configs`, and `data`, so you cannot change them.

### Filename patterns

The `filenames` config 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.

```yaml title="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 {#chapters-naming}

When a title has chapters, unshackle writes them to an OGM chapters file (`filenames.chapters`) and passes it to the muxer. Unnamed chapters use the `chapter_fallback_name` template:

```yaml title="unshackle.yaml"
chapter_fallback_name: "Chapter {i:02}"
```

The fallback can hold two placeholders: `{i}` (chapter number, starting at 1) and `{j}` (which increments only for unnamed chapters). It permits standard format directives like `{i:02}`.

## Removed & migrated options

!!! warning "`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

Each tab shows a template and what it produces for a few different downloads, so you can see
how the optional (`?`) variables appear and disappear.

=== "Movies"

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

    A 4K Atmos HDR download fills every placeholder:

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

    The same template on a plain 1080p SDR stereo download, where `{edition?}`, `{atmos?}`
    and `{hdr?}` collapse along with their dots:

    ```text
    The Movie (2024)/
      └─ The.Movie.2024.1080p.EXAMPLE.WEB-DL.AAC2.0.H.264-TAG.mkv
    ```

    A director's cut fills `{edition?}`:

    ```text
    The Movie (2024)/
      └─ The.Movie.2024.Directors.Cut.2160p.EXAMPLE.WEB-DL.DDP5.1.Atmos.H.265.DV.HDR-TAG.mkv
    ```

=== "TV series"

    ```yaml
    output_template:
      series: "{title}.{season_episode}.{episode_name?}.{quality}.{source}.WEB-DL.{audio_full}.{video}-{tag}"
      folder:
        series: "{title} ({year})/Season {season}"
    ```
    ```text
    The Show (2023)/Season S02/
      └─ The.Show.S02E04.The.Reckoning.2160p.EXAMPLE.WEB-DL.DDP5.1.H.265-TAG.mkv
    ```

    unshackle decides the separator style once for the whole folder template, and every
    segment then follows it. Spaces outnumber dots in `{title} ({year})/Season {season}`,
    so `Season {season}` keeps its space even though it holds only one variable.

    When an episode has no on-screen name, `{episode_name?}` disappears cleanly:

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

=== "Multi-language"

    Place `{dual?}`, `{multi?}` and `{dubbed?}` next to each other. At most one of them is
    ever set (see [`dual_multi_mode`](../reference/configuration/download.md#dual_multi_mode)), and the
    empty ones collapse:

    ```yaml
    output_template:
      movies: "{title}.{year}.{quality}.{source}.WEB-DL.{dual?}.{multi?}.{dubbed?}.{audio_full}.{video}-{tag}"
    ```

    Original English audio plus a French dub (`-l en,fr`):

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

    Original plus several dubs (`-l en,fr,de,es`):

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

    Only a dub, original audio left out (`-l de` on an English-original title):

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

    Two dialects of one language (`en-US` + `en-GB`) count as a single language, so none of the
    three variables is set:

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

    For finer control (for example a `SUBBED` tag driven by subtitle languages), use `{lang_tag?}`
    with [`language_tags` rules](../reference/configuration/download.md#language_tags) instead.

=== "Daily shows"

    Daily content needs no special template. When an episode carries an air date,
    `{season_episode}` becomes the date automatically and `{episode}` and `{year}` clear:

    ```yaml
    output_template:
      series: "{title}.{season_episode}.{episode_name?}.{quality}.{source}.WEB-DL.{audio_full}.{video}-{tag}"
    ```

    A normal episode and a dated one, same template:

    ```text
    The.Daily.Show.S28E101.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv
    The.Daily.Show.2024.06.01.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv
    ```

    The date separator follows your template style: dots here, spaces if your `series`
    template uses spaces.

    In folder names, `{season}` becomes the air year (`Season 2024` style grouping), and
    unshackle skips a `{year?}` in the folder template when it would only repeat that year.

=== "Music"

    ```yaml
    output_template:
      songs: "{track_number}. {title}"
      folder:
        albums: "{album_artist} - {album} ({year})"
    ```
    ```text
    The Artist - The Album (2024)/
      └─ 01.Opening.Track.mka
    ```

    In `"{track_number}. {title}"` the number of dots and spaces is equal, and a tie goes to
    dot style. Add more spaces between variables (as below) if you want space-separated names.

    A multi-disc album with explicit tracks, using more of the music variables. `{disc}` is
    empty on disc 1, so `{disc?}` and its separator only appear from disc 2 onward:

    ```yaml
    output_template:
      songs: "{disc?}-{track_number}. {title} {explicit?}"
      folder:
        albums: "{album_artist} - {album} ({year}) [{label?}]"
    ```
    ```text
    The Artist - The Album (2024) [The Label]/
      ├─ 01. Opening Track.mka
      └─ 02-03. Closing Track Explicit.mka
    ```

## See also

- [Configuration File](../getting-started/configuration-file.md): the full `unshackle.yaml` structure.
- [Downloading](downloading.md): the `dl` command and per-run flags like `-o`, `--no-folder`, `--tag`, and `--repack`.