Preprocesamiento de medios para HyperFrames
Tres comandos CLI que producen activos para composiciones: tts (voz), transcribe (marcas de tiempo) y remove-background (vídeo transparente). Cada uno descarga un modelo en la primera ejecución y lo almacena en caché en ~/.cache/hyperframes/. Coloca el resultado en el proyecto y luego haz referencia a él desde el HTML de la composición; consulta el skill hyperframes para conocer las convenciones de elementos de audio/vídeo.
Texto a voz (tts)
Genera audio de voz localmente con Kokoro-82M. No necesita clave API.
npx hyperframes tts "Texto aquí" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list # todas las 54 voces
Selección de voz
Elige la voz según el contenido. La voz por defecto es af_heart.
| Tipo de contenido | Voz | Motivo |
|---|---|---|
| Demostración de producto | af_heart/af_nova | Cálida y profesional |
| Tutorial / guía | am_adam/bf_emma | Neutra, fácil de seguir |
| Marketing / promocional | af_sky/am_michael | Enérgica o autoritaria |
| Documentación | bf_emma/bm_george | Inglés británico claro, formal |
| Casual / redes | af_heart/af_sky | Accesible, natural |
Multilingüe
Los IDs de voz codifican el idioma en la primera letra: a=inglés americano, b=inglés británico, e=español, f=francés, h=hindi, i=italiano, j=japonés, p=portugués brasileño, z=mandarín. La CLI detecta automáticamente la configuración regional del fonetizador a partir del prefijo; no necesitas --lang cuando la voz coincide con el texto.
npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav
Usa --lang solo para anular la detección automática (acentos estilizados). Códigos válidos: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh. La fonetización para idiomas no ingleses requiere tener espeak-ng instalado en el sistema (brew install espeak-ng / apt-get install espeak-ng).
Velocidad
0.7-0.8— tutorial, contenido complejo, accesibilidad1.0— ritmo natural (por defecto)1.1-1.2— intros, transiciones, contenido dinámico1.5+— raramente apropiado; probar con cuidado
Guiones largos
Para más de unos pocos párrafos, escribe el texto en un archivo .txt y pasa la ruta. Las entradas de más de ~5 minutos de voz pueden beneficiarse de dividirse en segmentos.
Requisitos
Python 3.8+ con kokoro-onnx y soundfile (pip install kokoro-onnx soundfile). El modelo se descarga en el primer uso (~311 MB + ~27 MB de voces, almacenado en caché en ~/.cache/hyperframes/tts/).
Transcripción (transcribe)
Produce un archivo transcript.json normalizado con marcas de tiempo a nivel de palabra.
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt # importar existente
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
Regla de idioma (no negociable)
Nunca uses modelos .en a menos que el usuario indique explícitamente que el audio está en inglés. Los modelos .en (small.en, medium.en) traducen el audio no inglés al inglés en lugar de transcribirlo. Esto destruye silenciosamente el idioma original.
- Idioma conocido y no inglés →
--model small --language <código>(sin sufijo.en) - Idioma conocido y inglés →
--model small.en - Idioma desconocido →
--model small(sin.en, sin--language) — Whisper detecta automáticamente
El modelo por defecto es small, no small.en.
Tamaños de modelo
| Modelo | Tamaño | Velocidad | Cuándo usarlo |
|---|---|---|---|
tiny | 75 MB | Más rápido | Vistas previas rápidas, pruebas |
base | 142 MB | Rápido | Clips cortos, audio claro |
small | 466 MB | Moderada | Por defecto — la mayoría del contenido |
medium | 1.5 GB | Lenta | Contenido importante, audio ruidoso, música |
large-v3 | 3.1 GB | Más lenta | Calidad de producción |
Música con voces: empezar con medium como mínimo; las pistas producidas a menudo necesitan importación manual de SRT/VTT. Para controles de calidad de subtítulos (obligatorios después de cada transcripción), el JS de limpieza, las reglas de reintento y la ruta de importación de la API de OpenAI/Groq, consulta hyperframes/references/transcript-guide.md.
Formato de salida
Las composiciones consumen un arreglo plano de objetos de palabra. El campo id (w0, w1, ...) se añade durante la normalización para referencias estables en las anulaciones de subtítulos; es opcional para compatibilidad hacia atrás.
[
{ "id": "w0", "text": "Hola", "start": 0.0, "end": 0.5 },
{ "id": "w1", "text": "mundo.", "start": 0.6, "end": 1.2 }
]
Eliminación de fondo (remove-background)
Elimina el fondo de un vídeo o imagen para que pueda usarse como superposición transparente en una composición (por ejemplo, un avatar flotando sobre un fondo).
npx hyperframes remove-background avatar.mp4 -o transparent.webm # por defecto: VP9 con alfa en WebM
npx hyperframes remove-background avatar.mp4 -o transparent.mov # ProRes 4444 (edición)
npx hyperframes remove-background portrait.jpg -o cutout.png # recorte de imagen única
npx hyperframes remove-background avatar.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # proveedores detectados
Usa u2net_human_seg (MIT). La primera ejecución descarga ~168 MB de pesos a ~/.cache/hyperframes/background-removal/models/.
Formato de salida
| Formato | Cuándo usarlo |
|---|---|
.webm (VP9 + alfa) | Por defecto. Las composiciones lo reproducen directamente con <video>. |
.mov (ProRes 4444) | Edición en DaVinci/Premiere/FCP. Archivos grandes. |
.png | Recorte de imagen única (sujeto estático, superpuesto sobre un fondo). |
Chrome decodifica el alfa VP9 de forma nativa, por lo que el .webm se integra en una composición como cualquier otro vídeo con reproducción automática silenciada; consulta el skill hyperframes para conocer las convenciones de pistas <video>.
TTS → Transcribir → Subtítulos
Cuando no hay una locución pregrabada, genera una y transcríbela para obtener marcas de tiempo a nivel de palabra para los subtítulos:
npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav # → transcript.json
Whisper extrae límites de palabra precisos del audio generado, por lo que la sincronización de los subtítulos coincide con la locución sin necesidad de ajuste manual.