Video

Video provides controlled playback of live or VOD content with optional built-in UI, trick play, and captions

import { Video } from "@roku-sdk/components";

Video(props: IVideoProps): JSX.Element

Description

Video provides controlled playback of live or VOD content with optional built-in UI, trick play, and captions.

Parameters

Name	Type	Description
`props`	IVideoProps

Example

<video
  width={1280}
  height={720}
  content={<VideoContentNode url={url} />}
  control="play"
  onState={state => console.log(state)}
/>

Types

IVideoProps

All Video node props: extends Group with playback, trick play, UI, captions, audio, and misc fields.

Extends IGroupProps, IVideoPlaybackProps, ITrickPlayProps, IVideoUiProps, IVideoCaptionProps, IVideoAudioProps, IVideoMiscProps.

IAudioSelectionPreferences

Audio track selection preferences (Roku OS 12.5+).

Name	Type	Description
`overrideSystem`	`boolean`
`values`	`AudioSelectionPreferenceRule[]`

GlobalCaptionMode

Global Roku closed-caption mode for the Video globalCaptionMode field.

Member	Value	Description
`Off`	`"Off"`
`On`	`"On"`
`InstantReplay`	`"Instant replay"`
`WhenMute`	`"When mute"`

IVideoAudioTrack

One entry of the Video node availableAudioTracks field.

Firmware always emits every key below; the TypeScript and BrightScript bridges both build each entry from the media player's audio track list.

Name	Type	Description
`Format`	`string`	Human-readable audio format description from the demuxer, for example `"ISO/IEC 14496-3, Advanced Audio Coding, ADTS container"`. Not listed in the Roku docs; may be an empty string when the demuxer reports no format.
`HasAccessibilityDescription`	`boolean`	HLS "public.accessibility.describes-video", or a DASH audio description.
`HasAccessibilityEAI`	`boolean`	DASH Enhanced Audio Intelligibility track.
`Language`	`string`	Language code as declared by the stream. Roku docs describe an ISO 639-2 three-letter code (`"eng"`), but the value is passed through from the manifest, so two-letter codes such as `"en"` also occur.
`Name`	`string`	Descriptive name of the audio track.
`Track`	`string`	Track identifier; assign it to `audioTrack` to select the track.

IVideoSubtitleTrack

One entry of the Video node availableSubtitleTracks field.

Firmware always emits every key below.

Name	Type	Description
`Description`	`string`	Descriptive name of the subtitle track.
`HasAccessibilityCaption`	`boolean`	HLS "public.accessibility.transcribes-spoken-dialog", or DASH captions.
`HasAccessibilityDescription`	`boolean`	HLS "public.accessibility.describes-music-and-sound".
`HasAccessibilitySign`	`boolean`	DASH sign-language interpretation.
`Language`	`string`	Language code as declared by the stream. Roku docs describe an ISO 639-2 three-letter code (`"eng"`), but two-letter codes such as `"en"` also occur.
`TrackName`	`string`	Track identifier; assign it to `subtitleTrack` to select the track.

IDecoderStats

Video decoder statistics when IVideoPlaybackProps.enableDecoderStats is true.

Name	Type	Description
`frameDropCount`	`number`
`renderCount`	`number`
`repeatCount`	`number`
`streamErrorCount`	`number`

IDownloadedSegmentInfo

Information about a segment that was just downloaded.

Name	Type	Description
`bitrateBPS`	`number`
`downloadDuration`	`number`
`hdrMode`	`DownloadedSegmentHdrMode`
`height`	`number`
`path`	`string`
`segDuration`	`string`
`segSequence`	`number`
`segSize`	`number`
`segStart`	`number`
`segType`	`number`
`segUrl`	`string`
`status`	`number`
`width`	`number`

VideoErrorInfo

Structured error information from the Video node errorInfo field.

Name	Type	Description
`category`	`string`
`clipId`	`number`
`dbgmsg`	`string`
`drmerrcode`	`number`
`errcode`	`number`
`ignored`	`number`
`source`	`string`

ILicenseStatus

DRM license acquisition status from the Video node.

Name	Type	Description
`duration`	`string`
`keysystem`	`string`
`response`	`string`
`status`	`string`

IPlayStartInfo

Timing measurements related to the start of video playback (seconds unless noted).

Name	Type	Description
`drm_lic_acq_dur`	`number`
`drm_lic_acq_start`	`number`
`drm_load_dur`	`number`
`drm_load_start`	`number`
`manifest_dur`	`number`
`manifest_start`	`number`
`prebuf_dur`	`number`
`prebuf_start`	`number`
`total_dur`	`number`

IPositionInfo

Position info for last rendered audio/video samples.

Name	Type	Description
`audio`	`number`
`clip_id`	`number`
`epoch`	`number`
`video`	`number`

IStreamingSegmentInfo

Information about the video segment currently streaming (HLS/DASH).

Name	Type	Description
`hdrModeStr`	`StreamingSegmentHdrMode`
`height`	`number`
`latency`	`number`
`path`	`string`
`segBitrateBps`	`number`
`segSequence`	`number`
`segStart`	`number`
`segType`	`number`
`segTypeStr`	`StreamingSegmentType`
`segUrl`	`string`
`width`	`number`

IPlaybackActionButton

One playback action button on the pause screen.

Name	Type	Description
`buttonIsDisabled?`	`boolean`
`focusIcon?`	`Uri`
`icon?`	`Uri`
`text?`	`string`

VideoSeekMode

Seek accuracy for the Video node seekMode field.

Member	Value	Description
`Default`	`"default"`
`Accurate`	`"accurate"`

ISubtitleSelectionPreferences

Subtitle track selection preferences (Roku OS 12.5+).

Name	Type	Description
`overrideSystem`	`boolean`
`values`	`SubtitleSelectionPreferenceRule[]`

IVideoPlaybackProps

Playback-related fields for the Video node: content, control, errors, and DRM.

Name	Type	Description
`asyncStopSemantics?`	`boolean`	When true, STOP runs asynchronously (Roku OS 12.5+). `state` becomes `stopping` then `stopped`.
`audioSelectionPreferences?`	`IAudioSelectionPreferences`	Audio track selection priority (write-only configuration).
`content?`	`Element`	ContentNode (or playlist parent) with content metadata for playback.
`contentIsPlaylist?`	`boolean`	When true, children of `content` form a video playlist.
`control?`	`MediaControl`	Play state command (play, pause, stop, prebuffer, etc.).
`enableDecoderStats?`	`boolean`	When true, `decoderStats` is populated and updated.
`nextContentIndex?`	`number`	Next playlist index to play after the current item ends or is skipped.
`onContentIndex?`	`EventHandler<number>`	Index of the current item in a playlist (or 0 for single content).
`onDecoderStats?`	`EventHandler<IDecoderStats>`	Fired when decoder statistics are updated (requires `enableDecoderStats`).
`onErrorCode?`	`EventHandler<number>`	Fired when `errorCode` changes after an error state.
`onErrorInfo?`	`EventHandler<VideoErrorInfo>`	Fired when structured `errorInfo` is updated.
`onErrorMsg?`	`EventHandler<string>`	Fired when `errorMsg` changes.
`onErrorStr?`	`EventHandler<string>`	Fired when `errorStr` changes.
`onLicenseStatus?`	`EventHandler<ILicenseStatus>`	Fired when DRM license status changes.
`onPlayStartInfo?`	`EventHandler<IPlayStartInfo>`	Fired when play-start timing info is updated.
`onState?`	`EventHandler<MediaState>`	Fired when playback state changes (buffering, playing, error, etc.).
`playbackActionButtonFocused?`	`number`	Focused index in `playbackActionButtons`.
`playbackActionButtonFocusedTextColor?`	`string`	Text color when the playback action button has focus.
`playbackActionButtonFocusedTextFont?`	`string`	Font for the focused playback action button label.
`playbackActionButtonFocusIndicatorBlendColor?`	`string`	Background blend color when the playback action button has focus.
`playbackActionButtons?`	`IPlaybackActionButton[]`	Buttons and UI on the pause screen at start of playback.
`playbackActionButtonSelected?`	`number`	Selected index in `playbackActionButtons`.
`playbackActionButtonUnfocusedTextColor?`	`string`	Text color when the playback action button does not have focus.
`playbackActionButtonUnfocusedTextFont?`	`string`	Font for unfocused playback action button labels.
`subtitleSelectionPreferences?`	`ISubtitleSelectionPreferences`	Subtitle track selection priority (write-only configuration).

ITrickPlayProps

Trick play, seek, segments, and related timing fields.

Name	Type	Description
`autoplayAfterSeek?`	`boolean`	When false, disables auto-play after rebuffer following a seek.
`enableLiveAvailabilityWindow?`	`boolean`	Enables trick play bar scrubbing within the live availability window.
`enableThumbnailTilesDuringLive?`	`boolean`	When true, `thumbnailTiles` updates during live HLS/DASH with thumbnails.
`loop?`	`boolean`	When true, restarts playlist or single content after the end.
`notificationInterval?`	`number`	Seconds between `position` observer notifications; 0 disables notifications.
`onClipId?`	`EventHandler<number>`	Fired when the current clip ID changes.
`onDownloadedSegment?`	`EventHandler<IDownloadedSegmentInfo>`	Fired when a segment download completes.
`onDuration?`	`EventHandler<number>`	Fired when stream duration is known or changes.
`onPosition?`	`EventHandler<number>`	Fired on position updates (interval from `notificationInterval`).
`onPositionInfo?`	`EventHandler<IPositionInfo>`	Fired with last rendered sample positions.
`onStreamingSegment?`	`EventHandler<IStreamingSegmentInfo>`	Fired with info about the segment currently being streamed.
`seek?`	`number`	Seek target in seconds from stream start (write-only).
`seekMode?`	`VideoSeekMode`	Seek accuracy: default (keyframe) vs accurate (if supported).
`thumbnailTiles?`	`Record<string, unknown>`	Thumbnail tile sets from the manifest (structure varies by OS version).
`timedMetaDataSelectionKeys?`	`string[]`	Keys for timed metadata (e.g. ID3); matching tags populate `timedMetaData` / `timedMetaData2`.
`trickPlayBackgroundOverlay?`	`Uri`	Background overlay URI while playback UI is visible.

IVideoUiProps

Built-in Video UI: dimensions, toggles, and internal bar/BIF/pivot nodes.

Name	Type	Description
`bifDisplay?`	`Element`	BIF display sub-node instance.
`bufferingBar?`	`Element`	Buffering progress bar sub-node instance.
`bufferingTextColor?`	`string`	Text color near the buffering bar (0 = system default).
`enableTrickPlay?`	`boolean`	When false, remote trick play keys have no effect (requires `enableUI`).
`enableUI?`	`boolean`	When false, hides most built-in UI (app implements custom UI).
`height?`	`number`	Video window height in pixels; 0 uses full display height.
`pivotNode?`	`Element`	Pivot renderable shown when video is paused.
`retrievingBar?`	`Element`	Initial retrieve progress bar sub-node instance.
`retrievingTextColor?`	`string`	Text color near the retrieving bar (0 = system default).
`trickPlayBar?`	`Element`	Trick play bar sub-node instance.
`width?`	`number`	Video window width in pixels; 0 uses full display width.

IVideoCaptionProps

Closed caption and subtitle styling fields.

Name	Type	Description
`captionStyle?`	`Record<string, string>`	Caption styling keys (Text/Font, Text/Size, Background/Color, etc.) per Roku docs.
`globalCaptionMode?`	`GlobalCaptionMode`	Global caption mode; app should still set `subtitleTrack` as needed.
`onAvailableSubtitleTracks?`	`EventHandler<IVideoSubtitleTrack[]>`	Fired with the subtitle tracks found in the stream and content metadata (read-only on the node).
`onCurrentSubtitleTrack?`	`EventHandler<string>`	Fired when the playing subtitle track changes; carries the track identifier (`TrackName`).
`subtitleTrack?`	`string`	Selected subtitle track identifier (read/write).
`suppressCaptions?`	`boolean`	Suppresses captions when resolving UI overlap conflicts.

IVideoAudioProps

Audio output and track selection fields.

Name	Type	Description
`audioTrack?`	`string`	Selected audio track identifier (prefer platform selection when possible).
`mute?`	`boolean`	Mutes or restores audio for the current stream.
`onAvailableAudioTracks?`	`EventHandler<IVideoAudioTrack[]>`	Fired with the audio tracks found in the stream (read-only on the node).
`onCurrentAudioTrack?`	`EventHandler<string>`	Fired when the playing audio track changes; carries the track identifier (`Track`).
`seamlessAudioTrackSelection?`	`boolean`	When true, continues video on audio track switch (HLS only; set before any control command).
`supplementaryAudioVolume?`	`number`	Description track volume vs main audio (0–100).

IVideoMiscProps

Decode resolution, output protection, and screensaver behavior.

Name	Type	Description
`cgms?`	`number`	CGMS level for analog outputs (0–3 per Roku docs).
`disableScreenSaver?`	`boolean`	Suppresses screensaver (e.g. audio-only).
`enableScreenSaverWhilePlaying?`	`boolean`	Allows screensaver when video covers less than half the screen.
`maxVideoDecodeResolution?`	`Vector2D`	Max decode resolution [width, height]; [0,0] means unlimited per axis.

AudioSelectionPreferenceRule

One rule object in audio selection preferences (ordered highest to lowest significance).

type AudioSelectionPreferenceRule = { language: string[] } | { descriptive: string | string[] };

DownloadedSegmentHdrMode

HDR mode enum for downloadedSegment info.

Member	Value	Description
`Unknown`	`0`
`None`	`1`
`Hdr10`	`2`
`DolbyVision`	`3`
`Hlg10`	`4`
`Hdr10Plus`	`5`
`SlHdr2`	`6`

StreamingSegmentHdrMode

HDR mode reported on streamingSegment (HLS/DASH).

Member	Value	Description
`Invalid`	`"invalid"`
`Unknown`	`"unknown"`
`None`	`"none"`
`Hdr10`	`"hdr10"`
`DolbyVision`	`"dolby_vision"`
`Hlg10`	`"hlg10"`
`SlHdr2`	`"sl-hdr2"`

StreamingSegmentType

Segment payload type from streamingSegment.segTypeStr.

Member	Value	Description
`Audio`	`"audio"`
`Video`	`"video"`
`Captions`	`"captions"`
`Mux`	`"mux"`

SubtitleSelectionPreferenceRule

One rule object in subtitle selection preferences (ordered highest to lowest significance).

type SubtitleSelectionPreferenceRule = { language: string[] } | { caption: string } | { descriptive: string | string[] } | { easyReader: string };

Updated about 4 hours ago

What’s Next

VideoContentNode

Did this page help you?