davinci-resolve-mcp 2.79.2 → 2.80.1

package/CHANGELOG.md

@@ -2,6 +2,121 @@
 
 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.80.1
+
+A correction to the retime measurement contract published in v2.80.0, and a fix
+for a documented timecode conversion that never happened.
+
+### Fixed
+
+- **`timeline_markers.set_current_timecode` now honors the documented
+  elapsed-timecode conversion.** The tool doc has always said timecodes before
+  the timeline start are treated as elapsed time and converted automatically —
+  but only marker actions did the conversion. `set_current_timecode` passed the
+  raw string to `Timeline.SetCurrentTimecode`, which refuses sub-start
+  timecodes with a bare `False` and no error info (measured on Studio 19.1.3.7:
+  on a timeline starting `00:59:50:00`, `00:00:21:03` failed while
+  `01:00:11:03` succeeded). The wrapper now lifts elapsed timecodes by the
+  start frame — `00:00:21:03` lands the playhead at `01:00:11:03` — with
+  drop-frame-correct formatting on DF timelines. Absolute timecodes and strings
+  the parser cannot read pass through unchanged. Marker `add()`'s conversion
+  was re-verified live on a non-zero-start timeline (elapsed `00:00:21:03` →
+  relative frame 507) and was already correct.
+
+### Documentation
+
+- **🚩 Correction to v2.80.0's retime witness — the recommended instrument
+  cannot see retimes.** The v2.80.0 retime entry recommended reading
+  `GetLeftOffset`/`GetRightOffset` to tell whether a retime was built. A
+  calibration with the confound removed (the SAME clip twice in ONE timeline,
+  one copy hand-set to 200%, Studio 19.1.3.7) proves that pair reads the
+  WARPED domain — position ÷ speed, span always equal to the record span — so
+  it is exact for placement and structurally blind for speed. The corrected
+  entry installs the calibrated model: judge speed by the
+  `GetSourceStartFrame`/`GetSourceEndFrame` span vs the record duration (the
+  200% copy read span 96 vs 48; a 0/0 read on xmeml-imported timelines is
+  UNKNOWN, never "no retime"), cross-checked by the `Sm2TimeMap` slope in a
+  saved Project.db or the `EXPORT_EDL` M2 rate.
+- **Two import routes DO build constant retimes**, now documented with their
+  emission rules: OTIO `LinearTimeWarp` through `ImportTimelineFromFile` (200%
+  and 50% measured; `source_range.duration` is the RECORD span — the
+  `time_scalar` handles source consumption; source frames timecode-absolute)
+  and EDL `M2` in the exact shape Resolve's own `EXPORT_EDL` writes (200%
+  measured; event-line source span equals the record span; `* FROM CLIP NAME:`
+  drives linking). Reverse and varying-speed maps remain untested as import
+  routes and the entry says so.
+- `docs/reference/api-limitations.md` regenerated; the `GetSourceStartFrame`
+  off-by-one entry now scopes its GetLeftOffset advice to 100%-speed placement.
+
+### Validation
+
+- Full offline suite: 2460 passed, 1 skipped (up exactly the 7 new tests from
+  the 2453 baseline).
+- Live Resolve Studio 19.1.3.7: new
+  `tests/live_playhead_timecode_validation.py` harness — raw refusal control,
+  elapsed lift to `01:00:11:03`, absolute pass-through, and marker add() at
+  relative frame 507 all verified against a disposable project.
+
+## What's New in v2.80.0
+
+Three community PRs from @staahlarkitektur, all found on Windows, all real. Each is merged with
+its diagnosis intact and a fix on top for what the patch didn't reach.
+
+### Added
+
+- **`background=true` now actually runs the analysis.** `background`/`async_job` were accepted on
+  `analyze_clip` / `analyze_bin` / `analyze_file` / `analyze_project` / `analyze_sequence` and
+  silently ignored — the call ran the whole analysis inline and returned no `job_id`, which from
+  the caller's side is indistinguishable from a hang (#119). The two async opt-ins are now
+  distinct and both do what their names say:
+  - `prefer_handle=true` — creates the durable batch job and hands it back **queued**. Nothing
+    runs until you call `run_batch_job_slice`. Unchanged contract.
+  - `background=true` / `async_job=true` — creates the job **and drives it to completion
+    off-thread**, matching what `background` means on every other tool in this server. Poll
+    `batch_job_status` until `completed` / `completed_with_errors` / `canceled`.
+
+  Aliasing the two, as the PR proposed, would have replaced one silence with a quieter one: a job
+  that nothing ever advanced, polled forever. The runner deliberately does **not** hold the
+  Resolve busy gate — analysis drives ffmpeg, whisper and vision over file paths and touches the
+  scripting bridge nowhere, so holding it for an hour of transcription would lock the editor out
+  for nothing. A process-wide slice lock bounds the real cost instead: queued analyses interleave
+  a clip at a time rather than starting N ffmpeg passes at once.
+
+### Fixed
+
+- **A timeout could take 82 seconds to report a 5-second limit.** `subprocess.run(timeout=...)`
+  kills only the direct child. On Windows a bare-name PATH lookup can resolve to a shim
+  (Chocolatey, npm, a pip console script) that runs the real work as a grandchild, so the kill hit
+  the wrapper while the real `ffmpeg` kept running — and the follow-up read blocked on the pipe
+  handles it had inherited. Measured on a Chocolatey-managed machine: `ffmpeg` on PATH was a 392KB
+  shim, and a 5s timeout against an ~82s pass returned after the full 82s with "timed out after
+  5s" attached to complete, correct output (#120). `_run_command` now spawns via `Popen` in its own
+  session/process group and kills the whole tree. Beyond the PR: the kill helper no longer raises
+  (`killpg` returns EPERM, `taskkill` can be missing from PATH — either escaped and broke the
+  return contract mid-failure), the read after the kill is bounded and says so when it gives up
+  rather than hanging on a survivor, and a cancellation mid-run kills the tree instead of orphaning
+  it. Fixes every `_run_command` caller at once — the whisper CLI and every ffmpeg pass in
+  `_readthrough_analysis`, `silence_ripple`, and `deep_vision`.
+- **The whisper CLI inherited a `PYTHONHOME` that killed it.** `PYTHONHOME`/`PYTHONPATH` point this
+  server at Resolve's bundled Python so `DaVinciResolveScript` imports. Inherited by a child that
+  is itself a *different* Python, they corrupt its stdlib resolution — and whisper's CLI is exactly
+  that. Measured: whisper on 3.14 inheriting a 3.10 `PYTHONHOME` dies on `AssertionError: SRE
+  module mismatch` (#118). The whisper subprocess now gets a scrubbed environment. This is the
+  **shipped Windows configuration**, not a local quirk: `install.py` writes `PYTHONHOME` into
+  generated client configs (issue #26) and `server.py` sets it on Windows whenever it isn't
+  already set, so every Windows install hands a foreign `PYTHONHOME` to every child it spawns.
+
+### Corrected in the merged PRs
+
+- The documented async return shape was wrong — `{job_id, status}` was advertised, the real
+  envelope is `{success, job, plan}` with the id at `job.job_id`. Now documented as it is, plus
+  `running` and a `note` naming the next call so the queued and running routes can't be confused.
+- The async divert ran *after* `dry_run` was resolved from the `dry_run_first_default` preference,
+  so a user with that preference on still got `background=true` swallowed in silence. An explicit
+  `dry_run` still wins; an inherited one no longer does.
+- A code comment attributed the whisper failure to a silent stall with an ffmpeg child at 0% CPU —
+  a diagnosis the PR's own description retracted, and one that belongs to the shim problem above.
+
 ## What's New in v2.79.2
 
 A published contract was **wrong**. This release corrects it. If you read the retime entry in

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.79.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.80.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)

package/docs/reference/api-limitations.md

@@ -117,8 +117,8 @@ equivalent, blocking full automation.
 ### Clip speed / retime ratio and speed ramps
 
 - **Object:** `TimelineItem`
-- **Behavior:** SetProperty exposes only retime *quality* (RetimeProcess, MotionEstimation) and transform/crop/composite/opacity keys — not the speed value itself. There is no way to set a clip to a given % speed, reverse it, or author a speed ramp. Verified against the documented SetProperty key list AND by live mutating attempt on 21.0.0: SetProperty('Speed'|'PlaybackSpeed'|'RetimeSpeed'|'ClipSpeed', 50) all return False, while SetProperty('RetimeProcess', 1) returns True. THE READ SIDE IS AS DEAD AS THE WRITE SIDE, which is easy to miss: re-measured on Studio 19.1.3.7 against a placed item, GetProperty('Speed'), GetProperty('PlaybackSpeed'), GetProperty('RetimeSpeed') and GetProperty('ClipSpeed') ALL return None, and the keyless GetProperty() dict (26 keys on that item) carries no speed value at all — its only retime key is RetimeProcess, which is quality, not ratio. SetProperty('Speed', 1.75) returned False on 19.1.3.7 too, so the write refusal is not specific to 21.0.0. Note the 21.0.0 stamp above covers the SetProperty measurements only. THE SCRIPTING-API xmeml IMPORT BUILDS NO RETIME — and the way it fails is worse than a no-op. First, what Premiere actually writes, because having this backwards is what produced the wrong contract this entry published in 2.79.0–2.79.1 (see CORRECTION below). In an FCP7 XML a retimed clipitem's <in>/<out> live in the POST-RETIME (warped) domain and always span the RECORD duration; pproTicksIn/pproTicksOut carry the TRUE SOURCE position; and <duration> is the file length expressed in the warped domain. A real 200% clip at 24 fps: <in>1957</in> <out>1971</out> — span 14, EQUAL to its record span; pproTicksIn 41425776000000 and pproTicksOut 41722128000000, which at 254016000000/24 = 10584000000 ticks per frame are source frames 3914 and 3942, exactly 1957x2 and 1971x2, a 28-frame source span over a 14-frame record span; <duration>24292</duration> for a 48584-frame file; and a graphdict mapping warped to true source with the ratio as its slope (when 17910 -> value 35820). So for a retimed clip <in> and pproTicksIn are SUPPOSED to disagree, by exactly the ratio. The same relationship seen from the other side is already encoded in this repo: resolve-advanced/server/prproj.mjs derives Premiere speed from tick geometry as |srcSpan / recSpan| * 100, reversing when in > out. Against that convention, measured on 19.1.3/19.1.3.7: (a) the importer IGNORES the scalar Time Remap speed filter and the clips arrive at 100%; (b) `graphdict` is ignored too — re-tested in Premiere's exact convention with one 100% control clip and one 200% clip per timeline, a document carrying warped <in>/<out>, true-source pproTicks, <duration> = fileLen/ratio and a constant-slope graphdict imports cleanly, the control lands correct, and the 200% clip reads back src 1500..1548 — a 48-frame source span over a 48-frame record span, i.e. NO retime; emitting the identical document WITHOUT the graphdict gives the identical result; (c) `reverse` does not survive either; (d) THE HAZARD, and it is the part that bites: Resolve reads <in> LITERALLY as the true source frame, honouring neither the ticks nor the graphdict. Import a genuine Premiere XML that contains retimes and every retimed clip is placed at in / ratio — the 200% clip above lands on source frame 1957 instead of 3914. There is no error, the cut lengths are still correct, every clip is linked and online, and the timeline renders — so it reads as a good conform while sitting at the wrong moment of the right file. This is the same failure class as the Avid AAF camera-file link (docs/guides/conforming-an-avid-aaf.md): wrong in a way only a frame comparison against a reference can see. SCOPE: all of the above is the SCRIPTING-API import (ImportTimelineFromFile). Resolve's UI importer (File > Import > Timeline) has NOT been tested, and that is how editors usually conform a Premiere XML — do not read this as covering it. CORRECTION: this entry as published in 2.79.0–2.79.1 also claimed that any <in>/<pproTicksIn> inconsistency is silently REJECTED in both orientations. That claim was FALSE and has been removed — it came from an emitter writing ticks = in x ticks-per-frame at every speed, so what it observed was its own malformed files being refused. The graphdict evidence published with it (dead in FOUR shapes, 0 of 2 landed, a 200% clip emitted in 200 / out 296 'clamped' to out 248) described that same malformed input being normalized and is replaced by the re-test above. The conclusion is unchanged; only its evidence is. Placement is NOT the problem: the same route imported 573 clips with 572 of 573 matching by track and record position with source frames exact, and the importer BUILT a 59-frame dissolve. The retime gap is specific, not general. TRAP: Resolve's own FCP7 export cannot witness a speed. It writes a DEGENERATE Time Remap on every clip — `speed` value 0 (not 100) and a graphdict whose keyframe `value`s are all 0 while its `when`s carry the clip's source in/out — so anyone verifying a retime by round-tripping through EXPORT_FCP_7_XML is reading furniture, and the identity Time Remap blocks present on every clip are what make the route look like it should work.
-- **Workaround / current handling:** Set clip speed/retime in the Resolve UI; no scripted equivalent exists, and the scripting-API xmeml import does not carry one in. Do NOT read speed back with GetProperty (None) or witness it via EXPORT_FCP_7_XML (degenerate). Read the clip's GEOMETRY instead — GetLeftOffset / GetRightOffset, whose source span is what shows whether a retime was built (the re-tested 200% clip read src 1500..1548, 48 source frames over a 48-frame record, so none was). Caveat worth keeping: there is still no positive control — no clip KNOWN to be retimed has been read back through those two witnesses, because there is no scripting path to create one, so the geometry witness is the best available, not a proven one. And if you are importing a real Premiere XML that contains retimes, treat every retimed clip's source position as WRONG — placed at <in>, i.e. in / ratio — until it is checked against a reference; the lengths and the links will look right.
+- **Behavior:** SetProperty exposes only retime *quality* (RetimeProcess, MotionEstimation) and transform/crop/composite/opacity keys — not the speed value itself. There is no way to set a clip to a given % speed, reverse it, or author a speed ramp. Verified against the documented SetProperty key list AND by live mutating attempt on 21.0.0: SetProperty('Speed'|'PlaybackSpeed'|'RetimeSpeed'|'ClipSpeed', 50) all return False, while SetProperty('RetimeProcess', 1) returns True. THE READ SIDE IS AS DEAD AS THE WRITE SIDE, which is easy to miss: re-measured on Studio 19.1.3.7 against a placed item, GetProperty('Speed'), GetProperty('PlaybackSpeed'), GetProperty('RetimeSpeed') and GetProperty('ClipSpeed') ALL return None, and the keyless GetProperty() dict (26 keys on that item) carries no speed value at all — its only retime key is RetimeProcess, which is quality, not ratio. SetProperty('Speed', 1.75) returned False on 19.1.3.7 too, so the write refusal is not specific to 21.0.0. Note the 21.0.0 stamp above covers the SetProperty measurements only. THE SCRIPTING-API xmeml IMPORT BUILDS NO RETIME — and the way it fails is worse than a no-op. First, what Premiere actually writes, because having this backwards is what produced the wrong contract this entry published in 2.79.0–2.79.1 (see CORRECTION below). In an FCP7 XML a retimed clipitem's <in>/<out> live in the POST-RETIME (warped) domain and always span the RECORD duration; pproTicksIn/pproTicksOut carry the TRUE SOURCE position; and <duration> is the file length expressed in the warped domain. A real 200% clip at 24 fps: <in>1957</in> <out>1971</out> — span 14, EQUAL to its record span; pproTicksIn 41425776000000 and pproTicksOut 41722128000000, which at 254016000000/24 = 10584000000 ticks per frame are source frames 3914 and 3942, exactly 1957x2 and 1971x2, a 28-frame source span over a 14-frame record span; <duration>24292</duration> for a 48584-frame file; and a graphdict mapping warped to true source with the ratio as its slope (when 17910 -> value 35820). So for a retimed clip <in> and pproTicksIn are SUPPOSED to disagree, by exactly the ratio. The same relationship seen from the other side is already encoded in this repo: resolve-advanced/server/prproj.mjs derives Premiere speed from tick geometry as |srcSpan / recSpan| * 100, reversing when in > out. Against that convention, measured on 19.1.3/19.1.3.7: (a) the importer IGNORES the scalar Time Remap speed filter and the clips arrive at 100%; (b) `graphdict` is ignored too — re-tested in Premiere's exact convention with one 100% control clip and one 200% clip per timeline, a document carrying warped <in>/<out>, true-source pproTicks, <duration> = fileLen/ratio and a constant-slope graphdict imports cleanly, the control lands correct, and NO retime is built: recalibrated 2026-08-05, every xmeml-imported clip carries a DEGENERATE time map in Project.db (Sm2TimeMap with an empty source axis — five Time Remap shapes re-measured, 15/15 clips degenerate), so no speed exists in the project data, and the API source witness reads 0/0 on those clips (see WITNESS CALIBRATION below); emitting the identical document WITHOUT the graphdict gives the identical result; (c) `reverse` does not survive either; (d) THE HAZARD, and it is the part that bites: Resolve reads <in> LITERALLY as the true source frame, honouring neither the ticks nor the graphdict. Import a genuine Premiere XML that contains retimes and every retimed clip is placed at in / ratio — the 200% clip above lands on source frame 1957 instead of 3914. There is no error, the cut lengths are still correct, every clip is linked and online, and the timeline renders — so it reads as a good conform while sitting at the wrong moment of the right file. This is the same failure class as the Avid AAF camera-file link (docs/guides/conforming-an-avid-aaf.md): wrong in a way only a frame comparison against a reference can see. SCOPE: all of the above is the SCRIPTING-API import (ImportTimelineFromFile). Resolve's UI importer (File > Import > Timeline) has NOT been tested, and that is how editors usually conform a Premiere XML — do not read this as covering it. CORRECTION: this entry as published in 2.79.0–2.79.1 also claimed that any <in>/<pproTicksIn> inconsistency is silently REJECTED in both orientations. That claim was FALSE and has been removed — it came from an emitter writing ticks = in x ticks-per-frame at every speed, so what it observed was its own malformed files being refused. The graphdict evidence published with it (dead in FOUR shapes, 0 of 2 landed, a 200% clip emitted in 200 / out 296 'clamped' to out 248) described that same malformed input being normalized and is replaced by the re-test above. The conclusion is unchanged; only its evidence is. Placement is NOT the problem: the same route imported 573 clips with 572 of 573 matching by track and record position with source frames exact, and the importer BUILT a 59-frame dissolve. The retime gap is specific, not general. TRAP: Resolve's own FCP7 export cannot witness a speed. It writes a DEGENERATE Time Remap on every clip — `speed` value 0 (not 100) and a graphdict whose keyframe `value`s are all 0 while its `when`s carry the clip's source in/out — so anyone verifying a retime by round-tripping through EXPORT_FCP_7_XML is reading furniture, and the identity Time Remap blocks present on every clip are what make the route look like it should work. WITNESS CALIBRATION (2026-08-05, Studio 19.1.3.7) — the positive control this entry previously lacked now exists, and it RETRACTS the witness the 2.80.0 revision of this entry recommended. The rig removed every confound: the SAME clip placed twice, adjacent, in ONE timeline, the second copy hand-set to 200% in the UI (the only way to make one — see above). GetSourceStartFrame/GetSourceEndFrame separated the copies — 1822..1870 (span 48) at 100% vs 1822..1918 (span 96) at 200% — while GetLeftOffset/GetRightOffset did NOT: 1822..1870 at 100% vs 911..959 at 200%, which is exactly position / 2. GetLeftOffset reports the WARPED (record-side) domain — position / speed, the `In` column of Project.db's Sm2TiItem — so it is exact for PLACEMENT and blind for SPEED BY CONSTRUCTION: its span equals the record span at every speed. The speed itself lives in the item's Sm2TimeMap blob (keyframe slope = ratio; the hand-set 200% reads slope exactly 2.0), which is what GetSourceStart/EndFrame and EXPORT_EDL read. THE SPEED WITNESS is therefore the GetSourceStart/EndFrame span vs the record duration. CAVEAT: on xmeml-IMPORTED timelines those return 0/0 — the importer leaves the time map's source axis empty — and a 0/0 read is UNKNOWN, never 'no retime'. Cross-checks that work everywhere: the Sm2TimeMap slope read from a saved Project.db, and the EXPORT_EDL M2 rate (rate = fps x speed/100, so 048.0 = 200% at 24 fps; `M2 ... 000.0` on every clip is the degenerate-map furniture of an xmeml import — ignore it). TWO IMPORT ROUTES DO BUILD CONSTANT RETIMES (measured 2026-08-05, media linked, judged via the calibrated witnesses above): (1) OTIO LinearTimeWarp through ImportTimelineFromFile — 200% (src 200..296 over a 48-frame record) and 50% (src 300..324 over a 48-frame record) both landed with correct source in-points; the saved Project.db shows slope 2.0 and 0.5. Emission rules: the document must be Resolve-shaped with TIMECODE-ABSOLUTE source frames (see the ImportTimelineFromFile .otio entry), the effect is `LinearTimeWarp.1` with `time_scalar`, and `source_range.duration` is the RECORD span — OTIO semantics, the time_scalar handles source consumption; sending the source span as the duration builds a spec-correctly longer clip, not a retime. (2) EDL M2 — 200% landed (src 100..196 over a 48-frame record), linked. Author the shape Resolve's own EXPORT_EDL writes: the event line's source span EQUALS the record span even under M2; the `M2 <reel> <rate> <srcInTC>` line carries the play rate in fps (048.0 = 200% at 24); `* FROM CLIP NAME:` comments drive pool linking. UNTESTED as import routes: reverse (negative time_scalar / reverse M2) and varying-speed maps — do not extrapolate the constant-speed result to them.
+- **Workaround / current handling:** Set clip speed/retime in the Resolve UI, or BUILD it by import: OTIO LinearTimeWarp and EDL M2 both construct constant retimes through ImportTimelineFromFile (measured — emission rules in reality above); xmeml does not, in any Time Remap shape. To READ a retime back, judge speed by the GetSourceStart/EndFrame span vs the record duration — a 0/0 read (xmeml-imported timelines) is UNKNOWN, never 'no retime' — and cross-check with the Sm2TimeMap slope in a saved Project.db or the EXPORT_EDL M2 rate. Do NOT read speed with GetProperty (None), witness it via EXPORT_FCP_7_XML (degenerate), or judge it from GetLeftOffset/GetRightOffset — the 2.80.0 revision of this entry recommended that pair as the witness and it is blind by construction: it reads the warped domain (position / speed) and its span equals the record span at every speed. Keep it for PLACEMENT checks only. Reverse and varying-speed maps remain untested as import routes. And if you are importing a real Premiere XML that contains retimes, treat every retimed clip's source position as WRONG — placed at <in>, i.e. in / ratio — until it is checked against a reference; the lengths and the links will look right.
 - **Tags:** missing-method, timeline, retime, speed, interchange, silent-failure, unreliable-return
 
 ### Color node graph editing and primary grade values
@@ -363,7 +363,7 @@ values, or automation-hostile modal prompts.
 - **Object:** `TimelineItem`
 - **Signature:** `() -> int`
 - **Behavior:** Reads back one frame off on some items. Measured while verifying a constructed timeline against the clipInfos it was built from: for 4/4 items GetLeftOffset returned exactly the startFrame that was sent, while GetSourceStartFrame disagreed by 1 on some of the same items. The two are supposed to describe the same edit point, so a conform that verifies placement with GetSourceStartFrame reports phantom off-by-one drift on correctly placed clips — and would hide a real one-frame error just as easily.
-- **Workaround / current handling:** Verify source-side placement with GetLeftOffset, which is exact. Treat GetSourceStartFrame as approximate, and never diff it against a sent startFrame to decide whether a clip landed right.
+- **Workaround / current handling:** Verify source-side placement with GetLeftOffset, which is exact. Treat GetSourceStartFrame as approximate, and never diff it against a sent startFrame to decide whether a clip landed right. Scope: placement at 100% speed. On a retimed clip the two read DIFFERENT domains — GetLeftOffset is warped (position / speed), GetSourceStartFrame is true source — see the retime entry's witness calibration before comparing them.
 - **Tags:** off-by-one, unreliable-return, timeline, conform, verify
 
 ### hasattr() / getattr() on Resolve API objects (attribute fabrication)

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.79.2"
+VERSION = "2.80.1"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

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

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.79.2"
+VERSION = "2.80.1"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.79.2"
+VERSION = "2.80.1"
 
 import base64
 import os
@@ -104,9 +104,11 @@ from src.utils.media_analysis_jobs import (
     batch_job_status as media_analysis_batch_job_status,
     cancel_batch_job as cancel_media_analysis_batch_job,
     create_batch_job as create_media_analysis_batch_job,
+    join_batch_job_runner as join_media_analysis_batch_job_runner,
     list_batch_jobs as list_media_analysis_batch_jobs,
     resume_batch_job as resume_media_analysis_batch_job,
     run_batch_job_slice as run_media_analysis_batch_job_slice,
+    start_batch_job_runner as start_media_analysis_batch_job_runner,
 )
 from src.utils.platform import get_resolve_paths, get_resolve_plugin_paths
 from src.utils.resolve_connection import connect_resolve
@@ -1960,9 +1962,67 @@ def _marker_display_frame(tl, frame):
     return frame
 
 
-def _frame_id_to_timecode(frame: int, fps: float, separator: str = ":") -> str:
+def _playhead_absolute_timecode(tl, timecode):
+    """Lift an elapsed timecode to the absolute timecode SetCurrentTimecode wants.
+
+    Timeline.SetCurrentTimecode only accepts the absolute timeline timecode
+    shown in the Resolve UI; handing it a timecode below the start timecode
+    returns False with no error info (measured on Studio 19.1.3.7: on a
+    timeline starting 00:59:50:00, '00:00:21:03' fails while '01:00:11:03'
+    succeeds). Mirror the marker-param contract: a timecode that parses to a
+    frame below the timeline start is elapsed time and gets lifted by the
+    start frame. At-or-past-start timecodes, and strings this parser cannot
+    read, pass through unchanged so Resolve stays the arbiter of them.
+    """
+    if not isinstance(timecode, str):
+        return timecode
+    frame, err = _timeline_timecode_to_frame_id(tl, timecode)
+    if err:
+        return timecode
+    start = _timeline_start_frame(tl)
+    if not start or frame >= start:
+        return timecode
+    fps, fps_err = _timeline_fps(tl)
+    if fps_err:
+        return timecode
+    drop_frame = ";" in timecode
+    try:
+        start_tc = tl.GetStartTimecode()
+    except Exception:
+        start_tc = None
+    if isinstance(start_tc, str) and start_tc:
+        drop_frame = ";" in start_tc
+    separator = ";" if drop_frame else ":"
+    return _frame_id_to_timecode(
+        frame + start, fps, separator=separator, drop_frame=drop_frame
+    )
+
+
+def _frame_id_to_timecode(
+    frame: int, fps: float, separator: str = ":", drop_frame: bool = False
+) -> str:
     nominal_fps = max(1, int(round(float(fps))))
     frame = max(0, int(frame))
+    if drop_frame:
+        # Inverse of the drop-frame arithmetic in _timecode_to_frame_id: 2 (30
+        # fps) or 4 (60 fps) frame numbers are skipped each minute except every
+        # tenth minute.
+        drop = int(round(nominal_fps * 0.0666666667))
+        if drop > 0:
+            per_minute = nominal_fps * 60 - drop
+            per_ten = per_minute * 10 + drop
+            tens, rem = divmod(frame, per_ten)
+            if rem < nominal_fps * 60:
+                minutes = tens * 10
+                frame_in_minute = rem
+            else:
+                rem -= nominal_fps * 60
+                extra_minutes, frame_in_minute = divmod(rem, per_minute)
+                minutes = tens * 10 + 1 + extra_minutes
+                frame_in_minute += drop
+            hours, minutes = divmod(minutes, 60)
+            seconds, frames = divmod(frame_in_minute, nominal_fps)
+            return f"{hours:02d}:{minutes:02d}:{seconds:02d}{separator}{frames:02d}"
     total_seconds, frames = divmod(frame, nominal_fps)
     hours, rem = divmod(total_seconds, 3600)
     minutes, seconds = divmod(rem, 60)
@@ -8241,6 +8301,49 @@ def _media_analysis_bool(value: Any, default: bool = False) -> bool:
     return bool(value)
 
 
+MEDIA_ANALYSIS_ASYNC_QUEUED = "queued"
+MEDIA_ANALYSIS_ASYNC_RUNNING = "running"
+
+
+def _media_analysis_async_mode(p: Dict[str, Any], *, dry_run_explicit: bool = True) -> Optional[str]:
+    """How an analyze_* call wants its work handled. None means synchronously.
+
+    Two opt-ins, deliberately not synonyms:
+
+      prefer_handle        -> "queued".  Create the durable batch job and hand
+                              it back. Nothing runs until the caller drives
+                              run_batch_job_slice. This is the pre-existing
+                              contract and is unchanged.
+      background/async_job -> "running". Create the job AND drive it off-thread,
+                              so the work is under way when the call returns.
+
+    The split exists because `background` already means something specific
+    everywhere else in this server — _run_maybe_background starts the work and
+    the caller polls until it finishes on its own. Before, these two params were
+    accepted here and silently ignored: the analyze_* actions collapsed to
+    action="plan" and ran to completion inline, so a caller got no job_id and no
+    signal, indistinguishable from a hang. Aliasing them onto prefer_handle
+    would have replaced that with a job that never progressed — a quieter
+    failure than the one being fixed. So `background` keeps its meaning and gets
+    the runner it always implied.
+
+    `dry_run` still wins, but only when the caller asked for it. Pass
+    dry_run_explicit=False when p["dry_run"] came from the dry_run_first_default
+    preference rather than the call: a preference should not silently swallow an
+    explicit async request and hand back a plan the caller never asked for,
+    which is the same silence this whole change is closing.
+    """
+    if dry_run_explicit and _media_analysis_bool(p.get("dry_run"), False):
+        return None
+    if _media_analysis_bool(p.get("background"), False) or _media_analysis_bool(
+        p.get("async_job"), False
+    ):
+        return MEDIA_ANALYSIS_ASYNC_RUNNING
+    if _media_analysis_bool(p.get("prefer_handle"), False):
+        return MEDIA_ANALYSIS_ASYNC_QUEUED
+    return None
+
+
 def _media_analysis_target_dict(raw_target: Any, p: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     p = p or {}
     if raw_target is None:
@@ -17928,12 +18031,22 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
       set_ai_governance(preset?, mode?, overrides?) -> {success, tier, mode, overrides} — set the tier, the mode (advisory|enforce), and/or overrides (deblur_runs, speech_runs, render_bytes, render_wall_clock_ms; int or "unlimited"). In enforce mode a blocked run returns GOVERNANCE_BLOCKED; pass override_governance=true on the op to consciously exceed the tier once.
       resolve_output_root(analysis_root?, source_paths?) -> {project_root}
       plan(target, depth?, analysis_root?, transcription?, vision?, dry_run?) -> {clips, artifacts}
-      analyze_file(path|file_path, dry_run?, session_only?, persist?) -> {clips, manifest}
-      analyze_clip(clip_id|selected, dry_run?, session_only?, persist?) -> {clips, manifest}
-      analyze_bin(path|bin_path, recursive?, dry_run?, session_only?, persist?) -> {clips, manifest}
-      analyze_project(recursive?, dry_run?, session_only?, persist?) -> {clips, manifest}
-      analyze_sequence(timeline_index?, track_types?, dry_run?, session_only?, persist?) -> {clips, manifest}
+      analyze_file(path|file_path, dry_run?, session_only?, persist?, prefer_handle?|background?|async_job?) -> {clips, manifest} | {success, job, plan, running, note} when async
+      analyze_clip(clip_id|selected, dry_run?, session_only?, persist?, prefer_handle?|background?|async_job?) -> {clips, manifest} | {success, job, plan, running, note} when async
+      analyze_bin(path|bin_path, recursive?, dry_run?, session_only?, persist?, prefer_handle?|background?|async_job?) -> {clips, manifest} | {success, job, plan, running, note} when async
+      analyze_project(recursive?, dry_run?, session_only?, persist?, prefer_handle?|background?|async_job?) -> {clips, manifest} | {success, job, plan, running, note} when async
+      analyze_sequence(timeline_index?, track_types?, dry_run?, session_only?, persist?, prefer_handle?|background?|async_job?) -> {clips, manifest} | {success, job, plan, running, note} when async
       analyze_timeline(...) -> alias for analyze_sequence on the current timeline
+      -- async opt-ins on the analyze_* actions above. Both reroute to start_batch_job and return its
+         {success, job, plan} envelope — the id is job.job_id, NOT a top-level job_id — plus `running`
+         and a `note` naming the next call. They differ in what happens next:
+           prefer_handle=true        job is created and left queued; nothing runs until you call
+                                     run_batch_job_slice yourself. Unchanged contract.
+           background|async_job=true job is created AND driven to completion off-thread, matching what
+                                     `background` means on every other tool here. Poll batch_job_status
+                                     until status is completed / completed_with_errors / canceled.
+         An explicit dry_run=true still returns the synchronous plan and starts nothing. A dry_run that
+         came from the dry_run_first_default preference does not override an explicit async request.
       detect_sync_events(paths?|target?, event_types?, windows?) -> {files, alignment}
       add_sync_event_markers(target?|paths?|detections?, confirm?) -> {added, skipped}
       publish_clip_metadata(target?, fields?, slate_detection?, timed_markers?|write_markers?, dry_run?, confirm?) -> {results}
@@ -18787,21 +18900,56 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
             if warnings:
                 target_err["warnings"] = warnings
             return target_err
+        capabilities = detect_media_analysis_capabilities()
         created = create_media_analysis_batch_job(
             project_name=project_name,
             project_id=project_id,
             records=records or [],
             target=normalized_target,
             params=p,
-            capabilities=detect_media_analysis_capabilities(),
+            capabilities=capabilities,
             name=p.get("name") or p.get("job_name") or p.get("jobName"),
         )
         if warnings:
             created.setdefault("warnings", warnings)
+        # A created job sits at "queued" and nothing advances it on its own.
+        # That is the right default for start_batch_job and prefer_handle, whose
+        # contract is "here is a handle, drive it". It is the wrong one for
+        # background/async_job, which promise the work is under way — so those
+        # get a runner. Reached either by the analyze_* divert (which sets
+        # _async_mode) or by calling start_batch_job with background=true.
+        job_id = str((created.get("job") or {}).get("job_id") or "")
+        project_root = str((created.get("plan") or {}).get("output_root") or "")
+        wants_runner = p.get("_async_mode") == MEDIA_ANALYSIS_ASYNC_RUNNING or (
+            _media_analysis_bool(p.get("background"), False)
+            or _media_analysis_bool(p.get("async_job"), False)
+        )
+        if wants_runner and job_id and project_root:
+            started = start_media_analysis_batch_job_runner(
+                project_root, job_id, capabilities=capabilities
+            )
+            created["running"] = bool(started.get("started"))
+            created["note"] = (
+                f"Analysis is running off-thread. Poll with "
+                f"media_analysis(action='batch_job_status', params={{'job_id': '{job_id}'}})."
+            )
+            if not started.get("started"):
+                created["note"] = (
+                    f"Job created but not started ({started.get('reason')}). Drive it with "
+                    f"media_analysis(action='run_batch_job_slice', params={{'job_id': '{job_id}'}})."
+                )
+        else:
+            created["running"] = False
+            created["note"] = (
+                f"Job is queued, not running. Drive it with "
+                f"media_analysis(action='run_batch_job_slice', params={{'job_id': '{job_id}'}}), "
+                f"or pass background=true to have the server run it."
+            )
         return created
 
     if action in {"analyze_file", "analyze_clip", "analyze_bin", "analyze_project", "analyze_timeline", "analyze_sequence"}:
         dry_run_default = bool(_media_analysis_effective_preferences().get("dry_run_first_default"))
+        dry_run_explicit = _has_any_param(p, "dry_run", "dryRun")
         p["dry_run"] = _media_analysis_bool(p.get("dry_run"), dry_run_default)
         target = _media_analysis_target_dict(p.get("target"), p)
         if target.get("_invalid_target"):
@@ -18821,15 +18969,17 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
                 "track_types": p.get("track_types") or p.get("trackTypes") or target.get("track_types") or target.get("trackTypes"),
             })
         p["target"] = target
-        # E3 — `prefer_handle` opt-in. When true AND this isn't a dry-run,
-        # divert to the durable batch-job machinery so the call returns a
-        # job_id immediately instead of blocking on vision/transcription.
-        # Default false: existing blocking semantics are preserved.
+        # E3 — async opt-ins. `prefer_handle` hands back a queued job for the
+        # caller to drive; `background`/`async_job` additionally start driving
+        # it. Either way the call returns at once instead of blocking on
+        # vision/transcription. Default: unchanged blocking semantics.
         # The start_batch_job handler lives ABOVE this block in the dispatch
         # chain, so we can't just rewrite `action` and fall through — we
         # re-enter the tool with the rewritten action via await so the
         # handler chain restarts from the top.
-        if _media_analysis_bool(p.get("prefer_handle"), False) and not p.get("dry_run"):
+        async_mode = _media_analysis_async_mode(p, dry_run_explicit=dry_run_explicit)
+        if async_mode:
+            p["_async_mode"] = async_mode
             return await media_analysis("start_batch_job", p, ctx)
         action = "plan"
 
@@ -21531,9 +21681,12 @@ def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> An
 
     Marker frames are RELATIVE to the timeline start: frame 0 is the first
     frame of the timeline, even when the timeline starts at 01:00:00:00.
-    Timecode params are absolute timeline timecode as shown in the Resolve UI
-    (timecodes before the start timecode are treated as elapsed time) and are
-    converted to relative frames automatically.
+    Marker timecode params are absolute timeline timecode as shown in the
+    Resolve UI (timecodes before the start timecode are treated as elapsed
+    time) and are converted to relative frames automatically.
+    set_current_timecode accepts the same convention: elapsed timecodes below
+    the start timecode are lifted to absolute before calling Resolve, which
+    itself refuses sub-start timecodes with a bare False.
 
     Actions:
       add(frame|frame_id|frameId|timecode?, color?, name?, note?, duration?, custom_data?) -> {success, frame}
@@ -21598,7 +21751,7 @@ def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> An
     elif action == "get_current_timecode":
         return {"timecode": tl.GetCurrentTimecode()}
     elif action == "set_current_timecode":
-        return {"success": bool(tl.SetCurrentTimecode(p["timecode"]))}
+        return {"success": bool(tl.SetCurrentTimecode(_playhead_absolute_timecode(tl, p["timecode"])))}
     elif action == "get_current_video_item":
         it = tl.GetCurrentVideoItem()
         return {"name": it.GetName(), "id": it.GetUniqueId()} if it else {"name": None, "id": None}

package/src/utils/api_truth.py

@@ -645,7 +645,11 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "a real one-frame error just as easily.",
         "recommended": "Verify source-side placement with GetLeftOffset, which is exact. "
                        "Treat GetSourceStartFrame as approximate, and never diff it "
-                       "against a sent startFrame to decide whether a clip landed right.",
+                       "against a sent startFrame to decide whether a clip landed right. "
+                       "Scope: placement at 100% speed. On a retimed clip the two read "
+                       "DIFFERENT domains — GetLeftOffset is warped (position / speed), "
+                       "GetSourceStartFrame is true source — see the retime entry's "
+                       "witness calibration before comparing them.",
         "tags": ["off-by-one", "unreliable-return", "timeline", "conform", "verify"],
         "submit": "bug",
     },
@@ -710,10 +714,14 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "one 200% clip per timeline, a document carrying warped "
                    "<in>/<out>, true-source pproTicks, <duration> = fileLen/ratio "
                    "and a constant-slope graphdict imports cleanly, the control "
-                   "lands correct, and the 200% clip reads back src 1500..1548 — a "
-                   "48-frame source span over a 48-frame record span, i.e. NO "
-                   "retime; emitting the identical document WITHOUT the graphdict "
-                   "gives the identical result; (c) `reverse` does not survive "
+                   "lands correct, and NO retime is built: recalibrated 2026-08-05, "
+                   "every xmeml-imported clip carries a DEGENERATE time map in "
+                   "Project.db (Sm2TimeMap with an empty source axis — five Time "
+                   "Remap shapes re-measured, 15/15 clips degenerate), so no speed "
+                   "exists in the project data, and the API source witness reads "
+                   "0/0 on those clips (see WITNESS CALIBRATION below); emitting "
+                   "the identical document WITHOUT the graphdict gives the "
+                   "identical result; (c) `reverse` does not survive "
                    "either; (d) THE HAZARD, and it is the part that bites: Resolve "
                    "reads <in> LITERALLY as the true source frame, honouring neither "
                    "the ticks nor the graphdict. Import a genuine Premiere XML that "
@@ -750,24 +758,76 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "verifying a retime by round-tripping through EXPORT_FCP_7_XML "
                    "is reading furniture, and the identity Time Remap blocks "
                    "present on every clip are what make the route look like it "
-                   "should work.",
-        "recommended": "Set clip speed/retime in the Resolve UI; no scripted "
-                       "equivalent exists, and the scripting-API xmeml import does "
-                       "not carry one in. Do NOT read speed back with GetProperty "
-                       "(None) or witness it via EXPORT_FCP_7_XML (degenerate). "
-                       "Read the clip's GEOMETRY instead — GetLeftOffset / "
-                       "GetRightOffset, whose source span is what shows whether a "
-                       "retime was built (the re-tested 200% clip read src "
-                       "1500..1548, 48 source frames over a 48-frame record, so "
-                       "none was). Caveat worth keeping: there is still no positive "
-                       "control — no clip KNOWN to be retimed has been read back "
-                       "through those two witnesses, because there is no scripting "
-                       "path to create one, so the geometry witness is the best "
-                       "available, not a proven one. And if you are importing a real "
-                       "Premiere XML that contains retimes, treat every retimed "
-                       "clip's source position as WRONG — placed at <in>, i.e. "
-                       "in / ratio — until it is checked against a reference; the "
-                       "lengths and the links will look right.",
+                   "should work. "
+                   "WITNESS CALIBRATION (2026-08-05, Studio 19.1.3.7) — the "
+                   "positive control this entry previously lacked now exists, and "
+                   "it RETRACTS the witness the 2.80.0 revision of this entry "
+                   "recommended. The rig removed every confound: the SAME clip "
+                   "placed twice, adjacent, in ONE timeline, the second copy "
+                   "hand-set to 200% in the UI (the only way to make one — see "
+                   "above). GetSourceStartFrame/GetSourceEndFrame separated the "
+                   "copies — 1822..1870 (span 48) at 100% vs 1822..1918 (span 96) "
+                   "at 200% — while GetLeftOffset/GetRightOffset did NOT: "
+                   "1822..1870 at 100% vs 911..959 at 200%, which is exactly "
+                   "position / 2. GetLeftOffset reports the WARPED (record-side) "
+                   "domain — position / speed, the `In` column of Project.db's "
+                   "Sm2TiItem — so it is exact for PLACEMENT and blind for SPEED "
+                   "BY CONSTRUCTION: its span equals the record span at every "
+                   "speed. The speed itself lives in the item's Sm2TimeMap blob "
+                   "(keyframe slope = ratio; the hand-set 200% reads slope exactly "
+                   "2.0), which is what GetSourceStart/EndFrame and EXPORT_EDL "
+                   "read. THE SPEED WITNESS is therefore the GetSourceStart/"
+                   "EndFrame span vs the record duration. CAVEAT: on "
+                   "xmeml-IMPORTED timelines those return 0/0 — the importer "
+                   "leaves the time map's source axis empty — and a 0/0 read is "
+                   "UNKNOWN, never 'no retime'. Cross-checks that work everywhere: "
+                   "the Sm2TimeMap slope read from a saved Project.db, and the "
+                   "EXPORT_EDL M2 rate (rate = fps x speed/100, so 048.0 = 200% at "
+                   "24 fps; `M2 ... 000.0` on every clip is the degenerate-map "
+                   "furniture of an xmeml import — ignore it). "
+                   "TWO IMPORT ROUTES DO BUILD CONSTANT RETIMES (measured "
+                   "2026-08-05, media linked, judged via the calibrated witnesses "
+                   "above): (1) OTIO LinearTimeWarp through ImportTimelineFromFile "
+                   "— 200% (src 200..296 over a 48-frame record) and 50% (src "
+                   "300..324 over a 48-frame record) both landed with correct "
+                   "source in-points; the saved Project.db shows slope 2.0 and "
+                   "0.5. Emission rules: the document must be Resolve-shaped with "
+                   "TIMECODE-ABSOLUTE source frames (see the ImportTimelineFromFile "
+                   ".otio entry), the effect is `LinearTimeWarp.1` with "
+                   "`time_scalar`, and `source_range.duration` is the RECORD span "
+                   "— OTIO semantics, the time_scalar handles source consumption; "
+                   "sending the source span as the duration builds a "
+                   "spec-correctly longer clip, not a retime. (2) EDL M2 — 200% "
+                   "landed (src 100..196 over a 48-frame record), linked. Author "
+                   "the shape Resolve's own EXPORT_EDL writes: the event line's "
+                   "source span EQUALS the record span even under M2; the "
+                   "`M2 <reel> <rate> <srcInTC>` line carries the play rate in "
+                   "fps (048.0 = 200% at 24); `* FROM CLIP NAME:` comments drive "
+                   "pool linking. UNTESTED as import routes: reverse (negative "
+                   "time_scalar / reverse M2) and varying-speed maps — do not "
+                   "extrapolate the constant-speed result to them.",
+        "recommended": "Set clip speed/retime in the Resolve UI, or BUILD it by "
+                       "import: OTIO LinearTimeWarp and EDL M2 both construct "
+                       "constant retimes through ImportTimelineFromFile (measured "
+                       "— emission rules in reality above); xmeml does not, in any "
+                       "Time Remap shape. To READ a retime back, judge speed by "
+                       "the GetSourceStart/EndFrame span vs the record duration — "
+                       "a 0/0 read (xmeml-imported timelines) is UNKNOWN, never "
+                       "'no retime' — and cross-check with the Sm2TimeMap slope in "
+                       "a saved Project.db or the EXPORT_EDL M2 rate. Do NOT read "
+                       "speed with GetProperty (None), witness it via "
+                       "EXPORT_FCP_7_XML (degenerate), or judge it from "
+                       "GetLeftOffset/GetRightOffset — the 2.80.0 revision of this "
+                       "entry recommended that pair as the witness and it is blind "
+                       "by construction: it reads the warped domain (position / "
+                       "speed) and its span equals the record span at every speed. "
+                       "Keep it for PLACEMENT checks only. Reverse and "
+                       "varying-speed maps remain untested as import routes. And "
+                       "if you are importing a real Premiere XML that contains "
+                       "retimes, treat every retimed clip's source position as "
+                       "WRONG — placed at <in>, i.e. in / ratio — until it is "
+                       "checked against a reference; the lengths and the links "
+                       "will look right.",
         "tags": ["missing-method", "timeline", "retime", "speed", "interchange",
                  "silent-failure", "unreliable-return"],
         "submit": "missing",

package/src/utils/media_analysis.py

@@ -17,6 +17,7 @@ import os
 import platform as _platform
 import re
 import shutil
+import signal
 import sqlite3
 import subprocess
 import sys
@@ -2376,23 +2377,105 @@ def build_plan(
     }
 
 
-def _run_command(args: List[str], timeout: int = COMMAND_TIMEOUT_SECONDS) -> Tuple[int, str, str]:
+def _kill_process_tree(pid: int) -> None:
+    """Best-effort: terminate pid and its descendants, not just the direct child.
+
+    Popen.kill() reaches only the immediate child. On Windows a bare-name PATH
+    lookup can resolve to a wrapper — a Chocolatey/npm shim, a pip console
+    script — that runs the real work as a grandchild, which a single-PID kill
+    leaves untouched. Measured: `ffmpeg` on PATH was a 392KB shim, and a 5s
+    timeout against an ~82s real ffmpeg pass had no effect at all, because the
+    surviving grandchild still held the stdout/stderr handles it had inherited
+    and the follow-up read blocked until it finished on its own.
+
+    Failure here is never fatal. The caller is already on its error path and
+    owes its own caller a (code, stdout, stderr) tuple, so this must not raise:
+    `taskkill` can be absent from PATH and `killpg` can return EPERM, which is
+    why the whole branch catches OSError rather than only ProcessLookupError.
+    """
     try:
-        proc = subprocess.run(
+        if os.name == "nt":
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(pid)],
+                capture_output=True,
+                check=False,
+            )
+        else:
+            os.killpg(pid, signal.SIGKILL)
+    except OSError:
+        pass
+
+
+# How long to wait for the pipes to drain after a tree kill. The kill is
+# best-effort, so this read has to be bounded: anything that escaped it still
+# holds the inherited pipe handles, and an unbounded read there would hang for
+# exactly the reason the kill exists.
+_POST_KILL_DRAIN_SECONDS = 5
+
+
+def _run_command(
+    args: List[str],
+    timeout: int = COMMAND_TIMEOUT_SECONDS,
+    env: Optional[Dict[str, str]] = None,
+) -> Tuple[int, str, str]:
+    """Run args to completion and return (returncode, stdout, stderr).
+
+    Spawned via Popen rather than subprocess.run so a timeout can kill the whole
+    process tree instead of one PID — see _kill_process_tree.
+
+    `env=None` inherits this process's environment, matching what subprocess.run
+    did. Pass an explicit mapping for a child that must not inherit it: on
+    Windows this server sets PYTHONHOME so the fusionscript bridge can find
+    Resolve's Python, and a child that is itself a *different* Python (the
+    whisper CLI) dies loading a foreign stdlib against its own C extensions.
+
+    Returns 124 on timeout, 127 when the binary cannot be spawned.
+    """
+    popen_kwargs: Dict[str, Any] = {}
+    if os.name == "nt":
+        # Isolates the child from console signals sent to the server. Note this
+        # is not what makes the tree kill work — taskkill /T walks parent-child
+        # links, not process groups. start_new_session is load-bearing on POSIX,
+        # where killpg needs the child to lead a group of its own.
+        popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        popen_kwargs["start_new_session"] = True
+    try:
+        proc = subprocess.Popen(
             args,
-            capture_output=True,
-            timeout=timeout,
-            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=env,
+            **popen_kwargs,
         )
-    except subprocess.TimeoutExpired as exc:
-        stdout = exc.stdout.decode("utf-8", errors="replace") if exc.stdout else ""
-        stderr_tail = exc.stderr.decode("utf-8", errors="replace") if exc.stderr else ""
-        return 124, stdout, f"Command timed out after {timeout}s. {stderr_tail}".strip()
     except OSError as exc:
         return 127, "", str(exc)
-    stdout = proc.stdout.decode("utf-8", errors="replace") if proc.stdout else ""
-    stderr = proc.stderr.decode("utf-8", errors="replace") if proc.stderr else ""
-    return proc.returncode, stdout, stderr
+    try:
+        stdout, stderr = proc.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        _kill_process_tree(proc.pid)
+        abandoned = False
+        try:
+            stdout, stderr = proc.communicate(timeout=_POST_KILL_DRAIN_SECONDS)
+        except subprocess.TimeoutExpired:
+            # A descendant outlived the tree kill and still holds the pipes.
+            # Give up the output rather than block — a stalled caller is a
+            # worse outcome than a timeout report with no stderr tail.
+            stdout, stderr = b"", b""
+            abandoned = True
+        stdout_s = stdout.decode("utf-8", errors="replace") if stdout else ""
+        stderr_s = stderr.decode("utf-8", errors="replace") if stderr else ""
+        detail = " Output abandoned: a descendant survived the kill." if abandoned else ""
+        return 124, stdout_s, f"Command timed out after {timeout}s.{detail} {stderr_s}".strip()
+    except BaseException:
+        # subprocess.run kills the child on any exception on the way out;
+        # Popen does not. Under the server's threaded dispatch a cancellation
+        # or KeyboardInterrupt here would otherwise leave an orphaned tree.
+        _kill_process_tree(proc.pid)
+        raise
+    stdout_s = stdout.decode("utf-8", errors="replace") if stdout else ""
+    stderr_s = stderr.decode("utf-8", errors="replace") if stderr else ""
+    return proc.returncode, stdout_s, stderr_s
 
 
 def _write_json(path: str, payload: Dict[str, Any]) -> None:
@@ -4023,7 +4106,28 @@ def _transcribe_with_whisper_cli(path: str, artifacts: Dict[str, Any], transcrip
     ]
     if transcription.get("language"):
         cmd.extend(["--language", str(transcription["language"])])
-    code, _, stderr = _run_command(cmd, timeout=int(transcription.get("timeout", 1800)))
+    # PYTHONHOME/PYTHONPATH point this server at Resolve's bundled Python so
+    # DaVinciResolveScript imports. Inherited by a child that is itself a
+    # *different* Python, they corrupt its stdlib resolution — and the whisper
+    # CLI is exactly that: a Python program, frequently on another interpreter
+    # entirely. Measured: whisper under Python 3.14 inheriting a 3.10
+    # PYTHONHOME loads 3.10's stdlib against its own compiled extensions and
+    # dies on `AssertionError: SRE module mismatch`. That crash is fast, not a
+    # hang; it only reads as one when something else delays the response.
+    #
+    # This is the shipped Windows configuration, not a local quirk: install.py
+    # writes PYTHONHOME into generated client configs (see docs/install.md,
+    # issue #26), and server.py sets it on Windows whenever it isn't already
+    # set. So every Windows install hands a foreign PYTHONHOME to every child
+    # it spawns, and any Python-based tool added here needs the same scrub.
+    #
+    # PYTHONIOENCODING=utf-8 is unrelated: it avoids a UnicodeEncodeError in
+    # whisper's own argparse help text on a non-UTF-8 console.
+    whisper_env = dict(os.environ)
+    whisper_env.pop("PYTHONHOME", None)
+    whisper_env.pop("PYTHONPATH", None)
+    whisper_env["PYTHONIOENCODING"] = "utf-8"
+    code, _, stderr = _run_command(cmd, timeout=int(transcription.get("timeout", 1800)), env=whisper_env)
     if code != 0:
         return {"success": False, "backend": "whisper_cli", "error": stderr.strip() or "whisper CLI failed"}
     json_files = sorted(Path(work_dir).glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)

package/src/utils/media_analysis_jobs.py

@@ -13,6 +13,7 @@ import hashlib
 import json
 import os
 import sqlite3
+import threading
 import time
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional, Tuple
@@ -795,6 +796,135 @@ def run_batch_job_slice(
     }
 
 
+# A job reaching one of these is finished; the runner stops rather than
+# spinning on a queue that will never drain.
+TERMINAL_JOB_STATUSES = {"completed", "completed_with_errors", "canceled"}
+
+# Runner threads in flight, keyed by (project_root, job_id). Starting a second
+# runner for a job already being driven is a no-op, not a second pump — two
+# pumps on one job would race for the same pending rows.
+_ACTIVE_RUNNERS: Dict[Tuple[str, str], threading.Thread] = {}
+_RUNNERS_LOCK = threading.Lock()
+
+# Exactly one slice executes at a time across the whole process. Slices are
+# bounded (max_clips defaults to 1), so several jobs interleave a clip at a
+# time instead of one starving the others — and a laptop never ends up running
+# N ffmpeg/whisper passes at once because someone queued N analyses.
+_SLICE_LOCK = threading.Lock()
+
+
+def _job_status_value(root: str, job_id: str) -> Optional[str]:
+    """Current status string for a job, or None if it no longer exists.
+
+    Deliberately not batch_job_status: that assembles every clip row and event
+    for the caller, and the runner only needs the one column between slices.
+    """
+    conn = _connect_jobs(root)
+    try:
+        row = conn.execute("SELECT status FROM jobs WHERE job_id = ?", (job_id,)).fetchone()
+        return str(row["status"]) if row else None
+    finally:
+        conn.close()
+
+
+def _drive_batch_job(root: str, job_id: str, capabilities: Optional[Dict[str, Any]], max_clips: int) -> None:
+    """Run slices back to back until the job finishes, is canceled, or stalls."""
+    try:
+        while True:
+            status = _job_status_value(root, job_id)
+            if status is None or status in TERMINAL_JOB_STATUSES:
+                return
+            with _SLICE_LOCK:
+                result = run_batch_job_slice(
+                    root, job_id, max_clips=max_clips, capabilities=capabilities
+                )
+            if not result.get("success"):
+                return
+            # No pending rows left to claim. Either the job just finished (the
+            # status check above catches that next pass) or it is wedged; in
+            # both cases another identical slice would be a spin.
+            if not int(result.get("processed_count") or 0):
+                return
+            if str((result.get("job") or {}).get("status") or "") in TERMINAL_JOB_STATUSES:
+                return
+    except Exception as exc:  # pragma: no cover - defensive; per-clip errors are handled in the slice
+        conn = _connect_jobs(root)
+        try:
+            _event(conn, job_id, "error", "Batch job runner stopped", {"error": f"{type(exc).__name__}: {exc}"})
+            conn.commit()
+        except Exception:
+            pass
+        finally:
+            conn.close()
+    finally:
+        with _RUNNERS_LOCK:
+            _ACTIVE_RUNNERS.pop((root, job_id), None)
+
+
+def start_batch_job_runner(
+    project_root: str,
+    job_id: str,
+    *,
+    capabilities: Optional[Dict[str, Any]] = None,
+    max_clips: int = 1,
+) -> Dict[str, Any]:
+    """Drive a queued batch job to completion on a daemon thread.
+
+    This is what makes `background=true` mean the same thing on the analyze_*
+    actions as it does everywhere else in the server: the work is running when
+    the call returns, and the caller polls until it stops. Without it,
+    start_batch_job only ever left a row at status "queued" that nothing
+    advanced, so a caller that trusted the name waited forever.
+
+    Deliberately NOT routed through background_jobs.start_job, which wraps its
+    worker in resolve_busy.long_resolve_op. That gate exists to serialize calls
+    against Resolve's single-threaded scripting bridge, and analysis touches it
+    nowhere — media_analysis and this module drive ffmpeg, whisper and vision
+    over file paths only. Holding the gate for an hour of transcription would
+    lock the editor out of Resolve for the duration, for no benefit.
+
+    Returns {"started": bool, "reason": str} — `started` is False when a runner
+    is already driving this job or the job is already finished, neither of
+    which is an error.
+    """
+    root = normalize_path(project_root)
+    key = (root, job_id)
+    status = _job_status_value(root, job_id)
+    if status is None:
+        return {"started": False, "reason": "job_not_found"}
+    if status in TERMINAL_JOB_STATUSES:
+        return {"started": False, "reason": f"job_already_{status}"}
+    with _RUNNERS_LOCK:
+        existing = _ACTIVE_RUNNERS.get(key)
+        if existing is not None and existing.is_alive():
+            return {"started": False, "reason": "already_running"}
+        thread = threading.Thread(
+            target=_drive_batch_job,
+            args=(root, job_id, capabilities, max(1, int(max_clips or 1))),
+            name=f"media-analysis-job-{job_id}",
+            daemon=True,
+        )
+        _ACTIVE_RUNNERS[key] = thread
+    thread.start()
+    return {"started": True, "reason": "running"}
+
+
+def join_batch_job_runner(project_root: str, job_id: str, timeout: Optional[float] = None) -> bool:
+    """Block until this job's runner exits. True if it is gone, False on timeout.
+
+    A daemon thread dies with the process, so a server restart leaves a job
+    stuck at "running" with nothing driving it — resume_batch_job is the way
+    back from that. This exists so tests (and any caller that genuinely needs
+    to wait) don't have to poll the database.
+    """
+    with _RUNNERS_LOCK:
+        thread = _ACTIVE_RUNNERS.get((normalize_path(project_root), job_id))
+    if thread is None:
+        return True
+    thread.join(timeout)
+    return not thread.is_alive()
+
+
 def project_root_for_dashboard(project_name: Any, project_id: Any = None, analysis_root: Any = None, source_paths: Optional[Iterable[Any]] = None) -> Dict[str, Any]:
     return resolve_output_root(
         project_name=project_name,