Remotion LabRemotion Lab
›Player›排查 Player 播放問題

排查 Player 播放問題

解決 Remotion Player 中的常見播放問題，包括黑色幀、音訊斷斷續續、意外暫停和畫面跳動等。

<Player> 的播放問題

如果你在 Player 中遇到媒體播放問題，例如：

  • 場景之間出現黑色幀
  • 音訊斷斷續續
  • 意外暫停
  • 畫面跳動

請閱讀此頁面。

確保遵循最佳實踐

1. 為媒體元件新增 pauseWhenBuffering

為 <Html5Audio>、<Html5Video>、<OffthreadVideo> 和 <Img> 元件新增 pauseWhenBuffering：

import { OffthreadVideo, Html5Audio, Img, Sequence, staticFile } from 'remotion';
 
export const MyComp: React.FC = () => {
  return (
    <>
      <Sequence from={0} durationInFrames={120}>
        <OffthreadVideo
          src={staticFile('video.mp4')}
          pauseWhenBuffering
        />
      </Sequence>
      <Sequence from={120} durationInFrames={60}>
        <Html5Audio
          src={staticFile('audio.mp3')}
          pauseWhenBuffering
        />
      </Sequence>
      <Sequence from={0} durationInFrames={300}>
        <Img
          src={staticFile('image.jpg')}
          pauseWhenLoading
        />
      </Sequence>
    </>
  );
};

2. 為 <Sequence> 使用 premountFor prop 以實現無縫過渡

import { Sequence, OffthreadVideo, staticFile } from 'remotion';
 
export const MyComp: React.FC = () => {
  return (
    <>
      <Sequence from={0} durationInFrames={120}>
        <OffthreadVideo src={staticFile('video1.mp4')} pauseWhenBuffering />
      </Sequence>
      {/* 在第 120 幀開始前 60 幀（即第 60 幀）就預先掛載 */}
      <Sequence from={120} durationInFrames={120} premountFor={60}>
        <OffthreadVideo src={staticFile('video2.mp4')} pauseWhenBuffering />
      </Sequence>
    </>
  );
};

3. 若 Player 已掛載，不要使用 prefetch()

prefetch() 應在 Player 掛載之前呼叫。如果 Player 已掛載，prefetch() 可能會造成干擾，因為它可能會在播放途中替換 URL。

import { prefetch } from 'remotion';
 
// 正確做法：在應用程式初始化時預取，Player 掛載之前
const { free } = prefetch('https://example.com/video.mp4');
 
// 當不再需要時釋放
// free();

4. 避免過度積極的 prefetch() 和預掛載

過多的預取和預掛載會快速消耗資源。建議根據實際需求謹慎使用。

啟用日誌記錄

你可以透過將 logLevel="trace" 新增至 <Player> 元件來觀察媒體的掛載、載入、搜尋和緩衝事件。

此功能在 v4.0.250 中引入。

import React from 'react';
import { Player } from '@remotion/player';
 
export const MyApp: React.FC = () => {
  return (
    <Player
      component={() => null}
      compositionHeight={1080}
      compositionWidth={1920}
      fps={30}
      durationInFrames={100}
      logLevel="trace"
    />
  );
};

注意：不要在正式環境中啟用此 prop，因為它可能導致效能下降。

要觀察預取事件，可以在 prefetch() 呼叫中新增 logLevel: "trace"（如果有的話）：

import { prefetch } from 'remotion';
 
prefetch('https://example.com/video.mp4', {
  logLevel: 'trace',
});

常見問題排查

場景切換時出現黑色幀

原因：下一個場景的媒體資源在顯示前還未載入完畢。

解決方案：

  1. 使用 premountFor 提前預掛載下一個場景
  2. 使用 pauseWhenBuffering 讓 Player 等待資源載入完成
  3. 使用 preloadVideo() 或 preloadAudio() 預先載入資源
import { preloadVideo } from '@remotion/preload';
import { staticFile } from 'remotion';
 
// 在應用程式載入時預先載入
preloadVideo(staticFile('scene2.mp4'));

音訊斷斷續續

原因：音訊緩衝不足，或多個音訊標籤同時播放超出瀏覽器限制。

解決方案：

  1. 為 <Html5Audio> 新增 pauseWhenBuffering
  2. 如果使用多個音訊標籤，調整 numberOfSharedAudioTags prop
<Player
  component={MyComp}
  numberOfSharedAudioTags={10}
  durationInFrames={300}
  compositionWidth={1920}
  compositionHeight={1080}
  fps={30}
/>

意外暫停

原因：通常是 pauseWhenBuffering 觸發的，表示有資源正在載入中。

解決方案：

  1. 啟用 logLevel="trace" 以確認是哪個資源觸發了緩衝
  2. 考慮使用 premountFor 提前預載入資源
  3. 確認資源 URL 可以正常存取

畫面跳動（卡頓）

原因：多種可能原因，包括過重的計算、同時載入太多資源等。

解決方案：

  1. 啟用 logLevel="trace" 觀察事件
  2. 減少同時播放的媒體數量
  3. 降低影片解析度或位元率
  4. 使用 prefetch() 在播放前預先下載資源

回報問題

我們已實作精確的相關事件日誌記錄，以便改善 Remotion 處理媒體播放的方式。歡迎你提交意見回饋。如果你想回報問題，請：

  1. 確保你使用的 Remotion 版本至少為 v4.0.302。舊版本有已知的錯誤。
  2. 確保你使用了上述的最佳實踐。
  3. 啟用日誌記錄，並在回報時附上播放過程中的所有日誌。

診斷清單

在回報問題之前，請確認以下事項：

  • Remotion 版本 >= v4.0.302
  • 所有媒體元件都有 pauseWhenBuffering prop
  • 使用 premountFor 為即將出現的場景預掛載
  • 沒有在 Player 掛載後才呼叫 prefetch()
  • 沒有過度積極地預掛載或預取
  • 已啟用 logLevel="trace" 並收集了完整日誌

另請參閱