davinci-resolve-mcp 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 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 v3.4.0 — review a bin one frame at a time in the control panel
+
+Contributed by @tpellet (#230), their first contribution here.
+
+### Added
+
+- **Serial source review in the control panel.** Reviewing a bin meant opening
+  each clip separately. The review bin now has an **Enlarge / review** button
+  per card that opens a full-size frame with previous/next navigation, so a bin
+  is walked once rather than clicked through a card at a time.
+- **Include / Exclude / Unreviewed per clip, and an independent star rating.**
+  Keyboard-driven — `I`, `X`, `U` and the arrow keys — with Include and Exclude
+  advancing automatically. Selection and rating are separate fields: rating a
+  clip does not decide it, and excluding one does not discard its rating.
+- **A selection filter** — all / non-excluded / excluded — alongside the
+  existing bin filter, and a selection chip on every card, so the state of a
+  pass is visible without opening anything.
+- **Decisions survive a reload.** Both fields go through the existing
+  correction store, so they persist the way clip notes already did and are
+  visible to everything else that reads corrections. Notes are untouched.
+
+### Changed
+
+- **Review thumbnails are letterboxed rather than cropped** (`object-fit:
+  cover` → `contain`). A cropped thumbnail hides exactly what a source review
+  is for: framing, headroom, and what is at the edges of frame.
+
+### Gating
+
+- **Every save is verified, not assumed.** The panel re-reads the clip after
+  each write and refuses to advance if the value it reads back is not the one
+  it sent, so a failed save cannot be walked past. `apply_clip_correction`
+  validates server-side as well: `user.selection` must be one of the three
+  literals, and `user.rating` must be an `int` from 0 to 5 — `type(value) is
+  not int` deliberately, so a JSON `true` is rejected rather than silently
+  stored as a rating of 1.
+- **No source media is touched and no Resolve edit is made.** Previews are
+  analyzed frames that already exist on disk; there is no conversion step.
+
 ## What's New in v3.3.0 — ask the server what the native Resolve API contains
 
 Contributed by @legionsound (#229), the second of the two branches queued in #207.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-3.3.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.4.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-37%20(387%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

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

package/docs/guides/control-panel.md

@@ -101,6 +101,19 @@ detection has run (`detect_entities` + a one-frame-per-cluster confirmation
 in chat), a `Recurring across this bin` card lists the labeled people,
 places, and objects with their shot counts.
 
+Use **Enlarge / review** on a card to inspect its complete analyzed frame without
+cropping. Previous/Next (or arrow keys) follow the visible bin order. **Include**
+(`I`) and **Exclude** (`X`) save the selection and advance after readback;
+**Unreviewed** (`U`) clears the decision without advancing. Ratings save independently
+and do not clear exclusions. The selection filter can show all, non-excluded,
+or excluded clips; it applies to the bin browser, not search results.
+
+Selections are stored as `user.selection` corrections alongside existing notes
+and ratings. They express review preferences, not automatic timeline edits.
+Previews use existing analyzed frames, so their resolution depends on the analysis;
+this does not generate proxies or stream original media. Existing clip detail
+controls remain available for notes and metadata edits.
+
 ### Clip detail
 
 ![Clip detail with shot strip](../images/control-panel/03-clip-detail.png)

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "3.3.0"
+VERSION = "3.4.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": "3.3.0",
+  "version": "3.4.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -1658,7 +1658,7 @@ HTML = r"""<!doctype html>
       aspect-ratio: 16 / 9;
       background: var(--lab-workspace-letterbox);
       border-radius: var(--radius-sm);
-      object-fit: cover;
+      object-fit: contain;
       display: block;
     }
     .review-thumb.placeholder {
@@ -4265,6 +4265,11 @@ HTML = r"""<!doctype html>
           <select id="reviewBinFilter" aria-label="Filter by bin">
             <option value="">All bins</option>
           </select>
+          <select id="sourceSelectionFilter" aria-label="Filter by source selection">
+            <option value="all">All selections</option>
+            <option value="non-excluded">Non-excluded</option>
+            <option value="excluded">Excluded</option>
+          </select>
           <div class="review-view-toggle" role="tablist" aria-label="View mode">
             <button id="reviewViewGridBtn" class="active" data-view-mode="grid" type="button">Grid</button>
             <button id="reviewViewListBtn" data-view-mode="list" type="button">List</button>
@@ -8822,11 +8827,159 @@ HTML = r"""<!doctype html>
         sorted.map(b => `<option value="${escapeHtml(b)}" ${b === current ? 'selected' : ''}>${escapeHtml(b)}</option>`).join('');
     }
 
+    let sourceSelectionFilter = 'all';
+    function matchesSourceSelection(clip) {
+      const selection = clip.user_selection || 'Unreviewed';
+      return sourceSelectionFilter === 'all'
+        || (sourceSelectionFilter === 'excluded' ? selection === 'Exclude' : selection !== 'Exclude');
+    }
+
+    // Source preview reviews the current bin/filter order using persisted corrections.
+    const sourcePreview = document.createElement('dialog');
+    sourcePreview.setAttribute('aria-label', 'Source preview');
+    sourcePreview.style.cssText = 'max-width:96vw;max-height:96vh;background:var(--bg-elevated-1);color:var(--text-primary)';
+    sourcePreview.innerHTML = `<button type="button" data-preview-close>Close</button>
+      <h3 data-preview-title></h3><div data-preview-controls>
+      <button type="button" data-preview-step="-1">← Previous</button>
+      <button type="button" data-preview-selection="Include">Include & next (I)</button>
+      <button type="button" data-preview-selection="Exclude">Exclude & next (X)</button>
+      <button type="button" data-preview-selection="Unreviewed">Unreviewed (U)</button>
+      <button type="button" data-preview-step="1">Next →</button>
+      <span>Rating:</span>${[0,1,2,3,4,5].map(n => `<button type="button" data-preview-rating="${n}" aria-label="${n ? n + ' stars' : 'Clear stars'}">${n ? '★'.repeat(n) : 'Clear'}</button>`).join('')}
+      </div><p data-preview-status role="status"></p>
+      <img data-preview-image alt="" style="display:block;max-width:90vw;max-height:70vh;object-fit:contain">`;
+    document.body.append(sourcePreview);
+    const previewImage = sourcePreview.querySelector('[data-preview-image]');
+    const previewStatus = sourcePreview.querySelector('[data-preview-status]');
+    let previewQueue = [], previewIndex = -1, previewBusy = false, previewReady = false, previewGeneration = 0;
+
+    function lockSourcePreview(busy) {
+      previewBusy = busy;
+      sourcePreview.querySelectorAll('[data-preview-controls] button').forEach(button => {
+        button.disabled = busy || (!button.dataset.previewStep && !previewReady);
+      });
+    }
+
+    function displaySourceReview(data, clip) {
+      const selection = readCorrectionValue(data.corrections, 'clip', clip.clip_id, 'user.selection') || 'Unreviewed';
+      const rating = readCorrectionValue(data.corrections, 'clip', clip.clip_id, 'user.rating') || 0;
+      clip.user_selection = selection;
+      sourcePreview.querySelectorAll('[data-preview-rating]').forEach(button => {
+        button.setAttribute('aria-pressed', String(Number(button.dataset.previewRating) === rating));
+      });
+      sourcePreview.querySelectorAll('[data-preview-selection]').forEach(button => {
+        button.setAttribute('aria-pressed', String(button.dataset.previewSelection === selection));
+      });
+      previewStatus.textContent = `${selection} · ${rating} stars — saved. ←/→ navigate; I include; X exclude; U clear selection.`;
+    }
+
+    async function showSourcePreview(index) {
+      if (previewBusy || index < 0 || index >= previewQueue.length) return;
+      previewIndex = index;
+      previewReady = false;
+      const clip = previewQueue[index], generation = ++previewGeneration;
+      lockSourcePreview(true);
+      sourcePreview.querySelector('[data-preview-title]').textContent = `${index + 1} / ${previewQueue.length} — ${clip.clip_name || clip.clip_id}`;
+      previewStatus.textContent = 'Loading preview and saved review…';
+      previewImage.style.visibility = 'hidden';
+      previewImage.alt = clip.clip_name || clip.clip_id;
+      try {
+        if (!clip.representative_frame_index) throw new Error('No analyzed frame available. Use Previous/Next to continue.');
+        const loaded = new Promise((resolve, reject) => {
+          previewImage.onload = resolve;
+          previewImage.onerror = () => reject(new Error('Preview unavailable. Use Previous/Next to continue.'));
+        });
+        previewImage.src = `/api/clips/${encodeURIComponent(clip.clip_id)}/frames/${clip.representative_frame_index}`;
+        const [data] = await Promise.all([api(`/api/clips/${encodeURIComponent(clip.clip_id)}`, {cache:'no-store'}), loaded]);
+        if (generation !== previewGeneration) return;
+        if (!data.success) throw new Error(data.error || 'Could not load saved review');
+        displaySourceReview(data, clip);
+        previewImage.style.visibility = 'visible';
+        previewReady = true;
+      } catch (error) {
+        if (generation === previewGeneration) previewStatus.textContent = error.message;
+      } finally {
+        if (generation === previewGeneration) lockSourcePreview(false);
+      }
+    }
+
+    async function saveSourceReview(field, value) {
+      if (previewBusy || !previewReady || previewIndex < 0) return;
+      const clip = previewQueue[previewIndex], generation = previewGeneration;
+      lockSourcePreview(true);
+      previewStatus.textContent = 'Saving…';
+      try {
+        const result = await api(`/api/clips/${encodeURIComponent(clip.clip_id)}/corrections`, {
+          method:'POST', body:JSON.stringify({entity_type:'clip', entity_uuid:clip.clip_id,
+            field_path:field, new_value:value, author:'control_panel', reason:'source preview review'})});
+        if (!result.success) throw new Error(result.error || 'Save failed');
+        const data = await api(`/api/clips/${encodeURIComponent(clip.clip_id)}`, {cache:'no-store'});
+        if (!data.success || readCorrectionValue(data.corrections, 'clip', clip.clip_id, field) !== value) {
+          throw new Error('Saved review could not be verified; retry before continuing.');
+        }
+        clip.user_selection = readCorrectionValue(data.corrections, 'clip', clip.clip_id, 'user.selection') || 'Unreviewed';
+        const listedClip = state.review.clipList?.clips?.find(item => item.clip_id === clip.clip_id);
+        if (listedClip) listedClip.user_selection = clip.user_selection;
+        renderReviewBin();
+        if (generation !== previewGeneration) return;
+        displaySourceReview(data, clip);
+        lockSourcePreview(false);
+        if (field === 'user.selection') {
+          if (!matchesSourceSelection(clip)) {
+            previewQueue.splice(previewIndex, 1);
+            if (previewQueue.length) await showSourcePreview(Math.min(previewIndex, previewQueue.length - 1));
+            else sourcePreview.close();
+          } else if (value !== 'Unreviewed' && previewIndex + 1 < previewQueue.length) {
+            await showSourcePreview(previewIndex + 1);
+          }
+        }
+      } catch (error) {
+        if (generation === previewGeneration) previewStatus.textContent = 'Save failed: ' + error.message;
+      } finally {
+        if (generation === previewGeneration) lockSourcePreview(false);
+      }
+    }
+
+    sourcePreview.querySelector('[data-preview-close]').onclick = () => sourcePreview.close();
+    sourcePreview.addEventListener('close', () => {
+      ++previewGeneration;
+      previewReady = false;
+      lockSourcePreview(false);
+      renderReviewBin();
+    });
+    sourcePreview.addEventListener('click', event => {
+      const button = event.target.closest('button');
+      if (!button) return;
+      if (button.dataset.previewStep) showSourcePreview(previewIndex + Number(button.dataset.previewStep));
+      if (button.dataset.previewSelection) saveSourceReview('user.selection', button.dataset.previewSelection);
+      if (button.dataset.previewRating != null) saveSourceReview('user.rating', Number(button.dataset.previewRating));
+    });
+    sourcePreview.addEventListener('keydown', event => {
+      if (event.target.matches('input,textarea,select') || event.ctrlKey || event.metaKey || event.altKey) return;
+      const actions = {
+        ArrowLeft: () => showSourcePreview(previewIndex - 1),
+        ArrowRight: () => showSourcePreview(previewIndex + 1),
+        i: () => saveSourceReview('user.selection', 'Include'),
+        x: () => saveSourceReview('user.selection', 'Exclude'),
+        u: () => saveSourceReview('user.selection', 'Unreviewed'),
+      };
+      const action = actions[event.key] || actions[event.key.toLowerCase()];
+      if (action) { event.preventDefault(); event.stopPropagation(); if (!event.repeat) action(); }
+    });
+    $('reviewBinGrid').addEventListener('click', event => {
+      const button = event.target.closest('[data-source-preview]');
+      if (!button) return;
+      event.stopImmediatePropagation();
+      previewQueue = filteredClips().slice();
+      sourcePreview.showModal();
+      showSourcePreview(previewQueue.findIndex(clip => clip.clip_id === button.dataset.sourcePreview));
+    }, true);
+
     function filteredClips() {
       const data = state.review.clipList;
       if (!data || !data.clips) return [];
       const binFilter = state.review.binFilter || '';
-      return data.clips.filter(c => !binFilter || c.bin_path === binFilter);
+      return data.clips.filter(c => (!binFilter || c.bin_path === binFilter) && matchesSourceSelection(c));
     }
 
     function renderReviewBin() {
@@ -8850,8 +9003,8 @@ HTML = r"""<!doctype html>
       }
       const clips = filteredClips();
       if (!clips.length) {
-        if (state.review.binFilter) {
-          if (summary) summary.textContent = `No analyzed clips in bin "${state.review.binFilter}".`;
+        if (state.review.binFilter || sourceSelectionFilter !== 'all') {
+          if (summary) summary.textContent = 'No analyzed clips match these filters.';
           if (grid) grid.innerHTML = '';
         } else {
           if (summary) summary.textContent = 'Nothing analyzed yet.';
@@ -8868,8 +9021,8 @@ HTML = r"""<!doctype html>
       Array.from(selected).forEach(id => { if (!visibleIds.has(id)) selected.delete(id); });
       if (summary) {
         const total = data.clips.length;
-        const base = state.review.binFilter
-          ? `${clips.length} of ${total} analyzed clip${total === 1 ? '' : 's'} · bin: ${state.review.binFilter}`
+        const base = state.review.binFilter || sourceSelectionFilter !== 'all'
+          ? `${clips.length} of ${total} analyzed clip${total === 1 ? '' : 's'}${state.review.binFilter ? ' · bin: ' + state.review.binFilter : ''}`
           : `${total} analyzed clip${total === 1 ? '' : 's'} in this project\u2019s analysis root.`;
         if (selected.size > 0) {
           summary.innerHTML = `<span>${escapeHtml(base)}</span>
@@ -8901,8 +9054,9 @@ HTML = r"""<!doctype html>
               <span class="select-box">${isSelected ? '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>' : ''}</span>
             </button>
             ${thumb}
+            <button type="button" class="secondary" data-source-preview="${escapeHtml(clip.clip_id || '')}">Enlarge / review</button>
             <div class="review-clip-card-name">${escapeHtml(clip.clip_name || '')}</div>
-            <div class="review-clip-card-meta"><span>${dur}</span><span>${shots}</span>${primaryUse}${chip}</div>
+            <div class="review-clip-card-meta"><span>${dur}</span><span>${shots}</span>${primaryUse}${chip}<span class="review-chip">${escapeHtml(clip.user_selection || 'Unreviewed')}</span></div>
             ${clip.clip_summary_oneliner ? `<div class="review-clip-card-oneliner">${escapeHtml(clip.clip_summary_oneliner)}</div>` : ''}
           </div>`;
         }).join('');
@@ -11481,6 +11635,7 @@ HTML = r"""<!doctype html>
       openClipDetail(card.dataset.clipId).catch(alertError);
     });
     $('reviewBinGrid').addEventListener('keydown', event => {
+      if (event.target.closest('[data-source-preview]')) return;
       if (event.key !== 'Enter' && event.key !== ' ') return;
       const card = event.target.closest('.review-clip-card');
       if (card && card.dataset.clipId) {
@@ -11886,6 +12041,10 @@ HTML = r"""<!doctype html>
       const q = $('reviewSearchInput').value.trim();
       if (q) runReviewSearch(q).catch(alertError);
     });
+    $('sourceSelectionFilter').addEventListener('change', event => {
+      sourceSelectionFilter = event.target.value;
+      renderReviewBin();
+    });
     // Bin dropdown.
     $('reviewBinFilter').addEventListener('change', event => {
       state.review.binFilter = event.target.value || '';
@@ -13433,7 +13592,10 @@ def _v2_clip_summary_card(clip_slug: str, clip_dir: str, report: Dict[str, Any])
     if not isinstance(oneliner, str) or not oneliner:
         oneliner = summary[:140] + ("…" if len(summary) > 140 else "")
     rep_index = _v2_pick_representative_frame_index(report)
+    corrections = _v2_read_corrections_for_dir(clip_dir).get("current", {})
+    selection = corrections.get(f"clip:{clip_block.get('clip_id')}:user.selection", {}).get("value", "Unreviewed")
     return {
+        "user_selection": selection,
         "clip_id": clip_block.get("clip_id"),
         "clip_slug": clip_slug,
         "clip_dir": clip_dir,
@@ -13938,6 +14100,12 @@ def apply_clip_correction(project_root: str, clip_id: str, body: Dict[str, Any])
     clip_dir = _v2_find_clip_dir(project_root, clip_id)
     if not clip_dir:
         return {"success": False, "error": f"No analyzed clip found for id={clip_id}"}
+    field_path = body.get("field_path") or body.get("fieldPath")
+    value = body.get("new_value") if "new_value" in body else body.get("newValue", body.get("value"))
+    if field_path == "user.selection" and value not in ("Include", "Exclude", "Unreviewed"):
+        return {"success": False, "error": "Selection must be Include, Exclude, or Unreviewed"}
+    if field_path == "user.rating" and (type(value) is not int or not 0 <= value <= 5):
+        return {"success": False, "error": "Rating must be an integer from 0 to 5"}
     from src.server import _v2_update_field
     entity_type = body.get("entity_type") or body.get("entityType") or "shot"
     params: Dict[str, Any] = dict(body)

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "3.3.0"
+VERSION = "3.4.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 377-tool granular server instead
 """
 
-VERSION = "3.3.0"
+VERSION = "3.4.0"
 
 import base64
 import os