Skip to main content

How to use

Initialize and Authorize​

To use Video Stream Downloader plugin, you need to initialize and authorize it. You can do it in any place in your code.

warning

You need to initialize and authorize Video Stream Downloader plugin before using it. Otherwise, you will get an error.

import {
  registerPlugin,
  isRegistered,
} from "@TheWidlarzGroup/react-native-video-stream-downloader";

const initializePlugin = async () => {
  const success = await registerPlugin("YOUR_API_KEY");

  if (!success) {
    throw new Error("Video Stream Downloader plugin is not authorized");
  }
};

initializePlugin();
info

Getting API Key: You can obtain an API key either through the SDK platform or by contacting TheWidlarzGroup directly at hi@thewidlarzgroup.com.

If you want to check if plugin is already authorized, you can use isRegistered function.

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

const isAuthorized = isRegistered();

Download Stream or Video​

After you initialize and authorize plugin, you can download stream or video.

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

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

downloadStream function has two parameters:

  • url - url of the stream or video
  • config - configuration object (see Configuration)

see DownloadStatus type in API Reference

warning

downloadStream function returns downloadStatus object. You may want to save it to play downloaded stream/video later. function return value once download is added to the queue not when download is finished.

Downloading DRM-Protected Content​

To download DRM-protected content, you need to provide DRM configuration in the download options.

DRM Configuration Example​

Using License Server​

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

const drmConfig = {
  licenseServer: "https://your-license-server.com/license",
  certificateUrl: "https://your-certificate.com/cert", // required for FairPlay
  headers: {
    "x-drm-usertoken": "your-drm-token",
  },
};

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

Using Custom License Acquisition (iOS Only)​

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

const drmConfig = {
  certificateUrl: "https://your-certificate.com/cert", // required for FairPlay
  getLicense: (spcString, contentId, licenseUrl, loadedLicenseUrl) => {
    const base64spc = Base64.encode(spcString);
    const formData = new FormData();
    formData.append("spc", base64spc);

    return fetch(`https://license.pallycon.com/ri/licenseManager.do`, {
      method: "POST",
      headers: {
        "pallycon-customdata-v2": "your-custom-header",
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: formData,
    })
      .then((response) => response.text())
      .then((response) => response)
      .catch((error) => console.error("Error", error));
  },
};

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

For a complete, runnable example with platform-specific configuration, see the Examples section.

Platform-Specific DRM Requirements​

  • Android: Uses Widevine DRM - requires licenseServer URL
  • iOS: Uses FairPlay DRM - requires both licenseServer URL and certificateUrl
info

The plugin automatically handles DRM key download and caching for offline playback. You don't need to manage DRM keys separately.

Selecting Tracks (Video/Audio/Subtitles)​

You can pre-select specific tracks to optimize size and control quality/language. First, inspect available tracks:

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

const tracks = await getAvailableTracks("https://example.com/manifest.m3u8");

Then, pass chosen track IDs to downloadStream:

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

const selectedVideo = tracks.video?.find((v) => v.resolution?.height === 720);

await downloadStream("https://example.com/manifest.m3u8", {
  tracks: {
    video: selectedVideo ? [selectedVideo.id] : [],
    audio: tracks.audio?.map((a) => a.id) ?? [],
    text: tracks.text?.map((t) => t.id) ?? [],
  },
});

See the dedicated Track Selection guide for more patterns (e.g., lowest bitrate only).

Updating Download Progress​

Download Status​

You can get download progress in two ways:

  1. Using onDownloadProgress event
import { useEvent } from "@TheWidlarzGroup/react-native-video-stream-downloader";

useEvent("onDownloadProgress", (downloadsStatus: Array<DownloadStatus>) => {
  console.log(downloadsStatus);
});
  1. using getDownloadsStatus function
import { getDownloadsStatus } from "@TheWidlarzGroup/react-native-video-stream-downloader";

const downloadsStatus: Array<DownloadStatus> = getDownloadsStatus();
  1. using getDownloadStatus function
import { getDownloadStatus } from "@TheWidlarzGroup/react-native-video-stream-downloader";

const downloadStatus: DownloadStatus = getDownloadStatus(downloadId);

Download End Event​

to listen for download end event, you can use onDownloadEnd event.

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

useEvent("onDownloadEnd", (downloadStatus: DownloadStatus) => {
  console.log(downloadStatus);
});

Pause, Resume, Cancel Download​

You can pause, resume or cancel download using pauseDownload, resumeDownload and cancelDownload functions.

import {
  pauseDownload,
  resumeDownload,
  cancelDownload,
} from "@TheWidlarzGroup/react-native-video-stream-downloader";

const download = await downloadStream(
  "https://example.com/stream.m3u8",
  config
);
const downloadId = download.id;

// pause download
pauseDownload(downloadId);

// resume download
resumeDownload(downloadId);

// cancel download
cancelDownload(downloadId);

Playing Downloaded Assets​

To play downloaded assets, you need to use react-native-video component and provide the downloadedAsset.pathToFile as the source.uri.

info

Platform Differences:

  • Android: pathToFile is a URL that automatically points to the cached video file
  • iOS: pathToFile is the actual file path to the downloaded video file

Example: Playing a Downloaded Asset​

import React, { useState, useEffect } from "react";
import { View } from "react-native";
import Video from "react-native-video";
import { getDownloadedAssets } from "@TheWidlarzGroup/react-native-video-stream-downloader";

const VideoPlayer = () => {
  const [downloadedAssets, setDownloadedAssets] = useState([]);
  const [selectedAsset, setSelectedAsset] = useState(null);

  useEffect(() => {
    // Get all downloaded assets
    const assets = getDownloadedAssets();
    setDownloadedAssets(assets);

    // Select the first asset for playback (you can implement your own selection logic)
    if (assets.length > 0) {
      setSelectedAsset(assets[0]);
    }
  }, []);

  if (!selectedAsset) {
    return (
      <View>
        <Text>No downloaded assets available</Text>
      </View>
    );
  }

  return (
    <View style={{ flex: 1 }}>
      <Video
        source={{ uri: selectedAsset.pathToFile }}
        style={{ flex: 1 }}
        controls={true}
        resizeMode="contain"
      />
    </View>
  );
};

Example: Playing Asset by URL​

If you want to play a specific asset by its original URL:

import React, { useState, useEffect } from "react";
import { View } from "react-native";
import Video from "react-native-video";
import { getDownloadedAssets } from "@TheWidlarzGroup/react-native-video-stream-downloader";

const VideoPlayer = ({ originalUrl }) => {
  const [assetPath, setAssetPath] = useState(null);

  useEffect(() => {
    // Find the downloaded asset by original URL
    const assets = getDownloadedAssets();
    const asset = assets.find((a) => a.url === originalUrl);

    if (asset) {
      setAssetPath(asset.pathToFile);
    }
  }, [originalUrl]);

  if (!assetPath) {
    return (
      <View>
        <Text>Asset not found or not downloaded</Text>
      </View>
    );
  }

  return (
    <View style={{ flex: 1 }}>
      <Video
        source={{ uri: assetPath }}
        style={{ flex: 1 }}
        controls={true}
        resizeMode="contain"
      />
    </View>
  );
};
warning

The plugin does not automatically play downloaded content. You must explicitly use react-native-video with the correct pathToFile from the downloaded asset.

Manage Downloaded Assets​

Get All Downloaded Assets​

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

const downloadedAssets: Array<DownloadedAsset> = getDownloadedAssets();

see DownloadedAsset type in API Reference

Delete All Downloaded Assets​

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

deleteAllDownloadedAssets();

Delete Downloaded Asset​

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

const downloadedAssets: Array<DownloadedAsset> = getDownloadedAssets();

deleteDownloadedAsset(downloadedAssets[0].id);