서론

저는 대만에서 1인 회사를 운영하는 Leo라고 합니다. 엔지니어는 아니며, 코드는 거의 AI 에이전트(Claude)가 작성해 줍니다. 이 글은 저 같은 비엔지니어가 'Claude에게 동영상을 보여주고 싶다'는 단 하나의 목표로 OSS를 만들게 된 이야기입니다.

리포지토리는 여기입니다.

개발 동기: LLM은 동영상을 '볼 수 없다'

업무 특성상 참고하고 싶은 릴스 영상의 분석이나, 제가 만든 콘텐츠 점검을 매일 합니다. 이를 Claude에게 맡기고 싶지만, 동영상 파일을 전달해도 LLM은 볼 수가 없습니다. 텍스트와 정지 이미지는 읽을 수 있는데, 동영상만 빈틈이 있습니다.

'프레임을 잘라서 주면 되지 않을까'라고 생각하며 시작했지만, 실제로 해보니 상상했던 것보다 훨씬 깊은 문제였습니다.

작동 원리: ffmpeg + 전사(Transcription) + 타임스탬프

핵심 구조는 간단합니다.

• ffmpeg로 동영상에서 일정한 간격으로 프레임을 추출한다.
• 거의 같은 프레임(정지 장면의 연속 등)은 건너뛰어 토큰을 절약한다.
• 음성을 Whisper로 전사하여 타임스탬프가 포함된 텍스트를 만든다.
• 프레임 이미지 + 전사 내용 + 각 프레임의 시간 정보를 세트로 Claude에게 전달한다.

프레임 추출만 한다면 한 줄입니다.

ffmpeg -i input.mp4 -vf "fps=1/2" frames/%04d.jpg

어려운 부분은 여기서부터인데, '무엇을, 어느 밀도로, 어떤 메타데이터와 함께 전달할지'가 출력물의 품질을 거의 결정합니다.

실측으로 알게 된 것: 타임랩스를 '실시간'이라고 주장하는 문제

가장 흥미로웠던 실패 사례입니다.

구름이 흐르는 타임랩스(실제 시간은 수 시간, 영상은 10초)를 전달했더니, Claude는 자신만만한 태도로