capcut-cli — CapCut/JianYing editable ship

capcut-edit

CLI para editar borradores de CapCut / JianYing a través de un almacén con conciencia de versión. v0.11 detecta y sincroniza líneas de tiempo legibles en draft_content.json, draft_info.json, draft_meta_info.json y template-2.tmp.

Ubicaciones del proyecto

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

Principio fundamental: scripts deterministas

Cualquier receta que implique más de una llamada a capcut, cualquier aritmética o cualquier bifurcación se entrega como un script de shell parametrizado en scripts/. Claude invoca el script con entradas; el script ejecuta una secuencia fija. Si una receta puede ser un script, debe ser un script, no una narración en references/.

references/workflows.md documenta qué script llamar y por qué, nunca una secuencia reconstructible.

Divulgación progresiva

Comienza de manera general, profundiza en lo que necesites. Nunca vuelques el JSON completo del proyecto.

capcut info <proyecto> -H           # resumen
capcut doctor -H                   # capacidades de medios/transcripción instaladas
capcut diagnose <proyecto> -H       # archivos canónicos, divergencia, seguridad del editor
capcut tracks <proyecto> -H         # todas las pistas
capcut materials <proyecto> -H      # resumen de materiales
capcut segments <proyecto> -H       # segmentos con temporización
capcut segment <proyecto> <id>      # un elemento, detalle completo

Modos de salida

• JSON (por defecto): canalízalo a jq, aliméntalo a scripts.
• -H: tablas legibles para humanos.
• -q: silencioso, solo código de salida (para comandos de escritura en scripts).

Escrituras por lotes

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

Operaciones: set-text, shift, shift-all, speed, volume, opacity, trim.

El lote es transaccional: una operación fallida no escribe nada. Usa --continue-on-error solo cuando el usuario acepte explícitamente una confirmación parcial; aun así, sale con código no cero.

Dónde buscar

• references/api-reference.md — cada comando, cada bandera, cada formato de valor (tiempo, porcentajes, grados), la regla del prefijo de ID, el invariante .bak.
• ../../docs/command-reference.md — contrato de comando generado v2 con posicionales/opciones tipificados, mutabilidad, requisitos previos, formato de salida y códigos de salida.
• references/workflows.md — recetas = qué scripts/X.sh ejecutar y por qué.
• references/pitfalls.md — cerrar-el-proyecto-primero, .bak, clip=null en audio, matemáticas de source_timerange con speed, fotogramas clave alfa que no se renderizan (usa animations-materials), etc.
• Descubrimiento de enumeraciones — llama a capcut enums --<categoría> (o -H para una tabla) para listar cada slug de CapCut. Categorías: --transitions, --masks, --image-intros, --image-outros, --image-combos, --text-intros, --text-outros, --text-loop-anims, --scene-effects, --character-effects, --audio-effects, --fonts. Añade --jianying para cambiar el espacio de nombres. El paquete enums.json se genera una vez mediante python3 scripts/extract-enums.py; el tiempo de ejecución no requiere Python.
• scripts/ — la biblioteca cliente. Actual:
  • anim.sh — adjunta cualquiera de las 9 animaciones de entrada/salida de CapCut; fade-in.sh y fade-out.sh son envoltorios ligeros.
  • ken-burns.sh — fotogramas clave de escala + desplazamiento mediante capcut keyframe --batch (las propiedades de movimiento se renderizan; alfa no — usa anim.sh fade-in en su lugar).
  • long-to-short.sh — corta un rango, estampa título + texto CTA.
  • stamp-cta.sh — aplica una plantilla de texto guardada (ver assets/examples/subscribe-cta.json).
  • _test.sh — ejecuta cada envoltorio contra el fixture; ejecútalo después de cualquier cambio aquí.
• assets/examples/ — fragmentos JSON sin procesar para edición manual.

Invariantes

• Cierra el proyecto en CapCut antes de editarlo; vuélvelo a abrir después.
• Cada escritura se verifica por conflictos, se prepara atómicamente y se sincroniza con cada destino de línea de tiempo legible. Cada destino recibe .bak y capturas instantáneas históricas rotativas.
• Nunca pases --force-write a menos que el usuario acepte explícitamente sobrescribir el estado cambiado en disco o un editor abierto.
• clip es null en segmentos de audio (sin opacidad/escala).
• capcut cut escribe en --out, nunca modifica la fuente.
• IDs: los primeros 6+ caracteres del UUID coinciden como prefijo.
• Formatos de tiempo: 1.5s, 500ms, +0.5s, -1s, 1:30, 0:05.5, número simple = segundos.

Rutas de alto valor en v0.11

• Borrador completo: capcut compile spec.json --check, luego capcut compile spec.json --out <dir>. Las especificaciones admiten referencias, transformaciones, decoradores, plantillas, subtítulos, fotogramas clave y fundidos.
• Karaoke: capcut caption <proyecto> --audio <ruta> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke.
• Proxy: capcut render <proyecto> --all-video-tracks --burn-captions; ejecuta doctor primero para las banderas de capacidad de FFmpeg.
• Automatización: capcut serve --workers N --retries N --timeout MS; asigna a los trabajos campos id estables y deja que el ejecutor serialice las escrituras por proyecto.
• Esquema del agente: capcut describe es la fuente de verdad. No rasques texto de ayuda ni inventes banderas.