@remotion/player 使用範例

最基本範例

最簡單的 Player 用法，只需提供必要的 props：

import { Player } from "@remotion/player";
import { MyVideo } from "./remotion/MyVideo";
 
export const App: React.FC = () => {
  return (
    <Player
      component={MyVideo}
      durationInFrames={120}
      compositionWidth={1920}
      compositionHeight={1080}
      fps={30}
    />
  );
};

加入控制列

透過加入 controls prop 顯示播放控制列：

import { Player } from "@remotion/player";
import { MyVideo } from "./remotion/MyVideo";
 
export const App: React.FC = () => {
  return (
    <Player
      component={MyVideo}
      durationInFrames={120}
      compositionWidth={1920}
      compositionHeight={1080}
      fps={30}
      controls
    />
  );
};

循環播放

加入 loop prop 讓影片在結束後自動重播：

import { Player } from "@remotion/player";
import { MyVideo } from "./remotion/MyVideo";
 
export const App: React.FC = () => {
  return (
    <Player
      component={MyVideo}
      durationInFrames={120}
      compositionWidth={1920}
      compositionHeight={1080}
      fps={30}
      controls
      loop
    />
  );
};

更改尺寸

使用 style prop 指定 Player 的顯示尺寸：

import { Player } from "@remotion/player";
import { MyVideo } from "./remotion/MyVideo";
 
export const App: React.FC = () => {
  return (
    <Player
      component={MyVideo}
      durationInFrames={120}
      compositionWidth={1920}
      compositionHeight={1080}
      fps={30}
      controls
      loop
      style={{
        width: 1280,
        height: 720,
      }}
    />
  );
};

請參閱尺寸縮放以了解更多縮放 Player 的方法。

加入自動播放

使用 autoPlay prop 讓影片在載入後自動開始播放：

import { Player } from "@remotion/player";
import { MyVideo } from "./remotion/MyVideo";
 
export const App: React.FC = () => {
  return (
    <Player
      component={MyVideo}
      durationInFrames={120}
      compositionWidth={1920}
      compositionHeight={1080}
      fps={30}
      controls
      loop
      style={{
        width: 1280,
        height: 720,
      }}
      autoPlay
    />
  );
};

提示：你需要留意瀏覽器的自動播放政策。在大多數瀏覽器中，無法自動播放含有音訊的音訊檔案或影片。

以程式化方式控制播放器

透過 ref 可以從外部程式化地控制 Player，例如跳至特定影格：

import { Player, PlayerRef } from "@remotion/player";
import { useCallback, useRef } from "react";
import { MyVideo } from "./remotion/MyVideo";
 
export const App: React.FC = () => {
  const playerRef = useRef<PlayerRef>(null);
 
  const seekToMiddle = useCallback(() => {
    const { current } = playerRef;
    if (!current) {
      return;
    }
    current.seekTo(60);
  }, []);
 
  return (
    <Player
      ref={playerRef}
      component={MyVideo}
      durationInFrames={120}
      compositionWidth={1920}
      compositionHeight={1080}
      fps={30}
    />
  );
};

PlayerRef 提供以下方法：

play() — 開始播放
pause() — 暫停播放
toggle(e?) — 切換播放/暫停狀態
seekTo(frame) — 跳至指定影格
getCurrentFrame() — 取得目前影格編號
requestFullscreen() — 進入全螢幕
exitFullscreen() — 離開全螢幕
isFullscreen() — 是否處於全螢幕狀態
setVolume(num) — 設定音量（0 到 1）
getVolume() — 取得目前音量
isMuted() — 是否已靜音
isPlaying() — 是否正在播放
mute() — 靜音
unmute() — 取消靜音
pauseAndReturnToPlayStart() — 暫停並返回播放起始點

監聽事件

透過 ref 監聽 Player 發出的各種事件：

import { Player, PlayerRef } from "@remotion/player";
import { useEffect, useRef, useState } from "react";
import { MyVideo } from "./remotion/MyVideo";
 
export const App: React.FC = () => {
  const playerRef = useRef<PlayerRef>(null);
  const [currentFrame, setCurrentFrame] = useState(0);
 
  useEffect(() => {
    const { current } = playerRef;
    if (!current) {
      return;
    }
 
    // 監聽時間更新事件
    const onTimeUpdate = (e: { detail: { frame: number } }) => {
      setCurrentFrame(e.detail.frame);
    };
 
    current.addEventListener("timeupdate", onTimeUpdate);
 
    return () => {
      current.removeEventListener("timeupdate", onTimeUpdate);
    };
  }, []);
 
  return (
    <div>
      <Player
        ref={playerRef}
        component={MyVideo}
        durationInFrames={120}
        compositionWidth={1920}
        compositionHeight={1080}
        fps={30}
        controls
      />
      <p>目前影格：{currentFrame}</p>
    </div>
  );
};

Player 支援以下事件：

play — 播放開始時觸發
pause — 暫停時觸發
ended — 影片播放結束時觸發（非循環模式）
timeupdate — 時間更新時觸發，event.detail.frame 為目前影格
seeked — 跳轉完成時觸發，event.detail.frame 為目標影格
fullscreenchange — 全螢幕狀態改變時觸發，event.detail.isFullscreen 為是否全螢幕
volumechange — 音量改變時觸發，event.detail.volume 為新音量值
error — 發生錯誤時觸發，event.detail.error 為錯誤物件
waiting — 進入緩衝等待狀態時觸發
resume — 從緩衝等待狀態恢復時觸發

傳遞 inputProps

透過 inputProps 向合成傳遞動態資料，並請務必使用 useMemo 避免不必要的重新渲染：

import { Player } from "@remotion/player";
import { useState, useMemo } from "react";
import { MyVideo } from "./remotion/MyVideo";
 
export const App: React.FC = () => {
  const [text, setText] = useState("Hello World");
 
  const inputProps = useMemo(() => {
    return {
      text,
    };
  }, [text]);
 
  return (
    <div>
      <input
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="輸入文字..."
      />
      <Player
        component={MyVideo}
        durationInFrames={120}
        compositionWidth={1920}
        compositionHeight={1080}
        fps={30}
        controls
        inputProps={inputProps}
      />
    </div>
  );
};

使用自訂播放控制

你可以隱藏預設控制列並建立自己的播放控制介面：

import { Player, PlayerRef } from "@remotion/player";
import { useRef, useCallback } from "react";
import { MyVideo } from "./remotion/MyVideo";
 
export const App: React.FC = () => {
  const playerRef = useRef<PlayerRef>(null);
 
  const handlePlay = useCallback((e: React.MouseEvent) => {
    // 傳遞事件以降低自動播放限制的機率
    playerRef.current?.play(e);
  }, []);
 
  const handlePause = useCallback(() => {
    playerRef.current?.pause();
  }, []);
 
  const handleSeekTo = useCallback((frame: number) => {
    playerRef.current?.seekTo(frame);
  }, []);
 
  return (
    <div>
      <Player
        ref={playerRef}
        component={MyVideo}
        durationInFrames={120}
        compositionWidth={1920}
        compositionHeight={1080}
        fps={30}
        style={{ width: "100%" }}
      />
      <div style={{ display: "flex", gap: 8, marginTop: 8 }}>
        <button onClick={handlePlay}>播放</button>
        <button onClick={handlePause}>暫停</button>
        <button onClick={() => handleSeekTo(0)}>回到開頭</button>
        <button onClick={() => handleSeekTo(60)}>跳至第 60 格</button>
      </div>
    </div>
  );
};