DaVinci Resolve APIIntermediateMedia Pool

How to Import Media and Map MediaPoolItem Objects by File Path

ImportMedia, GetClipProperty, and a reusable path-to-MediaPoolItem lookup

Import multiple source files and build a normalized dictionary that lets later automation find the corresponding MediaPoolItem for each original path.

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 import_media_map_by_path(media_pool, paths: list[str]) -> dict[str, object]:
    unique = []
    seen = set()
    for path in paths:
        if not path:
            continue
        key = str(Path(path)).lower()
        if key not in seen:
            unique.append(path)
            seen.add(key)

    if not unique:
        return {}

    imported = safe_call(media_pool, "ImportMedia", unique) or []
    by_path = {}

    for item in imported:
        props = safe_call(item, "GetClipProperty") or {}
        file_path = props.get("File Path") or props.get("FilePath") or props.get("file_path") or ""
        if file_path:
            by_path[str(Path(file_path)).lower()] = item

    for item in imported:
        name = str(safe_call(item, "GetName") or "")
        for path in unique:
            key = str(Path(path)).lower()
            if key not in by_path and Path(path).name.lower() == name.lower():
                by_path[key] = item

    return by_path


resolve, project, timeline = get_project_and_timeline()
media_pool = safe_call(project, "GetMediaPool")
items = import_media_map_by_path(media_pool, [r"D:\\media\\clip01.mov", r"D:\\media\\music.wav"])
print("Imported items:", len(items))

Guide

What the example builds

The helper removes duplicate input paths, imports the remaining files, and creates a dictionary whose normalized source path points to the corresponding MediaPoolItem.

Why there is a second matching pass

The file-path property can vary across Resolve versions or may not be available in the expected form. As a fallback, the example compares imported item names with the source filenames when a path was not mapped during the first pass.

Where the map is useful

This lookup is particularly useful before bulk AppendToTimeline operations: import sources once, then retrieve the required MediaPoolItem quickly for each placement instead of repeatedly searching or re-importing files.

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 import media and map mediapoolitem objects by file path.

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

ImportMedia returns only items that Resolve successfully imported.
GetClipProperty can expose the source path under different property names.
Normalize paths before comparing them.
Use Media Pool folders and deliberate asset management when the project needs more than a lightweight path lookup.

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

Media Pool