bitmovin-player-react-native/build/metadata.d.ts

Official React Native bindings for Bitmovin's mobile Player SDKs.

import { TimeRange, Seconds, Milliseconds } from './utils/temporal';
/**
 * Enumerates all supported types of timed metadata entries.
 *
 * @see {@link MetadataEntry} for the full type narrowing documentation
 */
export declare enum MetadataType {
    /**
     * ID3 metadata embedded in the media stream.
     *
     * Used for timed ID3 tags such as text frames, comments, artwork,
     * chapters, private frames, and other ID3v2 structures.
     *
     * @see {@link Id3MetadataEntry}
     */
    ID3 = "ID3",
    /**
     * Event Message metadata as defined in ISO/IEC 23009-1.
     *
     * Represents MP4 Event Message boxes (`emsg`) or DASH `EventStream`
     * events carrying an application- or spec-defined payload.
     *
     * @platform Android
     * @remarks This metadata type is never emitted on iOS or tvOS, as the native
     *          player does not surface EMSG events on those platforms.
     * @see {@link EventMessageMetadataEntry}
     */
    EMSG = "EMSG",
    /**
     * SCTE-35 signaling extracted from HLS `#EXT-X-SCTE35` tags.
     *
     * Typically used for ad insertion, blackout signaling, or other
     * broadcast-style cue messages.
     *
     * @see {@link ScteMetadataEntry}
     */
    SCTE = "SCTE",
    /**
     * HLS `#EXT-X-DATERANGE` tags representing timed opportunities or annotations.
     *
     * Used for in-playlist markers such as interstitial opportunities,
     * blackout windows, content labels, or other time-bounded ranges.
     *
     * @see {@link DateRangeMetadataEntry}
     */
    DATERANGE = "DATERANGE",
    /**
     * Sentinel type for unsupported metadata.
     *
     * This value indicates that the underlying native player reported timed metadata
     * at some point in the stream, but the React Native SDK does not yet map it to
     * one of the supported metadata entry types of ({@link ID3}, {@link SCTE},
     * {@link DATERANGE}, or {@link EMSG}).
     *
     * @see {@link UnsupportedMetadataEntry}
     */
    Unsupported = "NONE"
}
/**
 * Raw data encoded as Base64 with no `data:...;base64,` prefix.
 *
 * Use this type whenever the value is just the Base64 string itself, not a full
 * data URI string.
 *
 * @example
 * // Correct format:
 * "SGVsbG8gV29ybGQ="
 *
 * @example
 * // Incorrect (includes a data URI scheme — not allowed):
 * "data:text/plain;base64,SGVsbG8gV29ybGQ="
 */
export type Base64Raw = string;
export type CueingOption = 'PRE' | 'POST' | 'ONCE';
interface BaseDateRangeMetadataEntry<TPlatform extends 'ios' | 'android'> {
    metadataType: MetadataType.DATERANGE;
    /**
     * Platform discriminator for TypeScript type narrowing.
     */
    platform: TPlatform;
    /**
     * The unique identifier for the date range.
     */
    id: string;
    /**
     * The class associated with the date range.
     */
    classLabel?: string;
    /**
     * The declared duration of the range in seconds.
     */
    duration?: Seconds;
    /**
     * All the attributes associated with the date range.
     *
     * @example "X-ASSET-URI": "https://www.example.com"
     */
    attributes: Record<string, string>;
}
/**
 * Represents in-playlist timed metadata from an HLS `#EXT-X-DATERANGE` tag.
 *
 * @platform Android
 */
export interface AndroidDateRangeMetadataEntry extends BaseDateRangeMetadataEntry<'android'> {
    /**
     * Time range of the entry relative to the beginning of the playback, in seconds.
     */
    relativeTimeRange: TimeRange<Seconds>;
    /**
     * The planned duration of the range in seconds.
     *
     * Used for live streams where the actual end time may not be known yet.
     */
    plannedDuration?: Seconds;
    /**
     * Indicates whether the date range ends at the start of the next date range
     * with the same {@link classLabel}.
     */
    endOnNext: boolean;
}
/**
 * Represents in-playlist timed metadata from an HLS `#EXT-X-DATERANGE` tag.
 *
 * @platform iOS, tvOS
 */
export interface IosDateRangeMetadataEntry extends BaseDateRangeMetadataEntry<'ios'> {
    /**
     * Time range of the entry relative to Unix Epoch, in seconds.
     *
     * If the metadata represents an instantaneous event, {@link TimeRange.end} should be equal
     * to {@link TimeRange.start}.
     * An omitted {@link TimeRange.end} indicates an open-ended range.
     */
    absoluteTimeRange: TimeRange<Seconds>;
    /**
     * The `CUE` attribute values from an `#EXT-X-DATERANGE` tag.
     *
     * Empty array if the attribute is not present.
     * `"PRE"` triggers before playback; `"POST"` triggers after completion; `"ONCE"` limits triggering to once.
     * When multiple values are provided, the first takes precedence (e.g., `"PRE,POST"` -> `"PRE"`).
     * `"PRE"` and `"POST"` are re-playable unless `"ONCE"` is included.
     *
     * @remarks Applies only to HLS Interstitial opportunities (pre-, mid-, post-roll).
     */
    cueingOptions: CueingOption[];
}
/**
 * Represents Event Message metadata according to ISO 23009-1.
 *
 * This is used for both MP4 Event Message boxes (`emsg`) and DASH EventStream events.
 *
 * @platform Android
 */
export interface EventMessageMetadataEntry {
    metadataType: MetadataType.EMSG;
    /** The instance identifier for this specific event occurrence. */
    id: number;
    /** The duration of the event in seconds. */
    duration?: Seconds;
    /**
     * Raw event message payload encoded as Base64 with no `data:...;base64,` prefix.
     */
    messageData: Base64Raw;
    /**
     * The message scheme URI identifying the event type.
     *
     * @example "urn:mpeg:dash:event:callback:2014"
     */
    schemeIdUri: string;
    /** The value for the event. */
    value: string;
}
/**
 * Typed representations of an iOS metadata value.
 *
 * Depending on the underlying value, one or more of these fields may be present;
 * others will be `undefined`.
 */
export interface IosMetadataValue {
    /**
     * A text representation of the value, if available.
     */
    stringValue?: string;
    /**
     * A numeric representation of the value, if available.
     */
    numberValue?: number;
    /**
     * A date/time representation of the value, formatted as an ISO 8601 string, if available.
     *
     * @example "2025-12-02T00:00:00Z"
     */
    dateValue?: string;
    /**
     * A binary representation of the value as Base64 data
     * with no `data:...;base64,` prefix, if available.
     *
     * @remarks Use this accessor to retrieve encapsulated artwork, thumbnails,
     *          proprietary frames, or any encoded value.
     */
    dataValue?: Base64Raw;
}
/**
 * iOS representation of ID3 metadata items.
 *
 * @platform iOS, tvOS
 */
export interface IosId3Frame {
    metadataType: MetadataType.ID3;
    /**
     * Platform discriminator for TypeScript type narrowing.
     */
    platform: 'ios';
    /**
     * ID3 frame identifier.
     *
     * @example "TXXX"
     */
    id?: string;
    /**
     * String representation of the metadata value.
     *
     * The underlying value is first interpreted as the most appropriate type
     * (date, number, text, or binary data) and then converted to a string.
     * - Dates are formatted as ISO 8601 strings (e.g. "2025-12-02T00:00:00Z").
     * - Binary data is encoded as a Base64 with no `data:...;base64,` prefix.
     *
     * This will be `undefined` if the value cannot be interpreted.
     */
    value?: string;
    /**
     * Full typed representation of the underlying value as reported by iOS.
     */
    rawValue?: IosMetadataValue;
    /**
     * Time range of the entry relative to the beginning of the playback, in seconds.
     */
    relativeTimeRange?: TimeRange<Seconds>;
    /**
     * The duration of the metadata item in seconds.
     */
    duration?: Seconds;
    /**
     * The IETF BCP 47 language identifier of the metadata item.
     */
    extendedLanguageTag?: string;
    /**
     * Additional attributes attached to the metadata item.
     */
    extraAttributes?: Record<string, unknown>;
}
/**
 * Base interface for all Android ID3 frames.
 *
 * @platform Android
 */
interface AndroidId3FrameBase {
    metadataType: MetadataType.ID3;
    /**
     * Platform discriminator for TypeScript type narrowing.
     */
    platform: 'android';
    /**
     * ID3 frame identifier.
     *
     * @example "TXXX"
     */
    id: string;
}
/**
 * Stores text-based metadata.
 *
 * @platform Android
 */
export interface AndroidTextInformationFrame extends AndroidId3FrameBase {
    frameType: 'text';
    description?: string;
    value: string;
}
/**
 * Encapsulates an ID3 frame whose payload is treated as opaque binary data.
 *
 * @platform Android
 */
export interface AndroidBinaryFrame extends AndroidId3FrameBase {
    frameType: 'binary';
    /** Raw frame payload encoded as Base64 data with no `data:...;base64,` prefix. */
    data: Base64Raw;
}
/**
 * Encapsulates an attached picture.
 *
 * @platform Android
 */
export interface AndroidApicFrame extends AndroidId3FrameBase {
    frameType: 'apic';
    /**
     * MIME type of the embedded image as stored in the APIC frame.
     *
     * @example "image/jpeg"
     */
    mimeType: string;
    description?: string;
    /**
     * Picture type as defined by the ID3 specification.
     *
     * @example 3 // front cover
     */
    pictureType: number;
    /** Raw image data encoded as Base64 data with no `data:...;base64,` prefix. */
    pictureData: Base64Raw;
}
/**
 * Stores an external resource via URL.
 *
 * @platform Android
 */
export interface AndroidUrlLinkFrame extends AndroidId3FrameBase {
    frameType: 'url';
    description?: string;
    url: string;
}
/**
 * Stores user comments or notes.
 *
 * @platform Android
 */
export interface AndroidCommentFrame extends AndroidId3FrameBase {
    frameType: 'comment';
    language: string;
    description: string;
    /** The comment text. */
    text: string;
}
/**
 * Encapsulates owner-specific private data.
 *
 * The structure and semantics of the payload are defined solely by the `owner`
 * identifier and are opaque to generic parsers.
 *
 * @platform Android
 */
export interface AndroidPrivFrame extends AndroidId3FrameBase {
    frameType: 'priv';
    /**
     * Owner identifier string.
     *
     * Typically a reverse-DNS or application-specific identifier.
     *
     * @example "com.example.app"
     */
    owner: string;
    /**
     * Raw private payload encoded as Base64 data with no `data:...;base64,` prefix.
     *
     * Consumers should only attempt to interpret this data if they recognize
     * and understand the corresponding {@link owner} value.
     */
    privateData: Base64Raw;
}
/**
 * Encapsulates arbitrary binary objects with metadata.
 *
 * @platform Android
 */
export interface AndroidGeobFrame extends AndroidId3FrameBase {
    frameType: 'geob';
    /**
     * MIME type of the encapsulated object.
     *
     * @example "application/octet-stream"
     */
    mimeType: string;
    /** Original filename of the object. */
    filename: string;
    description: string;
    /**
     * Raw object encoded as Base64 data with no `data:...;base64,` prefix.
     */
    data: Base64Raw;
}
/**
 * Defines a content chapter.
 *
 * @platform Android
 */
export interface AndroidChapterFrame extends AndroidId3FrameBase {
    frameType: 'chapter';
    /** Identifier of the chapter element. */
    chapterId: string;
    /** Time range of the chapter in milliseconds. */
    timeRange: TimeRange<Milliseconds>;
    /** The byte offset of the start of the chapter, or `-1` if not set. */
    startOffset: number;
    /** The byte offset of the end of the chapter, or `-1` if not set. */
    endOffset: number;
    /**
     * Nested ID3 subframes associated with this chapter (e.g. title, URL, etc.).
     */
    subFrames: AndroidId3Frame[];
}
/**
 * Defines hierarchical chapter structure.
 *
 * @platform Android
 */
export interface AndroidChapterTocFrame extends AndroidId3FrameBase {
    frameType: 'chapterToc';
    /** Identifier of the table-of-contents element. */
    elementId: string;
    /** Whether this element is the root of the chapter tree. */
    isRoot: boolean;
    /** Whether the listed children are ordered. */
    isOrdered: boolean;
    /** IDs of child chapter or TOC elements. */
    children: string[];
    /**
     * Nested ID3 subframes associated with this TOC element.
     */
    subFrames: AndroidId3Frame[];
}
/**
 * Android representation of ID3 metadata items.
 *
 * This is a discriminated union of Android ID3 frame types. Use {@link isAndroidId3Frame}
 * for type-safe narrowing to specific frame types.
 *
 * @platform Android
 * @see {@link isAndroidId3Frame} for frame type narrowing
 */
export type AndroidId3Frame = AndroidTextInformationFrame | AndroidBinaryFrame | AndroidApicFrame | AndroidUrlLinkFrame | AndroidCommentFrame | AndroidPrivFrame | AndroidGeobFrame | AndroidChapterFrame | AndroidChapterTocFrame;
/**
 * Describes metadata associated with ID3 tags.
 *
 * This is a discriminated union over the `platform` field:
 *
 * - `"ios"`: {@link IosId3Frame}
 * - `"android"`: {@link AndroidId3Frame}
 *
 * Narrowing on `platform` gives you access to the platform-specific fields.
 */
export type Id3MetadataEntry = IosId3Frame | AndroidId3Frame;
/**
 * Describes metadata associated with HLS `#EXT-X-SCTE35` tags.
 *
 * @remarks On iOS, {@link TweaksConfig.isNativeHlsParsingEnabled} must be enabled
 *          to parse this type of metadata.
 */
export interface ScteMetadataEntry {
    metadataType: MetadataType.SCTE;
    /**
     * The attribute name/key from the SCTE-35 tag.
     */
    key: string;
    /**
     * The attribute value (nullable for key-only attributes).
     */
    value?: string;
}
/**
 * Metadata entry for unsupported metadata types.
 *
 * This type is emitted when the native player reports timed metadata that
 * this SDK cannot attach to one of the supported types:
 * - iOS: metadata that is not exposed as ID3, SCTE, or DATERANGE
 * - Android: metadata that is not exposed as ID3, SCTE, DATERANGE, or EMSG
 */
export interface UnsupportedMetadataEntry {
    metadataType: MetadataType.Unsupported;
    /** The platform that reported the unsupported metadata. */
    platform: 'ios' | 'android';
}
/**
 * Represents in-playlist timed metadata from an HLS `#EXT-X-DATERANGE` tag.
 *
 * This is a discriminated union over the `platform` field:
 *
 * - `"ios"`: {@link IosDateRangeMetadataEntry}
 * - `"android"`: {@link AndroidDateRangeMetadataEntry}
 *
 * Narrowing on `platform` gives you access to the platform-specific fields.
 */
export type DateRangeMetadataEntry = IosDateRangeMetadataEntry | AndroidDateRangeMetadataEntry;
/**
 * Union type representing all supported timed metadata entry kinds.
 *
 * This is a discriminated union over the `metadataType` field:
 *
 * - {@link MetadataType.ID3}: {@link Id3MetadataEntry}
 * - {@link MetadataType.DATERANGE}: {@link DateRangeMetadataEntry}
 * - {@link MetadataType.SCTE}: {@link ScteMetadataEntry}
 * - {@link MetadataType.EMSG}: {@link EventMessageMetadataEntry}
 * - {@link MetadataType.Unsupported}: {@link UnsupportedMetadataEntry}
 *
 * Branching on `metadataType` using an `if`/`switch` statement narrows the type and
 * gives access to entry-specific fields.
 *
 * @example
 * ```ts
 * function handleMetadata(entry: MetadataEntry) {
 *   switch (entry.metadataType) {
 *     case MetadataType.DATERANGE:
 *       // `entry` is a DateRangeMetadataEntry
 *       if (entry.platform === 'android') {
 *         // `entry` is now an AndroidDateRangeMetadataEntry
 *         console.log('End on next:', entry.endOnNext);
 *       } else {
 *         // `entry` is now an IosDateRangeMetadataEntry
 *         console.log('Cueing options:', entry.cueingOptions);
 *       }
 *       break;
 *
 *     case MetadataType.SCTE:
 *       // `entry` is a ScteMetadataEntry
 *       console.log('SCTE key:', entry.key, 'value:', entry.value);
 *       break;
 *
 *     case MetadataType.ID3:
 *       // `entry` is an Id3MetadataEntry
 *       if (entry.platform === 'android') {
 *         // `entry` is now an AndroidId3Frame
 *         console.log('Frame type:', entry.frameType);
 *         // Further narrow down on the frame type
 *         if (entry.frameType == 'apic') {
 *           console.log('APIC frame mimeType: ', entry.mimeType)
 *         }
 *       } else {
 *         // `entry` is now an IosId3Frame
 *         console.log('Frame ID:', entry.id, 'Value:', entry.value);
 *       }
 *       // Or use isAndroidId3Frame to directly narrow to specific Android frame
 *       if (isAndroidId3Frame(entry, 'text')) {
 *         console.log('Text frame:', entry.value);
 *       }
 *       break;
 *
 *     case MetadataType.EMSG:
 *       // `entry` is an EventMessageMetadataEntry (Android only)
 *       console.log('EMSG data:', entry.messageData);
 *       break;
 *
 *     case MetadataType.Unsupported:
 *       // `entry` is an UnsupportedMetadataEntry
 *       console.warn('Unsupported metadata encountered from: ', entry.platform)
 *       break;
 *   }
 * }
 * ```
 */
export type MetadataEntry = DateRangeMetadataEntry | EventMessageMetadataEntry | Id3MetadataEntry | ScteMetadataEntry | UnsupportedMetadataEntry;
/**
 * A collection of timed metadata entries of the same type.
 *
 * All entries in the collection share the same `metadataType`.
 */
export interface MetadataCollection<T extends MetadataEntry> {
    /**
     * The playback time in seconds when this metadata should trigger, relative to the playback session.
     */
    startTime?: Seconds;
    /**
     * The metadata entries.
     *
     * The group is homogeneous: all entries share the same metadata type.
     */
    entries: T[];
}
/**
 * Type-safe narrowing helper for Android ID3 frame types.
 *
 * Android ID3 frames have 9 distinct frame types (text, binary, apic, url, comment,
 * priv, geob, chapter, chapterToc), each with different fields. This helper provides
 * type-safe access to frame-specific properties.
 *
 * @param entry - The ID3 metadata entry to check
 * @param frameType - The Android frame type to narrow to
 * @returns `true` if entry is an Android frame of the specified type
 *
 * @see {@link MetadataEntry} for the full type narrowing documentation
 */
export declare function isAndroidId3Frame<T extends AndroidId3Frame['frameType']>(entry: Id3MetadataEntry, frameType: T): entry is Extract<AndroidId3Frame, {
    frameType: T;
}>;
export {};
//# sourceMappingURL=metadata.d.ts.map