davinci-resolve-mcp 2.23.0

package/src/utils/script_templates.py

@@ -0,0 +1,1193 @@
+#!/usr/bin/env python3
+"""Boilerplate generators for Resolve-page Lua/Python scripts.
+
+These generate scripts that get installed into Resolve's
+Fusion/Scripts/<category>/ directories so they appear in the
+Workspace → Scripts menu. Two template kinds:
+
+    'scaffold'    — minimal boilerplate with Resolve handle setup, ready
+                    for the LLM/user to fill in custom logic.
+    'media_rules' — the rules-and-variables DSL: declarative VARIABLES +
+                    RULES tables interpreted by an embedded engine that
+                    handles sources, extract patterns, transforms,
+                    targets, actions, conditions, dry-run, external CSV/
+                    JSON data, and per-rule metadata.
+
+See docs/authoring/script-plugin-authoring.md for the full DSL spec.
+"""
+
+from typing import Any, Dict, Optional
+
+
+def header(name: str, kind: str, language: str) -> str:
+    """MCP marker comment placed at the top of generated scripts."""
+    if language == "py":
+        comment = "#"
+    else:
+        comment = "--"
+    return (
+        f"{comment} @mcp-script name={name} kind={kind} language={language}\n"
+        f"{comment} Generated by davinci-resolve-mcp. Edit freely; the\n"
+        f"{comment} marker above only affects how the MCP `script_plugin\n"
+        f"{comment} list` action reports this file.\n\n"
+    )
+
+
+VALID_LANGUAGES = ("lua", "py")
+VALID_CATEGORIES = ("Edit", "Color", "Deliver", "Comp",
+                    "Tool", "Utility", "Views")
+
+
+# ─── scaffold template ────────────────────────────────────────────────────────
+
+def scaffold(name: str, options: Optional[Dict[str, Any]] = None) -> str:
+    """Minimal stub: connects to Resolve, gets project/media-pool/timeline
+    handles, defines an empty main() function for the user to fill in.
+
+    options:
+        language: 'lua' (default) | 'py'
+    """
+    options = options or {}
+    language = options.get("language", "lua")
+    if language not in VALID_LANGUAGES:
+        raise ValueError(f"Invalid language '{language}'. Valid: {list(VALID_LANGUAGES)}")
+
+    if language == "lua":
+        return header(name, "scaffold", "lua") + f'''-- {name}: starting scaffold for a Resolve-page Lua script.
+
+local resolve = Resolve()
+if not resolve then
+    print("[{name}] No Resolve handle.")
+    return
+end
+
+local pm = resolve:GetProjectManager()
+local project = pm:GetCurrentProject()
+if not project then
+    print("[{name}] No project open.")
+    return
+end
+
+local mp = project:GetMediaPool()
+local timeline = project:GetCurrentTimeline()
+
+-- ════════════════════════════════════════════════════════════════════
+-- Implement your logic here.
+-- ════════════════════════════════════════════════════════════════════
+local function main()
+    print("[{name}] Hello from Resolve " .. resolve:GetVersionString())
+    print("[{name}] Project: " .. project:GetName())
+end
+
+main()
+'''
+    # Python
+    return header(name, "scaffold", "py") + f'''"""{name}: starting scaffold for a Resolve-page Python script."""
+
+import sys
+
+try:
+    import DaVinciResolveScript as dvr_script
+except ImportError:
+    sys.exit("[{name}] DaVinciResolveScript not available.")
+
+resolve = dvr_script.scriptapp("Resolve")
+if not resolve:
+    sys.exit("[{name}] No Resolve handle.")
+
+pm = resolve.GetProjectManager()
+project = pm.GetCurrentProject()
+if not project:
+    sys.exit("[{name}] No project open.")
+
+mp = project.GetMediaPool()
+timeline = project.GetCurrentTimeline()
+
+
+# ════════════════════════════════════════════════════════════════════
+# Implement your logic here.
+# ════════════════════════════════════════════════════════════════════
+def main():
+    print(f"[{name}] Hello from Resolve {{resolve.GetVersionString()}}")
+    print(f"[{name}] Project: {{project.GetName()}}")
+
+
+main()
+'''
+
+
+# ─── media_rules template ────────────────────────────────────────────────────
+
+def _example_rules_lua() -> str:
+    """Default RULES table illustrating the most common patterns."""
+    return '''local RULES = {
+    -- Rule 1: Pull ISO date YYYY-MM-DD from anywhere in the file path
+    -- and set it as the clip's Shoot Date metadata.
+    {
+        name    = "Shoot Date from file path",
+        target  = "media_pool_clips",
+        extract = {
+            { source = "file_path", pattern = "DATE_PATTERN",
+              into = {"yr", "mo", "dy"} },
+        },
+        apply = {
+            { type = "set_metadata", field = "Shoot Date",
+              value = "{yr}-{mo}-{dy}" },
+        },
+    },
+
+    -- Rule 2: Reel Name from filename prefix (e.g. "A001_C002.mov" → "A001").
+    {
+        name    = "Reel Name from filename prefix",
+        target  = "media_pool_clips",
+        extract = {
+            { source = "filename", pattern = "REEL_PATTERN",
+              into = {"reel"} },
+        },
+        apply = {
+            { type = "set_clip_property", field = "Reel Name",
+              value = "{reel}" },
+        },
+    },
+
+    -- Rule 3: Scene from filename, organize into Scenes/Scene N bin.
+    {
+        name    = "Scene from filename + auto-bin",
+        target  = "media_pool_clips",
+        extract = {
+            { source = "filename", pattern = "SCENE_PATTERN",
+              into = {"scene"} },
+        },
+        apply = {
+            { type = "set_metadata", field = "Scene",
+              value = "Scene {scene | pad(2, '0')}" },
+            { type = "move_to_bin",
+              path = "Scenes/Scene {scene | pad(2, '0')}" },
+        },
+    },
+}
+'''
+
+
+def _example_rules_py() -> str:
+    return '''RULES = [
+    # Rule 1: Pull ISO date YYYY-MM-DD from anywhere in the file path
+    # and set it as the clip's Shoot Date metadata.
+    {
+        "name": "Shoot Date from file path",
+        "target": "media_pool_clips",
+        "extract": [
+            {"source": "file_path", "pattern": "DATE_PATTERN",
+             "into": ["yr", "mo", "dy"]},
+        ],
+        "apply": [
+            {"type": "set_metadata", "field": "Shoot Date",
+             "value": "{yr}-{mo}-{dy}"},
+        ],
+    },
+
+    # Rule 2: Reel Name from filename prefix.
+    {
+        "name": "Reel Name from filename prefix",
+        "target": "media_pool_clips",
+        "extract": [
+            {"source": "filename", "pattern": "REEL_PATTERN",
+             "into": ["reel"]},
+        ],
+        "apply": [
+            {"type": "set_clip_property", "field": "Reel Name",
+             "value": "{reel}"},
+        ],
+    },
+
+    # Rule 3: Scene from filename, organize into Scenes/Scene N bin.
+    {
+        "name": "Scene from filename + auto-bin",
+        "target": "media_pool_clips",
+        "extract": [
+            {"source": "filename", "pattern": "SCENE_PATTERN",
+             "into": ["scene"]},
+        ],
+        "apply": [
+            {"type": "set_metadata", "field": "Scene",
+             "value": "Scene {scene | pad(2, '0')}"},
+            {"type": "move_to_bin",
+             "path": "Scenes/Scene {scene | pad(2, '0')}"},
+        ],
+    },
+]
+'''
+
+
+def media_rules(name: str, options: Optional[Dict[str, Any]] = None) -> str:
+    """Rules-and-variables DSL script.
+
+    options:
+        language: 'lua' (default) | 'py'
+        rules:    list of rule dicts to embed (default: 3-rule example
+                  covering shoot-date / reel / scene workflows)
+        variables: dict of named values referenced by rules (default: regex
+                   patterns for date, reel, scene)
+        external_data: optional config for CSV/JSON lookup
+        dry_run:  default DRY_RUN value (default false)
+    """
+    options = options or {}
+    language = options.get("language", "lua")
+    if language not in VALID_LANGUAGES:
+        raise ValueError(f"Invalid language '{language}'. "
+                         f"Valid: {list(VALID_LANGUAGES)}")
+    dry_run = bool(options.get("dry_run", False))
+
+    if language == "lua":
+        return _media_rules_lua(name, options, dry_run)
+    return _media_rules_py(name, options, dry_run)
+
+
+def _media_rules_lua(name: str, options: Dict[str, Any], dry_run: bool) -> str:
+    rules_block = options.get("rules_lua") or _example_rules_lua()
+    return header(name, "media_rules", "lua") + f'''-- {name}: rules + variables DSL for declarative Resolve operations.
+
+-- ════════════════════════════════════════════════════════════════════
+-- VARIABLES — patterns, lookup tables, lookup keys. Edit freely.
+-- ════════════════════════════════════════════════════════════════════
+local VARIABLES = {{
+    DATE_PATTERN  = "(%d%d%d%d)-(%d%d)-(%d%d)",
+    REEL_PATTERN  = "^([A-Z]%d%d%d)[_%-]",
+    SCENE_PATTERN = "[Ss]cene[_%-]?(%d+)",
+    -- Lookup tables can be referenced by the `lookup` transform pipe.
+    CAMERA_TABLE  = {{ A = "A-Cam", B = "B-Cam", C = "C-Cam" }},
+}}
+
+-- ════════════════════════════════════════════════════════════════════
+-- ENGINE GLOBALS — runtime behavior switches.
+-- ════════════════════════════════════════════════════════════════════
+local DRY_RUN            = {str(dry_run).lower()}   -- true = report only, no mutations
+local LOG_LEVEL          = "normal"  -- "quiet" | "normal" | "verbose"
+local LIMIT_TO_FIRST_N   = nil       -- e.g. 5 to test on only first 5 items
+local BACKUP_BEFORE_RUN  = false     -- true = export project before mutating
+
+-- Optional external data (CSV/JSON); see docs/authoring/script-plugin-authoring.md
+local EXTERNAL_DATA = nil
+-- EXAMPLE:
+-- local EXTERNAL_DATA = {{
+--     csv = "/Volumes/Production/dit_log.csv",
+--     match_on = {{ source = "filename", column = "Filename",
+--                   strategy = "exact" }},  -- "exact" | "regex" | "fuzzy"
+-- }}
+
+-- ════════════════════════════════════════════════════════════════════
+-- RULES — declarative operations. Compose freely.
+-- ════════════════════════════════════════════════════════════════════
+{rules_block}
+-- ════════════════════════════════════════════════════════════════════
+-- ENGINE — interprets the above. Edit only if extending the DSL.
+-- ════════════════════════════════════════════════════════════════════
+{LUA_ENGINE}
+
+run_engine(VARIABLES, RULES, EXTERNAL_DATA, {{
+    dry_run = DRY_RUN,
+    log_level = LOG_LEVEL,
+    limit = LIMIT_TO_FIRST_N,
+    backup = BACKUP_BEFORE_RUN,
+}})
+'''
+
+
+def _media_rules_py(name: str, options: Dict[str, Any], dry_run: bool) -> str:
+    rules_block = options.get("rules_py") or _example_rules_py()
+    return header(name, "media_rules", "py") + f'''"""{name}: rules + variables DSL for declarative Resolve operations."""
+
+import os
+import re
+import sys
+import json
+import csv
+from datetime import datetime
+
+try:
+    import DaVinciResolveScript as dvr_script
+except ImportError:
+    sys.exit("[{name}] DaVinciResolveScript not available.")
+
+
+# ════════════════════════════════════════════════════════════════════
+# VARIABLES — patterns, lookup tables, lookup keys. Edit freely.
+# ════════════════════════════════════════════════════════════════════
+VARIABLES = {{
+    "DATE_PATTERN":  r"(\\d{{4}})-(\\d{{2}})-(\\d{{2}})",
+    "REEL_PATTERN":  r"^([A-Z]\\d{{3}})[_\\-]",
+    "SCENE_PATTERN": r"[Ss]cene[_\\-]?(\\d+)",
+    # Lookup tables can be referenced by the `lookup` transform pipe.
+    "CAMERA_TABLE":  {{"A": "A-Cam", "B": "B-Cam", "C": "C-Cam"}},
+}}
+
+
+# ════════════════════════════════════════════════════════════════════
+# ENGINE GLOBALS — runtime behavior switches.
+# ════════════════════════════════════════════════════════════════════
+DRY_RUN           = {dry_run}             # True = report only, no mutations
+LOG_LEVEL         = "normal"              # "quiet" | "normal" | "verbose"
+LIMIT_TO_FIRST_N  = None                  # e.g. 5 to test on first 5 only
+BACKUP_BEFORE_RUN = False                 # True = export project before mutating
+
+# Optional external data (CSV/JSON); see docs/authoring/script-plugin-authoring.md
+EXTERNAL_DATA = None
+# EXAMPLE:
+# EXTERNAL_DATA = {{
+#     "csv": "/Volumes/Production/dit_log.csv",
+#     "match_on": {{"source": "filename", "column": "Filename",
+#                   "strategy": "exact"}},  # "exact" | "regex" | "fuzzy"
+# }}
+
+
+# ════════════════════════════════════════════════════════════════════
+# RULES — declarative operations. Compose freely.
+# ════════════════════════════════════════════════════════════════════
+{rules_block}
+
+# ════════════════════════════════════════════════════════════════════
+# ENGINE — interprets the above. Edit only if extending the DSL.
+# ════════════════════════════════════════════════════════════════════
+{PY_ENGINE}
+
+
+run_engine(VARIABLES, RULES, EXTERNAL_DATA, {{
+    "dry_run": DRY_RUN,
+    "log_level": LOG_LEVEL,
+    "limit": LIMIT_TO_FIRST_N,
+    "backup": BACKUP_BEFORE_RUN,
+}})
+'''
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# LUA ENGINE
+# ═══════════════════════════════════════════════════════════════════════════════
+
+LUA_ENGINE = r"""
+local function log(level, msg)
+    if LOG_LEVEL == "quiet" then return end
+    if LOG_LEVEL == "normal" and level == "debug" then return end
+    print("[mcp-script] " .. msg)
+end
+
+-- ─── External data loaders ──────────────────────────────────────────────────
+
+local function load_csv(path)
+    local f = io.open(path, "r")
+    if not f then return nil, "could not open " .. path end
+    local rows, headers = {}, nil
+    for line in f:lines() do
+        local fields = {}
+        for v in (line .. ","):gmatch("([^,]*),") do
+            table.insert(fields, v:gsub('^"(.-)"$', "%1"))
+        end
+        if not headers then
+            headers = fields
+        else
+            local row = {}
+            for i, h in ipairs(headers) do row[h] = fields[i] end
+            table.insert(rows, row)
+        end
+    end
+    f:close()
+    return rows
+end
+
+local function load_json(path)
+    local f = io.open(path, "r")
+    if not f then return nil end
+    local content = f:read("*a")
+    f:close()
+    -- Resolve's Lua includes bmd which has json support
+    if bmd and bmd.readstring then
+        local ok, parsed = pcall(bmd.readstring, content)
+        if ok then return parsed end
+    end
+    return nil
+end
+
+-- ─── Transform pipes ────────────────────────────────────────────────────────
+
+local function levenshtein(a, b)
+    if a == b then return 0 end
+    if #a == 0 then return #b end
+    if #b == 0 then return #a end
+    local prev = {}
+    for j = 0, #b do prev[j] = j end
+    for i = 1, #a do
+        local cur = {[0] = i}
+        for j = 1, #b do
+            local cost = (a:sub(i,i) == b:sub(j,j)) and 0 or 1
+            cur[j] = math.min(prev[j] + 1, cur[j-1] + 1, prev[j-1] + cost)
+        end
+        prev = cur
+    end
+    return prev[#b]
+end
+
+local function apply_pipe(value, pipe, vars)
+    local op, arg = pipe:match("^(%w+)%s*%(?(.*)%)?$")
+    op = op or pipe
+    if op == "upper" then return tostring(value):upper()
+    elseif op == "lower" then return tostring(value):lower()
+    elseif op == "title" then
+        return tostring(value):gsub("(%a)(%w*)", function(a, b) return a:upper() .. b:lower() end)
+    elseif op == "slug" then
+        return tostring(value):lower():gsub("%s+", "_"):gsub("[^%w_%-]", "")
+    elseif op == "pad" then
+        local n, ch = arg:match("(%d+)%s*,?%s*['\"]?(.?)['\"]?")
+        n = tonumber(n) or 2; ch = (ch ~= "" and ch) or "0"
+        local s = tostring(value)
+        while #s < n do s = ch .. s end
+        return s
+    elseif op == "lookup" then
+        local tbl_name = arg:gsub("['\"]", ""):gsub("%s", "")
+        local tbl = vars[tbl_name]
+        if type(tbl) == "table" and tbl[value] ~= nil then return tbl[value] end
+        return value
+    elseif op == "add" or op == "sub" or op == "mul" or op == "div" then
+        local n = tonumber(value) or 0
+        local k = tonumber(arg) or 0
+        if op == "add" then return tostring(n + k)
+        elseif op == "sub" then return tostring(n - k)
+        elseif op == "mul" then return tostring(n * k)
+        elseif op == "div" then return tostring(k ~= 0 and (n / k) or 0) end
+    elseif op == "date" then
+        -- arg is a strftime format; assumes value is "Y-m-d" or similar
+        return tostring(value)  -- pass-through; Lua os.date is awkward to chain
+    end
+    return value
+end
+
+local function substitute(template, captures, vars)
+    if type(template) ~= "string" then return template end
+    return (template:gsub("{([^}]+)}", function(expr)
+        local parts, value = {}, nil
+        for part in expr:gmatch("[^|]+") do
+            table.insert(parts, (part:gsub("^%s+", ""):gsub("%s+$", "")))
+        end
+        local var_name = parts[1]
+        -- Special prefix "external_data:..."
+        if var_name:match("^external_data:") then
+            local col = var_name:sub(15)
+            value = captures.__external_row and captures.__external_row[col] or ""
+        else
+            value = captures[var_name]
+        end
+        if value == nil then return "{" .. expr .. "}" end
+        for i = 2, #parts do
+            value = apply_pipe(value, parts[i], vars)
+        end
+        return tostring(value)
+    end))
+end
+
+-- ─── Source resolvers ───────────────────────────────────────────────────────
+
+local function basename(p)
+    return p and (p:match("([^/\\]+)$") or p) or ""
+end
+
+local function dirname(p)
+    return p and (p:match("(.+)[/\\][^/\\]+$") or "") or ""
+end
+
+local function resolve_source(spec, item, project, mp, captures)
+    if spec == "file_path" then return item:GetClipProperty("File Path") or ""
+    elseif spec == "filename" then return basename(item:GetClipProperty("File Path") or "")
+    elseif spec == "dirname" then return basename(dirname(item:GetClipProperty("File Path") or ""))
+    elseif spec == "parent_dir" then return basename(dirname(dirname(item:GetClipProperty("File Path") or "")))
+    elseif spec == "grandparent_dir" then return basename(dirname(dirname(dirname(item:GetClipProperty("File Path") or ""))))
+    elseif spec == "file_extension" then
+        local fp = item:GetClipProperty("File Path") or ""
+        return fp:match("%.([^.]+)$") or ""
+    elseif spec == "bin_name" then
+        return captures.__bin_name or ""
+    elseif spec == "media_pool_path" then
+        return captures.__bin_path or ""
+    elseif spec == "static_value" then
+        return captures.__static or ""
+    elseif spec:match("^clip_property:") then
+        return item:GetClipProperty(spec:sub(15)) or ""
+    elseif spec:match("^metadata:") then
+        return item:GetMetadata(spec:sub(10)) or ""
+    elseif spec:match("^embedded_metadata:") then
+        return item:GetMetadata(spec:sub(19)) or ""
+    elseif spec:match("^camera_metadata:") then
+        return item:GetMetadata(spec:sub(17)) or ""
+    elseif spec:match("^previous_capture:") then
+        return captures[spec:sub(18)] or ""
+    elseif spec == "clip_duration" then return item:GetClipProperty("Duration") or ""
+    elseif spec == "clip_resolution" then return item:GetClipProperty("Resolution") or ""
+    elseif spec == "frame_rate" then return item:GetClipProperty("FPS") or ""
+    elseif spec == "codec" then return item:GetClipProperty("Video Codec") or ""
+    elseif spec == "audio_channels" then return item:GetClipProperty("Audio Ch") or ""
+    elseif spec == "audio_format" then return item:GetClipProperty("Audio Codec") or ""
+    elseif spec == "start_tc" then return item:GetClipProperty("Start TC") or ""
+    elseif spec == "end_tc" then return item:GetClipProperty("End TC") or ""
+    elseif spec == "creation_time" or spec == "modification_time" then
+        return item:GetClipProperty("Date Created") or ""  -- closest available
+    end
+    return ""
+end
+
+-- ─── Target resolvers ───────────────────────────────────────────────────────
+
+local function walk_bins(folder, prefix, out)
+    out = out or {}
+    prefix = prefix or ""
+    for _, clip in ipairs(folder:GetClipList() or {}) do
+        table.insert(out, {item = clip, bin_path = prefix, bin_name = folder:GetName()})
+    end
+    for _, sub in ipairs(folder:GetSubFolderList() or {}) do
+        local p = (prefix ~= "" and (prefix .. "/") or "") .. sub:GetName()
+        walk_bins(sub, p, out)
+    end
+    return out
+end
+
+local function resolve_target(spec, project, mp)
+    local tl = project:GetCurrentTimeline()
+    if spec == "media_pool_clips" then
+        return walk_bins(mp:GetRootFolder(), "")
+    elseif spec == "current_bin_clips" then
+        local cur = mp:GetCurrentFolder()
+        local out = {}
+        for _, c in ipairs(cur:GetClipList() or {}) do
+            table.insert(out, {item = c, bin_path = "", bin_name = cur:GetName()})
+        end
+        return out
+    elseif spec:match("^bin_path:") then
+        local path = spec:sub(10)
+        local folder = mp:GetRootFolder()
+        for seg in path:gmatch("[^/]+") do
+            local found = nil
+            for _, sub in ipairs(folder:GetSubFolderList() or {}) do
+                if sub:GetName() == seg then found = sub; break end
+            end
+            if not found then return {} end
+            folder = found
+        end
+        local out = {}
+        for _, c in ipairs(folder:GetClipList() or {}) do
+            table.insert(out, {item = c, bin_path = path, bin_name = folder:GetName()})
+        end
+        return out
+    elseif spec == "selected_clips" then
+        local sel = mp:GetSelectedClips() or {}
+        local out = {}
+        for _, c in ipairs(sel) do table.insert(out, {item = c, bin_path = "", bin_name = ""}) end
+        return out
+    elseif spec == "timeline_items" or spec == "selected_timeline_items" then
+        if not tl then return {} end
+        local out = {}
+        for trk = 1, tl:GetTrackCount("video") do
+            for _, ti in ipairs(tl:GetItemListInTrack("video", trk) or {}) do
+                table.insert(out, {item = ti, bin_path = "", bin_name = "", track = trk})
+            end
+        end
+        return out
+    elseif spec:match("^timeline_items_in_track:") then
+        if not tl then return {} end
+        local n = tonumber(spec:sub(25)) or 1
+        local out = {}
+        for _, ti in ipairs(tl:GetItemListInTrack("video", n) or {}) do
+            table.insert(out, {item = ti, bin_path = "", bin_name = "", track = n})
+        end
+        return out
+    end
+    return {}
+end
+
+-- ─── Action handlers ────────────────────────────────────────────────────────
+
+local function get_or_create_bin(mp, path)
+    local folder = mp:GetRootFolder()
+    if path == "" or path == nil then return folder end
+    for seg in path:gmatch("[^/]+") do
+        local found = nil
+        for _, sub in ipairs(folder:GetSubFolderList() or {}) do
+            if sub:GetName() == seg then found = sub; break end
+        end
+        if not found then
+            found = mp:AddSubFolder(folder, seg)
+        end
+        if not found then return nil end
+        folder = found
+    end
+    return folder
+end
+
+local function run_action(action, item, captures, vars, project, mp, dry)
+    local typ = action.type
+    if typ == "set_metadata" then
+        local v = substitute(action.value, captures, vars)
+        if not dry then item:SetMetadata(action.field, v) end
+        return string.format("set_metadata %s = %q", action.field, v)
+    elseif typ == "set_clip_property" then
+        local v = substitute(action.value, captures, vars)
+        if not dry then item:SetClipProperty(action.field, v) end
+        return string.format("set_clip_property %s = %q", action.field, v)
+    elseif typ == "rename_clip" then
+        local v = substitute(action.value, captures, vars)
+        if not dry then item:SetClipProperty("Clip Name", v) end
+        return string.format("rename → %q", v)
+    elseif typ == "move_to_bin" then
+        local p = substitute(action.path, captures, vars)
+        if not dry then
+            local target = get_or_create_bin(mp, p)
+            if target then mp:MoveClips({item}, target) end
+        end
+        return string.format("move_to_bin %q", p)
+    elseif typ == "set_clip_color" then
+        local v = substitute(action.color or action.value, captures, vars)
+        if not dry then item:SetClipColor(v) end
+        return string.format("set_clip_color %s", v)
+    elseif typ == "flag_clip" then
+        local v = substitute(action.color or action.value, captures, vars)
+        if not dry then item:AddFlag(v) end
+        return string.format("flag_clip %s", v)
+    elseif typ == "add_keyword" then
+        local v = substitute(action.keyword or action.value, captures, vars)
+        if not dry then item:AddKeyword(v) end
+        return string.format("add_keyword %q", v)
+    elseif typ == "add_marker" then
+        local frame = tonumber(substitute(tostring(action.frame or 0), captures, vars)) or 0
+        local color = substitute(action.color or "Blue", captures, vars)
+        local note = substitute(action.note or "", captures, vars)
+        local name = substitute(action.name or note, captures, vars)
+        if not dry then item:AddMarker(frame, color, name, note, action.duration or 1) end
+        return string.format("marker @%d %s %q", frame, color, note)
+    elseif typ == "apply_lut" then
+        local v = substitute(action.lut_path or action.value, captures, vars)
+        if not dry then item:SetClipProperty("Input LUT", v) end
+        return string.format("apply_lut %q", v)
+    elseif typ == "set_in_out" then
+        if not dry then
+            if action.in_point then item:SetClipProperty("In Point", tostring(action.in_point)) end
+            if action.out_point then item:SetClipProperty("Out Point", tostring(action.out_point)) end
+        end
+        return string.format("set_in_out in=%s out=%s", tostring(action.in_point), tostring(action.out_point))
+    elseif typ == "tag_for_review" then
+        local v = substitute(action.value or "needs_review", captures, vars)
+        if not dry then item:SetMetadata(action.field or "Description", v) end
+        return string.format("tag_for_review %q", v)
+    elseif typ == "notify" or typ == "print" then
+        local msg = substitute(action.message or action.value or "", captures, vars)
+        log("normal", msg)
+        return "notify"
+    end
+    return "(unknown action: " .. tostring(typ) .. ")"
+end
+
+-- ─── External data matching ────────────────────────────────────────────────
+
+local function find_external_row(rows, match_cfg, item, captures, vars)
+    if not rows or #rows == 0 then return nil end
+    local key_value = resolve_source(match_cfg.source, item, nil, nil, captures)
+    if not key_value or key_value == "" then return nil end
+    local strategy = match_cfg.strategy or "exact"
+    local column = match_cfg.column
+    if strategy == "exact" then
+        for _, row in ipairs(rows) do
+            if row[column] == key_value then return row end
+        end
+    elseif strategy == "regex" then
+        for _, row in ipairs(rows) do
+            if row[column] and key_value:match(row[column]) then return row end
+        end
+    elseif strategy == "fuzzy" then
+        local best, best_dist = nil, math.huge
+        for _, row in ipairs(rows) do
+            if row[column] then
+                local d = levenshtein(key_value:lower(), tostring(row[column]):lower())
+                if d < best_dist then best, best_dist = row, d end
+            end
+        end
+        return best  -- lowest-distance row even if not exact
+    end
+    return nil
+end
+
+-- ─── Main loop ─────────────────────────────────────────────────────────────
+
+function run_engine(vars, rules, external_cfg, opts)
+    local resolve = Resolve()
+    if not resolve then log("normal", "No Resolve handle.") return end
+    local pm = resolve:GetProjectManager()
+    local project = pm:GetCurrentProject()
+    if not project then log("normal", "No project open.") return end
+    local mp = project:GetMediaPool()
+
+    if opts.backup and not opts.dry_run then
+        local bak = "/tmp/" .. project:GetName() .. "_mcp_backup.drp"
+        pm:ExportProject(project:GetName(), bak)
+        log("normal", "Backup written to " .. bak)
+    end
+
+    -- Load external data once
+    local external_rows = nil
+    if external_cfg then
+        if external_cfg.csv then external_rows = load_csv(external_cfg.csv) end
+        if external_cfg.json then external_rows = load_json(external_cfg.json) end
+        if external_rows then
+            log("normal", "Loaded " .. #external_rows .. " external data rows")
+        end
+    end
+
+    local matched_set = {}
+    local total_actions, dry = 0, opts.dry_run
+
+    for ri, rule in ipairs(rules) do
+        if rule.enabled == false then
+            log("verbose", "skipping disabled rule: " .. (rule.name or ri))
+        else
+            local items = resolve_target(rule.target, project, mp)
+            local count = 0
+            for ii, entry in ipairs(items) do
+                if opts.limit and ii > opts.limit then break end
+                local item = entry.item
+                if rule.target == "unmatched_clips" and matched_set[item] then
+                    -- skip
+                else
+                    local captures = {
+                        __bin_path = entry.bin_path,
+                        __bin_name = entry.bin_name,
+                        __static = "",
+                    }
+                    -- External data row
+                    if external_rows and external_cfg.match_on then
+                        captures.__external_row = find_external_row(
+                            external_rows, external_cfg.match_on,
+                            item, captures, vars)
+                    end
+                    -- Extract patterns
+                    local matched = true
+                    for _, ex in ipairs(rule.extract or {}) do
+                        local src_value = resolve_source(ex.source, item, project, mp, captures)
+                        local pat = vars[ex.pattern] or ex.pattern
+                        local results = {string.match(src_value, pat)}
+                        if #results == 0 then
+                            matched = false; break
+                        end
+                        for i, name in ipairs(ex.into or {}) do
+                            captures[name] = results[i]
+                        end
+                    end
+                    if matched and rule.condition then
+                        local ok, res = pcall(rule.condition, captures, vars)
+                        if not ok or not res then matched = false end
+                    end
+                    if matched or #(rule.extract or {}) == 0 then
+                        for _, action in ipairs(rule.apply or {}) do
+                            local desc = run_action(action, item, captures, vars,
+                                                     project, mp, dry)
+                            log("verbose", string.format("  rule[%s] %s", rule.name or ri, desc))
+                            total_actions = total_actions + 1
+                        end
+                        matched_set[item] = true
+                        count = count + 1
+                        if rule.stop_on_match then break end
+                    end
+                end
+            end
+            log("normal", string.format("rule[%s] matched %d items", rule.name or ri, count))
+        end
+    end
+
+    log("normal", string.format("Done. %s%d action(s).",
+        dry and "[DRY-RUN] would have run " or "Ran ", total_actions))
+end
+"""
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# PYTHON ENGINE
+# ═══════════════════════════════════════════════════════════════════════════════
+
+PY_ENGINE = r'''
+def _log(level, msg, opts):
+    if opts.get("log_level") == "quiet":
+        return
+    if opts.get("log_level", "normal") == "normal" and level == "debug":
+        return
+    print(f"[mcp-script] {msg}")
+
+
+def _load_csv(path):
+    with open(path, newline="", encoding="utf-8") as f:
+        return list(csv.DictReader(f))
+
+
+def _load_json(path):
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    if isinstance(data, dict):
+        return [{"_key": k, **(v if isinstance(v, dict) else {"value": v})}
+                for k, v in data.items()]
+    return data
+
+
+def _levenshtein(a, b):
+    if a == b: return 0
+    if not a: return len(b)
+    if not b: return len(a)
+    prev = list(range(len(b) + 1))
+    for i, ca in enumerate(a, start=1):
+        cur = [i] + [0] * len(b)
+        for j, cb in enumerate(b, start=1):
+            cost = 0 if ca == cb else 1
+            cur[j] = min(prev[j] + 1, cur[j-1] + 1, prev[j-1] + cost)
+        prev = cur
+    return prev[-1]
+
+
+def _apply_pipe(value, pipe, vars):
+    pipe = pipe.strip()
+    m = re.match(r"^(\w+)\s*\(?(.*?)\)?$", pipe)
+    op = m.group(1) if m else pipe
+    arg = m.group(2) if m else ""
+    sval = str(value)
+    if op == "upper": return sval.upper()
+    if op == "lower": return sval.lower()
+    if op == "title": return sval.title()
+    if op == "slug":  return re.sub(r"[^\w\-]", "", sval.lower().replace(" ", "_"))
+    if op == "pad":
+        m2 = re.match(r"\s*(\d+)\s*,?\s*['\"]?(.?)['\"]?", arg)
+        n = int(m2.group(1)) if m2 else 2
+        ch = m2.group(2) if m2 and m2.group(2) else "0"
+        return sval.rjust(n, ch)
+    if op == "lookup":
+        tbl_name = arg.strip().strip("'\"")
+        tbl = vars.get(tbl_name)
+        if isinstance(tbl, dict) and value in tbl:
+            return tbl[value]
+        return value
+    if op in ("add", "sub", "mul", "div"):
+        try:
+            n = float(value); k = float(arg)
+        except (ValueError, TypeError):
+            return value
+        result = {"add": n + k, "sub": n - k, "mul": n * k,
+                  "div": n / k if k else 0}[op]
+        return str(int(result) if result.is_integer() else result)
+    if op == "date":
+        try:
+            d = datetime.strptime(sval, "%Y-%m-%d")
+            return d.strftime(arg.strip("'\""))
+        except ValueError:
+            return value
+    return value
+
+
+def _substitute(template, captures, vars):
+    if not isinstance(template, str):
+        return template
+    def repl(m):
+        expr = m.group(1)
+        parts = [p.strip() for p in expr.split("|")]
+        var_name = parts[0]
+        if var_name.startswith("external_data:"):
+            col = var_name[14:]
+            row = captures.get("__external_row") or {}
+            value = row.get(col, "")
+        else:
+            value = captures.get(var_name)
+        if value is None:
+            return "{" + expr + "}"
+        for pipe in parts[1:]:
+            value = _apply_pipe(value, pipe, vars)
+        return str(value)
+    return re.sub(r"\{([^}]+)\}", repl, template)
+
+
+def _basename(p):
+    return os.path.basename(p) if p else ""
+
+
+def _resolve_source(spec, item, captures):
+    if spec == "static_value":
+        return captures.get("__static", "")
+    if spec == "bin_name":
+        return captures.get("__bin_name", "")
+    if spec == "media_pool_path":
+        return captures.get("__bin_path", "")
+    if spec.startswith("clip_property:"):
+        return item.GetClipProperty(spec[14:]) or ""
+    if spec.startswith("metadata:") or spec.startswith("embedded_metadata:") or spec.startswith("camera_metadata:"):
+        key = spec.split(":", 1)[1]
+        return item.GetMetadata(key) or ""
+    if spec.startswith("previous_capture:"):
+        return captures.get(spec[17:], "")
+
+    fp = item.GetClipProperty("File Path") or ""
+    if spec == "file_path":     return fp
+    if spec == "filename":      return os.path.basename(fp)
+    if spec == "dirname":       return os.path.basename(os.path.dirname(fp))
+    if spec == "parent_dir":    return os.path.basename(os.path.dirname(os.path.dirname(fp)))
+    if spec == "grandparent_dir":
+        return os.path.basename(os.path.dirname(os.path.dirname(os.path.dirname(fp))))
+    if spec == "file_extension":
+        return os.path.splitext(fp)[1].lstrip(".")
+
+    prop_map = {
+        "clip_duration": "Duration",
+        "clip_resolution": "Resolution",
+        "frame_rate": "FPS",
+        "codec": "Video Codec",
+        "audio_channels": "Audio Ch",
+        "audio_format": "Audio Codec",
+        "start_tc": "Start TC",
+        "end_tc": "End TC",
+        "creation_time": "Date Created",
+        "modification_time": "Date Modified",
+    }
+    if spec in prop_map:
+        return item.GetClipProperty(prop_map[spec]) or ""
+    return ""
+
+
+def _walk_bins(folder, prefix=""):
+    out = []
+    for clip in (folder.GetClipList() or []):
+        out.append({"item": clip, "bin_path": prefix, "bin_name": folder.GetName()})
+    for sub in (folder.GetSubFolderList() or []):
+        p = (prefix + "/" if prefix else "") + sub.GetName()
+        out.extend(_walk_bins(sub, p))
+    return out
+
+
+def _resolve_target(spec, project, mp):
+    tl = project.GetCurrentTimeline()
+    if spec == "media_pool_clips":
+        return _walk_bins(mp.GetRootFolder())
+    if spec == "current_bin_clips":
+        cur = mp.GetCurrentFolder()
+        return [{"item": c, "bin_path": "", "bin_name": cur.GetName()}
+                for c in (cur.GetClipList() or [])]
+    if spec.startswith("bin_path:"):
+        path = spec[9:]
+        folder = mp.GetRootFolder()
+        for seg in path.split("/"):
+            found = None
+            for sub in (folder.GetSubFolderList() or []):
+                if sub.GetName() == seg:
+                    found = sub; break
+            if not found: return []
+            folder = found
+        return [{"item": c, "bin_path": path, "bin_name": folder.GetName()}
+                for c in (folder.GetClipList() or [])]
+    if spec == "selected_clips":
+        return [{"item": c, "bin_path": "", "bin_name": ""}
+                for c in (mp.GetSelectedClips() or [])]
+    if spec in ("timeline_items", "selected_timeline_items"):
+        if not tl: return []
+        out = []
+        for trk in range(1, (tl.GetTrackCount("video") or 0) + 1):
+            for ti in (tl.GetItemListInTrack("video", trk) or []):
+                out.append({"item": ti, "bin_path": "", "bin_name": "", "track": trk})
+        return out
+    if spec.startswith("timeline_items_in_track:"):
+        if not tl: return []
+        n = int(spec[24:]) if spec[24:].isdigit() else 1
+        return [{"item": ti, "bin_path": "", "bin_name": "", "track": n}
+                for ti in (tl.GetItemListInTrack("video", n) or [])]
+    return []
+
+
+def _get_or_create_bin(mp, path):
+    folder = mp.GetRootFolder()
+    if not path:
+        return folder
+    for seg in path.split("/"):
+        found = None
+        for sub in (folder.GetSubFolderList() or []):
+            if sub.GetName() == seg:
+                found = sub; break
+        if not found:
+            found = mp.AddSubFolder(folder, seg)
+        if not found:
+            return None
+        folder = found
+    return folder
+
+
+def _run_action(action, item, captures, vars, project, mp, dry):
+    typ = action.get("type")
+    if typ == "set_metadata":
+        v = _substitute(action["value"], captures, vars)
+        if not dry: item.SetMetadata(action["field"], v)
+        return f'set_metadata {action["field"]} = {v!r}'
+    if typ == "set_clip_property":
+        v = _substitute(action["value"], captures, vars)
+        if not dry: item.SetClipProperty(action["field"], v)
+        return f'set_clip_property {action["field"]} = {v!r}'
+    if typ == "rename_clip":
+        v = _substitute(action["value"], captures, vars)
+        if not dry: item.SetClipProperty("Clip Name", v)
+        return f"rename → {v!r}"
+    if typ == "move_to_bin":
+        p = _substitute(action["path"], captures, vars)
+        if not dry:
+            target = _get_or_create_bin(mp, p)
+            if target: mp.MoveClips([item], target)
+        return f"move_to_bin {p!r}"
+    if typ == "set_clip_color":
+        v = _substitute(action.get("color") or action["value"], captures, vars)
+        if not dry: item.SetClipColor(v)
+        return f"set_clip_color {v}"
+    if typ == "flag_clip":
+        v = _substitute(action.get("color") or action["value"], captures, vars)
+        if not dry: item.AddFlag(v)
+        return f"flag_clip {v}"
+    if typ == "add_keyword":
+        v = _substitute(action.get("keyword") or action["value"], captures, vars)
+        if not dry: item.AddKeyword(v)
+        return f"add_keyword {v!r}"
+    if typ == "add_marker":
+        frame = int(_substitute(str(action.get("frame", 0)), captures, vars) or 0)
+        color = _substitute(action.get("color", "Blue"), captures, vars)
+        note = _substitute(action.get("note", ""), captures, vars)
+        name = _substitute(action.get("name", note), captures, vars)
+        if not dry:
+            item.AddMarker(frame, color, name, note, action.get("duration", 1))
+        return f"marker @{frame} {color} {note!r}"
+    if typ == "apply_lut":
+        v = _substitute(action.get("lut_path") or action["value"], captures, vars)
+        if not dry: item.SetClipProperty("Input LUT", v)
+        return f"apply_lut {v!r}"
+    if typ == "set_in_out":
+        if not dry:
+            if "in_point" in action:
+                item.SetClipProperty("In Point", str(action["in_point"]))
+            if "out_point" in action:
+                item.SetClipProperty("Out Point", str(action["out_point"]))
+        return f"set_in_out in={action.get('in_point')} out={action.get('out_point')}"
+    if typ == "tag_for_review":
+        v = _substitute(action.get("value", "needs_review"), captures, vars)
+        if not dry: item.SetMetadata(action.get("field", "Description"), v)
+        return f"tag_for_review {v!r}"
+    if typ in ("notify", "print"):
+        msg = _substitute(action.get("message") or action.get("value", ""), captures, vars)
+        print(f"[mcp-script] {msg}")
+        return "notify"
+    return f"(unknown action: {typ})"
+
+
+def _find_external_row(rows, match_cfg, item, captures):
+    if not rows: return None
+    key = _resolve_source(match_cfg["source"], item, captures)
+    if not key: return None
+    strategy = match_cfg.get("strategy", "exact")
+    col = match_cfg["column"]
+    if strategy == "exact":
+        for row in rows:
+            if row.get(col) == key: return row
+    elif strategy == "regex":
+        for row in rows:
+            pat = row.get(col)
+            if pat and re.search(pat, key): return row
+    elif strategy == "fuzzy":
+        best, best_d = None, float("inf")
+        for row in rows:
+            v = row.get(col)
+            if v:
+                d = _levenshtein(key.lower(), str(v).lower())
+                if d < best_d:
+                    best, best_d = row, d
+        return best
+    return None
+
+
+def run_engine(vars, rules, external_cfg, opts):
+    resolve = dvr_script.scriptapp("Resolve")
+    if not resolve:
+        _log("normal", "No Resolve handle.", opts); return
+    pm = resolve.GetProjectManager()
+    project = pm.GetCurrentProject()
+    if not project:
+        _log("normal", "No project open.", opts); return
+    mp = project.GetMediaPool()
+
+    if opts.get("backup") and not opts.get("dry_run"):
+        bak = f"/tmp/{project.GetName()}_mcp_backup.drp"
+        pm.ExportProject(project.GetName(), bak)
+        _log("normal", f"Backup written to {bak}", opts)
+
+    external_rows = None
+    if external_cfg:
+        if external_cfg.get("csv"):
+            external_rows = _load_csv(external_cfg["csv"])
+        elif external_cfg.get("json"):
+            external_rows = _load_json(external_cfg["json"])
+        if external_rows:
+            _log("normal", f"Loaded {len(external_rows)} external rows", opts)
+
+    matched_set = set()
+    total = 0
+    dry = opts.get("dry_run", False)
+
+    for ri, rule in enumerate(rules):
+        if rule.get("enabled") is False:
+            continue
+        items = _resolve_target(rule["target"], project, mp)
+        count = 0
+        for ii, entry in enumerate(items):
+            if opts.get("limit") and ii >= opts["limit"]:
+                break
+            item = entry["item"]
+            if rule["target"] == "unmatched_clips" and id(item) in matched_set:
+                continue
+            captures = {
+                "__bin_path": entry.get("bin_path", ""),
+                "__bin_name": entry.get("bin_name", ""),
+                "__static": "",
+            }
+            if external_rows and external_cfg.get("match_on"):
+                captures["__external_row"] = _find_external_row(
+                    external_rows, external_cfg["match_on"], item, captures)
+
+            matched = True
+            for ex in (rule.get("extract") or []):
+                src_value = _resolve_source(ex["source"], item, captures)
+                pat = vars.get(ex["pattern"], ex["pattern"])
+                m = re.search(pat, src_value)
+                if not m:
+                    matched = False; break
+                for i, name in enumerate(ex.get("into", []), start=1):
+                    try:
+                        captures[name] = m.group(i)
+                    except IndexError:
+                        captures[name] = ""
+
+            if matched and rule.get("condition"):
+                try:
+                    if not rule["condition"](captures, vars):
+                        matched = False
+                except Exception:
+                    matched = False
+
+            if matched or not (rule.get("extract")):
+                for action in (rule.get("apply") or []):
+                    desc = _run_action(action, item, captures, vars,
+                                        project, mp, dry)
+                    _log("verbose", f'  rule[{rule.get("name", ri)}] {desc}', opts)
+                    total += 1
+                matched_set.add(id(item))
+                count += 1
+                if rule.get("stop_on_match"):
+                    break
+        _log("normal",
+             f'rule[{rule.get("name", ri)}] matched {count} items', opts)
+
+    _log("normal",
+         ("[DRY-RUN] would have run " if dry else "Ran ")
+         + f"{total} action(s).", opts)
+'''
+
+
+TEMPLATES = {
+    "scaffold": scaffold,
+    "media_rules": media_rules,
+}