Remotion Code Explainer (remotion-code-explainer)
개요
모든 소스 코드 파일을 1920×1080 30fps MP4 형식의 몰입형 프레임 동기화 Remotion 설명 동영상으로 단일 창 Log2Base2 스튜디오 형식으로 변환합니다.
화면을 경쟁하는 분할 창이나 복잡한 멀티 카드 벽으로 나누지 마십시오. 모든 동영상은 하나의 통합된 시각적 무대(<SinglePaneStage>)를 사용하여 시청자의 전체 집중이 코드가 실행되는 방식에 고정되도록 합니다.
- 최소 상단 바 (
44px,SinglePaneStage에 내장)- 왼쪽에는 수업 제목 + 현재 활성 섹션 알약; 오른쪽에는 미묘한 단계 카운터 + 얇은 진행 막대.
- 하나의 통합된 Log2Base2 무대 (
SinglePaneStage— 100% 너비)- 집중된 단일 라인 스포트라이트 헤더: 오직 현재 단계 제목과 단일 활성 코드 라인을 선명한 고정폭 글꼴로 표시합니다(활성 음성 토큰을 인라인으로
borderBottom: "2px solid #FACC15"로 강조 표시하며 절대 가로 패딩을 추가하지 않음) + 하나의 작은 활성 콜아웃 알약(token→일반 영어 의미)이triggerFrame에서 튀어나옵니다. - 전체 너비 몰입형 SVG 캔버스 (
viewBox="0 0 1600 680"): 넉넉하고 연속적인 모션 그래픽으로, Log2Base2 메모리/실행 시각 자료(라벨이 지정된 메모리 박스0x1004, 변수 변이, 애니메이션strokeDashoffset포인터 화살표, 푸시/팝되는 스택 프레임, 배열/트리 스왑)와 함께 라이브 UI/stdout/텐서 미리보기를 동일한 열린 캔버스에 직접 배치합니다.
- 집중된 단일 라인 스포트라이트 헤더: 오직 현재 단계 제목과 단일 활성 코드 라인을 선명한 고정폭 글꼴로 표시합니다(활성 음성 토큰을 인라인으로
- 최소 하단 자막 바 (
VoiceoverCaptionBar—68px)- 정확한 TTS
WordBoundary밀리초 타임스탬프(startMs,endMs)로 구동되는 깔끔한 중앙 정렬 단어별 강조 가라오케 자막.
- 정확한 TTS
종속성
remotion-best-practices(~/.gemini/skills/remotion/SKILL.md): 모든 Remotion 애니메이션 규칙(useCurrentFrame(),interpolate(),spring(),<Sequence premountFor>,<Audio>,@remotion/google-fonts, 0 CSS 전환)을 준수해야 합니다.uv(~/.gemini/config/plugins/science/skills/uv/SKILL.md): 신경 음성 해설 합성 및WordBoundary타임스탬프 추출을 위해uv run --with edge-tts를 실행하는 데 필요합니다.
빠른 시작
# 1. Remotion 설명 프로젝트 스캐폴드
uv run python3 \
~/.gemini/config/skills/remotion-code-explainer/scripts/code_explainer_cli.py \
scaffold \
--project-dir "/path/to/project" \
--source-file "/path/to/source.ext" \
--output "/path/to/project/scaffold-status.json"
# 2. 자연스러운 신경 음성 해설 + 정확한 WordBoundary 및 토큰 타임스탬프 합성
uv run --with edge-tts python3 \
~/.gemini/config/skills/remotion-code-explainer/scripts/code_explainer_cli.py \
synthesize-voiceover \
--project-dir "/path/to/project" \
--beats-json "/path/to/project/beats.json" \
--voice "en-US-AndrewNeural" \
--rate "+2%" \
--pause-sec 0.40 \
--output "/path/to/project/public/voiceover/manifest.json"
# 3. 빠른 8-워커 키프레임 중복 제거 렌더러를 통해 최종 1080p 30fps MP4 렌더링
uv run python3 \
~/.gemini/config/skills/remotion-code-explainer/scripts/code_explainer_cli.py \
render-mp4 \
--project-dir "/path/to/project" \
--composition-id "CodeExplainer" \
--out-name "Explainer.mp4" \
--concurrency 8 \
--output "/path/to/project/render-report.json"
몰입형 스토리텔링 및 워크플로우
- 에너제틱 비트 설계 (
beats.json)- 시청자를 코드가 특정 방식으로 동작하는 이유에 즉시 몰입시키는 선명하고 대화식 나레이션을 작성합니다.
<SinglePaneStage>에 전달된 활성 라인이token을 그대로 포함하도록codeSnippet을 집중(1–4라인)시킵니다.- 이동 패킷, 포인터 홉, 배열 스왑 또는 라이브 텐서/UI 애니메이션이 있는 비트에는
"motionStepFrames": 2를 설정합니다.
- 스캐폴드 및 음성 해설 합성
scripts/code_explainer_cli.py를 통해scaffold(SinglePaneStage.tsx,VoiceoverCaptionBar.tsx,render_full_mp4.mjs복사) 및synthesize-voiceover를 실행합니다.
- 전체 캔버스 모션 그래픽 제작 (
viewBox="0 0 1600 680")- 애니메이션된 Log2Base2 × KodeKloud SVG 스토리보드를
<SinglePaneStage>의children으로 전달합니다. - 보여주고, 말하지 마십시오: 정적 코드 벽과 텍스트 상자를 물리적 동작(값이 레지스터/변수에서 메모리 슬롯으로 날아감, 포인터가 부드럽게 경로 변경, 데이터 패킷이 컴포넌트 간 이동, 라이브 상태/UI 출력이 동일한 열린 캔버스에서 업데이트)으로 대체합니다.
- 동적 그리드나 스크롤 트레이스는
<clipPath>로 감싸서 모션이 해당 영역 밖으로 새지 않도록 합니다.
- 애니메이션된 Log2Base2 × KodeKloud SVG 스토리보드를
- 스틸 확인 및 최종 MP4 렌더링
npm run lint를 실행하고read_file로 대표적인 스틸 프레임(npx remotion still)을 검사하여 겹침이나 클리핑이 없는지 확인합니다.render-mp4(scripts/render_full_mp4.mjs)를 실행하고 최종.mp4가out/, 프로젝트 루트 및 작업 공간 루트에 저장되었는지 확인합니다.
속도 제한 및 일반적인 실수
scripts/code_explainer_cli.py는/tmp/remotion_edge_tts.lock을 적용합니다(0.35s간격,1s/2s/4s백오프로 3회 재시도).- 절대 2영역 분할 화면 대시보드를 사용하거나 40줄 스크롤 코드 벽을 덤프하지 마십시오. 화면을 하나의
<SinglePaneStage>창으로 유지하십시오. - 절대 강조 표시된 인라인 토큰에 가로
padding을 추가하지 마십시오(borderBottom: "2px solid #FACC15"및backgroundColor만 사용). - 절대 SVG 무대 내부에 정적 텍스트 카드를 사용하지 마십시오. 애니메이션 메모리/포인터/패킷 동작이 개념을 시각적으로 증명할 수 있을 때는 사용하지 마십시오.