Communitygithub.com

JacobLinCool/video-studio-mlx

Produisez une vidéo démo/promo narrée et peaufinée de n'importe quelle application ou site web. La séquence est un enregistrement d'écran réel du produit présenté ; la narration est générée et validée par ASR via l'API High Level Studio de video-studio-mlx (/studio/tts, clonage vocal optionnel).

Qu'est-ce que video-studio-mlx ?

Ce skill permet de créer des vidéos démo professionnelles (90-180 secondes) pour tout type d'application (macOS, site web, CLI) en suivant une approche 'narration d'abord'. Il s'appuie sur l'API Studio de video-studio-mlx pour générer des voix synthétiques avec timbres cohérents et valider le texte par reconnaissance vocale automatique (ASR). Le pipeline comprend la rédaction d'un storyboard scène par scène, la génération de la narration avec timings par mot, l'enregistrement de l'écran (AppleScript pour macOS, Playwright pour le web), et la composition vidéo avec ffmpeg (transitions, effets de zoom, sous-titres, mise au point sur les éléments nommés). Le résultat final est une vidéo 1080p avec narration synchronisée, musique de fond optionnelle, et effets de focus animés basés sur les timestamps des mots. Le skill insiste sur la vérification automatique : extraction de trames pour valider les zones de focus et découpage ASR pour vérifier la synchronisation audio. Il est particulièrement utile pour les démonstrations de produits, les tutoriels narrés ou les vidéos promotionnelles nécessitant une voix off synchronisée avec des captures d'écran réelles.

Compatible avec~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/JacobLinCool/video-studio-mlx/tree/HEAD/.agents/skills/studio-demo-video

Demander à votre IA préférée

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

Documentation

Vidéo Démo Studio

Réalisez une vidéo démo narrée d'environ 90 à 180 secondes de n'importe quel produit que l'utilisateur nomme — une application macOS, un site web, un CLI, tout ce que vous pouvez enregistrer à l'écran. Le seul élément fixe est le backend de narration : l'API Studio de video-studio-mlx (POST /studio/tts) qui clone une voix et valide chaque ligne. Le sujet de la démo est arbitraire et change à chaque fois. Gardez cette séparation à l'esprit : ne présumez pas que la cible de la démo est video-studio-mlx elle-même (ce n'est qu'un exemple dans references/).

Principe fondamental : narration d'abord, ancrage temporel précis

Générez la narration avant tout enregistrement. /studio/tts renvoie la durée exacte de chaque segment et les horodatages par mot — ceux-ci pilotent toute la timeline et tous les effets de focus. Enregistrez ensuite la séquence de manière généreuse et ajustez chaque clip à son segment. Couper d'abord et ajouter la voix après impose un réajustement fragile du timing.

Vous ne pouvez généralement pas lire ou entendre le résultat. Traitez cela comme une contrainte stricte : vérifiez la vidéo en extrayant des trames, et vérifiez le contenu audio/synchronisation en exécutant une ASR sur des tranches du fichier final. Construisez tout pour qu'il puisse être vérifié de cette manière.

Pipeline

  1. Rédigez un storyboard scène par scène — texte de narration, action à l'écran, légende, et (par scène) les éléments que la narration nomme pour que le focus puisse les pointer. Visez environ 2,1 mots/seconde (≈170 mots ≈ 80s). Copiez references/storyboard.example.json vers <work>/storyboard.json. Rédigez la narration de sorte que chaque élément nommé soit effectivement visible et dans l'ordre dans l'enregistrement de cette scène. Écrivez pour l'oreille : épelez les mots tels qu'ils sont prononcés, pas écrits — développez les abréviations et acronymes (« expression régulière » pas « regex », « version trois » pas « v3 »), évitez les symboles nus (~, /, &), et écrivez les nombres/unités en toutes lettres en cas de doute. Le TTS lit le texte littéralement et l'ASR valide par rapport à celui-ci, donc les raccourcis écrits uniquement provoquent à la fois une mauvaise prononciation et un mauvais taux d'erreur (WER).
  2. Générez la narration — scripts/generate_narration.py <storyboard.json>. Envoie chaque scène à /studio/tts, en clonant chaque scène à partir d'une voix verrouillée (le ref_audio de l'utilisateur, ou une instruction voice qu'il conçoit une fois — voir ci-dessous), valide par ASR, et écrit narration/manifest.json avec duration_s, wer par segment, et words par mot. (Voir references/studio-api.md.)
  3. Enregistrez la cible — un clip par scène de l'application/site (voir Enregistrement), plus une carte des rectangles d'éléments nommés pour les éléments que le focus doit pointer.
  4. Composez — scripts/compose.py <storyboard.json> : encadre l'enregistrement sur une scène dégradée, brûle les légendes Pillow, applique des zooms lents sur les plans héroïques, applique le focus ancré à la narration (zoom + cercle), fondus enchaînés de scènes, place la narration sur la timeline calculée, muxe.
  5. Vérifiez — filmstrip de chaque scène ; extrayez une trame à chaque temps de mot parlé du focus et confirmez que le surlignage se trouve sur l'élément nommé ; ASR sur deux ou trois tranches pour confirmer que la bonne ligne tombe sur la bonne scène.

Prérequis

  • L'API Studio accessible (par défaut http://127.0.0.1:8100). La configuration, le clonage et le contrat d'alignement/horodatage des mots sont dans references/studio-api.md.
  • Un fichier wav de référence de 3 à 15 secondes (mono 24 kHz) plus sa transcription exacte pour le clonage — confirmez la transcription avec /asr d'abord (la qualité du clonage dépend de l'alignement audio↔texte, pas d'une longueur « recommandée »).
  • Une seule voix pour toute la vidéo. Chaque scène est un appel /studio/tts séparé, donc la voix ne reste cohérente que si chaque appel clone une référence partagée. Si l'utilisateur fournit une référence, clonez à partir de celle-ci ; sinon, définissez une instruction de conception voice dans le storyboard et generate_narration.py conçoit un clip à l'avance et clone chaque scène à partir de celui-ci (mis en cache, donc les ré-exécutions gardent la même voix). Sans l'un ni l'autre, chaque scène est synthétisée indépendamment et le timbre dérive entre les scènes — évitez cela pour des vidéos sérieuses.
  • ffmpeg avec avfoundation (capture macOS), zoompan, xfade, gblur. drawtext est souvent absent (pas de libfreetype) — les légendes sont rendues avec Pillow.
  • Pour les cibles web : Playwright (ou Puppeteer) pour un enregistrement déterministe + boîtes d'éléments.

Enregistrement de la cible

Chaque scène a besoin de deux choses du produit cible :

  1. un clip enregistré à l'écran (enregistrez plus long que la narration — les résultats et les spinners arrivent quelques secondes après un clic), et
  2. une carte des rectangles d'éléments nommés : pour chaque élément que la narration nommera, son rectangle en pixels d'enregistrement (l'espace de coordonnées utilisé par le clip composé).

La boîte à outils UI de la cible décide comment vous obtenez ces éléments. Deux backends :

Une application macOS — AppleScript + ffmpeg avfoundation

  • Enregistrez avfoundation "Capture screen N" et recadrez en direct sur la fenêtre de l'application. Sondez une fois (enregistrez ~1,5s, extrayez une trame, confirmez crop=W:H:X:Y). L'écran est Retina, donc le recadrage physique = DPR × logique (le DPR est généralement de 2).
  • Pilotez avec System Events. Trouvez les primitives fiables pour cette boîte à outils d'application — elles diffèrent selon l'application. Mises en garde générales qui reviennent :
    • Les clics sur les coordonnées ne fonctionnent souvent pas sur les listes SwiftUI/AppKit ; utilisez AX select/AXPress sur l'élément à la place.
    • Les contrôles segmentés s'exposent sous forme de AXRadioButton ; interrogez-les par rôle.
    • Les requêtes AX juste après un changement de vue peuvent être en conflit technologique (résultats vides) — réessayez, ou évitez complètement la navigation dans la session.
    • Si la navigation est capricieuse, relancez l'application déjà dans l'état nécessaire (via les arguments de lancement / variables d'environnement / un schéma d'URL que l'application supporte) et ne déclenchez que la seule action devant la caméra. Peu coûteux et déterministe.
  • -capture_cursor 0 (les actions AX ne déplacent pas le pointeur, donc le curseur reste hors du cadre). Pour un curseur visible, synthétisez-en un en post-production (voir Focus).
  • Carte des éléments : interrogez position+size AX de chaque élément et convertissez en px d'enregistrement : (global − origine_fenêtre) × DPR. Si la boîte à outils cache les rectangles des champs, mesurez à partir d'une trame d'enregistrement quadrillée. Fiez-vous à la trame d'enregistrement plutôt qu'aux nombres AX obsolètes s'ils diffèrent (l'état de défilement diffère) ; vérifiez chaque trame de focus.

Un site web — Playwright (recommandé par rapport à la capture d'écran)

  • Enregistrez avec recordVideo ; définissez recordVideo.size égal au viewport et normalisez le webm à votre fps avant de composer.
  • Espace de coordonnées (le piège n°1) : Playwright enregistre à la taille du viewport, donc quand recordVideo.size == viewport, les px d'enregistrement == les px CSS. deviceScaleFactor: 2 ne fait qu'affiner le rendu — cela NE met PAS à l'échelle la vidéo enregistrée, et un recordVideo.size plus grand que le viewport ne fait que remplir la zone supplémentaire de noir (la page reste en haut à gauche à 1×, elle n'est PAS agrandie pour remplir). Donc boundingBox() donne directement les px d'enregistrement — NE multipliez PAS par le DPR. (Si vous enregistrez à une taille différente, mettez à l'échelle les rectangles par taille_enregistree / viewport.) Vérifiez toujours en superposant un rectangle connu sur une trame extraite avant d'enregistrer toutes les scènes — une hypothèse erronée sur le DPR place silencieusement chaque cercle de focus au mauvais endroit.
  • Capturez chaque rectangle à une seule position de défilement stabilisée : effectuez d'abord tout le défilement, laissez-le se stabiliser, puis lisez tous les boundingBox(), puis maintenez. Les cercles vivent dans les coordonnées d'enregistrement et doivent rester collés pendant que la caméra zoome/pivote. Émettez la piste d'interaction à partir de l'horloge de la page si vous voulez un focus automatique.
  • Stabilisez d'abord la page : désactivez les animations CSS / prefers-reduced-motion, fermez les bannières de cookies, cachez la barre de défilement, et waitForLoadState('networkidle') pour que rien ne surgisse devant la caméra. Authentifiez automatiquement via un addInitScript qui sème localStorage avant la navigation, quand l'application le supporte.
  • Motion : pour les longues pages, capturez une capture d'écran pleine page et panoramiquez-la (un Ken Burns vertical) plutôt que d'enregistrer un défilement en direct saccadé.

Séquences de modèle réel — montrez la véritable sortie, cachez l'attente. Lorsqu'une scène doit exécuter un modèle lent en direct (légendes/chat/inférence en temps réel), enregistrez le flux réel mais compressez temporellement les attentes : marquez chaque fenêtre clic → résultat (une horloge monotone depuis le début de la page), puis compressez UNIQUEMENT ces fenêtres avec ffmpeg (trim+setpts+concat ; l'action reste à 1×) et figez la dernière trame (tpad=stop_mode=clone) pour que toute durée de scène se joue sur le résultat. Réchauffez d'abord le modèle avec une requête jetable — un chargement à froid peut être 10 à 40 fois plus long qu'un appel à chaud (par exemple un modèle de vision : ~38s à froid → ~5s à chaud). Épousez et chronométrez la narration sur le clip compressé ; gardez ces scènes en lecture simple (l'action porte le mouvement). Recette complète + extraits : references/playwright-recording.md.

Un exemple macOS entièrement travaillé (sélecteurs exacts, hooks d'environnement, rectangle de recadrage, rectangles d'éléments et un enregistreur clé en main) se trouve dans references/video-studio-mlx-app.md — cet exemple se trouve présenter la même application qui héberge l'API Studio, mais traitez ses spécificités comme illustratives ; votre cible aura les siennes.

Composition (scripts/compose.py)

Pilotée par configuration, agnostique à la cible. Chaque scène devient un clip 1080p normalisé : séquence mise à l'échelle dans une carte encadrée sur un fond de scène dégradé sombre (ombre douce), une légende Pillow (pastille en bas pour les étapes, grand titre+sous-titre avec voile pour les plans héroïques), fondus du clip + légende, puis une gradation finale partagée (couleur + courbe en S + ombres froides + vignettage + grain de film + dé-banding) pour que des captures disparates se lisent comme un film dirigé ("grade": false le désactive, ou passez un bloc pour régler strength/tint). Les scènes héroïques reçoivent un traitement cinématique : un fondu enchaîné Ken Burns flottant avec atténuation (ease-out) sur l'image fixe, une plaque de fond givrée et assombrie derrière la carte, et un fondu d'apparition échelonné titre-puis-sous-titre. Les clips s'enchaînent avec des transitions xfade par scène (par défaut fade ; définissez transition/xfade_dur par scène — fadeblack se lit bien dans un plan héroïque). Audio : la narration est placée via adelay sur la timeline maîtresse et mixée via amix (normalize=0) ; un fond musical music optionnel est ducké par compresseur latéral sous la VO et le mix final est masterisé loudnorm à −16 LUFS (la VO seule est également masterisée).

Effets de focus — ancrés à la narration (zoom + cercle suivent les mots)

Le focus doit pointer ce que la narration nomme, exactement au moment où elle le dit — il est donc écrit comme phrase → élément, chronométré à partir des horodatages des mots, jamais placé manuellement en secondes et jamais épinglé à un seul élément pour toute une scène. Une scène déclare une view (quelle carte de rectangles d'éléments) et une liste focus (les noms d'éléments/vues sont ceux de votre application cible) :

"view": "principale",
"focus": [
  { "say": "recherche",   "element": "champ_recherche" },
  { "say": "résultats",  "element": "liste_resultats" },
  { "say": "générer", "element": "bouton_principal", "zoom": 1.7 }
]

Comment compose le résout :

  • Quand — resolve_phrase trouve la séquence contiguë de mots correspondant à say dans les words du segment et retourne [début,fin]. Les mots répétés ne sont pas ambigus : la liste des mots est positionnelle — choisissez par occurrence (par défaut la première). Joue au temps du clip lead + début_mot.
  • Où — element est un rectangle dans elements.json sous la view de la scène (ou une map:key pour référencer une carte partagée, par exemple une barre latérale persistante).
  • Caméra — zoompan multi-keyframes (focus_camera), smoothstep absolu basé sur on. Entre deux focus, elle glisse directement cible→cible par défaut ; elle ne revient à la vue complète que lorsque la cible suivante est À LA FOIS loin (en dehors du viewport zoomé précédent) ET l'écart est long (focus_gap_full, ~2,2s) — ainsi un élément adjacent/déjà visible ne fait que pivoter un peu au lieu d'un zoom arrière/zoom avant brusque. Les mouvements de caméra sont à vitesse constante (durée = distance ÷ focus_pan_speed px/s, plancher par focus_move_min) : la caméra maintient le cadrage précédent, puis glisse à un nombre fixe de px/s en arrivant au début du mot suivant — les mouvements proches et lointains se ressentent de la même manière, pas « lent puis rapide ». "focus_pan": true force le glissement direct partout.
  • Cercle — dessiné dans les coordonnées d'enregistrement avant la caméra, donc il reste collé à l'élément pendant le zoom/pivotement ; fondu d'apparition/disparition autour de la phrase.
  • Le zoom et le cercle sont découplés et le zoom se verrouille automatiquement pour s'ajuster (fit_zoom) : le zoom est réduit pour que l'élément surligné reste entièrement cadré, et une cible large passe en cercle uniquement (z=1) pour ne pas être recadrée. Ne les associez pas par défaut — les deux n'existent que pour attirer l'œil ; choisissez ce qui convient à la taille de la cible. ring:false donne un zoom doux sans cercle.

Données de support et extensions :

  • Carte des éléments (elements.json) : rectangles nommés par vue en px d'enregistrement. Voir Enregistrement pour savoir comment les obtenir ; vérifiez en contrôlant chaque trame de focus.
  • Capturez plus grand que vous ne présentez pour que le zoom reste net — la caméra recadre l'enregistrement natif à la taille sur scène, donc ~1,7× a encore des pixels réels. Sur macOS, la capture Retina sur-échantillonne déjà. Sur le web, deviceScaleFactor n'AGRANDIT PAS la vidéo enregistrée (voir Enregistrement) — pour obtenir un sur-échantillonnage, enregistrez à un viewport/recordVideo.size plus grand que la carte sur scène (par exemple capturez en 1920 de large, présentez dans une carte ~1456), pas en augmentant le DPR.
  • L'enregistreur peut émettre une piste d'interaction (emit_track.py) pour que track_to_effects dérive automatiquement un zoom+cercle par clic ; focus en ligne est le chemin précis. La structure est ouverte pour les superpositions de cursor/spotlight utilisant les mêmes rectangles + horodatages de mots.

Note de conception (pourquoi phrase→élément, pas des marqueurs de repère côté API) : les horodatages des mots sont déjà une liste positionnelle, donc le compositeur possède « quel élément / quelle occurrence » — l'API Studio reste une primitive propre (audio + horodatages de mots) utilisable pour démontrer n'importe quel produit. La séquence doit effectivement montrer l'élément nommé (non défilé/statique) à ce moment-là ; rédigez la narration en conséquence.

Calcul de la timeline (gardez la vidéo et l'audio cohérents)

  • durée de la scène d_i = narration_i + pad_i (pad ≈ 2 step / 3.4 héroïque).
  • début de la scène sur la master est accumulé par transition : start_0 = 0, start_i = start_(i−1) + d_(i−1) − T_i, où T_i est la durée xfade DANS la scène i (xfade_dur par scène, par défaut xfade ; clampé en dessous des deux clips adjacents). Avec chaque T_i = T, cela se réduit à Σ d_(<i) − i·T.
  • placez la narration i à start_i + lead (lead ≈ 0,8, après le fondu enchaîné entrant) — le même start_i recalculé, donc l'audio reste synchronisé. Assurez-vous que tin_i + d_i ≤ la longueur du clip source.

Vérification (vous ne pouvez pas entendre le résultat — vérifiez-le)

...

[Le contenu a été tronqué dans l'entrée originale ; le reste markdown n'étant pas fourni, la traduction s'arrête ici.]

Skills associés