Как создать проект DaVinci Resolve через Python API

01 / BEFORE THE CODE

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

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

02 / API CONTRACT

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

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

03 / UNDERSTAND

Что создаётся и где

CreateProject создаёт проект в контексте Project Manager. Имя API_Demo_Project — не путь, не каталог с исходниками и не имя экспортируемого .drp-файла. Локальная Project Library и её выбранная папка должны быть проверены до операции.

В README 21.0.4 у CreateProject также описан необязательный mediaLocationPath. Он относится к размещению медиа проекта, а не к переключению библиотеки. В этом вводном примере используется однопараметрический вызов; дополнительный аргумент не нужен для цели урока.

Мы ограничиваем выполнение локальной библиотекой Disk и выбранной папкой, чтобы не соединять первый опыт создания проекта с управлением серверной или облачной библиотекой. Это граница нашего кода, а не утверждение, что Resolve не умеет работать с другими библиотеками.[3]

04 / UNDERSTAND

Сначала посмотрите план

Без --apply код выполняет только чтение. Он показывает library, db_type, folder, name_available и project_open. При занятом имени или открытом проекте план всё равно может быть напечатан — это наблюдение, а не разрешение на создание.

План не резервирует имя и не блокирует Project Manager. Перед применением сохраните и закройте открытый проект вручную. Проверьте библиотеку и строку folder в выводе. Корень может быть представлен пустой строкой: переносите фактическое значение, не подставляйте придуманное Root.

Имена ограничены в нашем примере 1–96 символами без внешних пробелов, управляющих символов и разделителей пути. Это редакционное ограничение учебного скрипта. Оно не объявляется официальным пределом длины имени Resolve.[3]

05 / UNDERSTAND

Применение — отдельная команда

Для создания нужны --apply, --expect-library и --expect-folder. Скрипт повторно читает состояние и сравнивает его с ожидаемой целью. Если проект уже открыт, имя занято или выбранная папка изменилась, он останавливается до CreateProject.

Не запускайте параллельно второй экземпляр скрипта и не меняйте библиотеку/папку в интерфейсе. Повторное чтение сокращает вероятность ошибки, но не создаёт атомарную транзакцию и не защищает от всех действий другого процесса между проверкой и записью.

После успешного CreateProject нужно сверить имя и ID возвращённого объекта с текущим проектом. Только затем выполняется SaveProject. Он сохраняет текущий проект, поэтому проверка правильной цели здесь важнее самого факта, что CreateProject вернул непустое значение.[3]

06 / UNDERSTAND

Почему здесь нет «создать или открыть»

Старый подход CreateProject → при неудаче LoadProject объединяет два разных намерения. Сбой создания не доказывает, что существующий одноимённый проект является правильной целью. Особенно опасно продолжать после этого импорт, удаление или рендер.

Этот пример не переиспользует существующий проект и не добавляет числовой суффикс молча. Повторный запуск с тем же именем должен остановиться или показать name_available=false в плане. Для сценария «открыть известный проект» нужен отдельный, явно описанный режим с проверкой идентичности.[3]

07 / UNDERSTAND

Что делать после неполного результата

Если CreateProject вызван, но объект не получен или Python потерял ответ, не считайте операцию откатившейся. Проверьте Project Manager, список проектов и текущий проект. Скрипт не повторяет создание и не удаляет ничего в качестве автоматического восстановления.

Если проект получен, но SaveProject не подтвердил успех, проект уже мог появиться в библиотеке. Сохраните наблюдение и проверьте его вручную. Не запускайте весь файл с новым именем, пока не разобрались с первым результатом.

Статус created_and_save_acknowledged означает ровно два факта: объект создан и API подтвердил SaveProject после сверки идентичности. Долговременное сохранение, повторное открытие и резервная копия проверяются отдельно в интерфейсе и не приписываются этому статусу.[3]

PYTHON / COMPLETE EXAMPLE

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

"""Plan by default. Create ONE project in a local Disk library only after --apply.

Close/save any existing project manually first. Do not interact with Project
Manager while this script runs. There is no atomic transaction or automatic rollback.
"""
import argparse
import json

from resolve_api_connection import connect, project_manager


class CreationOutcomeError(RuntimeError):
    """A write may have happened. Inspect Resolve; never retry this blindly."""


def validate_name(name):
    # These are limits of this tutorial, not documented Resolve name limits.
    if not isinstance(name, str) or not name or name != name.strip() or len(name) > 96:
        raise ValueError("Use 1-96 characters without outer whitespace")
    if any(ord(ch) < 32 or ch in '/\\' for ch in name):
        raise ValueError("Control characters and path separators are not accepted here")
    return name


def inspect_target(manager, name):
    name = validate_name(name)
    database = manager.GetCurrentDatabase()
    if not isinstance(database, dict) or database.get("DbType") != "Disk" or not database.get("DbName"):
        raise RuntimeError("This tutorial targets a local Disk Project Library only")
    folder = manager.GetCurrentFolder()
    names = manager.GetProjectListInCurrentFolder()
    if not isinstance(folder, str) or not isinstance(names, list) or not all(isinstance(x, str) for x in names):
        raise RuntimeError("Could not read the current Project Manager folder")
    return {
        "library": database["DbName"],
        "db_type": database["DbType"],
        "folder": folder,
        "name": name,
        "name_available": name not in names,
        "project_open": bool(manager.GetCurrentProject()),
    }


def create_once(manager, name, apply=False, expected_library=None, expected_folder=None):
    before = inspect_target(manager, name)
    if not apply:
        return {"status": "plan_only", "writes": 0, "target": before}
    if expected_library is None or expected_folder is None:
        raise ValueError("--apply requires --expect-library and --expect-folder, copied from the inspected target")
    if before["library"] != expected_library or before["folder"] != expected_folder:
        raise RuntimeError("Project Library/folder differs from the explicitly expected target")
    if before["project_open"]:
        raise RuntimeError("An existing project is open. Save/close it yourself; this script will not do so.")
    if not before["name_available"]:
        raise RuntimeError("Name already exists. No LoadProject fallback is permitted.")
    # Re-read immediately before writing. This is a guard, not a lock.
    if inspect_target(manager, name) != before:
        raise RuntimeError("Project Manager state changed. No creation was attempted.")
    try:
        project = manager.CreateProject(name)
    except Exception as exc:
        raise CreationOutcomeError("CreateProject outcome unknown. Inspect Project Manager before any retry.") from exc
    if not project:
        raise CreationOutcomeError("CreateProject returned no object. No fallback, retry or deletion was attempted.")
    try:
        current = manager.GetCurrentProject()
        project_id = project.GetUniqueId()
        if not project_id or not current or current.GetUniqueId() != project_id or project.GetName() != name:
            raise CreationOutcomeError("Creation returned an object, but current-project identity is not confirmed")
        if not manager.SaveProject():
            raise CreationOutcomeError("Project was created; SaveProject did not acknowledge success. Inspect it manually.")
    except CreationOutcomeError:
        raise
    except Exception as exc:
        raise CreationOutcomeError("Creation happened; verification/save outcome is uncertain. Do not repeat creation.") from exc
    return {"status": "created_and_save_acknowledged", "target": before, "project_id": project_id}


def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("name", help="New project name; not a filesystem path")
    parser.add_argument("--apply", action="store_true", help="Allow one creation and save after all guards pass")
    parser.add_argument("--expect-library")
    parser.add_argument("--expect-folder", help="Exact folder string from plan; an empty string may represent root")
    args = parser.parse_args(argv)
    validate_name(args.name)
    result = create_once(project_manager(connect()), args.name, args.apply, args.expect_library, args.expect_folder)
    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 create_project.py "API_Demo_Project"

python create_project.py "API_Demo_Project" --apply --expect-library "Local Database" --expect-folder "API_Tests"

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

1. Проверить цель

   Прочитать локальную библиотеку, папку, занятость имени и наличие открытого проекта.

2. Отделить план

   Без --apply вернуть только план; не сохранять и не закрывать чужой проект.

3. Создать один раз

   После повторной проверки отправить один CreateProject; никаких LoadProject и скрытых повторов.

4. Сверить и сохранить

   Проверить ID текущего объекта и затем получить подтверждение SaveProject.

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 без проверки конкретного выпуска.