Preprocesamiento de Medios HyperFrames
Tres comandos CLI que producen activos para composiciones: tts (voz), transcribe (marcas de tiempo) y remove-background (video transparente). Cada uno descarga un modelo en la primera ejecución y lo almacena en caché en ~/.cache/hyperframes/. Coloque la salida en el proyecto y luego haga referencia a ella desde el HTML de la composición; consulte la habilidad hyperframes para conocer las convenciones de elementos de audio/video.
Texto a Voz (tts)
Genere audio de narración localmente con Kokoro-82M. Sin clave API.
npx hyperframes tts "Texto aquí" --voice af_nova --output narracion.wav
npx hyperframes tts script.txt --voice bf_emma --output narracion.wav
npx hyperframes tts --list # las 54 voces
Selección de Voz
Haga coincidir la voz con el contenido. El valor predeterminado es af_heart.
| Tipo de contenido | Voz | Por qué |
|---|---|---|
| Demostración de producto | af_heart/af_nova | Cálida, profesional |
| Tutorial / Guía | am_adam/bf_emma | Neutral, fácil de seguir |
| Marketing / Promoción | af_sky/am_michael | Enérgica o autoritaria |
| Documentación | bf_emma/bm_george | Inglés británico claro, formal |
| Casual / Social | 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 necesita --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
Use --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 en idiomas distintos al inglés requiere espeak-ng en todo el sistema (brew install espeak-ng / apt-get install espeak-ng).
Velocidad
0.7-0.8— tutorial, contenido complejo, accesibilidad1.0— ritmo natural (predeterminado)1.1-1.2— introducciones, transiciones, contenido dinámico1.5+— raramente apropiado; probar con cuidado
Guiones Largos
Para más de unos pocos párrafos, escriba en un archivo .txt y pase 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)
Produzca un 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 use 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 audio no inglés a 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 e inglés →
--model small.en - Idioma desconocido →
--model small(sin.en, sin--language) — whisper lo detecta automáticamente
El modelo predeterminado es small, no small.en.
Tamaños de Modelo
| Modelo | Tamaño | Velocidad | Cuándo usarlo |
|---|---|---|---|
tiny | 75 MB | Más rápido | Vista previa rápida, prueba de pipeline |
base | 142 MB | Rápido | Clips cortos, audio claro |
small | 466 MB | Moderado | Predeterminado — la mayoría del contenido |
medium | 1.5 GB | Lento | Contenido importante, audio ruidoso, música |
large-v3 | 3.1 GB | Más lento | Calidad de producción |
Música con voces: comience con medium como mínimo; las pistas producidas a menudo necesitan importación manual de SRT/VTT. Para comprobaciones de calidad de subtítulos (obligatorias después de cada transcripción), el JS de limpieza, las reglas de reintento y la ruta de importación de la API OpenAI/Groq, consulte hyperframes/references/transcript-guide.md.
Forma de Salida
Las composiciones consumen un array plano de objetos de palabras. El campo id (w0, w1, ...) se agrega durante la normalización para referencias estables en anulaciones de subtítulos; es opcional para retrocompatibilidad.
[
{ "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)
Elimine el fondo de un video o imagen para que el sujeto (generalmente una persona — avatar, presentador, cabeza parlante) se coloque como una superposición transparente en una composición.
npx hyperframes remove-background subject.mp4 -o transparente.webm # predeterminado: VP9 alpha WebM
npx hyperframes remove-background subject.mp4 -o transparente.mov # ProRes 4444 (edición)
npx hyperframes remove-background portrait.jpg -o recorte.png # recorte de una sola imagen
npx hyperframes remove-background subject.mp4 -o subject.webm \
--background-output plato.webm # ambas capas en un solo pase
npx hyperframes remove-background subject.mp4 -o transparente.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/.
Separación de Capas (--background-output)
Pase --background-output (o -b) para emitir un segundo video transparente junto con el recorte: mismo RGB de origen, alfa es 255 − máscara en lugar de máscara. El recorte es el sujeto con fondo transparente; el plato es el entorno original con un agujero transparente donde estaba el sujeto.
| Archivo | Alfa es… | Úselo para |
|---|---|---|
-o subject.webm | La máscara — sujeto opaco, fondo transparente | Capa frontal, colóquela encima |
--background-output plato.webm | Inversa — el entorno opaco, la región del sujeto transparente | Capa inferior; coloque texto o gráficos entre esta y el sujeto |
Ambas salidas comparten el mismo preajuste --quality y se ejecutan desde una sola inferencia: el costo de codificación se duplica aproximadamente, el costo de segmentación sigue siendo el mismo. Solo es válido para entradas de video y salidas .webm/.mov.
Plato con agujero, no un plato limpio con relleno. La región del sujeto en plato.webm es completamente transparente — componga algo opaco debajo para llenar el agujero. La única prueba para saber si --background-output es la herramienta correcta: ¿alguna vez se verá algo a través de la silueta del sujeto donde solía estar el sujeto?
| Caso de uso | Herramienta correcta |
|---|---|
| Texto/gráficos entre el recorte y el plato (la razón de existir de este comando) | Agujero (--background-output) |
| Sujeto sobre una escena no relacionada | Solo subject.webm; ignore el plato |
| Mostrar la sala sin la persona, sola sin otro contenido | Plato limpio — necesita un inpainter (LaMa, ProPainter, E2FGVI). No es este comando. |
| Reemplazar el sujeto con un sujeto diferente | Plato limpio — igual que arriba |
Si un usuario solicita "la sala sin la persona" y tiene la intención de mostrarla de forma independiente, no use --background-output. Dígale que necesita un inpainter.
Composición típica en capas (el caso de uso canónico de agujero):
<!-- z=1 el plato con alfa inversa llena todo excepto la región del sujeto -->
<video
src="plato.webm"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<!-- z=2 los gráficos/texto viven entre las dos capas -->
<h1 id="headline" style="z-index:2; ...">HÁGALO EN HYPERFRAMES</h1>
<!-- z=3 el recorte coloca el sujeto sobre el título -->
<div class="envoltura-recorte" style="position:absolute;inset:0;z-index:3">
<video
src="subject.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
Esto es funcionalmente equivalente al patrón de texto detrás del sujeto a continuación, pero no necesita el presenter.mp4 original en el proyecto — el plato lo reemplaza. Útil cuando desea enviar solo las dos capas transparentes y permitir que el usuario coloque contenido arbitrario entre ellas.
Formato de Salida
| Formato | Cuándo |
|---|---|
.webm (VP9 + alpha) | Predeterminado. Las composiciones lo reproducen directamente mediante <video>. |
.mov (ProRes 4444) | Edición en DaVinci/Premiere/FCP. Archivos grandes. |
.png | Recorte de una sola imagen (sujeto estático, superpuesto sobre un fondo). |
Chrome decodifica VP9 alpha de forma nativa, por lo que .webm se integra en una composición como cualquier otro video con reproducción automática silenciada; consulte la habilidad hyperframes para conocer las convenciones de pista <video>.
Preajustes de Calidad
--quality fast|balanced|best controla solo el CRF del codificador VP9; la calidad de segmentación es fija.
| Preajuste | CRF | Cuándo |
|---|---|---|
fast | 30 | Iteración, archivo más pequeño, coincidencia de color menos estricta |
balanced | 18 | Predeterminado. Visualmente idéntico para la mayoría de los usos |
best | 12 | Maestro / entrega final. Archivo más grande, coincidencia más precisa |
Patrones de Composición — elija el correcto
El webm recortado es una copia recodificada del RGB del mp4 de origen. Esa elección tiene consecuencias dependiendo de lo que coloque detrás:
| Patrón | Qué hay detrás del recorte | Resultado |
|---|---|---|
| Recorte sobre una escena diferente (más común) | Imagen estática, degradado o video no relacionado | Se ve genial. El RGB del recorte es la única fuente del sujeto: sin duplicación, sin halo en los bordes. Para esto está hecho remove-background. |
| Recorte sobre su propio mp4 de origen (texto detrás del sujeto) | El mismo mp4 del que se generó el recorte | Dos fuentes RGB para la misma persona. Con --quality balanced predeterminado (crf 18), la duplicación es apenas visible; con --quality fast (crf 30) verá un sutil cambio de color/halo en los bordes. Use --quality best (crf 12) para masters. |
| Recorte sobre una toma diferente de la misma persona | Metraje del mismo sujeto | Se verá como dos personas separadas superpuestas. No haga esto. |
Texto detrás del sujeto (título detrás de un presentador):
<video
src="presentador.mp4"
id="bg"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<h1 id="headline" style="z-index:2; ...">HÁGALO EN HYPERFRAMES</h1>
<div class="envoltura-recorte" style="position:absolute;inset:0;z-index:3;opacity:0">
<video
src="presentador.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
Dos reglas clave:
- Envuelva el video recortado en un
<div>sin temporización y anime la opacidad del envoltorio, no la del elemento de video. El framework fuerza opacidad:1 en clips activos (cualquier elemento condata-start/data-duration), por lo que animar la opacidad del video directamente se anula silenciosamente. El envoltorio no tiene atributosdata-*, por lo que es propiedad de su CSS/GSAP. - Ambos videos usan
data-start="0"ydata-media-start="0"para que el framework los descodifique sincronizados desde t=0. Montar tardíamente el recorte (data-start=3.3) introduce una búsqueda + calentamiento que termina fuera de sincronía con el mp4 base, visible como un fotograma de desalineación en el corte.
Luego, GSAP cambie la opacidad del envoltorio en el corte: tl.set(envolturaRecorte, { opacity: 1 }, 3.3).
TTS → Transcribir → Subtítulos
Cuando no haya una locución pregrabada, genere una y transcríbala para obtener marcas de tiempo a nivel de palabra para los subtítulos:
npx hyperframes tts script.txt --voice af_heart --output narracion.wav
npx hyperframes transcribe narracion.wav # → transcript.json
npx hyperframes transcribe subtitles.srt # importe subtítulos existentes
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json