vsmuxtools.video.hdr.helpers

@classmethod
def from_file(cls, path: PathLike, *, track: int = 0, profile: str | int | float | None = None) -> Self:
    """Create a helper from an existing Dolby Vision RPU sidecar.

    :param path: Existing RPU sidecar.
    :param track: Source video-track index, retained for compatibility; no extraction occurs.
    :param profile: Optional source profile, e.g. ``"8.1"`` or ``8.4``. Aliases
                    ``81``, ``84``, ``"p5"``, ``"p7"`` and ``"p8"`` are accepted.
                    Without a declaration, an RPU's Profile 8 compatibility stays unknown.
    :return: A lazy metadata helper backed by the sidecar.
    """

    return cls(path, metadata_path=path, track=track, profile=profile)

def convert_profile(self, profile: str | int | float) -> Self:
    """Request an explicit RPU conversion to Dolby Vision Profile 8.1.

    :param profile: Target profile; only P5/P7 to 8.1 is supported.
    :return: This helper, with conversion deferred until ``prepare``.

    P5 conversion changes RPU signaling only; the caller must convert pixels separately.
    P7 FEL handling likewise remains the caller's responsibility.
    """

    target = _canonical_profile(profile)
    self._target_profile = target
    self._mapping = None
    return self

def crop_active_area(self, *, frames: Trim | list[int | None] | Sequence[Trim] | None = None) -> Self:
    """Reset active-area offsets to zero for all or selected frames.

    :param frames: Optional current-timeline ranges receiving the crop.
    :return: This helper, with the active-area edit queued for ``prepare``.
    """

    if frames is None:
        self._operations.append(("config", {"active_area": {"crop": True}}))
    else:
        self._operations.append(("crop", copy.deepcopy(frames)))
    self._mapping = None
    return self

def active_area(self, left: int, top: int, right: int, bottom: int, *, frames: Trim | list[int | None] | Sequence[Trim] | None = None) -> Self:
    """Set explicit active-area offsets for all or selected frames.

    :param left: Active-area left offset in pixels.
    :param top: Active-area top offset in pixels.
    :param right: Active-area right offset in pixels.
    :param bottom: Active-area bottom offset in pixels.
    :param frames: Optional current-timeline ranges receiving the offsets.
    :return: This helper, with the active-area edit queued for ``prepare``.
    """

    values = (left, top, right, bottom)
    if any(not isinstance(value, int) or value < 0 for value in values):
        raise error("Active-area offsets must be non-negative integers.", self)
    self._operations.append(("active_area", ((left, top, right, bottom), copy.deepcopy(frames))))
    self._mapping = None
    return self