capcut-cli — CapCut/JianYing rascunho ship

capcut-edit

CLI para editar rascunhos do CapCut / JianYing através de um repositório com conhecimento de versão. v0.11 detecta e sincroniza linhas do tempo legíveis entre draft_content.json, draft_info.json, draft_meta_info.json e template-2.tmp.

Localizações do projeto

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

Princípio central — scripts determinísticos

Qualquer receita que envolva mais de uma chamada capcut, qualquer aritmética ou qualquer ramificação é fornecida como um script shell parametrizado em scripts/. Claude invoca o script com entradas; o script executa uma sequência fixa. Se uma receita pode ser um script, ela deve ser um script — não uma narrativa em references/.

references/workflows.md documenta qual script chamar e por quê, nunca uma sequência reconstruível.

Divulgação progressiva

Comece amplo, aprofunde-se no que você precisa. Nunca despeje o JSON completo do projeto.

capcut info <project> -H           # visão geral
capcut doctor -H                   # capacidades de mídia/transcrição instaladas
capcut diagnose <project> -H       # arquivos canônicos, divergência, segurança do editor
capcut tracks <project> -H         # todas as faixas
capcut materials <project> -H      # resumo de materiais
capcut segments <project> -H       # segmentos com temporização
capcut segment <project> <id>      # um item, detalhe completo

Modos de saída

• JSON (padrão): canalize para jq, alimente scripts.
• -H: tabelas legíveis por humanos.
• -q: silencioso, apenas código de saída — para comandos de escrita em scripts.

Gravações em lote

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

Operações: set-text, shift, shift-all, speed, volume, opacity, trim.

Lote é transacional: uma operação com falha não grava nada. Use --continue-on-error apenas quando o usuário aceitar explicitamente um commit parcial; ainda assim sai com código não zero.

Onde procurar

• references/api-reference.md — cada comando, cada flag, cada formato de valor (tempo, porcentagens, graus), a regra do prefixo de ID, o invariante .bak.
• ../../docs/command-reference.md — contrato de comando v2 gerado com posicionais/opções tipados, mutabilidade, pré-requisitos, formato de saída e códigos de saída.
• references/workflows.md — receitas = qual scripts/X.sh executar e por quê.
• references/pitfalls.md — feche-o-projeto-primeiro, .bak, clip=null em áudio, matemática source_timerange com speed, keyframes-alfa-não-renderizam-use-animação-materiais, etc.
• Descoberta de enumerações — chame capcut enums --<categoria> (ou -H para uma tabela) para listar todos os slugs do CapCut. Categorias: --transitions, --masks, --image-intros, --image-outros, --image-combos, --text-intros, --text-outros, --text-loop-anims, --scene-effects, --character-effects, --audio-effects, --fonts. Adicione --jianying para alternar namespace. O pacote enums.json é gerado uma vez via python3 scripts/extract-enums.py; tempo de execução é livre de Python.
• scripts/ — a biblioteca do cliente. Atual:
  • anim.sh — anexar qualquer uma das 9 animações de entrada/saída do CapCut; fade-in.sh e fade-out.sh são wrappers finos.
  • ken-burns.sh — keyframes de escala + pan via capcut keyframe --batch (propriedades de movimento renderizam; alfa não — use anim.sh fade-in em vez disso).
  • long-to-short.sh — cortar um intervalo, carimbar título + texto CTA.
  • stamp-cta.sh — aplicar um modelo de texto salvo (veja assets/examples/subscribe-cta.json).
  • _test.sh — executar cada wrapper contra o fixture; execute após qualquer alteração aqui.
• assets/examples/ — trechos JSON brutos para edição manual.

Invariantes

• Feche o projeto no CapCut antes de editar; reabra depois.
• Cada gravação é verificada quanto a conflitos, preparada atomicamente e sincronizada para cada destino de linha do tempo legível. Cada destino recebe .bak e instantâneos de histórico contínuo.
• Nunca passe --force-write a menos que o usuário aceite explicitamente sobrescrever o estado alterado no disco ou um editor aberto.
• clip é null em segmentos de áudio (sem opacidade/escala).
• capcut cut grava em --out, nunca modifica a origem.
• IDs: os primeiros 6+ caracteres do UUID correspondem como prefixo.
• Formatos de tempo: 1.5s, 500ms, +0.5s, -1s, 1:30, 0:05.5, número puro = segundos.

Caminhos de alto valor v0.11

• Rascunho inteiro: capcut compile spec.json --check, depois capcut compile spec.json --out <dir>. Especificações suportam referências, transformações, decoradores, modelos, legendas, keyframes e fades.
• Karaokê: capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke.
• Proxy: capcut render <project> --all-video-tracks --burn-captions; execute doctor primeiro para flags de capacidade do FFmpeg.
• Automação: capcut serve --workers N --retries N --timeout MS; dê aos jobs campos id estáveis e deixe o runner serializar gravações por projeto.
• Esquema do agente: capcut describe é a fonte da verdade. Não raspe texto de ajuda nem invente flags.