Communitygithub.com

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.

Qu'est-ce que HyperFrames Media ?

HyperFrames Media est une compétence spécialisée pour la création de ressources audio et médias destinées aux compositions HyperFrames. Elle fournit un moteur audio unique (`scripts/audio.mjs`) qui gère la synthèse vocale (TTS), la musique de fond (BGM), les effets sonores (SFX), la transcription, les sous-titres et la suppression d'arrière-plan. Le moteur adopte une approche multi-fournisseur : pour le TTS, il utilise HeyGen (avec timestamps par mot), ElevenLabs ou Kokoro local ; pour le BGM et les SFX, il privilégie la récupération depuis la bibliothèque HeyGen, avec un fallback local (Lyria/MusicGen pour le BGM et une bibliothèque de 21 fichiers pour les SFX). Cette compétence est utile pour les développeurs créant des compositions riches en médias, sans avoir à intégrer chaque API individuellement. Elle prend en charge des tâches comme la voix off / TTS, la sélection de voix et de fournisseurs, la génération de musique par humeur, les sous-titres karaoké, et la transcription via Whisper. Le moteur est conçu pour être utilisé via un fichier de requête JSON standardisé et produit des métadonnées exploitables, facilitant l'intégration dans des workflows automatisés.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/whyiloveher2411/_biong_backend_FE/tree/HEAD/agent/skills/hyperframes-media

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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ésenteabsente
TTSHeyGen Starfish REST (timestamps de mots natifs)→ ElevenLabs → Kokoro (chaîne transcribe pour les mots)
BGMRécupération de musique HeyGenGénération locale Lyria → MusicGen (détachée)
SFXRé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? } }. id relie 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 explicite retrieve est strict — il ignore plutôt que de lancer une génération détachée (pour les appelants sans étape wait-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,sfx exécute un sous-ensemble et fusionne dans un --out existant (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écutez scripts/wait-bgm.mjs avant l'assemblage.
  • scripts/heygen-tts.mjs est 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 "...") :

OrdreFournisseurDétecté quandTimestamps de mots
1HeyGen (Starfish)$HEYGEN_API_KEY / hyperframes auth loginOui, natifs — passez --words narration.words.json pour capturer
2ElevenLabs$ELEVENLABS_API_KEY définiNon — enchaînez transcribe après
3Kokoro-82M (local, 54 voix)toujours (aucune clé requise)Non — enchaînez transcribe après

La CLI publiée hyperframes tts est souvent la version locale uniquement (son --help indique "Kokoro-82M", pas de --provider/--words) et revient silencieusement à Kokoro même avec $HEYGEN_API_KEY défini. C'est pourquoi le chemin HeyGen du moteur est le scripts/heygen-tts.mjs autonome (REST), PAS la CLI ; la CLI n'est utilisée que pour le chemin Kokoro. Voir references/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 :

RessourceType HeyGenAtterrit dansFallback (sans information d'identification)
BGMmusicassets/bgm/track.mp3 (récupération) · track.wav (génération)Génération Lyria / MusicGen
SFXsound_effects (min_score 0.4)assets/sfx/<slug>.mp3Bibliothèque intégrée de 21 fichiers (assets/sfx/* + manifest.json)

Voir references/bgm.md et references/sfx.md.

Routage

TâcheLire
Le moteur audio — schéma requête/méta, --only, le commutateurscripts/audio.mjs (commentaire d'en-tête)
npx hyperframes tts / heygen-tts.mjs — fournisseurs, voix, motsreferences/tts.md
Script TTS vietnamien — ponctuation, phonétique (couche TTS)references/tts-vi.md
BGM — récupération HeyGen + génération locale Lyria / MusicGenreferences/bgm.md
SFX — récupération HeyGen (min_score 0.4) + bibliothèque locale intégréereferences/sfx.md
npx hyperframes transcribe — Whisper, règles de modèle, format de sortiereferences/transcribe.md
npx hyperframes remove-background — découpes transparentesreferences/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, sortiereferences/captions/authoring.md
Gestion des transcriptions — formats d'entrée, contrôles de qualité, nettoyage, APIreferences/captions/transcript-handling.md
Animation des sous-titres — karaoké, effets de marqueur, réactif à l'audioreferences/captions/motion.md
Caches de modèle, dépendances système, dépannagereferences/requirements.md

Règles non négociables

  • Un seul moteur, pas de copies externalisées. Produisez l'audio via scripts/audio.mjs (ou heygen-tts.mjs pour un TTS HeyGen unique). Ne réimplémentez pas le TTS/BGM/SFX dans un workflow — écrivez un adaptateur audio_request.json et appelez le moteur.
  • "HeyGen disponible" = une information d'identification résolvable, pas la CLI. Tout le commutateur repose sur heygenCredential() ; la CLI publiée hyperframes tts peut être Kokoro uniquement, et il n'y a aucune commande hyperframes bgm / hyperframes sfx du tout.
  • Les identifiants de voix sont spécifiques au fournisseur. am_michael est Kokoro uniquement ; les UUID HeyGen ne fonctionnent pas sur Kokoro. Si vous passez --voice, fixez aussi --provider pour é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 CLI small.en traduit silencieusement l'audio non anglais. Voir references/transcribe.md → "Règle de langue".
  • HeyGen renvoie des timestamps de mots ; ElevenLabs / Kokoro non. Le moteur enchaîne transcribe automatiquement pour ces deux derniers ; de manière autonome, passez --words à HeyGen ou exécutez transcribe sur le fichier audio.
  • Les sous-titres consomment le format de tableau de mots plat avec { id, text, start, end }. Voir references/transcribe.md → "Format de sortie".
  • remove-background --background-output est un trou découpé, pas une repeinture. Pour "scène sans la personne", un outil différent est nécessaire. Voir references/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/sounds classe par une requête textuelle — nommez les effets concrètement (bris de verre, pas son dramatique) ; une absence de correspondance ignore, ne bloque jamais le rendu. Les SFX ont un volume ~0.35 sous la voix + BGM. Voir references/sfx.md / references/bgm.md.

Skills associés