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:
| Momento | En pantalla | Línea | Texto (o silencio) | Mantiene |
|---|---|---|---|---|
| Apertura | Nombre del producto sobre la app desenfocada | N1 | Esta es Acme Tasks, la lista de tareas que planifica tu día. | 0.8 s después |
| Espera | El 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,N7bpara narración; otras letras para personajes (A1para un agente,C1para un cliente). Insertar una línea entre N7 y N8 comoN7bmantiene estables todos los demás ids y todos los anclajes que los usan. - role: una clave de
voice.rolesen product.yaml (narrator,agent,customer, o una variante de lectura comonarrator_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: phonepara alguien en una llamada,treatment: roompara 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 cambianclip_lufso el procesamiento, los clips se reconstruyen gratuitamente a partir de las tomas archivadas.--forcesolicita 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 --restorela 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.mdenumera 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.