react-native-theoplayer 1.6.1 → 1.7.1

package/src/api/ads/AdsConfiguration.ts

@@ -0,0 +1,76 @@
+/**
+ * Describes the configuration of advertisement.
+ *
+ * @public
+ */
+import type { GoogleImaConfiguration } from './GoogleImaConfiguration';
+
+export interface AdsConfiguration {
+  /**
+   * Allows configuring which mime types are allowed during ad playback.
+   *
+   * @remarks
+   * <br/> - This feature is only available for Google IMA.
+   * <br/> - If set to an array, all ads with another mime types will be ignored.
+   * <br/> - If set to `undefined` the ad system will pick media based on the browser's capabilities.
+   *
+   * @defaultValue `undefined`
+   */
+  allowedMimeTypes?: string[];
+
+  /**
+   * Whether an advertisement UI is shown.
+   *
+   * @defaultValue `true`
+   */
+  uiEnabled?: boolean;
+
+  /**
+   * Whether media files of mid- and postrolls are preloaded.
+   *
+   * @remarks
+   * <br/> - This feature is only available for Google IMA.
+   *
+   * @defaultValue `'midroll-and-postroll'`
+   */
+  preload?: AdPreloadType;
+
+  /**
+   * The iframe policy for VPAID ads.
+   *
+   * @remarks
+   * <br/> - This feature is only available for Google IMA and SpotX.
+   *
+   * @defaultValue `'enabled'`
+   */
+  vpaidMode?: VPAIDMode;
+
+  /**
+   * The Google IMA configuration.
+   *
+   * @internal
+   */
+  googleImaConfiguration?: GoogleImaConfiguration;
+}
+
+/**
+ * The ad preloading strategy, represented by a value from the following list:
+ * <br/> - `'none'`: Ads are not preloaded.
+ * <br/> - `'midroll-and-postroll'`: Mid- and postrolls are preloaded.
+ *
+ * @remarks
+ * <br/> - For Google IMA, preloading starts 4 seconds before ad playback.
+ *
+ * @public
+ */
+export type AdPreloadType = 'none' | 'midroll-and-postroll';
+
+/**
+ * The iframe policies for VPAID ads, represented by a value from the following list:
+ * <br/> - `'enabled'`: Ads will load in a cross domain iframe. This disables access to the site via JavaScript. Ads that require a friendly iframe will fail to play.
+ * <br/> - `'insecure'`: Ads will load in a friendly iframe. This allows access to the site via JavaScript.
+ * <br/> - `'disabled'`: Ads will error when requested.
+ *
+ * @public
+ */
+export type VPAIDMode = 'enabled' | 'insecure' | 'disabled';

package/src/api/ads/CompanionAd.ts

@@ -0,0 +1,65 @@
+/**
+ * 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/src/api/ads/GoogleDai.ts

@@ -0,0 +1,32 @@
+/**
+ * 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/src/api/ads/GoogleImaAd.ts

@@ -0,0 +1,86 @@
+/**
+ * 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/src/api/ads/GoogleImaConfiguration.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/src/api/ads/barrel.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/src/api/barrel.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/src/api/config/PlayerConfiguration.ts

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

package/src/api/drm/ContentProtectionAPI.ts

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

package/src/api/drm/ContentProtectionIntegration.ts

@@ -0,0 +1,93 @@
+import type { CertificateRequest, LicenseRequest } from './ContentProtectionRequest';
+import type { CertificateResponse, LicenseResponse } from './ContentProtectionResponse';
+
+/**
+ * A synchronous or asynchronous return type
+ *
+ * @public
+ */
+export type MaybeAsync<T> = T | PromiseLike<T>;
+
+export 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/src/api/drm/ContentProtectionIntegrationFactory.ts

@@ -0,0 +1,16 @@
+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/src/api/drm/ContentProtectionRequest.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 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/src/api/drm/ContentProtectionResponse.ts

@@ -0,0 +1,62 @@
+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/src/api/drm/barrel.ts

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

package/src/api/event/AdEvent.ts

@@ -0,0 +1,117 @@
+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 const AdEventNames = [
+  /**
+   * Dispatched when an ad break is added.
+   */
+  'addadbreak',
+
+  /**
+   * Dispatched when an ad break is removed.
+   */
+  'removeadbreak',
+
+  /**
+   * Dispatched when an ad is loaded.
+   */
+  'adloaded',
+
+  /**
+   * Dispatched when an ad break begins.
+   */
+  'adbreakbegin',
+
+  /**
+   * Dispatched when an ad break ends.
+   */
+  'adbreakend',
+
+  /**
+   * Dispatched when an ad break changes.
+   */
+  'adbreakchange',
+
+  /**
+   * Dispatched when an ad break is updated.
+   */
+  'updateadbreak',
+
+  /**
+   * Dispatched when an ad is added.
+   */
+  'addad',
+
+  /**
+   * Dispatched when an ad begins.
+   */
+  'adbegin',
+
+  /**
+   * Dispatched when an ad ends.
+   */
+  'adend',
+
+  /**
+   * Dispatched when an ad is updated.
+   */
+  'updatead',
+
+  /**
+   * Dispatched when an ad is loaded.
+   */
+  'adloaded',
+
+  /**
+   * Dispatched when an ad reaches the first quartile.
+   */
+  'adfirstquartile',
+
+  /**
+   * Dispatched when an ad reaches the mid point.
+   */
+  'admidpoint',
+
+  /**
+   * Dispatched when an ad reaches the third quartile.
+   */
+  'adthirdquartile',
+
+  /**
+   * Dispatched when an ad is skipped.
+   */
+  'adskip',
+
+  /**
+   * Dispatched when an ad counts as an impression.
+   */
+  'adimpression',
+
+  /**
+   * Dispatched when an ad error occurs.
+   */
+  'aderror',
+
+  /**
+   * Dispatched when an ads list is loaded.
+   */
+  'admetadata',
+
+  /**
+   * Dispatched when the ad has stalled playback to buffer.
+   */
+  'adbuffering'
+] as const;
+
+export type AdEventType = typeof AdEventNames[number];

package/src/api/event/barrel.ts

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