mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-11-14 13:05:09 +00:00
feat(tracks)!: match a language tag to the variant it means
A tag with a region (en-US, es-419) matches only that variant and reports a miss instead of taking another region. A bare tag takes the variant it means (pt -> pt-BR, es -> es-ES) and falls back to any variant only when that one is missing. `orig` prefers the title's own tag, `-sl orig` resolves, forced and SDH subtitles are picked from their own pools, and the track name no longer strips the region from the cached language. BREAKING CHANGE: -l es-419 no longer selects es-ES, and language_priority, language_tags and muxing.default_language treat a regional tag as exact.
This commit is contained in:
imSp4rky
@@ -104,7 +104,7 @@ unshackle dl [OPTIONS] SERVICE [SERVICE ARGS...]
|
||||
| `-fs`, `--forced-subs` | off | Include forced subtitle tracks. |
|
||||
| `-fso`, `--forced-subs-only` | off | Keep only forced subtitle tracks; drop the other subtitles. Implies `-fs`. |
|
||||
| `-fsl`, `--forced-s-lang` | none | Language(s) wanted for forced subtitles; implies `-fs`. A `-` prefix excludes. |
|
||||
| `--exact-lang` | off | Exact matching only: `-l es-419` matches `es-419`, not `es-ES`. Applies to selection and to sort order. |
|
||||
| `--exact-lang` | off | A tag without a region selects only the variant it means and never falls back to another: `-l es` does not select `es-419`. A tag with a region, such as `es-419`, is always exact. Applies to selection and to sort order. |
|
||||
| `--sub-format` | - | Output subtitle format (`SRT`/`srt`, `VTT`/`webvtt`, `ASS`/`ssa`, `TTML`, `SMI`, ...), or `original` to keep the source format. |
|
||||
|
||||
!!! tip "These flags select languages, they do not order them"
|
||||
|
||||
@@ -315,9 +315,9 @@ unshackle dl -l en,-es -vl ja EXAMPLE 81234567
|
||||
!!! note "Rules for exclusion tokens"
|
||||
- `orig` becomes the title's own original language, so `-sl -orig` drops the
|
||||
subtitles in that language.
|
||||
- `--exact-lang` applies to exclusions with the same matching rules as selection:
|
||||
`-es` removes exactly the tracks that `es` would select. Without it, `-es` also
|
||||
removes `es-419` and `es-ES`.
|
||||
- An exclusion without a region removes every regional form: `-es` removes `es-419`
|
||||
and `es-ES`. An exclusion with a region removes only that variant: `-es-419` removes
|
||||
only `es-419`. With `--exact-lang`, `-es` removes only the variant `es` means.
|
||||
- Tracks with no language tag are never excluded.
|
||||
- unshackle rejects `-all`. Name the languages you do not want instead.
|
||||
- The comma form is the documented style. `-sl -es` also works, but a shell can read
|
||||
@@ -345,9 +345,28 @@ See [`subtitle.language_priority`](../reference/configuration/download.md#subtit
|
||||
|
||||
### Exact vs fuzzy matching
|
||||
|
||||
By default language matching is fuzzy: `-l en` also accepts `en-US`, `en-GB`, and the
|
||||
other regional forms (up to a small distance). Pass `--exact-lang` when only an exact
|
||||
match is acceptable: with it, `-l es-419` selects only `es-419`, not `es-ES`.
|
||||
A tag without a region asks for the variant it means: `pt` is Brazilian Portuguese, `es` is
|
||||
Spanish from Spain, and `en` is US English. With `pt-PT` and `pt-BR` tracks, `-l pt`
|
||||
selects `pt-BR`. If the title has no such variant, the tag takes every regional form, so
|
||||
`-l es` on a title with only `es-419` selects `es-419`.
|
||||
|
||||
A tag with a region asks for that variant only: `-l es-419` selects `es-419`, never `es-ES`
|
||||
or `es-MX`. If the service has no `es-419` track, unshackle reports `es-419 not found` and
|
||||
stops. With `--best-available`, it continues with the other languages.
|
||||
|
||||
A track without a region matches only the region its language implies. `en` is US English
|
||||
and `pt` is Brazilian Portuguese, so `-l en-US` accepts a track tagged `en`, but `-l en-GB`
|
||||
and `-l pt-PT` do not accept `en` or `pt`. To take any English track, write `en`.
|
||||
|
||||
`--exact-lang` turns off that fallback: a tag without a region then selects only the
|
||||
variant it means, so `-l es` does not select `es-419`.
|
||||
|
||||
`orig` is the title language that the service gives. It selects that exact variant first,
|
||||
so a `fr-CA` title takes `fr-CA` audio over `fr-FR`. When the title has no track in that
|
||||
variant, `orig` takes the closest regional form, unless you pass `--exact-lang`.
|
||||
|
||||
An exclusion without a region removes every regional form: `-es` drops `es-ES` and `es-419`.
|
||||
See the [exclusion rules](#excluding-languages) for `--exact-lang`.
|
||||
|
||||
!!! tip "The `all` and `best` tokens"
|
||||
For audio, the tokens `all` and `best` bypass the usual one-track-per-language pick
|
||||
|
||||
@@ -116,7 +116,7 @@ Every variable below is valid in both output and folder templates. unshackle tak
|
||||
| `lang_tag` | Result of your `language_tags` rules, if configured | `MULTi` |
|
||||
|
||||
!!! note "How `language_tags` rules match"
|
||||
unshackle tries the rules in order, but language comparison is **fuzzy**: a rule condition of `en` matches `en-US`, `en-GB`, and any other `en-*` form. 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.
|
||||
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
|
||||
|
||||
|
||||
+14
-12
@@ -76,7 +76,7 @@ Subtitle selection happens through `dl` flags. The most important is language se
|
||||
| `-fs`, `--forced-subs` | Include forced subtitle tracks (excluded by default). |
|
||||
| `-fso`, `--forced-subs-only` | Keep only forced subtitle tracks and drop the other subtitles; implies `-fs`. |
|
||||
| `-fsl`, `--forced-s-lang` | Language(s) wanted for forced subtitles; implies `-fs`. A `-` prefix excludes. |
|
||||
| `--exact-lang` | Exact language matching, with no regional variants. |
|
||||
| `--exact-lang` | A tag without a region never falls back to another variant: `es` does not match `es-419`. |
|
||||
| `-S`, `--subs-only` | Download only subtitle tracks. |
|
||||
| `-ns`, `--no-subs` | Do not download subtitle tracks at all. |
|
||||
| `--sub-format` | Output subtitle format / conversion target (see [conversion](#converting-subtitle-formats)). |
|
||||
@@ -91,17 +91,18 @@ To narrow it down, pass a comma-separated list of language tags:
|
||||
unshackle dl --s-lang en,es EXAMPLE 81234567
|
||||
```
|
||||
|
||||
Language matching is fuzzy by default: `en` matches `en-US`, `en-GB`, and similar
|
||||
variants. If a requested language is missing but others were found, unshackle continues
|
||||
with whatever remains and tells you which languages it dropped.
|
||||
|
||||
For strict matching, where `es-419` matches only `es-419` and never `es-ES`, add
|
||||
`--exact-lang`:
|
||||
A tag without a region selects the variant it means, such as `en-US` for `en`, and every
|
||||
regional form only when the title has no such variant. A tag with a region matches only
|
||||
that variant:
|
||||
|
||||
```shell title="Only Latin-American Spanish, no other Spanish variants"
|
||||
unshackle dl --s-lang es-419 --exact-lang EXAMPLE 'https://www.example.com/...'
|
||||
unshackle dl --s-lang es-419 EXAMPLE 'https://www.example.com/...'
|
||||
```
|
||||
|
||||
If a requested language is missing, unshackle stops with an error. With `--best-available`,
|
||||
it continues with the languages it found and tells you which ones it dropped. See
|
||||
[exact vs fuzzy matching](downloading.md#exact-vs-fuzzy-matching) for the full rules.
|
||||
|
||||
### Requiring languages before downloading
|
||||
|
||||
`--require-subs` is a gate rather than a filter. It downloads **all** available
|
||||
@@ -193,10 +194,11 @@ can make a clean non-SDH version for you by stripping the hearing-impaired cues:
|
||||
sound effects, speaker labels, music notes, and similar. This is on by default and
|
||||
controlled by the [`strip_sdh`](#subtitle-configuration) config key.
|
||||
|
||||
The check is deliberately loose: if a close-enough plain track already exists (for
|
||||
example an `en-GB` non-SDH track when the SDH track is `en-US`), no stripped copy is
|
||||
created. When a stripped copy *is* created, the original SDH track is kept as well, so
|
||||
you end up with both.
|
||||
The check uses the same [matching rules](downloading.md#exact-vs-fuzzy-matching) as
|
||||
`--s-lang`. A plain track covers an SDH track only when it is the same variant: `en` and
|
||||
`en-US` cover each other, but a plain `en-GB` track does not stop a stripped `en` or `en-US`
|
||||
copy. When unshackle creates a stripped
|
||||
copy, it keeps the original SDH track as well, so you end up with both.
|
||||
|
||||
The [`sdh_method`](#subtitle-configuration) config key selects the stripping engine
|
||||
itself. The default (`auto`) prefers the `subby` cleaner for SRT, falls back to
|
||||
|
||||
Reference in New Issue
Block a user