Как получить текущий проект DaVinci Resolve через Python

01 / BEFORE THE CODE

До кода — условия запуска.

Ориентируйтесь на актуальные требования Studio и документацию установленной версии, а не на старые инструкции для консоли или Free.[1][4][3]

02 / API CONTRACT

Какой объект. Какой метод. Какой результат.

Контракты методов Resolve описаны Blackmagic; Python и авторские helper обозначены отдельно. Дополнительные проверки — устройство наших примеров. Непустой объект не доказывает совместимость всего API.[3]

03 / UNDERSTAND

Менеджер не является проектом

GetProjectManager возвращает объект для операций с библиотекой и проектами. GetCurrentProject вызывается уже у этого менеджера. Имя проекта читает project.GetName(), а не print(project): строковое представление native-объекта не заменяет его свойства.

Запрос не ищет проект по имени и не открывает его. Это полезное ограничение перед автоматизацией: пользователь явно выбирает рабочую цель в Resolve, а скрипт проверяет выбранное состояние.[3]

04 / UNDERSTAND

Почему одного имени недостаточно

В разных Project Library и папках могут встречаться одинаковые названия. В примере --expect-project — дополнительная проверка точного имени, а не универсальный адрес и не разрешение на правки. Отчёт также содержит GetUniqueId; сравнивать идентичность сессии надёжнее, чем полагаться на одно название.

Для устойчивого workflow сохраняйте контекст выбранной библиотеки отдельно. Не считайте, что экспорт/импорт проекта или его копирование обязаны сохранять прежний ID. В этой статье идентификатор используется для сверки текущего объекта в рамках одного короткого чтения.

Имена и ID в выводе реальны, если скрипт запущен у вас. Прежде чем переслать JSON заказчику или в поддержку, проверьте, нет ли в названии проекта персональных данных.[3]

05 / UNDERSTAND

Проект без таймлайна — нормальный случай

GetTimelineCount сообщает количество таймлайнов, а GetCurrentTimeline возвращает активный объект. Пример допускает count=0 и current_timeline=null. Если ваша следующая задача — импорт в Media Pool, активный таймлайн может вообще не требоваться.

Если следующая операция относится к конкретному Timeline, задайте отдельное требование: получить нужный объект, проверить его имя/ID и лишь затем продолжать. Не используйте автоматически GetTimelineByIndex(1) как «тот самый» таймлайн: порядок списка не выражает намерение пользователя.[3]

06 / UNDERSTAND

Повторное чтение — проверка, но не транзакция

В конце пример повторно получает текущий проект и сравнивает ID. Если пользователь переключил проект во время чтения, отчёт отбрасывается с ошибкой. Это защищает от части изменений состояния между вызовами.

Последовательность API-вызовов не становится атомарной: таймлайн может смениться внутри того же проекта, проект может поменяться и вернуться, а содержимое — измениться другим участником. Поэтому здесь нет формулировки «полностью согласованный снимок». Для будущих правок нужны отдельные предусловия и исключение параллельных действий.[3]

07 / UNDERSTAND

Как использовать результат дальше

Держите зависимости явными: приложение → менеджер → проект → опциональный таймлайн. Не прячьте получение проекта внутрь функции, которая при неудаче молча создаёт новый. Это особенно важно, когда тот же код затем используется для удаления клипов или рендера.

После успешного чтения можно перейти к отдельной статье по Media Pool или таймлайнам. Сам этот отчёт не подтверждает, что выбран правильный диапазон, материал находится онлайн или настройки экспорта соответствуют заданию.[3]

PYTHON / COMPLETE EXAMPLE

Прочитайте код. Затем запускайте осознанно.

"""Read the current project and optional timeline. No project is opened or created."""
import argparse
import json

from resolve_api_connection import connect, project_manager


def read_current(manager, expected_name=None):
    project = manager.GetCurrentProject()
    if not project:
        raise RuntimeError("No current project. Open the intended project manually.")
    name, project_id = project.GetName(), project.GetUniqueId()
    if not isinstance(name, str) or not isinstance(project_id, str) or not project_id:
        raise RuntimeError("Project identity is incomplete")
    if expected_name is not None and name != expected_name:
        raise RuntimeError("Current project name does not match --expect-project")
    timeline = project.GetCurrentTimeline()
    count = project.GetTimelineCount()
    if not isinstance(count, int) or isinstance(count, bool) or count < 0:
        raise RuntimeError("Timeline count could not be read")
    result = {
        "project": {"name": name, "id": project_id},
        "timeline_count": count,
        "current_timeline": None,
    }
    if timeline:
        timeline_name = timeline.GetName()
        timeline_id = timeline.GetUniqueId()
        if not timeline_name or not timeline_id:
            raise RuntimeError("Timeline identity is incomplete")
        result["current_timeline"] = {"name": timeline_name, "id": timeline_id}
    current = manager.GetCurrentProject()
    if not current or current.GetUniqueId() != project_id:
        raise RuntimeError("Active project changed during reading. Discard this report and inspect Resolve.")
    # Two identity reads detect some changes; they do not make the snapshot atomic.
    return result


def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--expect-project", help="Optional exact name check, not a globally unique identity")
    args = parser.parse_args(argv)
    result = read_current(project_manager(connect()), args.expect_project)
    print(json.dumps(result, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

"""Load the installed Blackmagic module; do not install a similarly named package.

This helper uses standard desktop installation paths or RESOLVE_SCRIPT_API.
It does not enable scripting, start Resolve, open projects or retry API calls.
Validate Python/native-library compatibility against your installed README.txt.
"""
from __future__ import annotations

import importlib.util
import os
from pathlib import Path
import struct
import sys


class ResolveConnectionError(RuntimeError):
    """An explicit environment, module, or application-connection failure."""


def scripting_root() -> Path:
    configured = os.environ.get("RESOLVE_SCRIPT_API")
    if configured is not None:
        if not configured.strip() or configured != configured.strip():
            raise ResolveConnectionError("RESOLVE_SCRIPT_API is empty or has outer whitespace")
        if configured.startswith(('"', "'")) or configured.endswith(('"', "'")):
            raise ResolveConnectionError("Do not store literal outer quotes in RESOLVE_SCRIPT_API")
        root = Path(os.path.expandvars(configured)).expanduser()
    elif sys.platform == "win32":
        root = Path(os.environ.get("PROGRAMDATA", r"C:\ProgramData")) / "Blackmagic Design/DaVinci Resolve/Support/Developer/Scripting"
    elif sys.platform == "darwin":
        root = Path("/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting")
    elif sys.platform.startswith("linux"):
        root = Path("/opt/resolve/Developer/Scripting")
    else:
        raise ResolveConnectionError("Set RESOLVE_SCRIPT_API for this platform/installation")
    if not root.is_absolute():
        raise ResolveConnectionError("RESOLVE_SCRIPT_API must be an absolute Scripting directory")
    return root


def module_file() -> Path:
    # RESOLVE_SCRIPT_API points to Scripting, not its Modules subdirectory.
    return scripting_root() / "Modules" / "DaVinciResolveScript.py"


def load_resolve_module():
    if struct.calcsize("P") * 8 != 64:
        raise ResolveConnectionError("Use a compatible 64-bit Python interpreter")
    source = module_file()
    if not source.is_file():
        raise ResolveConnectionError("Official DaVinciResolveScript.py not found at: " + str(source))
    configured_lib = os.environ.get("RESOLVE_SCRIPT_LIB")
    if configured_lib is not None:
        lib = Path(os.path.expandvars(configured_lib)).expanduser()
        if not lib.is_absolute() or not lib.is_file():
            raise ResolveConnectionError("RESOLVE_SCRIPT_LIB must name the installed native library file")
    name = "DaVinciResolveScript"
    spec = importlib.util.spec_from_file_location(name, source)
    if spec is None or spec.loader is None:
        raise ResolveConnectionError("Cannot create a loader for the official module")
    previous = sys.modules.get(name)
    module = importlib.util.module_from_spec(spec)
    sys.modules[name] = module
    try:
        spec.loader.exec_module(module)
        # Blackmagic's wrapper can replace its sys.modules entry with a native module.
        loaded = sys.modules[name]
        if not callable(getattr(loaded, "scriptapp", None)):
            raise ResolveConnectionError("Loaded module does not expose scriptapp")
        return loaded
    except Exception as exc:
        if previous is None:
            sys.modules.pop(name, None)
        else:
            sys.modules[name] = previous
        raise ResolveConnectionError("Official module was found, but loading it failed") from exc


def connect():
    module = load_resolve_module()
    try:
        resolve = module.scriptapp("Resolve")
    except Exception as exc:
        raise ResolveConnectionError("scriptapp failed; inspect the original exception") from exc
    if not resolve:
        raise ResolveConnectionError("No Resolve object: check running Studio, Local access and Python environment")
    return resolve


def project_manager(resolve):
    manager = resolve.GetProjectManager()
    if not manager:
        raise ResolveConnectionError("Resolve connected, but Project Manager is unavailable")
    return manager

Команды запуска

python current_project.py

python current_project.py --expect-project "API_Demo_Project"

Что делает код

1. Получить текущий объект

   Project Manager запрашивает уже открытый проект, без поиска или загрузки.

2. Прочитать идентичность

   Проверяются имя и ID; необязательный --expect-project ограничивает ожидаемое имя.

3. Разрешить пустой Timeline

   В JSON передаётся null, когда активного таймлайна нет; число таймлайнов читается отдельно.

4. Перечитать проект

   Перед возвратом результата сравнивается ID текущего проекта с первоначальным.

DEBUG / OBSERVATION FIRST

Ошибка — отправная точка, не готовый диагноз.

FAQ

Вопросы, которые возникают на практике.

SOURCES / VERSION BOUNDARIES

Источники, а не подразумеваемая сертификация.

Сверка источников, офлайн-тесты Python и проверка интерфейса — разные виды подтверждения. Ни один из них не означает, что каждый пример проверен со всеми сборками Studio, ОС и версиями Python. Указанная дата — дата редакционной проверки, не сертификат живого прогона.

1. Blackmagic Design — DaVinci Resolve Studio 21.1 release notes ↗

   8 сентября 2026. В объявлении выпуска Python scripting отнесён к Studio. Это источник требований редакции, а не протокол испытания наших примеров.

2. Blackmagic Design — Support Center ↗

   Каталог обновлений проверен 5 октября 2026: опубликована ветка 21.1.1. Последний выпуск не равен минимальной версии каждого метода.

3. Blackmagic Scripting README — snapshot 24 July 2026 (Resolve 21.0.4) ↗

   Публичная копия первичного README Blackmagic, поддерживаемая X-Raym. По ней сверены базовые сигнатуры; это не официальный хостинг и не README 21.1.1. Оригинал своей установки: Help → Documentation → Developer → Scripting → README.txt; расположение пункта зависит от версии.

4. Blackmagic Design — Scripting and Automation ↗

   Официальное описание Python/Lua scripting и интеграций Studio. Нельзя переносить обещания Studio на Free без проверки конкретного выпуска.