Prétraitement des médias HyperFrames
Trois commandes CLI qui produisent des assets pour les compositions : tts (parole), transcribe (horodatage) et remove-background (vidéo transparente). Chacune télécharge un modèle au premier lancement et le met en cache sous ~/.cache/hyperframes/. Placez la sortie dans le projet, puis référencez-la depuis le HTML de la composition — voir le skill hyperframes pour les conventions relatives aux éléments audio/vidéo.
Synthèse vocale (tts)
Générez de la parole localement avec Kokoro-82M. Aucune clé API 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, liste complète
Sélection de la voix
Adaptez la voix au contenu. La voix par défaut est af_heart.
| Type de contenu | Voix | Pourquoi |
|---|---|---|
| Démo produit | af_heart/af_nova | Chaleureuse, professionnelle |
| Tutoriel / guide | 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é / réseaux | 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 quand 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 forcer 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 pour les langues non anglaises nécessite espeak-ng au niveau 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 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 se télécharge lors de la première utilisation (~311 Mo + ~27 Mo de voix, mis en cache dans ~/.cache/hyperframes/tts/).
Transcription (transcribe)
Produisez un fichier transcript.json normalisé avec horodatage mot par mot.
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt # importer un fichier existant
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 précise 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 | Très rapide | Aperçus rapides, tests de pipeline |
base | 142 Mo | Rapide | Petits 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 | Très 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 script de nettoyage JS, les règles de réessai et le chemin d'importation via l'API OpenAI/Groq, consultez hyperframes/references/transcript-guide.md.
Format de sortie
Les compositions consomment un tableau plat d'objets mot. 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 facultatif 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 afin que le sujet (généralement une personne — avatar, présentateur, tête parlante) apparaisse 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écoupe d'une seule image
npx hyperframes remove-background sujet.mp4 -o sujet.webm \
--background-output fond.webm # les deux couches 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). Le premier lancement télécharge ~168 Mo de poids dans ~/.cache/hyperframes/background-removal/models/.
N'utilisez PAS u2net pour les autocollants détourés avec un contour blanc
remove-background (u2net) est une segmentation d'objet saillant — il segmente le corps du sujet et coupe le contour blanc de la découpe, car le trait blanc autour de la figure n'est pas « l'objet ». Pour les autocollants de messagerie transparents (Telegram, etc.) rendus avec un contour blanc sur un arrière-plan plat de couleur connue, incrustez l'arrière-plan au lieu de segmenter le sujet :
- Remplissage par diffusion de l'arrière-plan plat.
ImageDraw.floodfillde PIL amorcé à partir de points le long des quatre bords (pas ~24px), marquez les pixels remplis → alpha 0, tout le reste opaque. Cela préserve le contour blanc ET les accessoires intérieurs de même couleur ET les îlots déconnectés (une tasse volante séparée du corps garde son propre contour). Nécessite que le prompt de génération place le sujet sur un arrière-plan plat et uniforme et demande explicitement le contour blanc de la découpe. - Variante sans contour (plus propre qu'un retrait de contour intégré) : exécutez à nouveau chaque image par image-to-image — passez le rendu final comme
--refet invitez « recréer pose/propriétés identiques mais SUPPRIMER le contour blanc et placer sur un fond vert pur chroma-key (#00b140) », puis incrustez le vert avec une incrustation chroma douce, jamais un masque binaire (alpha = clip((HIGH-(G-max(R,B)))/(HIGH-LOW),0,1), LOW≈30 HIGH≈95, plus déversement globalG = min(G, max(R,B))). Un remplissage par diffusion binaire + érosion produit des bords en escalier / crénelés — floutez l'alpha binaire (GaussianBlur(0.8)) pour un bord lisse au lieu d'éroder. - Dimensionnement pour les autocollants de messagerie : rognez sur la boîte englobante alpha pleine et redimensionnez le côté long exactement à la cible (par exemple 512) — ne remplissez pas pour obtenir un carré de 512² (cela laisse le sujet petit avec de l'espace vide autour).
Ne s'applique PAS à : les découpes humaines pour incrustations vidéo (u2net est correct ici) ; les œuvres sans contour de découpe ; les sujets sur un arrière-plan non uniforme / chargé (le remplissage par diffusion nécessite une couleur clé plate).
Séparation des couches (--background-output)
Passez --background-output (ou -b) pour émettre une deuxième vidéo transparente en parallèle de la découpe : même source RVB, alpha est 255 − masque au lieu de masque. La découpe est le sujet avec un fond transparent ; le fond est l'environnement d'origine avec un trou transparent là où se trouvait le sujet.
| Fichier | Alpha est… | Utilisation |
|---|---|---|
-o sujet.webm | Le masque — sujet opaque, arrière-plan transparent | Couche de premier plan, à placer par-dessus |
--background-output fond.webm | Inverse — environnement opaque, région du sujet transparente | Couche 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 l'outil approprié : est-ce que quoi que ce soit sera visible à travers la silhouette du sujet là où le sujet se trouvait ?
| Cas d'utilisation | Outil approprié |
|---|---|
| Texte/graphiques entre la découpe et le fond (raison d'être de cette commande) | 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 inpaintor (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 sans la personne » et a l'intention de l'afficher seule, n'utilisez pas --background-output. Dites-lui qu'il a besoin d'un inpaintor.
Composition superposée typique (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 couches -->
<h1 id="headline" style="z-index:2; ...">FAITES-LE DANS HYPERFRAMES</h1>
<!-- z=3 la découpe replace le sujet par-dessus le 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>
Cela est fonctionnellement équivalent au motif texte-derrière-le-sujet ci-dessous, mais vous n'avez pas besoin du fichier presentateur.mp4 original dans le projet — le fond le remplace. Utile lorsque vous souhaitez fournir uniquement les deux couches transparentes et laisser l'utilisateur placer du contenu arbitraire entre elles.
Format de sortie
| Format | Quand |
|---|---|
.webm (VP9 + alpha) | Par défaut. Les compositions le lisent directement via <video>. |
.mov (ProRes 4444) | Montage dans DaVinci/Premiere/FCP. Fichiers volumineux. |
.png | Découpe d'image unique (sujet fixe, superposé sur un fond). |
Chrome décode le VP9 alpha nativement, donc le .webm s'intègre dans une composition comme n'importe quelle autre vidéo en lecture automatique muette — voir le skill hyperframes pour les conventions de pistes <video>.
Préréglages de qualité
--quality fast|balanced|best contrôle uniquement le CRF du codeur VP9 — la qualité de segmentation est fixe.
| Préréglage | CRF | Quand |
|---|---|---|
fast | 30 | Itération, fichier plus petit, correspondance couleur lâche |
balanced | 18 | Par défaut. Visuellement identique pour la plupart des usages |
best | 12 | Version finale / maître. Fichier le plus volumineux, correspondance la plus serrée |
Motifs de composition — choisissez le bon
Le webm découpé est une copie ré-encodée du RVB de la source mp4. Ce choix a des conséquences en fonction de ce que vous placez derrière :
| Motif | Ce qui se trouve derrière la découpe | Résultat |
|---|---|---|
| Découpe sur une scène différente (le plus courant) | Image statique, dégradé ou vidéo sans rapport | Rendu excellent. Le RVB de la découpe est la seule source du sujet — pas de doublement, pas de halo de bord. C'est à cela que sert remove-background. |
| Découpe sur son propre fichier source mp4 (texte-derrière-le-sujet) | Même mp4 à partir duquel la découpe a été générée | Deux sources RVB pour la même personne. Avec --quality balanced (crf 18) par défaut, le doublement est à peine visible ; avec --quality fast (crf 30), vous verrez un léger décalage de couleur / un halo de bord. |
...
[Le contenu des sections sur les autocollants de messagerie et la composition a été tronqué dans l'original, mais les parties essentielles sont traduites ci-dessus.]