Que fait HyperFrames Media ?
Créez les ressources audio et médias dont une composition a besoin — 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 des compositions, consultez hyperframes-core.
Le moteur audio — une source unique pour TTS · BGM · SFX
Les workflows NE créent PAS leur propre audio ni ne fournissent de copie externalisée. Il y a un seul moteur — scripts/audio.mjs — qui prend un audio_request.json neutre et écrit audio_meta.json (plus des 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 — selon qu'une information d'identification HeyGen est présente (résolue depuis $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen, pas la CLI) :
| Capacité | Information d'identification HeyGen présente | absente |
|---|---|---|
| TTS | HeyGen Starfish REST (timestamps de mots natifs) | → 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 auto (récupérer avec information d'identification, 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 ex., TTS+BGM tôt, SFX une fois les indices 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 CLI 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 + 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é.
Chaînes de fournisseurs (les détails derrière le moteur)
TTS — le premier fournisseur disponible gagne (le moteur, ou npx hyperframes tts "...") :
| Ordre | Fournisseur | Détecté quand | Timestamps de mots |
|---|---|---|---|
| 1 | HeyGen (Starfish) | $HEYGEN_API_KEY / hyperframes auth login | Oui, natifs — 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 |
La CLI publiée
hyperframes ttsest souvent la version locale uniquement (son--helpindique "Kokoro-82M", pas de--provider/--words) et revient silencieusement à 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 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 information d'identification que le TTS HeyGen, avec le fallback sans information d'identification du commutateur ci-dessus :
| Ressource | Type HeyGen | Atterrit dans | Fallback (sans information d'identification) |
|---|---|---|---|
| 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 |
| Script TTS vietnamien — ponctuation, phonétique (couche TTS) | references/tts-vi.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, format 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 |
| Rédaction 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 de 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èle, dépendances système, dépannage | references/requirements.md |
Règles non négociables
- Un seul moteur, pas de copies externalisées. Produisez l'audio via
scripts/audio.mjs(ouheygen-tts.mjspour un TTS HeyGen unique). Ne réimplémentez pas le TTS/BGM/SFX dans un workflow — écrivez un adaptateuraudio_request.jsonet appelez le moteur. - "HeyGen disponible" = une information d'identification résolvable, pas la CLI. Tout le commutateur repose sur
heygenCredential(); la CLI publiéehyperframes ttspeut être Kokoro uniquement, et il n'y a aucune commandehyperframes bgm/hyperframes sfxdu tout. - Les identifiants de voix sont spécifiques au 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 de fournisseur lorsque l'environnement de l'utilisateur change. - Passez toujours
--modelàtranscribe. La valeur par défaut de la CLIsmall.entraduit silencieusement l'audio non anglais. Voirreferences/transcribe.md→ "Règle de langue". - HeyGen renvoie des timestamps de mots ; ElevenLabs / Kokoro non. Le moteur enchaîne
transcribeautomatiquement pour ces deux derniers ; de manière autonome, passez--wordsà HeyGen ou exécuteztranscribesur le fichier audio. - Les sous-titres consomment le format de tableau de mots plat avec
{ id, text, start, end }. Voirreferences/transcribe.md→ "Format de sortie". remove-background --background-outputest un trou découpé, pas une repeinture. 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 en récupération HeyGen ; le fallback sans information d'identification 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 ont un volume ~0.35 sous la voix + BGM. Voirreferences/sfx.md/references/bgm.md.