GITHUB 레포 딥다이브 · 2026-08-03 · S1DASHU/ANIMATED-VOICEOVER · 코드가 아니라 "규율"로 만든 AI 애니메이션 해설 영상

animated-voiceover 딥다이브
여러 AI 클립을 한 편의 영화처럼 잇는 제작 파이프라인

s1dashu/animated-voiceover는 놀랍게도 코드가 한 줄도 없는 저장소다. package.json도, 파이썬 파일도, Dockerfile도 없다. 대신 마크다운 명령서 묶음 — 즉 AI 코딩 에이전트(Codex 등)가 읽어들이는 에이전트 스킬(Agent Skill)이다. 실제 영상 생성은 외부 LibTV CLI → Doubao Seedance 2.0 모델에 위임하고, 이 레포가 파는 것은 "어떻게 하면 지식 해설 애니메이션을 일관되게 만들 수 있나"라는 방법론 그 자체다.

AI 영상 생성의 최대 난제는 일관성이다. 15초짜리 클립 20개를 따로따로 만들면 주인공 얼굴이 매 클립 달라지고, 목소리가 바뀌고, 그림체가 튄다. animated-voiceover는 대본 → 캐릭터 참조 → 장면별 프롬프트 → 음색 고정 → 병렬 생성 → 조립7단계 사람-확인 워크플로로 이 셋(캐릭터 신원·음색·화풍)을 강제로 붙잡는다. 배울 것은 코드가 아니라 프롬프트 규율과 멀티모달 참조 설계다.

(저장소 s1dashu/animated-voiceover · 라이선스 MIT(제3자 문서 제외) · 형식 Agent Skill(마크다운+YAML) · 영상 모델 Doubao Seedance 2.0(VIP star-video2) · 실행 LibTV CLI · 오디오 FFmpeg · 파일 35개 · 코드 0줄 · ★500 · 저자 s1dashu · 생성 2026-07-31 · TrendShift Daily #11)
목차
  1. 한 줄 정체
  2. 왜 주목받는가 — "일관성"이라는 각도
  3. 기술 스택 전체 지도
  4. 아키텍처 심화 — 7단계 파이프라인과 일관성 3축
  5. 디렉토리 구조 해부
  6. 학습 포인트 — 기술별 배울 것
  7. 시스템 / 실행 요구사항
  8. 직접 해볼 수 있는 실습 과제
  9. 관련 기술 심화 로드맵 (주차별)
  10. 핵심 키워드 사전
  11. 참고 링크

1한 줄 정체

이 프로젝트가 정확히 무엇인지 한 문장으로

animated-voiceover는 "AI에게 지식 해설 애니메이션 영상을 만들게 시킬 때, 대본 쓰기 → 캐릭터 참조 이미지 → 장면별 영상 프롬프트 → 음색 고정 → 병렬 생성 → 조립까지의 순서와 규칙을 못 박아, 따로따로 생성된 클립들이 한 편의 영화처럼 일관돼 보이게 만드는 프롬프트 워크플로 스킬"이다. 한마디로 AI 영상 제작의 "제작 파이프라인 규율"이다. 영상을 그리는 모델이 아니라, 모델에게 영상을 그리게 시키는 방식을 방법론으로 정한 것이다.

한 장의 비유

"각본가 · 캐릭터 디자이너 · 성우 · 콘티 작가가 순서대로 붙는 애니메이션 스튜디오"

제대로 된 애니메이션 스튜디오에서는 각본가가 먼저 대본을 쓰고, 캐릭터 디자이너가 주인공의 앞모습·뒷모습 설정화(캐릭터 시트)를 그려 "이 인물은 이렇게 생겼다"를 고정한다. 그다음 성우가 목소리를 녹음해 톤을 통일하고, 콘티 작가가 장면마다 카메라와 동작을 짠다. 핵심은 순서와 설정 고정이다 — 캐릭터 시트가 있어야 매 컷 같은 얼굴이 나오고, 성우가 한 명이어야 목소리가 안 튄다.

animated-voiceover가 정확히 이 구조다. AI에게 ①대본을 15초 단위로 쪼개게 하고, ②주인공의 앞·뒤 모습을 흰 배경에 그린 참조 이미지를 먼저 만들어 신원을 고정하고, ③첫 클립의 목소리를 뽑아 "음색 앵커"로 박아 이후 모든 클립이 같은 목소리를 쓰게 하고, ④장면별 프롬프트를 정해진 5부 구조로 쓴다. 그래야 20개 클립이 한 사람이 만든 한 편처럼 이어진다.

용어
에이전트 스킬 (Agent Skill)
SKILL.md라는 마크다운 파일에 YAML 머리말(언제 이 스킬을 켤지 설명)과 실행 절차를 적어 둔 것. Claude Code·Codex 같은 AI 코딩 에이전트가 이 파일을 읽어 "이럴 땐 이 순서로 일해라"를 따른다. 즉 프로그램이 아니라 "AI에게 주는 작업 매뉴얼"이다. animated-voiceover는 이 매뉴얼 한 벌 + 스타일 가이드 + 예시 자산으로 이뤄져 있다.
용어
Doubao Seedance 2.0 · LibTV CLI
Seedance 2.0은 바이트댄스(ByteDance) 두바오(Doubao)의 영상 생성 모델로, 특이하게 영상과 오디오를 한 번에 같이 생성한다(joint audio+video). 참조 이미지·영상·오디오를 함께 넣어 주인공·동작·화풍·음색을 잡을 수 있다. LibTV CLI(libtv)는 이 모델을 실제로 호출하는 명령줄 도구다. animated-voiceover는 이 둘을 "실행 엔진"으로 삼고, 자기는 그 위에서 무엇을 어떤 순서로 시킬지만 지휘한다.

사용자가 "이 주제로 해설 영상 만들어 줘"라고 하면 이 스킬 규율 아래서 벌어지는 일을 압축하면 이렇다:

사용자 "이 주제로 지식 해설 애니메이션을 만들어 줘" │ ▼ ① 대본(旁白) 주제·대상·길이 확정 → 사실 검증 → 전체 대본 → 15초 단위로 의미 분할(한 조각 ≈ 60자) → 사용자 승인 │ ▼ ② 캐릭터 참조 이미지 대본 전체 읽고 "신원 고정이 필요한 핵심 인물" 수 결정 → 인물당 1장: 앞모습(좌)+뒷모습(우)을 순백 배경에 │ ▼ ③ 장면별 영상 프롬프트 조각마다 5부 구조 프롬프트 작성(片段01.md, 片段02.md…) │ ▼ ④ 첫 클립만 생성 음색 경로 선택(내장/기존/신규) → 片段01만 먼저 생성 → 승인 │ ▼ ⑤ 음색 앵커 고정 승인된 첫 클립에서 FFmpeg로 순수 오디오 추출 → 포맷 검증 후 오디오 노드로 업로드(이후 전 클립이 공유) │ ▼ ⑥ 나머지 병렬 생성 片段02~N을 같은 음색 앵커에 연결해 동시 생성 │ ▼ ⑦ 확인·조립 각 작업이 성공 종료+리소스 URL 있는지 검증 → video/ 폴더로 내려받아 순서대로 이어붙임 → (표지)

여기서 핵심은 ②의 앞·뒤 캐릭터 시트⑤의 음색 앵커다. 이 둘이 "매 클립 얼굴이 바뀌는" 문제와 "매 클립 목소리가 튀는" 문제를 각각 못 박는 장치다. animated-voiceover를 단순 "AI로 영상 만들기 팁"과 갈라놓는 지점이 바로 여기다.

2왜 주목받는가 — "일관성"이라는 각도

일주일도 안 돼 별 500개를 모은 신생 레포가 상위에 오른 이유

첫째, AI 영상 생성의 진짜 고통점인 "일관성"을 정면으로 때린다. 누구나 Sora·Seedance·Kling 같은 걸로 짧은 클립은 뽑아 봤지만, 정작 여러 클립을 이어 "한 편의 영상"을 만들려 하면 주인공 외모가 매번 달라지고, 성우 목소리가 클립마다 바뀌고, 화풍이 튀어서 도저히 못 쓴다. animated-voiceover는 이 "따로 만든 조각을 하나로 잇는 법"을 체계적인 절차로 내놓았다.

둘째, 코드가 아니라 "방법론을 레포로" 냈다. 이 저장소에는 실행 파일이 없다 — 마크다운 가이드와 스타일 문서, 예시 자산뿐이다. 그런데도 별이 폭발한 이유는, 사람들이 원하는 게 "또 하나의 영상 툴"이 아니라 "기존 툴로 좋은 결과를 뽑는 노하우"였기 때문이다. Skill/스킬이라는 새 포맷이 뜨는 흐름과도 맞물렸다(TrendShift 데일리 2위 토픽이 AI skills).

비유

좋은 카메라를 사는 것과, 좋은 촬영 매뉴얼을 얻는 것의 차이다. 대부분의 AI 영상 프로젝트는 "더 좋은 카메라(모델)"를 판다. animated-voiceover는 이미 있는 카메라로 좋은 영화를 찍는 촬영·편집 매뉴얼을 준다. 카메라가 아무리 좋아도 "주인공 설정화를 먼저 그려라, 목소리는 한 번 녹음해 돌려 써라, 컷마다 시작-동작-끝을 적어라"를 모르면 조각들이 따로 논다. 이 매뉴얼의 가치는 카메라값과 무관하게 크다.

셋째, 정직한 실전 검증 노트가 신뢰를 준다. 이 레포는 막연한 조언이 아니라 날짜가 박힌 실패 기록을 담았다. 예를 들어 "2026-08-01 Seedance 2.0 VIP에서 순수 오디오만 넣는 audio2video 작업이 '참조 음성은 단독 사용 불가'로 실패 → 캐릭터 이미지+오디오를 함께 넣는 mixed2video로는 성공"이라고 적어 두고, 그래서 규칙을 "단일 오디오라도 반드시 mixed2video"로 못 박는다. 직접 굴려 보고 얻은 교훈이라는 게 문서에서 드러난다.

넷째, 재사용 가능한 구조물이 여럿이다. 6종 내장 화풍 가이드(시네마틱 3D, 클레이 스톱모션, 크레용 라인, 도파민 큐트 3D 등), 4종 내장 음색 앵커, 표준화된 프롬프트 5부 양식 — 이것들은 이 레포를 안 써도 자기 작업에 그대로 가져다 쓸 수 있는 부품이다.

이 레포의 진짜 강점
"일관성"을 감이 아니라 절차로 강제한다

대부분의 "AI 영상 잘 만드는 법"은 프롬프트 예시 몇 개에 그친다. animated-voiceover는 일관성을 강제되는 순서로 바꿨다 — 캐릭터 신원은 앞·뒤 흰배경 참조 이미지로, 목소리는 FFmpeg로 추출해 고정한 음색 앵커로, 화풍은 고른 스타일 가이드 하나를 전 클립에 재사용해서 붙잡는다. "예쁘게 뽑는 팁"이 아니라 "20개 클립이 안 튀게 만드는 공정"이라는 게 이 프로젝트의 심장이다.

오해 주의
이건 "영상 생성 소프트웨어"가 아니다 · 외부 유료 도구가 필요하다

이름과 인기 때문에 "설치하면 영상이 나오는 앱"으로 착각하기 쉽지만, animated-voiceover는 코드 0줄의 방법론 문서 묶음이다. 실제 영상은 LibTV CLI를 통해 Doubao Seedance 2.0을 호출해 만들며, 이는 계정·크레딧이 필요한 외부 서비스다(중국 두바오 생태계). 또 문서 상당수가 중국어이고, 검증된 모델은 Seedance 2.0 Pro(=LibTV의 VIP star-video2)로 특정 버전에 묶여 있다(2.5 Pro는 미검증). "이 스킬 = 프롬프트/절차, 실제 렌더링 = 남의 엔진"이라는 분업을 이해하고 봐야 한다.

3기술 스택 전체 지도

빌드 도구가 없다 — 마크다운·YAML로 "지휘"하고, 렌더링은 외부 엔진에 위임한다

animated-voiceover에는 컴파일러도, 런타임도, 의존성 매니페스트(package.json·requirements.txt 등)도 없다. GitHub은 이 레포의 언어를 null로 표시한다. 이 프로젝트의 "스택"은 지휘용 문서 계층(스킬)과 외부 실행 계층(LibTV+Seedance)으로 나뉜다. 아래 표가 전체 지도다.

계층 / 구성요소무엇역할
Agent Skill 포맷SKILL.md(YAML 머리말+절차)이 레포의 두뇌. "언제 켤지 + 어떤 순서로 일할지"를 AI 에이전트에게 지시. Codex 명시 호환
영상 모델Doubao Seedance 2.0 계열실제 애니메이션 생성. 영상+오디오 동시 생성 + 멀티모달 참조. 권장 Pro = LibTV VIP star-video2. 2.5 Pro(30초)는 미검증
실행 CLI(유일 런타임)LibTV CLI (libtv)모델을 실제로 호출하는 유일한 공식 경로. libtv model search·node -s "model=..."·download·플래그 -p·--run·--count
이미지 모델(별칭)GPT-Image-2 · Nano Banana Pro · Midjourney캐릭터 참조 이미지 생성. LibTV 별칭으로 매핑(Lib Image·General image Pro·悠船)
오디오 도구FFmpeg(ffmpeg/ffprobe)승인된 첫 클립에서 순수 음색을 추출해 앵커로 고정. macOS afconvert 대안
에이전트 매니페스트agents/openai.yamlCodex/OpenAI용 스킬 등록(표시명·기본 프롬프트). 유일한 구조적 설정 파일
데이터/자산 포맷Markdown · YAML · WAV · PNG/WEBP가이드=MD, 매니페스트=YAML, 음색 앵커=WAV(48kHz/16bit/스테레오), 미리보기=WEBP
용어
멀티모달 참조 (multimodal reference)
텍스트 프롬프트뿐 아니라 이미지·영상·오디오를 함께 입력으로 넣어 결과를 통제하는 것. Seedance 2.0의 핵심 기능이다. "참조 이미지1의 인물을 주인공으로, 참조 오디오1의 음색으로 말하게" 같은 지시가 가능해, animated-voiceover가 캐릭터 신원·음색을 클립마다 재현할 수 있는 근거가 된다.
용어
mixed2video vs audio2video
Seedance 호출 모드. audio2video는 오디오만으로 영상 생성, mixed2video이미지+오디오를 섞어 생성. 레포의 실전 노트(2026-08-01)에 따르면 순수 오디오 단독 작업은 "참조 음성 단독 사용 불가" 오류로 실패했고, 캐릭터 이미지+오디오를 함께 넣은 mixed2video는 성공했다. 그래서 규칙은 "단일 오디오라도 무조건 mixed2video"로 못 박혀 있다.

주목할 점은 모든 런타임 파라미터를 파일이 아니라 실시간 CLI 플래그로 넘긴다는 것이다. duration=15·resolution=720p·enableSound·modeType=mixed2video·-p <projectUuid> 등은 프롬프트나 설정 파일에 굳혀 두지 않고, 항상 LibTV의 살아 있는 스키마에서 새로 읽어 넘긴다. 외부 서비스의 스펙이 바뀌어도 문서를 안 고쳐도 되게 한 설계다.

4아키텍처 심화 — 7단계 파이프라인과 일관성 3축

이 레포의 진짜 알맹이. 파이프라인 한 축, 일관성 세 축으로 나눠 본다

축 1 — 7단계 사람-확인 워크플로 (SKILL.md)

SKILL.md매 단계 사람이 승인해야 다음으로 넘어가는 7단계를 정의한다. 각 단계는 반드시 대응하는 참조 가이드를 완전히 읽은 뒤 행동하게 강제된다(작업↔가이드 라우팅 표).

단계하는 일반드시 읽는 가이드
① 대본(旁白)주제·대상·길이 확정 → 사실검증 → 대본 → 15초 조각 분할 → 승인 → 旁白.md 저장narration-script-guide.md
② 캐릭터 참조핵심 인물 수 결정 → 인물당 앞+뒤 흰배경 이미지 1장(장면 이미지·스타일 이미지는 생성 안 함)character-reference-image-guide.md + 화풍
③ 장면 프롬프트조각별 5부 구조 Seedance 프롬프트 → 片段01.md, 片段02.mdvideo-prompt-guide.md + Seedance 공식 가이드
④ 첫 클립만음색 경로 선택(내장/기존/신규) → 片段01만 생성 → 승인reference-asset-library.md
⑤ 음색 고정신규면 FFmpeg로 첫 클립 오디오 추출·검증·업로드 → 앵커 확정voice-reference-guide.md
⑥ 병렬 생성片段02~N을 같은 음색 앵커에 연결해 동시 제출
⑦ 확인·조립각 작업 성공 종료+리소스 URL 검증 → video/로 내려받아 순서대로 이어붙임(선택) video-cover-image-guide.md

검증된 케이던스(박자)가 구체적이다: 1~5분 영상은 15초 클립 여러 개로 쪼개고, 각 클립의 대본은 중국어 약 60자(목표 59~61, 한계 58~62), 보통 5개 샷(shot)으로 구성한다. 1분 ≈ 4조각, 2분 ≈ 8조각, 5분 ≈ 20조각. 이 숫자들은 감이 아니라 모델이 안정적으로 소화하는 검증된 분량이다.

축 2 — 일관성① 캐릭터 신원: 앞+뒤 흰배경 참조 이미지

첫 번째 일관성 문제는 "매 클립 주인공 얼굴이 달라진다"이다. animated-voiceover의 해법은 인물당 참조 이미지 딱 1장인데, 그 안에 같은 인물의 앞모습(좌)과 뒷모습(우)을 순백 배경에 나란히 담는다. 이 한 장이 이후 모든 장면 프롬프트에서 "참조 이미지1의 인물"로 호출돼 신원을 붙잡는다.

캐릭터 참조 이미지 (인물 1명당 1장) ┌────────────────────┬────────────────────┐ │ │ │ │ [앞모습] │ [뒷모습] │ │ front-view │ back-view │ │ │ │ │ 순백 배경 (pure white background) │ └────────────────────┴────────────────────┘ ↓ 이후 모든 片段 프롬프트에서 재호출 "참조 이미지1의 청년을, 2~3개 안정적 특징으로 '청년 주인공'으로 정의"

영리한 절제가 있다. 인물 수는 1~3명으로 고정하지 않고 내용이 요구하는 만큼만 정한다(불필요한 인물은 안 만든다). 또 애니메이션에서는 장면 이미지나 스타일 참조 이미지를 따로 생성하지 않는다 — 장면과 화풍은 텍스트 프롬프트가 감당하고, 이미지 참조는 오직 "인물 신원"에만 쓴다. 참조가 많을수록 모델이 헷갈리므로, 꼭 필요한 신원만 이미지로 못 박는 것이다.

축 3 — 일관성② 음색: FFmpeg 추출로 만든 "음색 앵커"

두 번째 문제는 "매 클립 목소리가 튄다"이다. 해법은 첫 클립에서 순수 오디오를 뽑아 앵커로 고정하는 것이다. 신규 음색 경로에서는 승인된 片段01에서 FFmpeg로 오디오만 추출한다(실제 명령):

# 승인된 첫 클립에서 순수 음색 추출 (영상 버리고 오디오만)
ffmpeg -hide_banner -n -i "./片段1.mp4" \
  -map 0:a:0 -vn -c:a pcm_s16le -ar 48000 -ac 2 \
  "./片段1-음색참조.wav"

# ffprobe로 포맷 검증 — 정확히 이 스펙이어야 함
#   codec_name = pcm_s16le / sample_rate = 48000 / channels = 2 / bits = 16

포맷을 WAV / pcm_s16le / 48kHz / 16bit / 스테레오로 못 박은 이유는 실전 검증이다 — 문서에는 "M4A 업로드는 Seedance가 거부했다"는 기록이 있다. 그래서 반드시 이 규격의 WAV로 변환해 오디오 노드로 업로드하고, 이후 片段02~N이 모두 같은 음색 ID를 연결한다. 각 클립의 대사 텍스트는 자기 프롬프트에서 오지만, 목소리(음색)는 전부 이 하나의 앵커를 공유한다.

용어
음색 앵커 (voice anchor) · pcm_s16le
음색 앵커는 "이 목소리로 통일해라"의 기준이 되는 참조 오디오. pcm_s16le는 압축하지 않은 16비트 리틀엔디언 PCM 오디오 코덱(WAV의 표준 무압축 형식)이다. MP3·M4A 같은 손실 압축이 아니라 무압축 원본이라 모델이 음색을 정확히 읽는다. 48kHz(초당 48000 샘플)·스테레오(2채널)까지 규격을 고정해, 업로드 거부나 음색 왜곡을 막는다.
설계에서 배우는 것
"생성물을 다시 입력으로" — 자기 출력을 재료로 되먹인다

음색 앵커의 묘미는 ①에서 만든 결과(첫 클립)를 ⑤에서 다시 입력 재료로 쓴다는 점이다. 새 성우를 섭외하는 게 아니라, "AI가 첫 클립에서 낸 목소리"를 추출해 그걸 나머지 클립의 기준으로 되먹인다. 사람이 미리 목소리를 정하지 못하는 생성 AI의 특성을 역이용한 부트스트랩(self-bootstrapping) 패턴이다. 첫 결과를 승인받은 뒤 그걸 기준으로 확장하는 이 구조는, 이미지·문체 등 다른 일관성 문제에도 그대로 응용할 수 있다.

축 4 — 일관성③ 화풍 + 프롬프트 5부 구조

세 번째 문제는 "그림체가 튄다"이다. 해법은 6종 화풍 가이드 중 하나를 골라 전 클립에 재사용하는 것이다. 각 화풍 가이드(시네마틱 3D·클레이 스톱모션·크레용 라인·도파민 큐트 3D·멜랑콜리 블루 라인·소프트 색연필)는 매체·재질·색·모션 언어를 고정하되, 고정 샷 템플릿으로 베끼는 것은 금지한다(장면은 다양해야 하므로).

그리고 모든 장면 프롬프트는 정해진 5부 구조로 쓴다(video-prompt-guide.md). 이 양식이 일관성을 강제하는 뼈대다:

장면 프롬프트 5부 구조 (Seedance) ───────────────────────────────────────────── 1. 오디오 역할 "오디오1은 {확정된 음색 특징} 참조용으로만" 2. 참조 이미지 "참조 이미지1의 {2~3개 안정 특징} 인물을 '주인공'으로 정의" 3. 내레이션 "화외 내레이션: 중국어, 오디오1 음색, {말속도}로 {이 조각의 정확한 대본}을 원래 순서대로 완전·정확히" 4. 전역 프레임 "모든 샷은 {고른 화풍의 안정 시각언어}. 이 조각의 장면은 {장소·시대·재질·색·조명·렌더링 방식}" 5. 샷들(순서대로) "샷1: [경별/기위 + 주체 + 장면 + 시작상태 → 동작 → 끝상태 + 운카메라] 샷2: …" (보통 5샷)

이 구조의 원칙은 "구상적 사건 우선(具象事件優先)"이다 — 떠다니는 상징·에너지 흐름·빛나는 사슬 같은 추상 대신, 각 샷은 시작상태→동작→끝상태를 가진 구체적 사건이어야 한다. 카메라 이동도 시작 위치·방향·기준·끝 프레이밍을 명시한다. 내레이션 텍스트는 프롬프트 안에 {}로 정확히 한 번만 들어간다. 이 규율이 "예쁘지만 무슨 장면인지 모를" 결과를 막는다.

5디렉토리 구조 해부

파일 35개. 코드가 없으니 문서 하나하나가 곧 "기능"이다
animated-voiceover/ ├─ README.md / README_CN.md 저장소 소개(영/중) · 태그라인 · 설치·사용 ├─ SKILL.md ★ 마스터 워크플로 = 두뇌 (7단계 + 작업↔가이드 라우팅 표) ├─ LICENSE MIT (단, references/공식 Seedance 가이드는 제외) │ ├─ agents/ │ └─ openai.yaml Codex 스킬 등록(표시명·기본 프롬프트) — 유일한 구조적 설정 │ ├─ styles/ ★ 6종 화풍 가이드 (전 클립에 하나 재사용) │ ├─ cinematic-3d-animation.md 시네마틱 3D │ ├─ clay-stop-motion.md 클레이 스톱모션 │ ├─ clean-line-crayon-animation.md 깔끔한 라인 크레용 │ ├─ dopamine-cute-3d-animation.md 도파민 큐트 3D │ ├─ melancholic-blue-simple-line-...md 멜랑콜리 블루 라인 │ └─ soft-colored-pencil-cute-...md 소프트 색연필 큐트 │ ├─ references/ ★ "어떻게" 지식 베이스 (핵심 노하우) │ ├─ narration-script-guide.md 대본 규칙(15초/60자/5샷 케이던스) 148줄 │ ├─ character-reference-image-guide.md 앞+뒤 흰배경 캐릭터 시트 48줄 │ ├─ video-prompt-guide.md ★ 5부 프롬프트 구조 301줄(최대 원본 문서) │ ├─ voice-reference-guide.md FFmpeg 음색 추출·mixed2video 노트 117줄 │ ├─ video-cover-image-guide.md 표지 이미지 118줄 │ ├─ community-directing-notes.md 커뮤니티 연출 노트 32줄 │ ├─ reference-asset-library.md 내장 자산 카탈로그 35줄 │ └─ official-seedance-2.0-prompt-guide.md 두바오 공식 가이드 1,571줄(제3자, MIT 제외) │ └─ assets/ ★ 예시·미리보기·내장 자산 ├─ repository-covers/ 커버 PNG ├─ examples/ 데모 WEBP 2종(철학·심리) ├─ style-previews/ 화풍 썸네일 WEBP 6종 └─ reference-library/ ├─ voices/ 내장 음색 앵커 WAV 4종 (각 SHA-256 기록) └─ image-styles/ 레거시 스타일 참조 PNG 2종(폐기 예정)

구조가 알려주는 힌트 셋. 첫째, 무게중심이 references/에 있다 — 특히 video-prompt-guide.md(301줄)와 제3자 official-seedance-2.0-prompt-guide.md(1,571줄)가 압도적으로 크다. 이 레포의 가치는 "얇은 지휘서(SKILL.md) + 두꺼운 노하우(references)"에 실려 있다. 둘째, styles/(화풍)·references/(방법)·assets/(자산)로 관심사가 폴더로 갈려 있어, 화풍만 추가하거나 음색만 교체하기 쉽다. 셋째, image-styles/가 "레거시·폐기 예정"으로 남아 있다 — 애니메이션은 이미지 참조를 인물에만 쓰기로 바뀐 흔적이다.

라이선스 함정
MIT지만 "공식 Seedance 가이드"는 제외된다

이 레포는 MIT 라이선스(© 2026 s1dashu)지만, 중요한 예외가 있다. references/official-seedance-2.0-prompt-guide.md(1,571줄)는 바이트댄스/두바오의 제3자 문서라 MIT에서 빠져 있고 원 소유자의 권리가 유지된다. 이 레포에서 가장 두꺼운 프롬프트 지식이 이 파일에 있는데, 그대로 재배포·상업 이용할 때는 MIT가 적용되지 않는다는 점을 유의해야 한다. 나머지 오리지널 가이드(video-prompt-guide.md 등)는 MIT 적용 대상이다.

6학습 포인트 — 기술별 배울 것

코드가 없어도 뽑아낼 설계 원칙과 실전 기술은 밀도가 높다

① 생성 AI 일관성 3축 (가장 값진 배움)

여러 AI 클립을 한 편처럼 잇는 일관성 = 신원·음색·화풍이라는 분해와, 각각을 (참조 이미지 / 음색 앵커 / 재사용 스타일 가이드)로 붙잡는 법. 이 사고틀은 Seedance뿐 아니라 어떤 영상·이미지 생성 파이프라인에도 그대로 옮겨진다. "무엇이 튀는가 → 그걸 고정하는 앵커는 무엇인가"를 묻는 습관을 배운다.

② 멀티모달 참조 프롬프트 엔지니어링

텍스트만이 아니라 이미지·영상·오디오를 함께 넣어 주체·동작·화풍·음색을 잡는 실전 기법. 특히 5부 프롬프트 구조(오디오 역할 → 이미지 인물 정의 → 내레이션 → 전역 프레임 → 순서 샷)는 "참조를 언제 어디서 호출하는지"의 좋은 표본이다. 참조를 남발하지 않고 "인물 신원에만" 쓰는 절제도 함께 배운다.

③ FFmpeg 오디오 추출·검증

ffmpeg -map 0:a:0 -vn -c:a pcm_s16le -ar 48000 -ac 2로 영상에서 순수 오디오를 뽑고, ffprobe로 코덱·샘플레이트·채널·비트를 검증하는 실무. "왜 M4A는 거부되고 WAV/pcm_s16le는 되는가", "왜 48kHz 스테레오로 고정하는가" 같은 포맷 감각은 오디오를 다루는 어떤 파이프라인에서도 쓸모가 크다.

④ "생성물을 입력으로 되먹이는" 부트스트랩

사람이 미리 정할 수 없는 값(AI 목소리)을, 첫 결과를 승인받은 뒤 그걸 기준으로 고정해 확장하는 패턴. 음색 앵커가 대표 사례다. 이 "1개 먼저 만들고 승인 → 그걸 앵커로 나머지 병렬 확장" 구조는 비용·품질을 동시에 잡는 생성 워크플로의 핵심 설계다.

⑤ Agent Skill 포맷 (스킬을 레포로)

SKILL.md의 YAML 머리말(언제 켤지)+절차 본문, 작업↔가이드 라우팅 표, 참조 문서 분리 구조. "코드 없이 방법론을 배포 가능한 산출물로" 만드는 법을 배운다. Claude Code·Codex 스킬을 직접 쓸 때 어떻게 문서를 조직해야 에이전트가 잘 따르는지의 실전 예다.

⑥ 정직한 실전 노트로 신뢰 쌓기

"2026-08-01 audio2video 실패 → mixed2video 성공", "M4A 거부됨" 같은 날짜 박힌 실패 기록을 문서에 남기는 습관. 매끈한 성공담보다 이런 구체적 삽질 기록이 오히려 신뢰를 만든다. 자기 프로젝트를 문서화할 때 두고두고 참고할 태도다.

실습 아이디어(가볍게)
Seedance가 없어도 "일관성 3축"만 흉내 내 보기

이 레포의 진짜 가치는 특정 모델이 아니라 일관성 규율이다. Seedance 접근이 없다면, 자기가 쓰는 아무 이미지/영상 생성 툴에서 "① 주인공 앞·뒤 흰배경 시트를 먼저 1장 만든다 → ② 그 시트를 참조로 여러 장면을 생성한다 → ③ 얼마나 얼굴이 유지되는지 본다"를 해 보라. 참조 이미지가 있을 때와 없을 때 신원 유지가 얼마나 차이 나는지 즉시 체감된다.

7시스템 / 실행 요구사항

실제로 영상을 뽑아 보려면 무엇이 필요한가
항목필요한 것
호스트 에이전트스킬을 읽어 실행할 AI 코딩 에이전트 — Codex 명시 호환(SKILL.md/스킬 디렉토리를 읽는 에이전트면 적용 가능)
영상 생성 엔진LibTV CLI + Doubao Seedance 2.0 Pro(=VIP star-video2) 접근 계정·크레딧. 2.5 Pro는 미검증
이미지 생성LibTV 별칭을 통한 GPT-Image-2 / Nano Banana Pro / Midjourney 중 하나(캐릭터 참조용)
오디오 도구FFmpeg(ffmpeg·ffprobe). Windows winget install --id Gyan.FFmpeg / macOS brew install ffmpeg
언어가이드·프롬프트 상당수가 중국어. 기본 내레이션도 중국어 전제(다른 언어 적용은 프롬프트 수정 필요)
산출물 경로생성 문서(旁白.md·片段NN.md)와 클립(video/片段NN.mp4)이 작업 폴더에 평면으로 쌓임

8직접 해볼 수 있는 실습 과제

난이도별로. Seedance가 없어도 대부분 가능하게 구성했다
과제 1 난이도 ●○○○○

SKILL.md 읽고 "7단계 파이프라인" 지도 그리기

git clone --depth 1로 받아 SKILL.md와 작업↔가이드 라우팅 표를 읽는다. 대본→캐릭터→프롬프트→첫클립→음색고정→병렬생성→조립의 7단계를 한 장으로 그리고, 각 단계에서 "사람이 승인"하는 지점이 어디인지 표시해 보자. "왜 첫 클립만 먼저 만들까?"를 스스로 답하는 게 목표.

과제 2 난이도 ●●○○○

FFmpeg로 실제 음색 추출·검증 재현하기

아무 mp4(말하는 영상)를 구해 voice-reference-guide.md의 명령을 그대로 실행한다: ffmpeg -i in.mp4 -map 0:a:0 -vn -c:a pcm_s16le -ar 48000 -ac 2 out.wavffprobe out.wav로 codec_name/sample_rate/channels/bits가 규격과 맞는지 확인. M4A로도 뽑아 보고 "왜 레포가 WAV/pcm_s16le만 허용하는지" 체감하라.

과제 3 난이도 ●●●○○

5부 프롬프트 구조로 장면 프롬프트 써 보기

video-prompt-guide.md의 5부 양식(오디오 역할/참조 이미지/내레이션/전역 프레임/순서 샷)에 맞춰, 60자 내레이션 한 조각 분량의 장면 프롬프트를 직접 작성한다. 자기가 쓰는 이미지/영상 생성 툴에 넣어, "시작상태→동작→끝상태"를 명시한 샷과 대충 쓴 샷의 결과 차이를 비교하라.

과제 4 난이도 ●●●●○

캐릭터 신원 앵커 실험 (참조 있음 vs 없음)

이미지 생성 툴에서 "같은 인물의 앞+뒤 흰배경 시트"를 1장 만든 뒤, 그걸 참조로 서로 다른 장면 3개를 생성한다. 같은 프롬프트를 참조 이미지 없이도 3개 생성해, 두 세트의 얼굴 일관성을 나란히 비교하라. animated-voiceover가 왜 "인물당 참조 1장"을 규칙으로 못 박았는지 데이터로 확인하는 과제.

과제 5 난이도 ●●●●●

나만의 화풍 가이드 + 미니 파이프라인 만들기

styles/의 6종 가이드 형식(안정 시각언어 / 이미지 프롬프트 / 영상 프롬프트 3절)을 본떠 새 화풍 가이드 1종을 쓰고, 그 화풍으로 15초×2조각짜리 초미니 해설 영상을 실제로 만들어 이어붙여 본다. 대본 60자×2 → 캐릭터 시트 → 첫 클립 → 음색 앵커 고정 → 둘째 클립 → 조립까지 전 과정을 한 번 완주하는 게 목표.

9관련 기술 심화 로드맵 (주차별)

이 레포를 계기로 "AI 영상 파이프라인"을 공부한다면
주차주제구체적으로
1주생성 영상 모델의 지형Seedance·Sora·Kling·Veo 비교, 영상+오디오 동시 생성, 멀티모달 참조(image/video/audio)의 개념과 한계
2주일관성 3축 심화캐릭터 신원 고정(참조/IP-Adapter 계열 사고), 음색 앵커, 화풍 재사용. "무엇이 튀고 어떤 앵커로 잡나"를 케이스별로
3주영상 프롬프트 엔지니어링5부 구조, 구상적 사건 우선, 샷의 시작-동작-끝, 운카메라 서술. video-prompt-guide.md+공식 가이드 정독
4주오디오/미디어 파이프라인FFmpeg 오디오 추출·변환·검증, 코덱/샘플레이트/채널, 무압축 WAV vs 손실 압축, ffprobe로 자동 검증
5주(선택)Agent Skill로 워크플로 배포SKILL.md 규격, 작업↔가이드 라우팅, 사람-확인 게이트 설계, 스킬을 레포로 조직·공유하는 법

10핵심 키워드 사전

이 문서에 나온 개념 압축 정리
용어
에이전트 스킬 (Agent Skill)
SKILL.md(YAML 머리말+절차)로 AI 코딩 에이전트에게 "언제·어떤 순서로 일할지"를 주는 작업 매뉴얼. animated-voiceover는 코드 대신 이 스킬 한 벌로 이뤄져 있다.
용어
Seedance 2.0 / LibTV CLI
Seedance 2.0=바이트댄스 두바오의 영상+오디오 동시 생성 모델(권장 Pro=VIP star-video2). LibTV CLI=이를 실제 호출하는 유일한 공식 명령줄 도구.
용어
일관성 3축 (신원·음색·화풍)
여러 클립을 한 편처럼 잇는 세 축. 각각 (앞+뒤 흰배경 참조 이미지 / FFmpeg 음색 앵커 / 재사용 스타일 가이드)로 고정한다. 이 레포의 핵심 사고틀.
용어
음색 앵커 (voice anchor)
승인된 첫 클립에서 FFmpeg로 추출한 참조 오디오(WAV/pcm_s16le/48kHz/스테레오). 이후 전 클립이 이 하나를 공유해 목소리가 안 튀게 한다.
용어
mixed2video vs audio2video
Seedance 호출 모드. 순수 오디오만(audio2video)은 거부됐고, 이미지+오디오 혼합(mixed2video)은 성공. 규칙=단일 오디오라도 무조건 mixed2video.
용어
15초 / 60자 / 5샷 케이던스
검증된 분량 박자. 클립=15초, 대본=중국어 약 60자(58~62), 보통 5샷. 1분≈4조각, 5분≈20조각. 감이 아니라 모델이 안정적으로 소화하는 검증치.
용어
캐릭터 참조 이미지 (앞+뒤 흰배경)
인물당 1장에 같은 인물의 앞모습(좌)+뒷모습(우)을 순백 배경에. 이후 모든 프롬프트에서 "참조 이미지1의 인물"로 호출돼 신원을 고정. 장면·스타일 이미지는 따로 안 만든다.
용어
5부 프롬프트 구조
오디오 역할 → 참조 이미지 인물 정의 → 내레이션(언어·음색·정확한 텍스트) → 전역 프레임(화풍·장면) → 순서 샷. 모든 장면 프롬프트가 이 뼈대로 작성된다.
용어
구상적 사건 우선 (具象事件優先)
추상 상징·에너지 흐름·빛나는 사슬 대신, 각 샷을 시작상태→동작→끝상태의 구체적 사건으로. "예쁘지만 뭔지 모를" 결과를 막는 프롬프트 원칙.
용어
pcm_s16le / FFmpeg
pcm_s16le=16비트 무압축 PCM(WAV 표준). FFmpeg=영상에서 오디오 추출·변환, ffprobe=포맷 검증 도구. 음색 앵커를 정확한 규격으로 만드는 데 쓴다.

11참고 링크

더 파고들 때