fix(delivery): withdraw hls_h264 and report each target's own QC reason

hls_h264 shipped in 2.94.0 because it resolved cleanly against the
format/codec matrix. It can never render. On Studio 21.0.4.5
GetRenderCodecs('m3u8') returns {'H.264': 'H264'} and
GetRenderResolutions('m3u8','H264') returns real rasters, yet
SetCurrentRenderFormatAndCodec('m3u8', ...) is False for every value tried
('H264', 'H.264', 'h264', '') while ('mp4','H264') succeeds. Withdrawn
along with its hls and streaming aliases; a target that always fails is
worse than no target.

Only queuing an actual job caught this. Resolving a name proves the pair
is LISTED, not that it is usable — so the matrix is not a capability
contract. Folded into the existing Project.GetRenderCodecs api_truth entry
rather than added as a second entry for the same symbol.

Also fixes qc_note, which hard-coded an image-sequence message for every
target without a QC projection. webp_animated declines QC because its
ffprobe values are unmeasured, and was telling callers its output was a
many-file sequence. It now surfaces the target's own qc_skip_reason.

31 targets, each verified end to end on 21.0.4.5: resolved, queued as a
real render job, then deleted, with project render state restored.

Python 2615 tests pass. Node is untouched by this change (zero files under
resolve-advanced) and was green at 553 tests on identical code.

Author: samuelgursky

CHANGELOG.md

@@ -2,6 +2,39 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.94.1
+
+Removes the `hls_h264` target added in v2.94.0 — it could never work — and fixes
+a QC note that told the truth only for image sequences.
+
+### Fixed
+
+- **`hls_h264` is withdrawn.** It resolved cleanly against the format/codec
+  matrix, which is why it shipped, but it can never render: on Studio 21.0.4.5
+  `GetRenderCodecs('m3u8')` returns `{'H.264': 'H264'}` and
+  `GetRenderResolutions('m3u8', 'H264')` returns real rasters, yet
+  `SetCurrentRenderFormatAndCodec('m3u8', ...)` is False for every value tried
+  (`'H264'`, `'H.264'`, `'h264'`, `''`) while `('mp4', 'H264')` succeeds. Caught
+  by queuing an actual job rather than by resolving a name. A target that always
+  fails is worse than no target, so it is gone along with its `hls` and
+  `streaming` aliases.
+- **`qc_note` reported every target's missing QC projection as an image
+  sequence.** It was hard-coded, so `webp_animated` — which declines QC because
+  its ffprobe values are unmeasured — told callers its output was a many-file
+  sequence. It now surfaces the target's own `qc_skip_reason`.
+
+### Notes
+
+- New API-truth finding, folded into the existing `Project.GetRenderCodecs`
+  entry: **the format/codec matrix is not a capability contract.** A format can
+  advertise a codec, and rasters for it, and still refuse to be selected. That is
+  worse than the zero-codec formats, which at least advertise nothing. Presence
+  in the matrix proves a pair is *listed*, never that it is usable — the
+  authoritative test is setting it and reading the boolean back, which
+  `prepare_render_job` and `prepare_delivery_job` already do.
+- 31 targets, all verified end to end on Studio 21.0.4.5: resolved, queued as a
+  real render job, then deleted.
+
 ## What's New in v2.94.0
 
 Adds four delivery targets for deliverable classes the table did not cover:

README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.94.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.94.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(353%20full)-blue.svg)](#server-modes)

README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.94.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.94.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.94.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.94.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

docs/reference/api-limitations.md

@@ -470,8 +470,8 @@ values, or automation-hostile modal prompts.
 
 - **Object:** `Project`
 - **Signature:** `(renderFormat) -> {codec description: codec name}`
-- **Behavior:** Returns {description: id} — the human-readable description is the KEY and the id Resolve actually accepts is the VALUE. SetCurrentRenderFormatAndCodec, GetRenderCodecs and GetRenderResolutions all require the id, so passing the description a user sees in the Deliver page is rejected. Verified live on Studio 19.1.3.7 and re-confirmed unchanged on 21.0.4.5: ('mov', 'Apple ProRes 422 HQ') -> False while ('mov', 'ProRes422HQ') -> True, and ('mp4', 'H.264') -> False while ('mp4', 'H264') -> True. It affects every family, not only the ones whose id differs obviously. Mirrors the same trap in GetRenderFormats, which returns {format: extension}. Descriptions also DRIFT between majors while ids do not — every DNx description gained an 'Avid ' prefix in 21.x ('DNxHR HQ' -> 'Avid DNxHR HQ 12-bit') while the ids (DNxHRHQ, DNxHRLB, DNxHRHQX_10) were unchanged. Key on ids.
-- **Workaround / current handling:** Normalize both arguments through the live maps before calling: src.utils.render_ids.render_format_id_from_formats and render_codec_id_from_codecs accept a description or an id and return the id.
+- **Behavior:** Returns {description: id} — the human-readable description is the KEY and the id Resolve actually accepts is the VALUE. SetCurrentRenderFormatAndCodec, GetRenderCodecs and GetRenderResolutions all require the id, so passing the description a user sees in the Deliver page is rejected. Verified live on Studio 19.1.3.7 and re-confirmed unchanged on 21.0.4.5: ('mov', 'Apple ProRes 422 HQ') -> False while ('mov', 'ProRes422HQ') -> True, and ('mp4', 'H.264') -> False while ('mp4', 'H264') -> True. It affects every family, not only the ones whose id differs obviously. Mirrors the same trap in GetRenderFormats, which returns {format: extension}. Descriptions also DRIFT between majors while ids do not — every DNx description gained an 'Avid ' prefix in 21.x ('DNxHR HQ' -> 'Avid DNxHR HQ 12-bit') while the ids (DNxHRHQ, DNxHRLB, DNxHRHQX_10) were unchanged. Key on ids. SEPARATELY, the returned map is not a capability contract: a format can ADVERTISE a codec it will not accept. On 21.0.4.5 GetRenderCodecs('m3u8') returns {'H.264': 'H264'} and GetRenderResolutions('m3u8','H264') returns real rasters, yet SetCurrentRenderFormatAndCodec('m3u8', ...) is False for every value tried ('H264', 'H.264', 'h264', '') while ('mp4','H264') succeeds. That is worse than the zero-codec formats, which at least advertise nothing.
+- **Workaround / current handling:** Never treat presence in the matrix as proof a pair is usable — set it and read the boolean back (prepare_render_job / prepare_delivery_job do this and refuse to queue on False). Normalize both arguments through the live maps before calling: src.utils.render_ids.render_format_id_from_formats and render_codec_id_from_codecs accept a description or an id and return the id.
 - **Reference:** [issue #59](https://github.com/samuelgursky/davinci-resolve-mcp/issues/59)
 - **Tags:** render, deliver, silent-failure, id-vs-label
 

install.py

@@ -36,7 +36,7 @@
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.94.0"
+VERSION = "2.94.1"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.94.0",
+  "version": "2.94.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

src/granular/common.py

@@ -87,7 +87,7 @@
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.94.0"
+VERSION = "2.94.1"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

src/server.py

@@ -11,7 +11,7 @@
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.94.0"
+VERSION = "2.94.1"
 
 import base64
 import os
@@ -17007,10 +17007,16 @@ def _resolve_delivery_target_live(proj, p: Dict[str, Any]):
             "timeline_fps": fps,
             "settings": _delivery_targets.to_render_settings(target, timeline_fps=fps),
             "qc_spec": qc_spec,
+            # Surface the target's OWN reason. This used to hard-code an
+            # image-sequence message, which was simply false for any other kind
+            # of target that declines a QC projection.
             "qc_note": (
                 None
                 if qc_spec
-                else "This target renders an image sequence; deliverable_qc probes a single file, so it has no QC spec."
+                else (
+                    target.qc_skip_reason
+                    or "This target has no single-file QC projection."
+                )
             ),
             "loudness_target": loudness,
             "loudness_note": (

src/utils/api_truth.py

@@ -1689,8 +1689,20 @@
                    "Descriptions also DRIFT between majors while ids do not — "
                    "every DNx description gained an 'Avid ' prefix in 21.x "
                    "('DNxHR HQ' -> 'Avid DNxHR HQ 12-bit') while the ids "
-                   "(DNxHRHQ, DNxHRLB, DNxHRHQX_10) were unchanged. Key on ids.",
-        "recommended": "Normalize both arguments through the live maps before "
+                   "(DNxHRHQ, DNxHRLB, DNxHRHQX_10) were unchanged. Key on ids. "
+                   "SEPARATELY, the returned map is not a capability contract: a "
+                   "format can ADVERTISE a codec it will not accept. On 21.0.4.5 "
+                   "GetRenderCodecs('m3u8') returns {'H.264': 'H264'} and "
+                   "GetRenderResolutions('m3u8','H264') returns real rasters, yet "
+                   "SetCurrentRenderFormatAndCodec('m3u8', ...) is False for every "
+                   "value tried ('H264', 'H.264', 'h264', '') while ('mp4','H264') "
+                   "succeeds. That is worse than the zero-codec formats, which at "
+                   "least advertise nothing.",
+        "recommended": "Never treat presence in the matrix as proof a pair is "
+                       "usable — set it and read the boolean back "
+                       "(prepare_render_job / prepare_delivery_job do this and "
+                       "refuse to queue on False). Normalize both arguments "
+                       "through the live maps before "
                        "calling: src.utils.render_ids.render_format_id_from_formats "
                        "and render_codec_id_from_codecs accept a description or an "
                        "id and return the id.",

src/utils/delivery_targets.py

@@ -110,11 +110,15 @@
 
 Two findings changed between the builds and should not be treated as fixed facts:
 
-- **PNG, WebP and HLS.** Not render formats on 19.1.3.7; they *are* on 21.0.4.5.
-  `png_sequence`, `webp_animated` and `hls_h264` therefore resolve on 21.x and
-  fail loudly on 19.x, which is the correct behavior rather than a regression.
-  PNG exposes RGB only — no alpha codec — so it does not replace `dpx_sequence`
-  for transparency.
+- **PNG and WebP.** Not render formats on 19.1.3.7; they *are* on 21.0.4.5, so
+  `png_sequence` and `webp_animated` resolve on 21.x and fail loudly on 19.x,
+  which is correct behavior rather than a regression. PNG exposes RGB only — no
+  alpha codec — so it does not replace `dpx_sequence` for transparency.
+- **A format can advertise a codec it will not accept.** `HLS` (m3u8) returns a
+  codec from `GetRenderCodecs` and real rasters from `GetRenderResolutions`, yet
+  `SetCurrentRenderFormatAndCodec` rejects every value. Resolving a target proves
+  only that the pair is *listed*; the authoritative test is queuing a job, which
+  is why `prepare_delivery_job` refuses to queue on a rejected pair.
 - **Zero-codec formats.** `wav` and `gif` on 19.x; `braw`, `mts` and `wav` on
   21.x — `gif` gained codecs, BRAW and MTS lost them. `wav` is the constant, so
   an audio-only WAV target remains inexpressible through
@@ -703,17 +707,13 @@ def _package(key: str, label: str, formats: Tuple[str, ...], codecs: Tuple[str,
             "need a human. easyDCP variants exist on this install too.",
         ),
     ),
-    "hls_h264": _package(
-        "hls_h264", "HLS package (H.264)",
-        ("HLS", "m3u8"), ("H264", "H.264"),
-        "HTTP Live Streaming package: an .m3u8 playlist plus its segment files.",
-        notes=(
-            "HLS is a PACKAGE: a playlist plus segments, not one file. Bitrate ladders, "
-            "variant playlists and encryption keys are not expressible as a render target "
-            "— this selects the format/codec only.",
-            "HLS is not a render format on Resolve 19.x; this target resolves on 21.x+.",
-        ),
-    ),
+    # No HLS target. `HLS` (m3u8) looks fully supported through the query APIs on
+    # 21.0.4.5 — GetRenderCodecs returns {'H.264': 'H264'} and GetRenderResolutions
+    # returns real rasters — but SetCurrentRenderFormatAndCodec('m3u8', ...) is
+    # rejected for every value tried ('H264', 'H.264', 'h264', ''), while the same
+    # call for mp4/H264 succeeds. The matrix advertises a pair that cannot be
+    # selected, so a target for it would fail 100% of the time.
+    # Verified on Studio 21.0.4.5, 2026-08-12. See api_truth.py.
 }
 
 VALID_TARGETS = frozenset(DELIVERY_TARGETS)
@@ -749,8 +749,6 @@ def _package(key: str, label: str, formats: Tuple[str, ...], codecs: Tuple[str,
     "png": "png_sequence",
     "gif": "gif_animated",
     "webp": "webp_animated",
-    "hls": "hls_h264",
-    "streaming": "hls_h264",
 }
 
 #: Fields a caller may override per call. Deliberately excludes id/label/tier/