Remotion LabRemotion Lab
›Player›解決自動播放問題

解決自動播放問題

了解瀏覽器的自動播放限制，以及如何正確使用 Remotion Player 避免觸發瀏覽器政策。

解決自動播放問題

瀏覽器對未經使用者互動便播放音訊的網站設有限制。請閱讀以下內容，了解如何正確使用 Remotion Player 以避免觸發瀏覽器政策。

限制最嚴格的瀏覽器是 Mobile Safari。如果你的組合在 Mobile Safari 上可以正常播放，在其他地方通常也不會有問題。

從使用者事件觸發播放

如果你在頁面載入時自動播放音訊（透過 <Audio>、<Html5Audio>、<Video>、<OffthreadVideo> 或 <Html5Video> 標籤），瀏覽器將會封鎖音訊。

因此，如果你的影片包含音訊，<Player> 的 autoPlay prop 是不建議使用的。

建議改為顯示播放按鈕，或使用 controls prop。

將事件傳遞給 play() 或 toggle() 方法

如果你不使用預設控制項，請確保呼叫 .play() 是從使用者手勢（例如滑鼠點擊）觸發的。你應該會從中取得 JavaScript 事件，例如 MouseEvent。將此事件傳遞給 play() 或 toggle() 函式，以允許音訊自動播放。

import { PlayerRef } from '@remotion/player';
import { useRef } from 'react';
 
export const App: React.FC = () => {
  const ref = useRef<PlayerRef>(null);
 
  return (
    <button
      onClickCapture={(e) => {
        const { current } = ref;
        // 將事件傳遞給 .play() 或 .toggle()
        current?.play(e);
      }}
    >
      播放
    </button>
  );
};

注意：請優先使用 onClickCapture 事件而非 onClick 事件，以確保事件傳播在 Safari 中正常運作。

在影片開始後才進入的媒體

包含音訊且在未經使用者互動的情況下播放的媒體需要特別注意。請考慮以下情境：

import { AbsoluteFill, Html5Audio, OffthreadVideo, Sequence, staticFile } from 'remotion';
 
export const MyComp = () => {
  return (
    <AbsoluteFill>
      {/* 情況 1：立即播放的 <Audio> 標籤 */}
      <Sequence from={0} durationInFrames={120}>
        <Html5Audio src={staticFile('audio1.mp3')} />
      </Sequence>
 
      {/* 情況 2：120 幀後播放的 <Audio> 標籤 */}
      <Sequence from={120} durationInFrames={120}>
        <Html5Audio src={staticFile('audio2.mp3')} />
      </Sequence>
 
      {/* 情況 3：120 幀後播放的 <OffthreadVideo> 標籤 */}
      <Sequence from={120} durationInFrames={120}>
        <OffthreadVideo src={staticFile('video.mp4')} />
      </Sequence>
    </AbsoluteFill>
  );
};

這裡有三種不同的情況：

  1. 立即播放的 <Audio> 標籤 — 沒問題，因為我們有使用者互動。
  2. 120 幀後播放的 <Audio> 標籤 — 可能受到瀏覽器自動播放政策的影響，但有解決方案 → 使用 numberOfSharedAudioTags prop
  3. 120 幀後播放的 <OffthreadVideo> 標籤 — 可能受到瀏覽器自動播放政策的影響，可能會限制影片帶音訊播放 → 處理自動播放失敗

使用 numberOfSharedAudioTags prop

預設情況下，Remotion 會掛載 5 個輔助 <audio> 標籤，這些標籤會在第一次使用者互動時「預熱」。如果 <Audio> 標籤在第一次使用者互動後才播放，它將被掛載至其中一個輔助標籤並允許播放。

如果你同時播放超過 5 個 <Audio> 標籤，可以透過將 numberOfSharedAudioTags prop 傳遞給 <Player> 來增加輔助標籤的數量，否則將會拋出錯誤。

<Player
  component={MyComp}
  numberOfSharedAudioTags={10}
  // ...其他 props
/>

處理自動播放失敗

如果瀏覽器因為影片包含音訊且未從使用者互動開始，而封鎖影片的自動播放：

預設行為：影片將被靜音並無音訊播放，並會在主控台顯示一則訊息。

自訂行為：你可以使用 <OffthreadVideo> 和 <Video> 的 onAutoPlayError prop 來處理自動播放失敗：

import { OffthreadVideo, staticFile } from 'remotion';
import type { PlayerRef } from '@remotion/player';
 
export const MyComp: React.FC<{
  playerRef: React.RefObject<PlayerRef>;
}> = ({ playerRef }) => {
  return (
    <OffthreadVideo
      src={staticFile('video.mp4')}
      onAutoPlayError={() => {
        // 暫停 Player
        playerRef.current?.pause();
      }}
    />
  );
};

在此範例中，Player 被直接暫停。如果使用者再次按下播放，由於此次是透過使用者互動啟動的，影片可以帶音訊播放。

你可以顯示一個海報並附上提示文字，例如「點擊以繼續」。

瀏覽器何時會限制自動播放？

這並非完全可預測的行為。

在以使用者手勢播放影片後，Safari 會允許更多媒體播放一段時間。然而，WebKit 的程式碼顯示這也取決於裝置的省電模式或熱壓力。

因此，較好的做法是嘗試帶音訊播放影片，並優雅地處理失敗情況。

另請參閱