Communitygithub.com

bardu-rgb/reels

Remotion 마크업을 구조화하여 상호작용성을 부여합니다.

reels란 무엇인가요?

이 스킬은 Remotion 스튜디오가 코드 구조를 인식하여 상호작용할 수 있도록 Remotion 마크업을 특정한 방식으로 작성하는 방법을 가이드합니다. 개발자는 이 스킬을 통해 요소 클릭 선택, 드래그 앤 드롭, 크기 조절, 회전, CSS 스타일 편집, 키프레임 및 이징 값 편집 등이 가능한 인터랙티브한 컴포넌트를 만들 수 있습니다. 주로 Remotion Studio 환경에서 사용되며, `Interactive.withSchema({wrapInSequence: true})`를 통해 커스텀 장면이나 카드, 타이틀과 같은 시각적 컴포넌트를 자체 타임라인과 함께 편집 가능하게 만듭니다. 모든 CSS 스타일은 인라인으로 유지하고, 애니메이션은 `interpolate()` 호출을 속성에 직접 작성해야 합니다. 또한 각각의 독립적으로 편집 가능한 아이템은 고유한 JSX 노드를 가져야 하며, `.map()`과 같은 반복문은 의도된 템플릿 제어에만 사용해야 합니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트가 Remotion 프로젝트의 상호작용성과 편집 가능성을 최적화하는 데 유용합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bardu-rgb/reels/tree/HEAD/.agents/skills/remotion-interactivity

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

미리보기

스킬 README에서

reels preview

문서

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

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

마크업이 Studio에서 인터랙티브하게 만들기에 너무 복잡하면 값이 회색으로 표시됩니다.

자체 타임라인을 가진 인터랙티브 컴포넌트 선호

Interactive.withSchema({wrapInSequence: true})를 사용하여 커스텀 장면, 카드, 타이틀 및 기타 시각적 컴포넌트의 props가 인스턴스별로 편집 가능하도록 만듭니다. InteractivitySchema에서 의미 있는 콘텐츠 및 외형 컨트롤을 노출합니다. 장식적인 구현 세부 사항은 컴포넌트 내부에 유지합니다.

컴포넌트는 style을 받아 하나의 시각적 루트로 전달해야 합니다. 변형, 자르기 또는 불투명도가 모든 레이어에 영향을 미쳐야 하는 경우 공유 루트를 유지합니다. 레이아웃이나 애니메이션을 변경하지 않고 스타일을 기존 요소로 이동할 수 있는 경우 중복된 내부 래퍼를 평탄화합니다.

import type React from 'react';
import {Interactive, type InteractivitySchema} from 'remotion';

type LowerThirdProps = {
  readonly children: string;
  readonly accentColor: string;
  readonly style?: React.CSSProperties;
};

const LowerThirdInner: React.FC<LowerThirdProps> = ({
  children,
  accentColor,
  style,
}) => {
  return (
    <Interactive.Div
      style={{
        position: 'absolute',
        left: 80,
        bottom: 80,
        display: 'flex',
        alignItems: 'center',
        gap: 20,
        backgroundColor: 'white',
        borderRadius: 16,
        padding: '20px 32px',
        color: 'black',
        fontFamily: 'Helvetica, Arial, sans-serif',
        fontSize: 48,
        fontWeight: 600,
        ...style,
      }}
    >
      <div
        style={{
          width: 8,
          alignSelf: 'stretch',
          borderRadius: 4,
          backgroundColor: accentColor,
        }}
      />
      {children}
    </Interactive.Div>
  );
};

const lowerThirdSchema = {
  children: {type: 'text-content', default: '', description: '텍스트'},
  accentColor: {
    type: 'color',
    default: '#0b84f3',
    description: '강조 색상',
  },
} as const satisfies InteractivitySchema;

export const LowerThird = Interactive.withSchema({
  Component: LowerThirdInner,
  componentName: '<LowerThird>',
  schema: lowerThirdSchema,
  wrapInSequence: true,
});

주입된 style을 컴포넌트 내부로 전달하는 것은 필수입니다. 편집 가능한 스타일은 컴포넌트 호출 사이트에서 인라인으로 유지합니다.

스키마 필드 선택

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

타입용도키프레임 가능
text-content제목과 같은 텍스트아니오
number선택적 min, max, step, integer 포함 숫자예
boolean켜기/끄기 스위치예 (hold)
colorCSS 색상 문자열예
enum각각 자체 중첩 스키마를 가진 variants 중에서 선택선택 (hold)
array숫자, 색상, 열거형 등의 리스트아니오
asset선택적 assetType이 있는 미디어 소스아니오
font-familyCSS 글꼴 패밀리아니오
font-weight글꼴 두께예
translate, scale, rotation-css, rotation-degrees, transform-origin변형예
uv-coordinate요소의 정규화된 [x, y] 포인트예
svg-pathSVG 경로 데이터예
remotion-captionsCaption[] 데이터아니오
hidden컨트롤에서 제외된 값—

모든 필드는 default가 필요하고 description이 있어야 하며, Studio가 이를 레이블로 표시합니다. 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. 모든 옵션은 InteractivitySchema를 참조하십시오.

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

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

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

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

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

export const RemotionRoot = () => (
  <Composition
    id="LowerThird"
    component={LowerThird}
    width={1280}
    height={720}
    fps={30}
    durationInFrames={30}
    defaultProps={{
      children: 'Jane Doe, Product Designer',
      accentColor: '#0b84f3',
    }}
  />
);

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

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

이미 타이밍 props를 허용하는 하나의 컴포넌트 주위에 별도의 <Sequence>를 사용하지 마십시오. wrapInSequence: true로 만든 내장 인터랙티브 컴포넌트 및 커스텀 컴포넌트는 name, from, durationInFrames, trimBefore, playbackRate 및 premountFor를 직접 받을 수 있습니다.

<LowerThird
  name="아래쪽 자막"
  from={30}
  durationInFrames={90}
  accentColor="#0b84f3"
>
  Jane Doe, Product Designer
</LowerThird>

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

<Sequence>는 여러 형제에 대해 공유 타이밍을 제공하거나, useVideoConfig()의 크기를 재정의하거나, 타이밍을 처리하지 않는 컴포넌트를 래핑할 때 유지합니다. 연속 레이아웃에는 <Series.Sequence>를, 전환에는 <TransitionSeries.Sequence>를 유지하십시오. 직접 from props는 이러한 동작을 대체하지 않습니다.

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

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

각 컴포지션 등록, 클립, 장면, 레이어 또는 시퀀스가 자체적으로 편집 가능해야 하는 경우 별도의 JSX 노드를 작성하고 해당 노드에 편집 가능한 props를 유지합니다. 이는 <Composition>, <Still>, 내장 미디어 컴포넌트, <Sequence>, <Series.Sequence>, <TransitionSeries.Sequence> 및 커스텀 컴포넌트에 적용됩니다.

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

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

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

Interactive를 사용하여 HTML 요소를 인터랙티브하게 만들기

<Img>(이미 인터랙티브)를 제외한 모든 HTML 및 SVG 요소(예: <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: 'perceptural-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}),
        output: 'perceptural-scale',
        extrapolateLeft: 'clamp',
        extrapolateRight: 'clamp'
      }
    ),
  }}
/>
const translateY = interpolate(frame, [0, 30], [0, 120]); // ❌ 수식은 마크업에 직접 있어야 함

<Interactive.Div
  name="제품 카드"
  style={{
    translate: translateY, // ❌ 인라인 interpolate() 호출만 지원됨,
    rotate: interpolate(frame, [start, start + 10], [0, Math.PI]), // ❌ 임의 변수와 수식, 상수 사용 불가
    scale

    …
  }}
/>

스타일을 인라인으로 유지하고 구조화된 컴포넌트 사용

위의 예제에서 style 객체는 모든 속성을 인라인으로 포함하며, Interactive.Div에 직접 전달됩니다. style prop은 컴포넌트 계층을 통해 전달되어야 하며, 최종적으로 렌더링되는 루트 DOM 요소에 적용되어야 합니다. 이렇게 하면 Studio가 해당 스타일을 인식하고 편집할 수 있습니다.

컴포넌트가 style을 받아 루트 요소에 적용하지 않으면, 해당 스타일은 Studio에서 편집할 수 없게 됩니다.

결론

이 문서는 Remotion Studio에서 완전한 상호작용성을 달성하기 위한 핵심 패턴을 설명합니다:

  1. **Interactive.withSchema**를 사용하여 커스텀 컴포넌트를 인터랙티브하게 만들고, 스키마를 통해 편집 가능한 props를 정의합니다.
  2. 모든 CSS 스타일을 인라인으로 유지하여 Studio가 인식하고 편집할 수 있도록 합니다.
  3. 애니메이션은 interpolate()를 인라인으로 사용하고 하드코딩된 값과 useVideoConfig()의 변수를 사용합니다.
  4. 각 독립적으로 편집 가능한 항목에 고유한 JSX 노드를 할당합니다.
  5. 타이밍을 컴포넌트에 직접 전달하고 불필요한 <Sequence> 래핑을 피합니다.
  6. **요소에 설명적인 name**을 지정하여 Studio 타임라인에서 식별하기 쉽게 만듭니다.

이러한 지침을 따르면 Remotion Studio에서 풍부하고 편집 가능한 비디오 컴포지션을 만들 수 있습니다.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

관련 스킬