feat(dl): let --worst run without -q and pick the lowest bitrate

--worst picks the lowest bitrate at each -q resolution, or at the lowest resolution when no -q is set. Hybrid mode still requires -q.

Thanks to reel.deal for the report and the first patch.
This commit is contained in:
imSp4rky
2026-11-15 15:14:14 -07:00
parent 3522de1e9c
commit 511db0c768
7 changed files with 147 additions and 18 deletions
+2 -2
View File
@@ -439,7 +439,7 @@ Make a download job. It requires `service` and `title_id`. Every other field is
| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `profile` | string | `null` | Credential/cookie profile. |
| `quality` | int[] | `[]` | Target resolution(s); best available if empty. |
| `quality` | int[] | `[]` | Target resolution(s); best available if empty, or the lowest with `worst`. |
| `vcodec` | string/string[] | `[]` | Video codec filter. |
| `acodec` | string/string[] | `[]` | Audio codec filter. |
| `vbitrate` / `abitrate` | int | `null` | Video / audio bitrate in kbps (positive). |
@@ -480,7 +480,7 @@ Make a download job. It requires `service` and `title_id`. Every other field is
| `adaptive_workers` | boolean | `false` | Scale segment workers to measured CDN throughput, up to the `workers` cap. |
| `download_processes` | int | `1` | Split a track's segments across this many processes. Only engages for large batches. |
| `downloads` | int | `1` | Concurrent tracks. |
| `worst` | boolean | `false` | Lowest bitrate within quality. |
| `worst` | boolean | `false` | Pick the lowest-bitrate video at each resolution in `quality`, or at the lowest resolution if `quality` is empty. With `worst`, `HYBRID` in `range` requires `quality`. |
| `best_available` | boolean | `false` | Fall back to best available. With `all_drm`, a DRM system that does not license is a warning. |
| `generate_dv` | boolean | `false` | With `HYBRID` in `range`, make Dolby Vision from the HDR10+ metadata or the decoded video when a title has no DV track. With `HDR10` or `HDR10P` in `range` and no `HYBRID`, make it for that base and ignore a DV track. With none of the three in `range`, the field has no effect. |
| `repack` | boolean | `false` | Add REPACK tag. |
+2 -2
View File
@@ -83,7 +83,7 @@ unshackle dl [OPTIONS] SERVICE [SERVICE ARGS...]
| `--generate-dv` | off | With `-r HYBRID`, make Dolby Vision from the HDR10+ metadata or the decoded video when a title has no Dolby Vision track. With `-r HDR10` or `-r HDR10P`, make it for that base and ignore a Dolby Vision track. See [Dolby Vision without a DV track](downloading.md#dolby-vision-without-a-dv-track). |
| `-c`, `--channels` | - | Audio channels; matches sub-layouts (5.1 ≈ 6.0). |
| `-naa`, `--noatmos` | off | Exclude Dolby Atmos audio tracks. |
| `--worst` | off | Pick the lowest bitrate within the requested quality. **Requires `-q`.** |
| `--worst` | off | Pick the lowest-bitrate video at each requested resolution, or at the lowest resolution if none is set. |
| `--best-available`, `--warn-only` | off | Warn and continue when a requested resolution, range, video language, or audio language is absent, instead of failing. With `--all-drm`, also when one DRM system does not license. |
| `-rvb`, `--real-video-bitrate` | off | Probe real media size for true video bitrates, overriding the manifest. |
| `-rab`, `--real-audio-bitrate` | off | Same for audio (slower). |
@@ -234,7 +234,7 @@ order the service used, then renumbers the episodes into the order you asked for
| `--slow` | - | Inter-title delay. Bare `--slow` = 60-120s; `--slow 20-40` = custom range (minimum 20s). |
!!! warning "Some flags cannot be combined"
`--select-titles` and `--wanted` are mutually exclusive. `--worst` needs `--quality`. `--vbitrate` and `--vbitrate-range` (and the audio equivalents) are mutually exclusive.
`--select-titles` and `--wanted` are mutually exclusive. With `--worst`, hybrid mode needs `--quality`. `--vbitrate` and `--vbitrate-range` (and the audio equivalents) are mutually exclusive.
---
+10 -3
View File
@@ -73,7 +73,8 @@ filtering. `--skip-dl` runs the license step but skips the actual segment downlo
### Resolution
`-q` / `--quality` takes one or more target resolutions (heights) as a comma-separated
list. Without it, unshackle picks the **best available** resolution.
list. Without it, unshackle picks the **best available** resolution, or the lowest resolution with
`--worst`.
```shell title="Single resolution"
unshackle dl -q 1080 EXAMPLE 81234567
@@ -98,7 +99,11 @@ By default a missing requested resolution is an error. Two flags change that:
| Flag | Behaviour |
| --- | --- |
| `--best-available` (`--warn-only`) | If the requested resolution(s) are not present, continue with the best that *is* available instead of failing. Also softens missing video and audio languages and hybrid fallbacks, and with `--all-drm` a DRM system that does not license. |
| `--worst` | Within the specified quality, pick the **lowest** bitrate rendition. **Requires `-q/--quality`.** |
| `--worst` | Pick the lowest-bitrate video at each requested resolution. With no requested resolution, pick the lowest-bitrate video at the lowest resolution. |
A `quality` in the config counts as a requested resolution. When `--best-available` finds none of the
requested resolutions, `--worst` also picks from the lowest resolution. With `--worst`, hybrid mode
requires `-q`, also when `--generate-dv` switches an HDR10 or HDR10+ request to hybrid mode.
```shell title="Never fail on a missing resolution"
unshackle dl -q 2160 --best-available EXAMPLE 0ABC123
@@ -299,6 +304,8 @@ bitrate for the top renditions, overriding the manifest value:
declared-bitrate renditions of each quality tier, in parallel (video grouped by codec
and range, audio by codec, channels, language, and descriptive flag). It extends a
group downward while a lower unprobed rendition could still outrank a probed one.
The lowest renditions are often not probed, so `--worst` usually compares their
manifest bitrates.
This keeps probing fast even when a service exposes dozens of renditions. A track
whose duration unshackle cannot find falls back to `ffprobe`. A probe failure is
non-fatal: the manifest value stays in place.
@@ -1225,7 +1232,7 @@ authoritative list.
| `--latest-episodes N` | | Only the N newest episodes. |
| `--video-only` / `--audio-only` / `--subs-only` | `-V` / `-A` / `-S` | Restrict track types. |
| `--no-video` / `--no-audio` / `--no-subs` / `--no-chapters` / `--no-attachments` | `-nv` / `-na` / `-ns` / `-nc` / `-nt` | Skip track types. |
| `--worst` | | Lowest bitrate within `-q`. |
| `--worst` | | Lowest-bitrate video at each requested resolution, or at the lowest resolution if none is set. |
| `--require-audio` | | Audio languages that must exist. The title fails if one is missing. |
| `--require-video` | | Video languages that must exist. The title fails if one is missing. |
| `--best-available` | | Degrade gracefully instead of failing. |