Médias HyperFrames
Créez les ressources 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 les ressources dans les compositions, voir hyperframes-core.
Le moteur audio — une source unique pour TTS · BGM · SFX
Les workflows NE créent PAS leur propre audio ni ne dupliquent un fournisseur. Il y a un seul moteur — scripts/audio.mjs — qui prend un audio_request.json neutre et écrit audio_meta.json (plus les ressources sous assets/voice|bgm|sfx) :
# <MEDIA_DIR> = répertoire de cette compétence
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
Les trois capacités se dégradent sur UN SEUL commutateur — la présence d'un identifiant HeyGen (résolu depuis $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen, pas l'interface en ligne de commande) :
| Capacité | Identifiant HeyGen présent | absent |
|---|---|---|
| TTS | HeyGen Starfish REST (horodatage par mot natif) | → ElevenLabs → Kokoro (chaîne transcribe pour les mots) |
| BGM | Récupération de musique HeyGen | Génération locale Lyria → MusicGen (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; omettre pour automatique (récupération avec identifiant, sinon génération). Unretrieveexplicite est 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é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 (par ex. TTS+BGM tôt, SFX une fois les repères existants).- 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 interface en ligne de commande unique sur le même code (un texte → wav + mots) pour quand vous avez besoin du TTS HeyGen sans fichier de requête.
La liste complète des drapeaux 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 particuliers de chaque capacité.
Pré-vol — afficher l'état de connexion avant tout audio
Exécutez toujours ceci avant de générer une voix ou une BGM — 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 basculer silencieusement vers les moteurs locaux : recommandez d'abord la connexion et laissez l'utilisateur décider. Exécutez le pré-vol partagé et relayez sa sortie textuelle — n'improvisez pas votre propre invite "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 d'inscription. Recommandez la connexion :npx hyperframes auth loginest un OAuth navigateur — il connecte et crée un compte (toujours disponible via l'interface en ligne de commande 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~/.heygenpartagé (pas de.envpar dépôt). La sortie liste également les moteurs locaux vers lesquels la voix/BGM basculera et une indicationpiplorsque des dépendances manquent. Relayez cette sortie telle quelle — ne la paraphrasez pas dans vos propres termes. 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 passagère : ne l'intégrez pas dans une autre question et ne passez pas outre tout seul. (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 l'interface en ligne de commande 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 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 gagne (le moteur, ou npx hyperframes tts "...") :
| Ordre | Fournisseur | Détecté quand | Horodatage par mot |
|---|---|---|---|
| 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 — enchaînez transcribe après |
| 3 | Kokoro-82M (local, 54 voix) | toujours (aucune clé requise) | Non — enchaînez transcribe après |
L'interface en ligne de commande publiée
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 le script autonomescripts/heygen-tts.mjs(REST), PAS l'interface en ligne de commande ; celle-ci n'est utilisée 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 identifiant que pour le TTS HeyGen, avec le basculement sans identifiant du commutateur ci-dessus :
| Ressource | Type HeyGen | Atterrit dans | Secours (pas d'identifiant) |
|---|---|---|---|
| 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 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, le commutateur | 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 (pas de voix off enregistrée) | references/tts-to-captions.md |
| Création 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 |
| Animation des sous-titres — karaoké, effets de marqueur, réactif à l'audio | references/captions/motion.md |
| Caches de modèles, 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 l'interface en ligne de commande. Tout le commutateur s'appuie sur
heygenCredential(); l'interface 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 exclusif à Kokoro ; les UUID HeyGen ne fonctionnent pas sur Kokoro. Si vous passez--voice, verrouillez aussi--providerpour éviter une dérive silencieuse de fournisseur lorsque l'environnement de l'utilisateur change. - Passez toujours
--modelàtranscribe. La valeur par défautsmall.entraduit silencieusement l'audio non anglais. Voirreferences/transcribe.md→ "Règle de langue". - HeyGen retourne les horodatages par mot ; ElevenLabs / Kokoro non. Le moteur enchaîne automatiquement
transcribepour ces deux derniers ; en utilisation autonome, passez--wordsà HeyGen ou exécuteztranscribesur le fichier audio. - Les sous-titres consomment le format de tableau plat de mots avec
{ id, text, start, end }. Voirreferences/transcribe.md→ "Forme de sortie". remove-background --background-outputest un trou découpé, pas un inpaintage. 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érés depuis HeyGen ; le secours sans identifiant est la génération (BGM) ou la bibliothèque intégrée (SFX).
/audio/soundsclasse par une requête textuelle — nommez les effets concrètement (bris de verre, passon dramatique) ; 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 du skin réutilisable se trouve dans
.hyperframes/caption-skin.htmlet le script du workflow écritcompositions/captions.html; ne modifiez pas le fichier générécompositions/captions.htmlpour corriger le skin. Reconstruisez via lecaptions.mjsdu workflow, ou utilisez le mécanisme de surcharges explicites de ce workflow lorsqu'il est présent.