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 | | Field | Type | Default | Notes |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| `profile` | string | `null` | Credential/cookie profile. | | `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. | | `vcodec` | string/string[] | `[]` | Video codec filter. |
| `acodec` | string/string[] | `[]` | Audio codec filter. | | `acodec` | string/string[] | `[]` | Audio codec filter. |
| `vbitrate` / `abitrate` | int | `null` | Video / audio bitrate in kbps (positive). | | `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. | | `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. | | `download_processes` | int | `1` | Split a track's segments across this many processes. Only engages for large batches. |
| `downloads` | int | `1` | Concurrent tracks. | | `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. | | `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. | | `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. | | `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). | | `--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). | | `-c`, `--channels` | - | Audio channels; matches sub-layouts (5.1 ≈ 6.0). |
| `-naa`, `--noatmos` | off | Exclude Dolby Atmos audio tracks. | | `-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. | | `--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. | | `-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). | | `-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). | | `--slow` | - | Inter-title delay. Bare `--slow` = 60-120s; `--slow 20-40` = custom range (minimum 20s). |
!!! warning "Some flags cannot be combined" !!! 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 ### Resolution
`-q` / `--quality` takes one or more target resolutions (heights) as a comma-separated `-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" ```shell title="Single resolution"
unshackle dl -q 1080 EXAMPLE 81234567 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 | | 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. | | `--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" ```shell title="Never fail on a missing resolution"
unshackle dl -q 2160 --best-available EXAMPLE 0ABC123 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 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 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. 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 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 whose duration unshackle cannot find falls back to `ffprobe`. A probe failure is
non-fatal: the manifest value stays in place. non-fatal: the manifest value stays in place.
@@ -1225,7 +1232,7 @@ authoritative list.
| `--latest-episodes N` | | Only the N newest episodes. | | `--latest-episodes N` | | Only the N newest episodes. |
| `--video-only` / `--audio-only` / `--subs-only` | `-V` / `-A` / `-S` | Restrict track types. | | `--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. | | `--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-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. | | `--require-video` | | Video languages that must exist. The title fails if one is missing. |
| `--best-available` | | Degrade gracefully instead of failing. | | `--best-available` | | Degrade gracefully instead of failing. |
+42 -1
View File
@@ -221,10 +221,51 @@ def test_worst_prefers_the_2d_track_at_one_height(tmp_path: Path) -> None:
ranked.sort_videos() ranked.sort_videos()
assert pick_video(ranked.videos, worst=True) is videos[1] assert pick_video(ranked.videos, worst=True) is videos[1]
assert pick_video(ranked.videos, worst=False) is videos[0] assert pick_video(ranked.videos, worst=False) is videos[0]
assert pick_video([videos[3], videos[2]], worst=True) is videos[2] assert pick_video([videos[2], videos[3]], worst=True) is videos[3]
assert pick_video([], worst=True) is None assert pick_video([], worst=True) is None
def test_worst_ranks_unknown_bitrates_and_sizes_highest(tmp_path: Path) -> None:
def ranked(*specs: tuple[bool, int, Any]) -> list[Video]:
tracks = Tracks([stereo_video(tmp_path, stereo=s, width=h * 16 // 9, height=h, bitrate=b) for s, h, b in specs])
tracks.sort_videos()
return tracks.videos
tie = ranked((False, 720, 500_000), (False, 480, 500_000))
assert pick_video(tie, worst=True) is tie[1]
unknown = ranked((False, 1080, 900_000), (False, 1080, 0), (False, 1080, None))
assert pick_video(unknown, worst=True) is unknown[0]
none_known = ranked((False, 1080, 0), (False, 1080, None))
assert pick_video(none_known, worst=True) is none_known[-1]
sizeless = stereo_video(tmp_path, stereo=False, bitrate=50_000)
sized = ranked((False, 720, 900_000))[0]
assert pick_video([sized, sizeless], worst=True) is sized
with_3d = ranked((False, 1080, 5_000_000), (True, 1080, 1_000_000))
assert pick_video(with_3d, worst=True) is with_3d[0]
def test_worst_ignores_the_language_order() -> None:
def rendition(language: str, bitrate: int) -> Video:
return Video(
url=f"https://x/{language}.mp4",
language=language,
codec=Video.Codec.HEVC,
width=1920,
height=1080,
bitrate=bitrate,
)
lower, higher = rendition("en-AU", 3_000_000), rendition("en-GB", 6_000_000)
tracks = Tracks([lower, higher])
tracks.sort_videos(by_language=["en"])
candidates = Tracks.by_language(tracks.videos, ["en"])
assert candidates == [lower, higher]
assert pick_video(candidates, worst=True) is lower
def test_hybrid_never_pairs_a_3d_dv_track(tmp_path: Path) -> None: def test_hybrid_never_pairs_a_3d_dv_track(tmp_path: Path) -> None:
base = stereo_video(tmp_path, stereo=False, range_=Video.Range.HDR10, height=2160) base = stereo_video(tmp_path, stereo=False, range_=Video.Range.HDR10, height=2160)
layered = stereo_video(tmp_path, stereo=True, range_=Video.Range.DV, height=2160) layered = stereo_video(tmp_path, stereo=True, range_=Video.Range.DV, height=2160)
+73
View File
@@ -0,0 +1,73 @@
"""Run --worst through the real dl.result() selection loop."""
from __future__ import annotations
from pathlib import Path
from typing import Any
import pytest
from tests.lang_selection import test_kind_only_selection as harness
from unshackle.core import binaries
from unshackle.core.titles import Episode
from unshackle.core.tracks import Tracks, Video
LADDER = [
("1080-hi", 1920, 1080, 6_000_000),
("1080-lo", 1920, 1080, 3_000_000),
("1080-unknown", 1920, 1080, None),
("540", 960, 540, 900_000),
("270-lo", 480, 270, 79_000),
("240-hi", 320, 240, 153_000),
("240-lo", 320, 240, 140_000),
("240-unknown", 320, 240, None),
]
class LadderService(harness.FakeService):
"""The harness episode with the video ladder above; a track with no bitrate is never the worst."""
def __init__(self) -> None:
super().__init__({1: {}})
def get_tracks(self, title: Episode) -> Tracks:
tracks = super().get_tracks(title)
tracks.videos = [
Video(
id_=id_,
url=f"https://x/{id_}",
language="en",
codec=Video.Codec.AVC,
range_=Video.Range.SDR,
width=width,
height=height,
bitrate=bitrate,
)
for id_, width, height, bitrate in LADDER
]
return tracks
@pytest.mark.parametrize(
("flags", "expected"),
[
({}, ["240-lo"]),
({"quality": [1080]}, ["1080-lo"]),
({"quality": [1080, 540]}, ["1080-lo", "540"]),
({"quality": [2160], "best_available": True}, ["240-lo"]),
],
)
def test_worst_picks_the_lowest_bitrate_of_the_quality_or_of_the_lowest_resolution(
monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture, flags: dict[str, Any], expected: list[str]
) -> None:
ids = harness.run(monkeypatch, caplog, {1: {}}, service=LadderService(), worst=True, **flags)
assert ids["video"] == expected
def test_worst_in_hybrid_mode_needs_a_quality(
monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
) -> None:
monkeypatch.setattr(binaries, "DoviTool", Path("dovi_tool"))
code = harness.run(monkeypatch, caplog, {1: {}}, service=LadderService(), worst=True, range_=[Video.Range.HYBRID])
assert code == 1
assert "--worst requires -q/--quality to be specified in hybrid mode" in caplog.text
+14 -8
View File
@@ -377,10 +377,16 @@ def hybrid_plan(videos: Sequence[Video], generate_dv: bool) -> tuple[list[Video]
def pick_video(candidates: list[Video], worst: bool) -> Optional[Video]: def pick_video(candidates: list[Video], worst: bool) -> Optional[Video]:
"""The best candidate, or with ``worst`` the last one, preferring 2D: a 3D track sorts after 2D at one height.""" """The best candidate, or with ``worst`` the lowest bitrate of the lowest resolution, preferring 2D.
A track with no bitrate or no size counts as the highest, and a full tie goes to the later track.
"""
if worst: if worst:
pool = [v for v in candidates if not v.stereo] or candidates return min(
return pool[-1] if pool else None reversed(candidates),
key=lambda v: (v.stereo, standard_resolution(v.width, v.height) or math.inf, v.bitrate or math.inf),
default=None,
)
return next(iter(candidates), None) return next(iter(candidates), None)
@@ -1328,7 +1334,8 @@ class dl:
"--worst", "--worst",
is_flag=True, is_flag=True,
default=False, default=False,
help="Select the lowest bitrate track within the specified quality. Requires -q/--quality.", help="Select the lowest bitrate track within the specified quality, or of the lowest resolution if no "
"quality is set. Hybrid mode requires -q/--quality.",
) )
@click.option( @click.option(
"--best-available", "--best-available",
@@ -2022,10 +2029,6 @@ class dl:
): ):
acodec = AUDIO_CODEC_LIST.convert(acodec) acodec = AUDIO_CODEC_LIST.convert(acodec)
if worst and not quality:
self.log.error("--worst requires -q/--quality to be specified")
sys.exit(1)
if select_titles and wanted: if select_titles and wanted:
self.log.error("--select-titles and -w/--wanted cannot be used together") self.log.error("--select-titles and -w/--wanted cannot be used together")
sys.exit(1) sys.exit(1)
@@ -2051,6 +2054,9 @@ class dl:
if not DoviTool: if not DoviTool:
self.log.error("Unable to run hybrid mode: dovi_tool not found") self.log.error("Unable to run hybrid mode: dovi_tool not found")
sys.exit(1) sys.exit(1)
if worst and not quality:
self.log.error("--worst requires -q/--quality to be specified in hybrid mode")
sys.exit(1)
if cdm_only is None: if cdm_only is None:
vaults_only = None vaults_only = None
+4 -2
View File
@@ -937,7 +937,7 @@ async def download(request: web.Request) -> web.Response:
items: items:
type: integer type: integer
description: >- description: >-
Download resolution(s) (default - best available). An API key with a Download resolution(s) (default - best available; lowest with worst). An API key with a
server_cdm_max_height for the service must pass a quality at or under that height. server_cdm_max_height for the service must pass a quality at or under that height.
vcodec: vcodec:
oneOf: oneOf:
@@ -1176,7 +1176,9 @@ async def download(request: web.Request) -> web.Response:
three in range, the field has no effect. three in range, the field has no effect.
worst: worst:
type: boolean type: boolean
description: Select the lowest bitrate track within the specified quality. Requires `quality` (default - false) description: >-
Select the lowest bitrate track within the specified quality, or at the lowest resolution if no
quality is set. HYBRID requires `quality` (default - false)
repack: repack:
type: boolean type: boolean
description: Add REPACK tag to the output filename (default - false) description: Add REPACK tag to the output filename (default - false)