自定义预加载功能允许您在业务逻辑的任何时机，为任意视频主动发起预加载任务。当播放器后续需要播放该视频时，会优先使用已预加载的缓存数据。这能极大地减少起播缓冲、加快首帧速度，从而显著提升用户的播放体验。本文将为您介绍如何使用自定义预加载功能，包括添加和取消预加载任务。

自定义预加载 vs. 预加载策略

尽管两种功能都旨在提升起播性能，但它们适用于不同的业务场景。

• 预加载策略：适用于可预测的、顺序性的列表播放场景，例如短视频信息流。在此场景下，SDK 的策略会为您自动管理预加载队列。
• 自定义预加载：适用于不可预测的、由用户行为驱动的场景。例如，在一个短剧应用中，用户可能在剧集卡片上浏览。当用户在一个卡片上停留或表现出兴趣时，您可以立即为该剧集视频发起一个自定义预加载任务。如果用户随后决定点击播放，由于视频数据已在本地，播放将能实现“秒开”。

添加自定义预加载任务

您可以根据播放源的类型（Vid、DirectUrl 或 VideoModel），调用相应的接口来添加预加载任务。您可以指定预加载的数据大小，并通过回调函数来监听任务的生命周期。调用成功后，接口会返回一个唯一的任务 ID taskId，您可以后续使用它来取消该任务。

Vid 模式

import { preloadVidSource } from '@volcengine/react-native-vod-player';
 
// 为一个 VidSource 发起预加载任务
const taskId = preloadVidSource(
    vidSource,
    { preloadSize: 800 * 1024}, // 可选：预加载配置
                                // `preloadSize` 是希望缓存的数据大小，单位为字节。默认为 800KB。
    // 可选：用于监听任务生命周期的回调函数
    {
    // `onLoadSuccess`：当请求的数据量成功缓存后触发
    // `cacheSize`：实际缓存的数据大小，单位为字节
    onLoadSuccess: (source, cacheSize) => {
      const message = `preload success: ${source.vid()}... (cache size: ${Math.round(
        cacheSize / 1024,
      )}KB)`;
      console.log(`[PreLoad] ${message}`);
    },
    // `onLoadFail`：预加载过程中发生错误时触发
    onLoadFail: (source, error) => {
      const message = `preload fail: ${source.vid()}... - ${
        error.message || error.code || 'unknown error'
      }`;
      console.log(`[PreLoad] ${message}`);
    },
    // `onLoadCancel`：任务在完成前被取消时触发
    onLoadCancel: source => {
      const message = `preload cancel: ${source.vid()}...`;
      console.log(`[PreLoad] ${message}`);
    },
})

DirectUrl 模式

使用 DirectUrlSource 时，请确保播放源对象中的 cacheKey 是一个对于视频 URL 而言唯一且稳定的标识符，SDK 将使用它来识别缓存。

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

// 为一个 DirectUrlSource 发起预加载任务
const taskId = preloadDirectUrlSource(
    directUrlSource, 
    { preloadSize: 800 * 1024}, // 可选：预加载配置
                                // `preloadSize` 是希望缓存的数据大小，单位为字节。默认为 800KB。
    // 可选：用于监听任务生命周期的回调函数
    {
    // `onLoadSuccess`：当请求的数据量成功缓存后触发
    // `cacheSize`：实际缓存的数据大小，单位为字节
    onLoadSuccess: (source, cacheSize) => {
      const message = `preload success: ${source.cacheKey}... (cache size: ${Math.round(
        cacheSize / 1024,
      )}KB)`;
      console.log(`[PreLoad] ${message}`);
    },
    // `onLoadFail`：预加载过程中发生错误时触发
    onLoadFail: (source, error) => {
      const message = `preload fail: ${source.cacheKey}... - ${
        error.message || error.code || 'unknown error'
      }`;
      console.log(`[PreLoad] ${message}`);
    },
    // `onLoadCancel`：任务在完成前被取消时触发
    onLoadCancel: source => {
      const message = `preload cancel: ${source.cacheKey}...`;
      console.log(`[PreLoad] ${message}`);
    },
})

VideoModel 模式

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

// 为一个 VideoModelSource 发起预加载任务
const taskId = preloadVideoModelSource(
    videoModelSource,
    { preloadSize: 800 * 1024}, // 可选：预加载配置
                                // `preloadSize` 是希望缓存的数据大小，单位为字节。默认为 800KB。
    // 可选：用于监听任务生命周期的回调函数
    {
    // `onLoadSuccess`：当请求的数据量成功缓存后触发
    // `cacheSize`：实际缓存的数据大小，单位为字节
    onLoadSuccess: (source, cacheSize) => {
      const message = `preload success: ${source.vid()}... (cache size: ${Math.round(
        cacheSize / 1024,
      )}KB)`;
      console.log(`[PreLoad] ${message}`);
    },
    // `onLoadFail`：预加载过程中发生错误时触发
    onLoadFail: (source, error) => {
      const message = `preload fail: ${source.vid()}... - ${
        error.message || error.code || 'unknown error'
      }`;
      console.log(`[PreLoad] ${message}`);
    },
    // `onLoadCancel`：任务在完成前被取消时触发
    onLoadCancel: source => {
      const message = `preload cancel: ${source.vid()}...`;
      console.log(`[PreLoad] ${message}`);
    },
})

命中预加载缓存

您无需进行任何额外操作来使用缓存。当您调用 play() 并传入一个播放源时，播放器会自动检测该播放源（通过 vid 或 cacheKey 匹配）是否存在有效的缓存。如果有，播放将直接从缓存数据开始，实现快速起播。

取消预加载任务

如果用户的行为表明一个已发起但尚未完成的预加载任务不再需要（例如，用户划走了视频卡片），您可以取消该任务以节省网络带宽和系统资源。

取消指定任务

使用添加任务时返回的 taskId，可以取消一个特定的预加载任务。

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

// `taskId` 是您在调用 `preload...` 函数时获取到的字符串
cancelPreloadByTaskId(taskId);

取消所有任务

您也可以一次性取消所有正在进行的预加载任务。这适用于用户离开某个需要预加载功能的页面或场景。

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

// 取消所有正在进行的预加载任务
cancelAllPreloads()