repo-cinema

repo-cinema Director Skill

코드베이스에서 바로 Screen Studio 수준의 60fps 제품 데모 비디오를 만듭니다. 임시방편 화면 녹화나 목적 없는 커서 이동 대신, repo-cinema는 5단계 결정론적 파이프라인인 analyze -> plan -> stage -> render -> verify 를 실행합니다.

핵심 아키텍처 원칙

1. 페르소나 우선 사용 사례 (analyze): 내부 디버그 통계나 원시 설정 화면을 절대 보여주지 마세요. 진입점, CLI 명령어, 라우트, 컴포넌트, 테스트를 읽어 구체적인 Persona -> Pain Point -> User Action -> Durable Outcome 장면을 종합합니다.
2. 인과적 공동 프레이밍 (plan): 마우스 포인터를 쫓는 대신 bbox(trigger ∪ outcome) 의 통합 바운딩 박스를 프레임화합니다. 콘텐츠 너비가 스테이지의 70% 이상을 차지할 때마다 수평 초점을 fx = viewport.width / 2로 고정하여 축, 헤더, 오른쪽 열이 화면 밖으로 잘리지 않도록 합니다.
3. 정적 읽기 유지: 액션 전에 카메라 줌을 천천히 확대한 다음, 상호 작용 및 이해 중에는 (zoom, fx, fy)를 100% 고정하여 시청자가 차트와 알림 업데이트를 실제로 읽을 수 있게 합니다.
4. 결정론적 가상-클록 60fps (render): 페이지 로드 전에 가상 클록 심(Date, performance.now, requestAnimationFrame)을 주입하여 CSS 전환, ECharts 애니메이션, C2 최소-저크 커서 궤적(sin^3(pi * u) 호, <=12% 속도 팽창, +/-6도 기울기, 화살표 <-> 포인팅 손 변형), 및 이중 클릭 리플이 결정론적으로 프레임별로 FFmpeg에 전달되도록 합니다.
5. 연락처 시트 자체 검사 (verify): 3x3 contact-sheet.png + verify-report.json(ffprobe 스트림 검증 + 화면 밖 클릭 제로)을 생성하고 제공하기 전에 모든 패널을 시각적으로 검사합니다.

유틸리티 CLI 명령어 (repo-cinema)

전역으로 설치되거나 저장소에서 실행될 때(npx repo-cinema ... 또는 node dist/cli.js ...), 각 단계는 구조화된 파일을 출력합니다:

# 1. 저장소를 읽고 사용 사례 시나리오 추출 (선택적으로 repomix 실행 가능)
repo-cinema analyze --repo ./my-project --output ./out/dossier.json [--repomix]

# 2. 인과적 카메라/커서 스토리보드 JSON + 시각적 HTML 미리보기 구축
repo-cinema plan --dossier ./out/dossier.json --output ./out/storyboard.json --html ./out/storyboard.html --theme aurora-indigo

# 3. 4-in-1 스테이지 구축 (web-url | plugin-or-component | cli-terminal | hybrid)
repo-cinema stage --dossier ./out/dossier.json --plan ./out/storyboard.json --output ./out/stage.html [--url http://localhost:3000]

# 4. 결정론적 60fps CDP 캡처 + 48kHz 스테레오 SFX (또는 선택적 TTS)
repo-cinema render --plan ./out/storyboard.json --stage ./out/stage.html --output ./out/demo.mp4 --gif ./out/demo.gif --audio sfx

# 5. 스트림, 텔레메트리 경계 검증 및 3x3 시각적 연락처 시트 구축
repo-cinema verify --video ./out/demo.mp4 --telemetry ./out/demo.telemetry.json --contact-sheet ./out/contact-sheet.png --output ./out/verify.json

# 또는 전체 5단계 파이프라인을 한 명령어로 실행:
repo-cinema run --repo ./my-project --out-dir ./out --theme aurora-indigo

Director Workflow

Step 1: 저장소 및 대상 분석

repo-cinema analyze --repo <path> --output <dossier.json> 실행. 생성된 useCases 읽기:

• 감지된 archetype(web-app, desktop-or-ide-plugin, cli-tool, ui-library, hybrid) 확인.
• 저장소에 특화된 워크플로가 있는 경우 캡션 개선 또는 도메인-진정성 샘플 픽스처 추가 (개인 데이터, 개발자 전용 카운터 금지).

Step 2: 스토리보드 계획 및 프레이밍 승인

repo-cinema plan을 --html 옵션으로 실행하여 storyboard.html 검사 (또는 beats, captionWarnings, cameraKeyframes 검토):

• Anti-Slop Caption Linter의 경고 수정 ("unprecedented", "next-gen", "seamlessly" 등 금지어 또는 96자를 초과하는 캡션 없음).
• 시작 프레임(t=0)과 종료 프레임(t=durationMs)이 zoom: 1.0으로 깔끔하게 설정되어 README GIF 루프가 원활한지 확인.

Step 3: 스테이지 어댑터 선택

• web-url: 앱이 이미 로컬에서 실행 중입니다 (http://localhost:PORT). 리코더가 가상 클록 심 + 비간섭 커서/카메라/캡션 오버레이를 라이브 페이지에 직접 주입합니다.
• plugin-or-component: 데스크톱 플러그인 (Obsidian, VS Code, Raycast) 또는 esbuild로 번들된 실제 코어 모듈을 사용하여 어두운 macOS Studio 크롬 내부에 렌더링된 UI 컴포넌트 패키지.
• cli-terminal: 명령어 출력, KPI 타일, 결과 영향 카드가 동기화된 유리 macOS 터미널에서 선보이는 터미널 도구.
• hybrid: CLI 실행을 라이브 시각적 출력 및 아키텍처 다이어그램과 함께 페어링하는 멀티탭 macOS Studio.

Step 4: 60fps 마스터 + GIF + 오디오 렌더링

repo-cinema render 실행:

• 기본 --audio sfx는 의존성 없는 48kHz 스테레오 마이크로-SFX(커서 x에 정렬된 스테레오 팬 클릭, 부드러운 줌 공기-움, 확인 토스트 차임)를 합성합니다 — 외부 API 키가 전혀 필요 없습니다.
• 선택적 --audio tts --tts-provider <macos-say|edge-tts|openai|elevenlabs>는 마이크로-SFX와 함께 내레이션을 깔끔하게 혼합합니다.

Step 5: 검증 및 시각적 검사

repo-cinema verify 실행하고 파일/이미지 뷰어로 contact-sheet.png 직접 검사:

• passed: true, offscreenClicks: 0, 그리고 9개의 키프레임 썸네일 전체에서 읽을 수 있는 텍스트인지 확인.
• 어떤 요소가 뷰포트 가장자리 근처에서 잘리면, computeCausalFraming에서 marginPx를 늘리거나 zoom을 0.06 줄이고 다시 렌더링.

참조 가이드

• Camera & Cursor Physics
• 4-in-1 Stage Adapters
• Storyboard Schema
• Open-Source Architecture & Attributions

피해야 할 일반적인 실수

• 타이핑/드래그 중 포인터를 프레임별로 따라가기: 멀미를 유발합니다. 항상 유지 구간 동안 비트별로 카메라 프레이밍을 잠그세요.
• 벽 시계 setTimeout / 실시간 화면 캡처 사용: CPU가 스파이크될 때마다 프레임이 드롭되어 24-40fps의 끊기는 녹화를 생성합니다. 항상 __rcStep(dtMs)를 통해 애니메이션을 구동하세요.
• 넓은 차트나 테이블에서 너무 공격적으로 줌(> 1.35x): Y축 레이블이나 가장 오른쪽 요약 열이 잘립니다. wideLockRatio를 0.70으로 유지하여 fx = width / 2가 되도록 하세요.
• 큰 원시 .mp4 바이너리를 GitHub 저장소에 커밋: 가벼운 팔레트 최적화 .gif + contact-sheet.png를 docs/assets/에 추적하고 .mp4는 GitHub Releases에 첨부하거나 로컬에서 *.mp4를 무시하세요.