Communitygithub.com

josueh04/product-video-skills

Redacta la narración de un vídeo de producto y conviértela en clips de voz con temporizaciones de palabras, correcciones de pronunciación, efectos de sonido e incluso volumen. El guion se convierte en una tabla de momentos y luego en audio/lines.tsv (un clip por frase, con columnas de rol y velocidad); tts.py lo vocaliza con ElevenLabs o la voz gratuita de macOS say, asigna las reescrituras de marca a la ortografía en pantalla, normaliza cada clip y escribe audio/timings.json para el compositor; make_sfx.py construye pistas de escritura a partir de pulsaciones reales y coloca sonidos de clic y pop grabados. Úsalo siempre que un vídeo necesite un guion, narración, voz en off, lines.tsv, timings.json, TTS, una nueva toma, una elección de voz o reparto, una corrección de pronunciación ('dice mal el nombre'), una frase cambiada, una nota de tono ('demasiado exagerado', 'suena cortado'), niveles de audio, un clic al final de un clip, sonidos de escritura o clic, o cuando la fase de compilación pida la voz. También úsalo para bucles silenciosos, que aún necesitan una tabla de momentos y SFX.

¿Qué es product-video-skills?

Esta habilidad está diseñada para automatizar el flujo de trabajo de narración y efectos de sonido en la producción de vídeos de producto. Su función principal es tomar un guion escrito, convertirlo en una tabla de momentos que sincroniza la acción en pantalla con las frases, generar pistas de audio (clips de voz) mediante TTS (ElevenLabs o la voz gratuita de macOS 'say'), y producir metadatos como timings.json para el compositor del vídeo. También gestiona la corrección de pronunciación de nombres de marca, la normalización del volumen de los clips, y la creación de efectos de sonido realistas (como escritura o clics) a partir de grabaciones reales. La habilidad está optimizada para entornos de IA como Claude Code, Cursor o Codex, y trabaja con archivos como lines.tsv (lista de frases con roles y velocidades) y scripts Python (tts.py, make_sfx.py, pronounce_check.py). Es útil para evitar la edición manual del audio, garantizar que la voz y los efectos se ajusten perfectamente a la animación, y mantener consistencia en la pronunciación y el volumen. También incluye comprobaciones para evitar términos prohibidos y gestionar versiones de clips.

Compatible con✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/script-and-voice

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Guion y voz

La voz es el reloj del vídeo. Cada compás de la animación está anclado a una palabra de la narración (T[clip] + w(clip, "palabra") en build.py), por lo que el guion y sus clips vienen antes que la animación, y cambiar una frase regenera un clip y re-temporiza todo lo que le sigue. En la producción de la que provienen estas habilidades, intercambiar todo el motor TTS re-temporizó un vídeo terminado sin ediciones manuales gracias a ese diseño. Animar primero y ajustar la voz después significa estirar el audio o arrastrar los compases a mano en cada cambio.

Escribe solo dentro de <video_dir>/audio/ (más la sección de guion de BRIEF.md). Cada frase debe estar respaldada en TRUTH.md y respetar CLAIMS.md; si una frase que necesitas no tiene fuente, pide que se verifique o elimínala.

Guiones, llamados como en docs/contracts.md:

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/script-and-voice/scripts"
"$PVS_HOME/bin/pvs-py" "$S/check_script.py" <video_dir>                 # lint lines.tsv
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir> [--only N3,N4] [--provider say] [--force] [--restore]
"$PVS_HOME/bin/pvs-py" "$S/pronounce_check.py" <video_dir> [--only N3]  # ¿el ASR escuchó las palabras de marca?
"$PVS_HOME/bin/pvs-py" "$S/make_sfx.py" <video_dir> [--list]            # sfx.tsv, o lista la biblioteca

1. El guion es una tabla de momentos

Una grabación del producto es una referencia, no una línea de tiempo: las esperas de carga reales y los cambios de pantalla no pertenecen al vídeo. Escribe el guion como momentos, cada uno con lo que sucede en pantalla, la frase (o silencio) y cuánto dura. Un momento dura tanto como lo más largo entre su acción y su frase. Comprime las esperas reales: cuarenta segundos de carga se convierten en unos dos segundos de un estado de pensamiento.

Añade la tabla a BRIEF.md bajo ## Guion, en orden de capítulos:

MomentoEn pantallaLíneaTexto (o silencio)Mantiene
AperturaNombre del producto sobre la app desenfocadaN1Esta es Acme Tasks, la lista de tareas que planifica tu día.0.8 s después
EsperaEl plan se está construyendo(silencio)2.0 s

Luego elige la plantilla para el formato del vídeo y sigue su estructura: lee references/script-templates.md (presentación, recorrido, página de documentación, tutorial, bucle silencioso).

Cómo escribir las líneas, y por qué:

  • Explica las funciones importantes; no las enumeres. Di lo que una función hace por el espectador mientras la interfaz de usuario la ejecuta. En la producción de la que provienen estas habilidades, 9 de 26 versiones ocurrieron porque un vídeo nombraba una función sin explicarla. COVERAGE.md dice qué funciones deben explicarse en pantalla: cada fila marcada como "debe explicarse" necesita al menos una línea que la explique.
  • Explica cada paso a alguien que nunca haya visto el producto. Quién es el personaje, qué pide, qué hace cada paso. Una apertura rápida y sin explicación fue rechazada en la revisión.
  • Una idea por frase y una frase por clip. Una frase cambiada cuesta entonces un clip.
  • Nombra lo que el cursor toca mientras lo toca. Los compases se anclan a esas palabras, por lo que el sustantivo en pantalla y la palabra en el clip deben ser los mismos.
  • Usa la etiqueta real de la interfaz de usuario, incluso cuando el revisor use otra palabra para ello. El vídeo entonces coincide con lo que el espectador verá en el producto.
  • Escribe números y horas como palabras ("las diez de la mañana", "treinta minutos después"). Los motores TTS leen los dígitos de forma inconsistente y la comparación de voz a texto compara palabras, no dígitos.
  • Deja aire alrededor de las esperas. Unos tres segundos antes de que suene un teléfono, "aproximadamente un minuto" en lugar de un número preciso que nadie puede verificar.
  • Termina con una frase completa, leída un poco más despacio. Un fragmento de eslogan como última línea sonó cortado en la revisión; una frase completa con el posicionamiento de CLAIMS.md no lo hizo.
  • Mantén la persona consistente dentro de un vídeo: primera persona como el usuario ficticio ("Primero, conecto mi calendario.") o tercera persona sobre él. Usa solo el reparto ficticio de product.yaml, con el mismo nombre en cada vídeo.
  • El posicionamiento proviene de CLAIMS.md, no de los documentos fuente: un documento fuente puede contener una frase que el equipo ha prohibido, y la regla gana.

2. lines.tsv

audio/lines.tsv, separado por tabulaciones, encabezado id role speed text, un clip por fila en orden de reproducción, las líneas # son comentarios. Formato completo y cómo build.py lee el resultado: references/audio-formats.md.

  • id: N1, N2, N7b para narración; otras letras para personajes (A1 para un agente, C1 para un cliente). Insertar una línea entre N7 y N8 como N7b mantiene estables todos los demás ids y todos los anclajes que los usan.
  • role: una clave de voice.roles en product.yaml (narrator, agent, customer, o una variante de lectura como narrator_close, ver sección 3). El rol, no el id, elige la voz.
  • speed: 1.0 por defecto, de 0.7 a 1.2. Usa 0.9 a 0.96 para las líneas de apertura y cierre.
  • text: exactamente como aparece en pantalla y en los subtítulos, con la ortografía canónica de los nombres del producto. Nunca escribas una reescritura aquí; la pronunciación vive en product.yaml.

Antes de cambiar líneas de una versión entregada, copia lines.tsv a lines-v<N>.tsv y timings.json a timings-v<N>.json, para que la versión anterior pueda reconstruirse.

Ejecuta check_script.py después de cada edición. Fallará en ids duplicados, roles desconocidos, velocidades fuera de rango, clips de más de 40 palabras, términos prohibidos, frases de "nunca decir", nombres obsoletos y reescrituras en el guion, y advertirá sobre clips largos, dígitos y guiones. Corrige todos los errores antes de vocalizar: una frase prohibida que llegue al TTS cuesta una toma, y una que llegue a un render cuesta una versión.

3. Reparto

Lee references/casting-and-pronunciation.md antes de proponer voces. En resumen:

  • Ofrece primero voces realistas. La voz predeterminada del producto y los modelos más baratos fueron juzgados como "muy falsos" en la revisión; el modelo más natural disponible vale la pena para los personajes.
  • Audiciona en contexto: dos líneas reales consecutivas por rol, de tres a seis candidatos por rol.
  • Propón cada elección para veto como una pregunta cerrada con un valor predeterminado recomendado ("Narrador: voz B, cálida y sin prisas. ¿La mantenemos?"). Las listas abiertas de opciones quedaron sin respuesta durante días.
  • Decide el tratamiento por rol: treatment: phone para alguien en una llamada, treatment: room para una reunión grabada, nada para el narrador.
  • Una lectura por línea (más constante, más lenta, menos estilo) es una variante de rol que apunta a la misma voz con otros ajustes, por lo que la elección está en la configuración y sobrevive a una reejecución.

voice.provider: say (o --provider say) usa la voz gratuita de macOS y whisper para las temporizaciones de palabras. Úsalo para borradores, pruebas y trabajos de temporización antes de que exista una clave; entrega con la voz real.

4. Generar los clips

"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir>

Para cada línea, reescribe las palabras de marca solo para el TTS, mantiene la toma sin modificar en audio/raw/ (la toma anterior se mueve a audio/raw/prev/), recorta el silencio, remuestrea a 48 kHz mono, aplica el tratamiento del rol, normaliza a voice.clip_lufs (ffmpeg loudnorm, dos pasos; picos por debajo de -1.5 dBTP), funde ambos bordes y fusiona la entrada del clip en audio/timings.json.

Por qué existe cada paso de procesamiento:

  • Las tomas originales siempre se archivan y siempre son la fuente. Un cliente anterior normalizaba a partir de un archivo raw desactualizado después de un render completo; aquí un clip siempre se reconstruye a partir de la toma que lo produjo.
  • La cola se corta como máximo 0.6 s después de la última palabra, con un fundido. Una toma TTS puede terminar con un clic o el inicio de otra frase; uno de esos clics se envió como un "corte extraño" en el audio.
  • Todos los clips al mismo volumen. Una voz de personaje salió 6 dB más fuerte que el narrador antes de la normalización.
  • Las líneas sin cambios se omiten (hash del texto, voz y ajustes en audio/raw/cache.json), por lo que una ejecución completa después de editar una línea llama al proveedor una vez. Si solo cambian clip_lufs o el procesamiento, los clips se reconstruyen gratuitamente a partir de las tomas archivadas. --force solicita una nueva toma de todos modos.

La clave la lee el script del entorno o de PVS_HOME/.env y nunca se imprime. Nunca leas .env tú mismo ni pidas la clave en el chat: si falta, dile al usuario que añada la línea a .env él mismo, o cambie a say.

Ejecuta pronounce_check.py después de cualquier toma nueva. Transcribe cada clip sin indicar el ASR, marca las palabras de marca y del reparto que no fueron reconocidas, los nombres obsoletos que se escucharon y las vocales que se desviaron (sección 5). Una marca significa escuchar, no regenerar: los ASR malinterpretan palabras de marca que se dijeron correctamente.

5. Pronunciación

El guion y la pantalla mantienen la ortografía real. product.pronounce cambia solo lo que se envía al TTS, y tts.py asigna las temporizaciones de nuevo, por lo que timings.json contiene la palabra en pantalla en w y la reescritura en say ({"w": "Acme", "say": "AK-mee", ...}). Los anclajes en build.py usan la palabra en pantalla.

product:
  pronounce:
    Acme: AK-mee                                    # reescritura simple
    Acme Tasks: {say: AK-mee Tasks, vowel: ae, confusable: ey}   # con verificación de primera vocal

Cuando un revisor dice que el nombre suena mal, prueba tres o cuatro reescrituras en una línea, mídelas con la verificación de vocales, conserva la que pase, luego verifica cada otra línea que tenga la palabra: los proveedores varían por toma. Detalles y la tabla de vocales: references/casting-and-pronunciation.md.

6. Tomas

  • Como máximo dos tomas por línea a menos que el usuario indique lo contrario; las cuotas del proveedor suelen compartirse entre un equipo. Di cuántos caracteres costará una ejecución completa antes de ejecutarla.
  • Regenera solo la línea que lo necesita: tts.py <video_dir> --only N7 --force.
  • Si la nueva toma es peor, --only N7 --restore la intercambia de nuevo con sus temporizaciones.
  • Para una nota de tono ("demasiado exagerado", "suena como media frase"), haz dos o tres variantes como variantes de rol o cambios de velocidad, y deja que el revisor las compare en contexto con la línea anterior.
  • Cambiar una línea, en orden: copia los archivos de la versión, edita la fila, check_script.py, tts.py --only <id>, pronounce_check.py --only <id>, luego el compositor reconstruye; todo lo que sigue a ese clip se mueve solo.

7. Efectos de sonido

Usa solo sonidos grabados, de la biblioteca que viene con HyperFrames (make_sfx.py --list). La escritura sintetizada sonaba "como una pajita, no un teclado" y un silbido sintetizado como "ruido blanco" en la revisión, por lo que el script rechaza silbidos y crescendos, y nada se coloca debajo de la narración como música a menos que el briefing lo solicite. La producción de la que provienen estas habilidades se envió sin cama musical ni ducking, y nadie lo echó de menos.

  • Escritura: typing_track(text, start, cps) construye una pista a partir de pulsaciones individuales extraídas de una grabación real, con un golpe más fuerte en los espacios y un ritmo sembrado, por lo que es determinista y el mismo texto siempre suena igual. Haz que dure exactamente tanto como el compás que muestra el texto (dur=), y deja que las palabras escritas coincidan con las habladas.
  • Clics y pops: library_sfx("click", start) en el fotograma en el que el cursor presiona.
  • audio/sfx/CREDITS.md enumera cada archivo de biblioteca utilizado y lleva la licencia de la biblioteca.
  • Niveles sugeridos: narración 1.0, personajes 1.0, clics 0.35 (0.22 en una liberación de arrastre), escritura 0.45, pops 0.12 a 0.3. Dos clips en la misma pista de audio nunca deben superponerse: comienza un clip al menos 0.02 s después de que termine el anterior, o muévelo a otra pista.

build.py importa las funciones; make_sfx.py <video_dir> con un audio/sfx.tsv preconstruye los mismos archivos desde la línea de comandos (formato en el docstring del script).

8. Entrega al compositor

Entrega, dentro de <video_dir>/audio/: lines.tsv, clips/<id>.wav, timings.json, y sfx/ con CREDITS.md. Dile al compositor a qué palabras debe anclar cada compás (el sustantivo que el cursor toca, la palabra en la que aterriza la escritura) y las esperas de la tabla de momentos. Nunca edites timings.json a mano: se regenera a partir de los clips, y una edición manual se pierde en la siguiente ejecución.

Informa al usuario: las líneas vocalizadas, la duración de cada clip, cualquier marca de pronunciación y lo que escuchaste, las voces utilizadas (con el valor predeterminado recomendado para cualquier cosa que aún esté abierta) y los caracteres del proveedor gastados.

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

josueh04/product-video-skills

The animation rules that keep HyperFrames' parallel render workers from dropping, flashing or flickering elements, plus a static lint (lint_motion.py) that finds the violations in a video's template before it costs a render. Use it whenever you write or edit GSAP tweens, timelines, cursors, camera moves, typing, scrolls or pop-ups in a HyperFrames composition or a video's src/template.tpl, whenever a render shows flicker, stutter, an element that vanishes on some frames, a title that flashes, or a "WORKER PATTERN" line from scan_render.py or qa.py, and whenever the preview looks right but the MP4 does not. Also use it to review someone else's timeline code before rendering.

josueh04/product-video-skills

Pin a product's source code (read-only exports in sources/ plus sources.lock), confirm that the pinned commit is what runs in production, and map every screen of a video brief to its route, components, i18n strings and state, written to the video's SOURCES.md. Use it whenever a video needs to know where a screen lives in the code, when sources/ is missing or stale, before ui-spec-from-code or product-truth start on a video, after the product's frontend changed ("what changed", "which videos are affected", "refresh the sources", "is this checkout current", "which commit is in prod"), and when there is no code and you need an inventory of the no-code references (recordings, recovered captures, docs) a screen can be rebuilt from.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Gather pixel references for UI that the code cannot show, or to check a rebuild against the real thing, using frames and timed OCR text from screen recordings, captures recovered from past Claude Code session transcripts, a local instance of the app built like production, and web research for third-party apps, plus side-by-side parity images and contact sheets. Use it whenever someone hands over a screen recording (.mov or .mp4) of the product, when a screen has no usable source code (a stale checkout, another company's UI such as a sign-in page, calendar or CRM, runtime output from a backend not in the repos), when asked "what does it really look like", "match the recording", "how long does that animation take in the app", "compare our render to the real app", or when screenshots from an earlier session might already exist. Never uses the reviewer's personal browser.

josueh04/product-video-skills

Turn a product's real frontend code into 1:1 rebuild specs for a video, one read-only subagent per screen, each returning static HTML, CSS with every variable resolved to its literal value and cited (role/path:line@sha), every state, transitions with exact durations and easings, icons from the code's own icon sets, and the exact i18n strings; plus resolve_tokens.py to write the product's design tokens to kit/tokens.css. Use it whenever a screen of the product has to appear in a video, when writing or fixing video/src/app.css or the template markup, when someone asks for exact sizes, colors, fonts, paddings, animations or icons of a screen, when a rebuilt screen "looks off" next to the real app, and when the design tokens or theme of a product need extracting. Framework adapters cover Angular with PrimeNG (proven), React, Vue, Tailwind and plain HTML (unproven).

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

Skills relacionados