HyperFrames Media
Créez les actifs audio et médias nécessaires à une composition — voix off (TTS), musique de fond + effets sonores, transcription, sous-titres, suppression d'arrière-plan — puis consommez et animez ces données en HTML. Pour placer des actifs dans des compositions, voir hyperframes-core.
Le moteur audio — une seule source pour TTS · BGM · SFX
Les workflows ne créent PAS d'audio de manière artisanale ni ne dupliquent de fournisseur. Il y a un moteur — scripts/audio.mjs — qui prend un audio_request.json neutre et écrit audio_meta.json (plus les actifs sous assets/voice|bgm|sfx) :
# <MEDIA_DIR> = répertoire de ce skill
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
Les trois capacités se dégradent selon UN interrupteur — la présence d'un identifiant HeyGen (résolu depuis $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen, pas la CLI) :
| Capacité | Identifiant HeyGen présent | absent |
|---|---|---|
| TTS | HeyGen Starfish REST (horodatage natif des mots) | → ElevenLabs → Kokoro (chaîne transcribe pour les mots) |
| BGM | Récupération de musique HeyGen retrieval | Lyria → MusicGen génération locale (détachée) |
| SFX | Récupération d'effets sonores HeyGen (min_score 0.4) | bibliothèque intégrée de 21 fichiers (assets/sfx/) |
- Requête (
audio_request.json) :{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }.idrelie chaque ligne au modèle de l'appelant (un numéro d'image, un identifiant de scène, …).bgm.mode=retrieve | generate | none; omettez pour automatique (récupérer si identifiant présent, sinon générer). Un mode expliciteretrieveest strict — il ignore plutôt que de lancer une génération détachée (pour les appelants sans étapewait-bgm). - Sortie (
audio_meta.json, indexé par 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,sfxexécute un sous-ensemble et fusionne dans un--outexistant (par exemple TTS+BGM tôt, SFX une fois les repères connus).- La génération BGM est lancée détachée (
bgm_pending: true) — exécutezscripts/wait-bgm.mjsavant l'assemblage. scripts/heygen-tts.mjsest une CLI à usage unique sur le même code (un texte → wav + mots) pour quand vous avez juste besoin du TTS HeyGen sans fichier de requête.
La liste complète des indicateurs et le schéma audio_meta.json se trouvent dans l'en-tête de scripts/audio.mjs. Les références ci-dessous couvrent les détails des fournisseurs et les cas particuliers derrière chaque capacité.
Pré-vérification — afficher l'état de connexion avant tout audio
Exécutez toujours ceci avant de générer une voix ou une BGM — que ce soit dans un workflow complet ou une demande ponctuelle "génère-moi une BGM/voix off". L'absence d'identifiant HeyGen n'est pas une raison pour passer silencieusement aux moteurs locaux : recommandez d'abord la connexion et laissez l'utilisateur décider. Exécutez la pré-vérification partagée et relayez sa sortie textuellement — n'improvisez pas votre propre message "clé manquante" et ne proposez pas d'écrire des clés dans un .env par dépôt :
npx hyperframes auth status
- Connecté → il affiche le compte ; continuez.
- Non connecté (
exit 1est attendu ici — "non connecté" est un état normal, pas un échec) → il affiche des instructions pour s'inscrire en premier. Recommandez la connexion :npx hyperframes auth loginest un OAuth par navigateur — il connecte et crée un compte (toujours disponible via la CLI de ce dépôt). Pour utiliser une clé API HeyGen existante (depuis app.heygen.com/settings/api), exécuteznpx hyperframes auth login --api-key— elle est sauvegardée dans le fichier partagé~/.heygen(pas de.envpar dépôt). La sortie liste également les moteurs locaux vers lesquels la voix/BGM se rabattra et une astucepiplorsque des dépendances manquent. Relayez cette sortie telle quelle — ne la paraphrasez pas avec vos propres mots. Puis ARRÊTEZ et attendez que l'utilisateur choisisse — se connecter, ou dire "go" / "local" pour continuer hors ligne — avant de générer quoi que ce soit. C'est un véritable point de décision, pas une note de passage : ne le fusionnez pas dans une autre question et ne le dépassez pas de votre propre chef. (Exception : en mode autonome / non interactif, notez l'état et continuez hors ligne.) npx hyperframes auth status --jsonretourne{ configured, recommended_action, offline_engines }pour un branchement déterministe.- Si la CLI ne peut pas s'exécuter (pas dans le PATH et
npxne peut pas la récupérer) → recommandez quand même la connexion (npx hyperframes auth login) et ARRÊTEZ pour le choix de l'utilisateur — ne traitez pas "pas d'identifiant" comme un feu vert silencieux pour la génération locale.
La résolution des identifiants, la priorité complète des clés et la liste des dépendances locales se trouvent dans references/requirements.md.
Chaînes de fournisseurs (le détail derrière le moteur)
TTS — le premier fournisseur disponible l'emporte (le moteur, ou npx hyperframes tts "...") :
| Ordre | Fournisseur | Détecté quand | Horodatage des mots |
|---|---|---|---|
| 1 | HeyGen (Starfish) | $HEYGEN_API_KEY / hyperframes auth login | Oui, natif — passez --words narration.words.json pour capturer |
| 2 | ElevenLabs | $ELEVENLABS_API_KEY défini | Non — chaîne transcribe après |
| 3 | Kokoro-82M (local, 54 voix) | toujours (aucune clé requise) | Non — chaîne transcribe après |
La CLI publiée
hyperframes ttsest souvent la version locale uniquement (son--helpdit "Kokoro-82M", pas de--provider/--words) et tombe silencieusement sur Kokoro même avec$HEYGEN_API_KEYdéfini. C'est pourquoi le chemin HeyGen du moteur est lescripts/heygen-tts.mjsautonome (REST), PAS la CLI ; la CLI est utilisée uniquement pour le chemin Kokoro. Voirreferences/tts.md.
BGM & SFX — par défaut récupérés depuis la bibliothèque audio HeyGen (/v3/audio/sounds), même identifiant que pour le TTS HeyGen, avec le repli sans identifiant depuis l'interrupteur ci-dessus :
| Actif | HeyGen type | Atterrit dans | Repli (pas d'identifiant) |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3 (récupération) · track.wav (génération) | Lyria / MusicGen génération |
| SFX | sound_effects (min_score 0.4) | assets/sfx/<slug>.mp3 | bibliothèque intégrée de 21 fichiers (assets/sfx/* + manifest.json) |
Voir references/bgm.md et references/sfx.md.
Routage
| Tâche | Lire |
|---|---|
Le moteur audio — schéma requête/méta, --only, l'interrupteur | scripts/audio.mjs (commentaire d'en-tête) |
npx hyperframes tts / heygen-tts.mjs — fournisseurs, voix, mots | references/tts.md |
| BGM — Récupération HeyGen + génération locale Lyria / MusicGen | references/bgm.md |
| SFX — Récupération HeyGen (min_score 0.4) + bibliothèque locale intégrée | references/sfx.md |
npx hyperframes transcribe — Whisper, règles de modèle, forme de sortie | references/transcribe.md |
npx hyperframes remove-background — découpes transparentes | references/remove-background.md |
| TTS → transcription → sous-titres (sans voix off enregistrée) | references/tts-to-captions.md |
| Édition de sous-titres — détection de style, disposition, regroupement de mots, sortie | references/captions/authoring.md |
| Gestion des transcriptions — formats d'entrée, contrôles qualité, nettoyage, API | references/captions/transcript-handling.md |
| Mouvement des sous-titres — karaoké, effets de marqueur, réactif à l'audio | references/captions/motion.md |
| Caches de modèle, dépendances système, dépannage | references/requirements.md |
Règles non négociables
- Un seul moteur, pas de copies dupliquées. Produisez l'audio via
scripts/audio.mjs(ouheygen-tts.mjspour un TTS HeyGen ponctuel). Ne réimplémentez pas le TTS/BGM/SFX dans un workflow — écrivez un adaptateuraudio_request.jsonet appelez le moteur. - "HeyGen disponible" = un identifiant résoluble, pas la CLI. Tout l'interrupteur repose sur
heygenCredential(); la CLI publiéehyperframes ttspeut être limitée à Kokoro, et il n'existe aucune commandehyperframes bgm/hyperframes sfx. - Les identifiants de voix sont spécifiques au fournisseur.
am_michaelest propre à Kokoro ; les UUID HeyGen ne fonctionnent pas sur Kokoro. Si vous passez--voice, fixez aussi--providerpour éviter une dérive silencieuse du fournisseur lorsque l'environnement de l'utilisateur change. - Passez toujours
--modelàtranscribe. La valeur par défaut de la CLI,small.en, traduit silencieusement l'audio non anglais. Voirreferences/transcribe.md→ "Règle de langue". - HeyGen retourne les horodatages des mots ; ElevenLabs / Kokoro pas. Le moteur chaîne automatiquement
transcribepour ces deux derniers ; de manière autonome, passez--wordsà HeyGen ou exécuteztranscribesur le fichier audio. - Les sous-titres consomment le format plat du tableau de mots avec
{ id, text, start, end }. Voirreferences/transcribe.md→ "Forme de sortie". remove-background --background-outputest une découpe, pas un remplissage. Pour "scène sans la personne", un outil différent est nécessaire. Voirreferences/remove-background.md→ "Quand ce n'est PAS le bon outil".- BGM/SFX par défaut : récupération HeyGen ; le repli sans identifiant est la génération (BGM) ou la bibliothèque intégrée (SFX).
/audio/soundsclasse par requête textuelle — nommez les effets concrètement (glass shatter, pasdramatic sound) ; une absence de correspondance ignore, ne bloque jamais le rendu. Les SFX sont à un volume d'environ 0,35 sous la voix + BGM. Voirreferences/sfx.md/references/bgm.md. - Traitez le HTML des sous-titres du workflow comme une sortie générée. Pour les vidéos basées sur des préréglages, la source de l'habillage réutilisable se trouve dans
.hyperframes/caption-skin.htmlet le script du workflow écritcompositions/captions.html; ne modifiez pas lecompositions/captions.htmlgénéré pour corriger l'habillage. Reconstruisez via lecaptions.mjsdu workflow, ou utilisez le mécanisme de surcharges explicites de ce workflow lorsqu'il est présent.