DaVinci Resolve APIAdvancedTimeline

How to Calculate Visible V1 Segments When V2 Clips Overlap

GetItemListInTrack, clip intervals, and Timeline geometry across stacked video tracks

Calculate which portions of V1 remain visible when clips on V2 cover parts of the primary video track, without modifying the Timeline.

API

Resolve Scripting API

Language

Python

Resolve

19–20+

Requires

Running Resolve

Syntax

result = api_method()

Parameters

• The relevant arguments are shown in the complete working example below. Validate paths, object types, and required project state before calling the API method.

Returns

Always validate the returned object, list, identifier, or boolean before continuing to the next automation step.

Complete working Python exampleuse it as a starting point for your own script

import os
import sys
from pathlib import Path


def import_resolve_module():
    try:
        import DaVinciResolveScript as dvr
        return dvr
    except ImportError:
        search_paths = [
            os.environ.get("RESOLVE_SCRIPT_API", ""),
            os.environ.get("RESOLVE_MODULES", ""),
            r"C:\\ProgramData\\Blackmagic Design\\DaVinci Resolve\\Support\\Developer\\Scripting\\Modules",
            "/opt/resolve/Developer/Scripting/Modules",
            "/opt/BlackmagicDesign/DaVinciResolve/Developer/Scripting/Modules",
            "/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting/Modules",
            str(Path.home() / "Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting/Modules"),
        ]
        for path in search_paths:
            if path and os.path.isdir(path) and path not in sys.path:
                sys.path.append(path)
        import DaVinciResolveScript as dvr
        return dvr


def safe_call(obj, name, *args, **kwargs):
    try:
        fn = getattr(obj, name, None)
        if callable(fn):
            return fn(*args, **kwargs)
    except Exception:
        return None
    return None


def get_project_and_timeline():
    dvr = import_resolve_module()
    resolve = dvr.scriptapp("Resolve")
    if not resolve:
        raise RuntimeError("DaVinci Resolve API is unavailable")

    project_manager = safe_call(resolve, "GetProjectManager")
    project = safe_call(project_manager, "GetCurrentProject") if project_manager else None
    if not project:
        raise RuntimeError("No DaVinci Resolve project is open")

    timeline = safe_call(project, "GetCurrentTimeline")
    if not timeline:
        raise RuntimeError("No active Timeline")

    return resolve, project, timeline


def subtract_intervals(base_start: int, base_end: int, blockers: list[tuple[int, int]]) -> list[tuple[int, int]]:
    segments = [(base_start, base_end)]
    for block_start, block_end in blockers:
        next_segments = []
        for start, end in segments:
            if block_end <= start or block_start >= end:
                next_segments.append((start, end))
                continue
            if block_start > start:
                next_segments.append((start, min(block_start, end)))
            if block_end < end:
                next_segments.append((max(block_end, start), end))
        segments = next_segments
    return [(start, end) for start, end in segments if end > start]


def visible_v1_segments(timeline) -> list[dict]:
    v1_items = safe_call(timeline, "GetItemListInTrack", "video", 1) or []
    v2_items = safe_call(timeline, "GetItemListInTrack", "video", 2) or []
    blockers = [(int(safe_call(item, "GetStart") or 0), int(safe_call(item, "GetEnd") or 0)) for item in v2_items]

    result = []
    for item in v1_items:
        start = int(safe_call(item, "GetStart") or 0)
        end = int(safe_call(item, "GetEnd") or start)
        for visible_start, visible_end in subtract_intervals(start, end, blockers):
            result.append({
                "clip": safe_call(item, "GetName") or "",
                "visible_start": visible_start,
                "visible_end": visible_end,
                "duration": visible_end - visible_start,
            })
    return result


resolve, project, timeline = get_project_and_timeline()
for segment in visible_v1_segments(timeline):
    print(segment)

Guide

What the calculation does

The script reads V1 and V2 clips, treats V2 frame ranges as blockers, and subtracts those ranges from each V1 item. The result contains only portions of V1 that are not covered by V2.

How the interval logic works

Each V1 clip starts as one [start, end) interval. Every overlapping V2 interval splits or removes parts of that range. The helper keeps only non-empty fragments after all blockers have been applied.

Where to use it

The result is useful for technical reports, overlay audits, duration calculations, and downstream automation that needs the effective visible duration of the primary track rather than its raw clip duration.

How the example works

Connect to Resolve

Establish a Resolve Scripting API connection and stop early if the application object is unavailable.

Validate the current context

Check the active project, Timeline, Media Pool, source paths, or Render Queue state required by this specific operation.

Run the core API operation

Execute the operation demonstrated in this guide: how to calculate visible v1 segments when v2 clips overlap.

Validate the result

Check the returned value before the workflow continues. Resolve methods often signal an unavailable object or failed operation with None, False, or an empty result.

Resolve API notes

The example treats only V2 as an overlay track.
To include V3 and higher tracks, add their frame ranges to the blocker list as well.
GetStart() and GetEnd() operate in Timeline frames.
Divide frame counts by Timeline FPS when you need durations in seconds.

Common errors

Resolve API is unavailable

Reason: Resolve is closed or Python cannot import/use DaVinciResolveScript.

Fix: Start Resolve and verify the Developer/Scripting/Modules path from the same Python interpreter used by the script.

The method returns None or False

Reason: A required project, Timeline, clip, preset, path, or application state is missing.

Fix: Validate each input and add explicit result checks after important Resolve API calls.

The script only works on one workstation

Reason: Paths or environment assumptions are hard-coded for a single operating system or machine.

Fix: Move paths into configuration and support the required Windows, Linux, and macOS locations explicitly.

Next step

Continue only after the current operation has returned the expected Resolve object or result.

Related API guides

Timeline