@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/sg-nodes/video.props.ts

@@ -0,0 +1,573 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { ComponentRef } from "@roku-sdk/interfaces";
+
+import type { MediaControl, MediaState } from "../types";
+import type { IGroupProps } from "./group.props";
+import type { INodeProps } from "./node";
+import type { EventHandler, JSX, Uri, Vector2D } from "./types";
+
+/**
+ * Seek accuracy for the Video node `seekMode` field.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export enum VideoSeekMode {
+    Default = "default",
+    Accurate = "accurate"
+}
+
+/**
+ * HDR mode reported on `streamingSegment` (HLS/DASH).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export enum StreamingSegmentHdrMode {
+    Invalid = "invalid",
+    Unknown = "unknown",
+    None = "none",
+    Hdr10 = "hdr10",
+    DolbyVision = "dolby_vision",
+    Hlg10 = "hlg10",
+    SlHdr2 = "sl-hdr2"
+}
+
+/**
+ * Segment payload type from `streamingSegment.segTypeStr`.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export enum StreamingSegmentType {
+    Audio = "audio",
+    Video = "video",
+    Captions = "captions",
+    Mux = "mux"
+}
+
+/** HDR mode enum for `downloadedSegment` info. */
+export const enum DownloadedSegmentHdrMode {
+    Unknown = 0,
+    None = 1,
+    Hdr10 = 2,
+    DolbyVision = 3,
+    Hlg10 = 4,
+    Hdr10Plus = 5,
+    SlHdr2 = 6
+}
+
+/**
+ * Global Roku closed-caption mode for the Video `globalCaptionMode` field.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export enum GlobalCaptionMode {
+    Off = "Off",
+    On = "On",
+    InstantReplay = "Instant replay",
+    WhenMute = "When mute"
+}
+
+/**
+ * Timing measurements related to the start of video playback (seconds unless noted).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IPlayStartInfo {
+    total_dur: number;
+    manifest_dur: number;
+    drm_load_dur: number;
+    drm_lic_acq_dur: number;
+    prebuf_dur: number;
+    manifest_start: number;
+    drm_load_start: number;
+    drm_lic_acq_start: number;
+    prebuf_start: number;
+}
+
+/**
+ * DRM license acquisition status from the Video node.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface ILicenseStatus {
+    response: string;
+    status: string;
+    keysystem: string;
+    duration: string;
+}
+
+/** Alias for {@link MediaControl} used by the Video node `control` field. */
+export type VideoControl = MediaControl;
+
+/** Alias for {@link MediaState} from the Video node `state` field. */
+export type VideoState = MediaState;
+
+/**
+ * Structured error information from the Video node `errorInfo` field.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface VideoErrorInfo {
+    clipId: number;
+    ignored: number;
+    source: string;
+    category: string;
+    errcode: number;
+    dbgmsg: string;
+    drmerrcode: number;
+}
+
+/**
+ * Video decoder statistics when {@link IVideoPlaybackProps.enableDecoderStats} is true.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IDecoderStats {
+    renderCount: number;
+    repeatCount: number;
+    frameDropCount: number;
+    streamErrorCount: number;
+}
+
+/**
+ * One playback action button on the pause screen.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IPlaybackActionButton {
+    text?: string;
+    icon?: Uri;
+    focusIcon?: Uri;
+    buttonIsDisabled?: boolean;
+}
+
+/**
+ * One rule object in subtitle selection preferences (ordered highest to lowest significance).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export type SubtitleSelectionPreferenceRule =
+    { language: string[] } | { caption: string } | { descriptive: string | string[] } | { easyReader: string };
+
+/**
+ * Subtitle track selection preferences (Roku OS 12.5+).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface ISubtitleSelectionPreferences {
+    values: SubtitleSelectionPreferenceRule[];
+    overrideSystem: boolean;
+}
+
+/**
+ * One rule object in audio selection preferences (ordered highest to lowest significance).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export type AudioSelectionPreferenceRule = { language: string[] } | { descriptive: string | string[] };
+
+/**
+ * Audio track selection preferences (Roku OS 12.5+).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IAudioSelectionPreferences {
+    values: AudioSelectionPreferenceRule[];
+    overrideSystem: boolean;
+}
+
+/**
+ * Playback-related fields for the Video node: content, control, errors, and DRM.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IVideoPlaybackProps {
+    /** ContentNode (or playlist parent) with content metadata for playback. */
+    content?: JSX.Element;
+    /** Fired when play-start timing info is updated. */
+    onPlayStartInfo?: EventHandler<IPlayStartInfo>;
+    /** Fired when DRM license status changes. */
+    onLicenseStatus?: EventHandler<ILicenseStatus>;
+    /** When true, children of `content` form a video playlist. */
+    contentIsPlaylist?: boolean;
+    /** Index of the current item in a playlist (or 0 for single content). */
+    onContentIndex?: EventHandler<number>;
+    /** Next playlist index to play after the current item ends or is skipped. */
+    nextContentIndex?: number;
+    /** Play state command (play, pause, stop, prebuffer, etc.). */
+    control?: VideoControl;
+    /**
+     * When true, STOP runs asynchronously (Roku OS 12.5+). `state` becomes `stopping` then `stopped`.
+     */
+    asyncStopSemantics?: boolean;
+    /** Fired when playback state changes (buffering, playing, error, etc.). */
+    onState?: EventHandler<VideoState>;
+    /** Fired when `errorCode` changes after an error state. */
+    onErrorCode?: EventHandler<number>;
+    /** Fired when `errorMsg` changes. */
+    onErrorMsg?: EventHandler<string>;
+    /** Fired when `errorStr` changes. */
+    onErrorStr?: EventHandler<string>;
+    /** Fired when structured `errorInfo` is updated. */
+    onErrorInfo?: EventHandler<VideoErrorInfo>;
+    /** Fired when decoder statistics are updated (requires `enableDecoderStats`). */
+    onDecoderStats?: EventHandler<IDecoderStats>;
+    /** When true, `decoderStats` is populated and updated. */
+    enableDecoderStats?: boolean;
+    /** Buttons and UI on the pause screen at start of playback. */
+    playbackActionButtons?: IPlaybackActionButton[];
+    /** Selected index in `playbackActionButtons`. */
+    playbackActionButtonSelected?: number;
+    /** Focused index in `playbackActionButtons`. */
+    playbackActionButtonFocused?: number;
+    /** Font for the focused playback action button label. */
+    playbackActionButtonFocusedTextFont?: string;
+    /** Font for unfocused playback action button labels. */
+    playbackActionButtonUnfocusedTextFont?: string;
+    /** Text color when the playback action button has focus. */
+    playbackActionButtonFocusedTextColor?: string;
+    /** Text color when the playback action button does not have focus. */
+    playbackActionButtonUnfocusedTextColor?: string;
+    /** Background blend color when the playback action button has focus. */
+    playbackActionButtonFocusIndicatorBlendColor?: string;
+    /** Subtitle track selection priority (write-only configuration). */
+    subtitleSelectionPreferences?: ISubtitleSelectionPreferences;
+    /** Audio track selection priority (write-only configuration). */
+    audioSelectionPreferences?: IAudioSelectionPreferences;
+}
+
+/**
+ * Position info for last rendered audio/video samples.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IPositionInfo {
+    audio: number;
+    clip_id: number;
+    epoch: number;
+    video: number;
+}
+
+/**
+ * Information about the video segment currently streaming (HLS/DASH).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IStreamingSegmentInfo {
+    hdrModeStr: StreamingSegmentHdrMode;
+    segBitrateBps: number;
+    segSequence: number;
+    segStart: number;
+    segUrl: string;
+    segType: number;
+    segTypeStr: StreamingSegmentType;
+    latency: number;
+    path: string;
+    width: number;
+    height: number;
+}
+
+/**
+ * Information about a segment that was just downloaded.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IDownloadedSegmentInfo {
+    status: number;
+    segSequence: number;
+    segUrl: string;
+    downloadDuration: number;
+    segSize: number;
+    segType: number;
+    bitrateBPS: number;
+    segStart: number;
+    segDuration: string;
+    path: string;
+    width: number;
+    height: number;
+    hdrMode: DownloadedSegmentHdrMode;
+}
+
+/**
+ * Trick play, seek, segments, and related timing fields.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface ITrickPlayProps {
+    /** Fired when stream duration is known or changes. */
+    onDuration?: EventHandler<number>;
+    /** When true, restarts playlist or single content after the end. */
+    loop?: boolean;
+    /** Fired on position updates (interval from `notificationInterval`). */
+    onPosition?: EventHandler<number>;
+    /** Fired with last rendered sample positions. */
+    onPositionInfo?: EventHandler<IPositionInfo>;
+    /** Fired when the current clip ID changes. */
+    onClipId?: EventHandler<number>;
+    /** Seconds between `position` observer notifications; 0 disables notifications. */
+    notificationInterval?: number;
+    /** Seek target in seconds from stream start (write-only). */
+    seek?: number;
+    /** Seek accuracy: default (keyframe) vs accurate (if supported). */
+    seekMode?: VideoSeekMode;
+    /** When false, disables auto-play after rebuffer following a seek. */
+    autoplayAfterSeek?: boolean;
+    /** Fired with info about the segment currently being streamed. */
+    onStreamingSegment?: EventHandler<IStreamingSegmentInfo>;
+    /** Fired when a segment download completes. */
+    onDownloadedSegment?: EventHandler<IDownloadedSegmentInfo>;
+    /**
+     * Keys for timed metadata (e.g. ID3); matching tags populate `timedMetaData` / `timedMetaData2`.
+     */
+    timedMetaDataSelectionKeys?: string[];
+    /** Enables trick play bar scrubbing within the live availability window. */
+    enableLiveAvailabilityWindow?: boolean;
+    /** When true, `thumbnailTiles` updates during live HLS/DASH with thumbnails. */
+    enableThumbnailTilesDuringLive?: boolean;
+    /**
+     * Thumbnail tile sets from the manifest (structure varies by OS version).
+     */
+    thumbnailTiles?: Record<string, unknown>;
+    /** Background overlay URI while playback UI is visible. */
+    trickPlayBackgroundOverlay?: Uri;
+}
+
+/**
+ * Built-in Video UI: dimensions, toggles, and internal bar/BIF/pivot nodes.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IVideoUiProps {
+    /** Video window width in pixels; 0 uses full display width. */
+    width?: number;
+    /** Video window height in pixels; 0 uses full display height. */
+    height?: number;
+    /** When false, hides most built-in UI (app implements custom UI). */
+    enableUI?: boolean;
+    /** When false, remote trick play keys have no effect (requires `enableUI`). */
+    enableTrickPlay?: boolean;
+    /** BIF display sub-node instance. */
+    bifDisplay?: JSX.Element;
+    /** Trick play bar sub-node instance. */
+    trickPlayBar?: JSX.Element;
+    /** Buffering progress bar sub-node instance. */
+    bufferingBar?: JSX.Element;
+    /** Text color near the buffering bar (0 = system default). */
+    bufferingTextColor?: string;
+    /** Initial retrieve progress bar sub-node instance. */
+    retrievingBar?: JSX.Element;
+    /** Text color near the retrieving bar (0 = system default). */
+    retrievingTextColor?: string;
+    /** Pivot renderable shown when video is paused. */
+    pivotNode?: JSX.Element;
+}
+
+/**
+ * Closed caption and subtitle styling fields.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IVideoCaptionProps {
+    /** Global caption mode; app should still set `subtitleTrack` as needed. */
+    globalCaptionMode?: GlobalCaptionMode;
+    /** Suppresses captions when resolving UI overlap conflicts. */
+    suppressCaptions?: boolean;
+    /** Selected subtitle track identifier (read/write). */
+    subtitleTrack?: string;
+    /**
+     * Caption styling keys (Text/Font, Text/Size, Background/Color, etc.) per Roku docs.
+     */
+    captionStyle?: Record<string, string>;
+}
+
+/**
+ * Audio output and track selection fields.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IVideoAudioProps {
+    /** Mutes or restores audio for the current stream. */
+    mute?: boolean;
+    /** Selected audio track identifier (prefer platform selection when possible). */
+    audioTrack?: string;
+    /**
+     * When true, continues video on audio track switch (HLS only; set before any control command).
+     */
+    seamlessAudioTrackSelection?: boolean;
+    /** Description track volume vs main audio (0–100). */
+    supplementaryAudioVolume?: number;
+}
+
+/**
+ * Decode resolution, output protection, and screensaver behavior.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IVideoMiscProps {
+    /**
+     * Max decode resolution [width, height]; [0,0] means unlimited per axis.
+     */
+    maxVideoDecodeResolution?: Vector2D;
+    /** CGMS level for analog outputs (0–3 per Roku docs). */
+    cgms?: number;
+    /** Allows screensaver when video covers less than half the screen. */
+    enableScreenSaverWhilePlaying?: boolean;
+    /** Suppresses screensaver (e.g. audio-only). */
+    disableScreenSaver?: boolean;
+}
+
+/**
+ * All Video node props: extends Group with playback, trick play, UI, captions, audio, and misc fields.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IVideoProps
+    extends
+        IGroupProps,
+        IVideoPlaybackProps,
+        ITrickPlayProps,
+        IVideoUiProps,
+        IVideoCaptionProps,
+        IVideoAudioProps,
+        IVideoMiscProps {}
+
+/**
+ * Handle for imperative control of a {@link Video} component, obtained via the `ref` prop.
+ *
+ * Extends {@link ComponentRef} with convenience methods that map to
+ * {@link VideoControl} values, so you can drive playback without manually
+ * setting the `control` prop.
+ *
+ * @example
+ * ```tsx
+ * import { Button, Video, VideoRef } from "@roku-sdk/components";
+ *
+ * const Player = () => {
+ *   let videoRef!: VideoRef;
+ *
+ *   return (
+ *     <>
+ *       <Button text="Play" onButtonSelected={() => videoRef.play()} />
+ *       <Video
+ *         ref={videoRef}
+ *         width={1920}
+ *         height={1080}
+ *         content={<ContentNode url="https://example.com/stream.m3u8" />}
+ *       />
+ *     </>
+ *   );
+ * };
+ * ```
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface VideoRef extends ComponentRef<IVideoProps> {
+    /**
+     * Begin playback of the video specified by `content`. Equivalent to setting
+     * `control="play"`. The node transitions through `buffering` to `playing`,
+     * which is observable via {@link IVideoPlaybackProps.onState}.
+     */
+    play: () => void;
+    /**
+     * Pause playback while preserving the current position. Equivalent to setting
+     * `control="pause"`. Use {@link VideoRef.resume} to continue from where it
+     * paused. Has no effect when not currently `playing`.
+     */
+    pause: () => void;
+    /**
+     * Stop playback and release the video stream. Equivalent to setting
+     * `control="stop"`. With {@link IVideoPlaybackProps.asyncStopSemantics} true
+     * (Roku OS 12.5+) the state transitions through `stopping` to `stopped`;
+     * otherwise the transition to `stopped` is synchronous.
+     */
+    stop: () => void;
+    /**
+     * Resume playback after a {@link VideoRef.pause}. Equivalent to setting
+     * `control="resume"`. Has no effect when the node is not in the `paused`
+     * state.
+     */
+    resume: () => void;
+    /**
+     * Restart the current video (or playlist) from the beginning. Equivalent to
+     * setting `control="replay"`.
+     */
+    replay: () => void;
+    /**
+     * Pre-buffer the video without starting playback. Equivalent to setting
+     * `control="prebuffer"`. Useful to reduce time-to-first-frame when playback
+     * is started later via {@link VideoRef.play}.
+     */
+    prebuffer: () => void;
+    /**
+     * Skip to the next item in a playlist. Equivalent to setting
+     * `control="skipcontent"`. Only meaningful when
+     * {@link IVideoPlaybackProps.contentIsPlaylist} is true.
+     */
+    skipcontent: () => void;
+    /**
+     * Seek to a specific position in the current video. Equivalent to setting
+     * the {@link ITrickPlayProps.seek} prop. Seek accuracy is governed by
+     * {@link ITrickPlayProps.seekMode}, and auto-play after rebuffer can be
+     * disabled via {@link ITrickPlayProps.autoplayAfterSeek}.
+     *
+     * @param position Target position in seconds from the start of the stream.
+     */
+    seekTo: (position: number) => void;
+    /**
+     * Set the index of the next video in the playlist to be played.
+     * @param index The index of the next video in the playlist.
+     */
+    setNextContentIndex: (index: number) => void;
+}
+
+/**
+ * BIF (trick play image) display sub-component fields on Video.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IBifDisplayProps extends INodeProps {
+    /** Blend color for the frame background behind BIF images. */
+    frameBgBlendColor?: string;
+    /** URI of image behind individual BIF frames. */
+    frameBgImageUri?: Uri;
+    /**
+     * Request nearest BIF to this time offset (seconds); write-only.
+     */
+    getNearestFrame?: number;
+    /** URI of the requested BIF (e.g. memory://BIF_…). */
+    onNearestFrame?: EventHandler<string>;
+}
+
+/**
+ * Trick play bar appearance fields.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface ITrickPlayBarProps extends INodeProps {
+    currentTimeMarkerBlendColor?: string;
+    textColor?: string;
+    thumbBlendColor?: string;
+    filledBarBlendColor?: string;
+    liveFilledBarBlendColor?: string;
+    filledBarImageUri?: Uri;
+    trackBlendColor?: string;
+    trackImageUri?: Uri;
+}
+
+/**
+ * Progress bar fields used for buffering and retrieving indicators on Video.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IProgressBarProps extends INodeProps {
+    width?: number;
+    height?: number;
+    emptyBarBlendColor?: string;
+    emptyBarImageUri?: Uri;
+    filledBarBlendColor?: string;
+    filledBarImageUri?: Uri;
+    trackBlendColor?: string;
+    trackImageUri?: Uri;
+    percentage?: number;
+}

package/src/sg-nodes/video.tsx

@@ -0,0 +1,73 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { registerImperativeMethods } from "@roku-sdk/solid";
+
+import type { IBifDisplayProps, IProgressBarProps, ITrickPlayBarProps, IVideoProps } from "./video.props";
+export { VideoSeekMode, StreamingSegmentHdrMode, StreamingSegmentType, GlobalCaptionMode } from "./video.props";
+
+export type {
+    IPlayStartInfo,
+    ILicenseStatus,
+    VideoControl,
+    VideoState,
+    VideoErrorInfo,
+    IDecoderStats,
+    IPlaybackActionButton,
+    SubtitleSelectionPreferenceRule,
+    ISubtitleSelectionPreferences,
+    AudioSelectionPreferenceRule,
+    IAudioSelectionPreferences,
+    IVideoPlaybackProps,
+    IPositionInfo,
+    IStreamingSegmentInfo,
+    IDownloadedSegmentInfo,
+    ITrickPlayProps,
+    IVideoUiProps,
+    IVideoCaptionProps,
+    IVideoAudioProps,
+    IVideoMiscProps,
+    IVideoProps,
+    VideoRef,
+    IBifDisplayProps,
+    ITrickPlayBarProps,
+    IProgressBarProps
+} from "./video.props";
+
+import { mediaPlaybackMethods } from "./media-playback-methods";
+import { Component } from "./types";
+
+export { DownloadedSegmentHdrMode } from "./video.props";
+
+registerImperativeMethods("video", mediaPlaybackMethods);
+
+/**
+ * Video provides controlled playback of live or VOD content with optional built-in UI, trick play,
+ * and captions.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ *
+ * @example
+ * <video
+ *   width={1280}
+ *   height={720}
+ *   content={<VideoContentNode url={url} />}
+ *   control="play"
+ *   onState={state => console.log(state)}
+ * />
+ */
+export const Video: Component<IVideoProps> = props => {
+    return <video {...props}></video>;
+};
+
+export const BifDisplay: Component<IBifDisplayProps> = props => {
+    return <bifDisplay {...props}></bifDisplay>;
+};
+
+export const TrickPlayBar: Component<ITrickPlayBarProps> = props => {
+    return <trickPlayBar {...props}></trickPlayBar>;
+};
+
+export const ProgressBar: Component<IProgressBarProps> = props => {
+    return <progressBar {...props}></progressBar>;
+};