iamryoman/remotion-best-practices

Remotion 모범 사례

Remotion 출력물을 프레임, 입력 속성, 선언된 자산의 결정론적 함수로 구축하세요. 사용자 편집 내용과 프로젝트의 기존 패키지 매니저, 아키텍처, 스타일은 작업에서 변경이 필요하지 않은 한 유지합니다.

증거부터 확인

1. 리포지토리 지침을 읽고 package.json, 잠금 파일, Remotion 설정, 진입점, 등록된 컴포지션 및 주변 테스트를 검사합니다.
2. 기존 프로젝트에서 node <skill-directory>/scripts/audit-remotion-project.mjs <project-root>를 실행합니다. 출력물을 증거로 취급하고 업그레이드 허가로 간주하지 않습니다.
3. 설치된 Remotion 버전을 API 선택 전에 기록합니다. 모든 remotion 및 @remotion/* 패키지를 정확히 동일한 버전으로 유지합니다. 두 번째 잠금 파일을 추가하지 마세요.
4. 결과물이 비디오, 단일 스틸 이미지, 비디오에서 샘플링된 프레임, 또는 배치 스토어 스크린샷인지 식별합니다.
5. 구현 전에 컴포지션 ID, 크기, FPS, 지속 시간, 속성, 출력 경로 및 필요한 자산을 정의합니다.

관련 참조만 로드

• <Composition>, <Still>, useCurrentFrame(), interpolate(), spring(), <Sequence> 또는 <Series>의 경우 composition-and-timing.md를 읽으세요.
• staticFile(), 미디어, 폰트, 네트워크 데이터, useDelayRender(), delayRender() 또는 calculateMetadata()의 경우 assets-and-async.md를 읽으세요.
• CLI, renderStill(), 서버 사이드 렌더링 또는 Remotion Lambda의 경우 rendering-and-lambda.md를 읽으세요.
• 느린 렌더링, 높은 메모리 사용, 비결정론, 또는 검증 전략의 경우 performance-and-testing.md를 읽으세요.
• App Store 또는 Google Play 이미지의 경우(screenshot-studio에 의해 위임된 1284×2778 출력 포함) store-stills.md를 읽으세요.
• API 또는 플랫폼 규칙이 변경되었을 수 있는 경우, 코딩 전에 sources.md에 링크된 라이브 주요 출처를 참조하세요.

절대 타협하지 않는 구현 규칙

• 시간은 useCurrentFrame()과 useVideoConfig()에서 파생합니다. CSS 전환, CSS 키프레임 애니메이션, 벽시계 타이머 또는 시드되지 않은 난수를 렌더링된 모션에 사용하지 마세요.
• 외삽이 의도적이지 않은 한 유한 애니메이션을 클램프합니다. 시간을 나타낼 때는 초 단위에 fps를 곱하여 표현하고, 공유 장면 지속 시간을 중앙화합니다.
• useCurrentFrame()은 시간이 지정된 컴포넌트 내에서 상대적임을 기억하세요. 전역 동기화가 의도적인 경우에만 컴포지션 루트에서 절대 프레임을 전달합니다.
• 부모 타임라인에 명시적으로 배치하려면 <Sequence>를, 연속적인 장면에는 <Series>를 사용합니다. 모든 장면에 명시적인 지속 시간을 부여합니다.
• 로컬 자산은 public/에 넣고 staticFile()로 해석합니다. Remotion 미디어 컴포넌트를 사용하여 원시 HTML 태그 대신 렌더링이 미디어를 올바르게 기다리도록 합니다.
• 컴포넌트 내에서 useDelayRender()를 선호합니다. 핸들을 한 번 생성하고 정확히 한 번 해제하며, 실패 시 cancelRender(error)를 호출합니다. 렌더링당 한 번 속성 또는 메타데이터를 결정하는 데 필요한 데이터에는 calculateMetadata()를 선호합니다.
• 렌더링 시간 코드를 headless Chromium 또는 Lambda에서 사용할 수 없는 브라우저 전용 가정에서 자유롭게 유지합니다. AWS 자격 증명이나 다른 비밀을 브라우저 번들에 노출하지 마세요.
• 각 스토어 대상에 대해 크기, 파일 형식, 알파 채널 정책 및 플랫폼별 규칙을 독립적으로 검증합니다. 하나의 세로 크기가 Apple과 Google 모두에서 허용된다고 가정하지 마세요.

타이트한 렌더 루프로 작업

1. 타입 검사 및 집중 테스트를 실행합니다.
2. 대표적인 스틸 프레임(시작, 각 장면 경계, 모션 중간점, 마지막 프레임)을 렌더링합니다.
3. Studio 미리보기가 아닌 실제 픽셀을 검사합니다. 클리핑, 텍스트 줄 바꿈, 안전 여백, 누락된 자산 및 투명 배경을 확인합니다.
4. 전체 고비용 비디오 전에 짧은 프레임 범위 또는 저해상도 드래프트를 렌더링합니다.
5. 맹목적으로 최대화하는 대신 배포 머신에서 동시성을 벤치마킹합니다.
6. 명시적인 컴포지션 ID, 속성, 출력 경로, 크기 및 형식으로 최종 아티팩트를 렌더링합니다.
7. 종료 상태, 파일 존재 여부, 픽셀 크기, 관련된 경우 지속 시간/프레임 수 및 최종 시각적 샘플을 확인합니다.

변경 사항 보수적으로 적용

• 작업에서 필요하거나 사용자가 승인하지 않는 한 Remotion을 업그레이드하거나, 프로젝트 구조를 재작성하거나, 미디어 컴포넌트를 교체하지 마세요.
• 새로운 API는 설치된 버전 뒤에 게이트합니다. 실용적일 때 호환 가능한 폴백을 제공합니다.
• 임의의 시간 초과 증가로 렌더링 실패를 숨기지 마세요. 먼저 해결되지 않은 핸들, 네트워크 요청, 자산, 폰트 또는 미디어 디코드를 식별합니다.
• 비교 가능한 렌더링의 측정값 없이 성능 개선을 주장하지 마세요.