Communitygithub.com

shinyobjectz/reactable

Prétraitement d'actifs pour les compositions HyperFrames — synthèse vocale (Kokoro), transcription audio/vidéo (Whisper) et suppression d'arrière-plan pour incrustations transparentes (u2net).

Qu'est-ce que reactable ?

Ce skill regroupe trois commandes CLI essentielles pour préparer des actifs multimédia destinés aux compositions HyperFrames : la synthèse vocale via Kokoro-82M (sans clé API), la transcription audio/vidéo avec Whisper (générant un transcript avec timestamps mot par mot) et la suppression d'arrière-plan via u2net pour produire des vidéos ou images transparentes. Chaque commande télécharge son modèle d'IA localement lors de la première exécution et le met en cache dans `~/.cache/hyperframes/`. Le skill est conçu pour fonctionner avec les outils de développement comme Claude Code, Cursor ou Codex, permettant aux agents IA de générer des voix off, sous-titrer des discours ou créer des incrustations transparentes. Il offre un contrôle précis sur les voix TTS (54 voix multilingues), la taille des modèles Whisper (de `tiny` à `large-v3`), et la qualité de compression VP9. Une attention particulière est portée à la règle de langue pour la transcription : il ne faut jamais utiliser les modèles `.en` pour des langues non anglaises, car ils traduiraient silencieusement l'audio au lieu de le transcrire. Le skill supporte également le chaînage TTS → Transcription → Sous-titres pour générer des légendes à partir de scripts textuels.

Compatible avec~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shinyobjectz/reactable/tree/HEAD/skill/vendored/hyperframes-media

Demander à votre IA préférée

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

Aperçu

Depuis le README du skill

Documentation

Prétraitement multimédia HyperFrames

Trois commandes CLI qui produisent des actifs pour les compositions : tts (parole), transcribe (timestamps) et remove-background (vidéo transparente). Chacune télécharge un modèle à la première exécution et le met en cache dans ~/.cache/hyperframes/. Déposez la sortie dans le projet, puis référencez-la depuis le HTML de la composition — voir le skill hyperframes pour les conventions des éléments audio/vidéo.

Synthèse vocale (tts)

Générez de l'audio de parole localement avec Kokoro-82M. Pas de clé API.

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

Associez la voix au contenu. La voix par défaut est af_heart.

Type de contenuVoixPourquoi
Démo produitaf_heart/af_novaChaleureux, professionnel
Tutoriel / guideam_adam/bf_emmaNeutre, facile à suivre
Marketing / promotionaf_sky/am_michaelÉnergique ou autoritaire
Documentationbf_emma/bm_georgeAnglais britannique clair, formel
Décontracté / socialaf_heart/af_skyAccessible, 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. Le 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 — intros, transitions, contenu dynamique
  • 1.5+ — rarement approprié ; tester avec soin

Scripts longs

Pour plus de quelques paragraphes, écrivez dans un fichier .txt et passez le chemin. Les entrées de plus d'environ 5 minutes de discours peuvent bénéficier d'une segmentation.

Prérequis

Python 3.8+ avec kokoro-onnx et soundfile (pip install kokoro-onnx soundfile). Modèle téléchargé lors de la première utilisation (~311 Mo + ~27 Mo de voix, mis en cache dans ~/.cache/hyperframes/tts/).

Transcription (transcribe)

Produisez un transcript.json normalisé avec des timestamps au niveau du mot.

npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt          # importer 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 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.

  1. Langue connue et non anglaise → --model small --language <code> (pas de suffixe .en)
  2. Langue connue et anglaise → --model small.en
  3. 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èleTailleVitesseQuand l'utiliser
tiny75 MoLe plus rapideAperçus rapides, test du pipeline
base142 MoRapideCourts clips, audio clair
small466 MoModéréePar défaut — la plupart des contenus
medium1,5 GoLenteContenu important, audio bruité, musique
large-v33,1 GoLa plus lenteQualité de 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 de l'API OpenAI/Groq, voir 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 remplacements de sous-titres ; il est facultatif pour la rétrocompatibilité.

[
  { "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
  { "id": "w1", "text": "world.", "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) se superpose de manière transparente dans une composition.

npx hyperframes remove-background subject.mp4 -o transparent.webm  # par défaut : VP9 alpha WebM
npx hyperframes remove-background subject.mp4 -o transparent.mov   # ProRes 4444 (montage)
npx hyperframes remove-background portrait.jpg -o cutout.png       # découpe d'image unique
npx hyperframes remove-background subject.mp4 -o subject.webm \
  --background-output plate.webm                                   # les deux couches en un seul passage
npx hyperframes remove-background subject.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 environ 168 Mo de poids dans ~/.cache/hyperframes/background-removal/models/.

Séparation des couches (--background-output)

Passez --background-output (ou -b) pour émettre une deuxième vidéo transparente à côté du cutout : même source RGB, alpha est 255 − masque au lieu de masque. Le cutout est le sujet avec un arrière-plan transparent ; la plaque est le décor d'origine avec un trou transparent là où se trouvait le sujet.

FichierAlpha est…Utilisation
-o subject.webmLe masque — sujet opaque, arrière-plan transparentCouche de premier plan, placez dessus
--background-output plate.webmInverse — décor opaque, région du sujet transparenteCouche de fond ; placez du texte ou des graphiques entre cette et le sujet

Les deux sorties partagent le même préréglage --quality et proviennent d'un seul passage d'inférence — le coût d'encodage double approximativement, le coût de segmentation reste le même. Valable uniquement pour les entrées vidéo et les sorties .webm/.mov.

Plaque avec trou, pas une plaque nettoyée par inpainting. La région du sujet dans plate.webm est entièrement transparente — compositez quelque chose d'opaque en dessous pour combler le trou. Le seul test pour savoir si --background-output est le bon outil : est-ce que quelque chose sera jamais visible à travers la silhouette du sujet à l'endroit où le sujet se trouvait ?

Cas d'utilisationOutil approprié
Texte/graphiques entre le cutout et la plaque (raison d'être de cette commande)Trou (--background-output)
Sujet sur une scène non liéeJuste subject.webm ; ignorez la plaque
Montrer la pièce sans la personne, seule sur aucun autre contenuPlaque nettoyée — nécessite un inpaint (LaMa, ProPainter, E2FGVI). Pas cette commande.
Remplacer le sujet par un sujet différentPlaque nettoyée — idem ci-dessus

Si un utilisateur demande "la pièce avec la personne supprimée" et prévoit de l'afficher seule, n'utilisez pas --background-output. Dites-lui qu'il a besoin d'un inpaint.

Composition en couches typique (le cas d'utilisation canonique du trou) :

<!-- z=1 la plaque alpha inverse remplit tout sauf la région du sujet -->
<video
  src="plate.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; ...">MAKE IT IN HYPERFRAMES</h1>

<!-- z=3 le cutout remet le sujet au-dessus du titre -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
  <video
    src="subject.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

Ceci est fonctionnellement équivalent au motif texte-derrière-sujet ci-dessous, mais vous n'avez pas besoin du fichier presenter.mp4 original dans le projet — la plaque le remplace. Utile lorsque vous souhaitez livrer uniquement les deux couches transparentes et laisser l'utilisateur placer du contenu arbitraire entre elles.

Format de sortie

FormatQuand
.webm (VP9 + alpha)Par défaut. Les compositions le lisent directement via <video>.
.mov (ProRes 4444)Montage dans DaVinci/Premiere/FCP. Fichiers volumineux.
.pngDécoupe 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 le skill hyperframes pour les conventions de piste <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églageCRFQuand
fast30Itérations, fichier plus petit, correspondance de couleur moins stricte
balanced18Par défaut. Visuellement identique pour la plupart des usages
best12Version maître / livraison finale. Fichier le plus volumineux, correspondance la plus stricte

Motifs de composition — choisissez le bon

Le webm du cutout est une copie ré-encodée du RGB de la source mp4. Ce choix a des conséquences selon ce que vous placez derrière :

MotifCe qui se trouve derrière le cutoutRésultat
Cutout sur une scène différente (le plus courant)Image statique, dégradé ou vidéo non liéeSuperbe. Le RGB du cutout est la seule source du sujet — pas de doublon, pas de halo de bord. C'est pour cela que remove-background a été conçu.
Cutout sur son propre mp4 source (texte-derrière-sujet)Le même mp4 que celui à partir duquel le cutout a été généréDeux sources RGB pour la même personne. Avec --quality balanced par défaut (crf 18), le doublon 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îtresses.
Cutout sur une prise différente de la même personneSéquence du même sujetRessemblera à deux personnes distinctes qui se chevauchent. Ne faites pas cela.

Texte-derrière-sujet (titre derrière un présentateur) :

<video
  src="presenter.mp4"
  id="bg"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>
<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
  <video
    src="presenter.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

Deux règles clés :

  1. Enveloppez la vidéo du cutout dans un <div> non temporisé et animez l'opacité de l'élément enveloppe, pas de l'élément vidéo. Le framework force l'opacité :1 sur les clips actifs (tout élément avec data-start/data-duration), donc animer directement l'opacité de la vidéo est silencieusement remplacé. L'élément enveloppe n'a pas d'attributs data-*, il est donc contrôlé par votre CSS/GSAP.
  2. Les deux vidéos utilisent data-start="0" et data-media-start="0" afin que le framework les décode en synchronisation à partir de t=0. Monter le cutout tardivement (data-start=3.3) introduit une recherche + un échauffement qui aboutit à une image de décalage par rapport au mp4 de base — visible comme une image de désalignement au moment du cut.

Ensuite, inversez l'opacité de l'élément enveloppe avec GSAP au moment du cut : tl.set(cutoutWrap, { opacity: 1 }, 3.3).

TTS → Transcription → Sous-titres

Lorsqu'il n'y a pas de voix pré-enregistrée, générez-en une et retranscrivez-la pour obtenir des timestamps au niveau du mot pour les sous-titres :

npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav   # → transcript.json

Le résultat est un tableau normalisé de mots avec timestamps (start, end en secondes) qui peut être injecté dans la composition comme données de sous-titres. Pour plus de détails sur le format de transcription et les techniques de sous-titrage avancées, voir hyperframes/references/transcript-guide.md.

Skills associés