davinci-resolve-mcp 2.93.3 → 2.94.1

package/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 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:
+image sequences for web/graphics, animated web assets, and an HTTP Live
+Streaming package. All 32 targets resolve live on Studio 21.0.4.5.
+
+### Added
+
+- **`png_sequence`** — PNG frames for web and motion-graphics handoff. Resolve
+  exposes **RGB only** (no alpha codec), so the target says so and points at
+  `dpx_sequence` (`RGBA 8 bits`) or `prores4444_master` when transparency is
+  actually needed. Alias: `png`.
+- **`gif_animated`** — looping animated GIF. No audio track at all, so
+  `ExportAudio` is False rather than merely unpinned. Its QC projection uses
+  ffprobe values measured on a generated file (`container: gif`, `codec: gif`).
+  Alias: `gif`.
+- **`webp_animated`** — looping animated WebP. Ships with **no QC projection**:
+  the reference machine's ffmpeg has only the `webp_pipe` still-image demuxer, so
+  a rendered animated WebP could not be probed and the ffprobe values are
+  unmeasured. `qc_skip_reason` says exactly that. Guessing `webp`/`webp` would
+  have produced QC failures about vocabulary rather than about the deliverable —
+  the same trap as mp4 reporting its container as `mov`. Alias: `webp`.
+- **`hls_h264`** — HTTP Live Streaming package (`.m3u8` playlist plus segments),
+  in the `package` tier alongside IMF and DCP. Bitrate ladders, variant playlists
+  and encryption keys are not expressible as a render target. Aliases: `hls`,
+  `streaming`.
+
+### Notes
+
+- PNG, WebP and HLS are **not render formats on Resolve 19.x**. These targets
+  resolve on 21.x and fail loudly with the machine's available list on older
+  builds, which is the designed behavior rather than a regression.
+- Deliberately **not** added, having checked the full 21.0.4.5 matrix: container
+  swaps that duplicate existing capability (MKV carries the same ProRes and
+  H.264/H.265 codecs already covered), standalone JPEG 2000 (the same essence the
+  IMF/DCP targets reach), and legacy formats (AVI, Cineon, MJ2, Panasonic AVC
+  8K). All remain reachable via a `format_candidates` override or a user target.
+- `braw`, `mts` and `wav` expose zero codecs and reject every codec value, so no
+  target is possible for them at all.
+
 ## What's New in v2.93.3
 
 Re-verifies the delivery-target table and the two recorded render API

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.93.3-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)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.93.3-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.93.3 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.94.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/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
 

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.93.3"
+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/package.json

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

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.93.3"
+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()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.93.3"
+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": (

package/src/utils/api_truth.py

@@ -1689,8 +1689,20 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "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.",

package/src/utils/delivery_targets.py

@@ -110,9 +110,15 @@ major-version upgrade.
 
 Two findings changed between the builds and should not be treated as fixed facts:
 
-- **PNG.** Not a render format on 19.1.3.7; it *is* one on 21.0.4.5 (along with
-  `jpg` and `webp`). There is still no `png_sequence` target, but the reason is
-  now "not added", not "impossible".
+- **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
@@ -578,6 +584,63 @@ DELIVERY_TARGETS: Dict[str, DeliveryTarget] = {
         ("RGB 16 bits", "RGB16", "RGB 8 bits"),
         "TIFF frames for stills-oriented or archival handoff.",
     ),
+    "png_sequence": _sequence(
+        "png_sequence", "PNG image sequence", ("PNG", "png"),
+        ("RGB16", "RGB 16 bits", "RGB8", "RGB 8 bits"),
+        "PNG frames for web and motion-graphics handoff.",
+        notes=(
+            "RGB ONLY — Resolve exposes no alpha PNG codec (21.0.4.5 offers just "
+            "'RGB 16 bits' / 'RGB 8 bits'). For transparency use dpx_sequence "
+            "('RGBA 8 bits') or prores4444_master.",
+            "PNG is not a render format on Resolve 19.x; this target resolves on 21.x+.",
+        ),
+    ),
+    # ── Animated web assets ─────────────────────────────────────────────────
+    # Not _web(): that helper pins mp4 and requires a raster. These carry no
+    # audio track at all, so export_audio is False rather than merely unpinned.
+    "gif_animated": DeliveryTarget(
+        id="gif_animated",
+        label="Animated GIF",
+        describe="Looping animated GIF for web/social placement. No audio.",
+        tier="web",
+        format_candidates=("GIF", "gif"),
+        codec_candidates=("Animated_GIF", "Animated GIF"),
+        qc_container="gif",
+        qc_codec="gif",
+        export_audio=False,
+        verified=_VERIFIED,
+        source="Live matrix: GIF render format; ffprobe values measured on a generated .gif.",
+        notes=(
+            "GIF carries no audio and is palette-limited to 256 colours; prefer "
+            "webp_animated where the destination supports it.",
+            "Raster and rate inherit the timeline — set them explicitly for a "
+            "placement with a fixed spec.",
+        ),
+    ),
+    "webp_animated": DeliveryTarget(
+        id="webp_animated",
+        label="Animated WebP",
+        describe="Looping animated WebP for web placement. No audio.",
+        tier="web",
+        format_candidates=("WebP", "webp"),
+        codec_candidates=("Animated_WEBP", "Animated WebP"),
+        export_audio=False,
+        # No QC projection on purpose — see qc_skip_reason. Guessing "webp"/"webp"
+        # would produce failures that say nothing about the deliverable, which is
+        # the exact trap the mp4-reports-as-mov case taught.
+        qc_skip_reason=(
+            "ffprobe container/codec values for animated WebP are unverified: the "
+            "reference machine's ffmpeg has only the webp_pipe still-image demuxer, "
+            "so a rendered animated WebP could not be probed. Measure and fill in "
+            "qc_container/qc_codec on a build with full WebP support."
+        ),
+        verified=_VERIFIED,
+        source="Live matrix: WebP render format (ffprobe side unmeasured).",
+        notes=(
+            "WebP carries no audio track.",
+            "WebP is not a render format on Resolve 19.x; this target resolves on 21.x+.",
+        ),
+    ),
     # ── Broadcast / Avid handoff ────────────────────────────────────────────
     "dnxhr_hq_mxf_opatom": DeliveryTarget(
         id="dnxhr_hq_mxf_opatom",
@@ -644,6 +707,13 @@ DELIVERY_TARGETS: Dict[str, DeliveryTarget] = {
             "need a human. easyDCP variants exist on this install too.",
         ),
     ),
+    # 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)
@@ -676,6 +746,9 @@ TARGET_ALIASES: Dict[str, str] = {
     "dnx_master": "dnxhr_hqx_master",
     "avid": "dnxhr_hq_mxf_opatom",
     "vfx": "exr_sequence",
+    "png": "png_sequence",
+    "gif": "gif_animated",
+    "webp": "webp_animated",
 }
 
 #: Fields a caller may override per call. Deliberately excludes id/label/tier/