Remotion Player

Remotion Player는 React 컴포넌트로, Remotion 영상을 React 앱 어디든 임베드할 수 있게 해준다. 미리보기·웹 SaaS·쇼케이스 등에 사용.

---

📦 설치

npm i @remotion/player

---

🚀 기본 사용법

import { Player } from "@remotion/player";
import { MyComposition } from "./MyComposition";

export const App = () => {
  return (
    <Player
      component={MyComposition}
      durationInFrames={300}     // 10초 @ 30fps
      compositionWidth={1920}
      compositionHeight={1080}
      fps={30}
      controls                  // 자체 컨트롤 UI 표시
    />
  );
};

---

🎛️ 주요 Props

prop	설명
component	렌더링할 React 컴포넌트
durationInFrames	총 프레임 수
compositionWidth / compositionHeight	컴포지션 크기
fps	프레임레이트
controls	true면 자체 컨트롤 표시
loop	true면 끝나면 처음으로
autoplay	자동 재생
muted	음소거
playbackRate	배속 (1=원본)
inputProps	컴포지션에 주입할 props
style	컨테이너 스타일 (크기, 위치)
showVolumeControls	음량 컨트롤 표시

---

🔄 Ref로 제어

PlayerRef로 외부에서 재생·일시정지·탐색 제어:

import { Player, PlayerRef } from "@remotion/player";
import { useRef } from "react";

const App = () => {
  const playerRef = useRef<PlayerRef>(null);

  return (
    <>
      <button onClick={() => playerRef.current?.play()}>Play</button>
      <button onClick={() => playerRef.current?.pause()}>Pause</button>
      <button onClick={() => playerRef.current?.seekTo(60)}>1초로 이동</button>

      <Player
        ref={playerRef}
        component={MyComposition}
        durationInFrames={300}
        compositionWidth={1920}
        compositionHeight={1080}
        fps={30}
      />
    </>
  );
};

PlayerRef 메서드

메서드	설명
play()	재생
pause()	일시정지
seekTo(frame)	특정 프레임으로 이동
seekTo(time)	특정 시간(초)으로 이동
getCurrentFrame()	현재 프레임 반환
isPlaying()	재생 중 여부
mute() / unmute()	음소거/해제
setVolume(volume)	음량 설정 (0~1)

---

🖼️ 컨테이너 크기 맞추기

컴포지션은 1920×1080이지만 화면에 맞게 스케일 다운:

<Player
  component={MyComposition}
  durationInFrames={300}
  compositionWidth={1920}
  compositionHeight={1080}
  fps={30}
  style={{ width: "100%", maxWidth: 800, aspectRatio: "16/9" }}
/>

📌 Player는 컴포지션 비율 유지하며 컨테이너에 맞춰 자동 스케일

---

🔁 이벤트 핸들러

<Player
  component={MyComposition}
  durationInFrames={300}
  compositionWidth={1920}
  compositionHeight={1080}
  fps={30}
  onPlay={() => console.log("Play")}
  onPause={() => console.log("Pause")}
  onEnded={() => console.log("Ended")}
  onError={(e) => console.error("Error", e)}
  onTimeUpdate={(frame) => console.log("Frame", frame)}
  onClick={() => console.log("Clicked")}
/>

---

🎨 커스텀 컨트롤

controls={false}로 숨기고 직접 UI 만들기:

<Player
  ref={playerRef}
  component={MyComposition}
  durationInFrames={300}
  compositionWidth={1920}
  compositionHeight={1080}
  fps={30}
  controls={false}
  // ...
/>
<div>
  <button onClick={() => playerRef.current?.play()}>▶</button>
  <button onClick={() => playerRef.current?.pause()}>⏸</button>
</div>

---

⚠️ 알아둘 점

• 렌더링 ≠ 미리보기 — Player는 실시간 미리보기일 뿐, mp4로 저장되지 않음. mp4로 만들려면 Client-side Rendering 사용
• Props 동적 변경 — inputProps 변경 시 자동 리렌더 (useEffect 의존성 처리 필요할 수 있음)
• 메모리 — 큰 컴포지션 + 여러 인스턴스는 메모리 많이 사용

---

📚 영역 구분

• Studio: Remotion Studio
• 앱 통합: Remotion Building Apps
• 한글 hub: Remotion Studio & Player

상위 문서: ← Remotion Studio & Player 출처: Remotion 공식 문서 — Player 한글화 (2026-07-29) 공급사: Remotion AG

변경 이력

날짜	변경
2026-07-29	초판 작성 (공식 Player 가이드 한글화)
2026-07-29	메타데이터 블록을 본문 하단으로 이동