davinci-resolve-mcp 2.101.0 → 2.103.0

package/CHANGELOG.md

@@ -2,6 +2,130 @@
 
 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.103.0
+
+**An unreachable Resolve no longer ends the work.** The interchange authoring that can
+write an importable timeline has been in this repository the whole time, one process
+away, while a connection failure stopped everything. This routes to it.
+
+### Added
+
+- **`timeline author_offline`** — write an importable timeline from a file-path clip plan
+  with no Resolve connection. Served **above** the connection check, because it exists
+  for the case where there is none. Targets in preference order:
+  - **`drt`** (default) — Resolve-native, carries track structure. Stamped at project
+    version 17 (Resolve 21.0); older builds need the advanced server's
+    `drt(action='downgrade')`. Verified map: 18.0.4 -> 11, 19.1.x -> 14, 21.0 -> 17.
+  - **`otio`** — round-trips through this repo's own parser and carries gaps, per-clip
+    speed, and transitions. The target to pick when the plan has retimes.
+  - **`edl`** — CMX3600: video cuts and M2 speed, nothing else.
+- **`timeline offline_fallback_capabilities`** — whether authoring is available here, and
+  why not if it is not.
+- **`offline_alternative` on every not-connected error** — naming what could be produced.
+
+### It is an offer, never a substitute
+
+A caller who asked to build a timeline *in Resolve* has not succeeded because a file was
+written somewhere. The connection error stays an error, the block says outright that
+authoring does not complete what failed, and nothing is authored unless it is asked for.
+A test asserts both halves, because an offer that reads as success is worse than no offer.
+
+### Two silent failures, now named
+
+- `media_tc_origin_assumed` — OTIO source frames are **timecode-absolute**. An event with
+  no media timecode origin imports as an *empty* timeline: the file opens, nothing
+  appears, and no error is raised. Every event that had to assume an origin is named,
+  with the fix (`media_start_tc_frame` per clip).
+- `retimes_flattened` — a `.drt` carries no per-clip speed field, so retimes flatten to
+  100% forward. Every event that lost one is named, with OTIO as the target that keeps it.
+
+### Fixed
+
+`_check()` emitted its own flat `NOT_CONNECTED` error asserting Resolve might not be
+running and pointing every reader at a Studio-only preference — the same three wrong
+claims `_not_connected_error` was written to stop making in v2.63, still being made here
+because two producers of one error had drifted apart. It now delegates, so the message
+distinguishes "not running" from "running but refusing scripting" from "the bridge is
+enabled and silent", and free-edition users stop being sent to check a Studio install.
+
+### Design notes
+
+- **Frame numbers are at the timeline rate and `end_frame` is EXCLUSIVE**, matching
+  `AppendToTimeline`'s half-open range. The two shapes disagreeing would be a one-frame
+  error on every clip — exactly the kind that survives review.
+- **Authoring runs in Node** against `resolve-advanced/server/author-interchange.mjs`
+  rather than a second Python writer. Two writers to keep in agreement means the one that
+  drifts is always the copy nobody runs. Without Node it refuses and says why.
+
+### Validation
+
+- Offline suite: 2959 passed, 1 skipped, 719 subtests, 0 failures.
+- All three targets authored and read back: OTIO parsed as a Timeline document with
+  timecode-absolute source ranges, DRT and EDL written and inspected.
+- Three deliberate mutations (swallowing the media-origin warning, treating `end_frame`
+  as inclusive, and marking the connection error as a success) were each caught.
+- No Resolve behavior changed by the authoring path itself; live import validation of an
+  authored file is **not** included in this release.
+
+## What's New in v2.102.0
+
+**A rough mix that reports what it achieved, not what it intended.** The pieces were
+already here — `media_analysis` measures EBU R128 loudness and detects silence,
+`delivery_targets` holds the standards, `loudness_qc` grades a finished file. What was
+missing is the step between measuring and grading: deciding the gains.
+
+### Added
+
+- **`media_analysis mix_plan`** — dialogue-normalisation gain, a music-bed level relative
+  to it, and ducking windows derived from silence detection **on the dialogue stem**, so
+  the bed follows the words rather than a hand-placed envelope. `dry_run` defaults to
+  true and renders nothing.
+  - **The achieved loudness is measured, not derived.** The premix is rendered, then
+    re-measured; `achieved` carries integrated LUFS, true peak, loudness range, and the
+    delta from target. A plan that hits its target on paper and clips on true peak is a
+    failed plan, and only the measurement tells you which one you have.
+  - **Dialogue-anchored, then programme-trimmed.** Anchoring dialogue at target is right
+    for a dialogue-gated standard and wrong for a full-programme one the moment a bed is
+    added. For non-dialogue-gated standards one measured trim is applied to everything
+    equally — preserving the dialogue-to-bed relationship — and reported as
+    `program_normalize.trim_db`. It never runs on a dialogue-gated standard, where
+    dialogue is the figure being graded.
+  - **Nothing else is corrected.** `loudness_off_target`, `true_peak_over`, and `clipped`
+    come back as flags with remedies, never as a quietly normalised file.
+  - Standards come from `delivery_targets` (`web`, `podcast`, `ebu_r128`, `atsc_a85`,
+    `ott_dialogue_gated`) — the table the delivery tools already grade against, not a
+    second copy.
+- **`media_analysis measure_loudness`** — integrated LUFS, loudness range, and true peak
+  per file.
+- **`media_analysis mix_plan_capabilities`** — dependency state, known standards, and the
+  defaults, including the music-bed offset, which is the number most likely to be argued
+  with and so is named rather than buried.
+
+### Fixed while building it
+
+The new loudness parser reads the `Summary:` block **and** drops ebur128's per-frame
+progress lines, which carry their own `I:` and `LRA:` fields. A plain last-match-wins
+parse is correct only because ffmpeg happens to print the summary last, and scoping to
+the summary alone still swallows a progress line printed after it. Both steps are needed;
+a test with a trailing progress line pins it.
+
+### Scope
+
+A rough mix: gain staging, a bed, and ducking. No EQ, compression, de-essing, or
+limiting, and the module says so in its capabilities rather than leaving it implied.
+
+### Validation
+
+- Offline suite: 2924 passed, 1 skipped, 711 subtests, 0 failures.
+- End-to-end through real ffmpeg on generated tones: target hit from measurement, the
+  programme trim landing a hot bed on R128, a dialogue-gated standard refusing the trim,
+  and clipping reported rather than normalised away.
+- Three deliberate mutations (silent peak normalisation, trimming a dialogue-gated
+  standard, and dropping the parser scoping) were each caught. The parser mutation was
+  caught only after the test was strengthened — the first version of it passed against
+  both the fix and its absence.
+- No Resolve behavior changed; live test not required.
+
 ## What's New in v2.101.0
 
 **A grade can now reject itself.** `assess_grade` has measured grade damage since

package/README.md

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

package/docs/SKILL.md

@@ -552,6 +552,20 @@ Key actions:
   `load_user_preferences_preset`
 - `quit` — terminates Resolve (destructive; confirm with user first)
 
+**Offline timeline authoring on `timeline`** — served above the connection check:
+`author_offline` writes an importable `.drt` / `.otio` / `.edl` from a clip plan when
+Resolve is unreachable, and `offline_fallback_capabilities` reports whether it can. Every
+not-connected error carries an `offline_alternative` block naming it. Authoring a file
+does not complete a failed live operation — the timeline is not in a project until it is
+imported. See `docs/kernels/timeline-conform-interchange-kernel.md`.
+
+**Offline audio and image QC on `media_analysis`** — no Resolve connection required:
+`measure_loudness`, `mix_plan` / `mix_plan_capabilities` (dialogue-anchored rough mix
+with dialogue-following ducking, rendered and re-measured), and `assess_grade` /
+`grade_loop` / `grade_loop_capabilities` (numeric grade-damage QC and the retry ladder
+that backs a look off until it stops damaging the picture). See
+`docs/kernels/audio-fairlight-kernel.md` and `docs/kernels/color-grade-kernel.md`.
+
 **`layout_presets`** — Save, load, export, import, delete UI layout presets.
 `list` (Resolve 21.0.4+) enumerates the saved preset names the other actions
 take.

package/docs/kernels/audio-fairlight-kernel.md

@@ -53,6 +53,39 @@ All kernel actions are exposed through `timeline`.
 - Subtitle generation from the generated timeline returned true.
 - Fairlight preset listing and the full boundary report worked.
 
+## Rough mix (`media_analysis`)
+
+Offline and file-based — no Resolve connection — sitting between measuring loudness and
+grading it against a spec. The step nothing else covered was deciding the gains.
+
+- `measure_loudness(path|paths)` — integrated LUFS, loudness range, and true peak per
+  file via ffmpeg `ebur128`.
+- `mix_plan(dialogue[], music?, sfx?, standard?, target_lufs?, bed_offset_lu?, duck_db?,
+  attack_s?, release_s?, hold_s?, dry_run?, output_path?, program_normalize?)` —
+  dialogue-normalisation gain, a bed level relative to it, and ducking windows derived
+  from silence detection **on the dialogue stem**, so the bed follows the words rather
+  than a hand-placed envelope. `dry_run` defaults to true and renders nothing.
+- `mix_plan_capabilities()` — dependency state, the standards it knows, and the defaults.
+
+Three things worth knowing before using it:
+
+- **The achieved loudness is measured, not derived.** The premix is rendered, then
+  re-measured, and `achieved` carries what came back. A plan that hits its target on
+  paper and clips on true peak is a failed plan; only the measurement distinguishes them.
+- **Dialogue-anchored, then programme-trimmed.** Anchoring dialogue at target is right
+  for a dialogue-gated standard and wrong for a full-programme one the moment a bed is
+  added. For non-dialogue-gated standards a single measured trim is applied to everything
+  equally — preserving the dialogue-to-bed relationship — and reported as
+  `program_normalize.trim_db`. It never runs on a dialogue-gated standard.
+- **Nothing else is corrected.** Over true peak or clipped comes back as a flag with a
+  remedy, never as a quietly normalised file. Pulling the mix down to fix a peak would
+  move the loudness off the target it just hit.
+
+Standards come from `src/utils/delivery_targets.py` (`web`, `podcast`, `ebu_r128`,
+`atsc_a85`, `ott_dialogue_gated`) — the same table the delivery tools grade against, not
+a second copy. It is a rough mix: gain staging, a bed, and ducking. No EQ, compression,
+de-essing, or limiting.
+
 ## Boundaries
 
 - Timeline item audio properties may be readable as `None` and can reject writes

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -67,6 +67,45 @@ Supported aliases include `aaf`, `drt`, `edl`, `edl_cdl`, `edl_sdl`,
 - Synthetic-only unlink, missing-media detection, relink candidate planning,
   and safe relink all worked through generated media.
 
+## When Resolve is unreachable
+
+An unreachable Resolve used to end the work. It no longer has to: `timeline` serves two
+actions **above** the connection check, and every not-connected error carries an
+`offline_alternative` block naming them.
+
+- `author_offline(clips[], output_path, target?, name?, fps?, start_timecode?,
+  resolution?)` — write an importable timeline from a file-path clip plan.
+  Targets, in preference order:
+  - **`drt`** (default) — Resolve-native, carries track structure. Stamped at project
+    version 17 (Resolve 21.0); older builds need the advanced server's
+    `drt(action='downgrade')`. Verified map: 18.0.4 → 11, 19.1.x → 14, 21.0 → 17.
+  - **`otio`** — round-trips through this repo's own parser and carries gaps, per-clip
+    speed, and transitions. The target to pick when the plan has retimes.
+  - **`edl`** — CMX3600: video cuts and M2 speed, nothing else.
+- `offline_fallback_capabilities()` — whether authoring is available here, and why not
+  if it is not.
+
+Frame numbers are at the timeline rate and `end_frame` is **EXCLUSIVE**, matching
+`AppendToTimeline`'s half-open range.
+
+**It is an offer, not a substitute.** A caller who asked to build a timeline *in Resolve*
+has not succeeded because a file was written. The connection error stays an error, the
+block says outright that authoring does not complete what failed, and nothing is authored
+unless someone asks for it.
+
+Two warnings the result can carry, both for failures that are otherwise silent:
+
+- `media_tc_origin_assumed` — OTIO source frames are **timecode-absolute**. An event with
+  no media timecode origin imports as an *empty* timeline: the file opens, nothing
+  appears, no error is raised. Pass `media_start_tc_frame` (or an absolute
+  `src_tc_frame`) per clip. Every event that had to assume is named.
+- `retimes_flattened` — a `.drt` has no per-clip speed field, so retimes flatten to 100%
+  forward. Every event that lost one is named; author OTIO to keep them.
+
+Authoring runs in Node against `resolve-advanced/server/author-interchange.mjs` rather
+than a second Python writer — two writers to keep in agreement means the one that drifts
+is always the copy nobody runs. Without Node it refuses and says so.
+
 ## Boundaries
 
 - Interchange formats are not semantically equivalent. DRT is the strongest

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.101.0"
+VERSION = "2.103.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.101.0",
+  "version": "2.103.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.101.0"
+VERSION = "2.103.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.101.0"
+VERSION = "2.103.0"
 
 import base64
 import os
@@ -970,7 +970,7 @@ def _not_connected_error():
     running = resolve_is_running()
     bridge_on = _bridge_requested()
     if bridge_on:
-        return _err(
+        return _with_offline_alternative(_err(
             "The in-app bridge is enabled but not answering.",
             code="BRIDGE_UNAVAILABLE", category="not_connected",
             # `not_connected` defaults to retryable because auto-launch may
@@ -986,9 +986,9 @@ def _not_connected_error():
                         "run `launchctl setenv PYTHON3HOME \"$(python3 -c 'import sys; "
                         "print(sys.prefix)')\"` (launchctl, not export) and restart Resolve.",
             state={"resolve_running": running, "bridge_enabled": True},
-        )
+        ))
     if running:
-        return _err(
+        return _with_offline_alternative(_err(
             "DaVinci Resolve is running but is not answering the scripting API.",
             code="SCRIPTING_UNAVAILABLE", category="not_connected",
             # Not retryable: a preference has to change, or the bridge has to be
@@ -1006,13 +1006,33 @@ def _not_connected_error():
             # responses, and the in-app bridge is not an option for the former.
             state={"resolve_running": True, "bridge_enabled": False,
                    "headless": _resolve_runtime.is_headless()},
-        )
-    return _err(
+        ))
+    return _with_offline_alternative(_err(
         "DaVinci Resolve is not running and could not be started.",
         code="RESOLVE_NOT_RUNNING", category="not_connected",
         remediation="Start DaVinci Resolve and open a project, then retry.",
         state={"resolve_running": bool(running), "bridge_enabled": False},
-    )
+    ))
+
+
+def _with_offline_alternative(error: Dict[str, Any]) -> Dict[str, Any]:
+    """Attach the offline-authoring offer to a not-connected error.
+
+    An offer, not a substitute: the error stays an error, and the block says outright
+    that authoring a file does not complete the operation that just failed. Rerouting
+    silently would turn "your project now has this timeline" into a claim that is false
+    in the only sense that matters.
+    """
+    try:
+        from src.utils import offline_fallback as _offline_mod
+
+        alternative = _offline_mod.offline_alternative()
+        if alternative.get("available"):
+            error.setdefault("error", {})["offline_alternative"] = alternative
+    except Exception:
+        # A connection error must survive anything wrong with the fallback path.
+        pass
+    return error
 
 
 def _destructive_versioning_provider() -> Optional[Tuple[Any, Any, str, Optional[str]]]:
@@ -2489,11 +2509,12 @@ def _check():
         )
     resolve = get_resolve()
     if resolve is None:
-        return None, None, _err(
-            "Not connected to DaVinci Resolve. Is Resolve running?",
-            code="NOT_CONNECTED", category="not_connected", retryable=True,
-            remediation="Open DaVinci Resolve Studio and set Preferences > General > 'External scripting using' to Local.",
-        )
+        # Delegate rather than assert. This branch used to claim Resolve might not be
+        # running and point every reader at a Studio-only preference — the same three
+        # wrong claims `_not_connected_error` was written to stop making, still being
+        # made here because two producers of the same error drifted apart. It also
+        # carries the offline-authoring offer, which this branch never had.
+        return None, None, _not_connected_error()
     pm = resolve.GetProjectManager()
     if pm is None:
         return None, None, _err(
@@ -20128,6 +20149,52 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         from src.utils import grade_loop as _grade_loop_mod
 
         return _ok(**_grade_loop_mod.capabilities())
+    if action in {"mix_plan", "measure_loudness", "mix_plan_capabilities"}:
+        # Gain staging between measuring loudness and grading it: dialogue-norm gain,
+        # a bed level relative to it, and ducking windows the dialogue itself implies.
+        # The render is measured afterwards, so what comes back is the loudness
+        # achieved rather than the arithmetic meant to produce it.
+        from src.utils import mix_plan as _mix_plan_mod
+
+        if action == "mix_plan_capabilities":
+            return _ok(**_mix_plan_mod.capabilities())
+        try:
+            if action == "measure_loudness":
+                paths = p.get("paths") or ([p["path"]] if p.get("path") else [])
+                if not paths:
+                    return _err("measure_loudness requires path or paths")
+                return _ok(measurements=[_mix_plan_mod.measure(str(item)) for item in paths])
+
+            dialogue = p.get("dialogue") or ([p["path"]] if p.get("path") else [])
+            if isinstance(dialogue, str):
+                dialogue = [dialogue]
+            kwargs = dict(
+                music=p.get("music") or [],
+                sfx=p.get("sfx") or [],
+                standard=str(p.get("standard") or _mix_plan_mod.DEFAULT_STANDARD),
+                target_lufs=(
+                    float(p["target_lufs"]) if p.get("target_lufs") is not None else None
+                ),
+                bed_offset_lu=float(p.get("bed_offset_lu", _mix_plan_mod.DEFAULT_BED_OFFSET_LU)),
+                duck_db=float(p.get("duck_db", _mix_plan_mod.DEFAULT_DUCK_DB)),
+                attack_s=float(p.get("attack_s", _mix_plan_mod.DEFAULT_ATTACK_S)),
+                release_s=float(p.get("release_s", _mix_plan_mod.DEFAULT_RELEASE_S)),
+                hold_s=float(p.get("hold_s", _mix_plan_mod.DEFAULT_HOLD_S)),
+            )
+            if p.get("dry_run", True):
+                return _ok(**_mix_plan_mod.plan(dialogue, **kwargs))
+            return _ok(**_mix_plan_mod.render(
+                dialogue,
+                output_path=(p.get("output_path") or p.get("outputPath")) or None,
+                program_normalize=p.get("program_normalize"),
+                **kwargs,
+            ))
+        except _mix_plan_mod.MixPlanError as exc:
+            return _err(str(exc), code="MIX_PLAN_REFUSED", category="invalid_input",
+                        remediation=(
+                            "Supply dialogue=[...] stems that carry audio. The mix is "
+                            "anchored to dialogue, so it cannot be planned without one."
+                        ))
     if action == "image_qc_capabilities":
         from src.utils import image_qc as _image_qc_mod
 
@@ -21082,6 +21149,9 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "assess_grade",
         "grade_loop",
         "grade_loop_capabilities",
+        "mix_plan",
+        "mix_plan_capabilities",
+        "measure_loudness",
         "image_qc_capabilities",
         "install_guidance",
         "resolve_output_root",
@@ -22826,6 +22896,8 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
 
 
 _TIMELINE_ACTIONS = [
+    # Offline authoring — served without a Resolve connection, above the _check() gate.
+    "author_offline", "offline_fallback_capabilities",
     "list", "get_current", "set_current", "get_name", "set_name", "get_start_frame",
     "get_end_frame", "get_start_timecode", "set_start_timecode", "get_track_count",
     "add_track", "delete_track", "get_track_sub_type", "set_track_enable",
@@ -23082,6 +23154,38 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     # action_help is pull-on-demand metadata; no Resolve connection needed.
     if action == "action_help":
         return _action_help("timeline", p)
+    if action in {"author_offline", "offline_fallback_capabilities"}:
+        # Deliberately above the connection check: these exist FOR the case where there
+        # is no connection. Authoring writes a file the user imports; it does not make
+        # a failed live operation succeed, and the response says so.
+        from src.utils import offline_fallback as _offline_mod
+
+        if action == "offline_fallback_capabilities":
+            return _ok(**_offline_mod.capabilities())
+        err, _clean = _validate_params(p, {
+            "output_path": {"type": str, "required": True, "non_empty": True},
+        })
+        if err:
+            return _err(err)
+        try:
+            return _ok(**_offline_mod.author(
+                p.get("clips") or [],
+                str(p["output_path"]),
+                target=str(p.get("target") or _offline_mod.DEFAULT_TARGET),
+                name=str(p.get("name") or "Offline Conform"),
+                fps=float(p.get("fps") or _offline_mod.DEFAULT_FPS),
+                start_timecode=str(p.get("start_timecode") or "01:00:00:00"),
+                resolution=str(p.get("resolution") or "1920x1080"),
+            ))
+        except _offline_mod.OfflineFallbackError as exc:
+            return _err(str(exc), code="OFFLINE_AUTHORING_REFUSED",
+                        category="invalid_input", retryable=False,
+                        remediation=(
+                            "Supply clips=[{path, start_frame, end_frame}] with frame "
+                            "numbers at the timeline rate; end_frame is EXCLUSIVE. Add "
+                            "media_start_tc_frame per clip so source frames are "
+                            "timecode-absolute, or the import can produce an empty timeline."
+                        ))
     pm, proj, err = _check()
     if err:
         return err