HyperFrames Media
Crea los activos de audio y medios que necesita una composición — locución (TTS), música de fondo + efectos de sonido, transcripción, subtítulos, eliminación de fondos — y luego consume y anima esos datos en HTML. Para colocar activos en composiciones, consulta hyperframes-core.
El motor de audio — una sola fuente para TTS · BGM · SFX
Los flujos de trabajo NO crean audio manualmente ni utilizan copias externas. Hay un único motor — scripts/audio.mjs — que toma un audio_request.json neutral y escribe audio_meta.json (además de los activos en assets/voice|bgm|sfx):
# <MEDIA_DIR> = directorio de este skill
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
Las tres capacidades se degradan según UN SOLO INTERRUPTOR — si hay una credencial HeyGen presente (resuelta desde $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen, no desde la CLI):
| Capacidad | Credencial HeyGen presente | ausente |
|---|---|---|
| TTS | HeyGen Starfish REST (marcas de tiempo nativas) | → ElevenLabs → Kokoro (encadenar transcribe para palabras) |
| BGM | Recuperación de música HeyGen | Generación local Lyria → MusicGen (desacoplado) |
| SFX | Recuperación de efectos de sonido HeyGen (min_score 0.4) | Biblioteca local de 21 archivos (assets/sfx/) |
- Solicitud (
audio_request.json):{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }.idvincula cada línea al modelo de la persona que llama (un número de fotograma, un id de escena, …).bgm.mode=retrieve | generate | none; omite para auto (recuperar cuando hay credencial, generar en caso contrario). Unretrieveexplícito es estricto — se salta en lugar de iniciar una generación desacoplada (para quienes llaman sin un pasowait-bgm). - Salida (
audio_meta.json, indexado por id):{ tts_provider, voice_id, bgm, bgm_pending, …, voices: [{ id, path, duration_s, words }], sfx: [{ id, name, file, source, offset_s, duration_s, volume }], total_duration_s }. --only tts,bgm,sfxejecuta un subconjunto y fusiona en un--outexistente (por ejemplo, TTS+BGM temprano, SFX una vez que existen las señales).- La generación BGM se inicia desacoplada (
bgm_pending: true) — ejecutascripts/wait-bgm.mjsantes de ensamblar. scripts/heygen-tts.mjses una CLI de un solo uso sobre el mismo código (un texto → wav + palabras) para cuando solo necesitas TTS HeyGen sin un archivo de solicitud.
La lista completa de banderas y el esquema de audio_meta.json se encuentran en el encabezado de scripts/audio.mjs. Las referencias a continuación cubren los detalles del proveedor y los casos límite detrás de cada capacidad.
Verificación previa — mostrar estado de inicio de sesión antes de cualquier audio
Ejecuta esto siempre antes de generar voz o BGM — ya sea dentro de un flujo de trabajo completo o una solicitud única de "generar un BGM/locución". La ausencia de una credencial HeyGen no es motivo para recurrir silenciosamente a motores locales: primero recomienda iniciar sesión y deja que el usuario decida. Ejecuta la verificación previa compartida y transmite su salida textualmente — no improvises tu propio mensaje de "clave faltante" y no ofrezcas escribir claves en un .env por repositorio:
npx hyperframes auth status
- Con sesión iniciada → imprime la cuenta; continúa.
- Sin sesión iniciada (aquí se espera
exit 1— "sin sesión iniciada" es un estado normal, no un fallo) → imprime instrucciones centradas en el registro. Recomienda iniciar sesión:npx hyperframes auth logines OAuth en el navegador — inicia sesión y crea una cuenta (siempre disponible a través de la CLI de este repositorio). Para usar una clave API HeyGen existente (de app.heygen.com/settings/api), ejecutanpx hyperframes auth login --api-key— se guarda en~/.heygencompartido (sin.envpor repositorio). La salida también enumera los motores locales a los que recurrirán la voz/BGM y una sugerencia depipcuando faltan dependencias. Transmite esta salida tal cual — no la parafrasees con tus propias palabras. Luego DETENTE y espera a que el usuario elija — iniciar sesión, o decir "adelante" / "local" para continuar sin conexión — antes de generar nada. Este es un punto de decisión real, no una nota pasajera: no lo integres en otra pregunta y no continúes por tu cuenta. (Excepción: en modo autónomo / no interactivo, anota el estado y continúa sin conexión.) npx hyperframes auth status --jsondevuelve{ configured, recommended_action, offline_engines }para ramificaciones deterministas.- Si la CLI no puede ejecutarse (no está en PATH y
npxno puede obtenerla) → igualmente recomienda iniciar sesión (npx hyperframes auth login) y DETENTE para que el usuario elija — no trates "sin credencial" como un semáforo verde silencioso para generación local.
La resolución de credenciales, la prioridad completa de claves y la lista de dependencias locales están en references/requirements.md.
Cadenas de proveedores (el detalle detrás del motor)
TTS — gana el primer proveedor disponible (el motor, o npx hyperframes tts "..."):
| Orden | Proveedor | Detectado cuando | Marcas de tiempo de palabras |
|---|---|---|---|
| 1 | HeyGen (Starfish) | $HEYGEN_API_KEY / hyperframes auth login | Sí, nativas — pasa --words narration.words.json para capturar |
| 2 | ElevenLabs | $ELEVENLABS_API_KEY establecida | No — encadena transcribe después |
| 3 | Kokoro-82M (local, 54 voces) | siempre (sin clave requerida) | No — encadena transcribe después |
La CLI publicada
hyperframes ttssuele ser la compilación solo local (su--helpdice "Kokoro-82M", sin--provider/--words) y recurre silenciosamente a Kokoro incluso con$HEYGEN_API_KEYestablecida. Por eso la ruta HeyGen del motor es el script autónomoscripts/heygen-tts.mjs(REST), NO la CLI; la CLI se usa solo para la ruta Kokoro. Consultareferences/tts.md.
BGM y SFX — por defecto se recuperan de la biblioteca de audio de HeyGen (/v3/audio/sounds), misma credencial que HeyGen TTS, con el respaldo sin credencial del interruptor anterior:
| Activo | Tipo HeyGen | Llega a | Respaldo (sin credencial) |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3 (recuperación) · track.wav (generación) | Generación Lyria / MusicGen |
| SFX | sound_effects (min_score 0.4) | assets/sfx/<slug>.mp3 | Biblioteca local de 21 archivos (assets/sfx/* + manifest.json) |
Consulta references/bgm.md y references/sfx.md.
Enrutamiento
| Tarea | Lectura |
|---|---|
El motor de audio — esquema de solicitud/meta, --only, el interruptor | scripts/audio.mjs (comentario del encabezado) |
npx hyperframes tts / heygen-tts.mjs — proveedores, voces, palabras | references/tts.md |
| BGM — recuperación HeyGen + generación local Lyria / MusicGen | references/bgm.md |
| SFX — recuperación HeyGen (min_score 0.4) + biblioteca local empaquetada | references/sfx.md |
npx hyperframes transcribe — Whisper, reglas de modelo, forma de salida | references/transcribe.md |
npx hyperframes remove-background — recortes transparentes | references/remove-background.md |
| TTS → transcripción → subtítulos (sin locución grabada) | references/tts-to-captions.md |
| Autoría de subtítulos — detección de estilo, diseño, agrupación de palabras, salida | references/captions/authoring.md |
| Manejo de transcripciones — formatos de entrada, controles de calidad, limpieza, APIs | references/captions/transcript-handling.md |
| Movimiento de subtítulos — karaoke, efectos de marcador, reactivo al audio | references/captions/motion.md |
| Cachés de modelo, dependencias del sistema, resolución de problemas | references/requirements.md |
Reglas no negociables
- Un solo motor, sin copias externas. Produce audio a través de
scripts/audio.mjs(oheygen-tts.mjspara TTS HeyGen de un solo uso). No reimplementes TTS/BGM/SFX dentro de un flujo de trabajo — escribe un adaptador deaudio_request.jsony llama al motor. - "HeyGen disponible" = una credencial resoluble, no la CLI. Todo el interruptor se basa en
heygenCredential(); la CLI publicadahyperframes ttspuede ser solo Kokoro, y no existe ningún comandohyperframes bgm/hyperframes sfx. - Los IDs de voz son específicos del proveedor.
am_michaeles solo Kokoro; los UUID de HeyGen no funcionan en Kokoro. Si pasas--voice, también fija--providerpara evitar una deriva silenciosa del proveedor cuando cambia el entorno del usuario. - Pasa siempre
--modelatranscribe. El valor predeterminadosmall.entraduce silenciosamente audio no inglés. Consultareferences/transcribe.md→ "Regla de idioma". - HeyGen devuelve marcas de tiempo de palabras; ElevenLabs / Kokoro no. El motor encadena
transcribeautomáticamente para estos dos últimos; de forma independiente, pasa--wordsa HeyGen o ejecutatranscribecontra el archivo de audio. - Los subtítulos consumen el formato de matriz plana de palabras con
{ id, text, start, end }. Consultareferences/transcribe.md→ "Forma de salida". remove-background --background-outputes un corte de agujero, no un relleno. Para "escena sin la persona", se necesita una herramienta diferente. Consultareferences/remove-background.md→ "CUÁNDO NO es la herramienta adecuada".- BGM/SFX por defecto recuperan de HeyGen; el respaldo sin credencial es generación (BGM) o la biblioteca empaquetada (SFX).
/audio/soundsclasifica por una consulta de texto — nombra los efectos concretamente (vidrio roto, nosonido dramático); una falta de coincidencia se salta, nunca bloquea la representación. Los SFX se sitúan en un volumen de aproximadamente 0.35 debajo de la voz + BGM. Consultareferences/sfx.md/references/bgm.md. - Trata el HTML de subtítulos del flujo de trabajo como salida generada. Para videos respaldados por plantillas predefinidas, la fuente de la piel reutilizable se encuentra en
.hyperframes/caption-skin.htmly el script del flujo de trabajo escribecompositions/captions.html; no edites elcompositions/captions.htmlgenerado para corregir la piel. Vuelve a compilar a través delcaptions.mjsdel flujo de trabajo, o utiliza el mecanismo de anulaciones explícitas de ese flujo de trabajo cuando esté presente.