API reference#

Exports of @sigx/lynx-video v0.20.0.

Import everything from the package entry. Importing the entry also auto-applies the JSX augmentation that registers the <video-player> intrinsic, so you never import it directly.

import { VideoPlayer } from '@sigx/lynx-video';
import type {
  VideoPlayerProps,
  VideoPlayerAttributes,
  VideoResizeMode,
  VideoLoadEvent,
  VideoLoadEventDetail,
  VideoEndEvent,
  VideoEndEventDetail,
  VideoErrorEvent,
  VideoErrorEventDetail,
  VideoTimeUpdateEvent,
  VideoTimeUpdateEventDetail,
  VideoPlaybackState,
  VideoStateChangeEvent,
  VideoStateChangeEventDetail,
} from '@sigx/lynx-video';

Components#

Each component has its own page with usage, props, slots and events — see the Components catalog:

• VideoPlayer — typed sigx-lynx component wrapping the native <video-player> intrinsic (iOS AVPlayer, Android androidx.media3 ExoPlayer).

Their prop types and related APIs remain documented below.

Types#

VideoPlayerProps#

Props type for VideoPlayer. Every prop is optional (the third Define.Prop type argument is false = not required). Shared across platforms.

export type VideoPlayerProps =
    & Define.Prop<'src', string, false>
    & Define.Prop<'poster', string, false>
    & Define.Prop<'autoplay', boolean, false>
    & Define.Prop<'playing', boolean, false>
    & Define.Prop<'loop', boolean, false>
    & Define.Prop<'muted', boolean, false>
    & Define.Prop<'volume', number, false>
    & Define.Prop<'controls', boolean, false>
    & Define.Prop<'resizeMode', VideoResizeMode, false>
    & Define.Prop<'startTime', number, false>
    & Define.Prop<'class', string, false>
    & Define.Prop<'style', string | Record<string, string | number>, false>
    & Define.Prop<'onLoad', (e: VideoLoadEvent) => void, false>
    & Define.Prop<'onEnd', (e: VideoEndEvent) => void, false>
    & Define.Prop<'onError', (e: VideoErrorEvent) => void, false>
    & Define.Prop<'onTimeUpdate', (e: VideoTimeUpdateEvent) => void, false>
    & Define.Prop<'onStateChange', (e: VideoStateChangeEvent) => void, false>;

Props

• src — URL or file:// URI of the asset. Also accepts http:// and absolute paths starting with / (treated as a local file). Setting it reloads the player; clearing it (empty/undefined) stops playback and releases the asset.
• poster — image shown before the first frame. iOS loads it async (best-effort, no caching) and hides it once the first frame is ready. On Android it is a no-op stub in v1.
• autoplay — begin playback once the asset is ready. Default false.
• playing — declarative play/pause toggle. Overrides autoplay when both are set.
• loop — restart at end-of-clip, handled natively. Default false. Suppresses onEnd.
• muted — mute audio independently of volume. Default false. Sets effective volume to 0 without losing the stored value.
• volume — audio volume, clamped to 0..1. Default 1.
• controls — show the platform default controls overlay. Default false.
• resizeMode — how the frame fits the box; a VideoResizeMode. Default contain.
• startTime — one-shot seek (in seconds) applied once the asset is ready, before the first play. Applied once per loaded src — use for resuming or deep-linking into a clip.
• class / style — standard styling. The player must be given a size.
• onLoad / onEnd / onError / onTimeUpdate / onStateChange — event handlers; see the event types below.

VideoResizeMode#

How the video frame fits inside the element box. Default contain. Shared across platforms.

export type VideoResizeMode = 'contain' | 'cover' | 'stretch';

Values

• contain — letterbox/fit (iOS AVLayerVideoGravity.resizeAspect, Android RESIZE_MODE_FIT).
• cover — fill, cropping overflow (iOS .resizeAspectFill, Android RESIZE_MODE_ZOOM).
• stretch — distort to fill (iOS .resize, Android RESIZE_MODE_FILL).

Interfaces#

VideoPlayerAttributes#

Low-level JSX intrinsic attribute interface for the raw <video-player> element — the native attribute surface, with kebab-case attrs and bind* event handlers. Registered globally as JSX.IntrinsicElements['video-player']. Most apps use the VideoPlayer wrapper instead, which exposes camelCase prop names. Shared (JSX intrinsic).

export interface VideoPlayerAttributes extends LynxCommonAttributes {
    src?: string;
    poster?: string;
    autoplay?: boolean;
    playing?: boolean;
    loop?: boolean;
    muted?: boolean;
    volume?: number;
    controls?: boolean;
    'resize-mode'?: VideoResizeMode;
    'start-time'?: number;
    bindload?: LynxEventHandler<VideoLoadEvent>;
    bindend?: LynxEventHandler<VideoEndEvent>;
    binderror?: LynxEventHandler<VideoErrorEvent>;
    bindtimeupdate?: LynxEventHandler<VideoTimeUpdateEvent>;
    bindvideostatechange?: LynxEventHandler<VideoStateChangeEvent>;
}

Extends LynxCommonAttributes (from @sigx/lynx-runtime), which adds Lynx's shared view attributes like style/class and common layout events. bindtimeupdate fires ~4x/sec and crosses the bridge on each call — use sparingly.

VideoLoadEvent#

Event passed to onLoad / bindload. Fires once asset metadata is available — iOS on AVPlayerItem .readyToPlay, Android on ExoPlayer STATE_READY. Fires at most once per loaded asset. Shared across platforms.

export interface VideoLoadEvent {
    type: 'load';
    detail: VideoLoadEventDetail;
}

VideoLoadEventDetail#

Detail payload of VideoLoadEvent. Shared across platforms.

export interface VideoLoadEventDetail {
    durationMs: number;
    width: number;
    height: number;
    [k: string]: unknown;
}

Fields

• durationMs — total duration in milliseconds; 0 if unknown (live streams / indeterminate duration).
• width / height — natural pixel dimensions. May be 0 if the codec has not decoded a frame yet on Android, and are not re-fired when the size later resolves.
• Index signature for forward-compatible extra fields.

VideoEndEvent#

Event passed to onEnd / bindend. Fires when playback reaches the end of the clip. Does not fire when loop is true — looping is handled natively (iOS seeks to zero and replays; Android uses REPEAT_MODE_ONE). Shared across platforms.

export interface VideoEndEvent {
    type: 'end';
    detail: VideoEndEventDetail;
}

VideoEndEventDetail#

Detail payload of VideoEndEvent. Empty in v1 — only an index signature for forward-compat. Shared across platforms.

export interface VideoEndEventDetail {
    [k: string]: unknown;
}

VideoErrorEvent#

Event passed to onError / binderror. Fires on a non-recoverable load or playback error (iOS AVPlayerItem .failed or invalid src; Android Player.Listener.onPlayerError). Also fired immediately for an invalid/unparseable src URL on iOS. Shared across platforms.

export interface VideoErrorEvent {
    type: 'error';
    detail: VideoErrorEventDetail;
}

VideoErrorEventDetail#

Detail payload of VideoErrorEvent. Shared across platforms.

export interface VideoErrorEventDetail {
    message: string;
    [k: string]: unknown;
}

Fields

• message — human-readable error string (iOS localizedDescription / 'Invalid src: ...'; Android PlaybackException.message or 'Playback error').
• Index signature for forward-compat.

VideoTimeUpdateEvent#

Event passed to onTimeUpdate / bindtimeupdate. Fires ~4x/sec (every 250ms) while actively playing, broadcasting the current position. Crosses the bridge on each call — use sparingly; for high-frequency animation, read the duration once via onLoad and animate locally. On Android the 250ms timer only runs while playing (re-armed on play, stopped on pause/end). Shared across platforms.

export interface VideoTimeUpdateEvent {
    type: 'timeupdate';
    detail: VideoTimeUpdateEventDetail;
}

VideoTimeUpdateEventDetail#

Detail payload of VideoTimeUpdateEvent. Shared across platforms.

export interface VideoTimeUpdateEventDetail {
    positionMs: number;
    [k: string]: unknown;
}

Fields

• positionMs — current playback position in milliseconds (clamped >= 0; iOS guards against NaN/Inf from live streams).
• Index signature for forward-compat.

VideoPlaybackState#

The playback state reported by onStateChange / bindvideostatechange. Shared across platforms.

export type VideoPlaybackState = 'playing' | 'paused' | 'buffering' | 'ended';

VideoStateChangeEvent#

Event passed to onStateChange / bindvideostatechange. Fires whenever playback transitions between playing / paused / buffering / ended — including pauses driven by the OS or the platform controls overlay, which the declarative playing prop can't observe. Lets apps mirror native play state without polling. Shared across platforms.

The wire/intrinsic event is named videostatechange (not statechange) because statechange is a reserved event name in the Lynx engine — a bindstatechange handler would be silently dropped. The public wrapper prop is unchanged: use onStateChange on <VideoPlayer>.

export interface VideoStateChangeEvent {
    type: 'videostatechange';
    detail: VideoStateChangeEventDetail;
}

VideoStateChangeEventDetail#

Detail payload of VideoStateChangeEvent. Shared across platforms.

export interface VideoStateChangeEventDetail {
    state: VideoPlaybackState;
    positionMs: number;
    [k: string]: unknown;
}

Fields

• state — the VideoPlaybackState playback just transitioned into.
• positionMs — current position in milliseconds at the transition.
• Index signature for forward-compat.

See also#

• Usage — practical guides and examples.
• Installation — project setup.