User API¶

def set_output(
    node: OutputNode,
    index_or_name: int | Sequence[int] | str | bool | None = None,
    name: str | bool | None = None,
    /,
    alpha: vs.VideoNode | Literal[True] | None = None,
    *,
    framedurs: Sequence[SupportsFloat] | None = None,
    hdr: bool | None = None,
    downmix: bool | None = None,
    **kwargs: Any,
) -> None:
    """
    Register one or more VapourSynth nodes as outputs for preview.

    This function sets the output(s) and registers metadata for tab naming in vsview.
    If no index is provided, outputs are assigned to the next available indices.

    Examples:
        ```python
        set_output(clip)  # Auto-index, auto-name ("clip")
        set_output(clip, 0)  # Index 0, auto-name
        set_output(clip, 0, "My Clip")  # Index 0, explicit name
        set_output(clip, "Source")  # Auto-index, explicit name
        set_output([clip1, clip2])  # Multiple outputs
        ```

    Args:
        node: A VideoNode, AudioNode, or iterable of nodes to output.
        index_or_name: Either:

               - An int or sequence of ints specifying output indices
               - A str to use as the output name
               - True/None to auto-detect the variable name
               - False to disable name detection

        name: Explicit name override. If provided when index_or_name is an int,
            this sets the display name for the output.
        alpha: Optional alpha channel VideoNode or if True, fetch the `_Alpha` prop (only for VideoNode outputs).
        framedurs: Optional sequence of frame durations in seconds for VFR clips (only for VideoNode outputs).
        hdr: Optional boolean override for the HDR detection for VideoNode outputs.
            If passing `--hdr`, this flag can be used to disable HDR conversion for this output.
        downmix: if None (default), follows the global settings downmix of vsview if previewed
            through vsview. Otherwise True or False forces the behavior.
        **kwargs: Additional metadata for custom configuration of this output.
    """
    if isinstance(index_or_name, (str, bool)):
        index = None
        name = index_or_name
    else:
        index = index_or_name

    outputs = vs.get_outputs()
    nodes = list[vs.VideoNode | vs.AudioNode](flatten([node]))

    indices = to_arr(index) if index is not None else [max(outputs, default=-1) + 1]

    while len(indices) < len(nodes):
        indices.append(indices[-1] + 1)

    frame_depth = kwargs.pop("frame_depth", 1) + 1
    script_module = sys.modules.get("__vsview__")

    for i, n in zip(indices[: len(nodes)], nodes):
        if i in outputs:
            _logger.warning("Output index %d already in use; overwriting.", i)

        match n:
            case vs.VideoNode():
                n.set_output(i, alpha if alpha is not True else None)
                title = "Clip"
            case vs.AudioNode():
                n.set_output(i)
                title = "Audio"
            case _:
                assert_never(n)

        if not script_module:
            continue

        effective_name: str | None

        match name:
            case True | None:
                effective_name = _resolve_var_name(n, frame_depth=frame_depth)
            case False:
                effective_name = None
            case str():
                effective_name = name

        if file := getattr(script_module, "__file__", None):
            if isinstance(n, vs.VideoNode):
                if framedurs and len(framedurs) != n.num_frames:
                    raise CustomValueError(
                        "framedurs length must match number of frames", kwargs.pop("func", set_output)
                    )

                _output_metadata[file][i] = VideoMetadata(
                    effective_name or f"{title} {i}",
                    [float(f) for f in (framedurs or [])],
                    alpha is True or None,
                    hdr,
                    kwargs,
                )
            elif isinstance(n, vs.AudioNode):
                _output_metadata[file][i] = AudioMetadata(effective_name or f"{title} {i}", downmix, kwargs)

def catch_output[**P, N: OutputNode](
    func: Callable[P, N] | None = None,
    /,
    index: int | Sequence[int] | None = None,
    name: str | bool | None = None,
    alpha: vs.VideoNode | Literal[True] | None = None,
    *,
    framedurs: Sequence[SupportsFloat] | None = None,
    downmix: bool | None = None,
    **kwargs: Any,
) -> Callable[P, N] | Callable[[Callable[P, N]], Callable[P, N]]:
    """
    Decorator variant of `set_output()`.

    Calls the decorated function and registers its return value as an output.

    Examples:
        ```python
        @catch_output
        def source() -> vs.VideNode:
            return vs.core.bs.BestSource("video.mkv")


        @catch_output(name="Filtered", alpha=True)
        def filtered() -> vs.VideNode:
            src = vs.core.bs.BestSource("image.png")
            return src.std.BoxBlur()
        ```

    Args:
        func: The function to decorate (populated automatically when used as a bare decorator).
        index: An int or sequence of ints specifying output indices
        name: Explicit name override. If not provided, the function name is used.
        alpha: Optional alpha channel VideoNode or if True, fetch the `_Alpha` prop (only for VideoNode outputs).
        framedurs: Optional sequence of frame durations in seconds for VFR clips (only for VideoNode outputs).
        downmix: If None (default), follows the global settings downmix of vsview if previewed through vsview.
            Otherwise True or False forces the behavior.
        **kwargs: Additional metadata passed to VSView plugins for custom configuration of this output.

    Returns:
        The decorated function (its original return type is preserved).
    """

    def decorator(fn: Callable[P, N]) -> Callable[P, N]:
        @wraps(fn)
        def wrapper(*fn_args: P.args, **fn_kwargs: P.kwargs) -> N:
            nonlocal name

            result = fn(*fn_args, **fn_kwargs)

            if name is True or name is None:
                name = fn.__name__

            set_output(  # type: ignore[misc]
                result,  # type: ignore[arg-type]
                index,  # type: ignore[arg-type]
                name,
                alpha=alpha,
                framedurs=framedurs,
                downmix=downmix,
                **kwargs,
            )

            return result

        return wrapper

    if func is not None:
        return decorator(func)

    return decorator

def is_preview() -> bool:
    """Check if the current script is running in a preview environment (VSView only)."""
    return bool(sys.modules.get("__vsview__"))

def is_reload() -> bool | None:
    """
    Check if the current script run is a reload inside VSView.
    """
    return ctx.is_reload if (ctx := Context.get()) is not None else None

def get_reload_count() -> int | None:
    """
    Return how many times the current script has been reloaded in VSView
    (0 if initial load or None outside preview).
    """
    return ctx.reload_count if (ctx := Context.get()) is not None else None

def get_state() -> MutableMapping[Any, Any] | None:
    """
    Return the persistent state dictionary shared across script reloads, or None if outside VSView.

    Note:
        Objects stored in this dictionary survive script reloads within the same workspace.
        - DO NOT store VapourSynth clips, frames, or script closures capturing 'globals()'.
        - DO store heavy external resources (e.g. PyTorch models, ONNX sessions, lookup tables).
    """
    return ctx.persistent_state if (ctx := Context.get()) is not None else None

def get_cached[**P, R](key: str, loader: Callable[P, R], *args: P.args, **kwargs: P.kwargs) -> R:
    """
    Get a cached value from the persistent state, or compute and cache it if not present.

    If running outside VSView, the loader is called directly without caching.

    Args:
        key: The key to look up or store in the persistent state.
        loader: A callable to produce the value if key is not found.
        *args: Positional arguments forwarded to loader.
        **kwargs: Keyword arguments forwarded to loader.

    Returns:
        The cached or newly computed value.
    """
    if (state := get_state()) is None:
        return loader(*args, **kwargs)
    if key not in state:
        state[key] = loader(*args, **kwargs)
    return state[key]