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.
Methods
Section titled “Methods”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
descriptor
Section titled “descriptor”@property
def descriptor(self) -> Descriptor:
Return read/frame capabilities with controllable false.
Source: python/yosoi/surface.py:809
observation
Section titled “observation”@property
def observation(self) -> Observation:
Return frozen source and decoder-profile interpretation identity.
Source: python/yosoi/surface.py:814
root_reference
Section titled “root_reference”@property
def root_reference(self) -> Reference:
Return the complete visual timeline scope.
Source: python/yosoi/surface.py:819
metadata
Section titled “metadata”@property
def metadata(self) -> VideoMetadata:
Return original video dimensions and primary stream timing.
Source: python/yosoi/surface.py:824
policy
Section titled “policy”@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
write_to
Section titled “write_to”async def write_to(self, archive: Archive) -> VideoArchiveRef:
Archive the frozen source and interpretation without live authority.
Source: python/yosoi/surface.py:851
read_from
Section titled “read_from”@classmethod
async def read_from(cls, archive: Archive, reference: VideoArchiveRef) -> Self:
Restore a timeline without probing; new frame decoding still needs FFmpeg.