@remotion/preload

此套件提供用於預載入資源的函式。雖然預載入對於渲染來說並非必要，但它可以幫助在 <Player /> 和 Studio 中實現無縫播放。

目前已實作以下函式：

函式	說明
`preloadVideo()`	預載入影片來源
`preloadAudio()`	預載入音訊來源
`preloadFont()`	預載入字體
`preloadImage()`	預載入圖片
`resolveRedirect()`	取得所有重定向後的最終 URL

@remotion/preload 的替代方案是 prefetch() API。請參閱 @remotion/preload vs prefetch() 來決定哪個更適合你的使用場景。

安裝

# 使用 Remotion CLI（推薦）
npx remotion add @remotion/preload
 
# 使用 npm
npm i --save-exact @remotion/preload@4.0.445
 
# 使用 pnpm
pnpm i @remotion/preload@4.0.445
 
# 使用 bun
bun i @remotion/preload@4.0.445
 
# 使用 yarn
yarn --exact add @remotion/preload@4.0.445

請確保 remotion 和所有 @remotion/* 套件都更新到相同版本。移除版本號前的 ^ 字元以避免版本衝突。

preloadVideo()

此函式會在 DOM 中預載入影片，使得當 <video> 標籤被掛載時，可以立即播放。

基本用法

import {preloadVideo} from '@remotion/preload';
 
const unpreload = preloadVideo('https://remotion.media/BigBuckBunny.mp4');
 
// 如果之後想要取消預載入
unpreload();

運作原理

Firefox：在文件的 <head> 中加入 <link rel="preload" as="video"> 標籤
其他瀏覽器：在文件的 <body> 中加入 <video preload="auto"> 標籤

處理重定向

如果影片 URL 重定向到另一個 URL，預載入原始 URL 將不起作用。如果你不確定 URL 是否會重定向，請使用 resolveRedirect() 以程式方式取得所有重定向後的最終 URL。

如果資源不支援 CORS，resolveRedirect() 將會失敗。如果資源重定向且不支援 CORS，你就無法預載入該資源。

以下程式碼片段會盡力預載入影片。如果無法解析重定向，則嘗試預載入原始 URL：

import {preloadVideo, resolveRedirect} from '@remotion/preload';
import {OffthreadVideo} from 'remotion';
 
// 此程式碼在頁面載入後立即執行
let urlToLoad =
  'https://player.vimeo.com/external/291648067.hd.mp4?s=94998971682c6a3267e4cbd19d16a7b6c720f345&profile_id=175&oauth2_token_id=57447761';
 
resolveRedirect(urlToLoad)
  .then((resolved) => {
    // 成功解析重定向，使用解析後的 URL
    urlToLoad = resolved;
  })
  .catch((err) => {
    // 無法解析重定向（例如因為不支援 CORS）
    console.log('Could not resolve redirect', err);
  })
  .finally(() => {
    // 無論如何，嘗試預載入原始或解析後的 URL
    preloadVideo(urlToLoad);
  });
 
// 此程式碼只在元件掛載後執行
const MyComp: React.FC = () => {
  // 如果元件沒有立即掛載，這將是解析後的 URL
  // 如果元件立即掛載，這將是原始 URL（此時預載入也無效）
  return <OffthreadVideo src={urlToLoad} />;
};

preloadAudio()

此函式會在 DOM 中預載入音訊，使得當 <audio> 標籤被掛載時，可以立即播放。

基本用法

import {preloadAudio} from '@remotion/preload';
 
const unpreload = preloadAudio(
  'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3'
);
 
// 如果之後想要取消預載入
unpreload();

運作原理

Firefox：在文件的 <head> 中加入 <link rel="preload" as="audio"> 標籤
其他瀏覽器：在文件的 <body> 中加入 <audio preload="auto"> 標籤

處理重定向

與影片的處理方式相同，可以搭配 resolveRedirect() 使用：

import {preloadAudio, resolveRedirect} from '@remotion/preload';
import {Audio} from 'remotion';
 
let urlToLoad =
  'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3';
 
resolveRedirect(urlToLoad)
  .then((resolved) => {
    urlToLoad = resolved;
  })
  .catch((err) => {
    console.log('Could not resolve redirect', err);
  })
  .finally(() => {
    preloadAudio(urlToLoad);
  });
 
const MyComp: React.FC = () => {
  return <Audio src={urlToLoad} />;
};

resolveRedirect()

追蹤 URL 的重定向（最常見於遠端影片或音訊），直到解析到最終 URL 並回傳它。

如果資源不支援 CORS，此函式將會拋出錯誤。

基本用法

import {resolveRedirect} from '@remotion/preload';
 
resolveRedirect(
  'https://player.vimeo.com/external/291648067.hd.mp4?s=94998971682c6a3267e4cbd19d16a7b6c720f345&profile_id=175&oauth2_token_id=57447761'
)
  .then((src) => {
    console.log(src);
    // "https://vod-progressive.akamaized.net/..."
  })
  .catch((err) => {
    console.log('Could not resolve redirect', err);
  });

解析並預載入影片的完整範例

import {preloadVideo, resolveRedirect} from '@remotion/preload';
import {OffthreadVideo} from 'remotion';
 
let urlToLoad =
  'https://player.vimeo.com/external/291648067.hd.mp4?s=94998971682c6a3267e4cbd19d16a7b6c720f345&profile_id=175&oauth2_token_id=57447761';
 
resolveRedirect(urlToLoad)
  .then((resolved) => {
    // 成功解析重定向，使用解析後的 URL 作為載入目標
    urlToLoad = resolved;
  })
  .catch((err) => {
    // 無法解析重定向，例如因為不支援 CORS
    console.log('Could not resolve redirect', err);
  })
  .finally(() => {
    // 無論如何，嘗試預載入原始或解析後的 URL
    preloadVideo(urlToLoad);
  });
 
const MyComp: React.FC = () => {
  // 如果元件沒有立即掛載，這將是解析後的 URL
  // 如果元件立即掛載，這將是原始 URL（此時預載入也無效）
  return <OffthreadVideo src={urlToLoad} />;
};

何時使用預載入

預載入特別有用於以下情況：

Player 元件：用戶可能在你的影片完全緩衝之前就點擊播放
Studio 預覽：在開發過程中確保媒體資源能夠即時顯示
切換場景：當影片從一個場景切換到另一個場景時，預先載入下一個場景的媒體

注意：預載入對於伺服器端渲染（使用 @remotion/renderer）沒有效果，因為渲染器會直接下載所需的所有資源。