Configuration

Global Config

name	type	default	description
updateFrequencyMS	number	1000	How often to update the download progress
maxParallelDownloads	number	5	How many files to download in parallel

To update global config, you can use setConfig function.

import {
  setConfig,
  Config,
  getConfig,
} from "@TheWidlarzGroup/react-native-video-stream-downloader";

setConfig({ updateFrequencyMS: 1000, maxParallelDownloads: 5 });

const config: Config = getConfig();

Download Config

name	type	default	description
includeAllTracks	boolean	false	Include all (audio and text) tracks from stream in the download
expiresAt	number	0	Date when the download will expire. Once download is expired, it will be deleted from the device.
drm	object	undefined	DRM configuration for protected content (see DRM Config)
metadata	object	undefined	Custom metadata to store with the download (see Metadata)

import { DownloadOptions } from "@TheWidlarzGroup/react-native-video-stream-downloader";

const downloadOptions: DownloadOptions = {
  includeAllTracks: true,
  expiresAt: new Date(Date.now() + 1000 * 60 * 60 * 24 * 30), // 30 days
};

// download stream with download options
const downloadStatus = await downloadStream(
  "https://example.com/stream.m3u8",
  downloadOptions
);

Metadata

The metadata field allows you to store custom data with your download. You can add any key-value pairs, and they will be preserved and returned in the DownloadedAsset object.

Reserved Keys

Some metadata keys are used by the plugin:

• title: Used to name the downloaded file on the device

Example Metadata Usage

const downloadOptions: DownloadOptions = {
  metadata: {
    title: "My Video Title", // Used by plugin for file naming
    category: "movies",
    genre: "action",
    year: 2024,
    rating: 4.5,
    tags: ["action", "adventure"],
    customData: {
      userId: "12345",
      playlistId: "playlist_1",
      isFavorite: true,
    },
  },
};

const downloadStatus = await downloadStream(
  "https://example.com/video.m3u8",
  downloadOptions
);

Accessing Metadata in Downloaded Assets

import { getDownloadedAssets } from "@TheWidlarzGroup/react-native-video-stream-downloader";

const assets = getDownloadedAssets();
const asset = assets[0];

console.log(asset.metadata?.title); // "My Video Title"
console.log(asset.metadata?.category); // "movies"
console.log(asset.metadata?.customData?.userId); // "12345"

Metadata Type

The metadata field uses the Metadata type which allows any string key with any value:

interface Metadata {
  title?: string; // Used by plugin for file naming
  [key: string]: unknown; // Any other key-value pairs
}

DRM Config

When downloading DRM-protected content, you need to provide DRM configuration:

drm?: {
  /**
   * The license server URL.
   * @Platform Android - Widevine License Server URL
   * @Platform iOS - FairPlay License Server URL
   */
  licenseServer: string;

  /**
   * Optional URL to the DRM certificate.
   * @Platform iOS - *required* FairPlay Certificate URL
   * @Platform Android - not required for Widevine
   */
  certificateUrl?: string;

  /**
   * Additional headers to include in the DRM request.
   */
  headers: { [key: string]: string };
}

Example DRM Configuration

import { Platform } from "react-native";

const drmConfig = {
  licenseServer:
    Platform.OS === "ios"
      ? "https://your-fairplay-license-server.com/license"
      : "https://your-widevine-license-server.com/license",
  certificateUrl:
    Platform.OS === "ios"
      ? "https://your-fairplay-certificate.com/certificate"
      : undefined,
  headers: {
    "x-drm-usertoken": "your-drm-token",
  },
};

const downloadOptions: DownloadOptions = {
  drm: drmConfig,
};

const downloadStatus = await downloadStream(
  "https://example.com/drm-video.m3u8",
  downloadOptions
);