Developer API Overview¶

def get_local_storage(self, plugin: _PluginBase[Any, Any]) -> Path | None:
    """
    Return a path to a local storage directory for the given plugin,
    or None if the current workspace has no file path.
    """
    if not self.file_path:
        return None

    settings_path = SettingsManager.local_settings_path(self.file_path)
    local_storage = settings_path.with_suffix("").with_stem(settings_path.stem.upper()) / plugin.identifier
    local_storage.mkdir(parents=True, exist_ok=True)

    return local_storage

def register_on_destroy(self, cb: Callable[[], Any]) -> None:
    """
    Register a callback to be called before the workspace begins a reload or when the workspace is destroyed.
    This is generaly used to clean up VapourSynth resources.
    """
    self.__workspace.cbs_on_destroy.append(cb)

@contextmanager
def vs_context(self) -> Iterator[None]:
    """
    Context manager for using the VapourSynth environment of the workspace.
    """
    with self.__workspace.env.use():
        yield

@contextmanager
def block_workspace(self, caller: WidgetPluginBase[Any, Any]) -> Iterator[None]:
    """
    Mark the workspace as busy for the duration of the context.

    Specifically, a busy workspace will prevent:

    * Automatic or manual reloading.
    * Frame requests (via seeking, programmatic calls, or playback start).
    """
    self.__busy_callers.add(caller)

    try:
        yield
    finally:
        self.__busy_callers.discard(caller)

def register_action(
    self,
    action_id: str,
    action: QAction,
    *,
    context: Qt.ShortcutContext = Qt.ShortcutContext.WidgetWithChildrenShortcut,
) -> None:
    """
    Register a QAction for shortcut management.

    Args:
        action_id: The namespaced identifier (e.g., "my_plugin.do_thing").
        action: The QAction to manage.
        context: The context in which the shortcut should be active.
    """
    ShortcutManager.register_action(action_id, action, context=context)

def register_shortcut(
    self,
    action_id: str,
    callback: Callable[[], Any],
    parent: QWidget,
    *,
    context: Qt.ShortcutContext = Qt.ShortcutContext.WidgetWithChildrenShortcut,
) -> QShortcut:
    """
    Create and register a QShortcut for shortcut management.

    Args:
        action_id: The namespaced identifier (e.g., "my_plugin.do_thing").
        callback: The function to call when the shortcut is activated.
        parent: The parent widget that determines shortcut scope.
        context: The context in which the shortcut should be active.

    Returns:
        The created QShortcut instance.
    """
    return ShortcutManager.register_shortcut(action_id, callback, parent, context=context)

def get_shortcut_label(self, action_id: str) -> str:
    """
    Return the current shortcut's native display string or an empty string if no shortcut is assigned.
    """
    key = ShortcutManager.get_key(action_id)
    return QKeySequence(key).toString(QKeySequence.SequenceFormat.NativeText) if key else ""

def time_to_frame(self, time: timedelta, fps: VideoOutputProxy | Fraction | None = None) -> Frame:
    """
    Convert a time to a frame number for this output.

    Args:
        time: The time to convert.
        fps: Optional override for FPS/duration context.
    """
    return VideoOutput.time_to_frame(self, time, fps)  # type: ignore[arg-type]

def frame_to_time(self, frame: int, fps: VideoOutputProxy | Fraction | None = None) -> Time:
    """
    Convert a frame number to time for this output.

    Args:
        frame: The frame number to convert.
        fps: Optional override for FPS/duration context.
    """
    return VideoOutput.frame_to_time(self, frame, fps)  # type: ignore[arg-type]

def set_rect_selection(self, rect: QRect, *, finished: bool = False) -> None:
    """Set the current rectangular selection in source image pixel coordinates."""
    self.__view.set_rect_selection(rect, finished=finished)

def clear_rect_selection(self) -> None:
    """Clear the current rectangular selection."""
    self.__view.clear_rect_selection()

@copy_signature(QGraphicsView().mapToScene if TYPE_CHECKING else lambda *args, **kwargs: cast(Any, None))
def map_to_scene(self, *args: Any, **kwargs: Any) -> Any:
    """
    Map coordinates to this view's scene.
    """
    return self.__view.mapToScene(*args, **kwargs)

@copy_signature(QGraphicsView().mapFromScene if TYPE_CHECKING else lambda *args, **kwargs: cast(Any, None))
def map_from_scene(self, *args: Any, **kwargs: Any) -> Any:
    """
    Map coordinates from view's scene.
    """
    return self.__view.mapFromScene(*args, **kwargs)

def update_global_settings(self, **updates: Any) -> None:
    """Update specific global settings fields and trigger persistence."""
    self.api._update_settings(self, "global", **updates)

def update_local_settings(self, **updates: Any) -> None:
    """Update specific local settings fields and trigger persistence."""
    self.api._update_settings(self, "local", **updates)

def on_current_voutput_changed(self, voutput: VideoOutputProxy, tab_index: int) -> None:
    """
    Called when the current video output changes.

    Execution Thread: **Main or Background**.
    If you need to update the UI, use the `@run_in_loop` decorator.
    """
    self.on_current_frame_changed(self.api.current_frame)

def on_current_frame_changed(self, n: int) -> None:
    """
    Called when the current frame changes.

    Execution Thread: **Main or Background**.
    If you need to update the UI, use the `@run_in_loop` decorator.
    """

def on_playback_started(self) -> None:
    """
    Called when playback starts.

    Execution Thread: **Main**.
    """

def on_playback_stopped(self) -> None:
    """
    Called when playback stops.

    Execution Thread: **Main**.
    """

def on_view_context_menu(self, event: QContextMenuEvent) -> None:
    """
    Called when a context menu of the current viewis requested.

    The event is forwarded BEFORE the view processes it.

    Execution Thread: **Main**.
    """

def on_view_mouse_moved(self, event: QMouseEvent) -> None:
    """
    Called when the mouse of the current view is moved.

    The event is forwarded AFTER the view processes it.

    Execution Thread: **Main**.
    """

def on_view_mouse_pressed(self, event: QMouseEvent) -> None:
    """
    Called when the mouse of the current view is pressed.

    The event is forwarded AFTER the view processes it.

    Execution Thread: **Main**.
    """

def on_view_mouse_released(self, event: QMouseEvent) -> None:
    """
    Called when the mouse of the current view is released.

    The event is forwarded AFTER the view processes it.

    Execution Thread: **Main**.
    """

def on_view_rect_selection_changed(self, rect: QRect) -> None:
    """
    Called when the current view's rectangular selection changes.

    `rect` is in source image pixel coordinates. An empty rect means the selection was cleared.

    Execution Thread: **Main**.
    """

def on_view_rect_selection_finished(self, rect: QRect) -> None:
    """
    Called when the current view's rectangular selection interaction finishes.

    `rect` is in source image pixel coordinates. An empty rect means the selection was cleared.

    Execution Thread: **Main**.
    """

def on_view_key_press(self, event: QKeyEvent) -> None:
    """
    Called when a key is pressed in the current view.

    The event is forwarded AFTER the view processes it.

    Execution Thread: **Main**.
    """

def on_view_key_release(self, event: QKeyEvent) -> None:
    """
    Called when a key is released in the current view.

    The event is forwarded AFTER the view processes it.

    Execution Thread: **Main**.
    """

def on_hide(self) -> None:
    """
    Called when the plugin is hidden.

    Execution Thread: **Main**.
    """

def update_global_settings(self, **updates: Any) -> None:
    """Update specific global settings fields and trigger persistence."""
    self.api._update_settings(self, "global", **updates)

def update_local_settings(self, **updates: Any) -> None:
    """Update specific local settings fields and trigger persistence."""
    self.api._update_settings(self, "local", **updates)

def prepare(self, node: NodeT, /) -> NodeT:
    """
    Process the input node and return a modified node of the same type.

    Args:
        node: The raw input node (VideoNode or AudioNode).

    Returns:
        The processed node compatible with the player's output requirements.
    """
    raise NotImplementedError

def resolve(self, global_settings: BaseModel) -> Self:
    """
    Resolve global settings with local overrides applied.

    Args:
        global_settings: Source of default values.

    Returns:
        A new instance with all fields resolved.
    """
    base_values = global_settings.model_dump(include=set(self.__class__.model_fields))

    overrides = self.model_dump(exclude_none=True)

    return self.__class__(**base_values | overrides)