threerocks/sweety-handdraw-video

从主题或文章制作完整手绘讲解视频：按部位描线、逐字书写、VoiceStudio 配音、五项内置制作依赖。

그것이 무엇인가

Sweety‑handdraw‑video는 언어 모델 기반 에이전트가 텍스트(주제, 기사 또는 전체 이야기)를 손으로 그린 내레이션 비디오로 변환할 수 있게 하는 오픈소스 "스킬"입니다. 에이전트는 대본을 작성하고 스토리보드를 계획하며 시각적 스타일을 결정합니다. 로컬 Python 도구는 다음을 수행합니다:

Pillow/SciPy로 각 일러스트레이션을 스트로크별로 그리고,
손글씨 자막과 화면 텍스트를 렌더링하고,
그리기 단계를 사전 생성된 음성과 동기화하고,
FFmpeg로 MP4로 조립합니다.

이 프로젝트에는 21개의 사전 정의된 일러스트레이션 스타일, 6개의 손-팔 프리셋, 6개의 내장 음성 프로필이 포함되어 있습니다. 사용자는 자신의 자산을 제공할 수도 있습니다.

대상 사용자

콘텐츠 제작자: 시청자가 그리기 과정을 실시간으로 볼 수 있는 짧은 교육 또는 스토리텔링 비디오를 원하는 사람.
교사/트레이너: 강의 노트를 시각적 설명으로 빠르게 전환할 방법을 찾는 사람.
마케터 또는 인디 영화 제작자: 손으로 그린 설명 비디오를 위한 저렴하고 완전히 로컬인 파이프라인이 필요한 사람.

작동 방식(높은 수준 흐름)

에이전트에 프롬프트 – 使用 $sweety-handdraw-video，把“为什么越生气，越容易做错决定”做成手绘讲解 같은 명령을 보냅니다. 에이전트는:
- 핵심 포인트를 추출하고,
- 내레이션 대본을 작성하고,
- 스토리보드(장면 순서, 타이밍)를 만들고,
- 시각적 스타일, 손-팔 프리셋, 음성 프로필을 선택합니다.
음성 생성 – 다음 중 하나:
- 로컬 TTS 모델(Apple 실리콘의 VoxCPM2‑8bit 또는 자체 호스팅 VoiceStudio 서비스)을 실행하거나,
- 이미 녹음된 전체 길이 내레이션을 가져옵니다.
각 프레임 그리기 – Python 스크립트가 Pillow를 사용하여:
- 윤곽선을 추적하고 색상을 채우고 자막을 스트로크별로 쓰고,
- 선택한 프리셋에 따라 손-팔 그래픽을 애니메이션화합니다.
동기화 – 내레이션의 타임스탬프가 각 그리기 단계의 시작/종료를 구동합니다.
내보내기 – FFmpeg가 이미지 시퀀스, 오디오 및 선택적 자막을 1920×1080 @ 30fps MP4로 결합합니다.

모든 산출물(대본, 타임스탬프, 생성된 이미지, 오디오)이 저장되므로 전체 비디오를 다시 렌더링하지 않고도 단일 부분(예: 워터마크 변경)을 편집할 수 있습니다.

주요 기능

기능	제공 내용
21개의 내장 일러스트레이션 스타일	미니멀한 흑백 라인 아트에서 수채화 같은 "暖光童画"까지. 스타일은 숫자 ID(1‑20 + 3.1)로 식별되며 직접 선택하거나 모델이 콘텐츠에 따라 선택하도록 할 수 있습니다.
6개의 손-팔 프리셋	그림이 그려지는 동안 나타나는 다양한 손-팔 그림(예: `navy`, `diamond-woman`, `pen-only`).
6개의 음성 프로필	실제 녹음된 "逼真男声", "逼真女声", "甜美学姐" 등과 로컬 TTS 엔진(VoxCPM2 또는 VoiceStudio) 또는 기존 오디오 파일을 사용하는 기능.
전체 파이프라인 자동화	필요한 로컬 도구(Python 3.9+, Pillow, NumPy, SciPy, FFmpeg, Bun, ExifTool)가 설치되어 있으면 하나의 명령으로 원시 텍스트에서 최종 MP4까지.
편집 가능한 출력	대본, 타임스탬프, 자막, 워터마크, 펜 막대 텍스트가 별도로 저장되어 대상 재렌더링이 가능합니다.
로컬 전용 처리	클라우드 비디오 생성 서비스가 사용되지 않습니다. 모든 그리기 및 오디오 합성은 사용자 머신에서 발생합니다.
스킬 기반 설치	`npx skills add threerocks/sweety-handdraw-video`로 추가하거나 폴더를 Codex 스타일 Skills 디렉토리에 수동으로 복사하여 추가할 수 있습니다.

시작하기(빠른 체크리스트)

스킬 설치 – npx skills add threerocks/sweety-handdraw-video(또는 v1.2.3 릴리스를 ~/.codex/skills/에 압축 해제).

Python 환경 설정:

python3 -m venv .venv && source .venv/bin/activate
pip install -r skills/sweety-handdraw-video/scripts/requirements.txt
python skills/sweety-handdraw-video/scripts/validate_package.py

외부 도구 확인 – FFmpeg/ffprobe, 중국어 글꼴, Bun + ExifTool, TTS 백엔드(Apple 실리콘의 VoxCPM2 또는 로컬에서 실행 중인 VoiceStudio 서비스).
테스트 프롬프트 실행 – README에 표시된 예제 명령을 에이전트(예: Codex)에 보냅니다. 에이전트는 계획으로 응답한 다음 로컬 스크립트를 호출하여 비디오를 생성합니다.
결과 찾기 – 출력 폴더에는 video.mp4, 커버 PNG, SRT 자막 파일, 생성된 대본 및 타임스탬프 로그가 포함됩니다.

제한 사항 및 미해결 질문

플랫폼 지원 – 전체 엔드투엔드 흐름은 Apple 실리콘(M3 Max)이 있는 macOS/Linux에서만 검증되었습니다. Windows 및 기타 하드웨어는 특히 VoxCPM2 TTS 모델에서 추가 작업이 필요할 수 있습니다.
업스트림 모델 비용 – 에이전트가 호출하는 이미지 생성 및 TTS 모델은 상업적이거나 별도 라이선스가 필요할 수 있습니다. 저장소에는 포함되어 있지 않습니다.
배경 음악 없음 – 파이프라인은 의도적으로 순수 내레이션을 출력합니다. 음악을 추가하려면 수동 후처리 단계가 필요합니다.
배치 처리 – 도구는 여러 입력에 대해 스크립트화할 수 있지만 내장 큐 관리자는 없습니다. 각 비디오는 여전히 전체 그리기 및 동기화 주기를 거칩니다.
손글씨 충실도 – 스트로크는 간단한 윤곽선-채우기 알고리즘을 따릅니다. 올바른 중국어 획 순서나 서예 스타일을 보장하지 않습니다.

TL;DR

sweety-handdraw-video는 LLM 기반 계획과 로컬 Python 렌더링을 결합하여 일반 텍스트에서 손으로 그린 내레이션 비디오를 생성하는 진정한 오픈소스 프로젝트입니다. 기성 시각적 스타일, 손-팔 프리셋 및 음성 프로필이 포함되어 있으며 전적으로 사용자 머신에서 실행되며 클라우드 서비스 없이 빠르고 편집 가능한 설명 비디오를 원하는 제작자를 대상으로 합니다.