cli-anything-shotcut

O que cli-anything-shotcut faz?

Uma interface de linha de comando com estado para edição de vídeo, construída sobre o formato MLT XML. Projetada para agentes de IA e usuários avançados que precisam criar e editar projetos Shotcut sem uma interface gráfica.

Instalação

Esta CLI é instalada como parte do pacote cli-anything-shotcut:

pip install cli-anything-shotcut

Pré-requisitos:

• Python 3.10+
• melt (CLI do MLT) — necessário para renderização e reprodução
• ffmpeg / ffprobe — necessário para análise de mídia
• shotcut deve estar instalado no sistema

Uso

Comandos Básicos

# Exibir ajuda
cli-anything-shotcut --help

# Iniciar modo REPL interativo
cli-anything-shotcut

# Criar um novo projeto
cli-anything-shotcut project new -o project.json

# Executar com saída JSON (para consumo por agentes)
cli-anything-shotcut --json project info -p project.json

Modo REPL

Quando invocada sem um subcomando, a CLI entra em uma sessão REPL interativa com suporte a undo/redo:

cli-anything-shotcut
# ou com um projeto:
cli-anything-shotcut --project my_project.mlt

Comandos REPL

Fluxo de trabalho: Sempre media import primeiro para obter um clip_id, depois use add-clip para colocá-lo na linha do tempo.

Projeto e Sessão:

• new [profile] — Criar novo projeto (padrão: hd1080p30)
• open <path> — Abrir arquivo .mlt
• save [path] — Salvar projeto
• info — Mostrar informações do projeto
• xml — Imprimir XML MLT bruto
• status — Mostrar status da sessão
• undo / redo — Navegar pelo histórico de operações

Mídia (modelo de duas etapas):

• media import <file> [--caption nome] — Importar arquivo para o bin do projeto, retorna clip_id (ex.: clip0)
• media — Listar todas as mídias importadas
• probe <file> — Analisar um arquivo de mídia

Linha do Tempo:

• add-track <video|audio> [nome] — Adicionar uma faixa
• tracks — Listar todas as faixas
• show — Visão geral visual da linha do tempo
• add-clip <clip_id> <faixa> [in] [out] [--at tempo] — Colocar clipe importado na faixa
• clips <faixa> — Listar clipes em uma faixa
• remove-clip <faixa> <clip> — Remover um clipe
• trim <faixa> <clip> [--in tc] [--out tc] — Aparar clipe
• split <faixa> <clip> <at> — Dividir clipe em um timecode

Filtros:

• list-filters [video|audio] — Navegar pelos filtros disponíveis
• filter-info <nome> — Mostrar detalhes do filtro
• add-filter <nome> [--track n] [--clip n] [chave=val ...] — Adicionar filtro a clipe, faixa ou global
• filters [--track n] [--clip n] — Listar filtros ativos
• remove-filter <idx> [--track n] [--clip n] — Remover filtro por índice
• set-filter <idx> <parâmetro> <valor> [--track n] [--clip n] — Definir parâmetro de filtro
• volume-envelope [--track n] [--clip n] TEMPO=NÍVEL ... — Envelope de volume com keyframes (ex.: 00:00:00.000=1.0 00:00:03.000=0.35)
• duck [--track n] [--clip n] INÍCIO..FIM ... — Envelope de ducking (ex.: 00:00:06.000..00:00:09.000)

Exportação:

• presets — Listar predefinições de exportação
• render <output> [--preset nome] — Renderizar para arquivo de vídeo

Grupos de Comandos

Projeto

Gerenciamento de projetos: novo, abrir, salvar, informações.

Comando	Descrição
new	Criar um novo projeto em branco
open	Abrir um arquivo de projeto .mlt existente
save	Salvar o projeto atual
info	Mostrar informações detalhadas do projeto
profiles	Listar perfis de vídeo disponíveis
xml	Imprimir o XML MLT bruto do projeto atual

Linha do Tempo

Operações na linha do tempo: faixas, clipes, aparação.

Comando	Descrição
show	Mostrar a visão geral da linha do tempo
tracks	Listar todas as faixas
add-track	Adicionar uma nova faixa à linha do tempo
remove-track	Remover uma faixa por índice
add-clip	Adicionar um clipe importado a uma faixa pelo clip_id; suporta --at para posicionamento absoluto
remove-clip	Remover um clipe de uma faixa
move-clip	Mover um clipe entre faixas ou posições
trim	Aparar os pontos de entrada/saída de um clipe
split	Dividir um clipe em dois no timecode fornecido
clips	Listar todos os clipes em uma faixa
add-blank	Adicionar um espaço em branco a uma faixa
set-name	Definir o nome de exibição de uma faixa
mute	Silenciar ou ativar o som de uma faixa
hide	Ocultar ou exibir uma faixa de vídeo

Grupo de Filtros

Operações de filtro: adicionar, remover, configurar efeitos.

Comando	Descrição
list-available	Listar todos os filtros disponíveis
info	Mostrar informações detalhadas sobre um filtro e seus parâmetros
add	Adicionar um filtro a um clipe, faixa ou globalmente
remove	Remover um filtro por índice
set	Definir um parâmetro em um filtro
list	Listar filtros ativos em um destino
volume-envelope	Criar ou substituir um envelope de volume com keyframes em uma faixa ou clipe
duck	Construir um envelope de ducking prático em uma ou mais janelas de tempo

Mídia

Operações de mídia: análise, listagem, verificação de arquivos.

Comando	Descrição
import	Importar um arquivo de mídia para o bin do projeto
probe	Analisar as propriedades de um arquivo de mídia
list	Listar todos os clipes de mídia no projeto atual
check	Verificar se todos os arquivos de mídia existem
thumbnail	Gerar uma miniatura a partir de um arquivo de vídeo

Exportação

Operações de exportação/renderização.

Comando	Descrição
presets	Listar predefinições de exportação disponíveis
preset-info	Mostrar detalhes de uma predefinição de exportação
render	Renderizar o projeto para um arquivo de vídeo

Grupo de Transições

Operações de transição: dissolução, cortina e outras transições.

Comando	Descrição
list-available	Listar todos os tipos de transição disponíveis
info	Mostrar informações detalhadas sobre um tipo de transição
add	Adicionar uma transição entre duas faixas
remove	Remover uma transição por índice
set	Definir um parâmetro em uma transição
list	Listar todas as transições na linha do tempo

Grupo de Composição

Composição: modos de mesclagem, PIP, opacidade.

Comando	Descrição
blend-modes	Listar todos os modos de mesclagem disponíveis
set-blend	Definir o modo de mesclagem para uma faixa
get-blend	Obter o modo de mesclagem atual de uma faixa
set-opacity	Definir a opacidade de uma faixa (0.0-1.0)
pip	Definir a posição picture-in-picture para um clipe

Sessão

Gerenciamento de sessão: status, undo, redo.

Comando	Descrição
status	Mostrar o status da sessão atual
undo	Desfazer a última operação
redo	Refazer a última operação desfeita
save	Salvar o estado da sessão no disco
list	Listar todas as sessões salvas

Preview

Bundles de pré-visualização e sessões de pré-visualização ao vivo para revisão iterativa de edição.

Comando	Descrição
preview recipes	Listar receitas de pré-visualização
preview capture	Renderizar um bundle de pré-visualização de baixa resolução
preview latest	Retornar o bundle existente mais recente
preview live start	Iniciar uma sessão de pré-visualização ao vivo e publicar o primeiro bundle
preview live push	Publicar um novo bundle na sessão ao vivo
preview live status	Consultar o estado atual da sessão ao vivo sem renderizar
preview live stop	Parar a sessão ao vivo sem excluir artefatos

Conteúdo típico de um bundle quick:

• preview.mp4
• vários frames amostrados
• hero.png do ponto médio
• summary.json com fatos do projeto

O modo de polling é suportado:

cli-anything-shotcut --json --project edit.mlt preview live start --recipe quick --mode poll --source-poll-ms 500

preview live status --json inclui referências de sessão e um compacto trajectory_summary para que agentes possam entender de forma barata as últimas publicações.

Comandos do visualizador:

cli-hub previews inspect /path/to/bundle-or-session
cli-hub previews html /path/to/bundle-or-session -o page.html
cli-hub previews watch /path/to/session --open
cli-hub previews open /path/to/bundle-or-session

Exemplos

Criar um Novo Projeto

Criar um novo arquivo de projeto Shotcut.

cli-anything-shotcut project new -o myproject.json
# Ou com saída JSON para uso programático
cli-anything-shotcut --json project new -o myproject.json

Sessão REPL Interativa

Iniciar uma sessão interativa com suporte a undo/redo.

cli-anything-shotcut
# Digite comandos interativamente
# Use 'help' para ver comandos disponíveis
# Use 'undo' e 'redo' para navegação no histórico

Exportar Projeto

Exportar o projeto para um formato de saída final.

cli-anything-shotcut --project myproject.json export render output.mp4 --overwrite

Reconstrução Determinística da Linha do Tempo

Para reconstruções, prefira posicionamento absoluto em vez de inserção de clipe apenas com anexação:

cli-anything-shotcut --project myproject.mlt media import intro.mp4
cli-anything-shotcut --project myproject.mlt timeline add-clip clip0 \
  --track 1 --in 00:00:00.000 --out 00:00:04.000 --at 00:00:00.000

cli-anything-shotcut --project myproject.mlt media import broll.mp4
cli-anything-shotcut --project myproject.mlt timeline add-clip clip1 \
  --track 1 --in 00:00:10.000 --out 00:00:16.000 --at 00:00:08.000

• --at insere espaços em branco automaticamente quando o tempo alvo cai em espaço vazio.
• A CLI rejeita sobreposição com um clipe existente.
• Prefira valores explícitos de --in e --out para que o posicionamento absoluto posterior permaneça inequívoco.

Automação de Áudio

cli-anything-shotcut --project myproject.mlt filter volume-envelope \
  --track 2 \
  --point 00:00:00.000=1.0 \
  --point 00:00:03.000=0.35 \
  --point 00:00:05.000=1.0

cli-anything-shotcut --project myproject.mlt filter duck \
  --track 2 \
  --window 00:00:06.000..00:00:09.000 \
  --window 00:00:15.000..00:00:18.000 \
  --normal 1.0 --duck 0.25

A CLI mantém o estado da sessão com:

• Undo/Redo: Até 50 níveis de histórico
• Persistência de projeto: Salvar/carregar estado do projeto como JSON
• Rastreamento de sessão: Rastrear modificações e alterações

Formatos de Saída

Todos os comandos suportam modos de saída dupla:

• Legível por humanos (padrão): Tabelas, cores, texto formatado
• Legível por máquina (flag --json): JSON estruturado para consumo por agentes

# Saída humana
cli-anything-shotcut project info -p project.json

# Saída JSON para agentes
cli-anything-shotcut --json project info -p project.json

Para Agentes de IA

Ao usar esta CLI programaticamente:

1. Sempre use a flag --json para saída parseável
2. Verifique códigos de retorno - 0 para sucesso, diferente de zero para erros
3. Analise stderr para mensagens de erro em caso de falha
4. Use caminhos absolutos para todas as operações de arquivo
5. Verifique se as saídas existem após operações de exportação
6. Prefira timeline add-clip --at ao recriar uma edição conhecida
7. Revise as renderizações finais após alterações de volume com keyframes ou ducking
8. Use preview capture ou preview live ... para validar ritmo, cortes e efeitos de filtro visualmente
9. Leia os caminhos de artefatos retornados como hero.png e preview.mp4; cargas JSON referenciam arquivos no disco
10. Use preview live status --json antes de ler o trajectory.json completo
11. Use cli-hub previews ... apenas para inspecionar/abrir bundles ou sessões ao vivo existentes

Mais Informações

• Documentação completa: Veja README.md no pacote
• Cobertura de testes: Veja TEST.md no pacote
• Metodologia: Veja HARNESS.md no cli-anything-plugin

Versão

1.0.0