davinci-resolve-mcp 2.90.0 → 2.91.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 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.91.0
+
+A timeline item's source frames are counted in the **media's** frame rate, not
+the timeline's — and a WAV carries no native rate, so Resolve reports **24** for
+it. Read back at the timeline rate a WAV offset lands minutes from the real
+position in the file, and nothing errors: `source_end` is derived as
+`source_start + timeline_duration`, so the start/end pair stays internally
+consistent whatever rate the caller assumed. Reported and measured by
+@rusanivsky in #144.
+
+### Added
+
+- **`source_fps` beside the frames.** Every timeline-item summary now carries
+  the rate its source frames are counted in, plus `source_start_seconds` /
+  `source_end_seconds`, so the frame number always arrives with its unit
+  attached. The rate is read from the media-pool item's `FPS` property, never
+  assumed; an unreadable rate reports `null` so callers see *unknown* rather
+  than a guess.
+- **The reader that produced the value is tracked**, because the two do not
+  agree on units: on an audio item `GetLeftOffset` counts in **timeline** frames
+  while `GetSourceStartFrame` counts in **source** frames — 60687 vs 75784 for
+  the same edit point. On that fallback the summary reports `source_fps: null`
+  rather than pairing a timeline-frame number with the media rate.
+- **`create_variant_from_ranges`' per-range `track_index`** — 1-based within
+  `track_type`, missing tracks added — was accepted but undocumented, so
+  multicam angles collapsed onto V1 for anyone who did not read the source. Now
+  in the action help, the action list, the example, and `docs/SKILL.md`.
+- The trap is in the `api_truth` ledger and in `resolve-rough-cut`'s verified
+  traps table.
+
+### Fixed
+
+- **`source_end_seconds` was the same unit lie the field was added to stop.**
+  `source_end` is `source_start + duration`, and that duration comes from
+  `GetDuration` — a **timeline** duration. Converting the sum at the media rate
+  compounds the very mix-up being guarded. The seconds now come from
+  `GetSourceStartTime` / `GetSourceEndTime`, which answer in seconds with no
+  rate inference at all, then from `GetSourceEndFrame / source_fps`, and read
+  `null` rather than convert the derived value. `source_end` itself is
+  unchanged — no consumer moves — but it is now annotated as unit-mixed where
+  it is assigned, in the probe action help, and in the ledger.
+
+### Validation
+
+- Suite: 2613 passed, 1 skipped. `gen_api_limitations.py --check` clean.
+- **Live on Studio 19.1.3.7** with synthetic media, which also shows the trap is
+  not a 21.x regression. A 300 s 48 kHz WAV reports `FPS 24`; appending its
+  source frames 4800–5235 to a 29.97 fps timeline yields a timeline duration of
+  **543** (= 435 × 29.97/24), so `source_end` came back **5343** where the true
+  source end is 5235 — `source_end / 24` reports **222.625 s** against a real
+  **218.133 s**, 4.49 s out on a clip 18.1 s long. The patched code reports
+  218.133 s. The matching 29.97 video item was unaffected either way (24.524 s
+  read vs 24.525 s derived). Both second-readers exist on 19.1.3.7.
+- Not tested here: the 21.0.3.7 measurements in the ledger entry, which are
+  @rusanivsky's and are labelled as such.
+
 ## What's New in v2.90.0
 
 AAF turnovers parsed by `editorial.parse_interchange` on the advanced server now

package/README.md

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

package/docs/SKILL.md

@@ -1381,7 +1381,9 @@ Key actions:
   into an editor-facing beat report
 - `create_variant_from_ranges(name, ranges, markers?, cdl?, dry_run?)` — create
   a guarded timeline variant from declarative source ranges, optional markers,
-  transforms, and CDL
+  transforms, and CDL. Each range takes `track_type?` and a 1-based
+  `track_index?` (default 1), so multicam angles can be rebuilt onto V2/V3
+  rather than collapsing onto V1; missing tracks are added
 - `bulk_set_item_properties(ops, dry_run?, readback?)` — apply transforms,
   crop/composite/audio/property groups to many timeline items in one call
 - `apply_look_to_items(target_ids, cdl?|copy_from_item_id?, dry_run?)` — apply a

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 27 missing capabilities, 32 bugs / unreliable behaviors.
+**Totals:** 27 missing capabilities, 33 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -382,6 +382,14 @@ values, or automation-hostile modal prompts.
 - **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
 
+### TimelineItem.GetSourceStartFrame on an AUDIO item (media-rate frames; 24 fps for WAV)
+
+- **Object:** `TimelineItem`
+- **Signature:** `() -> int  # source frame, counted in the MEDIA's frame rate`
+- **Behavior:** The value is counted in the source MEDIA's own frame rate, not the timeline's — and a WAV carries no frame rate, so Resolve falls back to 24 fps. Reading it at the timeline rate lands minutes away from the real position in the file. Verified live on Studio 21.0.3.7 (2026-08-09, 29.97 fps timeline): a ZOOM0028.WAV item reported source_start 56871, which is 56871 / 24 = 2369.6 s into the file, NOT the 1897.6 s a 29.97 fps reading gives — a 471.9 s (7 min 52 s) error. Nothing looks wrong, because timeline probe_timeline_structure derives source_end as source_start + timeline_duration: the start/end pair stays internally consistent whatever rate you assume. VIDEO items are NOT affected — two 29.97 fps items (KR020007.MOV, IMG_0001.mov) on the same timeline reported source frames in their own, matching rate, confirmed against ffprobe durations and span arithmetic. This is the read-side twin of the AppendToTimeline mixed-fps entry below: that one is about writing source frames whose rate differs from the timeline's, this one about reading them back and not knowing which rate they are in. The rate was pinned by regression, not assumed: across 12 items of the same WAV, GetSourceStartFrame advances at 24.000 fps against the item's own GetSourceStartTime (24.0000/24.0007/23.9995 over spans up to 22 minutes). The same measurement exposed a second unit trap: on an AUDIO item GetLeftOffset advances at 29.970 — the TIMELINE rate — so the two readers describe the same edit point in DIFFERENT frame spaces (60687 vs 75784 for one item). On video they share the source space. Caveat on the absolute zero: Resolve's model of this file is 133003 frames (Duration 01:32:21:19 at 24 fps = 5541.79 s) while its true PCM length is 266264768 samples / 48 kHz = 5547.18 s, a 0.097% difference we have not explained — so frames/24 is exact in Resolve's source-time space, which is the space every other Resolve call uses, but may sit ~2 s off the byte position in a 40-minute-deep offset. Re-confirmed on Studio 19.1.3.7 (2026-08-10) with synthetic media, so this is not a 21.x regression: a 300 s 48 kHz WAV reports FPS 24, and appending source frames 4800-5235 of it to a 29.97 fps timeline yields a timeline duration of 543 (= 435 x 29.97/24), which is the conversion happening in the open. The same run measured the cost of the derived end: source_end came back 5343 (4800 + 543) where the true source end is 5235, so source_end / 24 reports 222.625 s against a real 218.133 s from GetSourceEndTime — 4.49 s out, on a clip only 18.1 s long. GetSourceStartTime read exactly 200.0 s (= 4800/24) on the same item. The matching VIDEO item (29.97 source in a 29.97 timeline) was unaffected in both: 24.524 s read against 24.525 s derived. Both second-readers exist on 19.1.3.7, so the GetSourceEndFrame fallback below is for builds older still.
+- **Workaround / current handling:** Convert an audio item's source frames with the MEDIA's rate, never the timeline's: seconds = source_start / media_fps, treating a WAV (or any container with no native rate) as 24 fps. Take media_fps from the media-pool item's 'FPS' clip property or from ffprobe — do not infer it from the timeline. Feed the frames back to timeline create_variant_from_ranges in the same media-rate space you read them in; it converts on placement and reports the conversion in items[].duration_delta. The separate GetSourceStartFrame entry above (off-by-one vs GetLeftOffset) applies on top of this — the rate question is which unit the number is in, not whether it is exact. Mitigated in-process: _timeline_item_summary now emits source_fps and source_start_seconds/source_end_seconds beside the frames, so the number always arrives with its unit; on the GetLeftOffset fallback for an audio item it reports the rate as unknown rather than converting a timeline-frame value at the media rate. Note which number may be converted: source_end in the same summary is derived as source_start + TIMELINE duration, so on this WAV it adds 435 frames of 29.97 record time to a 24 fps source frame and dividing THAT by 24 reports an 18.125 s span for a 14.515 s clip. The seconds therefore come from GetSourceStartTime/GetSourceEndTime — which answer in seconds with no rate inference at all — then from GetSourceEndFrame / media_fps, and read null rather than convert the derived source_end.
+- **Tags:** timeline, audio, wav, frame-rate, mixed-fps, silent-failure, readback
+
 ### Studio-gated calls on the free edition raise a modal that blocks LATER calls
 
 - **Object:** `Resolve (all objects)`

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.90.0"
+VERSION = "2.91.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.90.0",
+  "version": "2.91.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.90.0"
+VERSION = "2.91.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.90.0"
+VERSION = "2.91.0"
 
 import base64
 import os
@@ -2992,18 +2992,31 @@ def _safe_media_pool_item_name(mpi):
     return None
 
 
-def _timeline_item_source_start(item):
+def _timeline_item_source_start_with_origin(item):
+    """(source_start, origin) — which reader the frame number came from.
+
+    The origin matters because the two readers do not agree on units. On an
+    AUDIO item, measured on Studio 21.0.3.7 across 12 items of one WAV,
+    GetSourceStartFrame advances at exactly 24.000 fps against the item's own
+    GetSourceStartTime (the media's rate) while GetLeftOffset advances at 29.970
+    — the TIMELINE rate. Same edit point, different frame spaces. Callers that
+    attach a rate to the number must know which reader produced it.
+    """
     if _has_method(item, "GetSourceStartFrame"):
         try:
             source_start = _frame_int(item.GetSourceStartFrame())
             if source_start is not None:
-                return source_start
+                return source_start, "GetSourceStartFrame"
         except Exception:
             pass
     try:
-        return _frame_int(item.GetLeftOffset())
+        return _frame_int(item.GetLeftOffset()), "GetLeftOffset"
     except Exception:
-        return None
+        return None, None
+
+
+def _timeline_item_source_start(item):
+    return _timeline_item_source_start_with_origin(item)[0]
 
 
 def _timeline_item_media_pool_item(item):
@@ -3039,7 +3052,103 @@ def _timeline_item_track_info(item):
         return None, _err("invalid source track index")
 
 
-def _timeline_item_summary(item, track_info=None):
+def _media_item_source_fps(media_pool_item, clip_properties=None):
+    """The frame rate a media-pool item's SOURCE frames are counted in.
+
+    Source frames (GetSourceStartFrame / GetLeftOffset) are expressed in the
+    MEDIA's own rate, never the timeline's — and a WAV carries no native rate,
+    so Resolve reports 24 for it. Read the rate instead of assuming the
+    timeline's: at 29.97 a WAV offset lands minutes away from the real position
+    in the file, and nothing errors (see the api_truth entry "GetSourceStartFrame
+    on an AUDIO item"). Returns None when the rate cannot be read, so callers
+    surface "unknown" rather than a guess.
+
+    Pass ``clip_properties`` when the caller already holds the item's property
+    dict — the probe path does, so this costs it no extra bridge call.
+    """
+    value = None
+    if isinstance(clip_properties, dict):
+        value = clip_properties.get("FPS")
+    if value in (None, "") and media_pool_item is not None:
+        try:
+            value = media_pool_item.GetClipProperty("FPS")
+        except Exception:
+            value = None
+        if isinstance(value, dict):  # GetClipProperty("") returns the whole map
+            value = value.get("FPS")
+    try:
+        fps = float(value)
+    except (TypeError, ValueError):
+        return None
+    return fps if fps > 0 else None
+
+
+def _source_frames_to_seconds(frames, fps):
+    """Source frames -> seconds into the file, or None when either is unknown."""
+    if frames is None or not fps:
+        return None
+    return round(frames / fps, 3)
+
+
+def _timeline_item_source_time(item, method):
+    """Resolve's own source-time reader (GetSourceStartTime/GetSourceEndTime).
+
+    Seconds into the source file, read directly — no rate inference, so it is
+    the authoritative answer whenever the build exposes it. None when the
+    method is absent or unreadable, leaving the caller to fall back to
+    frames / source_fps.
+    """
+    if not _has_method(item, method):
+        return None
+    try:
+        value = getattr(item, method)()
+    except Exception:
+        return None
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError):
+        return None
+    return round(seconds, 3)
+
+
+def _timeline_item_source_end_frame(item):
+    """The item's SOURCE-space end frame, from Resolve's own reader.
+
+    Distinct from the ``source_end`` this module derives as
+    ``source_start + duration``: that duration is a TIMELINE duration
+    (GetDuration), so the sum mixes units the moment the media rate differs
+    from the timeline's — always, for a WAV. Only a genuine source-space frame
+    may be divided by source_fps.
+    """
+    if not _has_method(item, "GetSourceEndFrame"):
+        return None
+    try:
+        return _frame_int(item.GetSourceEndFrame())
+    except Exception:
+        return None
+
+
+def _timeline_item_source_seconds(item, source_start, source_end, source_fps):
+    """(start_seconds, end_seconds) into the source file, or None each.
+
+    Prefers Resolve's second-readers, then a source-space frame divided by the
+    media rate. The derived ``source_end`` is deliberately NOT a fallback: it
+    is ``source_start + timeline_duration``, so on a 24 fps WAV in a 29.97 fps
+    timeline it overstates the clip's span by 25% (18.1 s reported for a
+    14.5 s clip). An unknown end reads as unknown.
+    """
+    start_seconds = _timeline_item_source_time(item, "GetSourceStartTime")
+    if start_seconds is None:
+        start_seconds = _source_frames_to_seconds(source_start, source_fps)
+    end_seconds = _timeline_item_source_time(item, "GetSourceEndTime")
+    if end_seconds is None:
+        end_seconds = _source_frames_to_seconds(
+            _timeline_item_source_end_frame(item), source_fps)
+    return start_seconds, end_seconds
+
+
+def _timeline_item_summary(item, track_info=None, *, media_pool_item=None,
+                           clip_properties=None):
     if not item:
         return None
     start = end = duration = source_start = source_end = None
@@ -3049,12 +3158,23 @@ def _timeline_item_summary(item, track_info=None):
     except Exception:
         pass
     duration = _timeline_item_duration(item, start, end)
-    source_start = _timeline_item_source_start(item)
+    source_start, source_start_origin = _timeline_item_source_start_with_origin(item)
     if source_start is not None and duration is not None:
         source_end = source_start + duration
     if track_info is None:
         track_info, _ = _timeline_item_track_info(item)
-    media_pool_item = _timeline_item_media_pool_item(item)
+    if media_pool_item is None:
+        media_pool_item = _timeline_item_media_pool_item(item)
+    # source_* are in the MEDIA's frame rate; report it and the derived seconds
+    # so a caller never has to guess which rate the frame numbers are in.
+    source_fps = _media_item_source_fps(media_pool_item, clip_properties)
+    if source_start_origin == "GetLeftOffset" and (track_info or (None,))[0] == "audio":
+        # GetLeftOffset counts an audio item in TIMELINE frames, so pairing it
+        # with the media rate would produce a confidently wrong number. Report
+        # the frame and leave the rate unknown rather than convert it wrong.
+        source_fps = None
+    source_start_seconds, source_end_seconds = _timeline_item_source_seconds(
+        item, source_start, source_end, source_fps)
     summary = {
         "timeline_item_id": _safe_timeline_item_id(item),
         "name": _safe_timeline_item_name(item),
@@ -3064,7 +3184,13 @@ def _timeline_item_summary(item, track_info=None):
         "end": end,
         "duration": duration,
         "source_start": source_start,
+        # NOTE: derived as source_start + TIMELINE duration, so it is unit-mixed
+        # whenever source_fps != the timeline rate. Kept for compatibility; use
+        # source_end_seconds, which is read from source space, for real time.
         "source_end": source_end,
+        "source_fps": source_fps,
+        "source_start_seconds": source_start_seconds,
+        "source_end_seconds": source_end_seconds,
         "media_pool_item_id": _safe_media_pool_item_id(media_pool_item),
         "media_pool_item_name": _safe_media_pool_item_name(media_pool_item),
     }
@@ -5008,8 +5134,9 @@ def _conform_capabilities():
 
 
 def _timeline_item_conform_summary(item, track_type: str, track_index: int, item_index: int):
-    summary = _timeline_item_summary(item, (track_type, track_index)) or {}
-    summary["item_index"] = item_index
+    # Fetch the media-pool item and its properties FIRST, then hand both to the
+    # summary: it needs the 'FPS' property for source_fps, and this way the probe
+    # pays for one GetMediaPoolItem/GetClipProperty pair per item, not two.
     media_pool_item = _timeline_item_media_pool_item(item)
     file_path = None
     clip_properties = None
@@ -5019,12 +5146,17 @@ def _timeline_item_conform_summary(item, track_type: str, track_index: int, item
             clip_properties = _ser(media_pool_item.GetClipProperty(""))
         except Exception:
             clip_properties = None
-        if isinstance(clip_properties, dict):
-            file_path = clip_properties.get("File Path") or clip_properties.get("FilePath")
-            for key in ("Status", "Media Status", "Offline", "Online Status"):
-                if key in clip_properties:
-                    media_status = clip_properties.get(key)
-                    break
+    summary = _timeline_item_summary(
+        item, (track_type, track_index),
+        media_pool_item=media_pool_item, clip_properties=clip_properties,
+    ) or {}
+    summary["item_index"] = item_index
+    if isinstance(clip_properties, dict):
+        file_path = clip_properties.get("File Path") or clip_properties.get("FilePath")
+        for key in ("Status", "Media Status", "Offline", "Online Status"):
+            if key in clip_properties:
+                media_status = clip_properties.get(key)
+                break
     summary["file_path"] = file_path
     summary["file_exists"] = bool(file_path and os.path.exists(str(file_path)))
     summary["media_status"] = media_status
@@ -5409,7 +5541,8 @@ def _timeline_apply_look_to_items(tl, p: Dict[str, Any]) -> Dict[str, Any]:
 def _variant_item_placement(item) -> Dict[str, Any]:
     """Report an appended item's placed frame positions in both frame spaces.
     record_* are TIMELINE frames (GetStart/GetEnd/GetDuration); source_start is
-    a SOURCE frame."""
+    a SOURCE frame, counted in source_fps — the MEDIA's rate, which for a WAV is
+    24 and not the timeline's."""
     def _read(method):
         fn = getattr(item, method, None)
         if not callable(fn):
@@ -5423,11 +5556,16 @@ def _variant_item_placement(item) -> Dict[str, Any]:
     duration = _read("GetDuration")
     if duration is None and record_start is not None and record_end is not None:
         duration = record_end - record_start
+    source_start = _timeline_item_source_start(item)
+    source_fps = _media_item_source_fps(_timeline_item_media_pool_item(item))
+    source_start_seconds, _ = _timeline_item_source_seconds(item, source_start, None, source_fps)
     return {
         "record_start": record_start,
         "record_end": record_end,
         "duration": duration,
-        "source_start": _timeline_item_source_start(item),
+        "source_start": source_start,
+        "source_fps": source_fps,
+        "source_start_seconds": source_start_seconds,
     }
 
 
@@ -21393,7 +21531,10 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     Frame numbers are TIMELINE/record frames (position on the timeline) unless an action
     says SOURCE. Source frames are positions within a media-pool clip's own media:
     create_variant_from_ranges takes SOURCE start_frame/end_frame; extract_source_frame_ranges
-    and source_range_report return SOURCE ranges.
+    and source_range_report return SOURCE ranges. A SOURCE frame is counted in the MEDIA's own
+    frame rate, not the timeline's: an AUDIO item's source_start/source_end read back in the
+    file's rate, and a WAV (no native rate) defaults to 24 fps, so converting one at the timeline
+    rate is silently wrong by minutes (resolve_control api_truth "GetSourceStartFrame").
 
     Actions:
       list() -> {timelines}
@@ -21449,6 +21590,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         nothing moves. (frames here are TIMELINE/record frames.)
       story_spine_report() -> {beats, track_summaries, source_ranges, audio_spine}
       create_variant_from_ranges(name, ranges, markers?, cdl?, dry_run?) -> {success, id, items}
+        ranges[] take track_type? (video|audio) and track_index? (1-based, within the
+        track_type, default 1); missing tracks are added, so V2/V3 multicam angles survive.
         # example: action_help(name='<action_name>')
       bulk_set_item_properties(ops, dry_run?, readback?) -> {results, op_count}
         # example: action_help(name='<action_name>')
@@ -21511,6 +21654,14 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
         Default handles=24, gap_max=30. Use handles=0 for gap-only auto handles.
       conform_capabilities() -> {supported, partially_supported, unsupported, export_aliases}
       probe_timeline_structure(track_types?, include_markers?, include_clip_properties?) -> {tracks, markers}
+        Each item reports source_start in the MEDIA's frame rate, the source_fps it is
+        counted in, and source_start_seconds/source_end_seconds. Use those seconds — a
+        WAV counts at 24 fps on any timeline, so dividing by the timeline rate is wrong
+        by minutes. source_fps is null when the rate could not be read; treat the frames
+        as unitless then, do not assume the timeline's. source_end is derived as
+        source_start + TIMELINE duration, so it is unit-mixed when the rates differ —
+        the seconds come from Resolve's own source-time readers instead, and read null
+        rather than convert the derived value.
       detect_gaps_overlaps(track_types?, min_gap?) -> {gaps, overlaps}
       source_range_report(handles?, merge?) -> {ranges, occurrences}
       export_timeline_checked(path, format?|type?, subtype?, require_temp_path?, dry_run?, background?) -> {success, path, size | job_id}
@@ -23334,9 +23485,16 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
             "summary": "Build a variant timeline from N source ranges. Video-only unless ranges include track_type='audio'. Source-safe; dry_run validates clip ids and frame ranges.",
             "params": (
                 "name, ranges: [{clip_id|media_pool_item_id, start_frame, end_frame, "
-                "record_frame?, track_type?}], pack?, markers?, cdl?, dry_run?  — clip_id is a "
+                "record_frame?, track_type?, track_index?}], pack?, markers?, cdl?, dry_run?  — clip_id is a "
                 "media-pool item id (not a timeline-item id); start_frame/end_frame are SOURCE "
                 "frames, end_frame exclusive (source duration = end_frame - start_frame). "
+                "track_index is the 1-based destination track WITHIN track_type (default 1); the "
+                "variant is created with enough video/audio tracks to cover the highest index used, "
+                "so multicam angles can be rebuilt onto V2/V3 instead of collapsing onto V1. "
+                "SOURCE frames are counted in the MEDIA's frame rate, not the timeline's — an audio "
+                "item's read back as 24 fps for a WAV (api_truth \"GetSourceStartFrame on an AUDIO "
+                "item\"); pass them in that space, placement converts and items[].duration_delta "
+                "reports the conversion. "
                 "pack=true butts clips together at the end of each track (gap-free, ignores record_frame)"
             ),
             "returns": "{success, id, items}  — items[].placed = placed frames; items[].range = the requested range",
@@ -23344,8 +23502,11 @@ _ACTION_HELP: Dict[str, Dict[str, Dict[str, Any]]] = {
                 'timeline(action="create_variant_from_ranges", params={\n'
                 '  "name": "v02_tighter_act1",\n'
                 '  "ranges": [\n'
-                '    {"clip_id": "<media-pool-item-id>", "start_frame": 1200, "end_frame": 1320},\n'
-                '    {"clip_id": "<media-pool-item-id>", "start_frame": 1500, "end_frame": 1600}\n'
+                '    {"clip_id": "<cam1-id>", "start_frame": 1200, "end_frame": 1320},\n'
+                '    {"clip_id": "<cam3-id>", "start_frame": 1500, "end_frame": 1600,\n'
+                '     "track_index": 2},\n'
+                '    {"clip_id": "<wav-id>", "track_type": "audio", "track_index": 1,\n'
+                '     "start_frame": 56871, "end_frame": 57591}  # 24 fps source frames\n'
                 '  ],\n'
                 '  "dry_run": True\n'
                 '})'

package/src/utils/api_truth.py

@@ -660,6 +660,92 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["off-by-one", "unreliable-return", "timeline", "conform", "verify"],
         "submit": "bug",
     },
+    {
+        "symbol": "TimelineItem.GetSourceStartFrame on an AUDIO item (media-rate frames; 24 fps for WAV)",
+        "object": "TimelineItem",
+        "signature": "() -> int  # source frame, counted in the MEDIA's frame rate",
+        "reality": "The value is counted in the source MEDIA's own frame rate, not "
+                   "the timeline's — and a WAV carries no frame rate, so Resolve "
+                   "falls back to 24 fps. Reading it at the timeline rate lands "
+                   "minutes away from the real position in the file. Verified live "
+                   "on Studio 21.0.3.7 (2026-08-09, 29.97 fps timeline): a "
+                   "ZOOM0028.WAV item reported source_start 56871, which is "
+                   "56871 / 24 = 2369.6 s into the file, NOT the 1897.6 s a 29.97 "
+                   "fps reading gives — a 471.9 s (7 min 52 s) error. Nothing looks "
+                   "wrong, because timeline probe_timeline_structure derives "
+                   "source_end as source_start + timeline_duration: the start/end "
+                   "pair stays internally consistent whatever rate you assume. "
+                   "VIDEO items are NOT affected — two 29.97 fps items "
+                   "(KR020007.MOV, IMG_0001.mov) on the same timeline reported "
+                   "source frames in their own, matching rate, confirmed against "
+                   "ffprobe durations and span arithmetic. This is the read-side "
+                   "twin of the AppendToTimeline mixed-fps entry below: that one is "
+                   "about writing source frames whose rate differs from the "
+                   "timeline's, this one about reading them back and not knowing "
+                   "which rate they are in. The rate was pinned by regression, "
+                   "not assumed: across 12 items of the same WAV, "
+                   "GetSourceStartFrame advances at 24.000 fps against the item's "
+                   "own GetSourceStartTime (24.0000/24.0007/23.9995 over spans up "
+                   "to 22 minutes). The same measurement exposed a second unit "
+                   "trap: on an AUDIO item GetLeftOffset advances at 29.970 — the "
+                   "TIMELINE rate — so the two readers describe the same edit "
+                   "point in DIFFERENT frame spaces (60687 vs 75784 for one "
+                   "item). On video they share the source space. Caveat on the "
+                   "absolute zero: Resolve's model of this file is 133003 frames "
+                   "(Duration 01:32:21:19 at 24 fps = 5541.79 s) while its true "
+                   "PCM length is 266264768 samples / 48 kHz = 5547.18 s, a 0.097% "
+                   "difference we have not explained — so frames/24 is exact in "
+                   "Resolve's source-time space, which is the space every other "
+                   "Resolve call uses, but may sit ~2 s off the byte position in "
+                   "a 40-minute-deep offset. Re-confirmed on Studio 19.1.3.7 "
+                   "(2026-08-10) with synthetic media, so this is not a 21.x "
+                   "regression: a 300 s 48 kHz WAV reports FPS 24, and appending "
+                   "source frames 4800-5235 of it to a 29.97 fps timeline yields "
+                   "a timeline duration of 543 (= 435 x 29.97/24), which is the "
+                   "conversion happening in the open. The same run measured the "
+                   "cost of the derived end: source_end came back 5343 "
+                   "(4800 + 543) where the true source end is 5235, so "
+                   "source_end / 24 reports 222.625 s against a real 218.133 s "
+                   "from GetSourceEndTime — 4.49 s out, on a clip only 18.1 s "
+                   "long. GetSourceStartTime read exactly 200.0 s (= 4800/24) on "
+                   "the same item. The matching VIDEO item (29.97 source in a "
+                   "29.97 timeline) was unaffected in both: 24.524 s read against "
+                   "24.525 s derived. Both second-readers exist on 19.1.3.7, so "
+                   "the GetSourceEndFrame fallback below is for builds older "
+                   "still.",
+        "recommended": "Convert an audio item's source frames with the MEDIA's rate, "
+                       "never the timeline's: seconds = source_start / media_fps, "
+                       "treating a WAV (or any container with no native rate) as 24 "
+                       "fps. Take media_fps from the media-pool item's 'FPS' clip "
+                       "property or from ffprobe — do not infer it from the "
+                       "timeline. Feed the frames back to timeline "
+                       "create_variant_from_ranges in the same media-rate space you "
+                       "read them in; it converts on placement and reports the "
+                       "conversion in items[].duration_delta. The separate "
+                       "GetSourceStartFrame entry above (off-by-one vs "
+                       "GetLeftOffset) applies on top of this — the rate question "
+                       "is which unit the number is in, not whether it is exact. "
+                       "Mitigated in-process: _timeline_item_summary now emits "
+                       "source_fps and source_start_seconds/source_end_seconds "
+                       "beside the frames, so the number always arrives with its "
+                       "unit; on the GetLeftOffset fallback for an audio item it "
+                       "reports the rate as unknown rather than converting a "
+                       "timeline-frame value at the media rate. Note which "
+                       "number may be converted: source_end in the same summary "
+                       "is derived as source_start + TIMELINE duration, so on "
+                       "this WAV it adds 435 frames of 29.97 record time to a 24 "
+                       "fps source frame and dividing THAT by 24 reports an "
+                       "18.125 s span for a 14.515 s clip. The seconds therefore "
+                       "come from GetSourceStartTime/GetSourceEndTime — which "
+                       "answer in seconds with no rate inference at all — then "
+                       "from GetSourceEndFrame / media_fps, and read null rather "
+                       "than convert the derived source_end.",
+        "tags": ["timeline", "audio", "wav", "frame-rate", "mixed-fps",
+                 "silent-failure", "readback"],
+        "submit": "bug",
+        "mitigation": ["_media_item_source_fps", "_source_frames_to_seconds",
+                       "_timeline_item_source_seconds"],
+    },
     {
         "symbol": "Razor / blade / split a timeline item",
         "object": "Timeline / TimelineItem",