Communitygithub.com

shinyobjectz/reactable

Preprocesamiento de activos para composiciones HyperFrames: narración de texto a voz (Kokoro), transcripción de audio/video (Whisper) y eliminación de fondo para superposiciones transparentes (u2net).

¿Qué es reactable?

Este skill proporciona tres comandos CLI (tts, transcribe, remove-background) para generar activos multimedia listos para usar en composiciones HyperFrames. El comando `tts` convierte texto en voz utilizando el modelo Kokoro-82M (sin necesidad de API keys), soportando 54 voces y múltiples idiomas. `transcribe` produce un `transcript.json` con marcas de tiempo a nivel de palabra usando Whisper de OpenAI, con advertencias sobre el uso de modelos `.en` que traducen silenciosamente audio no inglés. `remove-background` elimina fondos de videos e imágenes usando u2net_human_seg, generando superposiciones transparentes (WebM con alfa o ProRes 4444) que se integran directamente como capas superiores en composiciones. Cada comando descarga su modelo en la primera ejecución y lo cachea en `~/.cache/hyperframes/`. Está diseñado para desarrolladores que usan el framework HyperFrames, facilitando la creación de voiceovers, subtítulos y presentadores recortados sin depender de servicios cloud.

Compatible con~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shinyobjectz/reactable/tree/HEAD/skill/vendored/hyperframes-media

Preguntar en tu IA favorita

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

Vista previa

Del README del skill

Documentación

Preprocesamiento Multimedia HyperFrames

Tres comandos CLI que generan 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 cachea en ~/.cache/hyperframes/. Coloca la salida en el proyecto y luego refiérela desde el HTML de la composición — consulta el skill hyperframes para las convenciones de elementos de audio/video.

Texto a Voz (tts)

Genera audio de voz localmente con Kokoro-82M. Sin clave API.

npx hyperframes tts "Texto aquí" --voice af_nova --output narración.wav
npx hyperframes tts script.txt --voice bf_emma --output narración.wav
npx hyperframes tts --list                       # todas las 54 voces

Selección de Voz

Elige la voz según el contenido. El valor predeterminado es af_heart.

Tipo de contenidoVozPor qué
Demostraciónaf_heart/af_novaCálida, profesional
Tutorial / guíaam_adam/bf_emmaNeutra, fácil de seguir
Marketing / promosaf_sky/am_michaelEnérgica o autoritaria
Documentaciónbf_emma/bm_georgeInglés británico claro, formal
Casual / socialaf_heart/af_skyAccesible, 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. El CLI detecta automáticamente la configuración regional del fonetizador a partir del prefijo — no se 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

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 en idiomas no ingleses requiere espeak-ng a nivel de sistema (brew install espeak-ng / apt-get install espeak-ng).

Velocidad

  • 0.7-0.8 — tutoriales, contenido complejo, accesibilidad
  • 1.0 — ritmo natural (predeterminado)
  • 1.1-1.2 — intros, transiciones, contenido dinámico
  • 1.5+ — rara vez apropiado; probar con cuidado

Scripts Largos

Para más de unos pocos párrafos, escribe 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, cacheado en ~/.cache/hyperframes/tts/).

Transcripción (transcribe)

Genera 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 (Innegociable)

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 audio no inglés a inglés en lugar de transcribirlo. Esto destruye silenciosamente el idioma original.

  1. Idioma conocido y no inglés → --model small --language <código> (sin sufijo .en)
  2. Idioma conocido e inglés → --model small.en
  3. Idioma desconocido → --model small (sin .en, sin --language) — Whisper detecta automáticamente

El modelo predeterminado es small, no small.en.

Tamaños de Modelo

ModeloTamañoVelocidadCuándo usarlo
tiny75 MBMás rápidoVistas previas rápidas, pruebas de pipeline
base142 MBRápidoClips cortos, audio claro
small466 MBModeradoPredeterminado — la mayoría del contenido
medium1.5 GBLentoContenido importante, audio ruidoso, música
large-v33.1 GBMás lentoCalidad de producción

Música con voces: empezar como mínimo en medium; las pistas producidas a menudo necesitan importación manual de SRT/VTT. Para verificaciones de calidad de subtítulos (obligatorias después de cada transcripción), el JS de limpieza, reglas de reintento y la ruta de importación de API 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 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)

Elimina el fondo de un video o imagen para que el sujeto (típicamente una persona — avatar, presentador, cabeza parlante) se sitúe como superposición transparente en una composición.

npx hyperframes remove-background sujeto.mp4 -o transparente.webm  # predeterminado: WebM con alfa VP9
npx hyperframes remove-background sujeto.mp4 -o transparente.mov   # ProRes 4444 (edición)
npx hyperframes remove-background retrato.jpg -o recorte.png       # recorte de imagen única
npx hyperframes remove-background sujeto.mp4 -o sujeto.webm \
  --background-output placa.webm                                   # ambas capas en una pasada
npx hyperframes remove-background sujeto.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)

Usa --background-output (o -b) para generar un segundo video transparente junto al recorte: mismo RGB de origen, el alfa es 255 − máscara en lugar de máscara. El recorte es el sujeto con fondo transparente; la placa es el entorno original con un agujero transparente donde estaba el sujeto.

ArchivoAlfa es…Úsalo para
-o sujeto.webmLa máscara — sujeto opaco, fondo transparenteCapa frontal, colocar encima
--background-output placa.webmInverso — entorno opaco, región del sujeto transparenteCapa inferior; coloca texto o gráficos entre esta y el sujeto

Ambas salidas comparten el mismo preset --quality y se ejecutan en una sola pasada de segmentación — el costo de codificación se duplica aproximadamente, el costo de segmentación se mantiene igual. Solo válido para entradas de video y salidas .webm/.mov.

Placa con agujero, no una placa limpia con relleno. La región del sujeto en placa.webm es completamente transparente — compón algo opaco debajo para llenar el agujero. La prueba única sobre si --background-output es la herramienta adecuada: ¿alguna vez será visible algo a través de la silueta del sujeto donde solía estar el sujeto?

Caso de usoHerramienta adecuada
Texto/gráficos entre el recorte y la placa (razón de existencia de este comando)Agujero (--background-output)
Sujeto sobre una escena no relacionadaSolo sujeto.webm; ignora la placa
Mostrar la sala sin la persona, sola sobre ningún otro contenidoPlaca limpia — necesita un inpainter (LaMa, ProPainter, E2FGVI). No es este comando.
Reemplazar el sujeto con un sujeto diferentePlaca limpia — igual que arriba

Si un usuario pide "la sala con la persona eliminada" y tiene la intención de mostrarla sola, no uses --background-output. Indícale que necesita un inpainter.

Composición típica en capas (el caso de uso canónico del agujero):

<!-- z=1 la placa con alfa inverso llena todo excepto la región del sujeto -->
<video
  src="placa.webm"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>

<!-- z=2 gráficos / texto viven entre las dos capas -->
<h1 id="titulo" style="z-index:2; ...">HAZLO EN HYPERFRAMES</h1>

<!-- z=3 el recorte flota al sujeto de nuevo sobre el titular -->
<div class="contenedor-recorte" style="position:absolute;inset:0;z-index:3">
  <video
    src="sujeto.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 necesitas el presentador.mp4 original en el proyecto — la placa lo reemplaza. Útil cuando quieres distribuir solo las dos capas transparentes y permitir que el usuario coloque contenido arbitrario entre ellas.

Formato de Salida

FormatoCuándo
.webm (VP9 + alfa)Predeterminado. Las composiciones lo reproducen directamente con <video>.
.mov (ProRes 4444)Edición en DaVinci/Premiere/FCP. Archivos grandes.
.pngRecorte de imagen única (sujeto estático, superpuesto sobre un fondo).

Chrome decodifica VP9 alfa de forma nativa, por lo que el .webm se conecta a una composición como cualquier otro video con auto-reproducción silenciado — consulta el skill hyperframes para las convenciones de pistas <video>.

Presets de Calidad

--quality fast|balanced|best controla solo el CRF del codificador VP9 — la calidad de segmentación es fija.

PresetCRFCuándo
fast30Iteración, archivo más pequeño, coincidencia de color más suelta
balanced18Predeterminado. Visualmente idéntico para la mayoría de los usos
best12Maestro / entrega final. Archivo más grande, coincidencia más precisa

Patrones de Composición — elige el correcto

El webm recortado es una copia recodificada del RGB del mp4 de origen. Esa elección tiene consecuencias dependiendo de lo que coloques detrás:

PatrónQué hay detrás del recorteResultado
Recorte sobre una escena diferente (más común)Imagen estática, degradado o video no relacionadoSe ve genial. El RGB del recorte es la única fuente del sujeto — sin duplicación, sin halo en bordes. Para esto está diseñado remove-background.
Recorte sobre su propio mp4 de origen (texto-detrás-del-sujeto)El mismo mp4 del que se generó el recorteDos fuentes RGB para la misma persona. Con --quality balanced (crf 18) predeterminado, la duplicación es apenas visible; con --quality fast (crf 30) verás un ligero cambio de color / halo en bordes. Usa --quality best (crf 12) para maestros.
Recorte sobre una toma diferente de la misma personaMetraje del mismo sujetoParecerán dos personas separadas superpuestas. No hagas esto.

Texto-detrás-del-sujeto (titular detrás de un presentador):

<video
  src="presentador.mp4"
  id="fondo"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>
<h1 id="titulo" style="z-index:2; ...">HAZLO EN HYPERFRAMES</h1>
<div class="contenedor-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:

  1. Envuelve el video recortado en un <div> sin temporización y anima la opacidad del contenedor, no la del elemento video. El framework fuerza opacidad:1 en clips activos (cualquier elemento con data-start/data-duration), por lo que animar la opacidad del video directamente se anula silenciosamente. El contenedor no tiene atributos data-*, por lo que es propiedad de tu CSS/GSAP.
  2. Ambos videos usan data-start="0" y data-media-start="0" para que el framework los decodifique sincronizados desde t=0. Montar el recorte tarde (data-start=3.3) introduce una búsqueda + calentamiento que aterriza un fotograma desfasado del mp4 base — visible como un fotograma de desalineación en el corte.

Luego, invierte la opacidad del contenedor con GSAP en el corte: tl.set(contenedorRecorte, { opacity: 1 }, 3.3).

TTS → Transcripción → Subtítulos

Cuando no hay voz en off pre-grabada, genera una y transfórmala de nuevo para obtener marcas de tiempo a nivel de palabra para los subtítulos:

npx hyperframes tts script.txt --voice af_heart --output narración.wav
npx hyperframes transcribe narración.wav   # → transcript.json

# ... (truncado por traducción)

Skills relacionados