bitlife70/guide-vidéo-visuel

Guide Vidéo Visuel

Analyse une vidéo et crée un seul fichier de timeline (timeline.py) ; le moteur rend tous les effets, la musique et les sons par code. Aucun outil de montage ou fichier audio externe n'est utilisé.

SKILL_DIR = dossier contenant ce SKILL.md. Les scripts s'exécutent par python "$SKILL_DIR/scripts/<nom>.py".

0. Préparation

pip install -r "$SKILL_DIR/requirements.txt"   # opencv-python imageio-ffmpeg numpy scipy pillow edge-tts

ffmpeg est fourni par le bundle imageio-ffmpeg. Les polices coréennes et emoji sont détectées automatiquement dans l'OS (peut être spécifié par VGUIDE_FONT_BOLD/REGULAR/EMOJI). Le dossier de travail se trouve à côté de la vidéo : project/timeline.py, production dans project/build/, project/output/.

1. Détermination du type de vidéo → sélection du profil

python "$SKILL_DIR/scripts/analyze.py" VIDEO --out build/analysis

Lisez directement la console (Type estimé) et les build/analysis/sheets/*.jpg pour décider du type. Un PROFILE change les valeurs par défaut, et les valeurs écrites dans timeline.py ont toujours priorité.

PROFILE	Cible	Valeurs par défaut	Effets clés
screen	Enregistrement d'écran, tutoriel, démo	Musique pop, son original coupé, barre de progression	SHOTS zoom, CLICKS, LINKS, HIGHLIGHTS, CARDS, HUD, FLOW
game	Gameplay, boss, highlights	Musique épique (faible), son original activé, étalonnage cinéma, 30fps	MAGNIFY, IMPACTS, SPEED/FREEZE, POPS, CALLOUTS(@track), analyse de jauge
vlog	Quotidien, voyage, critique	Musique chill, son original activé, étalonnage chaud	CALLOUTS, STICKERS, SPEED (accéléré), sous-titres, GRADES
anim	Animation, vidéo de personnage	Musique cute, étalonnage vif	POPS (funny), STICKERS, CALLOUTS, FREEZE
promo	Publicité, promotion, voyage, film de marque	Musique épique (fort), son original coupé, 30fps	TYPE (typographie pub, tampon), CLEANUP (suppression texte original), INK transition, GLOWS, LETTERBOX, particules saisonnières, musique zen arc

Chaque type a un sujet d'explication différent :

• screen : "Que se passe-t-il quand on clique ?" → zoom sur le point de clic, flèche sur le panneau modifié, carte d'état.
• game : "Quel événement (attaque, défense, toucher, soin, pattern boss)" + fun → impacts, pop-up de réaction, loupe sur cible lointaine, arrêt sur moment clé commenté, accélération des phases ennuyeuses.
• vlog : "Où et quoi" + émotion → plutôt l'ambiance que l'explication. Ralentir et ajouter des particules sur les climax (anniversaire, voyage, remise de diplôme), accélérer les déplacements agités, figer au moment des photos + effet polaroid, fin en collage photo.
• anim : Accentuer les réactions des personnages → pop-up mignons, stickers, arrêt sur une expression clé.
• promo : "Donner envie de voir, d'acheter" → texte court et percutant (2 lignes d'ouverture → titre héro → chapitres par scène → carte de fin), transition signature (encre qui se répand) en changeant de grand chapitre, courbe d'énergie musicale (calme → montée → apogée → résonance → finale). Si la vidéo originale a du texte dans une autre langue, le supprimer et le remplacer par la langue cible (version internationale).

Règle d'édition commune (ce que les utilisateurs préfèrent) : les passages inutiles (déplacement, chargement, caméra instable) sont accélérés, les moments importants sont figés (freeze) pour ajouter une explication ou un ornement. Dès l'analyse, chaque segment est classé en "clé / transition / superflu".

2. Analyse — quand, où, quoi

Types d'événements dans events.json :

• Communs : cut (changement de scène), flash (éclair), loud (pic sonore = bruit d'impact, explosion), motion (pic de mouvement)
• screen : switch (candidat au changement après un clic/tap), big-change, scroll
• Jauge (--bar) : bar-drop/bar-big-drop (touché), bar-low (danger), bar-empty (mort), bar-rise (soin)

Pour les jeux, mesurer impérativement la barre de vie. Les instants de toucher, soin, mort sont précis à la frame.

python "$SKILL_DIR/scripts/crops.py" VIDEO --t 10,30 --box 200,940,500,100 --step 25 --out build/hp.jpg   # mesurer coordonnées jauge
python "$SKILL_DIR/scripts/analyze.py" VIDEO --out build/analysis --bar player:337,982,626,988 --bar boss:1015,911,1590,915

• Le cadre de la jauge doit être une ligne unique à l'intérieur de la barre (hauteur 4~8px). Une jauge blanche utilise par défaut light, une jauge colorée utilise :any.
• Vérifiez les bar_<nom>.png (kai-mographe : vertical = temps) dans Read pour confirmer les événements. Les clignotements rouges au moment des touches ou la disparition du HUD peuvent créer de fausses détections ; recoupez avec graph.png et les planches.
• Les planches sont espacées de 2 secondes. Pour les phases de combat, extrayez des frames toutes les 0.3~0.6 secondes pour interpréter directement l'action (attaque, roulade, toucher, transformation).

Coordonnées précises : mesurez toujours avec un crop à grille.

python "$SKILL_DIR/scripts/crops.py" VIDEO --t 7.4,13.5 --box 0,760,420,240 --out build/crops.jpg  # zone, grille 50px
python "$SKILL_DIR/scripts/crops.py" VIDEO --t 12 --full --out build/grid.jpg                    # entier, grille 100px

3. Création de timeline.py

Commencez par une recette. Copiez la recette correspondant au type dans timeline.py et remplissez uniquement les [1. valeurs à remplir] (temps, coordonnées, textes des moments clés). La structure de mise en scène validée est alors automatiquement générée. Ensuite, ajustez ou ajoutez des éléments en fonction de la vidéo après un aperçu.

Recette	Cible	Valeurs à remplir
recipes/screen_walkthrough.py	Tutoriel / démo d'écran	Clics (temps, coordonnées, texte, zone modifiée, carte), zone à souligner, sous-titres
recipes/game_boss_fight.py	Highlight combat jeu	Position jauge HP, touches (temps, HP restant), attaque, down boss, soin, mort/élimination, phases de déplacement, sous-titres commentaire
recipes/event_vlog.py	Vlog anniversaire / événement	Temps et cible du climax, phases agitées, compte à rebours photo / frame d'arrêt, apparition invités, dernière scène
recipes/promo_shorts.py	Shorts verticaux 30s (montage pub)	Liste des segments (plage source, durée sortie), panoramique par scène, mots saisonniers / texte chapitre, type de transition
recipes/promo_film.py	Film pub / promo / voyage	Copie d'ouverture, carte héro / fin, scènes (plage, vitesse, texte chapitre, tampon, caméra, particules, énergie, son fond), temps transition encre, cible brillante, texte à effacer

Les valeurs par défaut des recettes sont validées sur des vidéos réelles, donc elles fonctionnent comme dans l'exemple si laissées telles quelles (mais elles doivent être remesurées pour d'autres vidéos). Pour ajouter des éléments non présents dans la recette, référez-vous au schéma complet dans templates/timeline_template.py. S'il n'y a pas de recette adaptée, commencez par le template. Placez le fichier timeline.py de la vidéo traitée dans le dossier de cette vidéo. N'incluez pas de timeline spécifique à une vidéo (nom de personne, scène privée, contenu de travail) dans le dépôt du skill — les motifs généralisables sont transférés dans les recettes et ce document.

Règles : les temps sont toujours ceux de la vidéo source, les coordonnées sont en pixels source. SPEED et FREEZE changent la durée de sortie, mais le moteur convertit automatiquement. Pour les temps dans une zone d'arrêt, écrivez (temps source, décalage sortie en secondes) : (49.45, 1.6) = arrêt à 49.45s, 1.6s après le début de l'arrêt. Utilisé pour afficher successivement des pop-up, polaroïds, outro pendant l'arrêt.

Éléments universels (tous profils)

Élément	Usage
TRIM, SPEED, FREEZE	Découpage, accélération/ralenti (badge de vitesse, si label=None pas de badge), arrêt sur image (look desat=commentaire / photo=flash d'obturateur). L'accéléré a un flou de mouvement automatique (SPEED_BLEND)
TRACKS	Keyframes d'une cible mobile. auto=True (suivi OpenCV : personnes, animaux) / auto="match" (matching de template : objets à forme fixe comme gâteaux, panneaux, suivi avec une seule clé jusqu'à until) / follow="parent" (cible attachée à un track parent, ex. bougie sur gâteau). Référencé dans d'autres éléments par "@nom", "@nom:top"
PARTICLES	Particules confetti/hearts/sparkle/bokeh/notes/stars/snow/petals/leaves/fireflies (couleur spécifiée par ex. palette=[6]). burst (explosion unique) ou rate (continu) sur un track / coordonnée, ou plein écran (at="screen")
PHOTOS	Afficher une frame source en polaroïd (légende, angle, apparition tombante). Pour arrêt sur image ou collage d'outro
SHOTS	Caméra : zoom sur coordonnée / "full" / "fill" (remplit sans letterbox) / "@track" (zoom suivi)
MAGNIFY	Loupe : agrandissement circulaire d'une cible lointaine + ligne de connexion + étiquette
CALLOUTS	Bulle de dialogue pointant une cible (suit le track)
POPS	Pop-up texte de style impact/danger/cool/info/funny/small/party/sweet/count (numéro de compte à rebours)
STICKERS	Sticker emoji (bob/pulse)
IMPACTS	Effet d'impact hit/heavy/crit/damage/block/parry : secousse + flash + zoom punch + aberration chromatique (+ bruitage auto)
SHAKE, FLASH	Secousse / flash manuels
GRADE, GRADES	Étalonnage cinematic/warm/cool/vivid/mono/sepia/danger/dream/night (transition par segment)
SFX, SFX_VOLUME	Bibliothèque bruitages : hit boom clang pop ding scratch sad_trombone heartbeat shutter slowmo crash whoosh riser party_horn twinkle confetti / stamp temple_bell ink gliss gliss_down / sons fond avec durée "waves:8" "wind:6" "water:6" "birds:5"
SOURCE_AUDIO	Son original (ralenti : pitch descend, arrêt : silence, accéléré : volume réduit par fast_gain)
MUSIC	style pop/epic/chill/cute/zen, arc (zen : énergie par scène), start (musique à partir de ce temps), drop, end (+end_fx scratch/fade/cut), volume
MASTER_GAIN_DB	Gain final du mix (avant limiteur). Vidéos de téléphone souvent faibles, ajouter +3~5 dB
CUSTOM_LAYERS, CUSTOM_FRAME_FX, CUSTOM_SFX	Nouvel effet demandé ajouté via une fonction dans timeline.py (voir ci-dessous)
OUTPUT_SIZE, FPS, QUALITY	Résolution sortie (ex. 720p (1280, 720)), fps, CRF
CANVAS, BACKDROP	Canvas de conception. Shorts verticaux : CANVAS = (1080, 1920) + OUTPUT_SIZE = (1080, 1920). Source horizontale insérée au milieu, le vide est rempli par BACKDROP ("black", "blur", dict(kind="blur", tint=(r,g,b), amount=0.5)). Pour remplir, zoomer SHOTS par ≈ 3.16 (= 1920 / 607.5) et panoramiquer en x
SPEED_RAMP	Pour enchaîner des segments accélérés sans blanc (montage short) : transition fluide entre les segments sans revenir à 1x

Éléments publicitaires / promotionnels (script promo.py, utilisables dans tous profils)

Élément	Usage
CLEANUP	Supprimer texte, tampon, logo de la source (t0, t1, (x0,y0,x1,y1), dict(plate=(ta, tb), ref=t)). plate = frame sans texte dans la même scène → restaure l'arrière-plan (correction automatique par corrélation de phase si panoramique/zoom). mask="box" remplace toute la boîte (arrière-plan fixe). Sans plate, utilise inpainting (NS + grain papier). live=True pour texte mobile (ex. label entrant, ink="light")
TYPE	Typographie pub. "line" (copie montant mot par mot), "hero" (grand titre apparaissant par espacement + sous-titre + tampon), "chapter" (tampon frappé puis kicker + trait + titre, veil pour voile de brume derrière). Coordonnées en canvas 1920x1080, couleur color, lisibilité halo
GLOWS	Lueur de soleil/lune/lumière + flare (stries, fantômes) — suit un track
INK	Transition à l'encre (t, dict(dur, at)) : à t, l'encre couvre le plus l'écran puis se retire du centre (bruitage auto)
TYPE "slam"	Pour shorts : grand mot 'bang' sur le rythme — se voit même quand l'encre recouvre l'écran (over_ink). Tampon seal
LETTERBOX	Letterbox cinéma dict(ratio=2.39, range=(t0, t1)) — entrée et sortie douces. Les particules sont masquées sous la bande

Quand un nouvel effet est demandé — hooks personnalisés

Écrivez une fonction dans timeline.py sans modifier le moteur. ctx contient t (temps sortie), ts (temps source), raw (frame source), frame (canvas BGR actuel), view, cv (canvas overlay), tl, gfx, fx, W, H, screen("@boss"), window(t0, t1) (intervalle temps source → (alpha, progression)).

def speed_lines(ctx):                           # CUSTOM_LAYERS : dessiner overlay (pas de retour ou nouvelle frame)
    w = ctx.window(57.2, 58.4)
    if w:
        x, y = ctx.screen("@boss")
        for k in range(12):
            a = k / 12 * 6.283
            ctx.fx.draw_line(ctx.cv, (x + 300 * math.cos(a), y + 300 * math.sin(a)),
                             (x + 700 * math.cos(a), y + 700 * math.sin(a)), (255, 255, 255), 3, w[0] * 0.6)
CUSTOM_LAYERS = [speed_lines]

def red_pulse(ctx):                             # CUSTOM_FRAME_FX : modifier frame → retourner nouvelle frame
    return ctx.fx._tint(ctx.frame, (255, 0, 0), 0.15) if ctx.window(76, 78) else None
CUSTOM_FRAME_FX = [red_pulse]

def boss_roar(a):                               # CUSTOM_SFX : a = dict(buf, add, lib, tl, SR)
    a["add"](a["buf"], a["lib"]["boom"](), a["tl"].out(14.4), 0.8)
CUSTOM_SFX = [boss_roar]

Les effets fréquents sont ensuite déplacés dans fx.py pour devenir des éléments officiels.

Règles de mise en page (issues de cas réels)

Commun

• Les emojis sont rendus en couleur. Pour les symboles ▸ ✓ ✕ qui peuvent s'afficher en carré, utilisez les emojis correspondants (✅ ✖️ 👉 ⏩ ⏸) ou • → ·.
• Sous-titres : environ 40 caractères par ligne. Mettez en gras avec [crochets] pour les mots-clés. Pour un sous-titre sur un arrêt, écrivez (tf, tf, "...") (temps début = fin) pour qu'il n'apparaisse que pendant l'arrêt.
• Évitez plus de 3 pop-up, bulles, stickers simultanés. Les pop-up durent 0.8~1.2s suffisamment.

screen

• Séparez cartes et highlight dans le temps (carte → highlight). Finissez la carte avant le prochain zoom de clic.
• En zoom, si un highlight sort de l'écran, il est coupé → taux de zoom 1.15~1.3.
• Placement des étiquettes "right" (flèche), "above-right" (ligne de tableau), "below" (élément haut). HUD en mini mode (100px à gauche) si zoom ≥1.12x.

game

• Ultra-wide (21:9) entre en letterbox dans un canvas 16:9. Les bandes haute et basse contiennent les badges de vitesse et sous-titres sans masquer l'action. Pour remplir, utilisez "fill" dans SHOTS.
• Highlight de jauge : "above|nodim" — assombrir l'écran cacherait l'action.
• Zoom max 1.3~1.5x. Si l'action est rapide, un zoom trop fort fait sortir la cible. Utilisez MAGNIFY pour un agrandissement.
• Arrêt (FREEZE) : 12s, 34 fois par vidéo suffisent. Pendant l'arrêt, utilisez CALLOUTS pour montrer "qui fait quoi".
• Accélérez les phases de déplacement/chargement à SPEED 23x. Ralenti 0.30.4x seulement sur des touches/points décisifs de 0.5~1s.
• Keyframes de track : insérez-en à chaque gros mouvement de la cible ; en cas de cut de scène, écrivez deux fois la même valeur (juste avant / juste après) pour éviter les interpolations abruptes. Vérifiez avec python "$SKILL_DIR/scripts/tracks.py" timeline.py qui génère une planche.
• Repérez les instants de toucher via les événements HP et placez les IMPACTS à la frame précise. Toucher = damage/crit, attaque réussie de ma part = hit/heavy.
• Gardez le son original du jeu, réduisez la musique (volume 0.3~0.45). À la mort, utilisez MUSIC["end"] + end_fx="scratch" pour couper la musique et un bruitage humoristique comme sad_trombone.

promo (publicité, promotion, version internationale)

• Suppression de texte : choisissez une frame plate au moins 0.4s avant l'apparition ou après la disparition du texte. Sur les frames en fondu, du texte fantôme subsiste → vérifiez sur un crop à contraste augmenté (fond flou soustrait ×4). Après effacement, vérifiez les résidus/coutures sur un crop en résolution source avec --preview.
• Pour un fond qui change continuellement (brume, embruns), une plate ne correspond pas (taches grises) → utilisez l'inpainting sans plate, et placez un chapitre typographique avec veil par-dessus.
• Détection de tampon rouge : ne capte que le rouge foncé (exclut les ciels orange/cramoisi). Si le ciel est orange, vérifiez que la boîte entière n'est pas modifiée (pas de bande colorée).
• Copie courte : ouverture 24 mots × 2 lignes, titre de chapitre 25 mots, carte de fin : marque + une ligne. N'utilisez pas de slogan officiel d'organisation/marque réelle.
• Typographie à l'intérieur du letterbox (haut 140px, bas 140px exclus). L'emplacement du texte original est souvent un "ciel vide", idéal pour un chapitre.
• Musique zen : utilisez arc pour définir l'énergie par scène. Ajustez la vitesse des scènes pour que le temps de transition à l'encre tombe sur une limite de mesure (80 BPM = 3s) pour que la transition, le tambour et le tampon soient en rythme (utilisez tl.load pour afficher les temps de sortie → ajustement de vitesse). Volume par palier : calm −20 / peak −12 dB environ ; la différence doit être grande pour que l'apogée fonctionne.
• Scène décisive (déploiement d'écran, lever de soleil) : 0.751x, paysage lent : 1.52.4x. Utilisez la transition à l'encre uniquement pour les grands changements (saison, région) ; pour une même grande section, conservez la transition source.
• Shorts verticaux (30s) (recipes/promo_shorts.py) : 96 BPM (une mesure = 2.5s), une scène par mesure. Utilisez SEGMENTS = [(début source, fin source, durée sortie)] pour les enchaîner ; Remap calcule la vitesse inverse pour que les transitions tombent exactement sur les mesures. Les transitions source (fondu) sont compressées à 0.2s sous l'encre ou le flash.
  • Les 1ères secondes sont l'accroche : une ligne de copie → mesure 1 : titre de marque + impact musical. Ouverture et finale en bandes (source au milieu, typographie haut et bas), partie principale en crop vertical plein + panoramique vers le sujet (soleil/chutes/lune au centre, paysage large de gauche à droite).
  • En zones accélérées, le temps source raccourcit ; écrivez les temps de typographie en temps de sortie comme (TRIM[0], secondes de sortie). Les chapitres apparaissent rapidement avec pace=0.55.
  • Particules avec clip=True pour qu'elles s'arrêtent au cut (empêcher les pétales de passer à la saison suivante). Évitez l'interface des shorts en plaçant la typographie à l'intérieur de la zone : haut 260px, bas 420px.

vlog (vidéo de famille/événement)

• Les vidéos de téléphone sont souvent tremblantes. Accélérez les déplacements agités à 3~4x (le flou de mouvement automatique rend l'effet fluide), le son original est automatiquement réduit.
• Le climax (souffler les bougies, trinquer, but) : ralenti 0.4x + flash + confetti burst + party_horn. La musique commence à cet instant (MUSIC["start"]) — avant, gardez le son original (chanson d'anniversaire, conversation).
• Pour une photo : arrêtez sur la frame stable juste après le déclenchement (look="photo") et affichez un polaroïd. Vérifiez toujours dans l'aperçu que la frame est nette (une frame de caméra en mouvement est floue).
• Ne placez pas de stickers/pop-up/cœurs sur les visages. Mesurez les coordonnées des visages et placez-les à côté ou dans un espace vide. Pour pointer une expression (langue tirée, clin d'œil), utilisez CALLOUTS (ring=False) pour pointer depuis le côté.
• Si un compte à rebours est visible à l'écran (timer de téléphone), placez les pop-up count 3·2·1 à ces moments exacts et ajoutez un bruitage pop.
• Outro : collage de 2~3 polaroïds sur arrêt sur image + petite phrase de félicitations (remontez avec OUTRO top et stats=[]).
• Le récit doit être compréhensible même sans sous-titres ni voix off : titre d'intro + un court pop-up par scène suffisent.

4. Aperçus itératifs

python "$SKILL_DIR/scripts/build.py" timeline.py --preview 3.5,7.4,26        # temps source
python "$SKILL_DIR/scripts/build.py" timeline.py --preview-out 16.6,36.2     # temps sortie (vérification au milieu d'un arrêt/ralenti)

Lisez build/preview/sheet*.jpg dans Read pour corriger les chevauchements, coupures, occultations, erreurs de coordonnées, polices cassées. L'étiquette src ↔ out montre aussi la conversion temporelle. Les zones d'arrêt ne sont pas vérifiables en temps source ; utilisez --preview-out.

5. Audio

• Musique de fond MUSIC["style"] : pop (126BPM électro-pop), epic (96BPM taïko, cordes staccato, cuivres, chœur), chill (82BPM lo-fi), cute (132BPM marimba, pizzicato), zen (80BPM gayageum, daegeum, janggu, tambour, chœur, MUSIC["arc"] = [(temps source, "calm|flow|pulse|build|peak|hush|finale")]). Sauf zen, les structures sont : intro → A → B → build → drop → outro ; le highlight se produit au drop.
• Son original : activé par défaut pour game/vlog/anim. Il est ducké quand le narrateur parle (SOURCE_AUDIO["duck"]).
• Vérification des niveaux : pour un jeu, le son original est prioritaire. Mesurez le RMS par segment pour que la musique soit 3~5 dB plus faible que l'original, et les bruitages ne s'entendent qu'à l'impact.

  import tl, music, build; t = tl.load("timeline.py"); m = music.build_music(t)[0] * t.music["volume"]; s = build.source_audio(t, m.shape[1])
  

• Narration (optionnelle) NARRATION = [(t, "phrase")] (si absent, lit les sous-titres). --voice edge (réseau neuronal Microsoft, en ligne — prévenir que les phrases sont envoyées à Microsoft) / --voice sapi (hors ligne Windows). Dans build/voice_report.json, si rate dépasse +15% ou s'il y a overflow, réduisez la phrase (coréen ≈ 7 syllabes/s).

6. Rendu final et vérification

python "$SKILL_DIR/scripts/build.py" timeline.py [--voice edge] [--workers 8]

Les frames sont réparties sur plusieurs processus en parallèle, puis assemblées (1min 1080p ≈ 2~3min, 8 workers). Exécutez en arrière-plan.

Points à vérifier avant validation

• Dernière ligne : [done] ... Ns (expected Ns), N MB — la durée correspond-elle ? Aucun Traceback dans les logs.
• Extrayez quelques frames pour vérifier : ffmpeg -ss T -i out.mp4 -frames:v 1 f.png
• La musique et les bruitages ne peuvent être écoutés directement ; vérifiez par RMS des segments et demandez à l'utilisateur d'écouter.

Structure des fichiers

Fichier	Rôle
scripts/analyze.py	Métadonnées, estimation du type, coupes, pics sonores, événements de jauge, graphiques, planches
scripts/crops.py	Crop à grille des coordonnées source
scripts/tracks.py	Suivi de cible (interpolation keyframe, OpenCV), planche de vérification
scripts/remap.py	Remappage temporel (TRIM·SPEED·FREEZE)
scripts/build.py	Aperçu / mix audio (remappage son source, limiteur) / rendu parallèle / SRT
scripts/tl.py	Chargeur timeline.py, valeurs par défaut du profil, conversion coordonnées/temps
scripts/render.py	Caméra (suivi, secousse), couche enregistrement écran, hooks personnalisés
scripts/fx.py	Effets généraux : étalonnage, impact, loupe, bulle, pop-up, sticker, badge, ...