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.
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();
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 videoconfig
- configuration object (see Configuration)
see DownloadStatus
type in API Reference
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,
}
);
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 andcertificateUrl
The plugin automatically handles DRM key download and caching for offline playback. You don't need to manage DRM keys separately.
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:
- Using
onDownloadProgress
event
import { useEvent } from "@TheWidlarzGroup/react-native-video-stream-downloader";
useEvent("onDownloadProgress", (downloadsStatus: Array<DownloadStatus>) => {
console.log(downloadsStatus);
});
- using
getDownloadsStatus
function
import { getDownloadsStatus } from "@TheWidlarzGroup/react-native-video-stream-downloader";
const downloadsStatus: Array<DownloadStatus> = getDownloadsStatus();
- 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
.
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>
);
};
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);