capcut-cli — CapCut/JianYing brouillon ship

capcut-edit

CLI pour éditer les brouillons CapCut / JianYing via un stockage conscient des versions. v0.11 détecte et synchronise les timelines lisibles à travers draft_content.json, draft_info.json, draft_meta_info.json et template-2.tmp.

Emplacements des projets

• macOS : ~/Movies/CapCut/User Data/Projects/com.lveditor.draft/<project>/
• Windows : %LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<project>\

Principe fondamental — scripts déterministes

Toute recette impliquant plus d’un appel à capcut, un calcul arithmétique ou une branche conditionnelle est livrée sous forme de script shell paramétré dans scripts/. Claude invoque le script avec des entrées ; le script exécute une séquence fixe. Si une recette peut être un script, elle doit l’être — pas un récit dans references/.

references/workflows.md documente quel script appeler et pourquoi, jamais une séquence reconstituable.

Divulgation progressive

Commencez par une vue d’ensemble, puis creusez si nécessaire. Ne jamais vider l’intégralité du JSON du projet.

capcut info <project> -H           # aperçu
capcut doctor -H                   # capacités média / transcription installées
capcut diagnose <project> -H       # fichiers canoniques, divergence, sécurité de l’éditeur
capcut tracks <project> -H         # toutes les pistes
capcut materials <project> -H      # résumé des médias
capcut segments <project> -H       # segments avec timing
capcut segment <project> <id>      # un seul élément, détails complets

Modes de sortie

• JSON (par défaut) : à rediriger vers jq, à passer à des scripts.
• -H : tableaux lisibles par un humain.
• -q : silencieux, seulement le code de retour — pour les commandes d’écriture dans les scripts.

Écritures par lots

echo '{"cmd":"set-text","id":"a1b2c3","text":"Fixed"}
{"cmd":"volume","id":"d4e5f6","volume":0.5}' | capcut batch <project>

Opérations : set-text, shift, shift-all, speed, volume, opacity, trim.

Le lot est transactionnel : une opération échouée n’écrit rien. Utilisez --continue-on-error uniquement si l’utilisateur accepte explicitement une validation partielle ; il renvoie toujours un code non nul.

Où chercher

• references/api-reference.md — chaque commande, chaque drapeau, chaque format de valeur (temps, pourcentages, degrés), la règle de préfixe d’ID, l’invariant .bak.
• ../../docs/command-reference.md — contrat de commande généré v2 avec arguments positionnels/options typés, mutabilité, prérequis, format de sortie et codes de retour.
• references/workflows.md — recettes = quel scripts/X.sh exécuter et pourquoi.
• references/pitfalls.md — fermer-le-projet-d’abord, .bak, clip=null sur l’audio, calcul de source_timerange avec speed, alpha-keyframes-ne-sont-pas-rendus-utiliser-animation-materials, etc.
• Découverte des énumérations — appelez capcut enums --<category> (ou -H pour un tableau) pour lister chaque slug CapCut. Catégories : --transitions, --masks, --image-intros, --image-outros, --image-combos, --text-intros, --text-outros, --text-loop-anims, --scene-effects, --character-effects, --audio-effects, --fonts. Ajoutez --jianying pour changer d’espace de noms. Le bundle enums.json est généré une fois via python3 scripts/extract-enums.py ; l’exécution ne nécessite pas Python.
• scripts/ — la bibliothèque cliente. Actuellement :
  • anim.sh — attache l’une des 9 animations d’intro/outro CapCut ; fade-in.sh et fade-out.sh sont des wrappers légers.
  • ken-burns.sh — images clés de zoom + panoramique via capcut keyframe --batch (les propriétés de mouvement s’affichent ; alpha non — utilisez anim.sh fade-in à la place).
  • long-to-short.sh — coupe une plage, ajoute le titre + texte CTA.
  • stamp-cta.sh — applique un modèle de texte sauvegardé (voir assets/examples/subscribe-cta.json).
  • _test.sh — exécute tous les wrappers sur le fixture ; à exécuter après toute modification ici.
• assets/examples/ — extraits JSON bruts pour édition manuelle.

Invariants

• Fermez le projet dans CapCut avant de l’éditer ; rouvrez-le après.
• Chaque écriture est vérifiée pour les conflits, préparée de manière atomique et synchronisée vers chaque cible de timeline lisible. Chaque cible reçoit .bak et des instantanés d’historique roulant.
• Ne passez jamais --force-write sauf si l’utilisateur accepte explicitement d’écraser un état modifié sur le disque ou un éditeur ouvert.
• clip est null sur les segments audio (pas d’opacité/échelle).
• capcut cut écrit dans --out, ne modifie jamais la source.
• ID : les 6 premiers caractères (ou plus) de l’UUID suffisent comme préfixe.
• Formats d’heure : 1.5s, 500ms, +0.5s, -1s, 1:30, 0:05.5, nombre brut = secondes.

Chemins à forte valeur ajoutée v0.11

• Brouillon complet : capcut compile spec.json --check, puis capcut compile spec.json --out <dir>. Les specs prennent en charge les références, transformations, décorateurs, modèles, sous-titres, images clés et fondus.
• Karaoké : capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke.
• Proxy : capcut render <project> --all-video-tracks --burn-captions ; exécutez d’abord doctor pour les indicateurs de capacité FFmpeg.
• Automatisation : capcut serve --workers N --retries N --timeout MS ; donnez aux tâches des champs id stables et laissez l’exécuteur sérialiser les écritures par projet.
• Schéma agent : capcut describe est la source de vérité. Ne parcourez pas le texte d’aide et n’inventez pas de drapeaux.