Communitygithub.com

다큐멘터리 영상 스킬

모든 주제를 완성된 단편 다큐멘터리 영화로 바꿔줍니다. 연구, 사실 확인된 내레이션 대본, 음성 해설, 출처가 있는 아카이브 스틸 이미지, 자막, 크레딧, 배경 음악, 그리고 ffmpeg로 렌더링된 등급 조정 MP4까지 한 번에 제공합니다.

다큐멘터리 영상 스킬란 무엇인가요?

이 스킬은 사용자가 주제만 입력하면 연구부터 최종 MP4 파일까지 완성된 단편 다큐멘터리 영화를 자동으로 제작합니다. AI 에이전트가 웹 검색으로 신뢰할 수 있는 출처를 수집하고, 사실에 기반한 내레이션 대본을 작성하며, ElevenLabs 또는 오프라인 TTS를 사용해 음성을 합성하고, Wikimedia Commons 등 공개 아카이브에서 이미지를 검색해 가져옵니다. 최종 출력물은 1920x1080 해상도의 H.264/AAC MP4 파일, SRT 자막 파일, CREDITS.md, 대본, 그리고 사용된 모든 출처 목록을 포함합니다. 이 스킬은 Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있으며, 사용자가 별도의 소프트웨어를 설치하거나 직접 렌더링할 필요가 없도록 설계되었습니다. 내레이션은 분당 155단어로 작성되며, 3분 길이의 영화를 기준으로 약 460단어로 구성됩니다. 영화는 '후크(세계 소개) → 메커니즘(변화가 일어난 방식) → 대가(사람들에게 미친 영향) → 에코(변화된 후크로 돌아옴)'의 4단계 구조를 따릅니다. 모든 이미지와 음악은 라이선스를 확인하고 CREDITS.md에 기록하여 저작권 문제를 방지합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/0xAkashic/documentary-video-skill/tree/HEAD

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

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

문서

다큐멘터리 영상

사용자가 주제를 제시합니다. 당신은 완성된 영화를 제공합니다: out/<slug>.mp4 (1920x1080, H.264/AAC), 그리고 .srt, CREDITS.md, 대본, 출처. 사용자는 직접 설치, 조사, 작성 또는 렌더링할 필요가 없습니다. 결정이 명백히 사용자의 몫인 경우에만 멈추세요: 유료 생성, 다운로드에 권한이 필요한 경우, 또는 확인할 수 없는 사실 주장.

SKILL_DIR은 이 폴더입니다. DOC는 python3 "$SKILL_DIR/scripts/doc.py"를 의미합니다.

1. 쓰기 전에 구체화하세요

영화의 방향을 바꾸는 경우에만, 최대 두 가지 질문을 하세요: 길이 (기본 3분)와 관점 (영화가 주장하는 바, 단순한 주제가 아닌). 그 외의 모든 것은 당신이 결정합니다.

다큐멘터리는 그림을 곁들인 주장이지, 요약이 아닙니다. 시청자가 본 후에 따라 말할 수 있는 하나의 주장을 고르세요 -- "등대지기는 기술에 진 것이 아니라 스프레드시트에 진 것이다" -- 그리고 그 주장에 기여하지 않는 모든 것은 잘라내세요.

절대 사실의 목록을 영화로 만들지 마세요. 변화를 영화로 만드세요: 어떤 것이 사실이었다가 더 이상 사실이 아니게 되었고, 그 대가가 무엇인지.

2. 설정 (최초 실행 시)

DOC doctor

python3과 libx264가 포함된 ffmpeg가 필요합니다. Termux: pkg install ffmpeg. macOS: brew install ffmpeg. ffmpeg만 누락된 경우 설치하고 다시 실행하세요. doctor가 "Ready"라고 말할 때까지 다른 것은 쓰지 마세요.

DOC new <project> --title "The Last Lightkeeper" --subtitle "1985 -- 1997"

이 명령어는 project.json, shots.json, research.md, script.md, 그리고 work/img, work/audio, out 디렉토리를 생성합니다.

3. 연구

웹 검색을 사용하세요. 4~6개의 견고한 출처를 목표로 하세요: 1차 문서, 아카이브, 대학 또는 기관 페이지, 신뢰할 수 있는 저널리즘, 책 한 권. 결과뿐만 아니라 메커니즘을 설명할 수 있을 만큼 충분히 읽으세요.

research.md에 저장하세요:

# 연구

## 테제
영화가 주장하는 한 문장.

## 사실 (각각 출처 포함)
- 1841년: <사실> -- <출처 URL>
- <연도>: <사실> -- <출처 URL>

## 논쟁 / 불명확한 점
- <출처들이 동의하지 않는 부분과 영화에서 이를 표현할 방법>

## 시각 자료
- <아카이브, 컬렉션, 공개 도메인 이미지 검색 가능성>

내레이션의 모든 문장은 여기의 한 줄로 추적 가능해야 합니다. 두 출처가 의견을 달리하면, 화면에 그 사실을 밝히거나 사실을 버리세요. 숫자, 날짜, 인용구, 일화를 지어내지 마세요. 빠진 사실은 플롯 문제이지만, 가짜 사실은 사기입니다.

4. 대본 쓰기

쓰기 전에 references/script-craft.md를 읽으세요. 요약:

  • 분당 155단어. 3분 = ~460단어. 느낌이 아니라 막(act)별로 예산을 세우세요.
  • 네 가지 움직임: 변화 전 세계 (후크), 메커니즘 (변화가 어떻게 작동했는지), 대가 (사람들에게 미친 영향), 메아리 (변화된 후크로 돌아옴).
  • 문장당 하나의 생각. 줄당 한 호흡. 22단어를 넘는 문장은 금지.
  • 구체적 > 추상적. "그는 밤에 두 번 117계단을 올랐다"가 "그 일은 힘들었다"보다 낫습니다.
  • 이야기는 현재형, 판결은 과거형.
  • 내레이션이 주장을 전달하고, 캡션이 증거(이름, 날짜, 장소)를 전달합니다. 캡션이 이미 증명하는 것을 사운드트랙에서 말하지 마세요.

script.md에 막 별로, 한 줄에 한 문장씩 작성하세요. shots.json의 줄이 그대로 일치해야 하기 때문입니다:

## Act I -- 변화 전 세계
200년 동안, 누군가는 깨어 있어야 배가 해안을 찾을 수 있었습니다.
...

그런 다음 전체 대본을 한 메시지(약 30줄)로 사용자에게 보여주고 계속 진행하세요. 사용자가 검토를 요청하지 않는 한 승인을 기다리지 마세요.

5. 샷 목록

모든 필드와 완전한 예시를 보려면 references/shot-list.md를 읽고, shots.json을 작성하세요:

{"shots": [
  {"id": "s01", "kind": "card", "text": "The Last Lightkeeper",
   "sub": "A job that vanished in twelve years", "hold": 4.0},
  {"id": "s02", "line": "For two hundred years, someone had to stay awake.",
   "img": "work/img/cape-byron-1891.jpg", "motion": "zoom-in",
   "caption": "Cape Byron, 1891"}
]}

중요한 규칙:

  • line은 대본에서 그대로 가져온 내레이션이며 순서대로 있어야 합니다. 길이는 오디오에서 결정되므로, 줄이 바뀌면 편집도 바뀝니다.
  • 샷당 3.5~6초. 스틸 이미지는 생각보다 더 오래 보여줘야 합니다. 의도적인 플래시가 아니라면 절대 2.5초 미만으로 하지 마세요.
  • 하나의 이미지, 하나의 아이디어. 샷에 두 개의 이미지가 필요하다면 두 개의 샷입니다.
  • 카메라를 움직이고, 세계를 움직이지 마세요. zoom-in은 친밀감, zoom-out은 결과, pan-*은 풍경과 문서, static은 얼굴과 텍스트에 사용하세요.
  • 카드는 장(chapter) 구분입니다. 3분짜리 영화에 2~4개 사용하세요: 제목, 날짜나 숫자 하나, 그리고 마무리되는 마지막 카드. 카드에는 내레이션이 없습니다.
  • **caption**은 화면에 표시되는 작은 증거 줄입니다: 장소, 연도, 출처. 6단어 미만으로 유지하세요.

6. 스틸 이미지

실제 아카이브 자료를 선호하세요. 그것이 다큐멘터리와 슬라이드쇼의 차이입니다.

DOC archive <project> --query "Cape Byron lighthouse 1900" --n 3

이 명령어는 Wikimedia Commons를 검색하고, 사용 가능한 이미지를 work/img/에 다운로드하며, 저자와 라이선스 정보가 포함된 sources.json + CREDITS.md를 작성합니다. 기본적으로 공개 도메인, CC0 및 CC BY / BY-SA만 유지합니다. 게시된 영화는 일반적으로 상업적 사용이 필요하기 때문입니다. 엄격한 공개 도메인을 원하면 --license pd를, 모든 것을 보고 각 라이선스를 직접 확인하려면 --license any를 추가하세요.

아카이브에 자료가 없으면, 다음과 같은 우선순위로 진행하세요:

  1. 기타 오픈 컬렉션 -- Library of Congress, Smithsonian Open Access, NASA, Internet Archive, Europeana. 새 사이트에서 다운로드하기 전에 사용자에게 물어보고, 라이선스와 URL을 CREDITS.md에 기록하세요.
  2. 이미지 생성 -- 사용 가능한 이미지 도구를 사용하여 references/image-prompts.md를 참고해 이미지를 생성하세요. 생성된 프레임은 CREDITS.md에 AI 생성 복원으로 표시하고, 시청자가 사진으로 오해하지 않도록 캡션을 추가하세요.
  3. 타이포그래피 및 오브제 샷 -- 문서, 지도, 일지 페이지, 추상 판. 정직하고 저렴합니다.

절대 AI 이미지를 아카이브 자료로 제시하지 마세요. 그 한 줄이 이 형식의 전체 윤리입니다.

7. 내레이션

DOC tts <project>

ELEVENLABS_API_KEY가 설정된 경우 ElevenLabs를 사용하고(최상), 그렇지 않으면 오프라인 음성(espeak-ng, Android termux-tts-speak, macOS say)을 사용합니다. 한 번에 녹음합니다. 귀를 위해 쓰세요: 짧은 문장, 텅 트위스터 금지, 숫자는 발음되는 대로 철자.

음성이 전혀 없어도 영화는 예상 시간으로 렌더링됩니다. 이를 알리고, 사용자가 나중에 직접 내레이션을 녹음할 수 있도록 .srt를 제공하세요. line은 변경하지 않아 재녹음 시 바로 적용될 수 있도록 하세요.

녹음 품질이 모델 품질보다 중요합니다: 조용한 방에서 전화로 녹음한 것이 대부분의 다큐멘터리에 합성 음성보다 낫습니다. 그 옵션을 제안하세요.

8. 빌드 및 시청

DOC build <project> --draft     # 반복 작업 중 빠른 패스
DOC build <project> --subs      # 최종, 자막이 화면에 포함됨
DOC sheet <project>             # 12프레임 콘택트 시트

매번 out/contact.jpg를 확인하세요. 확인 사항:

  • 캡션 아래에 중요한 내용이 없고, 캡션이 프레임 밖으로 나가지 않았는지;
  • 컷이 문장 끝에 있고, 이미지의 빈 부분이나 관련 없는 부분에 샷이 머물지 않는지;
  • 등급이 일관되고, 얼굴이 뭉개지지 않았으며, 텍스트 이미지를 읽을 수 있는지;
  • 마지막 카드가 내레이션이 끝난 후에 나타나지, 내레이션 위에 겹쳐 나타나지 않는지.

shots.json(이미지, 모션, 캡션, 순서)을 편집하고 다시 빌드하여 수정하세요. 내부 클립은 샷 ID별로 캐시되므로 변경된 샷만 다시 렌더링됩니다.

속도. 렌더링은 CPU에 의존합니다. 1080p에서 3분짜리 영화는 노트북에서 약 1분, 휴대폰에서 10~20분이 소요됩니다. 항상 --draft(절반 해상도, 빠른 프리셋)로 반복 작업하고, 마지막에 한 번 전체 패스를 하세요. build는 각 샷이 진행될 때마다 출력하므로, 잘못된 렌더링을 중단할 수 있습니다.

9. 음악

음악을 추가하기 전에 사용자에게 물어보세요. 출처를 제안하고, 라이선스를 확인한 후 파일을 public/music/bed.mp3에 넣고 다음을 실행하세요:

DOC build <project> --music public/music/bed.mp3

음악은 반복되며, 약 14% 볼륨으로 설정되고 음성 아래로 자동으로 낮아집니다. 침묵은 합법적인 선택이며, 진지한 영화에는 종종 더 나은 선택입니다.

10. 전달

사용자에게 제공하세요:

  • MP4;
  • .srt (YouTube에서도 유용함);
  • CREDITS.md -- 모든 스틸 이미지, 저자, 라이선스, 링크;
  • 대본, 관점에 대한 한 단락, 그리고 3~5개의 출처 링크;
  • 아카이브 자료, 생성된 자료, 증거 부족으로 잘라낸 부분에 대한 솔직한 노트.

그런 다음 한 가지 다음 단계를 제안하세요: 더 긴 컷, 다른 오프닝, 두 번째 막, 또는 동일한 영화의 세로 60초 컷.

좋은 판단력

  • 영화는 주장이지, 영상이 아닙니다. 이미지는 아름다운데 주장이 모호하다면 다시 쓰세요.
  • 세 번째 예시는 자르세요. 두 개로 패턴이 증명되면, 세 번째는 목록일 뿐입니다.
  • 설명이 아닌 화면에 출처를 표시하세요. 연도와 장소가 있는 캡션이 시청자가 나머지를 신뢰하게 만듭니다.
  • 모르는 것을 말하세요. "아무도 그 숫자에 동의하지 않는다"는 자신 있는 잘못된 숫자보다 더 강력한 대사입니다.
  • 죽은 이를 존중하세요. 실제 인물, 실제 사건: 지어낸 대화, 기록으로 제시되는 재연, 실명 인물에 대한 생성된 얼굴은 금지.
  • 길이는 약속입니다. 자료가 90초만 뒷받침한다면, 90초를 전달하세요.

파일

  • scripts/doc.py -- 전체 파이프라인 (모든 플래그는 DOC -h)
  • references/script-craft.md -- 영화처럼 들리는 내레이션 작성법
  • references/shot-list.md -- 완전한 shots.json 스키마 및 작업 예제
  • references/sourcing.md -- 아카이브, 라이선스 규칙, 저작자 표시 형식
  • references/image-prompts.md -- 아카이브와 함께 사용할 생성 스틸 이미지 프롬프트
  • examples/last-lightkeeper/ -- 완성된 3샷 예제 (대본 + 샷)

관련 스킬