Claude Code로 만든 비디오 전사 도구: 멀티모달 에이전트 파이프라인 실전 구축

회의 녹화본이나 강연 영상을 던져 넣고 “여기서 무슨 슬라이드 보여줬지?”를 LLM에게 묻고 싶은 순간이 자주 있습니다. 그런데 대부분의 LLM은 비디오 파일을 직접 읽지 못하고, 음성을 텍스트로만 받으면 화면 위 차트·데모는 통째로 사라집니다. 이 간극을 메우려고 우리 팀은 Claude Code 멀티모달 에이전트로 비디오 전사 AI 도구를 직접 만들었습니다. Claude Code의 CLI 환경에서 mlx_whisper, 씬 감지, 프레임 단위 시각 해석을 하나의 타임라인으로 묶어내는 파이프라인입니다.

지난번 공개한 회의록 자동화는 오디오만 다뤘다면, 이번 도구는 화면에 표시된 슬라이드·차트·데모 스크린까지 같은 transcript에 병합합니다. 이 글에서는 Claude Code 에이전트 구축 관점에서 어떻게 4단계 파이프라인을 짰는지, 그리고 Codex·Gemini와의 비교·로컬 vs 클라우드 API 트레이드오프까지 정리합니다.

Claude Code 멀티모달 활용은 왜 비디오 분석에 적합한가?

비디오 한 편을 그냥 LLM에 던지면 두 가지가 무너집니다. 첫째, 토큰 비용이 폭발합니다. 1시간짜리 1080p 영상을 1초당 1프레임으로만 잘라도 3,600장이고, 멀티모달 모델은 이미지당 수천 토큰을 씁니다. 둘째, 프레임만 따로 주면 모델은 “스마트폰 화면입니다” 수준의 빈약한 답만 돌려줍니다. 화자가 어떤 맥락에서 이 화면을 띄웠는지가 빠져 있기 때문입니다.

Claude Code는 이 두 문제를 동시에 풀기 좋은 도구입니다. CLI 기반이라 로컬 파일 시스템에 자유롭게 접근하고, 외부 도구 호출을 자연스럽게 체이닝합니다. 별도 API key 없이 CLI만 깔려 있으면 mlx_whisper 같은 로컬 STT 도구와 결합해 맥 실리콘에서 완전 로컬로 돌릴 수 있다는 점이 결정적이었습니다. 회의 녹화처럼 외부에 올리기 꺼려지는 자료를 다루는 팀에게는 이 점이 곧 도입 가능 여부를 가릅니다.

비디오 전사 파이프라인은 어떤 4단계로 구성되는가?

도구의 전체 흐름은 단순합니다. 핵심은 “오디오와 프레임을 따로 처리하지 말고, 시간 축으로 묶어서 에이전트에게 던진다”는 한 가지 원칙입니다.

```

video.mp4

│

├── 1) 오디오 분리 → mlx_whisper → segments[].text + timestamp

│

├── 2) 씬 변화 감지 + hybrid interval → key_frames[].png

│

├── 3) 각 프레임 + ±30초 오디오 텍스트 → AI Agent 호출

│ (Claude Code / Codex / Gemini 중 선택)

│

└── 4) 오디오 + 프레임 description 머지 → transcript.md / .json

```

1단계 — 오디오 전사 (mlx_whisper): ffmpeg로 오디오를 추출한 뒤 mlx_whisper에 넘겨 한국어를 포함한 다국어 전사를 받습니다. 한국어 콘텐츠에서 흔한 hallucination(같은 문장 무한 반복) 방지 옵션을 켜고, segment별 타임스탬프를 보존합니다. 이 타임스탬프가 4단계 머지의 기준 축이 됩니다.

2단계 — 프레임 추출: 1초당 1프레임을 그대로 뽑으면 토큰이 터지므로, 씬 체인지 감지(픽셀 히스토그램 차이)와 일정 간격(예: 30초) 강제 추출을 hybrid로 섞습니다. 발표 슬라이드처럼 변화가 적은 영상은 키 프레임이 30~50장 수준으로 압축되고, 변화가 많은 데모 영상은 자동으로 더 촘촘히 잡힙니다.

3단계 — 컨텍스트 동봉 호출: 각 프레임을 단독으로 보내지 않고, 그 프레임 시각 ±30초 구간의 mlx_whisper 텍스트를 함께 프롬프트에 넣습니다. 같은 프레임이라도 결과가 완전히 달라집니다.

4단계 — 타임라인 머지: 오디오 segment와 프레임 description을 timestamp 기준으로 정렬해 한 줄짜리 마크다운 transcript와 구조화된 JSON 두 가지를 동시에 출력합니다. 마크다운은 사람이 빠르게 훑는 용도, JSON은 후속 RAG·검색 인덱싱 용도입니다.

Claude Code vs Codex vs Gemini, 에이전트 선택은 어떻게?

이 도구는 3단계 “프레임 + 오디오 컨텍스트” 호출부를 어댑터로 분리해 Claude Code, Codex, Gemini 셋 다 갈아 끼울 수 있게 만들었습니다. 한 달 정도 같은 영상으로 비교해 보면 각자 강점이 다릅니다.

• Claude Code: 한국어 회의·강연 분석이 가장 자연스럽습니다. “이 시점에 화면이 바뀌었는데 화자 의도가 뭔지” 같은 추론이 안정적이고, 슬라이드 텍스트 OCR 정확도도 높습니다. 회사 내부 회의록처럼 긴 맥락이 중요한 작업에 우선 추천합니다.
• Codex: 코드 데모, IDE 화면, 다이어그램이 많은 영상에서 강합니다. 함수명·변수명을 정확히 잡아내고, 화면 속 코드 스니펫을 그대로 transcript에 옮겨 적는 경우가 많습니다.
• Gemini: 영문 콘퍼런스 발표·튜토리얼처럼 영어 비중이 높고 시각 디테일(차트 축, UI 위젯)을 묘사해야 할 때 유리합니다.

실측해 보니 한 영상을 세 에이전트에 모두 돌리고 결과를 머지하면 품질은 가장 좋지만, API/토큰 비용이 단일 호출 대비 약 2.7배로 뜁니다. 우리는 기본을 Claude Code로 두고, 코드 데모 영상에 한해 Codex를 우회 라우팅하는 식으로 비용/품질을 타협했습니다.

로컬 실행 vs 클라우드 API, 어떤 걸 골라야 하나?

이 영역에서 가장 자주 받는 질문이 “AssemblyAI나 OpenAI Whisper API를 그냥 쓰면 되지 않느냐”입니다. 실제로 4주간 두 경로를 병행해 본 결과는 이렇습니다.

NDA가 걸린 고객사 회의나 사내 워크숍 녹화처럼 “외부에 못 올리는” 영상이 한 달에 10건만 넘어가도 로컬 파이프라인의 가치가 빠르게 회수됩니다. 반대로 공개 콘퍼런스·유튜브 분석은 클라우드 쪽이 단순하고 빠릅니다. 우리는 두 경로를 다 운영하면서, 입력 파일의 출처 메타데이터로 라우팅을 자동 분기시켰습니다.

다음 단계는 어떻게 적용하면 되나요?

코드는 github.com/treesoop에 OSS로 공개되어 있고, README의 quickstart대로 mlx_whisper와 Claude Code CLI만 설치하면 1시간 안에 첫 transcript가 나옵니다. 적용처 우선순위는 세 가지를 추천합니다. 첫째, 사내 정기 회의 자동 회의록(가장 ROI가 빠릅니다). 둘째, 외부 강연·교육 영상 정리 — 슬라이드 캡처와 발화 내용을 동시에 검색 가능한 인덱스로 만듭니다. 셋째, 제품 데모·QA 영상 자동 분석 — 화면 위 버튼 클릭과 화자 설명을 같이 transcript에 묶어 둡니다.

같은 “자동화 파이프라인을 어떻게 우리 워크플로에 끼워 넣는가” 주제로 이전에 정리한 Claude Code MCP 워크플로 사례도 함께 보시면 도구 선택 기준이 더 또렷해질 겁니다. 이번 비디오 전사 도구도 결국 같은 원칙입니다 — 모델을 바꾸지 말고, 모델에게 던져 주는 “맥락의 단위”를 바꿉니다. 비디오에서는 그 단위가 “프레임 + ±30초 오디오”였습니다.