Skip to content
YosoiDocs

VideoSurface

yosoi.surface.VideoSurface

class VideoSurface:

Frozen local video with a lazy timeline and read-only frame capabilities.

Open with await VideoSurface.open(path). No OCR, audio transcription, playback, live-stream subscription or control is provided. Cancelling the Python await leaves Rust finishing bounded cleanup in the background. Snapshot resources are released when the owning handle is dropped.

Source: python/yosoi/surface.py:781

Members below are declared on this class. Inherited Pydantic methods and generated constructor signatures are not expanded.

def __init__(self, handle: _native.VideoSurface) -> None:

Wrap a Rust-owned snapshot returned by open or read_from.

Source: python/yosoi/surface.py:790

@classmethod
async def open(cls, path: str | Path, policy: VideoPolicy | None=None) -> Self:

Snapshot and probe a regular local file; failures raise VideoError.

Requires FFmpeg and FFprobe on PATH or YOSOI_FFMPEG/YOSOI_FFPROBE. The original file can be removed once this returns successfully.

Source: python/yosoi/surface.py:795

@property
def descriptor(self) -> Descriptor:

Return read/frame capabilities with controllable false.

Source: python/yosoi/surface.py:809

@property
def observation(self) -> Observation:

Return frozen source and decoder-profile interpretation identity.

Source: python/yosoi/surface.py:814

@property
def root_reference(self) -> Reference:

Return the complete visual timeline scope.

Source: python/yosoi/surface.py:819

@property
def metadata(self) -> VideoMetadata:

Return original video dimensions and primary stream timing.

Source: python/yosoi/surface.py:824

@property
def policy(self) -> VideoPolicy:

Return the processing bounds retained by this observation.

Source: python/yosoi/surface.py:829

def read(self, request: ReadRequest) -> ReadResult:

Read timeline evidence; search and parent are unsupported.

Source: python/yosoi/surface.py:833

def at(self, position_us: int) -> Reference:

Address stream-relative time for decoding the first frame at or after it.

Source: python/yosoi/surface.py:837

async def frame(self, reference: Reference) -> DecodedFrame:

Decode one frame; the final-frame tail may have no frame at or after it.

Source: python/yosoi/surface.py:841

async def crop(self, reference: Reference, rect: PixelRect) -> DecodedFrame:

Decode/crop a full-frame reference in decoded-canvas coordinates.

Source: python/yosoi/surface.py:845

async def write_to(self, archive: Archive) -> VideoArchiveRef:

Archive the frozen source and interpretation without live authority.

Source: python/yosoi/surface.py:851

@classmethod
async def read_from(cls, archive: Archive, reference: VideoArchiveRef) -> Self:

Restore a timeline without probing; new frame decoding still needs FFmpeg.

Source: python/yosoi/surface.py:858