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
- 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.jsonvers<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). - 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 (leref_audiode l'utilisateur, ou une instructionvoicequ'il conçoit une fois — voir ci-dessous), valide par ASR, et écritnarration/manifest.jsonavecduration_s,werpar segment, etwordspar mot. (Voirreferences/studio-api.md.) - 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.
- 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. - 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 dansreferences/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
/asrd'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/ttssé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 conceptionvoicedans le storyboard etgenerate_narration.pyconç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.drawtextest 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 :
- 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
- 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, confirmezcrop=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/AXPresssur 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.
- Les clics sur les coordonnées ne fonctionnent souvent pas sur les listes SwiftUI/AppKit ; utilisez AX
-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+sizeAX 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éfinissezrecordVideo.sizeégal auviewportet 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: 2ne fait qu'affiner le rendu — cela NE met PAS à l'échelle la vidéo enregistrée, et unrecordVideo.sizeplus 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). DoncboundingBox()donne directement les px d'enregistrement — NE multipliez PAS par le DPR. (Si vous enregistrez à une taille différente, mettez à l'échelle les rectangles partaille_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, etwaitForLoadState('networkidle')pour que rien ne surgisse devant la caméra. Authentifiez automatiquement via unaddInitScriptqui sèmelocalStorageavant 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_phrasetrouve la séquence contiguë de mots correspondant àsaydans leswordsdu segment et retourne [début,fin]. Les mots répétés ne sont pas ambigus : la liste des mots est positionnelle — choisissez paroccurrence(par défaut la première). Joue au temps du cliplead + début_mot. - Où —
elementest un rectangle danselements.jsonsous laviewde la scène (ou unemap:keypour référencer une carte partagée, par exemple une barre latérale persistante). - Caméra —
zoompanmulti-keyframes (focus_camera), smoothstep absolu basé suron. 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_speedpx/s, plancher parfocus_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": trueforce 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:falsedonne 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,
deviceScaleFactorn'AGRANDIT PAS la vidéo enregistrée (voir Enregistrement) — pour obtenir un sur-échantillonnage, enregistrez à unviewport/recordVideo.sizeplus 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 quetrack_to_effectsdérive automatiquement un zoom+cercle par clic ;focusen ligne est le chemin précis. La structure est ouverte pour les superpositions decursor/spotlightutilisant 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_iest la durée xfade DANS la scènei(xfade_dur par scène, par défautxfade; clampé en dessous des deux clips adjacents). Avec chaqueT_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êmestart_irecalculé, donc l'audio reste synchronisé. Assurez-vous quetin_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.]