Communitygithub.com

avatar-studio

단 한 장의 일러스트 초상화(만화나 그림 캐릭터)와 대본만으로, 캐릭터가 말하는 MP4 영상을 로컬 머신에서 완전히 생성합니다. 3D 헤드를 구축하거나 재사용하고, Kokoro로 로컬 음성을 합성하며, 깜빡임, 고개 흔들림, 끄덕임, 입 모양을 실제 오디오에 맞춰 구동하고, headless Chrome에서 결정론적으로 프레임을 렌더링하여 MP4와 함께 자막, 컴퓨터 생성 레이블, 제목, 이름 표시줄, 말하는 단어에 나타나는 포인트 사이드 패널, 엔드 카드를 출력합니다.

avatar-studio란 무엇인가요?

avatar-studio는 단일 일러스트 초상화(만화나 그림 캐릭터)와 대본을 입력으로 받아, 캐릭터가 말하는 완성된 MP4 비디오를 로컬에서 생성하는 AI 에이전트 스킬입니다. 이 스킬은 Claude Code, Cursor, Codex 등 AI 코딩 에이전트와 함께 사용되며, 사용자가 대화형 아바타 비디오, 애니메이션 프리젠터, 캐릭터 대본 낭독 클립, 소셜 미디어 또는 웹페이지용 설명 영상을 원할 때 유용합니다. `head`(초상화 → 3D 헤드), `audio`(Kokoro 음성 합성, 단어 타이밍, 프레임별 음량), `plan`(음량 기반 입 모양, 시드 기반 깜빡임 및 고개 흔들림, 강세 단어 끄덕임, 사이드 패널 응시, 시간 기반 레이아웃), `render`(headless Chrome에서 순수 함수로 프레임 그리기, ffmpeg 파이프)의 4단계 파이프라인으로 작동합니다. 가로, 세로, 정사각형 형식을 지원하며, 자막, 컴퓨터 생성 레이블, 제목, 이름 표시줄, 말하는 단어에 나타나는 포인트 사이드 패널, 엔드 카드를 포함합니다. 실제 사람 사진, 사칭, 딥페이크, 음소 동기화에는 사용할 수 없으며, 사용 전 초상권 동의 확인과 사실 주장 목록 확인을 요구합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VinVirtual/avatar-studio/tree/HEAD

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

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

문서

avatar-studio은(는) 무엇을 하나요?

파이프라인: head (토킹헤드: 초상화 → head.glb + head.json) → audio (Kokoro 음성, 측정된 단어 시간, 모든 프레임의 음량) → plan (음량 기반 입 모양, 시드 기반 깜빡임과 흔들림, 강세 단어에 끄덕임, 사이드 패널 응시, 시간에 따른 레이아웃) → render (모든 프레임은 t의 순수 함수, headless Chrome에서 그리고 ffmpeg로 파이프) → MP4 + 자막 + 웹 복사본.

스킬 폴더: ~/.claude/skills/avatar-studio/ (이하 $A). 모든 명령은 $A/avatar <command> <project>. $A/avatar help는 목록을 표시합니다. talking-head 스킬이 설치되어 있어야 합니다 (기본값 ~/.claude/skills/talking-head; 다른 폴더를 사용하려면 TALKING_HEAD_DIR 설정).

$A/avatar                  명령줄 (check, new, lint, head, audio, sheet, stills, video, build, test)
$A/engine/gen_audio.py     음성, 단어 시간, 프레임별 음량 ("avatar audio"가 실행)
$A/engine/lib/             순수, 단위 테스트된 모듈: envelope (입), motion, layout, plan, lint, captions
$A/engine/page/frame.js    한 프레임 그림: 배경, 헤드 (talking-head의 뷰어), 제목, 패널, 캡션, 레이블
$A/references/script.md    모든 스크립트 필드
$A/examples/juno/          완성된 예제 (Juno, talking-head의 가상 캐릭터)

시작하기 전: 얼굴과 단어에 대한 규칙

이 규칙들은 선택 사항이 아닙니다. 해당되는 경우 사용자에게 말하세요.

  1. 누구의 얼굴인가요? 초상화가 실제 사람을 보여주거나 그 사람으로부터 그려진 경우, 그 사람이 이 사용에 동의했어야 합니다. 사용자에게 물어보세요. 동의를 확인할 수 없으면 중단하세요. 공인, 동료, 전 애인, 어린이 또는 사용자가 대신 말할 수 없는 사람의 비디오를 절대 만들지 마세요. 스크립트에서 사용자가 확인한 후에만 "character": { "likeness": "real-person-with-consent", "consent": true }로 설정하세요; 그렇지 않으면 "likeness": "original" (창작 캐릭터) 또는 "licensed"를 사용하세요.
  2. 절대 사칭하지 마세요. 캐릭터가 실제 사람인 척 해서는 안 되며, 스크립트가 실제 사람의 말을 인용하거나, 그 사람의 실제 진술, 인용문, 지지, 사과로 제시해서는 안 됩니다. 사용자가 그런 요청을 하면 해당 부분을 거절하고 창작 캐릭터나 명백히 가상인 프레이밍을 제안하세요.
  3. 레이블을 표시하세요. 모든 프레임에는 화면상 레이블이 있습니다 (기본값 "컴퓨터 생성 캐릭터"; lint는 빈 값을 거부합니다). 엔드 카드는 캐릭터와 음성이 컴퓨터 생성임을 명시합니다. 사용자에게 비디오를 게시하는 모든 곳(캡션, 설명, 페이지 텍스트)에 유사한 메모를 유지하고 합성 미디어에 대한 플랫폼 규칙을 따르도록 알리세요.
  4. 주장을 나열하세요. 렌더링 전에 스크립트가 하는 모든 사실적 주장(숫자, 제품 기능, 가격, 날짜, 비교, 건강/법률/재무 진술)을 나열하고 사용자에게 각각 확인을 요청하세요. 캐릭터가 자신감 있는 목소리로 말하지만, 실제로 그 내용에 대한 책임은 사용자에게 있습니다.
  5. 머신 밖으로 아무것도 나가지 않습니다. 사용자의 명시적 동의 없이는: avatar head --source space는 초상화를 공개 Hugging Face Space에 업로드하며, 사용자 동의 후에 --yes가 필요합니다 (talking-head의 SKILL.md는 라이선스 제한을 설명합니다). 음성, 프레임 및 비디오는 모두 로컬에서 생성됩니다.

워크플로우

  1. 확인: $A/avatar check. 누락된 항목(talking-head, three.js, Kokoro, ffmpeg, Playwright, WebGL 지원 브라우저)을 어떻게 해결할지 알려줍니다.
  2. 시작: $A/avatar new <dir> --portrait picture.png (헤드가 빌드됩니다) 또는 --head <head.glb와 head.json이 있는 폴더> (예: $A/examples/juno/head를 재사용).
  3. 헤드 (초상화가 있는 경우에만): $A/avatar head <dir>. <dir>/build/head에서 talking-head를 실행하고(new, mark --auto, shape --source inflate, build, preview) 결과를 <dir>/head/로 복사합니다. 초상화가 마크 이후 변경되면 중단됩니다: --force(새 자동 마크) 또는 --marks FILE로 다시 실행하세요. 한 번에 하나의 Blender 프로세스만 실행되며 1-2분 정도 걸립니다. 그런 다음 <dir>/build/head/out/preview.png를 읽고 talking-head의 SKILL.md에 명시된 대로 평가하세요 (깜빡임 시 눈 가려짐, 입술 라인에서 입 열림). talking-head의 mark --page로 마크를 수정하거나 --marks FILE을 전달하고 avatar head를 다시 실행하세요.
  4. 스크립트: <dir>/script.json을 편집하세요 (필드는 references/script.md 참조). 줄은 한두 문장으로 유지하세요. 포인트는 2~6단어이며 같은 줄에서 말한 단어에 연결됩니다 ("at": "word"). 문장당 하나의 강세 단어를 *this*와 같이 표시하여 끄덕임을 나타냅니다. 그런 다음 오류가 없을 때까지 $A/avatar lint <dir>을 실행하세요 (sheet, stills, video, build는 자체적으로 lint를 실행하며 오류가 있으면 렌더링을 거부합니다: character.likeness 누락, consent: true 없는 실제 인물, 비었거나 너무 긴 레이블, 프로젝트 외부의 헤드 폴더). 지금 규칙 4(주장 나열)를 수행하세요.
  5. 음성: $A/avatar audio <dir>. 음성이나 타이밍을 변경하는 모든 것(줄, 음성, 속도, 언어, 발음, fps, lead, gap, tail, pause, 제목 또는 엔드 카드 추가/변경)을 변경한 후에는 다시 실행하세요; 렌더링 명령은 오래된 음성을 거부하고 그 이유를 알려줍니다. 각 줄의 시작, 길이, 그리고 단어 시간이 모델에서 측정되었는지(“모델의 음소 지속 시간에서”) 또는 추정되었는지 출력합니다; 추정된 시간으로는 포인트와 캡션이 약간 어긋날 수 있다고 렌더링 명령이 경고합니다. 20~60초를 목표로 하세요.
  6. 미리보기: $A/avatar sheet <dir> 실행 후 stills/<name>-sheet.png를 읽으세요 (비트당 한 프레임: 제목, 각 줄의 가장 넓은 입, 각 포인트, 깜빡임, 엔드 카드). 출력된 layout: 줄은 맞지 않은 텍스트입니다: 줄이세요. 확인: 얼굴 위에 텍스트 없음, 캡션이 읽을 수 있고 입 위에 없음, 패널 텍스트가 행 안에 있음, 레이블이 보임, 프레임 가장자리에서 잘리는 것 없음. 자세한 확인은 $A/avatar stills <dir> 4.2 11을 사용하고 해당 PNG를 읽으세요. 보지 않고 제대로 되었다고 말하지 마세요.
  7. 렌더링: $A/avatar video <dir> --web (또는 avatar build <dir>은 lint + audio + sheet + video + web + 반복 미리보기를 수행합니다). 완성된 파일에서 측정된 동기화 라인을 출력합니다: 그려진 입과 MP4에서 다시 디코딩된 사운드 에너지 간의 상관 관계 r과 최적 지연(프레임 단위). r이 0.75 이상이고 지연이 0 또는 -1(의도적으로 입이 한 프레임 앞섬)일 것으로 예상하세요. 이 숫자를 보고하세요; 사용자는 오디오를 들을 수 없습니다.
  8. 다른 형식: sheet, stills, video, build에 --format vertical 또는 --format square를 사용하세요. 파일 이름에 -<format>이 추가됩니다. 각 형식에 대해 시트를 다시 확인하세요.
  9. 사용자에게 알리세요 파일 위치(out/<name>.mp4, .vtt, .srt, out/web/), 동기화 숫자, 아래 제한 사항, 규칙 3 및 4.

솔직히 예상할 점

  • 입은 음량을 따릅니다, 음소가 아니라요: 큰 소리에 열리고 멈춤에서 닫힙니다. 만화에는 좋지만 입술 읽기에는 적합하지 않습니다.
  • 정면을 바라보는 일러스트 헤드만 잘 작동합니다 (talking-head의 제한 사항 적용: 오프라인 셰이프로 푹신한 프로필, 약 35도 이상의 평범한 측면). 그 이유로 헤드 회전은 작게 유지됩니다.
  • 실질적으로 비디오당 하나의 음성입니다 (줄이 자체 voice를 설정할 수 있지만, 화면에는 하나의 캐릭터만 있습니다).
  • 렌더링은 소프트웨어 WebGL입니다: 2페이지 기준 초당 약 4~5프레임이므로 30초 가로 비디오는 약 3분이 걸립니다.

규칙

  • 최대 2개의 브라우저 페이지(--workers 1|2)와 한 번에 하나의 Blender 프로세스.
  • 사용자가 렌더를 유지하기를 원하지 않는 한 프로젝트의 build/, stills/ 또는 out/ 폴더를 커밋하지 마세요.
  • engine/lib/의 내용을 변경한 후에는 $A/avatar test를 실행하세요.

관련 스킬