Médias HyperFrames
Créez les actifs audio et médias dont une composition a besoin – voix off (TTS), fond sonore + effets sonores, transcription, sous-titres, suppression d’arrière-plan – puis consommez et animez ces données en HTML. Pour le placement des actifs dans les compositions, voir hyperframes-core.
Le moteur audio – une source unique pour TTS · BGM · SFX
Les workflows n'écrivent pas leur propre code audio et ne dupliquent pas d'appels. Il existe un seul moteur – scripts/audio.mjs – qui prend un audio_request.json neutre et écrit audio_meta.json (ainsi que 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 dégradent selon un seul interrupteur – la présence d’un credential HeyGen (résolu depuis $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen, pas le CLI) :
| Capacité | Credential HeyGen présent | absent |
|---|---|---|
| TTS | HeyGen Starfish REST (timestamps natifs) | → ElevenLabs → Kokoro (chaîne transcribe pour les mots) |
| BGM | Récupération HeyGen retrieval | Lyria → MusicGen local generation (détaché) |
| SFX | Récupération HeyGen retrieval (min_score 0.4) | bibliothèque locale 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 appelant (numéro d’image, identifiant de scène…).bgm.mode=retrieve | generate | none; omettre pour auto (récupération si credential, sinon génération). Unretrieveexplicite est strict – il saute plutôt que de lancer une génération détachée (pour les appelants sans étapewait-bgm). - Sortie (
audio_meta.json, indexée 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 (ex. TTS+BGM tôt, SFX une fois les indices 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 un CLI mono-coup 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 flags et le schéma de 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 limites de chaque capacité.
Pré-vol – afficher le statut de connexion avant tout audio
Exécutez toujours ceci avant de générer de la voix ou un BGM – dans un workflow complet ou une demande ponctuelle « génère-moi un BGM/voix off ». L’absence de credential HeyGen n’est pas une raison pour basculer silencieusement vers les moteurs locaux : recommandez d’abord la connexion et laissez l’utilisateur décider. Lancez le pré-vol partagé 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é (
exit 0) → il affiche le compte ; poursuivez. - Non connecté (
exit 1est normal 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 navigateur – il connecte et crée un compte (toujours disponible via le 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~/.heygenpartagé (pas de.envpar dépôt). La sortie liste également les moteurs locaux vers lesquels la voix/BGM basculera et un indicepipsi des dépendances manquent. Relayez cette sortie telle quelle – ne la paraphrasez pas dans vos propres mots. Ensuite 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 vrai 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 le statut et continuez hors ligne.) npx hyperframes auth status --jsonretourne{ configured, recommended_action, offline_engines }pour un branchement déterministe.- Si le CLI ne peut pas s’exécuter (pas dans le PATH et
npxne peut pas le 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 de credential » comme un feu vert silencieux pour la génération locale.
La résolution des credentials, 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 | Timestamps des mots |
|---|---|---|---|
| 1 | HeyGen (Starfish) | $HEYGEN_API_KEY / hyperframes auth login | Oui, natifs – passez --words narration.words.json pour les capturer |
| 2 | ElevenLabs | $ELEVENLABS_API_KEY défini | Non – chaînez transcribe après |
| 3 | Kokoro-82M (local, 54 voix) | toujours (aucune clé requise) | Non – chaînez transcribe après |
Le CLI publié
hyperframes ttsest souvent la version locale uniquement (son--helpdit « Kokoro-82M », pas de--provider/--words) et bascule silencieusement vers Kokoro même avec$HEYGEN_API_KEYdéfini. C’est pourquoi le chemin HeyGen du moteur est lescripts/heygen-tts.mjsautonome (REST), PAS le CLI ; le CLI n’est utilisé que 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 credential que le TTS HeyGen, avec le repli sans credential du tableau ci-dessus :
| Actif | Type HeyGen | Destination | Repli (pas de credential) |
|---|---|---|---|
| BGM | music | assets/bgm/track.mp3 (récupération) · track.wav (génération) | Génération Lyria / MusicGen |
| SFX | sound_effects (min_score 0.4) | assets/sfx/<slug>.mp3 | Bibliothèque locale 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 | 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 (pas de voix off enregistrée) | references/tts-to-captions.md |
| Auteur de sous-titres – détection de style, disposition, groupement 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, audio-réactif | 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 TTS/BGM/SFX dans un workflow – écrivez un adaptateuraudio_request.jsonet appelez le moteur. - « HeyGen disponible » = un credential résoluble, pas le CLI. Tout l’interrupteur dépend de
heygenCredential(); le CLI publiéhyperframes ttspeut être Kokoro uniquement, et il n’existe pas de commandehyperframes bgm/hyperframes sfx. - Les identifiants de voix sont propres à chaque fournisseur.
am_michaelest Kokoro uniquement ; 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 du CLIsmall.entraduit silencieusement l’audio non anglais. Voirreferences/transcribe.md→ « Règle de langue ». - HeyGen retourne des timestamps de mots ; ElevenLabs / Kokoro non. Le moteur chaîne
transcribeautomatiquement pour les deux derniers ; en mode autonome, passez--wordsà HeyGen ou exécuteztranscribecontre le fichier audio. - Les sous-titres consomment le format plat de tableau de mots avec
{ id, text, start, end }. Voirreferences/transcribe.md→ « Forme de sortie ». remove-background --background-outputest un trou découpé, pas un inpaint. Pour « scène sans la personne », un autre outil est nécessaire. Voirreferences/remove-background.md→ « Quand NE PAS utiliser cet outil ».- BGM/SFX par défaut récupérés depuis HeyGen ; le repli sans credential est la génération (BGM) ou la bibliothèque locale (SFX).
/audio/soundsclasse par une requête textuelle – nommez les effets concrètement (glass shatter, pasdramatic sound) ; une absence de correspondance saute, 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 du skin réutilisable se trouve dans
.hyperframes/caption-skin.htmlet le script du workflow écritcompositions/captions.html; ne modifiez pascompositions/captions.htmlgénéré pour corriger le skin. Reconstruisez via lecaptions.mjsdu workflow, ou utilisez le mécanisme de surcharge explicite de ce workflow lorsqu’il est présent.