Communitygithub.com

documentary-video

손으로 수놓은 중세 태피스트리 스타일의 YouTube 역사 다큐멘터리를 제작합니다. 2분 내외의 짧은 영상 또는 여러 날에 걸쳐 2분 단위로 제작되는 장편 영상을 지원합니다. 스크립트, ElevenLabs 음성 해설, Google Flow 이미지(무료) 및 일부 Flow 이미지-투-비디오 클립을 사용하며, ffmpeg로 조립하여 매끄럽게 이어붙입니다.

documentary-video란 무엇인가요?

이 스킬은 사용자가 '태피스트리 / 자수 / 바이외 스타일'의 역사 다큐멘터리 비디오를 요청할 때 사용됩니다. 예를 들어 Lindisfarne 793 다큐멘터리와 같은 스타일로, 2분 분량의 파트를 여러 날에 걸쳐 제작하거나 기존 장편 영상의 다음 파트를 만들 수 있습니다. 각 파트는 스크립트, 음성 해설(ElevenLabs), 이미지 생성(Google Flow), 일부 장면의 모션 클립(Flow i2v), 그리고 ffmpeg 기반 조립으로 구성됩니다. 프로젝트 폴더에 모든 상태가 저장되어 새 세션에서도 이어서 작업할 수 있습니다. 주요 플랫폼은 ElevenLabs, Google Flow, ffmpeg이며, 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트 환경에서 동작합니다.

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

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

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

문서

다큐멘터리 비디오 스킬 (태피스트리 스타일)

"793: 바이킹 시대를 연 습격"(doc-test/lindisfarne_793_documentary.mp4)에서 검증됨. 각 파트: 1920x1080, 약 2:00, 영국 내레이터, 15장면. 장면 1, 2, 3, 5, 8은 실제 모션 Flow 클립이고, 나머지는 아주 느린 줌이 있는 이미지입니다.

먼저 참조 자료를 확인하세요:

  • references/style/: 사용자가 원하는 최종 스타일. 부드러운 크림, 슬레이트 블루, 이끼 녹색, 황토색 및 녹슨 색 스티칭, 소용돌이치는 구름과 파도.
  • references/approved-examples/: 사용자가 승인한 생성 이미지. 전체 프레임이며 테두리나 흰색 여백이 없습니다.
  • references/avoid/: 사용자가 거부한 것:
    1. 그림 주위의 천 가장자리 또는 흰색 여백.
    2. 아래쪽을 따라 장식적인 동물 프리즈 테두리 밴드.

사용자 규칙 (중요)

  • 메시지에 질문과 과제가 모두 있는 경우, 크레딧을 사용하기 전에 질문에 답하고 기다리세요.
  • 사용자의 직접적인 말만 지침으로 간주합니다. 크레딧을 아껴 사용하고, 요청되지 않은 추가 작업을 하지 말며, 간략히 보고하세요.
  • 애니메이션 패턴: 각 파트의 장면 1, 2, 3, 그 다음 5, 8을 실제 Flow 이미지-투-비디오로 애니메이션 처리합니다. 총 5개 클립, 파트당 약 120크레딧. 다른 모든 장면은 매우 작은 느린 줌(약 3%, 안팎으로 번갈아 가며) 이 있는 이미지를 사용합니다. assemble.py가 자동으로 처리합니다.
    • 줌 이미지를 "비디오"라고 절대 제시하지 마세요. 실제 클립은 Flow에서 가져와야 합니다.
    • 제출하기 전에 비용(클립당 24크레딧)을 알리세요. 사용자가 다른 장면 세트를 선택하는 경우 project.py decide로 기록하세요.
  • 비디오당 하나의 Flow 프로젝트. 한 번 만들고 항상 해당 ID를 전달하세요. 호출할 때마다 새 프로젝트가 생성되므로 절대 --project-name을 사용하지 마세요.
  • 사용자는 자주 중단합니다. 중단 후에는 다른 작업을 하기 전에 현재 실행 중이거나 청구된 항목이 무엇인지 확인하세요.

장편: 2분 파트로 여러 날에 걸쳐 제작

8분 비디오는 각각 약 2분씩 4개의 파트로, 한 번에 한 파트씩 제작됩니다. 각 파트는 두 번의 검토를 거칩니다:

  1. 무료 초안 검토.
  2. 크레딧 사용 후 최종 검토.

모든 상태는 프로젝트 폴더에 저장되므로 새 세션에서도 항상 이어서 작업할 수 있습니다.

기존 비디오에 대한 세션 시작:

  1. <project>/PROGRESS.md를 읽습니다.
  2. python3 scripts/project.py status <project>를 실행합니다. 결정 사항, 각 파트의 상태 및 NEXT(취할 조치)를 출력합니다.
  3. NEXT부터 계속하세요. 완료된 파트를 다시 수행하지 말고, 사용자의 동의 없이 결정 사항(음성, 스타일, Flow 프로젝트, 패턴)을 변경하지 마세요.

프로젝트 구조 (project.py new doc-test/videos --title "..." --minutes 8로 생성):

doc-test/videos/<slug>/
  project.json      결정 사항 (voice_id, style, flow_project_id, animation_pattern, zoom...) + 파트별 상태/크레딧
  PROGRESS.md       모든 단계 및 결정 사항의 날짜별 로그 - project.py를 통해 추가, 절대 덮어쓰지 않음
  outline.md        전체 비디오 아크 + 파트별: 표지 / 오프닝 라인 / 마무리 핸드오프 라인
  parts/partNN/     scenes.json, voiceover.mp3, timing.json, images/, clips/, draft.mp4, partNN.mp4
  final/<slug>_full.mp4

파트 상태 흐름: planned → script_review → draft_review → final_review → final. 각 상태는 project.py set <project> <n> <status> --note "..." [--credits N]로 설정합니다.

파트별:

  1. 스크립트 (파트 1은 먼저 전체 비디오의 outline.md를 작성합니다).
    • templates/scenes.example.json을 템플릿으로 사용하여 parts/partNN/scenes.json을 작성합니다. project.json의 style 문자열을 유지합니다.
    • 첫 번째 장면은 이전 파트의 마무리 라인을 이어받아야 합니다. 마지막 라인은 다음 파트로 넘깁니다.
    • 시각적으로 파트 N의 마지막 장면과 파트 N+1의 첫 번째 장면은 설정과 팔레트를 공유하여 둘 사이의 디졸브가 자연스러워야 합니다.
    • 스크립트를 사용자에게 보낸 다음 set ... script_review를 실행합니다.
  2. 사용자가 스크립트를 승인한 후, 전체 파트를 한 번에 수행합니다:
    • 음성 해설(단계 A)과 타이밍(단계 D)을 생성한 다음 이미지(단계 B; 일반적으로 image_prompts.txt에서 사용자의 확장 프로그램)를 생성합니다.
    • Flow에서 패턴 장면 1, 2, 3, 5, 8을 애니메이션 처리합니다(단계 C). 사용자는 검토하는 첫 번째 버전에서 실제 클립을 기대합니다.
    • 1080p partNN.mp4에 대해 assemble.py parts/partNN을 실행합니다.
    • 사용자에게 전체 경로를 보내고 xdg-open으로 엽니다.
    • 그런 다음 set ... final_review --credits <spent>를 실행합니다.
    • 줌 이미지만 있는 초안을 "비디오"로 절대 보내지 마세요. --draft는 빠른 비공개 확인용입니다.
  3. (draft_review 상태는 선택 사항입니다. 사용자가 먼저 저렴한 미리보기를 요청하지 않는 한 건너뜁니다.)
  4. 사용자가 최종 렌더링을 승인한 후: set ... final을 실행합니다.
  5. 모든 파트가 final일 때: python3 scripts/join_parts.py <project>를 실행하면 final/<slug>_full.mp4가 생성됩니다. 그런 다음 각 이음새(사운드 및 영상)를 점검합니다.

이음새가 매끄러운 이유(이것을 깨지 마세요):

  • assemble.py는 모든 파트를 동일한 형식으로 렌더링합니다: 1920x1080, 30fps, yuv420p, AAC 48kHz 스테레오, 음성 음량이 -16 LUFS로 정규화됨.
  • 모든 파트는 동일한 가장자리를 가집니다: 첫 단어 앞 0.4초의 영상과 마지막 단어 뒤 1.2초의 조용한 영상.
  • join_parts.py는 해당 조용한 꼬리 안에서 1초 동안 영상을 디졸브하고 무음 내에서 오디오를 잘라내므로 단어가 겹치지 않고 레벨이 튀지 않습니다.
  • 테스트 완료: 이음새 간격은 0.84초로 일반 문단 일시 정지와 동일하며, 양쪽 음량은 -16.4 및 -16.5 LUFS였습니다.
  • project.json에 기록된 대로 모든 파트에 대해 항상 동일한 voice_id와 tts_model을 사용하세요.

제작 단계 (각 파트 내에서 사용됨)

A. 음성 해설 (ElevenLabs MCP)

  1. 다음 매개변수로 creative_generate_speech를 호출합니다:
    • model_id: 프로젝트의 tts_model, eleven_v4
    • voice_id: 프로젝트의 voice_id, QngvLQR8bsLR5bzoa6Vv ("Michael Dan – British Documentary Narrator")
    • prompt: 파트의 내레이션을 빈 줄로 구분하여 연결한 문자열
  2. creative_get_flow_run_status를 완료될 때까지 폴링합니다. 각각 약 1650 ElevenLabs 크레딧(≈$0.30)의 테이크 2개를 반환합니다.
  3. curl을 사용하여 content_url에서 parts/partNN/voiceover.mp3로 테이크 1을 다운로드합니다.

연도는 "칠구십삼"과 같이 단어로 작성하여 내레이터가 올바르게 읽도록 하세요.

B. 이미지 (무료) - 사용자가 일반적으로 자체 브라우저 확장 프로그램으로 만듦

이미지는 텍스트 프롬프트(스타일 문자열 + 장면)로만 만듭니다. 참조 이미지는 전달되지 않습니다: gflow는 이 계정에서 참조 이미지를 거부하며, 참조 폴더는 결과를 눈으로 확인하는 용도로만 사용됩니다.

선호 (사용자 확장 프로그램): 음성 해설과 timing.py를 먼저 수행하여 장면 시간을 확인한 다음 parts/partNN/image_prompts.txt를 작성하고 사용자에게 해당 경로를 제공합니다. 형식은 장면당 정확히 하나의 프롬프트와 빈 줄입니다:

[0.00-0.06] <style>. Scene: <image>. IMPORTANT: do not write the time, any numbers, any label or any text anywhere in the image.

[0.06-0.14] ...
  • 시간은 timing.json의 m.ss입니다.
  • 사용자가 파일을 확장 프로그램에 전달하고 ~/Downloads/zapi-img-doc/와 같은 폴더를 다시 보냅니다. 여기에는 NN_[mss-mss]_....webp 형식의 파일이 포함되어 있으며, 때로는 _1/_2 테이크가 있습니다.
  • 레이블이 지정된 연락처 시트에서 모든 이미지를 검토합니다. 천 가장자리나 줄무늬, 여백, 테두리 밴드, 잘못된 텍스트, 잘못된 주제 또는 스타일 불일치가 있는지 확인합니다. 가장 좋은 테이크를 선택하여 parts/partNN/images/sceneNN.jpg로 변환합니다.
  • 잘못된 이미지만 gflow(무료)로 다시 생성하고 사용자에게 어떤 이미지와 이유를 알려줍니다.

대체 (gflow MCP):

  1. gflow_generate_image를 다음 매개변수로 실행: prompt "<style>. Scene: <image>.", aspect "16:9", model nano2, project <flow_project_id>.
  2. 새 비디오의 첫 번째 이미지의 경우 project를 생략하고 project_name을 전달합니다. 그런 다음 project.py decide <p> flow_project_id <id>를 실행합니다.
  3. 파일을 ~/Downloads/gflow-cli/images/<date>/<media>_1.jpg에서 parts/partNN/images/sceneNN.jpg로 복사합니다.

연락처 시트: ffmpeg -pattern_type glob -i 'images/scene*.jpg' -vf "scale=344:192,tile=5x3" -frames:v 1 contact.jpg

C. 패턴 장면 애니메이션 (Flow 웹사이트, 크레딧 소모)

gflow의 i2v는 이 계정에서 거부됩니다: Flow가 "agent-only composer"를 제공합니다(gflow 이슈 #799). 거부는 비용이 들지 않습니다. 대신 웹사이트를 사용하세요. Flow의 레이아웃은 2026년 11월에 변경되었습니다: 더 이상 에이전트 채팅이나 승인 단계가 없습니다.

사용자가 직접 클립을 만들고 싶어하는 경우 동일한 [m.ss-m.ss] 프롬프트 형식으로 parts/partNN/video_prompts.txt를 작성하세요. 애니메이션 처리할 각 장면에 대해 "Animate this exact image..." 텍스트와 장면의 motion을 사용하고, 각 장면과 함께 제공되는 sceneNN.jpg를 나열하세요.

  1. gflow_get_credits로 크레딧을 확인합니다. 비용이 들지 않습니다.
  2. scripts/launch_flow_chrome.sh "https://flow.google.com/project/<id>"를 실행합니다.
  3. ~/.local/share/uv/tools/gflow-cli/bin/python scripts/flow_animate.py --project <id> --part parts/partNN --upload --prefix <short>_pN_ 1 2 3 5 8을 실행합니다.
    • --upload는 장면 이미지를 Flow 프로젝트에 업로드합니다. 사용자의 확장 프로그램으로 이미지를 만든 경우 필요합니다.
    • 컴포저를 Video → Frames → x1로 전환하여 클립이 정확한 이미지에서 시작되도록 합니다. Omni 1.2 Flash, 720p, 8초, 클립당 24크레딧입니다.
    • 각 시작 프레임을 선택하고 모션 프롬프트를 입력하고 제출한 후 기다립니다.
    • 컴포저가 Image/Nano Banana 상태일 때 절대 제출하지 마세요. 비디오가 아닌 이미지 2개를 생성합니다. 무료이지만 애니메이션은 생성되지 않습니다.
  4. ~/.local/share/uv/tools/gflow-cli/bin/python scripts/flow_download.py --project <id> --part parts/partNN 1 2 3 5 8을 실행합니다.
    • 가장 최근 비디오(원본 크기)를 다운로드하고 첫 번째 프레임을 장면 이미지와 일치시켜 각각 clips/sceneNN.mp4로 저장합니다.
    • 올바른 장면의 경우 일치 거리는 약 4, 다른 장면의 경우 30 이상이어야 합니다.
  5. 각 클립의 프레임을 확인합니다: 동일한 태피스트리 모양, 텍스트 없음.
  6. CDP Browser.close로 CDP Chrome 창을 닫습니다. gflow MCP 호출은 프로필을 보유하는 동안 실패합니다.
  7. 크레딧을 다시 확인합니다. 감소량은 정확히 24 × 클립 수여야 합니다.

D. 타이밍 및 어셈블리

  1. python3 scripts/timing.py parts/partNN: 음성 해설의 문단 일시 정지에 장면 경계를 맞춥니다. 인쇄된 지속 시간을 확인합니다. 5초 미만 또는 11초 초과는 잘못된 스냅이므로 timing.json에서 수동으로 수정하세요.
  2. python3 scripts/assemble.py parts/partNN --draft는 검토용 복사본을 만듭니다. --draft 없이 실행하면 최종 렌더링을 만듭니다.
  3. 보내기 전에 프레임을 점검합니다.

E. YouTube 제목

60자 미만으로 유지하고, 후크를 먼저 배치하고 연도를 포함하세요. 예: "The Day the Viking Age Began (793 AD)". 35개의 옵션과 23단어의 텍스트가 포함된 썸네일 아이디어를 제공하세요.

환경 참고 사항 / 주의 사항

  • gflow MCP: ~/.local/bin/gflow-clean을 통해 등록됨(scripts/gflow-clean에 복사본). 래퍼는 VS Code 스냅 GTK/GIO 환경 변수를 제거합니다. 이것 없으면 Chrome이 시작 시 충돌하고 gflow는 이를 "Profile locked"으로 잘못 보고합니다.
  • 계정: gflow 프로필은 sajeel135입니다. 이미지 생성은 무료이고, 비디오는 크레딧이 필요합니다.
  • Chrome은 반드시 --password-store=basic을 사용해야 함: gflow 프로필에서 열리는 모든 Chrome은 --password-store=basic이 필요하며, 이는 launch_flow_chrome.sh에서 설정합니다. 이것 없이 Chrome은 시스템 키링으로 쿠키를 다시 암호화합니다. gflow가 이를 읽을 수 없어 flow.google.com/about(종료 코드 31)으로 이동하고 사용자가 다시 로그인해야 합니다.
    • Flow가 /about을 표시하지만 Google에 로그인되어 있는 경우, CDP 창을 열고 "Create with Google Flow"를 누르고 사용자가 로그인을 완료하도록 한 다음 CDP Browser.close로 깨끗이 닫습니다.
  • 오래된 잠금 파일: ~/.local/share/gflow-cli/profile_sajeel135/에서 오래된 Singleton* 잠금 파일을 제거하되, 해당 프로필을 사용하는 Chrome이 없을 때만 제거합니다(launch_flow_chrome.sh가 이 작업을 수행함).
  • 프로세스 중지: pkill -f <name>을 자신의 명령줄에 해당 이름이 포함된 셸에서 실행하지 마십시오. 자체적으로 종료됩니다. 대신 PID로 종료하세요.
  • 긴 렌더링: 최종 파트 렌더링은 몇 분이 소요됩니다. 도구 호출이 시간 초과될 수 있으면 백그라운드에서 긴 렌더링을 실행하세요.

관련 스킬