Communitygithub.com

daniela-socoloski/raiz-engine

대화 기반 동영상 편집 도구로, 짧은 세로형 (Reels, TikTok, Shorts) 및 긴 가로형 동영상을 자르고, 색보정하고, 자막을 추가하고, 그래픽을 삽입하고, 사운드트랙을 만듭니다.

raiz-engine란 무엇인가요?

Cena Raiz는 AI 에이전트(Claude Code, Codex 등)를 위한 비디오 편집 스킬로, 오디오 중심의 2단계 워크플로우를 통해 전문가 수준의 편집을 수행합니다. 1단계에서는 WhisperX 기반의 로컬 자동 전사 및 음성 강제 정렬을 통해 단어 경계를 정밀하게 파악하고, 자동 색보정과 J-컷 전환을 적용한 깔끔한 컷을 생성합니다. 2단계에서는 Remotion을 활용하여 자막(카라오케 스타일 포함), 그래픽, 이미지, 사운드트랙을 데이터 기반으로 추가합니다. 두 단계 사이에는 사용자의 명시적인 승인을 요구하는 게이트가 있어, AI가 무단으로 편집을 진행하지 않도록 합니다. 모든 편집은 ffmpeg 및 Python 스크립트로 로컬에서 이루어지며, Adobe MCP를 통한 Premiere Pro 연동도 지원합니다. 이 스킬은 토큰 사용을 최적화하여, JSON 대신 마크다운 형식의 전사본을 주로 읽고, 수치 기반 검증을 통해 시각적 확인을 최소화함으로써 AI의 판단 능력에 집중합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/daniela-socoloski/raiz-engine/tree/HEAD/skills/cena-raiz

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Cena Raiz

원칙

  1. 2단계, 게이트 하나. 1단계는 깔끔한 컷 + 색보정, 2단계는 자막, 그래픽, 이미지입니다. (하드 룰 1이 게이트를 강제합니다.)
  2. LLM은 원시 전사본 + 요청 시 시각 자료를 기반으로 추론합니다. 유일하게 유지되는 파생 아티팩트는 구문 단위 전사 파일(takes_packed.md)뿐입니다. 나머지는 결정 시점에 직접 도출합니다.
  3. 오디오가 우선이고, 시각 자료는 그 뒤를 따릅니다. 컷 후보는 음성 경계와 무음 구간에서 결정됩니다.
  4. 묻기 → 확인 → 실행 → 반복 → 저장. 사용자가 일반 언어로 전략을 확인하기 전에는 절대 컷을 건드리지 마십시오.
  5. 일반화하십시오. 자료를 살펴보고, 사용자에게 물어본 다음에 편집하십시오. 영상의 종류를 가정하지 마십시오.
  6. 예술적 자유가 기본값입니다. 여기 있는 특정 값은 예시일 뿐, 명령이 아닙니다. 하드 룰만이 필수입니다.
  7. 취향이 있는 곳에 토큰을 사용하십시오. 기계 데이터는 프로그램을 위한 것이지 읽기 위한 것이 아닙니다. 수치 검증이 시각적 검증보다 먼저입니다. 당신의 주의력은 희소한 자원입니다 — JSON을 파싱하는 것이 아니라 편집에 집중하십시오. (하드 룰 12와 13이 이것이 금지하는 바를 설명합니다.)

하드 룰 (프로덕션 정확성 — 변경 불가)

  1. 단계 게이트는 실제입니다. 컷이 승인되기 전에는 2단계 작업을 진행하지 마십시오.
  2. 세그먼트별 추출 → 무손실 -c copy 연결, 단일 패스 필터그래프는 사용하지 마십시오. (기본 J-컷에서는 테이크의 영상과 음성이 별도 범위로 추출되고 오디오 트랙이 합산됩니다 — 이것이 유일하게 허용된 믹스이며, 비디오 경로는 여전히 세그먼트별 + 무손실 연결입니다.)
  3. 모든 세그먼트 경계에 30ms 오디오 페이드 (render.py에 인코딩됨).
  4. 단어 내부에서 자르지 마십시오 — 전사본의 단어 경계에 맞춰 자르십시오.
  5. 모든 컷 가장자리에 패딩을 적용하십시오 (30–200ms 창, 트레일이 리드보다 약간 길게). 가능하면 무음 구간에서 자르십시오.
  6. 소스별로 전사본을 캐시하십시오. 소스가 변경되지 않았다면 다시 전사하지 마십시오.
  7. 추출 중에 세그먼트별로 색보정하고, 연결 후에는 하지 마십시오.
  8. **실행 전에 전략 확인.
  9. **모든 세션 출력물은 <videos_dir>/edit/**에 저장하십시오 — 절대 cena-raiz 저장소 내부에 두지 마십시오.
  10. 2단계는 Remotion 전용입니다 — ffmpeg/PIL로 텍스트나 오버레이를 직접 생성하지 마십시오.
  11. 2단계는 데이터 기반입니다. 트랙 템플릿을 복사하여 기본 구조를 만드십시오. public/edit-data.json에 비디오를 설명하십시오. 템플릿 TSX (src/Main.tsx 등)는 절대 읽거나 편집하지 마십시오 — 편집 가능한 유일한 코드 파일은 src/CustomGraphics.tsx이며, 맞춤 그래픽 전용입니다.
  12. 먼저 수치로 검증하십시오. 렌더링된 모든 컷에 대해 verify_cut.py를 실행하십시오. 문제가 있는 접합부에 대해서만 이미지를 여십시오. 여러 프레임을 한 번에 확인하려면 contact_sheet.py / grade.py --candidates 몽타주를 사용하십시오.
  13. 컨텍스트에 기계 데이터를 읽지 마십시오: 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는 대기 상태를 표시함):

  1. <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 탭을 구동)

  2. 런타임 어댑터를 선택하고 다른 호스트의 도구를 호출하지 마십시오.

    • 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을 제공하십시오. 프리뷰를 보여준 후, 사용자에게 저장하고 다시 ...

[truncated for translation]

관련 스킬