@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/sg-nodes/content-node.props.ts

@@ -0,0 +1,1316 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { INodeProps } from "./node";
+
+/**
+ * Content type values that affect how the title is displayed on screen.
+ *
+ * The return value on the Roku platform is of type `number`, but the value is set as a string.
+ */
+export enum ContentType {
+    /** Movie content. */
+    Movie = "movie",
+    /** TV series content. */
+    Series = "series",
+    /** Season of a TV series. */
+    Season = "season",
+    /** Episode of a TV series. */
+    Episode = "episode",
+    /** Audio-only content. */
+    Audio = "audio"
+}
+
+/**
+ * MPAA or TV rating values displayed as icon artwork at runtime.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#rating-attribute-icons}
+ */
+export enum Rating {
+    G = "G",
+    NC17 = "NC-17",
+    PG = "PG",
+    PG13 = "PG-13",
+    R = "R",
+    UR = "UR",
+    Unrated = "UNRATED",
+    NR = "NR",
+    TVY = "TV-Y",
+    TVY7 = "TV-Y7",
+    TVY7FV = "TV-Y7-FV",
+    TVG = "TV-G",
+    TVPG = "TV-PG",
+    TV14 = "TV-14",
+    TVMA = "TV-MA"
+}
+
+/** Stream format identifiers for content playback. */
+export enum StreamFormat {
+    /** MP4 container format. Also accepts `.mov` and `.m4v` files. */
+    Mp4 = "mp4",
+    /** HTTP Live Streaming. */
+    Hls = "hls",
+    /** Smooth Streaming. */
+    Ism = "ism",
+    /** MPEG-DASH. */
+    Dash = "dash",
+    /** Matroska Video. */
+    Mkv = "mkv",
+    /** Matroska Audio. */
+    Mka = "mka",
+    /** Matroska Subtitles. */
+    Mks = "mks",
+    /** MP3 audio. */
+    Mp3 = "mp3"
+}
+
+/** Live bounds pause behavior for live streams. */
+export enum LiveBoundsPauseBehavior {
+    /** Default behavior — resumes playback. */
+    Resume = "resume",
+    /** Stops playback. */
+    Stop = "stop",
+    /** Keeps stream paused even in the earliest part of the buffer. */
+    Pause = "pause"
+}
+
+/** Stream quality indicator. */
+export enum StreamQuality {
+    /** Standard definition. */
+    SD = "SD",
+    /** High definition. */
+    HD = "HD"
+}
+
+/** Preferred audio codec for playback. */
+export enum PreferredAudioCodec {
+    /** Advanced Audio Coding. */
+    AAC = "aac",
+    /** Dolby Digital (AC-3). */
+    AC3 = "ac3",
+    /** Dolby Digital Plus (Enhanced AC-3). */
+    EAC3 = "eac3"
+}
+
+/** PlayReady DRM encoding type. */
+export enum PlayReadyEncodingType {
+    /** PlayReady license acquisition URL. */
+    LicenseAcquisitionUrl = "PlayReadyLicenseAcquisitionUrl",
+    /** PlayReady license acquisition URL plus additional custom request data. */
+    LicenseAcquisitionAndChallenge = "PlayReadyLicenseAcquisitionAndChallenge"
+}
+
+/** DRM key system identifier. */
+export enum DrmKeySystem {
+    /** Microsoft PlayReady DRM. */
+    PlayReady = "playready",
+    /** Google Widevine DRM. */
+    Widevine = "widevine"
+}
+
+/**
+ * DRM license request template type.
+ *
+ * @since Roku OS 14.6
+ */
+export enum DrmTemplateType {
+    /** License request template is in JSON format. */
+    JSON = "JSON",
+    /** License request template is in XML format. */
+    XML = "XML",
+    /** Base64-encodes the challenge and sends it in POST body. Does not use `licReqTemplate`. */
+    BASE64 = "BASE64"
+}
+
+/**
+ * Content classifier values that map to sound and picture modes on Roku TVs.
+ *
+ * | Value         | Sound Mode | Picture Mode |
+ * |---------------|------------|-------------|
+ * | `"action"`    | Movie      | Movie       |
+ * | `"sports"`    | Standard   | Sports      |
+ * | `"comedy"`    | Movie      | Movie       |
+ * | `"drama"`     | Movie      | Movie       |
+ * | `"music"`     | Music      | Standard    |
+ * | `"music:lyrics"` | Music  | Low Power   |
+ * | `"news"`      | Dialog     | Vivid       |
+ * | `"podcast"`   | Dialog     | Low Power   |
+ * | `"animated"`  | Movie      | Vivid       |
+ * | `"black+white"` | Movie   | Standard    |
+ * | `"nature"`    | Standard   | Vivid       |
+ * | `"reality"`   | Standard   | Standard    |
+ */
+export enum ContentClassifier {
+    /** Action genre. Sound: Movie, Picture: Movie. */
+    Action = "action",
+    /** Animated content. Sound: Movie, Picture: Vivid. */
+    Animated = "animated",
+    /** Black and white content. Sound: Movie, Picture: Standard. */
+    BlackWhite = "black+white",
+    /** Comedy genre. Sound: Movie, Picture: Movie. */
+    Comedy = "comedy",
+    /** Drama genre. Sound: Movie, Picture: Movie. */
+    Drama = "drama",
+    /** Music content. Sound: Music, Picture: Standard. */
+    Music = "music",
+    /** Music with lyrics. Sound: Music, Picture: Low Power. */
+    MusicLyrics = "music:lyrics",
+    /** Nature content. Sound: Standard, Picture: Vivid. */
+    Nature = "nature",
+    /** News content. Sound: Dialog, Picture: Vivid. */
+    News = "news",
+    /** Podcast (audio only). Sound: Dialog, Picture: Low Power. */
+    Podcast = "podcast",
+    /** Reality content. Sound: Standard, Picture: Standard. */
+    Reality = "reality",
+    /** Sports content. Sound: Standard, Picture: Sports. */
+    Sports = "sports"
+}
+
+/**
+ * Descriptive metadata attributes for content items.
+ *
+ * These attributes describe the content item to the user in UI elements that allow
+ * the user to select the item — such as titles, descriptions, artwork, ratings, and credits.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#descriptive-attributes}
+ */
+export interface IDescriptiveAttributes {
+    /**
+     * Content type identifier. Although ContentType accepts a string, the return value on
+     * the Roku platform is of type `number`.
+     *
+     * | Content Type           | Return Value |
+     * |------------------------|--------------|
+     * | movie                  | 1            |
+     * | series                 | 2            |
+     * | season                 | 3            |
+     * | episode                | 4            |
+     * | audio                  | 5            |
+     * | not set or unsupported | 0            |
+     *
+     * @see {@link https://developer.roku.com/dev/docs/content-metadata#descriptive-attributes}
+     * @example "movie"
+     */
+    contentType?: ContentType | string;
+
+    /**
+     * Content title: movie title for films; episode title for TV series.
+     *
+     * @example "The Dark Knight"
+     */
+    title?: string;
+
+    /**
+     * Season title for TV series.
+     *
+     * @example "Battlestar Galactica Season 5"
+     */
+    titleSeason?: string;
+
+    /**
+     * Secondary title for the video content.
+     *
+     * @example "2022"
+     */
+    secondaryTitle?: string;
+
+    /**
+     * An opaque, unique identifier for the content the app is playing. Each movie, episode,
+     * or other content should have a different program ID value. This identifier is used to
+     * debug content-specific playback issues. Roku will reference this programID in playback
+     * error reports, allowing developers to identify the content that failed to play.
+     *
+     * @example "54b2f1ae-a0e9-46e0-a4d7-47b4e00e9c15"
+     */
+    programID?: string;
+
+    /**
+     * Description of content.
+     *
+     * @example "Batman, Gordon and Harvey Dent are forced…"
+     */
+    description?: string;
+
+    /**
+     * URL for SD content artwork.
+     *
+     * @example "mysite.com/img/sd1932.jpg"
+     */
+    sdPosterUrl?: string;
+
+    /**
+     * URL for HD content artwork.
+     *
+     * @example "mysite.com/img/hd1932.jpg"
+     */
+    hdPosterUrl?: string;
+
+    /**
+     * URL for FHD content artwork.
+     *
+     * @example "mysite.com/img/fhd1932.jpg"
+     */
+    fhdPosterUrl?: string;
+
+    /**
+     * Formatted date string for the content release date.
+     *
+     * @example "3/31/2009"
+     */
+    releaseDate?: string;
+
+    /**
+     * Selects an icon to be displayed for the corresponding MPAA or TV rating.
+     * The value will display as icon artwork at runtime.
+     *
+     * Valid values include: `"G"`, `"PG"`, `"PG-13"`, `"R"`, `"NC-17"`, `"UR"`, `"UNRATED"`, `"NR"`,
+     * `"TV-Y"`, `"TV-Y7"`, `"TV-Y7-FV"`, `"TV-G"`, `"TV-PG"`, `"TV-14"`, `"TV-MA"`.
+     *
+     * @example "PG-13"
+     */
+    rating?: Rating | string;
+
+    /**
+     * Specifies the star rating to display as red star icon artwork, as a number from 1 to 100.
+     * - 20 → one star
+     * - 40 → two stars
+     * - 60 → three stars
+     * - 80 → four stars
+     * - 100 → five stars
+     *
+     * Numbers not divisible by 20 are displayed as a fractional star (e.g. 30 → one and a half stars).
+     *
+     * @example 80
+     */
+    starRating?: number;
+
+    /**
+     * Specifies the user star rating to display as yellow star icon artwork, as a number from 1 to 100.
+     * - 20 → one star
+     * - 40 → two stars
+     * - 60 → three stars
+     * - 80 → four stars
+     * - 100 → five stars
+     *
+     * Does not display fractional stars for numbers not divisible by 20.
+     *
+     * @example 80
+     */
+    userStarRating?: number;
+
+    /**
+     * Line 1 of Poster Screen Description.
+     *
+     * @example "The Dark Knight"
+     */
+    shortDescriptionLine1?: string;
+
+    /**
+     * Line 2 of Poster Screen Description.
+     *
+     * @example "Rent $1.99, Buy $14.99"
+     */
+    shortDescriptionLine2?: string;
+
+    /**
+     * Episode number.
+     *
+     * @example "1"
+     */
+    episodeNumber?: string;
+
+    /**
+     * Number of episodes for a "season" or "series" contentType.
+     *
+     * @example 40
+     */
+    numEpisodes?: number;
+
+    /**
+     * List of actor names, or an individual actor name.
+     *
+     * @example ["Brad Pitt", "Angelina Jolie"]
+     * @example "Brad Pitt"
+     */
+    actors?: string | string[];
+
+    /**
+     * List of director names.
+     *
+     * @example ["Joel Coen", "Clint Eastwood"]
+     */
+    directors?: string[];
+
+    /**
+     * List of category/genre names, or an individual category/genre name.
+     *
+     * @example ["Comedy", "Drama"]
+     * @example "Comedy"
+     */
+    categories?: string | string[];
+
+    /**
+     * Album name. Used by roSpringboard audio style to display the album.
+     *
+     * @example "Achtung"
+     */
+    album?: string;
+
+    /**
+     * Artist name. Used by roSpringboard audio style to show artist.
+     *
+     * @example "U2"
+     */
+    artist?: string;
+
+    /** Text content. */
+    text?: string;
+
+    /**
+     * Text displayed in the upper left corner of roSlideShow slides.
+     *
+     * @example "Joe's Photos"
+     */
+    textOverlayUL?: string;
+
+    /**
+     * Text displayed in the upper right corner of roSlideShow slides.
+     *
+     * @example "3 of 20"
+     */
+    textOverlayUR?: string;
+
+    /**
+     * Text displayed on the bottom part of roSlideShow slides.
+     *
+     * @example "Wanda's 40th Birthday"
+     */
+    textOverlayBody?: string;
+}
+
+/**
+ * Stream entry configuration for specifying stream settings.
+ *
+ * Used by `stream` (single adaptive stream) and `streams` (array of fixed bitrate streams).
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#playback-configuration-attributes}
+ *
+ * @example
+ * ```typescript
+ * // Single adaptive stream (e.g., HLS)
+ * const stream: IStreamEntry = {
+ *     url: "http://example.com/stream.m3u8",
+ *     quality: true,
+ *     contentId: "hls-stream"
+ * };
+ *
+ * // Fixed bitrate stream variant
+ * const variant: IStreamEntry = {
+ *     url: "http://example.com/video-500.mp4",
+ *     bitrate: 500,
+ *     quality: false,
+ *     contentId: "mp4-500"
+ * };
+ * ```
+ */
+export interface IStreamEntry {
+    /**
+     * URL of the stream.
+     *
+     * @example "http://example.com/stream.m3u8"
+     */
+    url: string;
+
+    /**
+     * Bitrate of the stream in kbps. Used for fixed bitrate streams.
+     *
+     * @example 500
+     */
+    bitrate?: number;
+
+    /**
+     * Quality indicator. `true` for HD quality, `false` for SD.
+     *
+     * @example true
+     */
+    quality?: boolean;
+
+    /**
+     * Content identifier logged in Roku logs to identify the stream and bitrate played.
+     *
+     * @example "my-stream-500"
+     */
+    contentId?: string;
+}
+
+/**
+ * Subtitle track configuration for specifying available caption tracks.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#playback-configuration-attributes}
+ */
+export interface ISubtitleTrack {
+    /**
+     * ISO 639.2B 3-character language code.
+     * Used to match the caption track with the audio language.
+     *
+     * @example "eng"
+     * @example "spa"
+     */
+    Language: string;
+
+    /**
+     * Text shown for the corresponding track in the closed caption configuration dialog.
+     *
+     * @example "English"
+     * @example "Spanish (CC)"
+     */
+    Description: string;
+
+    /**
+     * Track name or URL for sideloaded caption tracks.
+     *
+     * For in-stream captions, this is the track name (e.g., `"mkv/english1"`).
+     * For sideloaded captions, this is the URL where the caption file can be downloaded.
+     * Supported sideloaded formats: srt, ttml, dfxp.
+     *
+     * @example "mkv/english1"
+     * @example "https://example.com/captions/en.srt"
+     */
+    TrackName: string;
+}
+
+/** Valid subtitle track source identifiers. */
+export type SubtitleTrackSource = "ism" | "mkv" | "eia608" | "dvb";
+
+/**
+ * Subtitle track name in the format `"source/trackId"`.
+ *
+ * @example "mkv/english1"
+ * @example "dvb/eng_sdh"
+ * @example "eia608/1"
+ */
+export type SubtitleTrackName = `${SubtitleTrackSource}/${string}`;
+
+/**
+ * Playback configuration metadata attributes for content items.
+ *
+ * These attributes configure the playback of the content item, including stream URLs,
+ * format, subtitles, trick play, and adaptive bitrate settings.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#playback-configuration-attributes}
+ */
+export interface IPlaybackConfigurationAttributes {
+    /**
+     * Optional flag indicating video is live.
+     * Replaces time remaining in progress bar to display "Live".
+     *
+     * @default false
+     */
+    live?: boolean;
+
+    /**
+     * Stream URL for Scene Graph Video node.
+     *
+     * @example "mysite.com/vid/vacation.mp4"
+     */
+    url?: string;
+
+    /**
+     * BIF URL for SD trick mode.
+     *
+     * @example "mysite.com/bif/sd1932.bif"
+     */
+    sdBifUrl?: string;
+
+    /**
+     * BIF URL for HD trick mode.
+     *
+     * @example "mysite.com/bif/hd1932.bif"
+     */
+    hdBifUrl?: string;
+
+    /**
+     * URL for an HD small icon image. Used by TimeGrid to display channel icons.
+     *
+     * @see {@link https://developer.roku.com/dev/docs/timegrid}
+     * @example "mysite.com/img/hd_icon_ch5.png"
+     */
+    hdSmallIconUrl?: string;
+
+    /**
+     * BIF URL for FHD trick mode.
+     *
+     * @example "mysite.com/bif/fhd1932.bif"
+     */
+    fhdBifUrl?: string;
+
+    /**
+     * Stream settings for a single adaptive stream (e.g., HLS or Smooth Streaming manifest).
+     *
+     * Supported by roVideoPlayer and roVideoScreen, but not the Roku Scene Graph Video node
+     * (use the top level `url`, `streamFormat`, etc. instead).
+     *
+     * The exception is when you don't have adaptive streams (typically MP4) and need to specify
+     * different bitrate variants separately — for that use case use the `streams` attribute.
+     *
+     * @example
+     * ```typescript
+     * stream: {
+     *     url: "http://example.com/stream.m3u8",
+     *     quality: true,
+     *     contentId: "hls-main"
+     * }
+     * ```
+     */
+    stream?: IStreamEntry;
+
+    /**
+     * Array of stream entries used to specify content metadata for a set of fixed bitrate streams.
+     * Each array item specifies the URL, bitrate, etc. for one stream variant.
+     *
+     * Recommended for non-adaptive video (such as MP4 progressive download) only.
+     * For adaptive streaming, use the `stream` attribute instead.
+     *
+     * @example
+     * ```typescript
+     * streams: [
+     *     { url: "http://example.com/video-384.mp4", bitrate: 384, quality: false, contentId: "mp4-384" },
+     *     { url: "http://example.com/video-2500.mp4", bitrate: 2500, quality: true, contentId: "mp4-2500" }
+     * ]
+     * ```
+     */
+    streams?: IStreamEntry[];
+
+    /**
+     * Array of bitrates in kbps for content streams. Recommended for non-adaptive video
+     * (such as MP4 progressive download) only.
+     * Must be used in conjunction with `streamUrls` and `streamQualities`.
+     *
+     * @example [384, 500, 1000, 1500]
+     */
+    streamBitrates?: number[];
+
+    /**
+     * Array of URLs for content streams. Recommended for non-adaptive video
+     * (such as MP4 progressive download) only.
+     * Must be used in conjunction with `streamBitrates` and `streamQualities`.
+     */
+    streamUrls?: string[];
+
+    /**
+     * Array of quality indicators identifying a stream as "SD" or "HD".
+     * Must be used in conjunction with `streamBitrates` and `streamUrls`.
+     *
+     * @example ["SD", "SD", "SD", "HD"]
+     */
+    streamQualities?: StreamQuality[];
+
+    /**
+     * Array of string values logged in Roku logs to identify stream and bitrate played.
+     *
+     * @example ["myco-19321-384.mp4", "myco-19321-500.mp4"]
+     */
+    streamContentIDs?: string[];
+
+    /**
+     * Array of boolean values indicating if the HTTP endpoint should be sticky and not
+     * subject to change on subsequent requests.
+     *
+     * @default false (for each entry)
+     */
+    streamStickyHttpRedirects?: boolean[];
+
+    /**
+     * The offset into the stream which is considered the beginning of playback. Time in seconds.
+     *
+     * @default 0
+     * @example 3600
+     */
+    streamStartTimeOffset?: number;
+
+    /**
+     * Type of content stream format.
+     *
+     * Valid values: `"mp4"`, `"hls"`, `"ism"` (smooth streaming), `"dash"` (MPEG-DASH),
+     * `"mkv"`, `"mka"`, `"mks"`, `"mp3"`.
+     *
+     * The `"mp4"` format also accepts `.mov` and `.m4v` files.
+     */
+    streamFormat?: StreamFormat | string;
+
+    /**
+     * Movie length in seconds. Length zero displays as "0m"; length not set will not display.
+     *
+     * @example 3600
+     */
+    length?: number;
+
+    /**
+     * Defines the start position of the content, in seconds.
+     * Starting from Roku OS 8.0, supports negative values, allowing media players
+     * to start playback distanced from the edge of a live stream.
+     *
+     * @default 0
+     */
+    playStart?: number;
+
+    /**
+     * Specifies the duration of a content item in seconds.
+     * Used by TimeGrid to determine the width of program cells.
+     *
+     * @default 0
+     */
+    playDuration?: number;
+
+    /**
+     * Boolean indicating if CC (closed captioning) icon should be displayed.
+     */
+    closedCaptions?: boolean;
+
+    /**
+     * Boolean indicating if HD branding should be displayed.
+     */
+    hdBranded?: boolean;
+
+    /**
+     * Boolean indicating if content is HD.
+     */
+    isHD?: boolean;
+
+    /**
+     * Specifies the color to use when rendering subtitle text.
+     *
+     * @example "#FF0000"
+     */
+    subtitleColor?: string;
+
+    /**
+     * Specifies the caption settings for content playback.
+     * `TrackName` sets the name of the caption track to render as a concatenation
+     * of the track source and track id separated by a "/".
+     *
+     * Valid track sources: `"ism"`, `"mkv"`, `"eia608"`, `"dvb"`.
+     *
+     * @example { TrackName: "mkv/english1" }
+     */
+    subtitleConfig?: { TrackName: SubtitleTrackName };
+
+    /**
+     * Sets the list of available caption tracks for the stream.
+     * This list is added to the track list in the closed caption configuration dialog
+     * that is displayed during video playback when the user presses the Roku remote * button.
+     *
+     * The Roku OS detects in-stream captions automatically, so specifying `subtitleTracks`
+     * is generally only needed for sideloaded captions.
+     *
+     * @example
+     * ```typescript
+     * subtitleTracks: [
+     *     { Language: "eng", Description: "English", TrackName: "https://example.com/captions/en.srt" },
+     *     { Language: "spa", Description: "Spanish", TrackName: "https://example.com/captions/es.srt" }
+     * ]
+     * ```
+     */
+    subtitleTracks?: ISubtitleTrack[];
+
+    /**
+     * Path to an SRT or TTML formatted file used to render subtitles or closed captions.
+     * Supported on roVideoScreen only.
+     *
+     * @example "mysite.com/vid/1932.srt"
+     */
+    subtitleUrl?: string;
+
+    /**
+     * If set to true, hides the Scene Graph Video node trick play UI.
+     *
+     * @default false
+     */
+    videoDisableUI?: boolean;
+
+    /**
+     * Specifies the encoding scheme for PlayReady DRM.
+     *
+     * Valid values: `"PlayReadyLicenseAcquisitionUrl"`, `"PlayReadyLicenseAcquisitionAndChallenge"`.
+     */
+    encodingType?: PlayReadyEncodingType | string;
+
+    /**
+     * Specifies the PlayReady license acquisition URL and additional custom request data,
+     * determined by the `encodingType` value specified.
+     */
+    encodingKey?: string;
+
+    /**
+     * Specifies different stream switching algorithms for HLS adaptive streaming.
+     * Only has an effect on HLS streams.
+     *
+     * @default "full-adaptation"
+     */
+    switchingStrategy?: string;
+
+    /**
+     * Flag indicating if content has been watched.
+     */
+    watched?: boolean;
+
+    /**
+     * Controls whether query string parameters from initial HLS stream manifest requests
+     * are forwarded to subsequent segment download requests.
+     *
+     * @default true
+     */
+    forwardQueryStringParams?: boolean;
+
+    /**
+     * Controls whether query string parameters from initial DASH stream manifest requests
+     * are forwarded to subsequent segment download requests.
+     *
+     * @default false
+     */
+    forwardDashQueryStringParams?: boolean;
+
+    /**
+     * When set to true, the media player will not stop playback when it encounters a
+     * streaming-related error. Instead, it will skip to the next item in the content list.
+     *
+     * @default false
+     */
+    ignoreStreamErrors?: boolean;
+
+    /**
+     * Minimum startup bitrate specified in kbps. Streaming will start with a variant
+     * equal to or greater than this value.
+     * If not set or set to zero, any minimum start bitrate will be ignored.
+     */
+    adaptiveMinStartBitrate?: number;
+
+    /**
+     * Maximum startup bitrate specified in kbps. Streaming will start with a variant
+     * less than or equal to this value.
+     *
+     * @default 2500
+     */
+    adaptiveMaxStartBitrate?: number;
+
+    /**
+     * Filters out any video profile/codec level combinations that the specified hardware
+     * cannot play. Currently only works for DASH streams.
+     *
+     * @default false
+     */
+    filterCodecProfiles?: boolean;
+
+    /**
+     * Allows an app to customize Media Player behavior on live streams when playing in
+     * the earliest part of a DVR buffer.
+     *
+     * - `"resume"`: Default behavior.
+     * - `"stop"`: Stops playback.
+     * - `"pause"`: Keeps stream paused even in the earliest part of the buffer.
+     *
+     * Currently works only with Smooth and DASH streams.
+     *
+     * @default "resume"
+     * @since Roku OS 8.1
+     */
+    liveBoundsPauseBehavior?: LiveBoundsPauseBehavior;
+
+    /**
+     * Sets the clip start position of the playback, in seconds.
+     *
+     * @since Roku OS 8.1
+     */
+    clipStart?: number;
+
+    /**
+     * Sets the clip end position of the playback, in seconds.
+     *
+     * @since Roku OS 8.1
+     */
+    clipEnd?: number;
+
+    /**
+     * Specifies the audio codec that should be used during playback.
+     * The Media Player will select only audio renditions encoded with the specified codec.
+     *
+     * Valid values: `"aac"`, `"ac3"`, `"eac3"`.
+     */
+    preferredAudioCodec?: PreferredAudioCodec | string;
+
+    /**
+     * Comma-separated list of audio tracks (based on ISO 639-1 or ISO 639-2 language code)
+     * that may be selected from the Audio track setting for the content.
+     *
+     * @example "en, spa"
+     */
+    audioWhitelist?: string;
+
+    /**
+     * Comma-separated list of audio tracks (based on ISO 639-1 or ISO 639-2 language code)
+     * that may not be selected from the Audio track setting for the content.
+     * If a language is both blacklisted and whitelisted, the blacklisting takes precedence.
+     *
+     * @since Roku OS 9.4
+     * @example "ita, fr"
+     */
+    audioBlacklist?: string;
+
+    /**
+     * Comma-separated list of captioning tracks (based on ISO 639-2 language code)
+     * that may be selected from the Accessibility > Captioning track setting for the content.
+     *
+     * @example "en, spa"
+     */
+    captionWhitelist?: string;
+
+    /**
+     * Comma-separated list of captioning tracks (based on ISO 639-2 language code)
+     * that may not be selected from the Accessibility > Captioning track setting for the content.
+     * If a language is both blacklisted and whitelisted, the blacklisting takes precedence.
+     *
+     * @since Roku OS 9.4
+     * @example "deu, dan"
+     */
+    captionBlacklist?: string;
+}
+
+/**
+ * DRM parameters passed via the `drmParams` content metadata attribute.
+ *
+ * Not all attributes are required, and may not have the same semantic meaning
+ * when applied to different DRM systems.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#digital-rights-management-drm-control-attributes}
+ */
+export interface IDrmParams {
+    /**
+     * The DRM key system to use. This value is case-insensitive.
+     *
+     * @example "playready"
+     * @example "widevine"
+     */
+    keySystem: DrmKeySystem | string;
+
+    /**
+     * URL location of a license server. May include CGI parameters.
+     * Required for both PlayReady and Widevine.
+     *
+     * @example "https://host.com/license/playready?contentid=090495867002"
+     */
+    licenseServerURL?: string;
+
+    /**
+     * Server address used for device provisioning.
+     *
+     * @example "https://host.com/provision/device?esn=090495867002"
+     */
+    serializationURL?: string;
+
+    /**
+     * Special meaning per DRM system. If supplied, expected to be a base64 encoded string.
+     */
+    appData?: string;
+
+    /**
+     * @deprecated Use `licenseServerURL` instead. Specifies the PlayReady license acquisition data.
+     */
+    encodingKey?: string;
+
+    /**
+     * @deprecated Use `licenseServerURL` instead. Specifies the encoding scheme for PlayReady DRM.
+     *
+     * Valid values: `"PlayReadyLicenseAcquisitionUrl"`, `"PlayReadyLicenseAcquisitionAndChallenge"`.
+     */
+    encodingType?: PlayReadyEncodingType | string;
+
+    /**
+     * The actual certificate string for Widevine purposes, obtained out-of-band (OOB) by the app.
+     * Leave unset unless Widevine is used for DRM.
+     */
+    serviceCert?: string;
+
+    /**
+     * URL location for sending license renewal requests.
+     * If not specified, the Roku OS sends renewal requests to the `licenseServerURL`.
+     */
+    licenseRenewURL?: string;
+
+    /**
+     * The maximum amount of time (in milliseconds) that an app waits before rotating
+     * its Widevine DRM keys.
+     */
+    lic_acq_window?: string;
+
+    /**
+     * Ignores the PSSH in the initialization segment. Enables support for Harmonic/DTV-GO
+     * DASH-IOP v5.0.0 streams with In-Band Key-Rotation Signaling.
+     *
+     * @default "false"
+     * @since Roku OS 14.5
+     */
+    ignoreInitDataPssh?: string;
+
+    /**
+     * Contains the license request template — the entire license request without
+     * the license challenge filled in. JSON or XML formats are supported.
+     *
+     * @since Roku OS 14.6
+     */
+    licReqTemplate?: string;
+
+    /**
+     * The format of the license request template.
+     *
+     * - `"JSON"`: `licReqTemplate` is in JSON format.
+     * - `"XML"`: `licReqTemplate` is in XML format.
+     * - `"BASE64"`: Does not use `licReqTemplate`; base64-encodes the challenge and sends it in POST body.
+     *
+     * If no value is specified, the license template is not used.
+     *
+     * @since Roku OS 14.6
+     */
+    templateType?: DrmTemplateType | string;
+
+    /**
+     * jsonpath or xpath to the element whose value must contain the fixed token `LICENSE_CHALLENGE`.
+     * - jsonpath if `templateType` is `"JSON"`
+     * - xpath if `templateType` is `"XML"`
+     *
+     * The Roku OS replaces the `LICENSE_CHALLENGE` token with the base64-encoded license challenge.
+     *
+     * @since Roku OS 14.6
+     * @example ".parameters[0].body"
+     */
+    requestField?: string;
+
+    /**
+     * jsonpath or xpath to the element that contains the base64-encoded license response.
+     * - jsonpath if `templateType` is `"JSON"`
+     * - xpath if `templateType` is `"XML"`
+     *
+     * @since Roku OS 14.6
+     * @example ".output.widevine2License.license"
+     */
+    responseField?: string;
+}
+
+/**
+ * Digital rights management (DRM) control attributes for content items.
+ *
+ * These attributes configure DRM through the `drmParams` parameter of type `Record<string, string>`.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#digital-rights-management-drm-control-attributes}
+ */
+export interface IDrmAttributes {
+    /**
+     * DRM parameters for configuring PlayReady, Widevine, or other DRM systems.
+     *
+     * @example
+     * ```tsx
+     * <ContentNode
+     *     drmParams={{
+     *         keySystem: "widevine",
+     *         licenseServerURL: "https://host.com/license/widevine"
+     *     }}
+     * />
+     * ```
+     */
+    drmParams?: IDrmParams;
+}
+
+/**
+ * Content classification attributes for automatic sound and picture adjustment on Roku TVs.
+ *
+ * When auto mode is selected for the picture or sound settings, the Roku OS uses
+ * the `contentClassifier` attribute to automatically adjust sound and picture.
+ *
+ * @since Roku OS 13.0
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#content-classification-attributes}
+ */
+export interface IContentClassificationAttributes {
+    /**
+     * Specifies the genre of the content (e.g., action, sports, comedy).
+     * The Roku OS uses this to automatically adjust sound and picture on Roku TVs
+     * if auto mode is selected.
+     *
+     * @since Roku OS 13.0
+     * @example "drama"
+     */
+    contentClassifier?: ContentClassifier | string;
+}
+
+/**
+ * CDN configuration entry for load balancing and failover.
+ */
+export interface ICdnConfigEntry {
+    /** URL filter pattern for matching CDN. */
+    URLFilter: string;
+    /** Content filter for matching specific programs. */
+    ContentFilter?: string;
+    /** Priority level for CDN selection. Lower values indicate higher priority. */
+    priority: number;
+    /** Weight for load balancing within the same priority level. */
+    weight: number;
+    /** Service location identifier. */
+    serviceLocation?: string;
+}
+
+/**
+ * CDN switching attributes for managing load balancing and failover during playback.
+ *
+ * Content Delivery Networks (CDNs) can be switched during playback to load balance
+ * traffic and failover to different servers in order to help optimize performance.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#cdn-switching}
+ */
+export interface ICdnSwitchingAttributes {
+    /**
+     * CDN configuration for managing load balancing and failovers.
+     * The `URLFilter`, `priority`, and `weight` attributes must be specified.
+     *
+     * To use this field, create a child node and use a playlist (even though only
+     * one content item will be in the playlist). This field is updated only when
+     * `contentIsPlayList` is true.
+     */
+    cdnConfig?: ICdnConfigEntry[];
+}
+
+/**
+ * SceneGraph certificate metadata attributes for configuring HTTP certificates and cookies
+ * used by Audio and Video nodes.
+ *
+ * **Important**: When setting any of these attributes, values are set on the HTTPAgent
+ * associated with the node. If the node does not have its own HTTPAgent (set via `setHttpAgent()`),
+ * the Roku OS traverses the scene graph hierarchy until it finds the first node with an HTTPAgent.
+ * If none is found, values are set on the global HTTPAgent.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#scenegraph-certificate-attributes}
+ */
+export interface ICertificateAttributes {
+    /**
+     * If set, the Audio or Video node loads this public certificate bundle to authenticate the server.
+     * The protocol must be HTTPS for this to have any effect.
+     *
+     * If this attribute is defined with a URI, the file URI is set into the HttpAgent instance.
+     * If defined as an empty string (`""`), no changes are made to the HttpAgent.
+     * If not defined and secure URLs exist in the metadata, the platform's default certificates are used.
+     */
+    httpCertificatesFile?: string;
+
+    /**
+     * If set, the Audio or Video node sends the cookies to the server.
+     * Each cookie must have the syntax: `dom=domain;path=path;name=name;val=value;`.
+     *
+     * When this attribute is set, all HTTP cookies in the agent are cleared
+     * and replaced with the cookies defined by this attribute.
+     */
+    httpCookies?: string[];
+
+    /**
+     * If set, the Audio or Video node sends these headers to the server.
+     * Each string must be of the format `"name:value"`.
+     *
+     * When this attribute is set, all HTTP headers in the agent are cleared
+     * and replaced with the headers defined by this attribute.
+     */
+    httpHeaders?: string[];
+
+    /**
+     * If true, the Audio or Video node sends the client device certificate to the server
+     * for client authentication. The protocol must be HTTPS for this to have any effect.
+     */
+    httpSendClientCertificate?: boolean;
+}
+
+/**
+ * Playback control metadata attributes for controlling playback parameters.
+ *
+ * These attributes set bandwidth constraints, resolution flags, and frame rate settings.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#playback-control-attributes}
+ */
+export interface IPlaybackControlAttributes {
+    /**
+     * Will only select variant streams with a bandwidth higher than this minimum bandwidth.
+     * Units are kbps.
+     *
+     * @example 48
+     */
+    minBandwidth?: number;
+
+    /**
+     * Will only select variant streams with a bandwidth less than this maximum bandwidth.
+     * Units are kbps.
+     *
+     * @example 2500
+     */
+    maxBandwidth?: number;
+
+    /**
+     * Specifies that this stream was encoded at 1080p resolution.
+     */
+    fullHD?: boolean;
+
+    /**
+     * Specifies the frame rate the 1080p stream was encoded at.
+     *
+     * @example 24
+     * @example 30
+     */
+    frameRate?: number;
+}
+
+/**
+ * Track ID metadata attributes for selecting specific audio, video, and subtitle tracks.
+ *
+ * Used primarily with SmoothStreaming (`StreamFormat = "ISM"`) to specify particular tracks
+ * from the manifest file.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#track-id-attributes}
+ */
+export interface ITrackIdAttributes {
+    /**
+     * Used in SmoothStreaming (`StreamFormat = "ISM"`) to specify the audio track.
+     * Set to the desired track's `StreamIndex.Name` attribute from the manifest file.
+     *
+     * @example "Spanish"
+     */
+    trackIDAudio?: string;
+
+    /**
+     * Used in SmoothStreaming (`StreamFormat = "ISM"`) to specify the video track.
+     * Set to the desired track's `StreamIndex.Name` attribute from the manifest file.
+     *
+     * @example "h264video"
+     */
+    trackIDVideo?: string;
+
+    /**
+     * Used to specify a closed caption track in a video stream that supports 608/708 captions.
+     *
+     * @example "eia608/1"
+     */
+    trackIDSubtitle?: string;
+
+    /**
+     * If set to `"dolby-digital"`, displays a "5.1 ))" icon in the lower left of a
+     * movie style springboard screen.
+     *
+     * @example "dolby-digital"
+     */
+    audioFormat?: string;
+
+    /**
+     * @deprecated As of Roku OS 9.2. Users can select their preferred audio language
+     * on-device in Settings > Audio > Audio Preferred Language.
+     */
+    audioLanguageSelected?: string;
+}
+
+/**
+ * roListScreen-specific metadata attributes for specifying background images.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata#rolistscreen-attributes}
+ */
+export interface IListScreenAttributes {
+    /**
+     * URL for the SD background image used by roListScreen.
+     *
+     * @example "mysite.com/images/bg1_sd.jpg"
+     */
+    sdBackgroundImageUrl?: string;
+
+    /**
+     * URL for the HD background image used by roListScreen.
+     *
+     * @example "mysite.com/images/bg1_hd.jpg"
+     */
+    hdBackgroundImageUrl?: string;
+}
+
+/**
+ * Content metadata attributes used by ZoomRowList to control per-item layout.
+ *
+ * When `useDefaultAspectRatio` is `false` for a row, ZoomRowList reads these
+ * fields from each item's ContentNode instead of using the row-level defaults.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/zoomrowlist}
+ */
+export interface IZoomRowListDataAttributes {
+    /**
+     * Aspect ratio (width/height) of this content item. Used by ZoomRowList to
+     * compute item width from the interpolated height when `useDefaultAspectRatio`
+     * is `false` for that row.
+     *
+     * @see {@link https://developer.roku.com/dev/docs/zoomrowlist}
+     * @example 1.7777778
+     */
+    aspectRatio?: number;
+}
+
+/**
+ * Properties for the ContentNode node.
+ *
+ * ContentNode allows you to specify the data used to configure a node or component. Many nodes and
+ * components require a ContentNode as the specification of their `content` field in order to be
+ * properly configured. Lists, grids, and panels typically require a ContentNode for configuration.
+ *
+ * ContentNodes are typically structured as one ContentNode parent node with a hierarchy of child
+ * nodes that specify the actual data. You should use ContentNode for complex data structures rather
+ * than associative arrays — ContentNode objects are passed by reference, while associative arrays
+ * are copied.
+ *
+ * All Content Meta-Data attributes are accessible as fields using dot notation on a ContentNode object.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/contentnode}
+ * @see {@link https://developer.roku.com/dev/docs/content-metadata}
+ */
+export interface IContentNodeProps
+    extends
+        INodeProps,
+        IDescriptiveAttributes,
+        IPlaybackConfigurationAttributes,
+        IDrmAttributes,
+        IContentClassificationAttributes,
+        ICdnSwitchingAttributes,
+        ICertificateAttributes,
+        IPlaybackControlAttributes,
+        ITrackIdAttributes,
+        IListScreenAttributes,
+        IZoomRowListDataAttributes {}
+
+/**
+ * Properties for a video-specific ContentNode.
+ *
+ * Extends {@link IContentNodeProps} with video stream URL and format fields commonly used
+ * when configuring a Scene Graph Video node's content.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/contentnode}
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IVideoContentNodeProps extends IContentNodeProps {
+    /**
+     * Stream URL for the video content. Overrides the base `url` field for explicit video use.
+     *
+     * @example "https://example.com/stream.m3u8"
+     */
+    url?: string;
+
+    /**
+     * The stream format of the video content (SceneGraph field `streamformat`).
+     *
+     * Valid values: `"mp4"`, `"hls"`, `"ism"`, `"dash"`, `"mkv"`.
+     *
+     * @remarks The RSG SDK does not currently wire this through for
+     * `VideoContentNode`; omit it and rely on URL / player behavior until support
+     * lands.
+     */
+    streamformat?: StreamFormat | string;
+}
+
+/**
+ * @deprecated Use {@link IPlaybackConfigurationAttributes} instead.
+ */
+export type IPlaybackConfiguration = IPlaybackConfigurationAttributes;