react-native-theoplayer 1.6.1 → 1.7.0

package/lib/typescript/src/api/ads/CompanionAd.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Represents a companion ad which is displayed near the video player.
+ *
+ * @public
+ */
+export interface CompanionAd {
+    /**
+     * The identifier of the element in which the companion ad should be appended, if available.
+     *
+     * @remarks
+     * <br/> Only available for Google DAI and THEO ads if provided in the VAST.
+     */
+    adSlotId?: string;
+    /**
+     * The alternative description for the ad.
+     *
+     * @remarks
+     * <br/> - Returns value as reported in the VAST StaticResource. If not specified, it returns an empty string.
+     * <br/> - Returns an empty string for THEO ads if not available.
+     * <br/> - Returns an empty string for Google IMA / Google DAI integrations.
+     */
+    altText: string;
+    /**
+     * The content of the ad, as HTML.
+     *
+     * @remarks
+     * <br/> - Available for StaticResource and HTMLResource in THEO ad system.
+     * <br/> - Available in the DAI ad system.
+     */
+    contentHTML: string;
+    /**
+     * The website of the advertisement.
+     *
+     * @remarks
+     * <br/> - Only available for StaticResource if specified by the VAST. Otherwise returns an empty string.
+     */
+    clickThrough?: string;
+    /**
+     * The height of the ad, in pixels.
+     *
+     * @remarks
+     * <br/> - Only available for IMA ad system and THEO ad system.
+     */
+    height: number;
+    /**
+     * The URI of the ad content as specified in the VAST file.
+     *
+     * @remarks
+     * <br/> - Only available in the THEO ad system for StaticResource. Otherwise returns an empty string.
+     */
+    resourceURI: string;
+    /**
+     * The width of the ad, in pixels.
+     *
+     * @remarks
+     * <br/> - Only available for IMA ad system and THEO ad system.
+     */
+    width: number;
+}

package/lib/typescript/src/api/ads/GoogleDai.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The Google DAI API.
+ *
+ * @public
+ */
+export interface GoogleDAI {
+    /**
+     * Returns the content time without ads for a given stream time. Returns the given stream time for live streams.
+     *
+     * @param time - The stream time with inserted ads (in seconds).
+     */
+    contentTimeForStreamTime(time: number): Promise<number>;
+    /**
+     * Returns the stream time with ads for a given content time. Returns the given content time for live streams.
+     *
+     * @param time - The content time without any ads (in seconds).
+     */
+    streamTimeForContentTime(time: number): Promise<number>;
+    /**
+     * Whether snapback is enabled. When enabled and the user seeks over multiple ad breaks, the last ad break that was seeked past will be played.
+     *
+     * @defaultValue `true`
+     */
+    readonly snapback: Promise<boolean>;
+    /**
+     * Set snapback value. When enabled and the user seeks over multiple ad breaks, the last ad break that was seeked past will be played.
+     */
+    setSnapback(enabled: boolean): void;
+}

package/lib/typescript/src/api/ads/GoogleImaAd.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Represents a Google IMA creative compliant to the VAST specification.
+ *
+ * @remarks
+ * <br/> - Available since v2.60.0.
+ *
+ * @public
+ */
+import type { Ad } from './Ad';
+export interface GoogleImaAd extends Ad {
+    /**
+     * The bitrate of the currently playing creative as listed in the VAST response or 0.
+     */
+    readonly bitrate: number;
+    /**
+     * Record of custom parameters for the ad at the time of ad trafficking.
+     * Each entry contains a parameter name with associated value.
+     *
+     * @remarks
+     * <br/> - Available when the {@link Ad.readyState} is `'ready'`.
+     */
+    traffickingParameters: {
+        [parameterKey: string]: string;
+    } | undefined;
+    /**
+     * Return title of the advertisement.
+     *
+     * @remarks
+     * <br/> - Available when the {@link Ad.readyState} is `'ready'`.
+     */
+    title: string | undefined;
+    /**
+     * The custom parameters for the ad at the time of ad trafficking, as a string.
+     *
+     * @remarks
+     * <br/> - A parsed version is available as {@link GoogleImaAd.traffickingParameters}.
+     * <br/> - Available when the {@link Ad.readyState} is `'ready'`.
+     */
+    traffickingParametersString: string | undefined;
+    /**
+     * List of wrapper ad identifiers as specified in the VAST response.
+     */
+    wrapperAdIds: string[];
+    /**
+     * List of wrapper ad systems as specified in the VAST response.
+     */
+    wrapperAdSystems: string[];
+    /**
+     * List of wrapper creative identifiers.
+     *
+     * @remarks
+     * <br/> - Starts with the first wrapper ad.
+     */
+    wrapperCreativeIds: string[];
+    /**
+     * The url of the chosen media file.
+     *
+     * @remarks
+     * <br/> - Available when the {@link Ad.readyState} is `'ready'`.
+     */
+    mediaUrl: string | undefined;
+    /**
+     * The content type of the ad.
+     *
+     * @remarks
+     * <br/> - Available when the {@link Ad.readyState} is `'ready'`.
+     * <br/> - For linear ads, the content type is only going to be available after the `'adbegin'` event, when the media file is selected.
+     */
+    contentType: string | undefined;
+    /**
+     * The identifier of the API framework needed to execute the ad.
+     *
+     * @remarks
+     * <br/> - Available when the {@link Ad.readyState} is `'ready'`.
+     * <br/> - This corresponds with the apiFramework specified in vast.
+     */
+    apiFramework: string | undefined;
+}

package/lib/typescript/src/api/ads/GoogleImaConfiguration.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Describes the configuration of Google IMA.
+ *
+ * @internal
+ */
+export interface GoogleImaConfiguration {
+    /**
+     * Whether the native (mobile) IMA implementation will be used.
+     *
+     * @internal
+     */
+    useNativeIma: boolean;
+}

package/lib/typescript/src/api/ads/barrel.d.ts

@@ -0,0 +1,8 @@
+export * from './Ad';
+export * from './AdBreak';
+export * from './AdsConfiguration';
+export * from './AdsAPI';
+export * from './CompanionAd';
+export * from './GoogleDai';
+export * from './GoogleImaAd';
+export * from './GoogleImaConfiguration';

package/lib/typescript/src/api/barrel.d.ts

@@ -1,7 +1,11 @@
+export * from './abr/barrel';
+export * from './ads/barrel';
+export * from './config/barrel';
 export * from './error/barrel';
 export * from './event/barrel';
+export * from './drm/barrel';
 export * from './source/barrel';
 export * from './timeranges/barrel';
 export * from './track/barrel';
-export * from './config/barrel';
+export * from './utils/barrel';
 export * from './THEOplayerView';

package/lib/typescript/src/api/config/PlayerConfiguration.d.ts

@@ -1,4 +1,9 @@
+import type { AdsConfiguration } from "../ads/AdsConfiguration";
 export interface PlayerConfiguration {
+    /**
+     * The ads configuration for the player.
+     */
+    ads?: AdsConfiguration;
     /**
      * The license for the player
      */

package/lib/typescript/src/api/drm/ContentProtectionAPI.d.ts

@@ -0,0 +1,5 @@
+import type { KeySystemId } from 'react-native-theoplayer';
+import type { ContentProtectionIntegrationFactory } from './ContentProtectionIntegrationFactory';
+export interface ContentProtectionAPI {
+    registerContentProtectionIntegration(integrationId: string, keySystem: KeySystemId, integrationFactory: ContentProtectionIntegrationFactory): void;
+}

package/lib/typescript/src/api/drm/ContentProtectionIntegration.d.ts

@@ -0,0 +1,86 @@
+import type { CertificateRequest, LicenseRequest } from './ContentProtectionRequest';
+import type { CertificateResponse, LicenseResponse } from './ContentProtectionResponse';
+/**
+ * A synchronous or asynchronous return type
+ *
+ * @public
+ */
+export declare type MaybeAsync<T> = T | PromiseLike<T>;
+export declare type BufferSource = ArrayBufferView | ArrayBuffer;
+/**
+ * This ContentProtectionIntegration defines some methods to alter license and certificate requests and responses.
+ *
+ * @public
+ */
+export interface ContentProtectionIntegration {
+    /**
+     * Handler which will be called when a HTTP request for a new certificate is about to be sent.
+     *
+     * @remarks
+     * If a valid certificate was provided as part of the {@link KeySystemConfiguration.certificate}, this handler will not be called.
+     * The handler must return either a request or a raw certificate. When a (possibly modified) request is returned,
+     * the player will send that request instead of the original request. When a raw certificate is returned,
+     * the request is skipped entirely and the certificate is used directly. If no handler is provided, the player sends the original request.
+     *
+     * For example, an integration may want to “wrap” the request body in a different format (e.g. JSON or XML) for
+     * certain DRM vendors, or add additional authentication tokens to the request.
+     * Alternatively, an integration may want to send the HTTP request using its own network stack,
+     * and return the final certificate response to the player.
+     *
+     * @param request - The {@link CertificateRequest} that is about to be sent.
+     */
+    onCertificateRequest?(request: CertificateRequest): MaybeAsync<Partial<CertificateRequest> | BufferSource>;
+    /**
+     * Handler which will be called when a HTTP request for a certificate returns a response.
+     *
+     * @remarks
+     * The handler will be called regardless of the HTTP status code on the response (i.e. also for unsuccessful statuses outside of the 200-299 range).
+     * The handler must return the raw certificate, in a manner suitable for further processing by the CDM.
+     * If no handler is provided, the player uses the response body as raw certificate, but only if the response’s status indicates success.
+     *
+     * For example, an integration may want to “unwrap” a wrapped JSON or XML response body, turning it into a raw certificate.
+     *
+     * @param response - The {@link CertificateResponse} that was returned from the certificate request.
+     */
+    onCertificateResponse?(response: CertificateResponse): MaybeAsync<BufferSource>;
+    /**
+     * Handler which will be called when a HTTP request for a new license is about to be sent.
+     *
+     * @remarks
+     * The handler must return either a request or a raw license. When a (possibly modified) request is returned,
+     * the player will send that request instead of the original request. When a raw license is returned,
+     * the request is skipped entirely and the license is used directly. If no handler is provided, the player sends the original request.
+     *
+     * For example, an integration may want to “wrap” the request body in a different format (e.g. JSON or XML) for certain DRM vendors,
+     * or add additional authentication tokens to the request. Alternatively, an integration may want to send the HTTP request using its own network stack,
+     * and return the final license response to the player.
+     *
+     * @param request - The {@link LicenseRequest} that is about to be sent.
+     */
+    onLicenseRequest?(request: LicenseRequest): MaybeAsync<Partial<LicenseRequest> | BufferSource>;
+    /**
+     * Handler which will be called when a HTTP request for a license returns an response.
+     *
+     * @remarks
+     * The handler will be called regardless of the HTTP status code on the response (i.e. also for unsuccessful statuses outside of the 200-299 range).
+     * The handler must return the raw license, in a manner suitable for further processing by the CDM.
+     * If no handler is provided, the player uses the response body as raw license, but only if the response’s status indicates success.
+     *
+     * For example, an integration may want to “unwrap” a wrapped JSON or XML response body, turning it into a raw license.
+     *
+     * @param response - The {@link LicenseResponse} that was returned from the license request.
+     */
+    onLicenseResponse?(response: LicenseResponse): MaybeAsync<BufferSource>;
+    /**
+     * A function to extract the Fairplay content ID from the key URI, as given by the URI attribute of the `#EXT-X-KEY` tag in the HLS playlist (m3u8).
+     *
+     * @remarks
+     * In order to start a Fairplay license request, the player must provide the initialization data, the content ID and the certificate to the CDM.
+     * The content ID is usually contained in the key URI in some vendor-specific way, for example in the host name (e.g. `skd://123456789`)
+     * or in the URL query (e.g. `skd://vendor?123456789`). This function should extract this content ID from the key URI.
+     * This method is required only for Fairplay integrations. It is ignored for other key systems.
+     *
+     * @param skdUrl - The key URI.
+     */
+    extractFairplayContentId?(skdUrl: string): MaybeAsync<string>;
+}

package/lib/typescript/src/api/drm/ContentProtectionIntegrationFactory.d.ts

@@ -0,0 +1,15 @@
+import type { ContentProtectionIntegration } from './ContentProtectionIntegration';
+import type { DRMConfiguration } from 'react-native-theoplayer';
+/**
+ * Factory pattern to create {@link ContentProtectionIntegration}s.
+ *
+ * @public
+ */
+export interface ContentProtectionIntegrationFactory {
+    /**
+     * Build a new {@link ContentProtectionIntegration} based on the given {@link DRMConfiguration}.
+     *
+     * @param configuration - The {@link DRMConfiguration} of the currently loading source.
+     */
+    build(configuration: DRMConfiguration): ContentProtectionIntegration;
+}

package/lib/typescript/src/api/drm/ContentProtectionRequest.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A request, either for a certificate or a license.
+ * @public
+ */
+export interface ContentProtectionRequest {
+    /**
+     * The URL for the certificate server. By default, this will equal the certificate URL configured in the
+     * `{@link KeySystemConfiguration}`.
+     */
+    url: string;
+    /**
+     * The method of the HTTP request, for example: GET, POST or PUT.
+     *
+     * @remarks
+     * <br/> - Will be equal to GET for Fairplay certificate requests and POST for Widevine certificate requests.
+     * <br/> - Will be equal to POST for all license requests.
+     */
+    method: string;
+    /**
+     * The HTTP request headers to be sent to the server.
+     */
+    headers: {
+        [headerName: string]: string;
+    };
+    /**
+     * The body of the certificate request.
+     *
+     * @remarks
+     * <br/> - For GET requests (such as with Fairplay), the body will be empty (null).
+     * <br/> - For POST requests (such as with Widevine): the body will contain the two bytes in an array as specified in the certificate request protocol.
+     */
+    body: Uint8Array | null;
+    /**
+     * Whether the player is allowed to use credentials for cross-origin requests.
+     */
+    useCredentials: boolean;
+}
+/**
+ * A request for a certificate.
+ *
+ * @public
+ */
+export declare type CertificateRequest = ContentProtectionRequest;
+/**
+ * A request for a license.
+ * @public
+ */
+export interface LicenseRequest extends ContentProtectionRequest {
+    /**
+     * The SKD URL (for example skd://fb64ba7c5bd34bf188cf9ba76ab8370e) as extracted from the #EXT-X-KEY tag in the HLS playlist.
+     *
+     * @remarks
+     * <br/> - Only available for Fairplay license requests. The value will be `undefined` otherwise.
+     */
+    fairplaySkdUrl: string | undefined;
+}

package/lib/typescript/src/api/drm/ContentProtectionResponse.d.ts

@@ -0,0 +1,56 @@
+import type { CertificateRequest, ContentProtectionRequest, LicenseRequest } from './ContentProtectionRequest';
+/**
+ * The response, either of a license or for a certificate request.
+ * @public
+ */
+export interface ContentProtectionResponse {
+    /**
+     * The request for which the response is being returned.
+     */
+    request: ContentProtectionRequest;
+    /**
+     * The URL from which the response was returned. This might have been redirected transparently.
+     */
+    url: string;
+    /**
+     * The status code as returned in the HTTP response.
+     */
+    status: number;
+    /**
+     * The status text as returned in the HTTP response.
+     */
+    statusText: string;
+    /**
+     * The HTTP headers as returned by the server.
+     *
+     * @remarks
+     * <br/> - On web not all headers might be shown due to Cross Origin Resource Sharing restrictions.
+     */
+    headers: {
+        [headerName: string]: string;
+    };
+    /**
+     * The body of the response.
+     */
+    body: Uint8Array;
+}
+/**
+ * The response of a certificate request.
+ * @public
+ */
+export interface CertificateResponse extends ContentProtectionResponse {
+    /**
+     * The request for which the response is being returned.
+     */
+    request: CertificateRequest;
+}
+/**
+ * The response of a license request.
+ * @public
+ */
+export interface LicenseResponse extends ContentProtectionResponse {
+    /**
+     * The request for which the response is being returned.
+     */
+    request: LicenseRequest;
+}

package/lib/typescript/src/api/drm/barrel.d.ts

@@ -0,0 +1,5 @@
+export * from './ContentProtectionAPI';
+export * from './ContentProtectionIntegration';
+export * from './ContentProtectionIntegrationFactory';
+export * from './ContentProtectionRequest';
+export * from './ContentProtectionResponse';

package/lib/typescript/src/api/event/AdEvent.d.ts

@@ -0,0 +1,13 @@
+import type { Ad, AdBreak } from 'react-native-theoplayer';
+export interface AdEvent {
+    /**
+     * Type of ad event.
+     */
+    type: AdEventType;
+    /**
+     * The ad or adbreak for which the event was dispatched.
+     */
+    ad: Ad | AdBreak;
+}
+export declare const AdEventNames: readonly ["addadbreak", "removeadbreak", "adloaded", "adbreakbegin", "adbreakend", "adbreakchange", "updateadbreak", "addad", "adbegin", "adend", "updatead", "adloaded", "adfirstquartile", "admidpoint", "adthirdquartile", "adskip", "adimpression", "aderror", "admetadata", "adbuffering"];
+export declare type AdEventType = typeof AdEventNames[number];

package/lib/typescript/src/api/event/barrel.d.ts

@@ -1,2 +1,3 @@
 export * from './PlayerEvent';
 export * from './TrackEvent';
+export * from './AdEvent';

package/lib/typescript/src/api/source/SourceDescription.d.ts

@@ -10,6 +10,7 @@ import type { DashPlaybackConfiguration } from './dash/DashPlaybackConfiguration
 import type { DRMConfiguration } from './drm/DRMConfiguration';
 import type { HlsPlaybackConfiguration } from './hls/HlsPlaybackConfiguration';
 import type { AdDescription } from './ads/Ads';
+import type { ServerSideAdInsertionConfiguration } from "./ads/ssai/ServerSideAdInsertionConfiguration";
 export declare type Source = TypedSource;
 /**
  * A media resource or list of media resources.
@@ -265,4 +266,11 @@ export interface TypedSource extends BaseSource {
      * <br/> - Available since v2.15.0.
      */
     contentProtection?: DRMConfiguration;
+    /**
+     * The Server-side Ad Insertion parameters for the media resource.
+     *
+     * @remarks
+     * <br/> - Available since v2.12.0.
+     */
+    ssai?: ServerSideAdInsertionConfiguration;
 }

package/lib/typescript/src/api/source/ads/FreeWheelAdDescription.d.ts

@@ -0,0 +1,85 @@
+import type { AdDescription } from "./Ads";
+/**
+ * The possible ad unit types, represented by a value from the following list:
+ * <br/> - `'preroll'`: The linear ad will play before the content started.
+ * <br/> - `'midroll'`: The linear ad will play at a time offset during the content.
+ * <br/> - `'postroll'`: The linear ad will play after the content ended.
+ * <br/> - `'overlay'`: The non-linear ad.
+ *
+ * @public
+ */
+export declare type FreeWheelAdUnitType = 'preroll' | 'midroll' | 'postroll' | 'overlay';
+/**
+ * Represents a FreeWheel cue.
+ *
+ * @public
+ */
+export interface FreeWheelCue {
+    /**
+     * The ad unit type.
+     */
+    adUnit: FreeWheelAdUnitType;
+    /**
+     * Offset after which the ad break will start, in seconds.
+     */
+    timeOffset: number;
+}
+/**
+ * Describes a FreeWheel ad break request.
+ *
+ * @remarks
+ * <br/> - Available since v2.42.0.
+ *
+ * @public
+ */
+export interface FreeWheelAdDescription extends AdDescription {
+    /**
+     * The integration of this ad break.
+     */
+    integration: 'freewheel';
+    /**
+     * The FreeWheel ad server URL.
+     */
+    adServerUrl: string;
+    /**
+     * The duration of the asset, in seconds.
+     *
+     * @remarks
+     * <br/> - Optional for live assets.
+     */
+    assetDuration?: number;
+    /**
+     * The identifier of the asset.
+     *
+     * @remarks
+     * <br/> - Generated by FreeWheel CMS when an asset is uploaded.
+     */
+    assetId?: string;
+    /**
+     * The network identifier which is associated with a FreeWheel customer.
+     */
+    networkId: number;
+    /**
+     * The server side configuration profile.
+     *
+     * @remarks
+     * <br/> - Used to indicate desired player capabilities.
+     */
+    profile: string;
+    /**
+     * The identifier of the video player's location.
+     */
+    siteSectionId?: string;
+    /**
+     * List of cue points.
+     *
+     * @remarks
+     * <br/> - Not available in all FreeWheel modes.
+     */
+    cuePoints?: FreeWheelCue[];
+    /**
+     * A record of query string parameters added to the FreeWheel ad break request.
+     * Each entry contains the parameter name with associated value.
+     */
+    customData?: Record<string, string>;
+}

package/lib/typescript/src/api/source/ads/IMAAdDescription.d.ts

@@ -0,0 +1,25 @@
+import type { AdDescription, AdSource } from "./Ads";
+/**
+ * Describes a Google IMA ad break request.
+ *
+ * @public
+ */
+export interface IMAAdDescription extends AdDescription {
+    /**
+     * The integration of this ad break.
+     */
+    integration: 'google-ima';
+    /**
+     * The source of the ad
+     *
+     * @remarks
+     * <br/> - VAST, VMAP and VPAID are supported.
+     */
+    sources: string | AdSource;
+    /**
+     * Optional settings object for mapping verification vendors (google.ima.OmidVerificationVendor) to OMID Access Modes (google.ima.OmidAccessMode).
+     */
+    omidAccessModeRules?: {
+        [key: number]: string;
+    };
+}