autoRecording
Convierte una aplicación web en un video demo terminado. Tú escribes un archivo guión que indica qué mostrar y qué decir; los scripts se encargan de la grabación, el dibujo, la codificación, la narración y la verificación. El video puede ser silencioso o narrado, en mandarín, inglés, japonés, coreano, alemán, francés, español, italiano, portugués o ruso, interpretado por un modelo local (GPU o CPU) o por un servicio remoto que el usuario proporciona.
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 (opcional)
0. Preguntar antes de cualquier otra cosa
No empieces a grabar antes de haber respondido a estas preguntas. En Claude Code usa AskUserQuestion; en Codex o cualquier otro agente, pregunta en palabras simples y espera la respuesta.
- ¿Narración? Video silencioso o narración hablada. Si el usuario no necesita narración, omite todos los pasos de narración; el video silencioso es el entregable.
- Idioma de la narración (y de los subtítulos, que son el texto que se lee): 普通话 / English / 日本語 / 한국어 / Deutsch / français / español / italiano / português / русский. Por defecto: el idioma de la aplicación y en el que escribe el usuario.
- Motor. Ofrece lo que esta máquina puede hacer realmente: ejecuta
python3 scripts/demo_env.pyprimero y solo ofrece los motores que aparezcan como disponibles:- local Qwen3-TTS (GPU local): mejor calidad; necesita una GPU NVIDIA con ~6 GB de VRAM libre y los modelos Qwen.
- local Kokoro (CPU local): no necesita GPU, funciona en Windows y macOS; buen mandarín e inglés; las voces son fijas (sin clonación).
- API remota: el usuario proporciona el proveedor (endpoint compatible con OpenAI incluyendo auto-alojados, ElevenLabs, o Alibaba DashScope Qwen-TTS), la clave y, opcionalmente, una URL base, modelo e ID de voz. Regla general: un modelo local que está listo → úsalo; el usuario ofrece una clave API → usa la API; ninguno → pregunta si se debe instalar Kokoro (descarga pequeña) o si se quiere un video silencioso.
- Voz, si el motor tiene opciones: ofrece 3–5 voces con una línea cada una (ej. Qwen
serena/ryan, Kokorozf_039/zm_013/af_maple, un ID de voz de OpenAI), con un valor predeterminado razonable.
Escribe las respuestas en el archivo guión — LANGUAGE y VOICE = {'engine': …, 'speaker': …} — para que el mismo video pueda volver a hacerse. Una clave remota nunca se escribe en el guión: colócala en el entorno o en demo_env.py key.
Innegociables
- Nunca grabes el servicio en vivo del usuario ni sus datos reales. Inicia una instancia desechable en otro puerto con su propio directorio de datos (
launch()en el archivo guión), o un conjunto de datos demo dedicado. Si la aplicación no se puede aislar, pregunta. - Comprueba con números, no mirando imágenes.
demo_render.py --checkydemo_voice.py checkson la fuente de la verdad. No afirmes que un video está terminado mientras alguno reporte problemas注意:. - No toques un servicio en ejecución. Si el puerto elegido ya está escuchando, elige otro puerto; nunca detengas el proceso de otra persona.
- La narración es opcional y su motor es elección del usuario. Qwen necesita una GPU NVIDIA; Kokoro funciona en cualquier CPU; los servicios remotos necesitan una clave y envían los subtítulos a ese servicio — dilo antes de usar uno.
Estructura
SKILL.md este archivo
scripts/demo_env.py verificar la máquina; preparar el Python de la habilidad; descargar modelos; recordar claves
scripts/demo_record.py conducir la app y grabar fotogramas + línea de tiempo
scripts/demo_render.py dibujar y codificar el video silencioso; comprobaciones numéricas
scripts/demo_voice.py narración: líneas, anclaje, tomas, escuchar, construir, verificar
scripts/demo_tts.py los motores: Kokoro (CPU) y los servicios remotos
scripts/demo_text.py cómo se dicen, cuentan y comparan los subtítulos, por idioma
scripts/demo_common.py rutas, configuraciones, navegadores, secretos compartidos
story_template.py copia esto para escribir un guión para una aplicación
examples/selftest/ una página y dos guiones (guión en mandarín story.py, guión en inglés story-en.py)
references/ environment.md, director.md, narration.md, engines.md
Todos los comandos siguientes son relativos al directorio de esta habilidad; en Windows escribe py -3 (o python) donde está escrito python3. Instala como habilidad personal clonando en ~/.claude/skills/autoDemoRecordingSkill (Claude Code) o ~/.agents/skills/autoDemoRecordingSkill (Codex).
1. Verificar la máquina
cd ~/.claude/skills/autoDemoRecordingSkill
python3 scripts/demo_env.py # solo lectura: qué hay, qué falta, cómo obtenerlo, qué motores pueden hablar
python3 scripts/demo_env.py setup # paquetes para grabar/renderizar/verificar (unos cientos de MB)
python3 scripts/demo_env.py setup --models # + Whisper large-v3 y checks CAM++ (~3 GB)
python3 scripts/demo_env.py setup --kokoro # + Kokoro, la voz para CPU (~400 MB)
Para el motor Qwen también prepara un Python con torch CUDA y faster-qwen3-tts, y los dos modelos Qwen3-TTS 1.7B; para un motor remoto, recuerda su clave una vez con python3 scripts/demo_env.py key openai=… (o una variable de entorno). Registra cada ubicación no predeterminada una vez:
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
Los archivos propios de la habilidad residen en ~/.cache/auto-demo-recording (sobresscribe con AUTO_DEMO_HOME). references/environment.md tiene los detalles para Windows, macOS y Linux.
2. Validar la instalación con la autoprueba
PY=~/.cache/auto-demo-recording/venv/bin/python
S=~/.claude/skills/autoDemoRecordingSkill
$PY $S/scripts/demo_record.py --story $S/examples/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 # solo si se desea narración
story-en.py es la misma prueba con subtítulos en inglés y la ruta de narración en inglés. La grabación imprime un resumen JSON (duración, fotogramas, navegador, errores). selftest.mp4 debería ser 1920×1080, 60 fps, aproximadamente 64 s.
3. Escribir el guión
Copia story_template.py al lado de la aplicación (o en cualquier lugar) y complétalo. El contrato:
| Nombre | Qué es |
|---|---|
TITLE, SUBTITLE, CHAPTERS | texto en la banda superior; los capítulos también se dibujan en la página |
LANGUAGE | el idioma de los subtítulos y de la narración (zh, en, ja, ko, de, fr, es, it, pt, ru) |
VIEW, DENSITY | tamaño de página en píxeles CSS y escala de dispositivo; ancho/alto debe ser 64:31 |
PORT | puerto de la instancia desechable |
LOOK | {'accent': '#2f6fed', 'note': '#ee5c18', 'fast': '快进'} — fast en el idioma de la banda de subtítulos |
VOICE | narración: engine, speaker, y para un servicio remoto model / base_url (nunca la clave); ver references/engines.md |
READING | velocidad de lectura para los subtítulos; por defecto: la del idioma (5.5 caracteres/s para mandarín) |
launch(work, port) | {'command': [...], 'url': ..., 'env': {...}, 'wipe': [...], 'cwd': ..., 'ready': ..., 'timeout': ...}; o define URL en su lugar |
guard(d) | opcional; falla temprano si la página no está en el estado inicial previsto |
story(d) | la dirección real: await d.say(...), await d.click(...), etc. |
El objeto d es el director. Su API completa, modelo de tiempo, reglas de marcado/colocación y patrones comunes están en references/director.md. Léelo antes de escribir un guión; el resto de este archivo es solo el flujo de trabajo.
Reglas generales para un buen guión:
- Una idea por subtítulo; indica lo que el espectador debe notar y los resultados que la página muestra realmente.
- Prefiere
d.say()y luegod.read()antes de seguir; los subtítulos son también el guión de la narración. - Escribe los subtítulos en
LANGUAGE. Para un video silencioso, igual se leen en pantalla, así que mantenlos cortos. - Numera los clics (
await d.click(locator, '添加')) y marca solo lo que importa. - Reproduce las esperas largas rápidas (
await d.until(..., speed=4)) en lugar de cortarlas.
4. Grabar
$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 es un ensayo rápido: omite las pausas para el espectador y solo espera a la aplicación. Úsalo para detectar errores de selectores y de estado. Graba de verdad después; work/timeline.json se sobrescribe y los fotogramas antiguos se eliminan.
Antes de grabar, el script limpia solo frames y las rutas listadas en wipe, verifica que el puerto esté libre, inicia el comando del guión y espera a que la aplicación responda. El registro de la aplicación es work/server.log. En Windows, la aplicación y todo lo que inicia se detiene con taskkill /T; en otros lugares, se detiene todo el grupo de procesos.
5. Verificar y renderizar
$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 verifica, sin mirar imágenes: las regiones marcadas no están vacías y coinciden con los colores expect, las etiquetas no se superponen con el contenido de la página, los recuadros están dentro de la cámara, los pasos/clics son visibles, los subtítulos caben y los glifos existen en la fuente. Corrige el guión o el tiempo y graba de nuevo. El renderizado también compara fotogramas de salida muestreados con los fotogramas que dibujó y escribe work/render.json.
Si el usuario no quiere narración, el video silencioso es el entregable — detente aquí e informa.
6. Narrar (solo si se pidió)
$PY $S/scripts/demo_voice.py --work /tmp/demo-work # todos los pasos
$PY $S/scripts/demo_voice.py lines --work /tmp/demo-work # inspeccionar pronunciación/tiempo primero
Escribe el video narrado junto al silencioso: <name>-配音版.mp4 para mandarín, <name>-narrated.mp4 para los demás idiomas. Los pasos se pueden reanudar: clip de referencia → (Qwen: prueba) → tomas → verificación de voz/hablante → elegir/ajustar/mezclar → verificar. Lee references/narration.md para la configuración, correcciones de pronunciación y líneas ajustadas, y references/engines.md para los motores, sus voces, claves y costos. La check final debe decir 没有发现问题; cualquier línea 听写有出入 significa que la voz dijo algo diferente — corrige el subtítulo, añade una anulación say, vuelve a decir esa línea o elige otra voz.
7. Informar
Proporciona al usuario la ruta de salida (silenciosa y, si se pidió, narrada), la duración, la resolución/fps, el número de subtítulos/marcas, el motor de narración y voz, y el resultado de la verificación de la narración. Menciona cualquier advertencia 注意: que quede y nunca ocultes una verificación fallida.
Primeros pasos para solucionar problemas
缺 …→ ejecutapython3 scripts/demo_env.pyy sigue la línea→.- Puerto ya en uso → cambia
PORTen el guión; no detengas el servicio existente. 点不到这个元素→ el elemento está cubierto o fuera de pantalla; desplázate/amplía primero, o elige otro objetivo.- Desajuste de ancho de página → la página no es responsiva en
VIEW; ajustaVIEWo la página, mantén la proporción 64:31. - Línea de narración demasiado ajustada → acorta ese subtítulo o dale más tiempo, luego graba de nuevo.
Kokoro 的词表里没有这些词→ Kokoro omite esas palabras; agrégalas aVOICE['say']en la ortografía del subtítulo (ej. `