视频下载与离线播放功能允许用户将视频内容下载到本地设备，并在无网络连接的环境下进行播放。React Native SDK 支持下载 MP4 和 HLS 格式的视频，并提供了一整套 API，用于处理任务创建、状态管理（暂停、恢复、删除）、进度查询和离线播放。

初始化下载模块 #

下载相关的全局参数需在 SDK 初始化阶段进行配置。建议根据 App 的存储策略和剩余空间预警值进行合理设置。

import { initEnv } from '@volcengine/react-native-vod-player';

initEnv({
  // ... 其他初始化配置
  DownloadDirectory: 'videos', // （可选）指定下载存储的子目录
  MaxDownloadOperationCount: 3, // （可选）最大同时下载任务数，默认为 1
  LimitFreeDiskSize: 1024 * 1024 * 500, // （可选）磁盘剩余空间低于 500MB 时禁止下载
});

创建与开启下载任务 #

播放器 SDK 支持播放 DirectUrl 视频源和 Vid 视频源。与之对应，播放器 SDK 也提供了不同数据源的下载能力。

import { createVidDownloadTask, ResolutionType, resumeDownloadTask } from '@volcengine/react-native-vod-player';

const task = await createVidDownloadTask(
  'video_vid_here',  // 视频vid
  ResolutionType.SuperHigh, // 指定下载超高清清晰度
  'video_playAuthToken_here',   // 播放凭证
);

resumeDownloadTask(task); // 开始下载

import { createUrlDownloadTask, resumeDownloadTask } from '@volcengine/react-native-vod-player';

const task = await createUrlDownloadTask(
  ['http://example.com/video.mp4'], // 支持主备 URL
  'your_custom_cache_key',          // 必须提供一个唯一的缓存 Key
  'optional_video_id_for_tracking'// 关联的视频vid
);

resumeDownloadTask(task); // 开始下载

管理下载任务 #

单任务控制 #

通过调用以下方法对单个 DownloadTask 实例进行操作。

• 开始/恢复：resumeDownloadTask(task)
• 暂停：suspendDownloadTask(task)
• 删除任务及文件：cancelDownloadTask(task)（执行后本地已下载文件将被彻底清除）

批量控制与恢复状态 #

当 App 重新启动时，你可以调用 loadAllTasks 获取所有历史任务（包括未完成的任务），以便在 UI 列表上展示。

import { loadAllTasks, resumeAllDownloadTasks } from '@volcengine/react-native-vod-player';

// 加载历史任务列表
const allTasks = await loadAllTasks();

// 批量操作
resumeAllDownloadTasks();  // 开始所有等待中/暂停的任务
suspendAllDownloadTasks(); // 全部暂停
cancelAllDownloadTasks();  // 全部删除并清空磁盘

设置监听器与更新 UI #

设置全局监听器 setDownloadListener，它是 UI 层获取进度、刷新状态的唯一入口。

import { setDownloadListener, DownloadTask, DownloadTaskState } from '@volcengine/react-native-vod-player';

setDownloadListener({
  onDownloadProgress: (task, receivedSize, totalSize) => {
    const progress = totalSize > 0 ? receivedSize / totalSize : 0;
    console.log(`任务 ${task.getCacheKey()} 下载进度: ${(progress * 100).toFixed(2)}%`);
    // 在这里更新你的 UI
  },
  onDownloadStateChanged: (task, state) => {
    console.log(`任务 ${task.getCacheKey()} 状态变更为: ${DownloadTaskState[state]}`);
    // 在这里更新你的 UI
  },
  onDownloadComplete: (task, error) => {
    if (error) {
      console.error(`任务 ${task.getCacheKey()} 下载失败:`, error);
    } else {
      console.log(`任务 ${task.getCacheKey()} 下载完成！`);
    }
  },
  // 其他回调...
});

离线播放 #

离线播放的逻辑是“自动命中”的。只要设置的播放源参数与下载时完全一致，且开启了缓存播放开关，播放器会优先读取本地文件。

• 开启缓存读取开关：设置播放源必须调用 player.enablePlayCachedSource()。
• 标识匹配：
  • Vid 模式：vid、resolution、playAuthToken 需保持一致。
  • URL 模式：urls、cacheKey、vid 需保持一致。

// 1. 在设置播放源之前开启缓存读取开关
player.enablePlayCachedSource();

// 2. 构造与下载任务相同的数据源
// 3. 设置给播放器，SDK 将自动定位到本地文件
player.setVideoSource(videoSource);
player.play();

参考信息 #

下载任务属性 DownloadTask #

任务状态枚举 DownloadTaskState #

使用示例 #

以下是一个简化的下载管理页面的示例。

import React, { useState, useEffect } from 'react';
import { View, Text, Button, FlatList } from 'react-native';
import { 
  loadAllTasks, 
  createVidDownloadTask,
  resumeDownloadTask,
  suspendDownloadTask,
  cancelDownloadTask,
  setDownloadListener,
  DownloadTask,
  ResolutionType 
} from '@volcengine/react-native-vod-player';

const DownloadManagerScreen = () => {
  const [tasks, setTasks] = useState<DownloadTask[]>([]);

  // 初始化时加载所有任务并设置监听器
  useEffect(() => {
    const init = async () => {
      const existingTasks = await loadAllTasks();
      setTasks(existingTasks);
    };

    init();

    setDownloadListener({
      onDownloadProgress: (task, receivedSize, totalSize) => {
        // 更新特定任务的进度 UI
        setTasks(currentTasks => 
          currentTasks.map(t => t.getCacheKey() === task.getCacheKey() ? task : t)
        );
      },
      onDownloadStateChanged: (task, state) => {
        // 更新任务列表
        setTasks(currentTasks => 
          currentTasks.map(t => t.getCacheKey() === task.getCacheKey() ? task : t)
        );
      },
      // ... 其他回调
    });
  }, []);
  
  const handleAddTask = async () => {
    const newTask = await createVidDownloadTask('your_vid_here', ResolutionType.SuperHigh, 'your_playAuthToken_here');
    if (newTask) {
      setTasks(prevTasks => [...prevTasks, newTask]);
      resumeDownloadTask(newTask); // 创建后立即开始
    }
  };

  const renderTaskItem = ({ item }: { item: DownloadTask }) => (
    <View style={{ padding: 10, borderBottomWidth: 1, borderColor: '#ccc' }}>
      <Text>ID: {item.getVideoId() || item.getCacheKey()}</Text>
      <Text>进度: {(item.progress * 100).toFixed(2)}%</Text>
      <Text>状态: {item.state}</Text>
      <View style={{ flexDirection: 'row', justifyContent: 'space-around', marginTop: 5 }}>
        <Button title="开始/恢复" onPress={() => resumeDownloadTask(item)} />
        <Button title="暂停" onPress={() => suspendDownloadTask(item)} />
        <Button title="删除" onPress={() => {
          cancelDownloadTask(item);
          setTasks(prev => prev.filter(t => t.getCacheKey() !== item.getCacheKey()));
        }} />
      </View>
    </View>
  );

  return (
    <View>
      <Button title="添加新下载任务" onPress={handleAddTask} />
      <FlatList
        data={tasks}
        renderItem={renderTaskItem}
        keyExtractor={item => item.getCacheKey() || ''}
      />
    </View>
  );
};