feat(hybrid): generate dolby vision from hdr10+ with --generate-dv

Builds per-scene L1 in unshackle (PQ mean, letterbox-aware) with a generate_dv_mode config (v29/v40/legacy); a failed hybrid no longer exits 0 with no video.

docs/dev/creating-a-service.md

@@ -156,8 +156,15 @@ class TrackRequest:
     codecs: list[Video.Codec] = []            # empty == accept any codec
     ranges: list[Video.Range] = [Video.Range.SDR]
     best_available: bool = False
+    generate_dv: bool = False                 # --generate-dv: make Dolby Vision from HDR10+
 ```
 
+!!! note "`generate_dv` and a hand-made HYBRID"
+    A service that fetches the HYBRID variants itself (HDR10 and DV) must also fetch
+    HDR10P when `track_request.generate_dv` is set and the title has no DV track.
+    The conversion needs an HEVC HDR10+ track as its base.
+    `get_tracks_for_variants` does this for you.
+
 !!! note "Read the request, don't second-guess the user"
     Services may narrow `track_request` for hard technical constraints (e.g.
     *"this service delivers HDR only as HEVC"*), but must **not** filter

docs/dev/rest-api/endpoints.md

@@ -471,6 +471,7 @@ Make a download job. It requires `service` and `title_id`. Every other field is
 | `downloads` | int | `1` | Concurrent tracks. |
 | `worst` | boolean | `false` | Lowest bitrate within 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 when a title has no DV track. Needs `hdr10plus_tool` on the server. Without `HYBRID` in `range`, the request returns `400`. |
 | `repack` | boolean | `false` | Add REPACK tag. |
 | `tag` | string | `null` | Release group tag. |
 | `tmdb_id` / `imdb_id` / `tvdb_id` / `anilist_id` | - | `null` | External ID overrides. Each resolves its metadata directly instead of by a title search, and is used for tagging. Set `enrich` to also take the title, year and original language. Give at most one of `tmdb_id`, `imdb_id` and `tvdb_id`, since unshackle resolves the others from it. Sending two returns `400`. `anilist_id` still combines with one of them. `tmdb_id` and `tvdb_id` must be positive integers, `imdb_id` must look like `tt1375666`, and `anilist_id` must be a positive integer or a string like `mal:12345`, or the request returns `400`. An ID whose provider is unconfigured, such as `tmdb_id` with no `tmdb_api_key`, fails the job rather than returning `400`. `anilist_id` needs no API key. |

docs/dev/rest-api/remote-sessions.md

@@ -130,8 +130,8 @@ hood the client walks a remote session through its lifecycle.
       The client also downloads playlists and segments through the same proxy,
       as a local run does. `--no-proxy-download` and `--proxy-download` change
       that for downloads only.
-    - Track-selection hints (`range_`, `vcodec`, `quality`, `best_available`) so
-      the server fetches the right manifests
+    - Track-selection hints (`range_`, `vcodec`, `quality`, `best_available`,
+      `generate_dv`) so the server fetches the right manifests
     - Your language and audio codec selection (`-l`, `-vl`, `-al`, `-a`, `-fs`)
       in a `dl_params` object. Some services fetch one manifest
       for each audio language, and pick the languages from these values
@@ -428,7 +428,7 @@ The server mounts all these routes, even in `--remote-only` mode. Paths use the
 answers CDM calls), `cdm_system_id` and `cdm_device_type` (Widevine only), `service_config`
 (the identity config keys the service lists in `client_config`), `client` (a freeform identity
 object the dashboard shows as sent), and the track-selection hints `range_`, `vcodec`,
-`quality`, `best_available`, plus arbitrary service CLI options
+`quality`, `best_available`, `generate_dv`, plus arbitrary service CLI options
 (`additionalProperties: true`).
 
 `dl_params` holds the `dl` track selection: `lang`, `v_lang` and `a_lang`

docs/dev/service-architecture.md

@@ -133,8 +133,10 @@ See [Proxies and VPN](../guide/proxies-and-vpn.md).
 !!! note "`TrackRequest`"
     `self.track_request` is a small dataclass built from the CLI: `codecs`
     (from `--vcodec`, empty means "accept any"), `ranges` (from `--range`, default
-    `[Video.Range.SDR]`), and `best_available`. Use it in `get_tracks` to decide which
-    variants to fetch.
+    `[Video.Range.SDR]`), `best_available`, and `generate_dv` (from `--generate-dv`).
+    Use it in `get_tracks` to decide which variants to fetch. A service that fetches
+    the HYBRID variants itself must also fetch HDR10P when `generate_dv` is set and
+    the title has no DV track, because the conversion needs an HEVC HDR10+ base.
 
 ## Titles and the `Title` hierarchy