remotion-interactivity

Remotion 마크업을 특정 방식으로 작성하면 Remotion Studio가 코드 구조를 인식하여 대화형으로 만들 수 있습니다:

• 항목을 클릭하여 선택 가능
• 드래그 앤 드롭, 크기 조절 및 회전 지원
• CSS 스타일 편집
• 키프레임 및 이징 값 편집 가능

마크업이 Studio에서 대화형으로 만들기에 너무 복잡하면 값이 회색으로 표시됩니다.

자체 타임라인이 있는 대화형 컴포넌트 선호

부모를 채우는 컴포넌트에는 Interactive.withSchema({wrapInSequence: true, layout: 'absolute-fill'})를 사용하세요. 래퍼는 시각적 루트와 타임라인 항목을 제공하고 기본적으로 오버플로를 잘라내므로 내부 컴포넌트는 프래그먼트를 반환할 수 있습니다. 타이밍, 사전 마운트, 크기 및 인스턴스별 스타일은 내보낸 컴포넌트에 배치합니다.

함께 속하는 시각적 요소는 동일한 컴포넌트에 유지하여 함께 이동하고 트리밍되도록 합니다. 내부 레이아웃 컨테이너는 여전히 정렬, 더 작은 영역 내 클리핑 또는 애니메이션 그룹을 제공할 수 있습니다. 장면만 채우는 컨테이너는 일반적으로 필요하지 않습니다. 자체 경계가 있는 카드, 텍스트 상자 및 SVG는 기본 layout: 'none'을 유지하고 style을 시각적 루트로 전달할 수 있습니다.

import {Video} from '@remotion/media';
import type React from 'react';
import {Interactive, useVideoConfig, type InteractivitySchema} from 'remotion';

type SceneProps = {
  readonly title: string;
};

const SceneInner: React.FC<SceneProps> = ({title}) => {
  const {fps} = useVideoConfig();

  return (
    <>
      <Video
        name="배경 영상"
        src="https://remotion.media/video.mp4"
        premountFor={fps}
        objectFit="cover"
        style={{width: '100%', height: '100%'}}
      />
      <Interactive.Div
        name="장면 제목"
        style={{
          position: 'absolute',
          left: 80,
          bottom: 80,
          color: 'white',
          fontFamily: 'Helvetica, Arial, sans-serif',
          fontSize: 80,
        }}
      >
        {title}
      </Interactive.Div>
    </>
  );
};

const sceneSchema = {
  title: {type: 'string', default: '', description: '제목'},
} as const satisfies InteractivitySchema;

export const Scene = Interactive.withSchema({
  Component: SceneInner,
  componentName: 'Scene',
  schema: sceneSchema,
  wrapInSequence: true,
  layout: 'absolute-fill',
});

스키마 필드 선택하기

스키마의 각 키는 Studio가 호출 지점에서 읽고 편집할 수 있는 prop입니다. 스키마에 없는 Props도 여전히 작동하지만 Studio에서는 편집할 수 없습니다. 키는 style.color와 같이 점 표기법을 사용할 수 있습니다.

유형	용도	키프레임 가능 여부
string	제목, 프롬프트 또는 코드 조각과 같은 문자열	아니요
number	선택적 min, max, step, integer가 있는 숫자	예
boolean	켜기/끄기 스위치	예 (hold)
color	CSS 색상 문자열	예
enum	각각 자체 중첩 스키마가 있는 variants 중에서 선택	선택 사항 (hold)
array	숫자, 색상, 열거형 등의 목록	아니요
asset	선택적 assetType이 있는 미디어 소스	아니요
font-family	CSS 글꼴 패밀리	아니요
font-weight	글꼴 두께	예
translate, scale, rotation-css, rotation-degrees, transform-origin	변환	예
uv-coordinate	요소의 정규화된 [x, y] 포인트	예
svg-path	SVG 경로 데이터	예
remotion-captions	Caption[] 데이터	아니요
hidden	컨트롤 밖에 유지되는 값	—

모든 필드에는 default가 필요하며 Studio에서 레이블로 표시하는 description이 있어야 합니다. keyframable: false로 설정하면 정적 컨트롤을 표시합니다.

콘텐츠 및 인스턴스별 모양(예: 텍스트와 강조 색상)을 노출합니다. style.translate, style.scale, style.rotate, style.transformOrigin 및 style.opacity에 대한 필드를 추가하지 마십시오. wrapInSequence: true가 이미 추가합니다.

루트의 CSS 속성을 인스턴스별로 편집 가능하게 만들려면 기본 제공 스키마 프래그먼트를 펼치십시오:

const cardSchema = {
  ...Interactive.textSchema, // style.color, style.fontSize, style.fontWeight, ...
  ...Interactive.backgroundSchema, // style.backgroundColor
  ...Interactive.borderRadiusSchema, // style.borderRadius, ...
} as const satisfies InteractivitySchema;

또한 사용 가능: Interactive.borderSchema, 및 캡션을 허용하는 컴포넌트용 Interactive.captionsSchema. React.ReactNode 자식을 허용하는 컴포넌트의 경우 ...Interactive.childrenSchema를 추가합니다. 자식 콘텐츠에 대한 컨트롤을 제공하며 더 풍부한 콘텐츠를 지원하도록 발전할 수 있습니다. 현재 기본값이 ''인 "텍스트" 레이블의 문자열 필드를 사용합니다. 컴포넌트에 문자열 전용 자식이 필요한 경우 대신 type: 'string'인 명시적 children 필드를 선언합니다. Interactive.textSchema는 타이포그래피 스타일을 제어합니다. childrenSchema는 콘텐츠를 제어합니다. 자식 프래그먼트는 baseSchema에 포함되지 않으며 사용자 정의 컴포넌트에 자동으로 추가되지 않습니다. 중첩 마크업 및 계산된 자식은 현재 읽기 전용입니다. text-content는 string 필드 유형의 더 이상 사용되지 않는 별칭입니다. 모든 옵션은 InteractivitySchema를 참조하십시오.

재사용 가능한 컴포넌트를 연결된 컴포지션으로 등록

중요한 장면과 재사용 가능한 컴포넌트를 자체 레이어 또는 애니메이션과 함께 독립형 컴포지션으로 등록합니다. Studio는 이를 연결된 컴포지션이라고 합니다. 부모 비디오와 동일한 컴포넌트 구현을 공유하면서 자체 타임라인에서 열 수 있습니다.

컴포넌트 내부에 필요한 스타일을 정의하고 글꼴을 로드하여 부모 없이도 작동하도록 합니다. 부모 독립성을 참조하십시오.

부모가 렌더링하는 동일한 내보낸 컴포넌트 참조를 등록합니다. 위의 예에서는 component={Scene}을 사용하고 SceneInner 또는 인라인 래퍼를 사용하지 마십시오. wrapInSequence: true를 사용하면 연결을 위해 추가 <Sequence>가 필요하지 않습니다.

import {Composition} from 'remotion';
import {Scene} from './Scene';

export const RemotionRoot = () => (
  <Composition
    id="Scene"
    component={Scene}
    width={1280}
    height={720}
    fps={30}
    durationInFrames={30}
    defaultProps={{
      title: '새로운 관점',
    }}
  />
);

고유 ID, 대표적인 인라인 기본값, 컴포넌트 미리보기에 적합한 크기, fps 및 duration을 선택합니다. 등록 기본값은 부모 인스턴스에서 props를 자동으로 복사하지 않습니다. 등록 및 추출 세부 정보는 연결된 컴포지션을 참조하십시오.

컴포넌트에 직접 타이밍 배치

이미 타이밍 props를 허용하는 하나의 컴포넌트 주위에 별도의 <Sequence>를 사용하지 마십시오. 기본 제공 대화형 컴포넌트와 wrapInSequence: true로 만든 사용자 정의 컴포넌트는 name, from, durationInFrames, trimBefore, playbackRate 및 premountFor를 직접 받을 수 있습니다.

<Scene
  name="오프닝 장면"
  from={30}
  durationInFrames={90}
  premountFor={fps}
  style={{opacity: 0.9}}
  title="새로운 관점"
/>

중복 시퀀스를 제거할 때는 해당 타이밍과 이름을 자식으로 이동합니다. 기존 자식 타이밍을 보존하고 오프셋을 덮어쓰거나 이중으로 적용하지 마십시오. 컴포넌트 내부의 useCurrentFrame() 호출은 로컬 프레임을 읽는 반면, 호출 지점의 스타일 표현식은 여전히 호출자의 프레임을 사용합니다. 애니메이션 스타일을 이동할 때 이 구분을 유지하십시오.

여러 형제에 대한 공유 타이밍을 제공하거나, 타이밍을 처리하지 않는 컴포넌트를 래핑하거나, 자식이 직접 받아들일 수 없는 크기를 제공하는 경우 <Sequence>를 유지합니다. 관리되는 루트는 useVideoConfig()에 대한 width 및 height도 허용합니다. 연속 레이아웃을 위해 <TransitionSeries.Sequence>를 유지합니다(전환 유무와 관계없이). 직접 from props는 이러한 동작을 대체하지 않습니다.

독립적으로 편집 가능한 모든 항목에 자체 JSX 노드 제공

Studio는 항목을 생성한 JSX 소스 노드를 편집합니다. 여러 런타임 항목이 동일한 JSX 노드에서 오는 경우 하나의 소스 편집 대상을 공유합니다.

자체적으로 편집 가능해야 하는 모든 컴포지션 등록, 클립, 장면, 레이어 또는 시퀀스에 대해 별도의 JSX 노드를 작성하고 해당 노드에 편집 가능한 props를 유지합니다. 이는 <Composition>, <Still>, 기본 제공 미디어 컴포넌트, <Sequence>, <TransitionSeries.Sequence> 및 사용자 정의 컴포넌트에 적용됩니다.

예를 들어 다음과 같이 편집 가능한 타임라인을 작성합니다:

import { TransitionSeries } from "@remotion/transitions";

<TransitionSeries>
  <TransitionSeries.Sequence name="소개" durationInFrames={90}>
    <Introduction />
  </TransitionSeries.Sequence>
  <TransitionSeries.Sequence name="데모" durationInFrames={150}>
    <Demo />
  </TransitionSeries.Sequence>
</TransitionSeries>

.map() 또는 기타 프로그래밍 방식 루프는 하나의 JSX 소스 노드에서 여러 런타임 항목을 생성합니다. 이는 시각화 막대 또는 입자와 같이 의도적으로 하나의 템플릿으로 제어되는 반복 출력에 적합합니다. Studio에서 인스턴스에 독립적인 ID 또는 이름, props, 메타데이터, 타이밍, 순서, 삭제 또는 복제가 필요한 경우에는 적합하지 않습니다.

Interactive를 사용하여 HTML 요소를 대화형으로 만들기

모든 HTML 및 SVG 요소(<Img> 제외, 이미 대화형임) 예: <div>는 Interactive를 사용하여 대화형으로 만들 수 있습니다:

<Interactive.Div
  name="인사말 카드"
  style={{fontSize: 80, padding: 24}}
>
  안녕하세요
</Interactive.Div>

이렇게 하면 Studio에서 스타일과 키프레임을 설정할 수 있습니다. 신중하게 사용하십시오. 컴포넌트에 요소가 많으면 타임라인이 지저분해질 수 있습니다.

인라인 텍스트 선호

텍스트가 고정되어 있고 한 번만 사용되는 경우 상수로 추출하는 대신 대화형 요소 내부에 직접 작성합니다.

// 👍 고정 복사본은 편집 가능한 상태 유지
<Interactive.Div name="제목">
  Remotion 모범 사례
</Interactive.Div>

텍스트가 동적이거나 재사용되는 경우에만 prop 또는 변수를 사용합니다.

대화형 요소에 설명적인 이름 부여

요소에 name prop을 추가하여 쉽게 식별할 수 있도록 합니다. 계산된 이름은 피하고 하드코딩합니다.

<>
  <Interactive.Div name="히어로 제목" style={{fontSize: 80}}>
    출시일
  </Interactive.Div>
  <Img name="아바타" src="https://remotion.media/image.jpeg" />
  <Video name="배경" src="https://remotion.media/video.mp4" />
  <Interactive.Div name="제목">
    출시일
  </Interactive.Div>
</>

모든 CSS 스타일을 인라인으로 유지

가장 좋은 방법은 일반 객체를 style에 전달하는 것입니다. 상수 참조, 객체 확산, 수학 없이 사용합니다.

<Interactive.Div
  style={{
    fontSize: 80,
    color: 'red',
  }}
>
  Hello World!
</Interactive.Div>

const baseStyle = useMemo(() => {
  return {
    fontSize: 12 // ❌ 인라인이 아닌 스타일은 지원되지 않음
  }
}, []);

<Interactive.Div
  style={{
    ...baseStyle, // ❌ 확산은 지원되지 않음
    color: RED, // ❌ 상수 참조는 지원되지 않음
    scale: frame * 10 // ❌ 수학은 지원되지 않음
  }}
>
  Hello World!
</Interactive.Div>

interpolate()를 사용하여 애니메이션 적용

변경되는 속성에 인라인 interpolate() 호출로 애니메이션을 작성합니다. 출력 범위, 이징, 외삽 및 output 속성은 하드코딩된 값을 사용해야 합니다.

입력 범위는 useVideoConfig()에서 직접 구조 분해된 durationInFrames, fps, width 및 height를 추가로 사용할 수 있습니다. durationInFrames와 같은 단순 식별자, 2 * fps 또는 fps * 2와 같은 숫자 곱셈, durationInFrames - 1과 같은 숫자 빼기가 지원됩니다.

const {fps, durationInFrames} = useVideoConfig();

// 👍 인라인 값은 표준화 및 키프레임화 가능
<Interactive.Div
  name="제품 카드"
  style={{
    color: 'white',
    fontSize: 80,
    scale: interpolate(frame, [0, fps], [0, 1], {
      easing: Easing.spring({damping: 200}),
      output: 'perceptual-scale',
      extrapolateLeft: 'clamp',
      extrapolateRight: 'clamp'
    }),
    rotate: interpolate(frame, [0, 1 * fps], ['0deg', '20deg'], {
      easing: Easing.spring({damping: 200}),
      extrapolateLeft: 'clamp',
      extrapolateRight: 'clamp'
    }),
    translate: interpolate(
      frame,
      [durationInFrames - 30, durationInFrames],
      ['0px 0px', '0px 120px'],
      {
        easing: Easing.spring({damping: 200}),
        extrapolateLeft: 'clamp',
        extrapolateRight: 'clamp'
      }
    ),
  }}
>
  Hello World!
</Interactive.Div>

interpolate() 호출을 함수로 추출하지 마십시오. 추출하면 Studio에서 보간을 인식할 수 없게 됩니다.

<Video> 및 <Audio>와 같은 미디어 요소를 제어하고 SIP 스타일 구문을 사용하여 청각적 특성을 대화형으로 설정할 수 있습니다:

<Video
  name="내레이션"
  src="narration.mp3"
  volume={interpolate(
    frame,
    [0, 2 * fps],
    [0, 1],
    {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'}
  )}
  playbackRate={interpolate(
    frame,
    [0, 30],
    [1, 2],
    {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'}
  )}
  muted={false}
/>

startFrom 및 endAt와 같은 미디어 요소 prop은 Studio에서 편집할 수 있지만 키프레임을 지정할 수는 없습니다.

동등한 대안보다 <Img>를 선호

<Interactive.Img>는 없습니다. <Img>는 이미 대화형입니다.

<Img
  name="사용자 아바타"
  src="https://remotion.media/image.jpeg"
  style={{borderRadius: 20}}
/>

<Img>를 <img> 또는 CSS background-image가 있는 <Interactive.Div>보다 선호합니다. <Img>는 Studio에서 속성을 읽고 src를 편집하는 기본 지원을 제공합니다.

<Interactive.Div>보다 <Interactive.Thumbnail> 선호

<Interactive.Thumbnail>은 일반 <Interactive.Div>보다 Studio에서 더 나은 미리보기 동작을 제공합니다.