Как проверить доступность Resolve Scripting API

01 / BEFORE THE CODE

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

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

02 / API CONTRACT

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

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

03 / UNDERSTAND

Пять проверок вместо одного «не работает»

Диагностика идёт в определённом порядке: окружение Python, загрузка модуля, получение Resolve, доступ к Project Manager и чтение текущего проекта. Поле stage показывает этап, на котором выполнение остановилось. Поле status отвечает за итог, а не за догадку о причине.

Если module прошёл, а connection нет, переустановка Python наугад не следует из результата. Если connection прошёл, а current_project завершился без открытого проекта, это нормальная пустая рабочая область. Рабочая автоматизация может требовать проект, но диагностике достаточно зафиксировать его отсутствие.[3][6]

04 / UNDERSTAND

Как читать JSON и код завершения

При успешной цепочке status равен read_access_available, stage — complete, а project_open и timeline_open явно показывают наличие объектов. Это проверка нескольких операций чтения, не тест всех методов API и не подтверждение доступности рендера, Color или Fusion.

При сбое status равен failed. Смотрите stage, exception_type и cause_type. Код завершения 0 означает, что диагностическая цепочка чтения пройдена; 1 — что она остановилась. Синтаксическая ошибка команды может обрабатываться argparse отдельно. Не делайте «успешный» мониторинг по одному факту, что Python напечатал JSON.

По умолчанию отчёт не выводит названия проектов, полный путь Python и traceback. Ключи configured_variables показывают только имена заданных переменных, не их значения. Версии и сведения о системе тоже могут быть внутренней информацией — перед отправкой просмотрите весь файл.

05 / UNDERSTAND

Что менять и в каком порядке

Сначала запишите исходные версии Resolve/Studio и Python. Затем убедитесь, что реальный DaVinciResolveScript.py находится по вычисленному пути. Если ошибка внутри loader, сравните native-библиотеку и архитектуру. Только после успешного импорта проверяйте состояние приложения и Local.

После изменения одной настройки повторите тот же минимальный тест. Не меняйте одновременно Python, права, переменные и редакцию Resolve: иначе невозможно понять, что исправило проблему. Выбранный путь должен относиться к той установке, которую вы действительно запустили.

Не включайте Network, не выключайте защиту ОС и не запускайте неизвестные процессы с повышенными правами ради зелёной строки. Соединение через Fusion нельзя представлять как универсальный способ обхода Studio или доказательство исправности прямого Resolve API.[3][1]

06 / UNDERSTAND

Подготовка сообщения об ошибке

Сначала сохраните обычный отчёт. Для локальной диагностики можно повторить запуск с --show-paths: появятся путь интерпретатора, путь wrapper и traceback при сбое. Эта опция может раскрыть имя пользователя, пути к дискам и зависимостям. Автоматического обезличивания нет.

В обращение включите точную команду запуска, версии ОС/Resolve/Python, редакцию и первый неуспешный этап. Уберите персональные пути и внутренние имена, но сохраните тип исключения и последний значимый кадр стека. При зависании после изменяющего вызова не повторяйте его: этот read-only диагностический файл не определяет, завершилась ли предыдущая правка.[6]

PYTHON / COMPLETE EXAMPLE

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

"""Read-only diagnostic; paths and traceback are shown only with --show-paths."""
import argparse
import json
import os
import platform
import struct
import sys
import traceback

import resolve_api_connection as bridge


def diagnose(show_paths=False):
    report = {
        "status": "not_checked",
        "stage": "environment",
        "python": platform.python_version(),
        "platform": sys.platform,
        "pointer_bits": struct.calcsize("P") * 8,
        "configured_variables": [key for key in ("RESOLVE_SCRIPT_API", "RESOLVE_SCRIPT_LIB") if key in os.environ],
    }
    if show_paths:
        report["python_executable"] = sys.executable
    try:
        report["stage"] = "module"
        if show_paths:
            report["module_file"] = str(bridge.module_file())
        module = bridge.load_resolve_module()
        report["stage"] = "connection"
        resolve = module.scriptapp("Resolve")
        if not resolve:
            raise bridge.ResolveConnectionError("No Resolve object")
        report["product"] = resolve.GetProductName()
        report["version"] = resolve.GetVersionString()
        if not report["product"] or not report["version"]:
            raise bridge.ResolveConnectionError("Application identity unavailable")
        report["stage"] = "project_manager"
        manager = bridge.project_manager(resolve)
        report["stage"] = "current_project"
        project = manager.GetCurrentProject()
        report["project_open"] = bool(project)
        report["timeline_open"] = bool(project.GetCurrentTimeline()) if project else False
        report["status"] = "read_access_available"
        # No project/timeline is a valid empty state, not a broken connection.
        report["stage"] = "complete"
    except Exception as exc:
        report["status"] = "failed"
        report["exception_type"] = type(exc).__name__
        report["cause_type"] = type(exc.__cause__).__name__ if exc.__cause__ else None
        report["next_step"] = "Inspect this stage locally; do not change permissions to Network as a generic fix."
        if show_paths:
            report["traceback"] = traceback.format_exc()
    return report


def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--show-paths", action="store_true", help="Include local paths/traceback; redact before sharing")
    args = parser.parse_args(argv)
    report = diagnose(args.show_paths)
    print(json.dumps(report, ensure_ascii=False, indent=2))
    return 0 if report["status"] == "read_access_available" else 1


if __name__ == "__main__":
    raise SystemExit(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 diagnose_resolve.py

python diagnose_resolve.py --show-paths

python .\diagnose_resolve.py
$LASTEXITCODE

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

1. Собрать окружение

   Записать версию Python, платформу, разрядность и только имена настроенных переменных.

2. Указать этап

   Перед каждой операцией обновить stage; ошибка остаётся привязанной к конкретному слою.

3. Зафиксировать пустые объекты

   Отсутствие текущего проекта/таймлайна отражается отдельными флагами, без их создания.

4. Вернуть статус процесса

   Возвращается 0 или 1, пригодный для ручной проверки в терминале и простого launcher.

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

6. Python — ImportError and ModuleNotFoundError ↗

   Различие ошибок поиска и загрузки зависимостей; цепочка исключений нужна для точной локальной диагностики.