remotion-orchestrator — Remotion Skills Package 진입점
/remotion-video 원샷 명령
/remotion-video는 Remotion 마케팅 비디오를 위한 원샷 명령 레인입니다. 간단한 브리프를 하나의 통제된 프로덕션 패킷, 하나의 렌더 경로, 하나의 최종 증거 보고서로 변환합니다.
이 명령 경로의 엄격한 규칙:
- 단일 음성만 사용 가능합니다. 다중 음성 캐스트나 장면별 음성 전환은 허용되지 않습니다.
- 기존 Synthex ElevenLabs 자격 증명 및 음성 구성만 사용합니다.
- 새로운 벤더, 새로운 계정, 커넥터 플랫폼은 사용하지 않습니다.
- 운영자가 명시적으로 프로덕션 렌더를 요청하지 않는 한 드라이-런(dry-run)으로 시작합니다.
.harness/remotion/<jobId>/production-packet.json,script.md,preflight-report.md,render-command.sh파일을 작성합니다.- 생성된 MP4를 커밋하지 않습니다.
이 명령은 remotion-script, remotion-production, remotion-direction, remotion-editing, remotion-integrations, remotion-professionalism을 통해 라우팅되며, 아래의 기존 Remotion Skills Package 워크플로우를 유지합니다.
Remotion Skills Package의 단일 진입점 — 10개의 형제 스킬(remotion-orchestrator, remotion-brand-research, remotion-brand-codify, remotion-designer, remotion-colour-family, remotion-motion-language, remotion-screen-storyteller, remotion-marketing-strategist, remotion-composition-builder, remotion-render-pipeline)이 ~/.claude/skills/remotion-*에 전역 설치되어 있으며(~/Pi-Dev-Ops/skills/remotion-*에 심볼릭 링크됨), Pi-Dev-Ops뿐만 아니라 모든 프로젝트에서 사용할 수 있습니다.
발견 브리프 게이트(턴 1, 필수)
nexu-io/open-design(Apache-2.0)에서 채택됨. 웨이브 계획이 생성되기 전에 브리프를 잠급니다. 모든 필수 필드가 채워질 때까지 진행을 거부합니다 — 모호한 브리프는 과도하게 긴 웨이브 계획과 브랜드 외 렌더를 생성합니다.
필수 필드
| 필드 | 유형 | 비고 |
|---|---|---|
brand | BrandSlug | src/brands/에서 확인 가능해야 함. 알 수 없는 경우 → 먼저 remotion-brand-research 실행. |
composition | Explainer | Intro | SocialAd | NIRReport | ProductDemo | v1은 Explainer만 지원; 나머지는 메모와 함께 폴백. |
channel | linkedin | youtube | instagram | tiktok | training | 화면 비율 + 지속 시간 규율 결정. |
aspectRatio | 1920x1080 | 1080x1920 | 1080x1080 | 생략 시 channel에서 기본값 사용. |
durationSec | 15 | 30 | 60 | 90 | 120 | 웨이브 수 상한 결정. |
topic | string | 비디오 내용을 한 문장으로 설명. "브랜드 인지도 비디오"만으로는 거부됨 — 구체적인 포인트를 명시해야 함. |
audience | string | 생략 시 BrandConfig.audience.primary에서 상속되지만, 창립자가 확인해야 함. |
선택 사항: school(색상 생성기를 위한 시각적 스타일 재정의), voiceoverScript(사전 작성된 경우 스토리텔러 건너뜀), referenceComposition(리믹스할 기존 작업).
하드 중지 조건
topic이 특정 주장이 아닌 카테고리("우리 제품", "런칭")로 읽히는 경우 → 차단.- v1에서
composition이Explainer가 아닌 경우, 명시적 폴백 승인 없이 → 차단. - 하나의 브리프에 여러 브랜드가 명명된 경우 → N개의 병렬 작업(브랜드당 하나)으로 분할; 절대 혼합하지 않음.
게이트는 웨이브 계획이 계산되기 전에 실행됩니다. 차단된 브리프는 디스패처에 도달하지 않습니다.
호출
사용자는 다음을 통해 패키지를 호출할 수 있습니다:
- 다음 중 하나를 말함: "Remotion Skills Package 사용", "remotion 패키지", "remotion 사용".
- 개별 스킬 이름 지정 (예: "이 레이아웃 QA에 remotion-designer 사용").
intent: "video"로 분류되는 브리프 제출 (app/server/brief.py를 통해).
자유 텍스트 브리프를 구조화된 렌더 작업과 Pi-Dev-Ops 오케스트레이터(app/server/orchestrator.py)가 P3-B 팬아웃을 통해 디스패치하는 웨이브 계획으로 변환합니다.
Remotion 프로젝트
모든 컴포지션, 브랜드 설정, 모션/색상 헬퍼 및 렌더 진입점은 다음 위치에 있습니다:
../../remotion-studio/
다른 프로젝트에서 작업할 때, 하위 스킬은 브랜드/컴포지션 파일을 읽거나 편집하기 전에 해당 경로로 cd합니다. 렌더 진입점은 remotion-studio 내부에서 npx tsx render/render.ts ...를 실행하는 것입니다.
트리거
브리프에 다음 중 하나가 포함된 경우: video, explainer, promo, ad, reel, intro, outro, cta, social cut, 60s/30s/15s, render, marketing video, training video, release video, feature video, 그리고 브랜드 식별자 dr / disaster recovery / nrpg / ra / restoreassist / carsi / ccw / carpet cleaners warehouse 중 하나와 쌍을 이룹니다.
입력
Pi-Dev-Ops 플래너(Opus 4.7)는 이 스킬을 다음과 함께 호출합니다:
brief— 원래 자유 텍스트 요청repo_url— 일반적으로local:Pi-Dev-Ops/remotion-studiolinear_team_id,linear_project_id—config/harness/projects.json에서 미리 확인됨
출력
다음 형태의 웨이브 계획 JSON이 remotion-studio/.research/wave-plans/{job_id}.json에 기록됩니다:
{
"jobId": "ra-nir-explainer-2026-04-28T15-30-00",
"brand": "ra",
"composition": "Explainer",
"channel": "linkedin",
"durationSec": 60,
"topic": "RestoreAssist NIR 1단계 표준화",
"linear": { "teamId": "...", "projectId": "..." },
"outputPath": "output/ra-nir-explainer-2026-04-28T15-30-00.mp4",
"waves": [
{ "id": 1, "parallel": [ {"skill":"remotion-brand-research","if":"brands/ra.ts 누락 또는 오래됨"}, {"skill":"remotion-marketing-strategist"} ] },
{ "id": 2, "parallel": [ {"skill":"remotion-screen-storyteller"}, {"skill":"remotion-colour-family","if":"팔레트 불완전"}, {"skill":"remotion-motion-language","if":"모션 누락"} ] },
{ "id": 3, "parallel": [ {"skill":"remotion-brand-codify","if":"새 브랜드 아티팩트 있음"}, {"skill":"remotion-designer"} ] },
{ "id": 4, "serial": [ {"skill":"remotion-composition-builder"}, {"skill":"remotion-render-pipeline"} ] }
]
}
웨이브 수 규율
- 출력 <30초: ≤3개 웨이브
- 출력 ≤120초: ≤5개 웨이브
- 출력 >120초: ≤8개 웨이브
과도한 분해가 이 규칙이 방지하는 주요 실패 모드입니다.
컴포지션 라우팅 (브리프 → 컴포지션 ID)
| 브리프 신호 | 컴포지션 |
|---|---|
| "explainer", "feature video", "how it works" | Explainer |
| "intro", "title card", "channel opener" | Intro (v1.1) |
| "ad", "promo", "reel", "social cut", "Instagram", "TikTok" | SocialAd (v1.1) |
| "NIR report", "inspection report", RA + "report" | NIRReport (v1.1) |
| "demo", "product walkthrough" | ProductDemo (v1.1) |
v1은 Explainer만 지원합니다. 다른 컴포지션 ID는 "{Composition}은 v1.1에서 제공됩니다 — 채널별 프레이밍으로 Explainer로 폴백합니다"를 반환합니다.
브랜드 확인
키워드 → BrandSlug 매핑:
disaster recovery,dr→drnrpg→nrpgrestoreassist,ra,nir→racarsi→carsiccw,carpet cleaners warehouse→ccw
브리프가 여러 브랜드를 명명하는 경우, 플래너에게 N개의 병렬 작업(브랜드당 하나)으로 분할하고 N개의 웨이브 계획을 생성하도록 요청합니다. 절대 브랜드를 하나의 컴포지션에 혼합하지 마십시오.
Linear 라우팅
렌더 스킬이 MP4를 기록한 후, 이 스킬(또는 렌더 스킬)은 config/harness/projects.json에서 매핑된 프로젝트에 Linear 티켓을 엽니다:
| 브랜드 | Linear 팀 | 프로젝트 |
|---|---|---|
| ra | a8a52f07-63cf-4ece-9ad2-3e3bd3c15673 (RA) | 3c78358a-b558-4029-b47d-367a65beea7b |
| dr / nrpg | 43811130-ac12-47d3-9433-330320a76205 (DR) | d2c1d63b-1e85-424d-9278-efff15b0d46b |
| carsi | 91b3cd04-... (GP) | 런타임에 확인 |
| ccw | 런타임 | 런타임 |
썸네일 & 정지 이미지 생성 (Canva 우선 — 자격 증명을 찾지 마십시오)
비디오 썸네일, 포스터 또는 마케팅 정지 이미지의 경우, 신뢰할 수 있는 경로는 연결된 Canva MCP이며, 원시 이미지 생성 API 키가 아닙니다:
generate-design(design_type: your_story(9:16용),youtube_thumbnail(16:9용))을 상세한 브랜드 정렬 쿼리와 함께 실행 — 팔레트/헤드라인을 쿼리에 전달; Canva가 헤드라인 텍스트를 안정적으로 렌더링합니다.- 후보 미리보기를 다운로드하고 최상의 것을 선택;
create-design-from-candidate→export-design(PNG, 대상 WxH,export_quality: pro).
엄격한 규칙 (2026-07-01 기준, 어렵게 배움):
- 이미지 생성 키를 찾으려고 절대 자격 증명을 탐색하지 마십시오.
.env파일이나vercel env pull을 프로젝트/환경 전체에서 스캔하여GEMINI_API_KEY/OPENAI_API_KEY/AI_GATEWAY_API_KEY를 찾지 마십시오. 자동 모드 분류기가 이를 자격 증명 탐색으로 차단하고 전체 세션을 낭비합니다. - Vercel "민감" 환경 변수는 쓰기 전용입니다 —
vercel env pull은 이를 비어 있게 반환합니다. 하나를 가져오려고 시도하지 마십시오; 원래 소스에서 값을 얻거나 Canva를 사용하십시오. - 이미지 도구가 연결되어 있지 않고 단일 지시된 확인으로 키에 도달할 수 없는 경우, 중단하고 창립자에게 한 번만 문의 — Canva를 먼저 제안하십시오.
- 렌더링된 MP4에서 프레임 그랩(프레임 추출)(번들 ffmpeg,
node_modules/@remotion/compositor-*/ffmpeg에 위치)은 오프라인 폴백입니다. 참고: macOS에서는 형제*.dylib파일을 cwd로 심볼릭 링크하여 번들 ffprobe/ffmpeg가 확인되도록 하십시오(SIP가DYLD_*를 제거함).
이 스킬이 수행하지 않는 작업
- 컴포지션을 작성하지 않습니다 —
remotion-composition-builder가 수행합니다. npx remotion render를 실행하지 않습니다 —remotion-render-pipeline이 수행합니다.- BrandConfig 파일을 편집하지 않습니다 —
remotion-brand-codify가 수행합니다.
오직 계획하고 위임만 합니다.
프로젝트별 사용 모델
패키지는 공유 인프라입니다. 각 호출 프로젝트는 자체 런타임 구성과 API 키를 제공합니다.
| 관심사 | 위치 |
|---|---|
| 스킬 정의 | ~/.claude/skills/remotion-* (심볼릭 링크 → Pi-Dev-Ops/skills/remotion-*) — 전역에서 사용 가능. |
| Remotion Node 프로젝트 (컴포지션, 브랜드 설정, 렌더 진입점) | ../../remotion-studio/ — 단일 공유 기반. |
| 브랜드 설정 | Synthex/packages/brand-config/src/brands/{slug}.ts — 브랜드당 하나의 진실 공급원, 해당 브랜드로 렌더링하는 모든 프로젝트에서 사용. (RA-1985 / Synthex SYN-897에 따라 Pi-Dev-Ops/remotion-studio/src/brands/에서 마이그레이션됨.) |
| API 키 (ElevenLabs, Telegram, Supabase, Linear, Remotion 라이선스) | 호출 프로젝트의 .env / .env.local. 스킬은 렌더 시 process.env를 읽습니다. |
| 렌더링된 MP4 출력 | 기본적으로 호출 프로젝트의 .remotion-renders/ 디렉토리. --out=으로 재정의 가능. |
프로젝트에 새 브랜드 추가
프로젝트(예: Synthex)가 아직 src/brands/에 없는 브랜드를 렌더링해야 하는 경우:
- 해당 브랜드의 공개 소스에 대해
remotion-brand-research를 실행합니다. remotion-brand-codify를 실행하여Synthex/packages/brand-config/src/brands/{slug}.ts를 생성합니다.Synthex/packages/brand-config/src/types.ts의BrandSlug유니언을 확장합니다.Synthex/packages/brand-config/src/brands/index.ts에 등록합니다.Synthex/packages/brand-config/에서npm run typecheck를 실행합니다(그런 다음npm run build로dist/재생성).
현재 등록된 브랜드: dr, nrpg, ra, carsi, ccw, synthex, unite.