Cena Raiz
원칙
- 2단계, 게이트 하나. 1단계는 깔끔한 컷 + 색보정, 2단계는 자막, 그래픽, 이미지입니다. (하드 룰 1이 게이트를 강제합니다.)
- LLM은 원시 전사본 + 요청 시 시각 자료를 기반으로 추론합니다. 유일하게 유지되는 파생 아티팩트는 구문 단위 전사 파일(
takes_packed.md)뿐입니다. 나머지는 결정 시점에 직접 도출합니다. - 오디오가 우선이고, 시각 자료는 그 뒤를 따릅니다. 컷 후보는 음성 경계와 무음 구간에서 결정됩니다.
- 묻기 → 확인 → 실행 → 반복 → 저장. 사용자가 일반 언어로 전략을 확인하기 전에는 절대 컷을 건드리지 마십시오.
- 일반화하십시오. 자료를 살펴보고, 사용자에게 물어본 다음에 편집하십시오. 영상의 종류를 가정하지 마십시오.
- 예술적 자유가 기본값입니다. 여기 있는 특정 값은 예시일 뿐, 명령이 아닙니다. 하드 룰만이 필수입니다.
- 취향이 있는 곳에 토큰을 사용하십시오. 기계 데이터는 프로그램을 위한 것이지 읽기 위한 것이 아닙니다. 수치 검증이 시각적 검증보다 먼저입니다. 당신의 주의력은 희소한 자원입니다 — JSON을 파싱하는 것이 아니라 편집에 집중하십시오. (하드 룰 12와 13이 이것이 금지하는 바를 설명합니다.)
하드 룰 (프로덕션 정확성 — 변경 불가)
- 단계 게이트는 실제입니다. 컷이 승인되기 전에는 2단계 작업을 진행하지 마십시오.
- 세그먼트별 추출 → 무손실
-c copy연결, 단일 패스 필터그래프는 사용하지 마십시오. (기본 J-컷에서는 테이크의 영상과 음성이 별도 범위로 추출되고 오디오 트랙이 합산됩니다 — 이것이 유일하게 허용된 믹스이며, 비디오 경로는 여전히 세그먼트별 + 무손실 연결입니다.) - 모든 세그먼트 경계에 30ms 오디오 페이드 (render.py에 인코딩됨).
- 단어 내부에서 자르지 마십시오 — 전사본의 단어 경계에 맞춰 자르십시오.
- 모든 컷 가장자리에 패딩을 적용하십시오 (30–200ms 창, 트레일이 리드보다 약간 길게). 가능하면 무음 구간에서 자르십시오.
- 소스별로 전사본을 캐시하십시오. 소스가 변경되지 않았다면 다시 전사하지 마십시오.
- 추출 중에 세그먼트별로 색보정하고, 연결 후에는 하지 마십시오.
- **실행 전에 전략 확인.
- **모든 세션 출력물은
<videos_dir>/edit/**에 저장하십시오 — 절대 cena-raiz 저장소 내부에 두지 마십시오. - 2단계는 Remotion 전용입니다 — ffmpeg/PIL로 텍스트나 오버레이를 직접 생성하지 마십시오.
- 2단계는 데이터 기반입니다. 트랙 템플릿을 복사하여 기본 구조를 만드십시오.
public/edit-data.json에 비디오를 설명하십시오. 템플릿 TSX (src/Main.tsx등)는 절대 읽거나 편집하지 마십시오 — 편집 가능한 유일한 코드 파일은src/CustomGraphics.tsx이며, 맞춤 그래픽 전용입니다. - 먼저 수치로 검증하십시오. 렌더링된 모든 컷에 대해
verify_cut.py를 실행하십시오. 문제가 있는 접합부에 대해서만 이미지를 여십시오. 여러 프레임을 한 번에 확인하려면contact_sheet.py/grade.py --candidates몽타주를 사용하십시오. - 컨텍스트에 기계 데이터를 읽지 마십시오:
transcripts/*.json(원시),captions.json,track.json,segments.json, 매트/트랙 바이너리.takes_packed.md와 도우미 stdout을 대신 읽으십시오.
실행 매체 — 로컬 파이프라인 vs Adobe MCP
기본 엔진은 아래의 ffmpeg/Remotion 파이프라인입니다. 연결, 진단, 기능 탐색, 또는 로컬 Adobe MCP를 통한 제어 작업의 경우, 먼저 references/adobe-mcp.md를 읽으십시오. 이 문서는 클라이언트 중립적입니다: Codex와 Claude Code에서 동일한 절차가 적용됩니다.
사용자가 premiere-pro MCP를 통해 Adobe Premiere Pro 내에서 편집을 요청하는 경우 ("edite a sequência no Premiere", "corte via MCP"), 또한 references/premiere-mcp.md를 읽으십시오. 방법(METHOD)은 변경되지 않습니다 — 오디오 우선, 무음 구간에서 컷, 단계 게이트, 취향에 따른 색보정 — 하지만 도구(hands)가 변경됩니다. 전사 및 edl.json은 동일하고 캐시되므로 승인된 EDL을 재사용하고 cut.mp4/프리뷰는 건너뛰십시오. After Effects 쓰기는 여전히 저장소의 통제된 Adobe 단계의 적용을 받습니다. MCP 가용성만으로는 변경 권한이 부여되지 않습니다.
디렉토리 구조
<videos_dir>/
├── <소스 파일, 수정되지 않음>
└── edit/
├── project.md ← 메모; 모든 세션에 추가됨
├── takes_packed.md ← 구문 수준 전사, 기본 읽기 뷰
├── edl.json ← 컷 결정 (1단계)
├── transcripts/<name>.json ← 캐시된 단어 수준 전사 (WhisperX, 로컬)
├── clips_graded/ ← 색보정 및 페이드가 적용된 세그먼트별 추출물
├── cut.mp4 ← 1단계 출력: 깔끔한 색보정 컷 (승인 아티팩트)
├── verify/ ← 몽타주 / 플래그된 경계 뷰
├── captions.srt + chapters.txt ← 긴 형식 전달물
├── final.mp4 ← 전달용 렌더 (2단계 + 3단계, loudnorm 적용)
└── remotion/ ← Remotion 프로젝트 (2단계 + 3단계)
├── public/ ← cut.mp4, edit-data.json (THE 편집), captions.json,
│ track.json, segments.json, pexels/ web/ brand/, sfx/, trilha.mp3
└── src/ ← 불변 템플릿 코드 + CustomGraphics.tsx
설정
첫 설치 과정은 install.md에 있습니다. 콜드 스타트 시에는 다음만 확인하십시오:
- 전사에 API 키가 필요하지 않습니다. WhisperX가 종속성으로 제공됩니다:
uv sync가 전체 설치입니다. Whisper로 전사한 다음 **강제 정렬(wav2vec2)**을 파형에 대해 실행하므로, 단어 시간은 추론된 것이 아니라 측정된 것입니다 — 단어의 93%가 실제 음성 영역 내에 위치하고 음성 끝은 10ms 이내에 배치됩니다(speech_regions.py로 측정). 모델은 첫 실행 시 한 번 다운로드되어 캐시됩니다. 속도는 ~실시간이며 길이가 길어질수록 향상됩니다(모델 로딩은 고정된 ~18초: 16초 클립은 23초, 166초 소스는 109초 소요). _transcription_backend에/UNALIGNED접미사가 있으면 감지된 언어에 대한 wav2vec2 모델이 없어 단어 시간이 디코더 자체의 것으로, 정밀도가 낮고 2단계 카라오케 자막에 안전하지 않음을 의미합니다. 발생하면 알리십시오.ffmpeg+ffprobe가 PATH에 있어야 함; Python 종속성(uv sync); 2단계를 위해 Node 18+.yt-dlp는 Python 종속성과 함께 제공되므로 URL 소스에 추가 설치가 필요하지 않습니다.- 2단계 도메인 지식을 위한
remotion-best-practices스킬(누락된 경우 https://github.com/remotion-dev/skills 에서 설치). - 2단계/3단계는 선택적 API 키(예시 이미지, AI 사운드트랙)를 사용할 수 있습니다. 이는 트랙 참조에 나열되어 있으며, 기능이 처음 사용될 때 게으르게 요청되고 설치 시에는 절대 요청되지 않습니다. 1단계에는 키가 필요하지 않습니다.
도우미는 helpers/에 있으며, 이 SKILL.md를 기준으로 경로가 확인됩니다(보통 ~/.claude/skills/cena-raiz/ 또는 ~/.codex/skills/cena-raiz/, 또는 심볼릭 링크/정션). uv run python helpers/<name>.py로 실행하십시오 — python만 사용하면 uv sync가 빌드한 .venv를 찾지 못합니다.
도우미
1단계:
ingest_url.py <url> --dest <videos_dir> [--section 12:00-25:30] [--max-height 1080]— 링크에서 편집: yt-dlp → MP4 (≤1080p)를 비디오 디렉토리로 직접 가져옵니다. 그런 다음 다른 소스와 마찬가지로 처리합니다.--section은 1시간 비디오의 12~25분만 잘라내는 저렴한 방법입니다(키프레임 정확도).--simulate는 다운로드하지 않고 제목/길이/해상도를 출력합니다(큰 파일은 확인 후 백그라운드에서 다운로드).transcribe.py <video> --edit-dir <edit> [--language pt] [--model large-v3-turbo]— 단어 수준, 캐시됨, 로컬(WhisperX + 강제 정렬). 제한 없음, 청크 분할 없음. 언어를 알면--language를 전달하십시오 — 자동 감지는 비용이 한 번 더 들고 짧은 클립에서 잘못 선택할 수 있습니다.transcribe_batch.py <videos_dir>— 디렉토리의 모든 소스를 하나씩 처리합니다(로컬 추론은 이미 모든 코어를 사용함). 파일별로 캐시되며, 한 소스에서 실패해도 이미 완료된 소스는 손실되지 않습니다.pack_transcripts.py --edit-dir <dir>— 전사 →takes_packed.md(구문 수준, ≥0.5초 무음에서 분할). 그것이 읽기 뷰입니다: 원시 JSON의 1/10 토큰.speech_regions.py <video>— silencedetect를 통한 음향 음성 간격. 컷 가장자리(EDGES)에 대한 진실 공급원(Whisper 시간은 드리프트/늘어짐이 있음). 음성이 어디에 있는지 대답합니다 — 얼마나 큰지는 대답하지 않습니다.voice_levels.py <video> [--edit-dir <dir>] [--edl edl.json] [--drop-db 5]— 음성 레벨에 대한 진실 공급원. 모든 구문을 플래그하고, 화자 자신의 중앙값보다 5dB 아래인 모든 EDL 범위를 찾아gain_db를 설정합니다. 다른 도구로는 잡지 못하는 것을 잡아냅니다: 전사는 완벽하고,speech_regions는 "음성"이라고 말하며,verify_cut은 결함을 찾지 못하지만 시청자가 여전히 들을 수 없는 속삭임을 찾습니다. EDL을 작성하기 전에 실행하십시오.detect_color.py <video> [--json]— 파일에서 NORMAL vs LOG를 확인하기 위해 묻는 대신 결정합니다. 메타데이터 우선, 메타데이터가 없을 때 이미지 통계 사용(일반적: 트랜스코딩 시 태그 손실). 프로필, 신뢰도, 증거 및 적용할grade를 반환합니다.confidence: low인 경우에만 사용자에게 다시 물어보십시오. 식별 세부 사항은references/log-grade.md에 있습니다.render.py <edl.json> -o cut.mp4 --no-subtitles [--voice-master] [--keep-resolution] [--jobs N] [--no-jcut] [--jcut-lead N] [--jcut-tail-trim N]— 세그먼트별 추출(색보정 + 페이드, 병렬) → J-컷 오버랩 조립(기본) 또는 무손실 연결 → 선택적 음성 마스터 → loudnorm. EDL에jcut_timeline을 씁니다: 실제 출력 위치, 이후 모든 다운스트림이 인덱싱해야 하는 대상. 짧은 형식의 fps는 자동입니다: 30fps 소스 이상은 30fps, 나머지는 24 (긴 형식은--keep-resolution을 통해 소스 fps를 유지). 결과cut.mp4와 일치하도록edit-data.json의fps를 설정하십시오.verify_cut.py <edl.json> <cut.mp4> [--min-silence 1.2]— 수치 자체 평가: 길이, 접합부별 팝/잘린 단어 프로브, 무음, 검은 프레임, 클리핑, 및 범위 레벨 균형(각 범위의 RMS 대 중앙값 범위;LOW-LEVEL은 −4 dB 미만). 이미지 N개 대신 ~350토큰의 텍스트. 범위 균형 라인은gain_db수정의 수렴 테스트입니다.grade.py <in> -o <out>— 색보정 사전 설정/원시 필터.--candidates "a=<filter>;b=<preset>;original=" --frame <t> -o cmp.png는 동일한 프레임에 N개의 룩을 하나의 레이블이 있는 몽타주로 렌더링합니다.timeline_view.py <video> <start> <end>— 플래그된 한 지점에 대한 필름스트립+파형 PNG. 스캔 도구가 아닙니다.contact_sheet.py <video> --times t1 t2 … -o sheet.png— 하나의 레이블이 있는 그리드에 N 프레임; 이미 알고 있는 여러 순간을 눈으로 확인하는 방법.watch_video.py <video> [--mode scene|keyframe|uniform] [--times t1 t2 …] [--start/--end] [--max-frames 24]— "이 영상 안에 무엇이 있나?" 확인할 위치를 모를 때: 장면 감지 + 지각적 중복 제거 →edit/verify/watch_<stem>/디렉토리에 레이블이 있는 연락처 시트 생성, 시트당 하나의 Read. 알 수 없는 자료의 시각적 인벤토리 및 verify_cut의 숫자 이상으로cut.mp4를 조사하기 위해 사용합니다.--times는 전사 큐 프레임을 고정합니다:takes_packed.md의 직시적 순간("olha isso", "como você pode ver")은 시각적 변화가 적고 장면 감지에서 보이지 않습니다 — 2단계에서 B-롤/콜아웃/줌 배치를 결정하기 위해 고정하십시오.
2단계/3단계 도우미(자막, 얼굴 추적, 이미지 검색, 음악)는 게이트를 통과한 후 로드하는 트랙 참조에 나열되어 있습니다.
인터페이스:
preview_server.py --root <edit> [--port 4820]— 표준 프리뷰 인터페이스를 제공합니다(프리뷰 인터페이스 섹션 참조). 앱 코드는assets/preview/에 있으며 변경할 수 없습니다.
프리뷰 인터페이스 (표준 — 모든 편집 세션 시작 시 실행)
모든 편집 세션은 사용자의 프리뷰 패널에서 동일한 대화형 인터페이스를 얻습니다: 비디오 편집 타임라인(필름스트립 비디오 트랙 + 파형 오디오 트랙), 실시간으로 렌더링을 스크러빙하는 라이브 플레이헤드, 테이크별 트림 핸들 및 테이크 제거, 그리고 2단계부터는 자막 및 삽입 트랙이 추가됩니다. 레이아웃은 소스 종횡비를 따릅니다: 세로 소스는 오른쪽에 키가 큰 플레이어와 왼쪽에 전송 + 타임라인을 배치합니다. 가로 소스는 플레이어를 타임라인 위에 쌓습니다. 어두운 유리 스타일, Cena Raiz 브랜드. 세션마다 UI를 구축하지 마십시오 — state.json으로 표준 인터페이스를 공급하십시오. assets/preview/ 편집은 사용자가 UI 변경을 요청할 때만 허용됩니다. 공유되므로 개선 사항이 모든 프로젝트에 적용됩니다.
실행 (세션이 시작될 때, 첫 번째 렌더링 전에도 수행 — UI는 대기 상태를 표시함):
-
<edit>/state.json작성:{"project": "Nome — C0000", "phase": 1, "video": "cut.mp4", "edl": "edl.json", "captions": "remotion/public/captions.json", "editData": "remotion/public/edit-data.json", "finalVideo": "final.mp4", "fps": 24, "message": "Fase 1 — cortando", "sourceDurations": {"C0000": 1038.5}, "awaitingStyle": false, "style": {"edit": "split", "captions": "karaoke", "elements": {"tracking": false, "zoomAuto": true, "zoomCuts": true, "musicAI": false}}}(
captions/editData/finalVideo는 존재할 때만 포함; 2단계 탭은finalVideo를 재생 — 자막/삽입이 포함된 렌더 — 1단계는 깔끔한 컷을 재생;sourceDurations는 UI가 테이크 확장을 제한하도록 함;awaitingStyle/style은 아래 Estilo 탭을 구동) -
런타임 어댑터를 선택하고 다른 호스트의 도구를 호출하지 마십시오.
- Claude Code:
.claude/launch.json에 구성이 있는지 확인하십시오(세션별로--root조정). 서버는 플래그로만 포트를 받으므로, 할당된$PORT를 전달하고autoPort를 설정하십시오:{"name": "cena-raiz-preview", "runtimeExecutable": "sh", "runtimeArgs": ["-c", "exec python3 <skill>/helpers/preview_server.py --root '<edit>' --port \"$PORT\""], "autoPort": true, "port": 4820}. 이름이cena-raiz-preview인preview_start를 실행한 다음, 동일한 턴에Monitor(command="python3 <skill>/helpers/watch_edits.py '<edit>'", description="escolhas e marcações salvas no preview", persistent=true)를 준비하십시오. - Codex 데스크탑 / CLI:
uv run python helpers/preview_server.py --root '<edit>' --port 4820을 환경이 유지할 수 있는 백그라운드 로컬 프로세스로 시작하십시오. 응답하면control-in-app-browser스킬을 사용하여http://127.0.0.1:4820을 앱 내 브라우저에서 자동으로 열고 해당 탭을 프리뷰에 유지하십시오.preview_start,Monitor또는.claude/launch.json이 있다고 가정하지 마십시오. 브라우저 기능이나 영구 로컬 프로세스를 사용할 수 없으면 대신 사용자에게 명령과 로컬 URL을 제공하십시오. 프리뷰를 보여준 후, 사용자에게 저장하고 다시 ...
- Claude Code:
[truncated for translation]