autoRecording
웹 앱을 완성된 데모 비디오로 바꿉니다. 스토리 파일에 보여줄 내용과 말할 내용을 작성하면; 스크립트가 녹화, 그리기, 인코딩, 나레이션 및 검사를 수행합니다. 비디오는 음소거 버전 또는 중국어, 영어, 일본어, 한국어, 독일어, 프랑스어, 스페인어, 이탈리아어, 포르투갈어, 러시아어 중 하나로 나레이션된 버전으로 제작할 수 있으며, 로컬 모델(GPU 또는 CPU) 또는 사용자가 제공하는 원격 서비스로 음성을 생성합니다.
story.py ──demo_record.py──► timeline.json + frames/*.jpg
│
demo_render.py ──► silent.mp4 (1920×1080, 60 fps)
│
demo_voice.py ──► silent-配音版.mp4 / silent-narrated.mp4 (선택 사항)
0. 무엇보다 먼저 물어보세요
다음 질문에 대한 답변을 받기 전까지 녹화를 시작하지 마세요. Claude Code에서는 AskUserQuestion을 사용하고; Codex 또는 다른 에이전트에서는 일반 언어로 질문하고 답변을 기다리세요.
- 나레이션? 음소거 비디오, 또는 음성 나레이션. 사용자가 나레이션을 원하지 않으면 모든 나레이션 단계를 건너뛰고; 음소거 비디오가 최종 결과물입니다.
- 나레이션 언어 (캡션의 언어이기도 하며, 스크립트가 읽는 언어입니다): 普通话 / English / 日本語 / 한국어 / Deutsch / français / español / italiano / português / русский. 기본값: 앱의 언어와 사용자가 작성하는 언어.
- 엔진. 이 기계가 실제로 할 수 있는 것을 제공하세요 —
python3 scripts/demo_env.py를 먼저 실행하고 사용 가능하다고 나열된 엔진만 제공하세요:- 로컬 Qwen3-TTS (本机 GPU): 최고 품질; 약 6 GB 여유 VRAM이 있는 NVIDIA GPU와 Qwen 모델이 필요합니다.
- 로컬 Kokoro (本机 CPU): GPU 불필요, Windows 및 macOS에서 작동; 중국어와 영어에 좋음; 음성은 고정됨(복제 불가).
- 원격 API: 사용자가 제공자(OpenAI 호환 엔드포인트, 자체 호스팅 포함, ElevenLabs, 또는 Alibaba DashScope Qwen-TTS), 키, 그리고 선택적으로 base URL, 모델 및 음성 ID를 제공합니다. 경험 법칙: 준비된 로컬 모델이 있으면 → 사용; 사용자가 API 키를 제공하면 → API 사용; 둘 다 아니면 → Kokoro 설치(작은 다운로드) 또는 음소거 진행 여부를 물어보세요.
- 음성, 엔진에 선택권이 있는 경우: 각각 한 줄씩 3–5개의 음성을 제공하고(예: Qwen
serena/ryan, Kokorozf_039/zm_013/af_maple, OpenAI 음성 ID), 합리적인 기본값을 제시하세요.
답변을 스토리 파일에 기록하세요 — LANGUAGE 및 VOICE = {'engine': …, 'speaker': …} — 동일한 비디오를 다시 만들 수 있도록. 원격 키는 절대 스토리 파일에 기록하지 마세요: 환경 변수나 demo_env.py key에 넣으세요.
절대 지켜야 할 사항
- 사용자의 라이브 서비스나 실제 데이터를 절대 녹화하지 마세요. 고유한 데이터 디렉토리(
launch()in the story file)와 함께 다른 포트에서 임시 인스턴스를 시작하거나, 전용 데모 데이터셋을 사용하세요. 앱을 분리할 수 없으면 물어보세요. - 화면을 보지 말고 숫자로 확인하세요.
demo_render.py --check및demo_voice.py check가 진실 공급원입니다. 둘 중 하나라도注意:문제를 보고하는 동안 비디오가 완료되었다고 주장하지 마세요. - 실행 중인 서비스를 건드리지 마세요. 선택한 포트가 이미 사용 중이면 다른 포트를 선택하세요; 타인의 프로세스를 절대 중지하지 마세요.
- 나레이션은 선택 사항이며 엔진은 사용자의 선택입니다. Qwen은 NVIDIA GPU가 필요합니다; Kokoro는 모든 CPU에서 실행됩니다; 원격 서비스는 키가 필요하며 캡션을 해당 서비스로 보냅니다 — 사용하기 전에 이를 알리세요.
구조
SKILL.md 이 파일
scripts/demo_env.py 기계 확인; 기술의 Python 환경 구축; 모델 가져오기; 키 기억
scripts/demo_record.py 앱 구동 및 프레임 + 타임라인 녹화
scripts/demo_render.py 음소거 비디오 그리기 및 인코딩; 숫자 검사
scripts/demo_voice.py 나레이션: lines, anchor, takes, hear, build, check
scripts/demo_tts.py 엔진: Kokoro (CPU) 및 원격 서비스
scripts/demo_text.py 언어별 캡션 발화, 계산 및 비교 방법
scripts/demo_common.py 공유 경로, 설정, 브라우저, 비밀
story_template.py 앱용 스토리 작성을 위해 복사
예제/selftest/ 페이지 및 두 개의 스토리 (중국어 story.py, 영어 story-en.py)
참조/ environment.md, director.md, narration.md, engines.md
아래 모든 명령어는 이 스킬의 디렉토리를 기준으로 합니다; Windows에서는 python3 대신 py -3(또는 python)를 작성하세요. ~/.claude/skills/autoDemoRecordingSkill(Claude Code) 또는 ~/.agents/skills/autoDemoRecordingSkill(Codex)로 클론하여 개인 스킬로 설치하세요.
1. 기계 확인
cd ~/.claude/skills/autoDemoRecordingSkill
python3 scripts/demo_env.py # 읽기 전용: 무엇이 있고, 무엇이 없고, 어떻게 얻고, 어떤 엔진이 말할 수 있는지
python3 scripts/demo_env.py setup # 녹화/렌더링/검사용 패키지 (수백 MB)
python3 scripts/demo_env.py setup --models # + Whisper large-v3 및 CAM++ 검사 (~3 GB)
python3 scripts/demo_env.py setup --kokoro # + Kokoro, CPU 음성 (~400 MB)
Qwen 엔진의 경우 CUDA torch와 faster-qwen3-tts가 있는 Python, 그리고 두 개의 Qwen3-TTS 1.7B 모델도 준비하세요; 원격 엔진의 경우 python3 scripts/demo_env.py key openai=…(또는 환경 변수)로 키를 한 번 기억시키세요. 기본값이 아닌 모든 위치를 한 번 기록하세요:
python3 scripts/demo_env.py set chromium=/path/to/chromium tts_python=/path/to/python \
tts_custom=/path/to/Qwen3-TTS-12Hz-1.7B-CustomVoice tts_base=/path/to/Qwen3-TTS-12Hz-1.7B-Base
스킬의 자체 파일은 ~/.cache/auto-demo-recording에 있습니다(AUTO_DEMO_HOME으로 재정의 가능). references/environment.md에 Windows, macOS 및 Linux 세부 정보가 있습니다.
2. 자체 테스트로 설치 확인
PY=~/.cache/auto-demo-recording/venv/bin/python
S=~/.claude/skills/autoDemoRecordingSkill
$PY $S/scripts/demo_record.py --story $S/예제/selftest/story.py --work /tmp/demo-selftest
$PY $S/scripts/demo_render.py --work /tmp/demo-selftest --check
$PY $S/scripts/demo_render.py --work /tmp/demo-selftest --out /tmp/demo-selftest/selftest.mp4
$PY $S/scripts/demo_voice.py --work /tmp/demo-selftest # 나레이션이 필요한 경우에만
story-en.py는 영어 캡션과 영어 나레이션 경로가 있는 동일한 테스트입니다. 녹화는 JSON 요약(길이, 프레임, 브라우저, 오류)을 출력합니다. selftest.mp4는 1920×1080, 60 fps, 약 64초여야 합니다.
3. 스토리 작성
story_template.py를 앱 옆(또는 아무 곳에) 복사하고 내용을 채우세요. 계약 사항:
| 이름 | 설명 |
|---|---|
TITLE, SUBTITLE, CHAPTERS | 상단 밴드의 텍스트; 챕터는 페이지에도 그려짐 |
LANGUAGE | 캡션 및 나레이션 언어 (zh, en, ja, ko, de, fr, es, it, pt, ru) |
VIEW, DENSITY | CSS px 단위 페이지 크기 및 장치 배율; 너비/높이는 64:31이어야 함 |
PORT | 임시 인스턴스의 포트 |
LOOK | {'accent': '#2f6fed', 'note': '#ee5c18', 'fast': '快进'} — fast는 캡션 밴드의 언어로 |
VOICE | 나레이션: engine, speaker, 원격 서비스의 경우 model / base_url (키는 제외); references/engines.md 참조 |
READING | 캡션 읽기 속도; 기본값: 언어 고유 값 (중국어의 경우 초당 5.5자) |
launch(work, port) | {'command': [...], 'url': ..., 'env': {...}, 'wipe': [...], 'cwd': ..., 'ready': ..., 'timeout': ...}; 또는 URL 대신 정의 |
guard(d) | 선택 사항; 페이지가 의도한 초기 상태가 아니면 조기에 실패 |
story(d) | 실제 지시: await d.say(...), await d.click(...) 등 |
d 객체는 디렉터입니다. 전체 API, 시간 모델, 마크/장소 규칙 및 일반 패턴은 references/director.md에 있습니다. 스토리를 작성하기 전에 이를 읽으세요; 이 파일의 나머지 부분은 워크플로우만 설명합니다.
좋은 스토리를 위한 경험 법칙:
- 캡션당 하나의 아이디어; 시청자가 주목해야 할 것과 페이지가 실제로 보여주는 결과를 명시하세요.
- 진행하기 전에
d.say()다음에d.read()를 선호하세요; 캡션은 또한 나레이션 스크립트입니다. - 캡션은
LANGUAGE로 작성하세요. 음소거 비디오의 경우에도 화면에 표시되므로 짧게 유지하세요. - 클릭에 번호를 매기고(
await d.click(locator, '添加')) 중요한 것만 표시하세요. - 긴 대기는 자르는 대신 빠르게 재생하세요(
await d.until(..., speed=4)).
4. 녹화
$PY $S/scripts/demo_record.py --story /path/to/story.py --work /tmp/demo-work --quick
$PY $S/scripts/demo_record.py --story /path/to/story.py --work /tmp/demo-work
--quick는 빠른 시험입니다: 시청자 일시 중지를 건너뛰고 앱만 기다립니다. 선택자 및 상태 오류를 잡는 데 사용하세요. 그런 다음 실제 녹화를 진행하세요; work/timeline.json은 덮어쓰여지고 이전 프레임은 제거됩니다.
녹화 전에 스크립트는 frames와 wipe에 나열된 경로만 지우고, 포트가 사용 가능한지 확인하며, 스토리의 명령을 시작하고, 앱이 응답할 때까지 기다립니다. 앱의 로그는 work/server.log입니다. Windows에서는 앱과 앱이 시작한 모든 것이 taskkill /T로 중지됩니다; 다른 곳에서는 전체 프로세스 그룹이 중지됩니다.
5. 확인 및 렌더링
$PY $S/scripts/demo_render.py --work /tmp/demo-work --check
$PY $S/scripts/demo_render.py --work /tmp/demo-work --out /tmp/demo-work/demo.mp4
--check는 사진을 보지 않고 다음을 확인합니다: 표시된 영역이 비어 있지 않고 expect 색상과 일치하는지, 레이블이 페이지 콘텐츠 위에 있지 않은지, 상자가 카메라 안에 있는지, 단계/클릭이 보이는지, 캡션이 맞는지, 글꼴에 문자가 존재하는지. 스토리나 타이밍을 수정하고 다시 녹화하세요. 렌더링은 또한 샘플링된 출력 프레임을 그린 프레임과 비교하여 work/render.json을 작성합니다.
사용자가 나레이션을 원하지 않으면, 음소거 비디오가 최종 결과물입니다 — 여기서 중단하고 보고하세요.
6. 나레이션 (요청된 경우에만)
$PY $S/scripts/demo_voice.py --work /tmp/demo-work # 모든 단계
$PY $S/scripts/demo_voice.py lines --work /tmp/demo-work # 먼저 발음/타이밍 검사
음성 비디오를 음소거 버전 옆에 작성합니다: <name>-配音版.mp4 (중국어), <name>-narrated.mp4 (기타 언어). 단계는 재개 가능합니다: 참조 클립 → (Qwen: 시험) → 테이크 → 음성/스피커 검사 → 선택/맞춤/혼합 → 확인. 설정, 발음 수정 및 타이트한 라인에 대해서는 references/narration.md를 읽고, 엔진, 음성, 키 및 비용에 대해서는 references/engines.md를 읽으세요. 최종 check는 没有发现问题라고 말해야 합니다; 听写有出入 줄이 있으면 목소리가 다른 것을 말한 것입니다 — 캡션을 수정하고, say 재정의를 추가하고, 해당 줄을 다시 말하거나, 다른 음성을 선택하세요.
7. 보고
사용자에게 출력 경로(음소거 및 요청 시 나레이션), 길이, 해상도/fps, 캡션/마크 수, 나레이션 엔진 및 음성, 그리고 나레이션 확인 결과를 제공하세요. 남아있는 注意: 경고가 있으면 언급하고, 실패한 검사를 절대 숨기지 마세요.
문제 해결 첫걸음
缺 …→python3 scripts/demo_env.py를 실행하고→줄을 따르세요.- 포트 이미 사용 중 → 스토리의
PORT를 변경하세요; 기존 서비스를 중지하지 마세요. 点不到这个元素→ 요소가 가려졌거나 화면 밖에 있습니다; 먼저 스크롤/확대하거나 다른 대상을 선택하세요.- 페이지 너비 불일치 → 페이지가
VIEW에서 반응하지 않습니다;VIEW또는 페이지를 조정하고 64:31 비율을 유지하세요. - 나레이션 라인이 너무 촉박함 → 해당 캡션을 줄이거나 더 많은 시간을 주고 다시 녹화하세요.
Kokoro 的词表里没有这些词→ 해당 단어는 Kokoro에서 건너뜁니다; 캡션의VOICE['say']에 해당 단어의 철자를 추가하거나(예:"API": "A P I","exported": "export ed"), 영어의 경우 Qwen 또는 원격 엔진을 사용하세요.- 글꼴 상자 (□□□) → Linux에서 Noto Sans CJK를 설치하세요; Windows 및 macOS에는 자체 중국어 글꼴이 있습니다; 또는
DEMO_FONT_*를 설정하세요(references/environment.md참조).
Codex 환경
Codex는 동일한 SKILL.md를 로드합니다. AskUserQuestion 도구가 없습니다: 0단계 질문을 일반 언어로 하세요. 다른 PATH로 실행될 수 있습니다 — py -3 또는 스킬의 Python 전체 경로를 사용하세요. git clone … ~/.agents/skills/autoDemoRecordingSkill로 스킬을 설치하거나(또는 Codex의 스킬 설치 관리자가 ~/.codex/skills에 배치하도록 함); 둘 다 발견됩니다. agents/openai.yaml은 표시 이름과 시작 프롬프트를 제공합니다.
개인정보 보호
작업 폴더에는 앱이 표시한 모든 것의 스크린샷이 포함되어 있습니다. 샘플 데이터로 임시 인스턴스를 사용하고, 실제 계정, 고객 또는 프로덕션 레코드는 절대 사용하지 마세요. 검토 없이 work/ 또는 렌더링된 비디오를 커밋하지 마세요. timeline.json은 또한 스토리 파일 경로와 캡처 시간을 기록합니다. 원격 나레이션 서비스는 모든 라인의 캡션 텍스트를 수신합니다; 로컬 엔진은 아무것도 보내지 않습니다.