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

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,
}
);
info

For complete examples 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.

warning

DRM Support: Currently, DRM downloading is only supported with DRM Cloud. We are working on adding support for other DRM providers.

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);