talking-clip (clip parlante)

¿Qué hace talking-clip (clip parlante)?

Un clip tiene cuatro pasos: escribir la línea, generar la voz, planificar la actuación, construir y renderizar. Salida: un proyecto HyperFrames y un mp4 (vertical 1080x1920 por defecto).

1. línea   la escribes tú, con la voz del personaje
2. voz     scripts/tts.py          (ElevenLabs gasta créditos; say y none son gratuitos)
3. plan    tú escribes plan.json     (gestos y expresiones sobre las palabras)
4. video   scripts/build_clip.py -> scripts/verify.py -> scripts/render.py

Las rutas son relativas a la raíz de este paquete: la carpeta que contiene .claude-plugin/, dos niveles por encima de este archivo (resolver enlaces simbólicos primero). Requiere las skills públicas de HyperFrames (hyperframes, hyperframes-cli): lee hyperframes una vez antes de editar cualquier composición a mano.

0. Verificación previa (siempre primero)

Ejecuta python3 scripts/setup.py doctor (añade --json para analizar la salida). Enumera cada dependencia, para qué sirve y el comando exacto de instalación para esta máquina; termina con código 1 cuando falta algún elemento requerido.

• Requerido faltante (ffmpeg, Node.js 18+, las skills de HyperFrames y la clave de ElevenLabs o say cuando esa voz está configurada): dile al usuario en una línea para qué sirve cada uno y propón el comando impreso. Ejecútalo solo después de que el usuario diga que sí. Nunca escribas ni pidas una clave API tú mismo: dile al usuario que exporte ELEVENLABS_API_KEY en su shell.
• Opcional faltante: ofrécelos una vez y di qué desbloquea cada uno. Playwright permite capturas web con zoom de elementos y capturas de página completa, tesseract (OCR) proporciona el escaneo de secretos en capturas de pantalla, y ASR (mlx-whisper / openai-whisper) proporciona la verificación de audio y los tiempos exactos de las palabras. Omítelos si el usuario los rechaza; las comprobaciones correspondientes se convierten entonces en pasos de review manuales.
• Skills de HyperFrames (hyperframes, hyperframes-cli, hyperframes-registry, media-use): si faltan, recomienda npx hyperframes skills. Lee hyperframes (y hyperframes-cli para problemas de renderizado) antes de construir o editar cualquier composición.

Configuración (primera ejecución, o cuando el usuario quiera cambiar algo)

Busca una configuración: python3 scripts/setup.py show. Si no hay ninguna, o el usuario pide cambiar su personaje, voz, renderizado o estilos, haz una entrevista (una pregunta corta a la vez, ofreciendo el valor por defecto) y luego escríbelo con flags:

Pregunta	Flag	Opciones
¿Qué partes?	--features	character, explainer o ambas
¿Qué personaje?	--character	el ejemplo incluido (pkg:characters/host/character.json) o una ruta al suyo (almacenada absoluta)
Idioma de narración	--language	código ISO; con say se elige una voz clara para él (setup.py voices --lang <code> las lista, --say-voice invalida)
¿Qué voz?	--voice	elevenlabs (su clave en ELEVENLABS_API_KEY, su --voice-id), say (macOS, gratuito), none
Límites de crédito (ElevenLabs)	--max-chars, --max-seconds, --daily-credit-cap	números que elijan; vacío = sin límite
¿Cómo renderizar?	--render	local (gratuito, esta máquina), cloud (nube de HyperFrames, necesita npx hyperframes auth login), preview (solo Studio)
Tamaño	--size	1080x1920, 1920x1080, 1080x1080

python3 scripts/setup.py init --features character --voice say --render local --yes

init ejecuta primero el doctor y ofrece las mismas instalaciones. Si ya existe una configuración, pregunta antes de sobrescribir, o necesita --force cuando no es interactivo.

Su propio personaje: python3 scripts/setup.py new-character --name "<nombre>" --out ./characters/<nombre> --activate copia el ejemplo y lo activa (sin un segundo init). Luego ayúdales a rellenar las claves que imprime: description, personality, speaking_style.rules, rig.colors (o sprites), expressions / poses / gestures, set, voice_moods.

Nunca pidas, imprimas ni escribas la clave API. Si falta ELEVENLABS_API_KEY, dile al usuario que la exporte en su shell. El esquema de configuración está en config/config.schema.json; el formato del archivo de personaje está en el README ("Tu propio personaje").

Elige un estilo para este clip

No hay un aspecto predeterminado. Para cada clip, elige el estilo según el tema, la audiencia y la marca o gusto del usuario: el escenario ({"type": "color"|"gradient"|"image", ...}), el encuadre (close, medium, wide) y la intensidad de movimiento (calm, normal, lively). Pregunta al usuario cuando la elección sea importante, por ejemplo cuando el clip sea para una marca, un canal público o una serie. Varía el estilo entre clips en lugar de repetir el último. Si la configuración tiene un kit de brand, su background tiene prioridad sobre tu elección. Escríbelo en un archivo y pasa --style:

{"set": {"type": "gradient", "colors": ["#FFF4E6", "#FFD9B3"]}, "framing": "medium", "motion": "lively"}

Lo mismo aplica a las palabras: adapta el tono a la audiencia dentro de la personalidad del personaje y no reutilices la misma frase de apertura o cierre de un clip al siguiente.

1. Escribe la línea

Lee el archivo del personaje indicado en la configuración (clave character): personality y speaking_style.rules son la voz. Síguelos; la solicitud del usuario tiene prioridad cuando entren en conflicto.

• Longitud: como máximo styles.talking_clip.max_seconds. Con speaking_style.chars_per_second (aproximadamente 14), un clip de 20 s tiene menos de ~260 caracteres. Una idea, una línea de cierre.
• Idioma: el del usuario, a menos que pida otro.
• Los modelos de ElevenLabs con etiquetas de audio (v3 y posteriores) aceptan etiquetas de emoción en inglés entre corchetes antes de las palabras que colorean: [excited], [calm], [whispers], [laughs], [pause]. say y none las ignoran (se eliminan); actúa con gestos en su lugar.

2. Genera la voz

python3 scripts/tts.py estimate --text "<línea>" --max-seconds 20
python3 scripts/tts.py speak --text "<línea>" --out out/voice.wav [--mood excited] [--confirm]

• ElevenLabs: ejecuta siempre estimate primero y dile al usuario el costo; speak se niega sin --confirm, y se niega cuando se superaría un límite establecido por el usuario (máx. caracteres, máx. segundos, tope diario de crédito). --takes 2 crea alternativas. Los tiempos de las palabras se guardan en out/voice.wav.words.json.
• --mood elige un estado de ánimo de los voice_moods del personaje (configuración de ElevenLabs + filtro ffmpeg opcional).
• say / none: gratuito. Con none no hay audio; pasa --text al constructor en su lugar.

3. Planifica la actuación

python3 scripts/timings.py out/voice.wav --text "<línea>" da los tiempos de inicio de las palabras. Escribe 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"}]}

• Los identificadores de gesture y expression provienen del archivo del personaje (gestures, expressions); cada gesto tiene una descripción y un dur típico. Léelos antes de planificar.
• Movimiento de boca, parpadeos, respiración y balanceo de reposo son automáticos. Solo colocas los golpes de actuación.
• Coloca un gesto fuerte 0.2-0.3 s antes de la palabra con la que va. Una reacción por golpe; nunca dos gestos en el mismo segundo. Termina con un gesto calmado y sostenido (se mantiene automáticamente hasta el final).

4. Construye, verifica, renderiza

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 "<línea>" --video out/clip.mp4

La verificación es obligatoria (detalles en la sección "Verificar" de la skill explainer, mismo bucle): build debe estar limpio, render produce una hoja de contacto que debes revisar (boca moviéndose, gestos donde se planearon, nada cortado), audio comprueba las palabras con ASR y el límite de duración. Corrige y vuelve a ejecutar desde la etapa fallida. Cada ejecución de verify.py all es una iteración; en verify.max_iterations termina con código 2 y le dices al usuario qué sigue fallando en lugar de enviarlo. render permanece como review hasta que revises la hoja de contacto y la registres con verify.py mark render pass|fail --project out/clip --note "...", luego ejecuta verify.py all de nuevo (una reconstrucción invalida la marca).

Luego renderiza la versión final con el backend configurado: python3 scripts/render.py out/clip --out out/clip.mp4 (render.max_mb reconvierte para ajustarse a un límite de subida). Nunca subas archivos mp4 ni wav.