talking-clip은(는) 무엇을 하나요?
클립은 네 단계로 구성됩니다: 대사 작성, 음성 만들기, 연기 계획, 빌드 및 렌더링. 출력물: HyperFrames 프로젝트와 mp4 파일(기본 1080x1920 세로).
1. 대사 캐릭터의 목소리로 작성
2. 음성 scripts/tts.py (ElevenLabs는 크레딧 소모; say와 none은 무료)
3. 계획 plan.json 작성 (단어에 맞춘 제스처와 표정)
4. 동영상 scripts/build_clip.py -> scripts/verify.py -> scripts/render.py
경로는 이 패키지의 루트를 기준으로 합니다: .claude-plugin/ 폴더가 있는 디렉토리로, 이 파일보다 두 단계 위에 있습니다(심볼릭 링크 해석 후). 공개 HyperFrames 스킬(hyperframes, hyperframes-cli)이 필요합니다: 컴포지션을 직접 편집하기 전에 hyperframes를 한 번 읽으십시오.
0. 사전 점검 (항상 먼저)
python3 scripts/setup.py doctor를 실행하십시오(--json을 추가하면 파싱 가능). 모든 의존성, 용도, 이 머신에 맞는 정확한 설치 명령어를 나열하며, 필수 항목이 없으면 exit 1로 종료합니다.
- 필수 항목 누락 (ffmpeg, Node.js 18+, HyperFrames 스킬, ElevenLabs 키 또는 설정된 음성에 대한
say): 각각의 용도를 한 줄로 설명하고 출력된 명령어를 제안하십시오. 사용자가 동의한 후에만 실행하십시오. API 키를 직접 입력하거나 요청하지 마십시오: 사용자에게 셸에서ELEVENLABS_API_KEY를 export하도록 안내하십시오. - 선택 항목 누락: 한 번 제안하고 각각이 무엇을 가능하게 하는지 설명하십시오. Playwright는 요소 확대 상자와 전체 페이지 캡처를 포함한 웹 캡처를 제공하고, tesseract(OCR)는 스크린샷의 비밀 스캔을 제공하며, ASR(mlx-whisper / openai-whisper)는 오디오 확인과 정확한 단어 타이밍을 제공합니다. 사용자가 거절하면 건너뛰십시오. 해당 확인은 수동
review단계가 됩니다. - HyperFrames 스킬 (
hyperframes,hyperframes-cli,hyperframes-registry,media-use): 누락된 경우npx hyperframes skills를 권장하십시오. 컴포지션을 빌드하거나 편집하기 전에hyperframes(및 렌더 문제가 있을 경우hyperframes-cli)를 읽으십시오.
설정 (첫 실행 또는 사용자가 변경을 원할 때)
설정 확인: python3 scripts/setup.py show. 설정이 없거나 사용자가 캐릭터, 음성, 렌더 또는 스타일 변경을 요청하면, 인터뷰를 진행하십시오(한 번에 하나의 짧은 질문, 기본값 제시). 그런 다음 플래그로 설정을 작성하십시오:
| 질문 | 플래그 | 옵션 |
|---|---|---|
| 어떤 파트? | --features | character, explainer, 또는 둘 다 |
| 어떤 캐릭터? | --character | 번들 예제(pkg:characters/host/character.json) 또는 사용자 경로(절대 경로로 저장) |
| 내레이션 언어 | --language | ISO 코드; say 사용 시 적합한 음성이 선택됨(setup.py voices --lang <code>로 목록 확인, --say-voice로 재정의 가능) |
| 어떤 음성? | --voice | elevenlabs (ELEVENLABS_API_KEY에 키, --voice-id에 음성 ID), say (macOS, 무료), none |
| 크레딧 관리 (ElevenLabs) | --max-chars, --max-seconds, --daily-credit-cap | 사용자가 선택한 숫자; 비워두면 제한 없음 |
| 렌더링 방식? | --render | local (무료, 이 머신), cloud (HyperFrames 클라우드, npx hyperframes auth login 필요), preview (Studio 전용) |
| 해상도 | --size | 1080x1920, 1920x1080, 1080x1080 |
python3 scripts/setup.py init --features character --voice say --render local --yes
init은 먼저 doctor를 실행하고 동일한 설치를 제안합니다. 설정이 이미 있으면 덮어쓰기 전에 확인하며, 비대화형 모드에서는 --force가 필요합니다.
사용자 캐릭터: python3 scripts/setup.py new-character --name "<name>" --out ./characters/<name> --activate
예제를 복사하고 활성화합니다(두 번째 init 불필요). 그런 다음 출력되는 키를 채우도록 도와주십시오:
description, personality, speaking_style.rules, rig.colors (또는 스프라이트), expressions / poses / gestures, set, voice_moods.
API 키를 요청하거나 출력하거나 기록하지 마십시오. ELEVENLABS_API_KEY가 없으면 사용자에게 셸에서 export하도록 안내하십시오. 설정 스키마는 config/config.schema.json에, 캐릭터 파일 형식은 README("Your own character")에 있습니다.
이 클립의 스타일 선택
고정된 스타일은 없습니다. 각 클립마다 주제, 대상, 사용자의 브랜드 또는 취향에 따라 스타일을 선택하십시오: 세트({"type": "color"|"gradient"|"image", ...}), 프레이밍(close, medium, wide), 모션 강도(calm, normal, lively). 클립이 브랜드, 공개 채널 또는 시리즈용일 때는 사용자에게 선택을 물어보십시오. 이전 클립을 반복하지 않고 클립 간에 스타일을 다양화하십시오. 설정에 brand 키트가 있으면 background가 선택을 덮어씁니다. 스타일을 파일에 쓰고 --style로 전달하십시오:
{"set": {"type": "gradient", "colors": ["#FFF4E6", "#FFD9B3"]}, "framing": "medium", "motion": "lively"}
단어도 마찬가지입니다: 캐릭터의 성격 내에서 대상에 맞는 톤을 선택하고, 클립마다 같은 시작 또는 마무리 문장을 재사용하지 마십시오.
1. 대사 작성
설정(character 키)에 지정된 캐릭터 파일을 읽으십시오: personality와 speaking_style.rules가 목소리입니다. 이를 따르되, 충돌 시 사용자의 요청이 우선합니다.
- 길이: 최대
styles.talking_clip.max_seconds.speaking_style.chars_per_second(약 14) 기준 20초 클립은 약 260자 이하입니다. 한 가지 아이디어, 한 마디 마무리. - 언어: 사용자의 언어를 사용하며, 다른 요청이 없으면 그대로 사용합니다.
- ElevenLabs 모델(v3 이상)은 영어 감정 태그를 지원합니다:
[excited],[calm],[whispers],[laughs],[pause].say와none은 이를 무시합니다(제거됨). 대신 제스처로 연기하십시오.
2. 음성 만들기
python3 scripts/tts.py estimate --text "<line>" --max-seconds 20
python3 scripts/tts.py speak --text "<line>" --out out/voice.wav [--mood excited] [--confirm]
- ElevenLabs: 항상 먼저
estimate를 실행하고 사용자에게 비용을 알리십시오.speak는--confirm없이 거절하며, 사용자가 설정한 제한(최대 문자, 최대 초, 일일 크레딧 한도)이 위반될 경우 거절합니다.--takes 2로 대안을 생성합니다. 단어 타이밍은out/voice.wav.words.json에 저장됩니다. --mood는 캐릭터의voice_moods에서 분위기를 선택합니다(ElevenLabs 설정 + 선택적 ffmpeg 필터).say/none: 무료.none의 경우 오디오가 없으며, 대신--text를 빌더에 전달하십시오.
3. 연기 계획
python3 scripts/timings.py out/voice.wav --text "<line>"는 단어 시작 시간을 제공합니다. plan.json을 작성하십시오:
{"expression": "neutral",
"events": [{"t": 0.0, "gesture": "hello"},
{"t": 2.1, "gesture": "explain", "dur": 2.5},
{"t": 5.0, "expression": "happy"},
{"t": 6.2, "gesture": "wink"}]}
gesture와expressionID는 캐릭터 파일(gestures,expressions)에서 가져옵니다. 각 제스처에는 설명과 일반적인dur이 있습니다. 계획 전에 이를 읽으십시오.- 입, 깜빡임, 호흡, 무게 중심 이동은 자동입니다. 연기 비트만 배치하십시오.
- 강한 제스처는 해당 단어보다 0.2-0.3초 먼저 배치하십시오. 비트당 하나의 반응; 같은 초에 두 개의 제스처를 넣지 마십시오. 차분하고 유지되는 제스처로 끝나야 합니다(자동으로 끝까지 유지됩니다).
4. 빌드, 확인, 렌더링
python3 scripts/build_clip.py --audio out/voice.wav --plan out/plan.json --style out/style.json --project out/clip
python3 scripts/render.py out/clip --out out/clip.mp4 --quality draft
python3 scripts/verify.py all --project out/clip --text "<line>" --video out/clip.mp4
확인은 필수입니다(설명 스킬의 "Verify" 섹션과 동일한 루프):
build는 깨끗해야 하고, render는 접촉 시트를 제공하므로 반드시 확인해야 합니다(입이 움직이는지, 제스처가 계획된 위치에 있는지, 잘리는 부분이 없는지). audio는 ASR로 단어를 확인하고 길이 제한을 확인합니다. 실패한 단계부터 수정하고 다시 실행하십시오. 각 verify.py all 실행은 한 번의 반복입니다. verify.max_iterations에 도달하면 exit 2로 종료되며, 상태를 사용자에게 알리고 배송하지 마십시오. render는 접촉 시트를 확인하고 verify.py mark render pass|fail --project out/clip --note "..."로 기록한 후 verify.py all을 다시 실행할 때까지 review 상태로 유지됩니다(재빌드 시 표시가 무효화됨).
그런 다음 설정된 백엔드로 최종 렌더링: python3 scripts/render.py out/clip --out out/clip.mp4
(render.max_mb는 업로드 제한에 맞게 재인코딩). mp4 또는 wav 파일을 커밋하지 마십시오.