video-use 딥다이브
— 클로드 에이전트가 영상을 읽고 직접 편집하다

텍스트 우선 + 온디맨드 비주얼 (Text-First, Visual-on-Demand)

LLM이 영상 프레임을 직접 소비하지 않는다. ElevenLabs Scribe가 단어 단위 타임스탬프를 만들고, pack_transcripts.py가 0.5초 이상 침묵이나 화자 변경에서 구를 분리해 takes_packed.md로 압축한다. 1시간 분량도 12KB 텍스트 안에 들어간다. 시각 확인이 필요한 경우(애매한 포즈, 테이크 비교)에만 timeline_view.py로 PNG를 생성한다.

이는 browser-use의 "DOM 우선" 원칙과 동일하다. 스크린샷 1장 대신 구조화된 DOM을 주면 LLM이 훨씬 정확하고 저렴하게 작동한다.

2단계 렌더링: 세그먼트 추출 → 무손실 Concat

render.py는 세그먼트를 먼저 개별 추출해 컬러 그레이딩과 오디오 페이드를 각각 적용한 뒤(clips_graded/seg_00.mp4, ...), ffmpeg concat demuxer로 무손실 이어붙인다(-c copy). 이후 오버레이와 자막을 합성한다.

이 2단계 방식이 중요한 이유: 단일 패스로 처리하면 나중에 오버레이를 추가할 때 전체를 다시 인코딩해야 한다. 분리하면 오버레이 추가 시 concat된 base.mp4만 재처리한다 — 더 빠르고 화질 손실이 없다.

병렬 서브에이전트로 애니메이션 슬롯 처리

애니메이션 오버레이(HyperFrames, Remotion, Manim)가 여러 개 필요하면, 에이전트가 슬롯별로 서브에이전트를 병렬 생성한다. 각 서브에이전트는 독립된 animations/slot_<id>/ 디렉터리에서 작업하고, 전체 렌더링 시간 ≈ 가장 느린 슬롯 1개 시간이다. 순차 처리 대비 수 배 빠르다.

ffmpeg 실전 활용 — 영상 편집의 스위스 아미 나이프

이 레포는 ffmpeg의 다양한 기능을 실제 프로덕션 코드에서 활용한다. 단순 포맷 변환을 넘어 필터 그래프(filtergraph), 자막 렌더링(libass), HDR→SDR 톤매핑(zscale+tonemap), 오디오 페이드(afade), 무손실 concat demuxer까지 다룬다.

배울 것: -vf 필터 체인 조합, -af 오디오 필터, HDR 소스 처리 (iphone 영상의 HLG/PQ 문제), concat demuxer 패턴, ffprobe로 메타데이터 파싱.

LLM 에이전트 스킬 설계 — SKILL.md 패턴

SKILL.md는 LLM에게 "이 도구를 어떻게 사용해야 하는가"를 가르치는 문서다. 12개의 하드 룰과 그 이유를 함께 설명하고, 나머지는 "artistic freedom"으로 열어둔다. 이 설계는 LLM이 규칙을 외우는 것이 아니라 원칙을 이해하도록 유도한다.

배울 것: 에이전트 스킬 문서 작성법, "Ask → Confirm → Execute → Self-Eval → Persist" 패턴, 무엇을 하드 룰로, 무엇을 자유 재량으로 줄지 결정하는 설계 감각.

오디오 신호처리 기초 — numpy로 파형 분석

timeline_view.py의 compute_envelope()는 ffmpeg로 mono 16kHz PCM WAV를 추출한 뒤, numpy로 윈도우 RMS 엔벨로프를 계산한다. librosa 없이 표준 라이브러리 wave와 numpy만으로 오디오 분석을 구현했다.

배울 것: PCM 오디오 데이터 구조, RMS(Root Mean Square) 에너지 계산, 오디오 샘플링 레이트, numpy 배열 연산으로 신호처리.

자동 컬러 그레이딩 — 데이터 기반 색보정

grade.py의 auto 모드는 ffmpeg로 영상 세그먼트에서 프레임들을 샘플링하고, 평균 밝기·RMS 대비·채도를 계산해 최적의 eq=contrast:brightness:saturation 필터 값을 수치로 도출한다. 최대 ±8% 범위로 제한해 "보정된 것처럼 안 보이게" 만든다.

배울 것: ffmpeg vf 컬러 필터 체인, 이미지에서 HSV(색조·채도·명도) 분석, 알고리즘적 색보정 원리, curves 필터로 S-커브 적용.

ElevenLabs Scribe API — 단어별 전사

transcribe.py는 Scribe v1 모델에 timestamps_granularity=word, diarize=true, tag_audio_events=true를 설정해 단어마다 시작·끝 타임스탬프와 화자 ID를 반환받는다. 전사 결과는 소스별로 캐싱해 재실행 시 API를 다시 호출하지 않는다.

배울 것: Speech-to-Text API 설계, 화자 분리(diarization), 단어 레벨 타임스탬프 활용, API 응답 캐싱 패턴.

ffmpeg 기초: 영상 자르기와 오디오 페이드 ★☆☆ 입문

video-use의 핵심 hard rule 중 하나인 "30ms 오디오 페이드"를 직접 구현해본다. 아무 영상 파일에서 특정 구간을 추출하면서 오디오 페이드를 적용한다.

# 5초~12초 구간 추출 + 30ms 오디오 페이드
ffmpeg -ss 5 -i input.mp4 -t 7 \
  -af "afade=t=in:st=0:d=0.03,afade=t=out:st=6.97:d=0.03" \
  -c:v copy output.mp4

페이드 없는 버전과 비교해 컷 경계에서 소리 차이를 들어보자. 페이드가 없으면 "뚝" 소리가 난다.

pack_transcripts.py 동작 원리 분석 ★★☆ 중급

ElevenLabs Scribe API 없이도 pack_transcripts.py의 구조를 이해할 수 있다. 가상의 Scribe JSON을 직접 만들어 파이프라인을 테스트해보자.

# 가상 Scribe 응답 JSON 만들기 (edit/transcripts/test.json)
{
  "words": [
    {"type": "word", "text": "Hello", "start": 0.5, "end": 0.9, "speaker_id": "speaker_0"},
    {"type": "word", "text": "world", "start": 1.0, "end": 1.4, "speaker_id": "speaker_0"},
    {"type": "spacing", "start": 1.4, "end": 2.2},
    {"type": "word", "text": "Goodbye", "start": 2.2, "end": 2.8, "speaker_id": "speaker_1"}
  ]
}

# 실행
python helpers/pack_transcripts.py --edit-dir edit/

출력된 takes_packed.md를 보면서 0.5초 침묵과 화자 변경에서 구가 분리되는 것을 확인한다.

grade.py 컬러 프리셋 비교 실험 ★★☆ 중급

같은 영상 클립에 4가지 컬러 프리셋을 각각 적용해 결과를 비교해본다. 코드에서 확인한 프리셋: subtle, neutral_punch, warm_cinematic, none.

# neutral_punch 프리셋으로 그레이딩
python helpers/grade.py input.mp4 -o output_neutral.mp4 --preset neutral_punch

# warm_cinematic (창작 용도)
python helpers/grade.py input.mp4 -o output_warm.mp4 --preset warm_cinematic

# auto 모드 (수치 기반 자동 보정)
python helpers/grade.py input.mp4 -o output_auto.mp4

# 분석 결과 확인 (적용할 필터 수치 출력)
python helpers/grade.py --analyze input.mp4

간단한 EDL 작성 후 render.py로 영상 합치기 ★★★ 고급

Edit Decision List(EDL)를 직접 JSON으로 작성하고 render.py를 실행해 실제 영상 편집을 체험한다. 먼저 영상 파일의 길이를 ffprobe로 확인한 뒤 컷할 구간을 결정한다.

# ffprobe로 영상 메타데이터 확인
ffprobe -v quiet -print_format json -show_streams input.mp4

# edl.json 작성
{
  "source": "/path/to/input.mp4",
  "grade": "neutral_punch",
  "ranges": [
    {"start": 2.5, "end": 8.0},
    {"start": 15.3, "end": 22.7}
  ]
}

# 렌더링 실행
python helpers/render.py edl.json -o final.mp4 --no-subtitles

실제 Claude Code로 영상 편집 세션 진행 ★★★ 고급

video-use를 실제로 설치하고 짧은 영상(1~2분)으로 전체 워크플로를 체험한다. ElevenLabs 무료 계정으로 시작할 수 있다.

# 1. 설치 (Claude Code에 setup prompt 붙여넣기)
# 2. 영상 폴더로 이동 후 claude 실행
cd ~/Desktop/my_videos
claude

# 3. 에이전트에게 지시
> "이 영상들을 분석하고 불필요한 침묵과 umm/uh를 제거해줘. 60초 이하로 편집해줘."

에이전트가 전략을 제안하고 승인을 기다린다. 승인하면 전사 → 편집 → 렌더링 → 자기검증까지 자동 진행된다.