Export (rendu final)
C'est le dernier maillon de la chaîne, et le seul endroit dans tout le produit où les pixels sont réellement dessinés.
Avant lui, tout n'est que métadonnées : le grand livre enregistre « quels mots diffuser », les sous-titres indiquent « ce qui est écrit à l'écran », les visuels décrivent « quelles couches superposer », et l'aperçu les assemble en temps réel pour l'utilisateur, sans les écrire sur le disque. L'export les fusionne en un seul fichier.
Nécessite edit-list.json (obligatoire), subtitles.json, visuals.json + modules/
Produit video_finale.mp4
Prérequis : disposer de Google Chrome sur la machine (pour rendre les sous-titres et les animations en images). FFmpeg / FFprobe installé via le bureau fait déjà partie du répertoire géré par le produit avec l'App ; une installation CLI autonome nécessite toujours ffmpeg ≥ 6 sur le système. L'absence de Chrome génère une erreur explicite, ne cherchez pas à contourner — sans lui, il n'y a ni couche de sous-titres ni couche d'animation.
Commencez par lire et exécuter la section « Niveau de conclusion » du contrat de phase du Skill métier. L'export n'entre pas dans la machine d'état de montage : il ne modifie aucun fichier projet, n'effectue aucune écriture CAS, n'avance pas l'étape ; le résultat est un nouveau fichier, une nouvelle exécution l'écrase. Il n'a donc pas besoin de carte de confirmation.
0. Prêt
Exécutez d'abord la « Vérification de préparation » de Vérifier les mises à jour — les skills sont-ils à jour, le Runtime est-il compatible ? La racine du plugin est également localisée ici (toutes les occurrences de <racine_plugin> dans les commandes de ce document sont à remplacer par ce chemin littéral). Continuez uniquement si l'état est « prêt » ; si c'est « nouvelle session nécessaire » ou « arrêt », suivez ses instructions (y compris l'interdiction « ne pas créer d'interface de substitution maison »), le Skill métier n'intègre pas sa propre logique d'environnement.
Si le résultat de la préparation est runtime.kind=desktop-managed, réutilisez directement les outils CLI stables, les outils média et le même service launchd/windows-task déjà installés par l'App de bureau ; n'analysez pas le chemin d'Electron, n'installez pas un autre FFmpeg/Bun et ne démarrez pas un second Runtime.
Commandes
node "<racine_plugin>/scripts/ensure-running.cjs" --json
node "<racine_plugin>/scripts/videocut-cli.cjs" export <projet> --dry-run --json # D'abord voir le plan, sans encoder
node "<racine_plugin>/scripts/videocut-cli.cjs" export <projet> --json # Produire le rendu final (par défaut 2x, fréquence d'images source)
node "<racine_plugin>/scripts/videocut-cli.cjs" export <projet> --out /chemin/video_finale.mp4 --json
node "<racine_plugin>/scripts/videocut-cli.cjs" export <projet> --scale 1 --json # Utiliser la taille source uniquement
node "<racine_plugin>/scripts/videocut-cli.cjs" export <projet> --keep-work --json # Conserver les fichiers intermédiaires et les PNG image par image pour le débogage
Si ensure-running échoue en raison d'une identité incompatible, d'un conflit de port ou d'un service non sain, arrêtez immédiatement ; il est interdit d'utiliser un processus en avant-plan temporaire pour continuer l'export.
Deux étapes, ne faites pas uniquement la seconde
① --dry-run rapporte d'abord le plan Durée, nombre d'images, nombre d'écrans de sous-titres, nombre de couches visuelles, nombre de segments de zoom avant, taille de sortie.
Lisez-le à l'utilisateur. Si les chiffres sont faux, c'est que l'amont est erroné ; dix minutes d'encodage ne les corrigeront pas.
② Exécution réelle Quatre phases de progression : assemble → overlay → compose → verify
Les warnings dans --dry-run doivent être transmis textuellement. Elles ne signalent qu'un type de problème : certains mots des écrans de sous-titres ou des couches visuelles ont déjà été coupés, donc ils n'apparaîtront pas dans le rendu final. C'est à l'amont de décider, ce n'est pas à l'export de les avaler silencieusement.
Résolution : la source est le plafond, regardez d'abord la source avant de parler d'agrandissement
Avant l'export, vérifiez la résolution source (le champ source de --dry-run la contient déjà) :
Largeur source ≥2560 (enregistrement écran Retina natif) → --scale 1, la sortie est en pixels natifs, c'est le meilleur cas
Largeur source <1920 (ex. 960×720) → Arrêtez-vous d'abord : demandez à l'utilisateur s'il existe un export haute résolution de la même session.
Les outils d'enregistrement d'écran permettent souvent de réexporter la même session en 3x la résolution ;
changer la source est plus efficace que tout post-traitement (voir section suivante). Absolument pas → --scale 2
Pourquoi --scale 2 est utile pour une source basse résolution : l'agrandissement du métrage ne le rendra pas plus net, mais les sous-titres et les animations sont redessinés à la taille de sortie — c'est ce que le public lit réellement ; et lorsque la plateforme re-compresse, une image plus grande reçoit également un débit binaire plus élevé.
**Ne modifiez pas --fps pour « améliorer la netteté ». ** La fréquence d'images suit la source ; la changer ne fera que désynchroniser l'échantillonnage de l'animation et de l'enregistrement.
Changer la source : lorsque l'utilisateur fournit une version haute résolution de la même session
Cela ne fait pas partie du processus d'export — l'export lui-même est toujours en lecture seule. Changer la source est une opération indépendante sur les éléments, effectuée après l'accord explicite de l'utilisateur, puis on revient à un export normal.
Déterminez d'abord s'il s'agit de la même session (les deux premiers critères sont suffisamment stricts) :
ffprobe -v error -show_entries format=duration -of csv=p=0 <fichier1> <fichier2> # Durée identique à la milliseconde près
ffmpeg -v error -i <fichier> -map 0:a:0 -c copy -f md5 - # Flux audio identique bit par bit
# Ensuite, comparez visuellement deux ou trois images du contenu
Flux audio identique bit par bit = timeline identique : la transcription mot à mot, le grand livre, les sous-titres, les couches visuelles sont tous liés par les identifiants de mots, aucun n'a besoin d'être modifié. C'est précisément la promesse de « lier les mots, pas les secondes » dans le cas du changement de source.
Quatre étapes pour changer la source (réellement parcourues le 2026-07-29 ; l'étape ③ avait été oubliée à l'époque, et l'aperçu du montage a immédiatement signalé « échec de génération » — l'empreinte n'est pas enregistrée à un seul endroit, grep pour trouver toutes les anciennes empreintes avant d'agir) :
① Remplacer le fichier input/source.mp4 et uploads/source.mp4 sont des liens physiques —
supprimez les deux, copiez le nouveau fichier dans input/, puis créez un lien physique vers uploads/
(macOS utilise ln ; Windows utilise New-Item -ItemType HardLink)
② Mettre à jour l'empreinte Le source.sha256 dans project.json doit être remplacé par celui du nouveau fichier
③ Vérifier un autre endroit Le sourceSha256 dans workbench.json enregistre également l'empreinte du métrage source,
et c'est précisément ce fichier que le pipeline de l'aperçu du montage valide — oubliez-le, et l'aperçu refuse de générer
(c'est le comportement correct du produit : si l'empreinte ne correspond pas, il échoue plutôt que d'utiliser un ancien aperçu frauduleux)
④ Réexporter --scale 1 — le changement de source vise à obtenir des pixels natifs, n'agrandissez plus
Mesure de sécurité : utilisez votre outil de recherche dans tous les fichiers *.json du <répertoire du projet> pour trouver les 8 premiers caractères de l'ancienne empreinte, et traitez chaque occurrence (les enregistrements de cache comme preview-edited/current.json sont recalculés automatiquement, pas besoin de les modifier manuellement).
Si l'audio est différent (ré-enregistré, coupé, durée différente), alors ce n'est pas un changement de source, c'est un nouveau projet : la transcription mot à mot doit être retranscrite, toutes les annotations sont annulées. Ne forcez pas.
Validation : trois éléments, aucun ne manque sinon l'export n'est pas considéré comme terminé
① La commande retourne avec succès Le produit vérifie la taille, le nombre d'images, les pistes audio du rendu final, une par une, par rapport au plan.
En cas de non-concordance, erreur readback_mismatch, le fichier reste sur le disque comme preuve, l'export n'est pas terminé
② Extraire des images pour inspection Extrayez des images du rendu final et regardez-les. Couvrez au moins : un segment de zoom avant,
un segment d'animation plein écran, un segment avec uniquement des sous-titres, et une frontière entre les couches
③ Écoute humaine Personne ne l'a vraiment écoutée, enregistrez toujours human listening UNVERIFIED
② Il est interdit d'utiliser des captures d'écran d'aperçu à la place. L'aperçu et le rendu final sont deux chemins de rendu différents, et la validation doit précisément vérifier leur correspondance — utiliser une image de l'aperçu comme preuve du rendu final revient à prendre pour acquis ce qui doit être vérifié.
Pour juger du zoom avant, cherchez des repères distinctifs ; l'impression générale peut tromper (véritablement vécu le 2026-07-29) : après un zoom avant de 1.6x, la page à l'écran ressemble toujours à « une page entière », et sur la vignette, elle est presque identique à la vue d'ensemble — une image de zoom avant correct a déjà été interprétée à tort comme « un zoom avant perdu », ce qui a entraîné 30 minutes de recherche inutile et deux réexports. La bonne méthode est de chercher des preuves que seul un recadrage peut produire : des éléments coupés en deux (bulle qui se brise au milieu), des éléments de bordure qui disparaissent (barre latérale, barre de titre). Comparez avec la même image de la source pour trancher d'un coup.
Pour extraire des images, utilisez ffmpeg :
ffmpeg -v error -ss 8.84 -i video_finale.mp4 -frames:v 1 -y frame.png
Où chercher en cas de problème
--keep-work laisse trois choses dans .chengfeng-videocut/export/ du projet, qui séparent directement « quelle moitié est erronée » :
assembled.mkv Uniquement le montage, sans rien de superposé. S'il est erroné = grand livre ou découpage erroné
overlay/*.png Uniquement les éléments superposés, fond transparent. S'ils sont erronés = style de sous-titres ou module erroné
spans/*.mp4 Segments après composition. S'ils sont erronés = zoom avant ou alignement erroné
Tableau de correspondance :
Rendu final sans sous-titres/animations Le PNG overlay est-il entièrement transparent ? Le module n'a-t-il pas accepté le seek ?
L'animation reste sur la première image Le module n'a pas implémenté le seek, ou la timeline GSAP n'était pas en pause
Écran entièrement blanc Le module manque `:root { color-scheme: dark }`
Le cadre de zoom avant est déformé Le viewBox du module et le zoom de la couche ne sont pas le même ensemble de valeurs
Le rendu final est plus court que prévu Un segment a un nombre d'images insuffisant, consultez l'erreur de la phase compose
Brève apparition d'une couche native L'instantané overlay est obsolète (validation de la marque d'image défaillante). Le produit utilise la barre de marque d'image en haut de la page pour prouver à quelle image appartient chaque instantané ; si cela se reproduit, vérifiez d'abord que le PNG overlay a une barre de marque en haut, et que compose l'a recadrée avec crop
Chrome introuvable Installez Google Chrome, ne changez pas pour un autre chemin de rendu
Ce qu'il ne faut pas faire
- Ne dites pas « export réussi » comme « validation réussie » — le retour réussi de la commande signifie seulement que le produit correspond à lui-même, pas que l'image est correcte
- N'utilisez pas de captures d'écran d'aperçu, de DOM ou de logs pour remplacer l'extraction d'images du rendu final
- Ne rapportez pas human listening PASS si personne n'a écouté
- Ne modifiez pas les fichiers du projet (changer les sous-titres, supprimer des couches, modifier le grand livre) pour faire fonctionner l'export. L'export est en lecture seule, il n'écrit pas
- Ne faites pas le travail de l'amont dans l'export : s'il manque des sous-titres, allez écrire les sous-titres ; s'il manque des visuels, allez créer les visuels ; ne bâclez pas une solution temporaire dans cette section