다큐멘터리 영상
사용자가 주제를 제시합니다. 당신은 완성된 영화를 제공합니다: 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를 추가하세요.
아카이브에 자료가 없으면, 다음과 같은 우선순위로 진행하세요:
- 기타 오픈 컬렉션 -- Library of Congress, Smithsonian Open Access, NASA, Internet Archive, Europeana. 새 사이트에서 다운로드하기 전에 사용자에게 물어보고, 라이선스와 URL을
CREDITS.md에 기록하세요. - 이미지 생성 -- 사용 가능한 이미지 도구를 사용하여
references/image-prompts.md를 참고해 이미지를 생성하세요. 생성된 프레임은CREDITS.md에 AI 생성 복원으로 표시하고, 시청자가 사진으로 오해하지 않도록 캡션을 추가하세요. - 타이포그래피 및 오브제 샷 -- 문서, 지도, 일지 페이지, 추상 판. 정직하고 저렴합니다.
절대 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샷 예제 (대본 + 샷)