Video¶

Video plays local and remote video in a native player view, and a ref on it publishes a VideoHandle. Enable it with use = ["video"] under [plugins]. See the Video guide.

Video playback: a native player view with a typed handle.

Enable it in pythonnative.toml:

[plugins]
use = ["video"]

Example

import pythonnative as pn
from pythonnative.video import Video

@pn.component
def Player(url: str) -> pn.Node:
    player = pn.use_ref()
    return pn.Column(
        Video(source=url, controls=True, ref=player, style=pn.style(aspect_ratio=16 / 9)),
        pn.Button("Restart", on_press=lambda: player.current.seek(0)),
    )

Classes:

Name	Description
`VideoInfo`	What `on_ready` reports about a loaded video.
`VideoHandle`	The handle a `ref` on `Video` receives.

Functions:

Name	Description
`Video`	Play a local or remote video in a native player view.

Attributes:

Name	Type	Description
`ResizeMode`		How the picture fits its view: letterboxed, cropped to fill, or distorted to fill.
`VideoSource`		An `http(s)` URL, a file path, a bundled `Asset`, or a path under `app/assets/`.

ResizeMode `module-attribute` ¶

ResizeMode = Literal['contain', 'cover', 'stretch']

How the picture fits its view: letterboxed, cropped to fill, or distorted to fill.

VideoSource `module-attribute` ¶

VideoSource = Union[str, Asset, 'os.PathLike[str]']

An http(s) URL, a file path, a bundled Asset, or a path under app/assets/.

VideoInfo `dataclass` ¶

VideoInfo(duration: float, width: float, height: float)

What on_ready reports about a loaded video.

Attributes:

Name	Type	Description
`duration`	`float`	Length in seconds, or `0` for a live stream.
`width`	`float`	Picture width in pixels, or `0` when there's no video track.
`height`	`float`	Picture height in pixels, or `0` when there's no video track.

VideoHandle ¶

VideoHandle(tag: int, type_name: str, backend: Any)

Bases: ViewHandle

The handle a ref on Video receives.

Methods:

Name	Description
`play`	Start or resume playback. A video that has ended restarts from the beginning.
`pause`	Pause playback.
`seek`	Jump to `seconds` from the start, clamped to the video's length.
`position`	Return the current playback position in seconds.

play ¶

play() -> None

Start or resume playback. A video that has ended restarts from the beginning.

pause ¶

pause() -> None

Pause playback.

seek ¶

seek(seconds: float) -> None

Jump to seconds from the start, clamped to the video's length.

position `async` ¶

position() -> float

Return the current playback position in seconds.

Video ¶

Video(
    source: Optional[VideoSource] = None,
    *,
    controls: bool = False,
    autoplay: bool = False,
    loop: bool = False,
    muted: bool = False,
    volume: float = 1.0,
    rate: float = 1.0,
    resize_mode: ResizeMode = "contain",
    poster: Optional[VideoSource] = None,
    progress_interval: float = 0.25,
    on_ready: Optional[Callable[[VideoInfo], Any]] = None,
    on_progress: Optional[
        Callable[[float, float], Any]
    ] = None,
    on_end: Optional[Callable[[], Any]] = None,
    on_error: Optional[Callable[[str], Any]] = None,
    on_buffering: Optional[Callable[[bool], Any]] = None,
    style: StyleProp = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

Play a local or remote video in a native player view.

The view has no intrinsic size, so give it one through style: a width and height, or a flex, or an aspect_ratio inside a sized parent. Passing a ref publishes a VideoHandle on ref.current.

The player releases its resources when the view unmounts. When the app goes to the background, playback pauses and resumes on return; Android also frees the decoder until then, since a device has few of them.

Parameters:

Name	Type	Description	Default
`source`	`Optional[VideoSource]`	What to play: an `http(s)` URL, a file path, a bundled `Asset`, or a path under `app/assets/`.	`None`
`controls`	`bool`	Show the platform's playback controls (`AVPlayerViewController` on iOS, `PlayerView`'s controller on Android, the browser's own in the preview).	`False`
`autoplay`	`bool`	Start playing as soon as the video is ready.	`False`
`loop`	`bool`	Restart at the end. A looping video doesn't fire `on_end`.	`False`
`muted`	`bool`	Silence the audio track without changing `volume`.	`False`
`volume`	`float`	Audio level from `0.0` to `1.0`.	`1.0`
`rate`	`float`	Playback speed, where `1.0` is normal.	`1.0`
`resize_mode`	`ResizeMode`	How the picture fits the view.	`'contain'`
`poster`	`Optional[VideoSource]`	An image shown until playback starts, as a URL, a file path, or an asset.	`None`
`progress_interval`	`float`	Seconds between `on_progress` calls.	`0.25`
`on_ready`	`Optional[Callable[[VideoInfo], Any]]`	Called with a `VideoInfo` once the source has loaded and can play.	`None`
`on_progress`	`Optional[Callable[[float, float], Any]]`	Called with `(position, duration)` in seconds while playing, every `progress_interval`.	`None`
`on_end`	`Optional[Callable[[], Any]]`	Called when playback reaches the end.	`None`
`on_error`	`Optional[Callable[[str], Any]]`	Called with a message when the source can't load or play.	`None`
`on_buffering`	`Optional[Callable[[bool], Any]]`	Called with `True` when playback stalls waiting for data and `False` when it can continue.	`None`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`ref`	`Optional[Ref]`	Optional `Ref` from `use_ref()`.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Video"`.

Raises:

Type	Description
`PluginNotEnabledError`	On a device whose build doesn't include `video`.