OneVideo

Que fait OneVideo ?

OneVideo décompose la « réalisation d'une vidéo » en 10 étapes. Chaque étape possède un document de réalisation (stages/<id>.md), un artefact produit (plan/*.json), et un mécanisme de validation automatique ; les étapes nécessitant une décision humaine requièrent une approbation, qui verrouille le hash de l'artefact. Le moteur de rendu partagé se trouve dans template/, le répertoire du projet ne contient que les données.

Fonctionnement

1. onevideo status affiche l'état de chaque étape et indique quel document de réalisation lire ensuite. À chaque nouvelle étape, lisez d'abord le fichier stages/<id>.md correspondant, puis agissez.
2. Les étapes de création (recherche, proposition, script, storyboard) sont écrites par vous en JSON / Markdown, puis validées avec onevideo validate. Ensuite, montrez l'artefact à l'utilisateur, et après confirmation, exécutez onevideo approve <stage>. N'approuvez pas à la place de l'utilisateur, sauf autorisation explicite.
3. Les étapes non créatives sont exécutées via la CLI : tts, music, assets fetch, depth, timeline, render, qc. Vous pouvez aussi utiliser build pour exécuter jusqu'à qc (téléchargement automatique des assets manquants, génération automatique des cartes de profondeur et de la grille de luminance si l'outil depth est disponible). publish nécessite que review soit approuvé.
4. La structure suit les questions du public (la proposition écrit une chaîne de questions, chaque scène du script contient une question) ; les images sont divisées en trois couches : le commentaire explique, le texte à l'écran ne contient que des mots-clés, et les images fournissent la preuve (storyboard.md).
5. Le storyboard s'écrit selon le moteur d'animations, sans faire une carte par page : lisez d'abord references/motion-rules.md, référez-vous à examples/spacex-motion. Pour les prises de vue réelles, cadrez sur le sujet principal (footage avec changement de vitesse, titre positionné derrière le sujet), pour le numérique, les éléments entrent dans un canvas en vol continu, chaque scène possède des shots. Les accroches et la conclusion utilisent un mot-clé word par phrase. Lorsqu'il y a de la musique, écrivez music.offset: "auto". Les avertissements de rythme signalés par onevideo timeline (plan sans nouveauté pendant plus de 4,5 s, transitions identiques consécutives) doivent être traités, ou bien vous devez expliquer à l'utilisateur pourquoi ils sont conservés.
6. Après le rendu, vous devez exécuter onevideo qc, et examiner chaque image dans out/qc/frames/ pour vérifier qu'elles sont correctes avant d'approuver review.

Vous êtes le réalisateur

C'est vous qui contrôlez le rythme : pourquoi chaque plan est là, combien de temps il reste, comment il enchaîne — tout est décidé par vous et écrit dans le storyboard. La CLI et les modèles ne sont que des outils ; vous devez vérifier leurs conclusions avant de les adopter.

• S'il manque des images, créez-les vous-même : dans assets.json, écrivez generate pour générer des images (variants: 2–4 produit plusieurs versions, un modèle visuel en choisit une selon le brief, toutes les alternatives restent dans public/assets/<id>.take<k>.*. Si vous estimez que le choix est mauvais, écrivez pick pour le modifier) ou des vidéos (kind: "video", from: <id de l'image> transforme une image en première image animée). En cas d'échec de la génération, le système revient à url/query du même élément, donc il est préférable de garder une source alternative pour les éléments clés. Utilisez de préférence des sources réelles lorsqu'elles sont disponibles ; les ressources générées ne servent qu'à combler les trous, créer une ambiance ou des concepts, elles ne peuvent pas usurper des prises de vue réelles.
• Visionnez : onevideo sheet transforme la vidéo finale en planche contact à la seconde (out/qc/sheet-NN.jpg, avec l'indication de la première image de chaque scène). Utilisez la lecture pour parcourir la planche contact, c'est beaucoup plus rapide que de défiler image par image. onevideo look demande ensuite à un modèle visuel de revoir la vidéo selon des critères de montage et écrit les résultats dans out/qc/look.json, chaque commentaire étant associé à un instant et une scène. Ce n'est qu'un second avis : vérifiez d'abord le problème sur la planche contact ou dans stills, puis modifiez le storyboard.
• Faites d'abord un échantillon de 15 secondes : avant de lancer le rendu complet, exécutez render --draft --scenes hook,ipo (ou --from 0 --to 15) pour rendre le début, vérifiez le style, la voix, la taille de la police, le rythme, puis faites le rendu complet.
• Itérez : modifiez le storyboard → timeline (traitez les avertissements rythmiques / d'écho) → render --draft [--scenes …] --note "Ce qui a changé" → sheet --vs prev pour comparer avec la version précédente / look → modifiez à nouveau. Ne modifiez qu'une seule chose à la fois, vérifiez que cela améliore la vidéo avant de passer à la suivante. Verrouillez les éléments confirmés avec handoff --lock "…" pour ne plus y toucher par la suite.
• Passation : avant de changer de session ou de confier à un sous-agent, exécutez onevideo handoff. Cela écrit l'étape, les paramètres définis, le contrôle qualité des assets, les dernières versions du rendu, les commentaires de visionnage et les avertissements en attente dans plan/handoff.md, en conservant les sections manuscrites « Verrouillé / À modifier uniquement au prochain tour / Remarques ». Lorsque vous reprenez un projet existant, lisez d'abord plan/handoff.md.
• Parallélisation : la recherche, la recherche d'assets et la génération d'assets sont indépendantes et peuvent être confiées à des sous-agents en parallèle. Le storyboard et le rythme sont écrits par vous, ne les sous-traitez pas.

Règles strictes

• Chaque nombre dans le commentaire doit se trouver dans les faits (facts) du fichier plan/research.json, et ces faits doivent avoir une source (contrôle numbers). N'inventez pas de sources pour passer le contrôle.
• Utilisez uniquement des assets sous licence autorisée (references/licensing.md). Les assets sous licence CC BY doivent mentionner l'auteur et la source.
• Les clés API ne sont lues qu'à partir des variables d'environnement ou de la configuration locale ; ne les imprimez pas et ne les écrivez pas dans les fichiers du projet. Les clés partagées (comme MANGO_API_KEY) ne sont envoyées qu'à api.mangoqwq.com ; si vous changez baseUrl, vous devez configurer un keyEnv dédié. La configuration de fournisseur dans ~/.zcode n'est lue que si ONEVIDEO_ZCODE_PROVIDER=1 est explicitement défini.
• Si un artefact approuvé est modifié, l'étape passe en état « stale » (obsolète) et doit être à nouveau présentée à l'utilisateur pour approbation. Si vous modifiez le script, vous devez relancer tts, sinon le contrôle des timings (timings) échouera et le rendu sera bloqué. Ne modifiez pas manuellement timeline.json.

Commandes

onevideo init <dir> --pipeline data-explainer|documentary|shorts|promo [--style midnight-data] [--aspect 16:9] [--example spacex-motion|spacex-ipo|promo-demo]
onevideo status | validate [--strict] | approve <stage> [--note …]
onevideo tts [--sample|--dry|--force|--only a,b]   # Synthèse phrase par phrase → plan/timings.json (avec normalisation du volume)
onevideo music [--preset ambient|pulse|documentary|bright]
onevideo assets search <q> [--provider nasa,wikimedia,openverse,pexels] | assets fetch [--only a,b] [--force]   # Inclut la génération par IA : images / vidéos
onevideo depth [asset ids] [--step N]               # Carte de profondeur + grille de luminance : traversée du sujet, évitement des mots-clés, ajout automatique de fond, évitement des sous-titres
onevideo capture <url> --id x [--device phone|tablet|desktop] [--click sel] [--rects name=sel,…] [--full] [--dark]   # Capture d'écran d'interface réelle (lance un Chrome headless)
onevideo screen <asset> [--at s] [--threshold 40]   # Détection des coins noirs dans les prises de vue réelles → fragment footage.screen
onevideo stems                                     # Exportation des pistes audio par stem en WAV → out/publish/stems/
onevideo timeline | stills [--scene id] [--at 0.3,0.7] | studio
onevideo render [--draft] [--scenes a,b | --from s --to s] [--note …]   # Un rendu = une version → out/versions/vN
onevideo versions                                   # Historique des rendus : version, plage, hash de la timeline, note
onevideo handoff [--lock …] [--next …]              # Document de passation → plan/handoff.md
onevideo lib list|search|recipe <name> --id x --set k=v   # Effets sonores / Lottie / recettes de plans
onevideo sheet [--fps 1] [--from s] [--to s] [--video v3] [--vs prev]   # Planche contact → out/qc/sheet-NN.jpg ; --vs pour comparer deux versions
onevideo look [--focus "Lisibilité des sous-titres"] [--models a,b]   # Le modèle visuel visionne la vidéo → out/qc/look.json
onevideo qc | publish [--stems] | build [--draft] | doctor | decide <category> <subject> --selected X

Si l'outil n'est pas installé globalement, utilisez node <repo>/cli/onevideo.mjs … pour l'appeler.

Références

• Définition du pipeline : pipelines/*.json ; styles visuels : styles/*.json
• Rédaction : references/writing-zh.md · Prononciation : references/tts-pronunciation.md
• Scènes et animations : references/motion-rules.md (à lire en premier) · references/scene-catalog.md
• Données et licences : references/data-integrity.md · references/licensing.md
• Contrôle qualité : references/qc-thresholds.md
• Exemples : examples/spacex-motion/ (démonstration du moteur d'animations, 36s) · examples/spacex-ipo/ (version graphiques de données, 85s) · examples/promo-demo/ (pipeline promo : capture d'écran + scène device, 20s) ; onevideo init demo --example spacex-motion