Remotion LabRemotion Lab
›Player›媒體鍵支援（Web MediaSession API）

媒體鍵支援（Web MediaSession API）

了解 Remotion Player 如何透過 browserMediaControlsBehavior prop 處理鍵盤媒體鍵和瀏覽器媒體控制項。

媒體鍵行為（Web MediaSession API）

此文件說明以下使用者操作的行為：

  • 按下鍵盤上的播放 / 暫停（⏯️）或上一首（⏮）按鈕
  • 使用其他控制項，例如 Chrome 使用者頭像旁的內建控制項來控制播放

這些行為由 browserMediaControlsBehavior prop 控制。底層使用的 Web API 是 Media Session API。

此功能在 Remotion v4.0.221 中引入。

模式

prevent-media-session（預設）

import { Player } from '@remotion/player';
 
export const MyComp: React.FC = () => {
  return (
    <Player
      browserMediaControlsBehavior={{
        mode: 'prevent-media-session',
      }}
      component={() => null}
      durationInFrames={120}
      compositionWidth={1280}
      compositionHeight={720}
      fps={30}
    />
  );
};

在此模式下，Remotion 不會對使用者的媒體鍵做出反應，而是將任何鍵盤操作對應至空操作（no-op）。

這樣可以防止以下問題：Player 被暫停，但音訊標籤在使用者按下鍵盤的播放 / 暫停按鈕時被恢復。此問題在 Remotion v4.0.221 之前存在。

register-media-session

import { Player } from '@remotion/player';
 
export const MyComp: React.FC = () => {
  return (
    <Player
      browserMediaControlsBehavior={{
        mode: 'register-media-session',
      }}
      component={() => null}
      durationInFrames={120}
      compositionWidth={1280}
      compositionHeight={720}
      fps={30}
    />
  );
};

在此模式下，Remotion 將使用 Media Session API 註冊以下處理程序：

  • 當使用者按下鍵盤的播放 / 暫停按鈕時
    • 切換 Remotion Player 的狀態
  • 當使用者按下鍵盤的上一首按鈕時
    • 跳至影片開始處
  • 當使用者按下鍵盤的快進按鈕時
    • 向前跳 10 秒
  • 當使用者按下鍵盤的倒退按鈕時
    • 向後跳 10 秒

此外，Remotion 將對搜尋事件做出反應，並告知裝置當前播放位置和持續時間。

do-nothing

import { Player } from '@remotion/player';
 
export const MyComp: React.FC = () => {
  return (
    <Player
      browserMediaControlsBehavior={{
        mode: 'do-nothing',
      }}
      component={() => null}
      durationInFrames={120}
      compositionWidth={1280}
      compositionHeight={720}
      fps={30}
    />
  );
};

恢復至 Remotion v4.0.221 之前的行為。Remotion 不會對任何媒體鍵做出反應，讓瀏覽器自行處理媒體鍵。

這會導致使用者可以透過按下鍵盤的播放 / 暫停按鈕恢復任何媒體標籤，而 Remotion Player 不會同步恢復。

使用多個 <Player> 時

Remotion 的 register-media-session 處理程序設計為只與一個已掛載的 Player 搭配使用。系統不定義哪個 Player 對媒體鍵做出反應。

使用多個 Player 時，將其中一個設定為 do-nothing 模式，另一個設定為 register-media-session 模式，以明確地只為一個 Player 設定媒體鍵。

import { Player } from '@remotion/player';
import { MyVideoA } from './MyVideoA';
import { MyVideoB } from './MyVideoB';
 
export const MultiplePlayersExample: React.FC = () => {
  return (
    <>
      {/* 主要 Player：使用媒體鍵控制 */}
      <Player
        component={MyVideoA}
        browserMediaControlsBehavior={{ mode: 'register-media-session' }}
        durationInFrames={120}
        compositionWidth={1280}
        compositionHeight={720}
        fps={30}
      />
 
      {/* 次要 Player：不響應媒體鍵 */}
      <Player
        component={MyVideoB}
        browserMediaControlsBehavior={{ mode: 'do-nothing' }}
        durationInFrames={120}
        compositionWidth={1280}
        compositionHeight={720}
        fps={30}
      />
    </>
  );
};

如果你希望所有 Player 都對媒體鍵做出反應，需要使用 do-nothing 模式，並使用 Player API 自行實作此行為：

import { Player, PlayerRef } from '@remotion/player';
import React, { useEffect, useRef } from 'react';
import { MyVideo } from './MyVideo';
 
export const AllPlayersRespondToMediaKeys: React.FC = () => {
  const playerRef1 = useRef<PlayerRef>(null);
  const playerRef2 = useRef<PlayerRef>(null);
 
  useEffect(() => {
    if ('mediaSession' in navigator) {
      navigator.mediaSession.setActionHandler('play', () => {
        playerRef1.current?.play();
        playerRef2.current?.play();
      });
      navigator.mediaSession.setActionHandler('pause', () => {
        playerRef1.current?.pause();
        playerRef2.current?.pause();
      });
    }
  }, []);
 
  return (
    <>
      <Player
        ref={playerRef1}
        component={MyVideo}
        browserMediaControlsBehavior={{ mode: 'do-nothing' }}
        durationInFrames={120}
        compositionWidth={1280}
        compositionHeight={720}
        fps={30}
      />
      <Player
        ref={playerRef2}
        component={MyVideo}
        browserMediaControlsBehavior={{ mode: 'do-nothing' }}
        durationInFrames={120}
        compositionWidth={1280}
        compositionHeight={720}
        fps={30}
      />
    </>
  );
};

在 Remotion Studio 中

從 v4.0.221 開始，行為設定為 register-media-session。在此之前的行為類似於 do-nothing。

模式比較

模式媒體鍵行為適用場景
prevent-media-session（預設）將媒體鍵對應至空操作大多數情況的推薦選項
register-media-session完整支援媒體鍵控制想讓鍵盤媒體鍵控制 Player
do-nothing讓瀏覽器自行處理自訂多 Player 媒體鍵行為

另請參閱