mk-video-editing은(는) 무엇을 하나요?
제공된 푸티지를 시청 가능하고 일관된 편집물로 만듭니다. 올바른 순서의 적절한 단어, 대상을 잘 프레이밍하는 카메라, 일관된 화면, 깨끗하고 레벨이 맞는 사운드, 그리고 세련된 타이틀. 구조는 푸티지와 그 안에 담긴 말에서 비롯됩니다.
스킬이 할 수 있는 작업
| 필요 | 도구 | 비용 | 참고 |
|---|---|---|---|
| 단어 대본, 필러/잘못된 시작/일시 정지 감지 | edit:transcribe (mlx-whisper), speech:flow | 무료, 로컬 | footage-editing.md |
| 안정화, 화자 추적, 4K 와이드 재구성(푸시, 펀치인, 팬), HDR→SDR, 플리커 제거, 색상 매칭, 디졸브, 점프 컷 | edit:analyze, edit:track, EDL + medit (edit:render) | 무료, 로컬 | footage-editing.md |
| 대화 정리, 믹스, 덕킹, 음량 | speech:clean (ISOLATE=1 Demucs), speech:mix, speech:measure | 무료, 로컬 | footage-editing.md |
| 나레이션 | voice:tts (ElevenLabs via Fal) | 유료, 승인 필요 | credentials.md |
| 타이틀, 하단 1/3, 엔드 카드 (ProRes 4444 알파) | mgraphics JSON 씬, graphics:render, scripts/tools/graphics/examples/ 템플릿 | 무료, 로컬 | graphics README |
| 편집 배경 음악 | EDL music (덕킹됨), music:score (ElevenLabs Music via Fal), audio:analyze 비트 타이밍 | 생성 시에만 유료 | finishing.md |
| 타이틀/전환 효과음 | SoundSynth (synth: whoosh, riser, impact, tick…), sfx:gen/sfx:mix 또는 EDL sounds | 무료 (Stable Audio prompt: 유료) | finishing.md |
| 영상 효과 (flash, dip, punch, glow, lens, streaks…) | mvfx 큐 시트, vfx:stills/vfx:render | 무료, 로컬 | finishing.md |
| 전달 인코딩 | media:twitter, media:youtube, media:faststart | 무료, 로컬 | tasks.md |
| 독립 작업에 대한 병렬 하위 에이전트 | work:next/work:accept/work:log/work:watch | 무료 | tasks.md |
모든 작업과 그 인수 및 옵션은 tasks.md에 있습니다. 테스트 프로필은 testing.md에 있습니다.
실행 계약
macOS 14+ Apple Silicon에서 Claude Code용으로 설계되었습니다(Swift 5.9+, Ruby 3.2+, Bundler, FFmpeg, ImageMagick, 로컬 Whisper용 uv). 누락된 도구로 인해 작업이 실패하면 먼저 doctor를 실행하고, setup은 Swift 도구를 빌드합니다. Ruby가 유일한 실행 진입 계층입니다: ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project 'task[args]'를 실행하세요. 작업은 네이티브 Swift 도구 medit (scripts/tools/edit), mgraphics (scripts/tools/graphics) 및 mvfx (scripts/tools/vfx)를 구동하는 Ruby 서비스(lib/media/edit.rb, speech.rb, guard.rb, …)에 위임됩니다. 기능이 누락된 경우 Ruby 메서드와 간단한 작업을 추가하세요. 프로젝트는 자체 복사본의 lib/ 및 tools/를 실행합니다. 스킬을 변경한 후에는 변경된 파일을 프로젝트에 rsync하세요.
메모리 안전 (필수)
4K/HDR 하드웨어 디코드는 프레임을 작업 자체 메모리 공간 외부의 VTDecoderXPCService에 유지합니다. 스왑이 없는 16GB 시스템에서 메모리를 소진하면 속도가 느려지는 대신 컴퓨터가 멈춥니다. 따라서:
- 한 번에 하나의 무거운 작업만 실행하세요(medit analyze/render/stills, mgraphics 인코딩, Demucs, 큰 ffmpeg 인코딩). 여러 작업을 서로 옆에서 병렬 또는 백그라운드로 실행하지 마십시오. 필요한 경우 하나의 백그라운드 명령에서 순차적으로 연결하세요. RAM이 32GB 이상이 아니면
JOBS는 1로 유지됩니다. - 모든 medit/mgraphics/mvfx 렌더 호출은
Media::Guard를 통해 이루어집니다(Ruby 서비스에서 자동으로 처리됨): 0.3초마다 작업 + 디코더 메모리 사용량 및 커널 여유 %를 샘플링하고MEDIT_MAX_FOOTPRINT_MB(기본값 3500)를 초과하거나MEDIT_MIN_FREE_PCT(기본값 30) 미만이 되기 전에 SIGKILL을 보냅니다. 여유 메모리가 이미 낮으면 시작을 거부합니다. 세 렌더러 모두 기본값은JOBS=1입니다. 병렬 청크에는 명시적인JOBS설정이 필요합니다. - 새로운 디코드/렌더 코드 경로는 먼저 짧은 범위와 엄격한 제한으로 검증하세요(
TO=15 MEDIT_MAX_FOOTPRINT_MB=1500 MEDIT_GUARD_LOG=/path/log). 로그가 평평한지 확인한 후 전체 길이로 실행하세요. - Swift 미디어 루프에서 각
copyNextSampleBuffer및 Core Image 렌더를autoreleasepool로 감싸세요(비동기 코드는 기본 풀을 비우지 않습니다. 프레임이 ~1.5GB/s 속도로 누출됩니다).
측정된 정상 상태: 분석 ≈ 4K HLG 소스당 1.0GB(작업 + 디코더); 디졸브가 있는 렌더는 두 소스를 엽니다.
1. 인테이크
누락된 것만 물어보세요: 푸티지 경로, 편집 내용(강연 발췌, 요약…), 타이틀/크레딧 텍스트, 대상 길이, 나레이션 요청 사항. 미디어로 초기화합니다(심볼릭 링크됨, 절대 복사되거나 수정되지 않음):
ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" init --project /abs/project --media /abs/clip1.MOV --media /abs/clip2.MOV --prompt-file /abs/brief.md
ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project setup
각 소스를 조사합니다(ffprobe: 크기, fps, 길이, HDR 전송). 오디오를 추출하고(audio/raw/*.wav, 48 kHz) 로컬로 대본을 작성합니다: edit:transcribe[analysis/transcripts,source/...] (mlx-whisper large-v3-turbo, 단어 시간, 무료). 모든 대본을 읽고 각 클립이 말하는 내용을 타임스탬프와 함께 docs/BRIEF.md에 작성합니다. 타이틀에 사용될 이벤트 사실을 웹 검색하고 출처를 기록합니다.
2. 분석 (순차적으로)
REGION=0,0,1,0.62 DETECT_REGION=0.15,0.3,0.85,0.8 mv 'edit:analyze[source/A.MOV,analysis/A.json]' # 한 번에 하나씩
mv 'edit:track[analysis/A.json,analysis/A.track.json]' # 화자가 조기에 발견되지 않으면 SEED=x,y; 안정화를 위한 SPACE=frame: 0
mv 'edit:stats[analysis/A.json,from,to]'
REGION은 안정화(위상 상관)를 정적인 배경(무대, 스크린)으로 제한하고 관객을 제외합니다.DETECT_REGION은 약 2배 해상도로 Vision 사람 감지를 위해 무대 영역을 자릅니다. 먼 화자에게 필수적입니다(감지율이 샘플의 2%에서 40–90%로 향상됨).- 트랙은 월드 록(안정화 제거)되고, 연속성이 선택되며,
max_aspect을 통해 넓은 전경 상자(머리)를 드롭합니다. - 휴대폰 푸티지(iPhone 등)는 카메라 내에서 이미 안정화되었습니다:
stabilize: 0및SPACE=frame트랙으로 렌더링하세요. 당사의 안정화 도구는 움직이는 슬라이드 콘텐츠를 카메라 움직임으로 오인하여 갑작스러운 수평 점프를 추가할 수 있습니다. 확인: 분석에서|Δshift| > 8 px인 프레임 수를 세십시오. iPhone 4K의 잔여 흔들림은 약 0.9px RMS로 측정되어 수정할 가치가 없습니다.
스피치 플로우 (필러, 잘못된 시작, 반복, 부자연스러운 일시 정지)
VERBATIM=1 mv 'edit:transcribe[analysis/transcripts_verbatim,source/A.MOV]' # Whisper가 음/어를 쓰도록 유도
mv 'speech:flow[analysis/transcripts_verbatim/A.json,audio/clean/A.wav,analysis/flow/A.json]' # analysis/flow/A.txt 읽기
감지기는 일시 정지를 음향학적으로 측정하고(에너지 + 발성, Whisper 단어 시간 아님), 분류하며(문장/쉼표/구) 필러, 대본 없는 흠, 반복 및 가능한 잘못된 시작을 각각 제안된 cut으로 플래그 지정합니다. 각각을 의미에 따라 결정한 다음 생성기(4단계)에서 Media::Cuts를 사용하여 컷을 적용하십시오. "~하기 위해—"와 같은 자기 수정 및 중단된 문장(박수 전 완성되지 않은 마지막 문장)을 .txt를 읽어 찾아보십시오. 감지기는 후보만 제안합니다.
- 전체 프레임 색상 통계는 프로젝션 스크린에 의해 지배됩니다. 트랙 주변 타일(화자 영역)의 노출을 매칭하고 스틸 샷에서 화이트 밸런스를 판단하십시오.
3. 계획 및 승인
docs/PLAN.md 작성: 선택 테이블(소스, 문장 경계에서의 in/out, 내용, 결합: 디졸브/점프 컷), 타이틀, 나레이션 텍스트, 카메라 언어, 영상 및 오디오 처리. 채팅에서 요약하고 NOTE='...' plan:approve로 승인을 기록하십시오(유료 호출 전에도 필요, 예: voice:tts를 통한 ElevenLabs 나레이션; credentials.md 참조 — 플러그인 세션에서 유료 작업은 mk-video-editing MCP 서버를 통해 실행됩니다).
4. 생성기 스크립트로 EDL 빌드
edit/build_edl.rb 작성(전체 EDL 스키마 및 작업 예제는 footage-editing.md 참조). 샷 어휘를 정의하고(WIDE zoom≈1.2–1.4, MWIDE fit≈0.4, MED fit≈0.56, max_zoom 3.6으로 제한된 PUNCH fit≈0.72) 대본에서 가져온 소스 초 단위로 카메라 비트를 작성하십시오: 6–12초에 걸친 느린 푸시, 강조 라인에서 컷 펀치인, 주제/슬라이드 변경 시 와이드로 컷, 모든 점프 컷에서 재구성. 클립당: safe 영역(방해가 되는 전경 유지), deflicker, grade 매칭; 하나의 공유 look. 오버레이는 ProRes 4444 알파 타이틀입니다(아래 타이틀 참조).
lib/media/cuts.rb를 사용하여 선택 항목 내 단어와 일시 정지를 제거하십시오: Media::Cuts.pause_cuts (자동으로 부자연스러운 일시 정지 단축), Media::Cuts.segments (선택 항목을 점프 컷 세그먼트로 분할, 경계를 단어 사이의 가장 조용한 지점에 스냅, 각 세그먼트를 대비되는 프레이밍으로 열고, 모든 줌을 ≥ 4.5초로 유지), Media::Cuts.text (각 컷이 제거한 내용을 edit/cuts.txt에 기록). 각 선택 항목을 침묵으로 시작 및 종료하고 카메라 핸들링(가장자리 근처 이동 속도 확인)에서 멀리 떨어지게 하십시오. 작업 예제는 footage-editing.md에 있습니다.
5. 오디오
speech:clean[audio/raw/A.wav,audio/clean/A.wav] (PRESET=room: 럼블 컷, FFT 노이즈 제거, 머드 컷, 프레즌스, 디에싱, 부드러운 확장기, 레벨러; ISOLATE=1은 로컬 Demucs 보컬용). 요청 시 voice:tts로 나레이션을 추가하십시오(MODEL=v4 for Eleven v4). 브리핑에서 요청하는 경우에만 배경 음악을 추가하십시오: 제공된 트랙 또는 music:score를 EDL music으로 배치합니다(finishing.md). 그런 다음 speech:mix[edit/edl.json,audio/mix.wav]를 실행합니다. 클립 오디오를 디졸브에서 크로스페이드와 혼합하고(audio_xfade: 0.15는 0.6초 디졸브 전 마지막 단어를 유지), 나레이션 아래에서 audio_duck, sounds, 사이드체인 덕킹이 있는 music을 적용한 후, 투패스 loudnorm을 −16 LUFS / −1.5 dBTP로 적용합니다.
6. 검토, 렌더링, 전달
DEBUG=1 edit:stills[edit/edl.json,edit/review/vN,t1,t2,...]— 각 스틸 샷과 전체 소스 프레임을 자르기(빨간색), 피사체(녹색) 및 안전 영역(노란색)과 함께 표시합니다. 프레이밍, 헤드룸, 전경 침입, 컷 간 노출/WB 연속성을 확인합니다.edit:sheet연락처 시트;edit:preview[edl,out.mp4,from,to]변경된 범위의 절반 해상도 초안.edit:render[edit/edl.json,output/final.mp4](JOBS=1). 전달된 마스터를 덮어쓰지 마십시오.- 비디오 렌더링 전 QA:
speech:mix, 그런 다음 믹스를edit:transcribe로 대본을 작성하고 각 클립의at주변 단어를 읽습니다(저렴함; 잘린 단어 및 단일 단어 플래시 포착). 렌더링 후 최종 파일을 다시 대본으로 작성합니다. 버전 및 이슈를docs/REVIEW.md에 기록합니다.
비디오, 계획/브리핑/검토 문서 및 선택 사항 및 알려진 이슈에 대한 간단한 요약을 전달합니다. 툴킷 변경 후 testing.md의 RSpec 프로필을 실행하고 렌더러 변경 후 tools/graphics에서 swift test를 실행합니다.
타이틀
scripts/tools/graphics/examples/의 템플릿에서 시작하십시오: opening_title.json, lower_third.json 및 end_card.json (1920×1080, AvenirNext, 하나의 악센트 색상). 이를 edit/titles/에 복사하고 텍스트 및 타이밍을 변경하거나, 여러 개가 있을 경우 edit/make_titles.rb에서 생성하십시오. 이름, 역할 및 이벤트 사실을 웹에서 확인합니다.
- 샷의 한 프레임 위에
ONLY=를 사용하여 스틸을 렌더링하고(PLATE=), 가독성, 안전 여백 및 악센트를 확인합니다. - 편집의 fps로
CODEC=prores4444 SUPERSAMPLE=2 graphics:render[edit/titles/x.json,edit/titles/x.mov,frames,1920,1080,fps]를 실행합니다. - 이를 EDL
overlays항목으로 배치하고, 카메라dim/blur로 오프닝 카드 아래 플레이트를 어둡게 하거나 흐리게 합니다.
씬 형식(노드, 트랙, 이징, 글로우, 폰트)은 graphics README에 있습니다. 렌더러 변경 후 scripts/tools/graphics에서 swift test를 실행하고 이전 및 새 타이틀 렌더를 바이트 단위로 비교하십시오.
마무리 (선택 사항)
배경 음악, 음향 효과 및 영상 효과는 선택적 패스이며, finishing.md에 설명되어 있습니다:
- 배경 음악은 렌더링 전에
speech:mix로 들어갑니다; - SFX (
sfx.yml) 및 VFX (cues.yml)는 렌더링된 마스터에서 실행되며 항상 새 파일을 씁니다.
브리핑에서 프로모 또는 요약 느낌을 요구할 때 사용하십시오. 깔끔한 강연 편집에는 거의 필요하지 않습니다.
병렬 작업
긴 편집의 경우 독립적인 작업(타이틀, 나레이션 라인, 섹션별 리뷰 스틸, QA 대본)을 depends와 함께 config/production.json으로 분할하십시오. work:next를 통해 하위 에이전트에 전달하고, work:log로 보고하게 한 후, 검토 후 각각을 승인하십시오(work:accept). 하위 에이전트는 씬, 스크립트 및 문서를 병렬로 작성할 수 있습니다. 무거운 미디어 작업(medit, mgraphics/mvfx 인코딩, Demucs)은 여전히 한 번에 하나씩 실행됩니다(위의 메모리 안전 참조).