Prétraitement Média HyperFrames
Trois commandes CLI qui produisent des actifs pour les compositions : tts (parole), transcribe (horodatages) et remove-background (vidéo transparente). Chacune télécharge un modèle lors de la première exécution et le met en cache dans ~/.cache/hyperframes/. Placez la sortie dans le projet, puis référencez-la dans le HTML de la composition — voir la compétence hyperframes pour les conventions des éléments audio/vidéo.
Synthèse Vocale (tts)
Générez de la parole localement avec Kokoro-82M. Aucune clé API n'est nécessaire.
npx hyperframes tts "Texte ici" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list # les 54 voix
Sélection de la Voix
Faites correspondre la voix au contenu. La voix par défaut est af_heart.
| Type de contenu | Voix | Pourquoi |
|---|---|---|
| Démo produit | af_heart/af_nova | Chaleureux, professionnel |
| Tutoriel / mode d'emploi | am_adam/bf_emma | Neutre, facile à suivre |
| Marketing / promotion | af_sky/am_michael | Énergique ou autoritaire |
| Documentation | bf_emma/bm_george | Anglais britannique clair, formel |
| Décontracté / social | af_heart/af_sky | Accessible, naturel |
Multilingue
Les identifiants de voix encodent la langue dans la première lettre : a=anglais américain, b=anglais britannique, e=espagnol, f=français, h=hindi, i=italien, j=japonais, p=portugais brésilien, z=mandarin. La CLI détecte automatiquement la locale du phonémiseur à partir du préfixe — pas besoin de --lang lorsque la voix correspond au texte.
npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav
Utilisez --lang uniquement pour remplacer la détection automatique (accents stylisés). Codes valides : en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh. La phonémisation non anglaise nécessite espeak-ng à l'échelle du système (brew install espeak-ng / apt-get install espeak-ng).
Vitesse
0.7-0.8— tutoriel, contenu complexe, accessibilité1.0— rythme naturel (par défaut)1.1-1.2— introductions, transitions, contenu dynamique1.5+— rarement approprié ; testez avec soin
Scripts Longs
Pour plus de quelques paragraphes, écrivez le contenu dans un fichier .txt et passez le chemin. Les entrées de plus de ~5 minutes de parole peuvent bénéficier d'un découpage en segments.
Prérequis
Python 3.8+ avec kokoro-onnx et soundfile (pip install kokoro-onnx soundfile). Le modèle est téléchargé lors de la première utilisation (~311 Mo + ~27 Mo de voix, mis en cache dans ~/.cache/hyperframes/tts/).
Transcription (transcribe)
Produit un fichier transcript.json normalisé avec des horodatages au niveau des mots.
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt # importation existante
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
Règle de Langue (Non Négociable)
N'utilisez jamais les modèles .en sauf si l'utilisateur déclare explicitement que l'audio est en anglais. Les modèles .en (small.en, medium.en) traduisent l'audio non anglais en anglais au lieu de le transcrire. Cela détruit silencieusement la langue d'origine.
- Langue connue et non anglaise →
--model small --language <code>(pas de suffixe.en) - Langue connue et anglaise →
--model small.en - Langue inconnue →
--model small(pas de.en, pas de--language) — whisper détecte automatiquement
Le modèle par défaut est small, pas small.en.
Tailles de Modèle
| Modèle | Taille | Vitesse | Quand l'utiliser |
|---|---|---|---|
tiny | 75 Mo | Le plus rapide | Aperçus rapides, test du pipeline |
base | 142 Mo | Rapide | Courts extraits, audio clair |
small | 466 Mo | Modérée | Par défaut — la plupart des contenus |
medium | 1,5 Go | Lente | Contenu important, audio bruité, musique |
large-v3 | 3,1 Go | La plus lente | Qualité production |
Musique avec voix : commencez au minimum par medium ; les pistes produites nécessitent souvent une importation manuelle SRT/VTT. Pour les vérifications de qualité des sous-titres (obligatoires après chaque transcription), le JS de nettoyage, les règles de nouvelle tentative, et le chemin d'importation API OpenAI/Groq, voir hyperframes/references/transcript-guide.md.
Structure de Sortie
Les compositions consomment un tableau plat d'objets word. Le champ id (w0, w1, ...) est ajouté lors de la normalisation pour des références stables dans les surcharges de sous-titres ; il est optionnel pour la rétrocompatibilité.
[
{ "id": "w0", "text": "Bonjour", "start": 0.0, "end": 0.5 },
{ "id": "w1", "text": "le monde.", "start": 0.6, "end": 1.2 }
]
Suppression d'Arrière-Plan (remove-background)
Supprimez l'arrière-plan d'une vidéo ou d'une image pour que le sujet (généralement une personne — avatar, présentateur, tête parlante) soit placé comme une incrustation transparente dans une composition.
npx hyperframes remove-background sujet.mp4 -o transparent.webm # par défaut : VP9 alpha WebM
npx hyperframes remove-background sujet.mp4 -o transparent.mov # ProRes 4444 (montage)
npx hyperframes remove-background portrait.jpg -o decoupe.png # découpage d'image unique
npx hyperframes remove-background sujet.mp4 -o sujet.webm \
--background-output fond.webm # les deux calques en une seule passe
npx hyperframes remove-background sujet.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # fournisseurs détectés
Utilise u2net_human_seg (MIT). La première exécution télécharge ~168 Mo de poids vers ~/.cache/hyperframes/background-removal/models/.
Séparation des Calques (--background-output)
Passez --background-output (ou -b) pour émettre une seconde vidéo transparente en plus du découpage : même RVB source, alpha est 255 − masque au lieu de masque. Le découpage est le sujet avec un arrière-plan transparent ; le fond est l'environnement d'origine avec un trou transparent à l'emplacement du sujet.
| Fichier | L'alpha est… | À utiliser pour |
|---|---|---|
-o sujet.webm | Le masque — sujet opaque, arrière-plan transparent | Calque de premier plan, placé au-dessus |
--background-output fond.webm | Inverse — environnement opaque, région du sujet transparent | Calque de fond ; placez du texte ou des graphiques entre ceci et le sujet |
Les deux sorties partagent le même préréglage --quality et sont issues d'une seule passe d'inférence — le coût de codage double environ, le coût de segmentation reste le même. Valide uniquement pour les entrées vidéo et les sorties .webm/.mov.
Fond troué, pas un fond nettoyé par inpainting. La région du sujet dans fond.webm est entièrement transparente — composez quelque chose d'opaque en dessous pour remplir le trou. Le seul test pour savoir si --background-output est le bon outil : y aura-t-il quelque chose de visible à travers la silhouette du sujet, là où se trouvait le sujet ?
| Cas d'utilisation | Bon outil |
|---|---|
| Texte/graphiques entre le découpage et le fond (raison d'être de cette commande) | Fond troué (--background-output) |
| Sujet sur une scène sans rapport | Juste sujet.webm ; ignorez le fond |
| Montrer la pièce sans la personne, seule, sans autre contenu | Fond nettoyé — nécessite un inpaint (LaMa, ProPainter, E2FGVI). Pas cette commande. |
| Remplacer le sujet par un sujet différent | Fond nettoyé — idem ci-dessus |
Si un utilisateur demande « la pièce avec la personne supprimée » et a l'intention de l'afficher seule, n'utilisez pas --background-output. Dites-lui qu'il a besoin d'un inpaint.
Composition typique en calques (le cas d'utilisation canonique du trou) :
<!-- z=1 le fond à alpha inversé remplit tout sauf la région du sujet -->
<video
src="fond.webm"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<!-- z=2 graphiques / texte entre les deux calques -->
<h1 id="titre" style="z-index:2; ...">FAITES-LE DANS HYPERFRAMES</h1>
<!-- z=3 le découpage replace le sujet au-dessus du titre -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
<video
src="sujet.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
C'est fonctionnellement équivalent au motif texte-derrière-sujet ci-dessous, mais vous n'avez pas besoin du presentateur.mp4 d'origine dans le projet — le fond le remplace. Utile lorsque vous souhaitez ne livrer que les deux calques transparents et laisser l'utilisateur placer du contenu arbitraire entre eux.
Format de Sortie
| Format | Quand |
|---|---|
.webm (VP9 + alpha) | Par défaut. Les compositions lisent ceci directement via <video>. |
.mov (ProRes 4444) | Montage dans DaVinci/Premiere/FCP. Fichiers volumineux. |
.png | Découpage d'image unique (sujet fixe, superposé sur un fond). |
Chrome décode nativement le VP9 alpha, donc le .webm s'intègre dans une composition comme n'importe quelle autre vidéo en lecture automatique muette — voir la compétence hyperframes pour les conventions de pistes <video>.
Préréglages de Qualité
--quality fast|balanced|best contrôle uniquement le CRF de l'encodeur VP9 — la qualité de segmentation est fixe.
| Préréglage | CRF | Quand |
|---|---|---|
fast | 30 | Itérations, fichier plus petit, correspondance de couleur lâche |
balanced | 18 | Par défaut. Visuellement identique pour la plupart des usages |
best | 12 | Version maître / livraison finale. Fichier le plus volumineux, correspondance la plus serrée |
Schémas de Composition — Choisissez le Bon
Le webm de découpage est une copie ré-encodée du RVB de la source mp4. Ce choix a des conséquences selon ce que vous placez derrière :
| Schéma | Ce qui est derrière le découpage | Résultat |
|---|---|---|
| Découpage sur une scène différente (le plus courant) | Image statique, dégradé, ou vidéo sans rapport | Superbe. Le RVB du découpage est la seule source du sujet — pas de doublement, pas de halo de bord. C'est ce pour quoi remove-background est conçu. |
| Découpage sur son propre mp4 source (texte-derrière-sujet) | Même mp4 dont le découpage a été généré | Deux sources RVB pour la même personne. Au préréglage --quality balanced par défaut (crf 18), le doublement est à peine visible ; avec --quality fast (crf 30), vous verrez un léger décalage de couleur / halo de bord. Utilisez --quality best (crf 12) pour les versions maîtres. |
| Découpage sur une autre prise de la même personne | Images de la même personne | Ressemblera à deux personnes distinctes se chevauchant. Ne faites pas cela. |
Texte-derrière-sujet (titre derrière un présentateur) :
<video
src="presentateur.mp4"
id="fond"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<h1 id="titre" style="z-index:2; ...">FAITES-LE DANS HYPERFRAMES</h1>
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
<video
src="presentateur.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
Deux règles clés :
- Enveloppez la vidéo de découpage dans un
<div>non temporisé et animez l'opacité de l'enveloppe, pas l'élément vidéo. Le framework force l'opacité à 1 sur les clips actifs (tout élément avecdata-start/data-duration), donc animer directement l'opacité de la vidéo est silencieusement ignoré. L'enveloppe n'a pas d'attributsdata-*, donc elle est gérée par votre CSS/GSAP. - Les deux vidéos utilisent
data-start="0"etdata-media-start="0"pour que le framework les décode en synchronisation à partir de t=0. Monter tardivement le découpage (data-start=3.3) introduit une recherche + préchauffage qui décale d'une image par rapport au mp4 de base — visible comme une image de désalignement au moment de l'incrustation.
Ensuite, basculez l'opacité de l'enveloppe avec GSAP au moment de l'incrustation : tl.set(cutoutWrap, { opacity: 1 }, 3.3).
TTS → Transcrive → Sous-titres
Lorsqu'il n'y a pas de voix off préenregistrée, générez-en une et retranscrivez-la pour obtenir des horodatages au niveau des mots pour les sous-titres :
npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav # → transcript.json