From 511db0c768fd26e3743a3c32ee23cdc43e53cc36 Mon Sep 17 00:00:00 2001 From: imSp4rky Date: Sun, 15 Nov 2026 15:14:14 -0700 Subject: [PATCH] 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. --- docs/dev/rest-api/endpoints.md | 4 +- docs/guide/cli-reference.md | 4 +- docs/guide/downloading.md | 13 ++++- tests/core/test_stereo_video.py | 43 ++++++++++++++- tests/core/test_worst_selection_loop.py | 73 +++++++++++++++++++++++++ unshackle/commands/dl.py | 22 +++++--- unshackle/core/api/routes.py | 6 +- 7 files changed, 147 insertions(+), 18 deletions(-) create mode 100644 tests/core/test_worst_selection_loop.py diff --git a/docs/dev/rest-api/endpoints.md b/docs/dev/rest-api/endpoints.md index 49be857f..74ab1139 100644 --- a/docs/dev/rest-api/endpoints.md +++ b/docs/dev/rest-api/endpoints.md @@ -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. | diff --git a/docs/guide/cli-reference.md b/docs/guide/cli-reference.md index ab69d634..6018a262 100644 --- a/docs/guide/cli-reference.md +++ b/docs/guide/cli-reference.md @@ -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. --- diff --git a/docs/guide/downloading.md b/docs/guide/downloading.md index 1eba5d61..676b6493 100644 --- a/docs/guide/downloading.md +++ b/docs/guide/downloading.md @@ -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. | diff --git a/tests/core/test_stereo_video.py b/tests/core/test_stereo_video.py index 392f076b..eed1e81d 100644 --- a/tests/core/test_stereo_video.py +++ b/tests/core/test_stereo_video.py @@ -221,10 +221,51 @@ def test_worst_prefers_the_2d_track_at_one_height(tmp_path: Path) -> None: ranked.sort_videos() assert pick_video(ranked.videos, worst=True) is videos[1] 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 +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: 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) diff --git a/tests/core/test_worst_selection_loop.py b/tests/core/test_worst_selection_loop.py new file mode 100644 index 00000000..4ace76ff --- /dev/null +++ b/tests/core/test_worst_selection_loop.py @@ -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 diff --git a/unshackle/commands/dl.py b/unshackle/commands/dl.py index f0173d13..cd50b42f 100644 --- a/unshackle/commands/dl.py +++ b/unshackle/commands/dl.py @@ -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]: - """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: - pool = [v for v in candidates if not v.stereo] or candidates - return pool[-1] if pool else None + return min( + 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) @@ -1328,7 +1334,8 @@ class dl: "--worst", is_flag=True, 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( "--best-available", @@ -2022,10 +2029,6 @@ class dl: ): 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: self.log.error("--select-titles and -w/--wanted cannot be used together") sys.exit(1) @@ -2051,6 +2054,9 @@ class dl: if not DoviTool: self.log.error("Unable to run hybrid mode: dovi_tool not found") 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: vaults_only = None diff --git a/unshackle/core/api/routes.py b/unshackle/core/api/routes.py index e0c49903..58de88af 100644 --- a/unshackle/core/api/routes.py +++ b/unshackle/core/api/routes.py @@ -937,7 +937,7 @@ async def download(request: web.Request) -> web.Response: items: type: integer 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. vcodec: oneOf: @@ -1176,7 +1176,9 @@ async def download(request: web.Request) -> web.Response: three in range, the field has no effect. worst: 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: type: boolean description: Add REPACK tag to the output filename (default - false)