@hybridlabor-api/aos 4.4.0 → 4.4.2-beta.0

package/mcps/davinci-resolve-mcp/src/utils/multicam.py

@@ -1,393 +0,0 @@
-"""Helpers for source-safe multicam setup timelines.
-
-Resolve's public scripting API does not expose native multicam clip creation.
-These helpers build append plans for a stacked prep timeline that can be
-converted to a native multicam clip in Resolve's UI.
-"""
-
-from __future__ import annotations
-
-import re
-from typing import Any, Callable, Dict, List, Optional, Tuple
-
-
-FindClip = Callable[[Any, str], Any]
-
-
-_SOURCE_TIMECODE_KEYS = (
-    "Start TC",
-    "Start Timecode",
-    "Start Time Code",
-    "Source Start TC",
-    "Source Start Timecode",
-)
-
-_FPS_KEYS = ("FPS", "Frame Rate", "Video Frame Rate")
-_FRAME_COUNT_KEYS = ("Frames", "Frame Count", "Video Frames")
-_DURATION_KEYS = ("Duration", "Video Duration")
-
-
-def _err(message: str) -> Dict[str, str]:
-    return {"error": message}
-
-
-def _frame_int(value: Any) -> Optional[int]:
-    if value is None or value == "":
-        return None
-    if isinstance(value, str):
-        match = re.search(r"-?\d+(?:\.\d+)?", value.strip())
-        if not match:
-            return None
-        value = match.group(0)
-    try:
-        return int(round(float(value)))
-    except (TypeError, ValueError):
-        return None
-
-
-def parse_frame_rate(value: Any) -> Optional[float]:
-    if value is None or value == "":
-        return None
-    if isinstance(value, (int, float)):
-        return float(value) if float(value) > 0 else None
-    match = re.search(r"\d+(?:\.\d+)?", str(value))
-    if not match:
-        return None
-    fps = float(match.group(0))
-    return fps if fps > 0 else None
-
-
-def _nominal_timecode_rate(fps: float) -> int:
-    if abs(fps - 23.976) < 0.02:
-        return 24
-    if abs(fps - 29.97) < 0.02:
-        return 30
-    if abs(fps - 47.952) < 0.05:
-        return 48
-    if abs(fps - 59.94) < 0.05:
-        return 60
-    return int(round(fps))
-
-
-def timecode_to_frames(timecode: Any, fps: Any, *, drop_frame: Optional[bool] = None) -> Optional[int]:
-    """Convert HH:MM:SS:FF timecode to a frame count.
-
-    Semicolon timecode implies drop-frame. When drop_frame is not specified,
-    29.97/59.94 colon timecode is treated as non-drop-frame.
-    """
-    rate = parse_frame_rate(fps)
-    if rate is None:
-        return None
-    text = str(timecode or "").strip()
-    match = re.match(r"^(\d{1,2}):(\d{2}):(\d{2})([:;])(\d{2})$", text)
-    if not match:
-        return None
-    hours, minutes, seconds, sep, frames = match.groups()
-    hh = int(hours)
-    mm = int(minutes)
-    ss = int(seconds)
-    ff = int(frames)
-    nominal = _nominal_timecode_rate(rate)
-    if mm > 59 or ss > 59 or ff >= nominal:
-        return None
-    total = ((hh * 3600 + mm * 60 + ss) * nominal) + ff
-    use_drop = (sep == ";") if drop_frame is None else bool(drop_frame)
-    if use_drop and nominal in (30, 60):
-        drop_frames = 2 if nominal == 30 else 4
-        total_minutes = hh * 60 + mm
-        total -= drop_frames * (total_minutes - total_minutes // 10)
-    return total
-
-
-def _get_clip_property_map(clip: Any) -> Dict[str, Any]:
-    try:
-        props = clip.GetClipProperty()
-    except Exception:
-        props = None
-    return dict(props) if isinstance(props, dict) else {}
-
-
-def _prop_from_map(props: Dict[str, Any], key: str) -> Any:
-    if key in props:
-        return props[key]
-    key_norm = key.strip().lower()
-    for existing, value in props.items():
-        if str(existing).strip().lower() == key_norm:
-            return value
-    return None
-
-
-def _clip_property(clip: Any, props: Dict[str, Any], keys: Tuple[str, ...]) -> Any:
-    for key in keys:
-        value = _prop_from_map(props, key)
-        if value not in (None, ""):
-            return value
-    for key in keys:
-        try:
-            value = clip.GetClipProperty(key)
-        except Exception:
-            value = None
-        if value not in (None, ""):
-            return value
-    return None
-
-
-def _clip_name(clip: Any, fallback: str) -> str:
-    try:
-        name = clip.GetName()
-    except Exception:
-        name = None
-    return str(name or fallback)
-
-
-def _clip_duration_frames(clip: Any, props: Dict[str, Any], fps: Optional[float]) -> Optional[int]:
-    frames = _frame_int(_clip_property(clip, props, _FRAME_COUNT_KEYS))
-    if frames is not None and frames > 0:
-        return frames
-    try:
-        duration = clip.GetDuration()
-    except Exception:
-        duration = None
-    frames = _frame_int(duration)
-    if frames is not None and frames > 0:
-        return frames
-    if duration and ":" in str(duration) and fps is not None:
-        frames = timecode_to_frames(duration, fps)
-        if frames is not None and frames > 0:
-            return frames
-    duration_value = _clip_property(clip, props, _DURATION_KEYS)
-    frames = _frame_int(duration_value)
-    if frames is not None and frames > 0 and ":" not in str(duration_value):
-        return frames
-    if fps is None:
-        return None
-    return timecode_to_frames(duration_value, fps)
-
-
-def _angle_source_range(angle: Dict[str, Any], clip: Any, props: Dict[str, Any], fps: Optional[float], index: int):
-    start = _frame_int(angle.get("start_frame", angle.get("startFrame", 0)))
-    if start is None or start < 0:
-        return None, None, _err(f"angles[{index}] start_frame must be a non-negative frame number")
-    end = _frame_int(angle.get("end_frame", angle.get("endFrame")))
-    if end is None:
-        duration = _frame_int(angle.get("duration_frames", angle.get("durationFrames")))
-        if duration is None:
-            duration = _clip_duration_frames(clip, props, fps)
-        if duration is not None:
-            end = start + duration
-    if end is None:
-        return None, None, _err(
-            f"angles[{index}] requires end_frame/duration_frames, or clip properties with Frames/Duration"
-        )
-    if end <= start:
-        return None, None, _err(f"angles[{index}] end_frame must be greater than start_frame")
-    return start, end, None
-
-
-def _normalize_sync_mode(value: Any) -> Optional[str]:
-    raw = str(value or "stack_start").strip().lower().replace("-", "_").replace(" ", "_")
-    aliases = {
-        "none": "stack_start",
-        "start": "stack_start",
-        "stack": "stack_start",
-        "stack_start": "stack_start",
-        "common_start": "stack_start",
-        "manual": "record_frame",
-        "record": "record_frame",
-        "record_frame": "record_frame",
-        "record_frames": "record_frame",
-        "timecode": "source_timecode",
-        "source_timecode": "source_timecode",
-        "source_tc": "source_timecode",
-    }
-    return aliases.get(raw)
-
-
-def _normalize_audio_mode(value: Any, include_audio: bool) -> Optional[str]:
-    if not include_audio:
-        return "none"
-    raw = str(value or "matching").strip().lower().replace("-", "_").replace(" ", "_")
-    aliases = {
-        "none": "none",
-        "off": "none",
-        "matching": "matching",
-        "match": "matching",
-        "per_angle": "matching",
-        "first": "first",
-        "first_angle": "first",
-        "scratch": "first",
-    }
-    return aliases.get(raw)
-
-
-def _selected_record_frame(
-    *,
-    angle: Dict[str, Any],
-    clip: Any,
-    props: Dict[str, Any],
-    fps: Optional[float],
-    sync_mode: str,
-    timeline_start_timecode: str,
-    record_frame_start: int,
-    index: int,
-):
-    offset = _frame_int(angle.get("record_offset", angle.get("recordOffset", 0)))
-    if offset is None:
-        return None, _err(f"angles[{index}] record_offset must be numeric")
-    if sync_mode == "source_timecode":
-        tc = (
-            angle.get("source_timecode")
-            or angle.get("sourceTimecode")
-            or angle.get("start_timecode")
-            or angle.get("startTimecode")
-            or _clip_property(clip, props, _SOURCE_TIMECODE_KEYS)
-        )
-        if not tc:
-            return None, _err(f"angles[{index}] has no source_timecode or readable clip Start TC")
-        tc_frames = timecode_to_frames(tc, fps)
-        start_frames = timecode_to_frames(timeline_start_timecode, fps)
-        if tc_frames is None or start_frames is None:
-            return None, _err(f"angles[{index}] could not parse source/timeline timecode at fps={fps!r}")
-        return record_frame_start + (tc_frames - start_frames) + offset, None
-    if sync_mode == "record_frame":
-        manual = _frame_int(angle.get("record_frame", angle.get("recordFrame")))
-        if manual is None:
-            manual = record_frame_start
-        return manual + offset, None
-    return record_frame_start + offset, None
-
-
-def build_multicam_setup_plan(root: Any, params: Dict[str, Any], find_clip: FindClip):
-    """Build a stacked multicam setup plan from media pool clip IDs."""
-    params = params or {}
-    name = str(params.get("name") or "Multicam Setup")
-    raw_angles = params.get("angles")
-    if raw_angles is None:
-        clip_ids = params.get("clip_ids") or params.get("clipIds")
-        if not isinstance(clip_ids, list) or not clip_ids:
-            return None, _err("setup_multicam_timeline requires angles or clip_ids")
-        raw_angles = [{"clip_id": clip_id} for clip_id in clip_ids]
-    if not isinstance(raw_angles, list) or not raw_angles:
-        return None, _err("angles must be a non-empty list")
-
-    sync_mode = _normalize_sync_mode(params.get("sync_mode", params.get("syncMode")))
-    if not sync_mode:
-        return None, _err("sync_mode must be stack_start, record_frame, or source_timecode")
-
-    include_video = bool(params.get("include_video", params.get("includeVideo", True)))
-    include_audio = bool(params.get("include_audio", params.get("includeAudio", False)))
-    if not include_video and not include_audio:
-        return None, _err("At least one of include_video or include_audio must be true")
-    audio_mode = _normalize_audio_mode(params.get("audio_track_mode", params.get("audioTrackMode")), include_audio)
-    if not audio_mode:
-        return None, _err("audio_track_mode must be matching, first, or none")
-
-    default_fps = parse_frame_rate(params.get("frame_rate", params.get("frameRate")))
-    timeline_start_timecode = str(
-        params.get("timeline_start_timecode")
-        or params.get("timelineStartTimecode")
-        or params.get("start_timecode")
-        or params.get("startTimecode")
-        or "01:00:00:00"
-    )
-    record_frame_start = _frame_int(params.get("record_frame_start", params.get("recordFrameStart", 0)))
-    if record_frame_start is None:
-        return None, _err("record_frame_start must be numeric")
-
-    rows: List[Dict[str, Any]] = []
-    angles: List[Dict[str, Any]] = []
-    max_video_track = 0
-    max_audio_track = 0
-    allow_negative = bool(params.get("allow_negative_record_frame", params.get("allowNegativeRecordFrame", False)))
-    record_frame_mode = params.get("record_frame_mode", params.get("recordFrameMode", "relative"))
-
-    for index, raw in enumerate(raw_angles):
-        if not isinstance(raw, dict):
-            return None, _err(f"angles[{index}] must be an object")
-        clip_id = raw.get("clip_id") or raw.get("media_pool_item_id") or raw.get("clipId")
-        if not clip_id:
-            return None, _err(f"angles[{index}] requires clip_id or media_pool_item_id")
-        clip = find_clip(root, str(clip_id))
-        if not clip:
-            return None, _err(f"angles[{index}]: media pool clip not found: {clip_id}")
-        props = _get_clip_property_map(clip)
-        fps = parse_frame_rate(raw.get("frame_rate", raw.get("frameRate"))) or parse_frame_rate(
-            _clip_property(clip, props, _FPS_KEYS)
-        ) or default_fps
-        source_start, source_end, range_err = _angle_source_range(raw, clip, props, fps, index)
-        if range_err:
-            return None, range_err
-        record_frame, record_err = _selected_record_frame(
-            angle=raw,
-            clip=clip,
-            props=props,
-            fps=fps,
-            sync_mode=sync_mode,
-            timeline_start_timecode=timeline_start_timecode,
-            record_frame_start=record_frame_start,
-            index=index,
-        )
-        if record_err:
-            return None, record_err
-        if record_frame is None or (record_frame < 0 and not allow_negative):
-            return None, _err(f"angles[{index}] resolved to a negative record frame")
-
-        video_track = _frame_int(raw.get("track_index", raw.get("trackIndex", index + 1)))
-        if video_track is None or video_track < 1:
-            return None, _err(f"angles[{index}] track_index must be a positive integer")
-        audio_track = _frame_int(raw.get("audio_track_index", raw.get("audioTrackIndex", video_track)))
-        if audio_track is None or audio_track < 1:
-            return None, _err(f"angles[{index}] audio_track_index must be a positive integer")
-        angle_name = str(raw.get("angle_name") or raw.get("angleName") or _clip_name(clip, str(clip_id)))
-
-        angle_summary = {
-            "angle_index": index + 1,
-            "angle_name": angle_name,
-            "clip_id": str(clip_id),
-            "clip_name": _clip_name(clip, str(clip_id)),
-            "source_start": source_start,
-            "source_end": source_end,
-            "record_frame": record_frame,
-            "video_track_index": video_track,
-            "audio_track_index": audio_track if audio_mode != "none" else None,
-            "fps": fps,
-        }
-        angles.append(angle_summary)
-        common = {
-            "clip_id": str(clip_id),
-            "start_frame": source_start,
-            "end_frame": source_end,
-            "record_frame": record_frame,
-            "record_frame_mode": raw.get("record_frame_mode", raw.get("recordFrameMode", record_frame_mode)),
-            "angle_index": index + 1,
-            "angle_name": angle_name,
-        }
-        if include_video:
-            rows.append({**common, "track_index": video_track, "media_type": 1, "role": "video"})
-            max_video_track = max(max_video_track, video_track)
-        if audio_mode == "matching" or (audio_mode == "first" and index == 0):
-            rows.append({**common, "track_index": audio_track, "media_type": 2, "role": "audio"})
-            max_audio_track = max(max_audio_track, audio_track)
-
-    return {
-        "success": True,
-        "name": name,
-        "sync_mode": sync_mode,
-        "start_timecode": params.get("start_timecode") or params.get("startTimecode"),
-        "timeline_start_timecode": timeline_start_timecode,
-        "include_video": include_video,
-        "include_audio": include_audio,
-        "audio_track_mode": audio_mode,
-        "angles": angles,
-        "append_rows": rows,
-        "max_video_track": max_video_track,
-        "max_audio_track": max_audio_track,
-        "native_multicam_created": False,
-        "native_multicam_api": False,
-        "manual_reference": "DaVinci Resolve 20 Manual, Edit > Chapter 42, Multicam Editing",
-        "next_step": (
-            "Resolve's public scripting API does not expose native multicam clip creation. "
-            "Use the created prep timeline directly, or in Resolve convert the timeline/"
-            "compound clip to a multicam clip from the Media Pool context menu."
-        ),
-    }, None

package/mcps/davinci-resolve-mcp/src/utils/object_inspection.py

@@ -1,301 +0,0 @@
-#!/usr/bin/env python3
-"""
-DaVinci Resolve MCP Server - Object Inspection Utilities
-
-This module provides functions for inspecting DaVinci Resolve API objects:
-- Exploring available methods and properties
-- Generating structured documentation
-- Inspecting nested objects
-- Converting between Python and Lua objects if needed
-"""
-
-import sys
-import inspect
-import logging
-from typing import Any, Dict, List, Optional, Union, Callable
-
-logger = logging.getLogger(__name__)
-
-
-def get_object_members(
-    obj: Any,
-    include_methods: bool = True,
-    include_properties: bool = True,
-) -> Dict[str, Any]:
-    """
-    Inspect a DaVinci Resolve object's methods and/or properties in a single pass.
-
-    DaVinci Resolve API objects are C extensions: every attribute access is a
-    bridge round-trip, so we walk ``dir(obj)`` exactly once and classify each
-    attribute, rather than walking it separately for methods and properties.
-
-    Args:
-        obj: A DaVinci Resolve API object
-        include_methods: Collect callable attributes
-        include_properties: Collect non-callable attributes
-
-    Returns:
-        A dict with ``"methods"`` and/or ``"properties"`` keys, or ``{"error": ...}``
-    """
-    if obj is None:
-        return {"error": "Cannot inspect None object"}
-
-    methods: Dict[str, Dict[str, Any]] = {}
-    properties: Dict[str, Dict[str, Any]] = {}
-
-    for attr_name in dir(obj):
-        # Skip private/internal attributes
-        if attr_name.startswith('_'):
-            continue
-
-        try:
-            attr = getattr(obj, attr_name)
-        except Exception as e:
-            if include_methods:
-                methods[attr_name] = {"error": str(e), "type": "error"}
-            if include_properties:
-                properties[attr_name] = {"error": str(e), "type_category": "error"}
-            continue
-
-        if callable(attr):
-            if not include_methods:
-                continue
-            # Only real Python functions/methods carry an introspectable
-            # signature. Resolve API methods are C extensions where
-            # inspect.signature() is slow and almost always raises, so we skip
-            # the attempt and default to "()" for them.
-            if inspect.isfunction(attr) or inspect.ismethod(attr):
-                try:
-                    signature = str(inspect.signature(attr))
-                except (ValueError, TypeError):
-                    signature = "()"
-            else:
-                signature = "()"
-
-            # Read __doc__ directly instead of inspect.getdoc() to avoid the
-            # MRO walk for inherited docstrings (irrelevant for C-ext methods).
-            doc = (getattr(attr, "__doc__", "") or "").strip()
-
-            methods[attr_name] = {
-                "signature": signature,
-                "doc": doc,
-                "type": "method",
-            }
-        else:
-            if not include_properties:
-                continue
-            properties[attr_name] = {
-                "value": str(attr),
-                "type": type(attr).__name__,
-                "type_category": "property",
-            }
-
-    result: Dict[str, Any] = {}
-    if include_methods:
-        result["methods"] = methods
-    if include_properties:
-        result["properties"] = properties
-    return result
-
-
-def get_object_methods(obj: Any) -> Dict[str, Dict[str, Any]]:
-    """
-    Get all methods of a DaVinci Resolve object with their documentation.
-
-    Thin wrapper over :func:`get_object_members` kept for backwards compatibility.
-    """
-    res = get_object_members(obj, include_methods=True, include_properties=False)
-    return res.get("methods", res)
-
-
-def get_object_properties(obj: Any) -> Dict[str, Dict[str, Any]]:
-    """
-    Get all properties (non-callable attributes) of a DaVinci Resolve object.
-
-    Thin wrapper over :func:`get_object_members` kept for backwards compatibility.
-    """
-    res = get_object_members(obj, include_methods=False, include_properties=True)
-    return res.get("properties", res)
-
-
-def inspect_object(obj: Any, max_depth: int = 1) -> Dict[str, Any]:
-    """
-    Inspect a DaVinci Resolve API object and return its methods and properties.
-    
-    Args:
-        obj: A DaVinci Resolve API object
-        max_depth: Maximum depth for nested object inspection
-        
-    Returns:
-        A dictionary containing the object's methods and properties
-    """
-    if obj is None:
-        return {"error": "Cannot inspect None object"}
-    
-    members = get_object_members(obj)
-    result = {
-        "type": type(obj).__name__,
-        "methods": members.get("methods", {}),
-        "properties": members.get("properties", {}),
-    }
-
-    # Add string representation
-    try:
-        result["str"] = str(obj)
-    except Exception as e:
-        result["str_error"] = str(e)
-        
-    # Add repr representation
-    try:
-        result["repr"] = repr(obj)
-    except Exception as e:
-        result["repr_error"] = str(e)
-    
-    return result
-
-
-def get_lua_table_keys(lua_table: Any) -> List[str]:
-    """
-    Get all keys from a Lua table object (if the object supports Lua table iteration).
-    
-    Args:
-        lua_table: A Lua table object from DaVinci Resolve API
-        
-    Returns:
-        A list of keys from the Lua table
-    """
-    if lua_table is None:
-        return []
-        
-    keys = []
-    
-    # Check for DaVinci-specific Lua table iteration methods
-    if hasattr(lua_table, 'GetKeyList'):
-        try:
-            # Some DaVinci Resolve objects have a GetKeyList() method
-            return lua_table.GetKeyList()
-        except Exception:
-            logger.debug("Lua table GetKeyList() lookup failed", exc_info=True)
-            
-    # Try different iteration methods that might work with Lua tables
-    try:
-        # Some Lua tables can be iterated directly
-        for key in lua_table:
-            keys.append(key)
-        return keys
-    except Exception:
-        logger.debug("Lua table direct iteration failed", exc_info=True)
-        
-    # Try manual iteration with pairs-like behavior (if available)
-    # This is a fallback for APIs that don't support Python-style iteration
-    return []
-
-
-def convert_lua_to_python(lua_obj: Any) -> Any:
-    """
-    Convert a Lua object from DaVinci Resolve API to a Python object.
-    
-    Args:
-        lua_obj: A Lua object from DaVinci Resolve API
-        
-    Returns:
-        The converted Python object
-    """
-    # Handle None
-    if lua_obj is None:
-        return None
-        
-    # Handle primitive types
-    if isinstance(lua_obj, (str, int, float, bool)):
-        return lua_obj
-        
-    # Try to convert Lua tables to Python dicts or lists
-    if hasattr(lua_obj, 'GetKeyList') or hasattr(lua_obj, '__iter__'):
-        keys = get_lua_table_keys(lua_obj)
-        
-        # If we found keys, convert to dict
-        if keys:
-            result = {}
-            for key in keys:
-                try:
-                    # Get the value for this key
-                    value = lua_obj[key]
-                    # Recursively convert nested Lua objects
-                    result[key] = convert_lua_to_python(value)
-                except Exception:
-                    logger.debug("Failed to convert Lua table key %r", key, exc_info=True)
-                    result[key] = None
-            return result
-        
-        # Try to convert to list if it appears numeric-indexed
-        try:
-            # Common Lua pattern for numeric arrays (1-indexed)
-            result = []
-            index = 1  # Lua arrays typically start at 1
-            while True:
-                try:
-                    value = lua_obj[index]
-                    result.append(convert_lua_to_python(value))
-                    index += 1
-                except Exception:
-                    logger.debug("Lua numeric iteration stopped at index %s", index, exc_info=True)
-                    break
-            
-            # If we found items, return as list
-            if result:
-                return result
-        except Exception:
-            logger.debug("Lua numeric-indexed conversion failed", exc_info=True)
-    
-    # If conversion failed, return string representation
-    return str(lua_obj)
-
-
-def print_object_help(obj: Any) -> str:
-    """
-    Generate a human-readable help string for a DaVinci Resolve API object.
-    
-    Args:
-        obj: A DaVinci Resolve API object
-        
-    Returns:
-        A formatted help string describing the object's methods and properties
-    """
-    if obj is None:
-        return "Cannot provide help for None object"
-    
-    obj_type = type(obj).__name__
-    members = get_object_members(obj)
-    methods = members.get("methods", {})
-    properties = members.get("properties", {})
-
-    help_text = [f"Help for {obj_type} object:"]
-    help_text.append("\n" + "=" * 40 + "\n")
-    
-    # Add methods
-    if methods:
-        help_text.append("METHODS:")
-        help_text.append("-" * 40)
-        for name, info in sorted(methods.items()):
-            if "error" in info:
-                continue
-            signature = info.get("signature", "()")
-            doc = info.get("doc", "").strip()
-            help_text.append(f"{name}{signature}")
-            if doc:
-                help_text.append(f"    {doc}\n")
-            else:
-                help_text.append("")
-    
-    # Add properties
-    if properties:
-        help_text.append("\nPROPERTIES:")
-        help_text.append("-" * 40)
-        for name, info in sorted(properties.items()):
-            if "error" in info:
-                continue
-            value = info.get("value", "")
-            type_name = info.get("type", "")
-            help_text.append(f"{name}: {type_name} = {value}")
-    
-    return "\n".join(help_text)