davinci-resolve-mcp 2.96.0 → 2.97.0

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 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.97.0
+
+**`timeline_frame(action="capture")` now renders the frame.** v2.96.0 shipped it
+reading Resolve's thumbnail API; live validation on Studio 19.1.3.7 showed that
+API cannot do the job, so the default route changed. Callers using `preview` or
+`full` keep working and now get a frame-accurate image.
+
+### Measured — the thumbnail API is per-CLIP, not per-frame
+
+`GetCurrentClipThumbnailImage` returns the same image for every frame of a clip.
+Seeking to 00:00, 01:00, 02:00 and 04:00 within one clip returned
+**byte-identical data every time**; the image changed only when the playhead
+crossed a clip boundary. Two further conditions make it fail silently:
+
+- It returns `None` whenever Resolve is **not the frontmost application**, at any
+  delay, even on the Color page with a clip under the playhead.
+- The first read after a page switch or a playhead move can be empty while the
+  viewer catches up, so a single failed read proves nothing.
+
+None of this is distinguishable from "no frame here."
+
+### Measured — `ExportStills` needs the Gallery panel open
+
+It returns a bare `False`, writing nothing, unless the Gallery panel is visible
+on the Color page — across png/jpg/tif/dpx, three destination folders, settle
+delays of 0.5s/1.5s/3.0s, with Resolve frontmost. `GrabStill` succeeds; only the
+export fails. No scripting call can open that panel.
+
+### So `capture` renders one frame
+
+`MarkIn == MarkOut` on a still-image render. Frame-exact, full resolution, well
+under a second, and it needs no GUI panel and no foreground window. Verified
+live: three timecodes produced three different images, and the rendered burn-in
+matched the requested frame.
+
+`quality` is now `frame` (default), `preview` (same render bounded to 1280px),
+`thumbnail` (the instant per-clip image), and `still` (Gallery still). `full` and
+`preview` from the original issue schema both map to the render.
+
+**The cost, stated rather than hidden:** render settings are project-level.
+Format and codec are snapshotted and restored, the render job is deleted, and
+the Deliver page and playhead that rendering pulls Resolve onto are put back —
+but `TargetDir`, `CustomName` and the mark range cannot be read back on builds
+without `GetRenderSettings`, so they are reset to the full timeline rather than
+truly restored. `quality="thumbnail"` remains for callers who need a strictly
+side-effect-free read and can live with per-clip granularity. A capture also
+refuses while another render is running.
+
+### Corrected — docs that claimed per-frame accuracy
+
+`docs/SKILL.md` said `get_thumbnail` "reflects the current frame as rendered by
+Resolve." It reflects the clip. `timeline(action="thumbnail_contact_sheet")`
+samples the same API, so it is a shot inventory, not frame evidence; both are
+now described accurately. Both API findings are recorded in `api_truth` and
+regenerated into `docs/reference/api-limitations.md`.
+
+### Fixed — thumbnail reads poll instead of trusting one call
+
+`timeline_markers(action="get_thumbnail")` and `get_thumbnail_image` now hold the
+Color page, poll for the viewer to catch up, and name the foreground requirement
+when the read stays empty.
+
 ## What's New in v2.96.0
 
 New tool **`timeline_frame`** — the assistant can look at what Resolve is

package/README.md

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

package/docs/SKILL.md

@@ -1393,10 +1393,12 @@ Key actions:
   crop/composite/audio/property groups to many timeline items in one call
 - `apply_look_to_items(target_ids, cdl?|copy_from_item_id?, dry_run?)` — apply a
   normalized CDL and/or copy a source grade to multiple video items
-- `thumbnail_contact_sheet` / `marker_thumbnail_review` — sample Resolve-rendered
-  thumbnails under the project analysis root for visual verification. Resolve
-  only serves these thumbnails on the Color page; the tool switches there
-  automatically and restores the previous page. Expect a page flash in the GUI,
+- `thumbnail_contact_sheet` / `marker_thumbnail_review` — sample Resolve
+  thumbnails under the project analysis root. These are CLIP thumbnails, so the
+  sheet is effectively one image per clip, not per sampled frame — a shot
+  inventory rather than frame evidence. Resolve only serves them on the Color
+  page and only while it is frontmost; the tool switches page automatically and
+  restores the previous one. Expect a page flash in the GUI,
   and note that landing on Color can kick off cache/render work for the current
   clip — on a large timeline the switch is not free
 - `edit_kernel_capabilities` — report supported, partially supported, and
@@ -1486,15 +1488,18 @@ The compound tool accepts `frame`, `frame_id`, and `frameId` aliases.
 
 Note: `get_thumbnail` returns raw pixel data from `GetCurrentClipThumbnailImage()`.
 The dictionary includes `data` (raw bytes as a Python bytes-like object),
-`format`, `width`, `height`, `noOfComponents`, and `depth`. This reflects the
-current frame as rendered by Resolve — including any color grading or effects
-applied — which is different from reading the source file directly.
+`format`, `width`, `height`, `noOfComponents`, and `depth`. This reflects Resolve's processed
+output — including color grading and effects — rather than the source file. It
+is the CLIP's thumbnail, though: every frame of a clip returns the same image, so
+it cannot verify a specific frame. Use `timeline_frame(action="capture")` for
+that.
 
 Use `get_thumbnail_image` when the MCP client can display image content directly.
 It converts the same Resolve thumbnail payload to PNG bytes without writing a
-file to disk. Both actions hold the Color page for the read and restore the
-previous page. Prefer `timeline_frame(action="capture")` for new work — it is the
-same capture plus a timecode target, `max_width`, and a full-resolution mode.
+file to disk. Both actions hold the Color page for the read, restore the
+previous page, and poll rather than trusting a single read; both still need
+Resolve to be the frontmost application. Prefer `timeline_frame(action="capture")`
+for new work — it renders the frame you actually asked for.
 
 **`timeline_frame`** — Capture a timeline frame as viewable image content.
 
@@ -1506,17 +1511,26 @@ rendering — grade, Fusion, titles, transitions — rather than inferring it fr
 metadata. (For the raw camera file instead, use
 `media_analysis(action="extract_frames")`.)
 
-- `quality="preview"` (default) is Resolve's thumbnail: fast, small, writes
-  nothing.
-- `quality="full"` grabs a Gallery still for a full-resolution frame, then
-  removes it again. `format` is `png` (default), `jpg`, or `tif`.
-- `max_width` caps the width to conserve context. On `full` this needs ffmpeg;
-  without it the call fails rather than quietly returning a full-size frame.
+- `quality="frame"` (default) renders exactly that frame — the only
+  frame-accurate route. Full resolution, well under a second, works headless.
+  `preview` is the same render bounded to 1280px.
+- `quality="thumbnail"` is instant and touches nothing, but returns the **clip's**
+  thumbnail — identical for every frame of that clip. Use it to see which clip is
+  under the playhead, never to judge a specific frame. Needs the Color page *and*
+  Resolve frontmost.
+- `quality="still"` uses a Gallery still; requires the Gallery panel to be open.
+- `max_width` caps the width to conserve context (needs ffmpeg; without it the
+  call fails rather than quietly returning a full-size frame). `format` is `jpg`
+  (default), `png`, or `tif`.
 - `timecode` accepts absolute (`01:00:15:12`) or elapsed (`00:00:15:12`) time;
   `frame` is the absolute timeline frame. Omit both to capture the playhead.
 
-A capture is a read: the Color page, the playhead, the current timeline, and the
-Gallery are all restored afterwards.
+The playhead, page, current timeline and Gallery are restored. The render route
+additionally touches project render settings: format and codec are restored and
+the render job is deleted, but `TargetDir`/`CustomName`/mark range cannot be read
+back on builds without `GetRenderSettings`, so they are reset to the full
+timeline rather than restored. Reach for `quality="thumbnail"` when zero side
+effects matter more than accuracy.
 
 ```
 timeline_frame(action="capture", params={"timecode": "01:00:15:12", "max_width": 1280})
@@ -2084,27 +2098,31 @@ file.
 
 **Start here: `timeline_frame(action="capture")`** — Returns the frame at the
 playhead (or at any `timecode`/`frame` you name) as MCP image content, so a
-multimodal assistant can simply look at it. `quality="preview"` is fast and
-writes nothing; `quality="full"` is full resolution; `max_width` bounds the
-context cost. The Color page, playhead, current timeline, and Gallery are all
-restored afterwards.
+multimodal assistant can simply look at it. It renders that one frame, which is
+what makes it frame-accurate; `max_width` bounds the context cost.
 
 ```
 timeline_frame(action="capture", params={"timecode": "01:00:15:12", "max_width": 1280})
 ```
 
-**`timeline_markers(action="get_thumbnail")`** — Returns raw thumbnail data at
-the current playhead position. The response is a dictionary with keys `data`,
-`format`, `width`, `height`, `noOfComponents`, and `depth`. Use it when you need
-pixel data for tooling rather than an image to look at.
+⚠️ **The thumbnail API is per-clip, not per-frame.** `GetCurrentClipThumbnailImage`
+returns the same image for every frame of a given clip — verified by seeking
+within one clip and getting byte-identical data, with the image changing only at
+a clip boundary. It also returns nothing unless Resolve is the frontmost app.
+Everything below is built on it, so none of it can confirm what a *specific*
+frame looks like. Use `timeline_frame` for that.
 
-**`timeline_markers(action="get_thumbnail_image")`** — The original image-content
-action, equivalent to `timeline_frame(action="capture")` at default quality with
-no positional arguments. Kept for existing callers.
+**`timeline_markers(action="get_thumbnail")`** — Raw thumbnail data for the clip
+under the playhead: `data`, `format`, `width`, `height`, `noOfComponents`,
+`depth`. Use it when you need pixel data for tooling.
 
-**`timeline(action="thumbnail_contact_sheet")`** — Many frames at once as a single
-labeled PNG written to the analysis root. Use it to review a stretch of cut rather
-than one moment.
+**`timeline_markers(action="get_thumbnail_image")`** — The same clip thumbnail as
+image content; equivalent to `timeline_frame(action="capture", params={"quality":
+"thumbnail"})`. Kept for existing callers.
+
+**`timeline(action="thumbnail_contact_sheet")`** — A labeled PNG sheet written to
+the analysis root. Because it samples the same API, it is effectively one image
+per clip; treat it as a shot inventory, not as frame evidence.
 
 **`gallery_stills(action="grab_and_export", params={...})`** — Grabs a still from
 the current frame on the Color page and returns the image encoded as base64 in the

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 27 missing capabilities, 33 bugs / unreliable behaviors.
+**Totals:** 27 missing capabilities, 35 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -360,6 +360,22 @@ values, or automation-hostile modal prompts.
 - **Workaround / current handling:** Use comp.CurrentFrame.FlowView.SetPos(tool, x, y); confirm with GetPosTable and a liberal position parser.
 - **Tags:** fusion, unreliable-return
 
+### Timeline.GetCurrentClipThumbnailImage (foreground only)
+
+- **Object:** `Timeline`
+- **Signature:** `() -> {width, height, format, data} | None`
+- **Behavior:** Being on the Color page is necessary but NOT sufficient: the call also returns None whenever Resolve is not the frontmost application. Measured on Studio 19.1.3.7 — with the Color page open, a clip under the playhead, and GetCurrentVideoItem returning that clip, every read came back None while Resolve sat behind a terminal window, at delays from 0 to 2 seconds; bringing Resolve to the front made the very next read return a 288x162 'RGB 8 bit' thumbnail. Separately, the first read after a page switch or a playhead move can be None while the viewer catches up, so a single failed read proves nothing. The two failure modes are indistinguishable from 'no thumbnail exists' and from each other.
+- **Workaround / current handling:** Poll the read a few times before concluding it failed (src/server.py:_playhead_thumbnail_settled), and when it stays empty, name the foreground requirement in the error rather than reporting a missing frame. Headless callers cannot use this API at all; there is no scripting call to raise Resolve, so a background agent must fall back to a Gallery still or a render.
+- **Tags:** timeline, thumbnail, silent-failure, focus-dependent
+
+### GalleryStillAlbum.ExportStills (Gallery panel must be visible)
+
+- **Object:** `GalleryStillAlbum`
+- **Signature:** `(stills, folder, prefix, format) -> bool`
+- **Behavior:** Returns a bare False, writing nothing, unless the Gallery panel is actually open on the Color page. Measured on Studio 19.1.3.7: Timeline.GrabStill() succeeded and the still landed in the album (count 0 -> 1), yet ExportStills returned False for png, jpg, tif and dpx alike, into three different destination folders, at settle delays of 0.5s, 1.5s and 3.0s, and with Resolve frontmost. Panel visibility is not readable or settable from the scripting API, so a script cannot establish the precondition it depends on, nor distinguish this from a permissions or format failure.
+- **Workaround / current handling:** Treat False as 'the Gallery panel is probably closed' and say so in the error; ask the user to open Workspace > Gallery on the Color page. Do not retry formats hoping one sticks — when the panel is closed they all fail.
+- **Tags:** gallery, stills, silent-failure, ui-dependent
+
 ### MediaPoolItem.GetClipProperty('Transcription')
 
 - **Object:** `MediaPoolItem`

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.96.0"
+VERSION = "2.97.0"
 # 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.96.0",
+  "version": "2.97.0",
   "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.96.0"
+VERSION = "2.97.0"
 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.96.0"
+VERSION = "2.97.0"
 
 import base64
 import os
@@ -12998,6 +12998,31 @@ def _playhead_seek(tl, p: Dict[str, Any]) -> Tuple[Optional[str], Optional[Dict[
     return original, None
 
 
+def _playhead_thumbnail_settled(tl, attempts: int = 12, delay: float = 0.3):
+    """Read the thumbnail, giving Resolve time to catch up first.
+
+    Two things make the first read come back empty even when everything is
+    correct: a page switch to Color, and a playhead move — the viewer has not
+    caught up when the very next scripting call lands (measured on Studio
+    19.1.3.7, where the first capture after a switch returned None and later
+    ones on the same timeline succeeded). Poll instead of sleeping a fixed
+    amount, so the common warm case stays immediate.
+    """
+    for attempt in range(attempts):
+        try:
+            thumbnail = tl.GetCurrentClipThumbnailImage()
+        except Exception as exc:
+            return None, _err(
+                f"GetCurrentClipThumbnailImage raised: {exc}",
+                code="THUMBNAIL_FAILED", category="api_error",
+            )
+        if thumbnail:
+            return thumbnail, None
+        if attempt < attempts - 1:
+            time.sleep(delay)
+    return None, None
+
+
 def _playhead_frame_preview(tl, p: Dict[str, Any]):
     """Current frame via GetCurrentClipThumbnailImage, as MCP image content."""
     max_width = p.get("max_width", p.get("maxWidth"))
@@ -13006,10 +13031,9 @@ def _playhead_frame_preview(tl, p: Dict[str, Any]):
         if seek_err:
             return seek_err
         try:
-            try:
-                thumbnail = tl.GetCurrentClipThumbnailImage()
-            except Exception as exc:
-                return _err(f"GetCurrentClipThumbnailImage raised: {exc}", code="THUMBNAIL_FAILED", category="api_error")
+            thumbnail, thumb_err = _playhead_thumbnail_settled(tl)
+            if thumb_err:
+                return thumb_err
             if not thumbnail:
                 return _err(
                     "Resolve returned no thumbnail for the current frame."
@@ -13018,9 +13042,13 @@ def _playhead_frame_preview(tl, p: Dict[str, Any]):
                     "works on the Color page and the automatic switch failed (headless, "
                     "or the page is locked).",
                     code="NO_THUMBNAIL", category="precondition",
-                    remediation="Ensure a video item sits under the playhead and the Color page is reachable."
-                    if on_color else
-                    "Open the Color page in Resolve, or use quality='full' which does not depend on the thumbnail API.",
+                    remediation=(
+                        "Bring DaVinci Resolve to the front — the thumbnail API returns "
+                        "nothing while Resolve is in the background, even on the Color "
+                        "page (measured on Studio 19.1.3.7). Also confirm a video item "
+                        "sits under the playhead."
+                    ) if on_color else
+                    "Open the Color page in Resolve and bring it to the front, or use quality='full'.",
                 )
             try:
                 width, height, raw = _thumbnail_raw_rgb(thumbnail)
@@ -13037,6 +13065,194 @@ def _playhead_frame_preview(tl, p: Dict[str, Any]):
                     pass
 
 
+def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
+    """Render exactly one frame — the only frame-accurate capture route.
+
+    The two cheaper routes cannot do this job (both measured on Studio 19.1.3.7,
+    recorded in api_truth):
+      - GetCurrentClipThumbnailImage returns the CLIP's thumbnail. Seeking within
+        a clip returns byte-identical data; it changes only at a clip boundary.
+      - ExportStills returns bare False unless the Gallery panel is open, which
+        no scripting call can arrange.
+    A single-frame render honours the grade, Fusion and titles, is frame-exact,
+    runs in well under a second, and needs no GUI panel or foreground window.
+
+    The cost is that render settings are project-level state. Format and codec
+    are readable and are restored; the rest (TargetDir, CustomName, mark range)
+    is NOT readable on builds without GetRenderSettings, so this resets those to
+    sane values rather than truly restoring them. Callers who need a strictly
+    side-effect-free read should use quality="thumbnail" and accept per-clip
+    granularity.
+    """
+    fmt = str(p.get("format", "jpg")).lower().lstrip(".")
+    if fmt == "jpeg":
+        fmt = "jpg"
+    if fmt not in ("jpg", "png", "tif"):
+        return _err(
+            f"format must be jpg, png or tif; got {fmt!r}",
+            code="INVALID_FORMAT", category="invalid_input",
+        )
+    max_width = p.get("max_width", p.get("maxWidth"))
+    if max_width and not shutil.which("ffmpeg"):
+        return _err(
+            "max_width needs ffmpeg to rescale, and ffmpeg is not on PATH",
+            code="FFMPEG_REQUIRED", category="precondition",
+            remediation="Install ffmpeg, or drop max_width to get the full-resolution frame.",
+        )
+    if proj.IsRenderingInProgress():
+        return _err(
+            "A render is already in progress",
+            code="RENDER_BUSY", category="precondition", retryable=True,
+            remediation="Wait for the current render to finish, or use quality='thumbnail'.",
+        )
+
+    # Which frame? Default to wherever the playhead already is.
+    frame = p.get("frame")
+    timecode = p.get("timecode")
+    if frame is None and timecode is not None:
+        frame, frame_err = _timeline_timecode_to_frame_id(tl, _playhead_absolute_timecode(tl, timecode))
+        if frame_err:
+            return frame_err
+    elif frame is None:
+        frame, frame_err = _current_timeline_frame_id(tl)
+        if frame_err:
+            return frame_err
+    try:
+        frame = int(frame)
+    except (TypeError, ValueError):
+        return _err("frame must be an integer", code="INVALID_FRAME", category="invalid_input")
+
+    folder = _resolve_safe_dir(os.path.join(tempfile.gettempdir(), "resolve-frame-captures"))
+    os.makedirs(folder, exist_ok=True)
+    name = f"capture-{int(time.time() * 1000)}"
+
+    original_fc = None
+    try:
+        original_fc = proj.GetCurrentRenderFormatAndCodec()
+    except Exception:
+        pass
+    # Rendering pulls Resolve onto the Deliver page and moves the playhead;
+    # measured leaving the user on Deliver at a different frame. Both are ours
+    # to put back.
+    resolve = get_resolve()
+    original_page = None
+    try:
+        original_page = resolve.GetCurrentPage() if resolve else None
+    except Exception:
+        original_page = None
+    original_tc = None
+    try:
+        original_tc = tl.GetCurrentTimecode()
+    except Exception:
+        pass
+
+    job = None
+    try:
+        codecs = proj.GetRenderCodecs("JPEG" if fmt == "jpg" else fmt.upper()) or {}
+        codec = list(codecs.values())[0] if codecs else fmt
+        if not proj.SetCurrentRenderFormatAndCodec(fmt, codec):
+            return _err(
+                f"Resolve refused render format {fmt!r} with codec {codec!r}",
+                code="RENDER_FORMAT_REFUSED", category="api_error",
+                state={"format": fmt, "codec": codec},
+            )
+        applied = proj.SetRenderSettings({
+            "TargetDir": folder,
+            "CustomName": name,
+            "MarkIn": frame,
+            "MarkOut": frame,
+            "SelectAllFrames": False,
+            "ExportVideo": True,
+            "ExportAudio": False,
+        })
+        if not applied:
+            return _err(
+                "SetRenderSettings refused the single-frame range",
+                code="RENDER_SETTINGS_REFUSED", category="api_error",
+                state={"frame": frame},
+            )
+        job = proj.AddRenderJob()
+        if not job:
+            return _err("AddRenderJob returned nothing", code="RENDER_JOB_FAILED", category="api_error")
+        before = set(os.listdir(folder))
+        if not proj.StartRendering([job], isInteractiveMode=False):
+            return _err("StartRendering refused the job", code="RENDER_START_FAILED", category="api_error")
+        waited = 0.0
+        while proj.IsRenderingInProgress() and waited < 120:
+            time.sleep(0.25)
+            waited += 0.25
+        status = _ser(proj.GetRenderJobStatus(job)) or {}
+        if status.get("JobStatus") != "Complete":
+            return _err(
+                f"Render did not complete: {status.get('JobStatus')}",
+                code="RENDER_FAILED", category="api_error",
+                state={"status": status, "frame": frame},
+            )
+        # Resolve appends the frame number to CustomName, so match on the prefix.
+        written = sorted(f for f in set(os.listdir(folder)) - before if f.startswith(name))
+        if not written:
+            return _err(
+                "Render reported success but wrote no file",
+                code="RENDER_FAILED", category="api_error",
+                state={"folder": folder, "frame": frame},
+            )
+        src_path = os.path.join(folder, written[0])
+        out_format = "jpg" if fmt == "jpg" else "png"
+        if max_width or fmt == "tif":
+            data, ff_err = _ffmpeg_scale_to_bytes(src_path, int(max_width) if max_width else None, out_format)
+            if ff_err:
+                return _err(f"Failed to rescale the rendered frame: {ff_err}", code="RESCALE_FAILED", category="api_error")
+        else:
+            with open(src_path, "rb") as handle:
+                data = handle.read()
+        return Image(data=data, format=out_format)
+    finally:
+        if job:
+            try:
+                proj.DeleteRenderJob(job)
+            except Exception:
+                pass
+        if original_fc:
+            try:
+                proj.SetCurrentRenderFormatAndCodec(
+                    original_fc.get("format"), original_fc.get("codec"))
+            except Exception:
+                pass
+        # Best-effort, not a restore: without GetRenderSettings there is nothing
+        # to restore FROM, so put the mark range back to the whole timeline
+        # rather than leaving it pinned to the captured frame.
+        try:
+            proj.SetRenderSettings({
+                "SelectAllFrames": True,
+                "MarkIn": tl.GetStartFrame(),
+                "MarkOut": tl.GetEndFrame(),
+                "CustomName": "",
+            })
+        except Exception:
+            pass
+        try:
+            for f in os.listdir(folder):
+                if f.startswith(name):
+                    try:
+                        os.remove(os.path.join(folder, f))
+                    except OSError:
+                        pass
+            if not os.listdir(folder):
+                os.rmdir(folder)
+        except OSError:
+            pass
+        if original_tc:
+            try:
+                tl.SetCurrentTimecode(original_tc)
+            except Exception:
+                pass
+        if original_page and original_page != "deliver":
+            try:
+                _open_page_serialized(resolve, original_page)
+            except Exception:
+                pass
+
+
 def _playhead_frame_full(proj, tl, p: Dict[str, Any]):
     """Current frame at full resolution via GrabStill + ExportStills."""
     fmt = str(p.get("format", "png")).lower().lstrip(".")
@@ -13158,14 +13374,32 @@ def _playhead_frame_full(proj, tl, p: Dict[str, Any]):
                 pass
 
 
+# quality -> capture route. "frame" renders and is the only frame-accurate one,
+# so it is the default; the aliases exist because issue #146 proposed
+# preview/full, and both of those mean "the frame", just at different sizes.
+_PLAYHEAD_QUALITY_ALIASES = {
+    "frame": "frame",
+    "full": "frame",
+    "preview": "frame",
+    "thumbnail": "thumbnail",
+    "still": "still",
+}
+
+
 def _playhead_frame_capture(p: Dict[str, Any]):
     """Dispatch a playhead capture, honouring an optional timeline_name."""
-    quality = str(p.get("quality", "preview")).lower()
-    if quality not in ("preview", "full"):
+    requested = str(p.get("quality", "frame")).lower()
+    quality = _PLAYHEAD_QUALITY_ALIASES.get(requested)
+    if not quality:
         return _err(
-            f"quality must be 'preview' or 'full'; got {quality!r}",
+            f"quality must be one of {sorted(_PLAYHEAD_QUALITY_ALIASES)}; got {requested!r}",
             code="INVALID_QUALITY", category="invalid_input",
         )
+    # "preview" asked for a fast, downscaled version of the real frame; honour
+    # the intent with a default bound rather than silently rendering full size.
+    if requested == "preview" and not p.get("max_width", p.get("maxWidth")):
+        p = dict(p)
+        p["max_width"] = 1280
     proj, tl, err = _get_tl()
     if err:
         return err
@@ -13193,9 +13427,11 @@ def _playhead_frame_capture(p: Dict[str, Any]):
                 code="SET_TIMELINE_FAILED", category="api_error",
             )
     try:
-        if quality == "full":
+        if quality == "thumbnail":
+            return _playhead_frame_preview(tl, p)
+        if quality == "still":
             return _playhead_frame_full(proj, tl, p)
-        return _playhead_frame_preview(tl, p)
+        return _playhead_frame_render(proj, tl, p)
     finally:
         if original_tl is not None:
             try:
@@ -22846,26 +23082,44 @@ def timeline_frame(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
 
     Actions:
       capture(timecode?|frame?, quality?, max_width?, format?, timeline_name?) -> MCP image content
-      capabilities() -> {quality_modes, ffmpeg, current_page, playhead, timeline}
+      capabilities() -> {quality_modes, ffmpeg, render_settings_restorable, ...}
 
     capture parameters:
       timecode     Absolute ('01:00:15:12') or elapsed ('00:00:15:12') timeline
                    timecode. Omit to capture the current playhead.
       frame        Alternative to timecode: absolute timeline frame number.
-      quality      'preview' (default) — Resolve's thumbnail; fast, small, no
-                   files written. 'full' — full-resolution via Gallery still.
-      max_width    Cap the width in pixels to conserve context. 'full' needs
-                   ffmpeg to rescale; without it the call fails rather than
+      quality      'frame' (default) renders exactly that frame — the only
+                   frame-accurate route, full resolution, ~1s, works headless.
+                   'preview' is the same render bounded to max_width 1280.
+                   'thumbnail' is instant and touches nothing, but returns the
+                   CLIP's thumbnail (see below). 'still' uses a Gallery still.
+      max_width    Cap the width in pixels to conserve context. Needs ffmpeg on
+                   the render path; without it the call fails rather than
                    quietly returning a full-size frame.
-      format       'full' only: png (default), jpg, or tif.
+      format       jpg (default), png, or tif.
       timeline_name  Capture from a different timeline; it is made current for
                    the read and the original is restored afterwards.
 
-    Both qualities need the Color page (GetCurrentClipThumbnailImage and
-    GrabStill are Color-page-only); the tool switches there and restores the
-    user's page. A named timecode is restored to the original playhead position
-    afterwards, and 'full' removes the still it grabbed from the Gallery — a
-    capture is a read, not an edit.
+    Choosing a quality — the trade-off is accuracy against side effects:
+
+      'frame'/'preview'  Frame-exact. Renders one frame, so it changes
+                   project-level render settings. Format and codec are restored;
+                   TargetDir, CustomName and the mark range cannot be read back
+                   on builds without GetRenderSettings, so they are reset to the
+                   full timeline rather than truly restored. Refuses while
+                   another render is running.
+      'thumbnail'  Changes nothing and returns instantly, but it is NOT frame
+                   accurate: GetCurrentClipThumbnailImage returns the clip's
+                   thumbnail, identical for every frame of that clip (measured
+                   on Studio 19.1.3.7). Use it to see which clip is under the
+                   playhead, never to judge a specific frame. It also needs the
+                   Color page AND Resolve frontmost, or it returns nothing.
+      'still'      Full-resolution Gallery still. Requires the Gallery panel to
+                   be open on the Color page — no scripting call can open it,
+                   so this fails with a bare refusal when it is closed.
+
+    The playhead, the Color page, the current timeline and the Gallery are all
+    restored; a capture is a read of the picture, not an edit of the cut.
     """
     p = _params(params)
     if action == "capture":
@@ -22877,10 +23131,12 @@ def timeline_frame(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
         except Exception:
             current_page = None
         payload = {
-            "quality_modes": ["preview", "full"],
-            "formats": {"preview": ["png"], "full": sorted(_PLAYHEAD_STILL_FORMATS)},
+            "quality_modes": ["frame", "preview", "thumbnail", "still"],
+            "default_quality": "frame",
+            "frame_accurate": {"frame": True, "preview": True, "thumbnail": False, "still": True},
+            "formats": ["jpg", "png", "tif"],
             "ffmpeg": bool(shutil.which("ffmpeg")),
-            "max_width_supported": {"preview": True, "full": bool(shutil.which("ffmpeg"))},
+            "max_width_supported": bool(shutil.which("ffmpeg")),
             "current_page": current_page,
         }
         _, tl, err = _get_tl()

package/src/utils/api_truth.py

@@ -496,6 +496,55 @@ API_TRUTH: List[Dict[str, Any]] = [
         "submit": "missing",
         "mitigation": ["color_page_for_thumbnails", "_timeline_thumbnail_contact_sheet"],
     },
+    {
+        "symbol": "Timeline.GetCurrentClipThumbnailImage (foreground only)",
+        "object": "Timeline",
+        "signature": "() -> {width, height, format, data} | None",
+        "reality": "Being on the Color page is necessary but NOT sufficient: the "
+                   "call also returns None whenever Resolve is not the frontmost "
+                   "application. Measured on Studio 19.1.3.7 — with the Color page "
+                   "open, a clip under the playhead, and GetCurrentVideoItem "
+                   "returning that clip, every read came back None while Resolve "
+                   "sat behind a terminal window, at delays from 0 to 2 seconds; "
+                   "bringing Resolve to the front made the very next read return a "
+                   "288x162 'RGB 8 bit' thumbnail. Separately, the first read after "
+                   "a page switch or a playhead move can be None while the viewer "
+                   "catches up, so a single failed read proves nothing. The two "
+                   "failure modes are indistinguishable from 'no thumbnail exists' "
+                   "and from each other.",
+        "recommended": "Poll the read a few times before concluding it failed "
+                       "(src/server.py:_playhead_thumbnail_settled), and when it "
+                       "stays empty, name the foreground requirement in the error "
+                       "rather than reporting a missing frame. Headless callers "
+                       "cannot use this API at all; there is no scripting call to "
+                       "raise Resolve, so a background agent must fall back to a "
+                       "Gallery still or a render.",
+        "tags": ["timeline", "thumbnail", "silent-failure", "focus-dependent"],
+        "submit": "bug",
+        "mitigation": ["_playhead_thumbnail_settled", "timeline_frame"],
+    },
+    {
+        "symbol": "GalleryStillAlbum.ExportStills (Gallery panel must be visible)",
+        "object": "GalleryStillAlbum",
+        "signature": "(stills, folder, prefix, format) -> bool",
+        "reality": "Returns a bare False, writing nothing, unless the Gallery "
+                   "panel is actually open on the Color page. Measured on Studio "
+                   "19.1.3.7: Timeline.GrabStill() succeeded and the still landed "
+                   "in the album (count 0 -> 1), yet ExportStills returned False "
+                   "for png, jpg, tif and dpx alike, into three different "
+                   "destination folders, at settle delays of 0.5s, 1.5s and 3.0s, "
+                   "and with Resolve frontmost. Panel visibility is not readable "
+                   "or settable from the scripting API, so a script cannot "
+                   "establish the precondition it depends on, nor distinguish this "
+                   "from a permissions or format failure.",
+        "recommended": "Treat False as 'the Gallery panel is probably closed' and "
+                       "say so in the error; ask the user to open Workspace > "
+                       "Gallery on the Color page. Do not retry formats hoping one "
+                       "sticks — when the panel is closed they all fail.",
+        "tags": ["gallery", "stills", "silent-failure", "ui-dependent"],
+        "submit": "bug",
+        "mitigation": ["_playhead_frame_full", "gallery_stills.grab_and_export"],
+    },
     {
         "symbol": "Timeline.GetTimelineByName",
         "object": "Project",