Scening Tool API¶

API for extending the Scening tool with custom parsers and serializers.

Core Classes

Models

Utility & Hook

Core Classes¶

Classes¶

Parser ¶

Bases: ABC

Base class for implementing custom scening parsers.

Parsers are responsible for reading file-like objects and converting them into SceneRow objects, which contain lists of frames or timestamps.

To implement a parser, create a subclass and:

Define the filter class variable.
Implement the parse method.
Register it using the vsview_scening_register_parser hook.

Attributes¶

FileFilter ¶

FileFilter: type[_FileFilter] = _FileFilter

Alias to FileFilter for convenience in subclasses.

filter ¶

filter: _FileFilter

The file filter used by the plugin to identify supported files in the import dialog.

Functions¶

parse ¶

parse(io: BinaryIO, name: str, fps: Fraction) -> SceneRow | Sequence[SceneRow]

Parse a binary stream into one or more SceneRow objects.

Parameters:

Name	Type	Description	Default
`io`	`BinaryIO`	The input binary stream.	required
`name`	`str`	The suggested name for the scene (usually the base filename).	required
`fps`	`Fraction`	The frame rate of the current video project, used for frame conversions.	required

Returns:

Type	Description
`SceneRow \| Sequence[SceneRow]`	A single scene or a sequence of scenes.

Source code in src/vsview/app/tools/scening/api.py

@abstractmethod
def parse(self, io: BinaryIO, name: str, fps: Fraction) -> SceneRow | Sequence[SceneRow]:
    """
    Parse a binary stream into one or more SceneRow objects.

    Args:
        io: The input binary stream.
        name: The suggested name for the scene (usually the base filename).
        fps: The frame rate of the current video project, used for frame conversions.

    Returns:
        A single scene or a sequence of scenes.
    """
    ...

get_color ¶

get_color() -> QColor

Get a suggested color for the new scene row.

This method is monkey-patched onto parser instances by the scening tool during the import process. It uses a golden-ratio-based generator to ensure distinct colors for adjacent scenes.

Returns:

Type	Description
`QColor`	A suggested color for the new scene.

Source code in src/vsview/app/tools/scening/api.py

def get_color(self) -> QColor:
    """
    Get a suggested color for the new scene row.

    This method is monkey-patched onto parser instances by the scening tool during the import process.
    It uses a golden-ratio-based generator to ensure distinct colors for adjacent scenes.

    Returns:
        A suggested color for the new scene.
    """
    ...

Serializer ¶

Bases: ABC

Base class for implementing custom scening exporters.

Serializers are responsible for taking a list of ranges and writing them to a file-like object in a specific format.

To implement a serializer, create a subclass and:

Define the filter class variable.
Implement the serialize method.
Register it using the vsview_scening_register_serializer hook.

Attributes¶

FileFilter ¶

FileFilter: type[_FileFilter] = _FileFilter

Alias to FileFilter for convenience in subclasses.

filter ¶

filter: _FileFilter

The file filter used by the plugin to identify supported files in the export dialog.

Functions¶

serialize ¶

serialize(io: BinaryIO, ranges: Iterator[UnifiedRange]) -> None

Serialize a set of ranges into a binary stream.

Parameters:

Name	Type	Description	Default
`io`	`BinaryIO`	The output binary stream.	required
`ranges`	`Iterator[UnifiedRange]`	An iterator of UnifiedRange objects. These provide helpers like `as_frames()` and `as_times()` to facilitate format conversion.	required

Source code in src/vsview/app/tools/scening/api.py

@abstractmethod
def serialize(self, io: BinaryIO, ranges: Iterator[UnifiedRange]) -> None:
    """
    Serialize a set of ranges into a binary stream.

    Args:
        io: The output binary stream.
        ranges: An iterator of UnifiedRange objects.
            These provide helpers like `as_frames()` and `as_times()` to facilitate format conversion.
    """

FileFilter ¶

Bases: NamedTuple

Metadata used to define file types in the scening tool's import/export dialogs.

Attributes¶

label ¶

label: str

The human-readable description of the file format (e.g., "Matroska XML Chapters").

suffix ¶

suffix: str | Sequence[str]

The file extension(s) without the leading dot (e.g., "xml" or ["txt", "log"]).

Models¶

Classes¶

RangeFrame ¶

Bases: AbstractRange[int], UUIDModel

A range defined by frame numbers.

Attributes¶

start ¶

start: T

The start point of the range.

end ¶

end: T | None = None

The end point of the range. If None, the range represents a single point (start).

label ¶

label: str = ''

An optional description for this range.

Functions¶

to_tuple ¶

to_tuple() -> tuple[T, T]

Return a tuple of (start, end), where end defaults to start if None.

Source code in src/vsview/app/tools/scening/models.py

def to_tuple(self) -> tuple[T, T]:
    """
    Return a tuple of (start, end), where end defaults to start if None.
    """
    return self.start, fallback(self.end, self.start)

RangeTime ¶

Bases: AbstractRange[timedelta], UUIDModel

A range defined by timestamps (timedelta).

Attributes¶

start ¶

start: T

The start point of the range.

end ¶

end: T | None = None

The end point of the range. If None, the range represents a single point (start).

label ¶

label: str = ''

An optional description for this range.

Functions¶

to_tuple ¶

to_tuple() -> tuple[T, T]

Return a tuple of (start, end), where end defaults to start if None.

Source code in src/vsview/app/tools/scening/models.py

def to_tuple(self) -> tuple[T, T]:
    """
    Return a tuple of (start, end), where end defaults to start if None.
    """
    return self.start, fallback(self.end, self.start)

SceneRow ¶

Bases: UUIDModel

Represents a collection of ranges grouped under a single name and color.

UnifiedRange ¶

UnifiedRange(
    r: RangeFrame | RangeTime,
    frame_to_time: Callable[[int], Time],
    time_to_frame: Callable[[timedelta], int],
)

A helper wrapper providing a unified interface for frame and time-based ranges.

Source code in src/vsview/app/tools/scening/models.py

def __init__(
    self,
    r: RangeFrame | RangeTime,
    frame_to_time: Callable[[int], Time],
    time_to_frame: Callable[[timedelta], int],
) -> None:
    self._r = r
    self._frame_to_time = frame_to_time
    self._time_to_frame = time_to_frame
    self.label = self._r.label

Functions¶

as_frames ¶

as_frames() -> tuple[int, int]

Convert the range to a tuple of (start_frame, end_frame).

Source code in src/vsview/app/tools/scening/models.py

def as_frames(self) -> tuple[int, int]:
    """Convert the range to a tuple of (start_frame, end_frame)."""
    if isinstance(self._r, RangeFrame):
        return self._r.to_tuple()

    s, e = self._r.to_tuple()

    return self._time_to_frame(s), self._time_to_frame(e)

as_times ¶

as_times() -> tuple[Time, Time]

Convert the range to a tuple of (Time, Time).

Source code in src/vsview/app/tools/scening/models.py

def as_times(self) -> tuple[Time, Time]:
    """Convert the range to a tuple of (Time, Time)."""
    if isinstance(self._r, RangeTime):
        s, e = self._r.to_tuple()
        return Time(seconds=s.total_seconds()), Time(seconds=e.total_seconds())

    s, e = self._r.to_tuple()

    return self._frame_to_time(s), self._frame_to_time(e)

Utility & Hook¶

Attributes¶

hookimpl ¶

hookimpl = HookimplMarker('vsview.scening')

Functions¶

borrowed_text_wrapper ¶

borrowed_text_wrapper(
    stream: BinaryIO, encoding: str = "utf-8", errors: str = "strict"
) -> Iterator[TextIOWrapper]

A context manager that wraps a binary stream into a text stream without closing it.

Source code in src/vsview/app/tools/scening/api.py

@contextmanager
def borrowed_text_wrapper(
    stream: BinaryIO,
    encoding: str = "utf-8",
    errors: str = "strict",
) -> Iterator[TextIOWrapper]:
    """A context manager that wraps a binary stream into a text stream without closing it."""

    wrapper = TextIOWrapper(stream, encoding=encoding, errors=errors)
    try:
        yield wrapper
    finally:
        wrapper.detach()