Skip to content

vsmuxtools.video.hdr.helpers

Reusable Dolby Vision and HDR10+ metadata sidecar builders.

DolbyVision 

DolbyVision(source: Any, *, track: int = 0, metadata_path: Path | None = None, profile: Any = None)

Bases: _DynamicMetadata

Build Dolby Vision RPU sidecars with dovi_tool.

Source code in vsmuxtools/video/hdr/helpers.py 
317
318
319
320
def __init__(self, source: Any, *, track: int = 0, metadata_path: Path | None = None, profile: Any = None) -> None:
    super().__init__(source, track=track, metadata_path=metadata_path)
    self._declared_profile = _canonical_profile(profile) if profile is not None else None
    self._target_profile: str | None = None

resolved_profile property 

resolved_profile: str

Return the canonical source or explicitly requested Dolby Vision profile.

Returns:

Type Description
str

A canonical profile string, preserving unknown Profile 8 compatibility.

convert_profile 

convert_profile(profile: Any) -> Self

Request an explicit RPU conversion to Dolby Vision Profile 8.1.

Parameters:

Name Type Description Default
profile Any

Target profile; only P5/P7 to 8.1 is supported.

 required

Returns:

Type Description
Self

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.
Source code in vsmuxtools/video/hdr/helpers.py 
357
358
359
360
361
362
363
364
365
366
367
368
369
370
def convert_profile(self, profile: Any) -> 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

crop_active_area 

crop_active_area(*, frames: Any = None) -> Self

Reset active-area offsets to zero for all or selected frames.

Parameters:

Name Type Description Default
frames Any

Optional current-timeline ranges receiving the crop.

 None

Returns:

Type Description
Self

This helper, with the active-area edit queued for prepare.
Source code in vsmuxtools/video/hdr/helpers.py 
372
373
374
375
376
377
378
379
380
381
382
383
384
def crop_active_area(self, *, frames: Any = 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

active_area 

active_area(left: int, top: int, right: int, bottom: int, *, frames: Any = None) -> Self

Set explicit active-area offsets for all or selected frames.

Parameters:

Name Type Description Default
left int

Active-area left offset in pixels.

 required
top int

Active-area top offset in pixels.

 required
right int

Active-area right offset in pixels.

 required
bottom int

Active-area bottom offset in pixels.

 required
frames Any

Optional current-timeline ranges receiving the offsets.

 None

Returns:

Type Description
Self

This helper, with the active-area edit queued for prepare.
Source code in vsmuxtools/video/hdr/helpers.py 
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
def active_area(self, left: int, top: int, right: int, bottom: int, *, frames: Any = 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

HDR10Plus 

HDR10Plus(source: Any, *, track: int = 0, metadata_path: Path | None = None)

Bases: _DynamicMetadata

Build HDR10+ JSON sidecars with hdr10plus_tool.

Source code in vsmuxtools/video/hdr/helpers.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def __init__(self, source: Any, *, track: int = 0, metadata_path: Path | None = None) -> None:
    if not isinstance(track, int) or track < 0:
        raise error("track must be a non-negative video-track index.", self)
    file = getattr(source, "file", source)
    if isinstance(file, (list, tuple)):
        raise error("HDR metadata helpers support one source file; supply already aligned metadata for concatenated sources.", self)
    self._source = ensure_path_exists(file, self)
    self._track = track
    self._from_file = metadata_path is not None
    self._source_trim_value = copy.deepcopy(getattr(source, "trim", None)) if metadata_path is None else None
    self._mapping: list[int] | None = None
    self._records_cache: dict[Path, list[dict[str, Any]]] = {}
    self._operations: list[tuple[str, Any]] = []
    self._stages: list[dict[str, Any]] | None = None
    self._material: Path | None = self._source if self._from_file else None
    self._prepared: Path | None = None
    self._segments: dict[tuple[str, ...], Path] = {}