Interface de Linha de Comando
Traga o OpenShot para seu fluxo de trabalho na linha de comando. Importe filmagens, corte e organize clipes, aplique efeitos, anime propriedades com keyframes e exporte vídeos diretamente do seu terminal. Use alguns comandos para automatizar edições repetitivas, escrever um script para um projeto recorrente ou deixar um agente de IA ajudar a montar e refinar um vídeo.
A linha de comando funciona com os mesmos projetos do editor. Você pode controlar um editor aberto e revisar as alterações conforme avança, ou trabalhar em uma sessão headless sem abrir uma janela. Uma sessão mantém seu projeto aberto entre comandos, incluindo suas edições, histórico de desfazer e trabalhos de exportação. Salve-o como um projeto .osp sempre que quiser continuar editando depois.
Começando
Use o executável do OpenShot instalado seguido de --cli. Comece com intro para um guia rápido sobre sessões, edição, animação e salvamento, ou help para a visão geral dos comandos. Esses comandos não precisam de uma sessão ativa. Os exemplos abaixo requerem uma versão do OpenShot que inclua edição pela linha de comando.
Linux AppImage
Do diretório que contém seu AppImage baixado:
./OpenShot.AppImage --cli intro
./OpenShot.AppImage --cli help
Substitua OpenShot.AppImage pelo nome do arquivo que você baixou. Se o AppImageLauncher mostrar diálogos de integração com a área de trabalho, defina APPIMAGELAUNCHER_DISABLE=1 antes de executar o comando:
APPIMAGELAUNCHER_DISABLE=1 ./OpenShot.AppImage --cli intro
Para scripts ou comandos repetidos, defina-o uma vez no seu shell atual:
export APPIMAGELAUNCHER_DISABLE=1
./OpenShot.AppImage --cli session start
A variável deve ser definida antes de iniciar o AppImage: o AppImageLauncher pode interceptá-la antes que o OpenShot receba --cli. Caminhos relativos de mídia e arquivos @batch.json são resolvidos a partir do seu diretório de trabalho. Mantenha o arquivo AppImage disponível enquanto suas sessões ou exportações estiverem em execução.
Linux Snap
Para o OpenShot Snap, use:
snap run openshot-qt --cli intro
snap run openshot-qt --cli help
snap run openshot-qt --cli session start
As permissões de arquivo do Snap também se aplicam à edição pela linha de comando. Mantenha mídias, projetos e exportações em locais que o Snap possa acessar, como sua pasta pessoal. Para permitir acesso a unidades externas, conecte a permissão removable-media:
sudo snap connect openshot-qt:removable-media
Windows
Importante
Use openshot-qt-cmd.exe para edição pela linha de comando no Windows. Este executável de console exibe resultados de comandos, ajuda e erros no seu terminal. O executável de área de trabalho, openshot-qt.exe, não exibe saída padrão em um terminal interativo, deixando os comandos sem feedback visível e tornando a CLI difícil de usar.
No PowerShell, a partir do diretório de instalação do OpenShot:
& .\openshot-qt-cmd.exe --cli intro
& .\openshot-qt-cmd.exe --cli help
& .\openshot-qt-cmd.exe --cli session start
Se você estiver em um diretório diferente, use o caminho completo para openshot-qt-cmd.exe. Mantenha --cli após o nome do executável.
macOS
Para uma instalação em Applications:
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli intro
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli help
Encontrando comandos
Ao longo deste guia, openshot-cli é uma abreviação para o comando da sua instalação acima, como snap run openshot-qt --cli ou ./OpenShot.AppImage --cli. Algumas instalações também fornecem um comando openshot-cli diretamente. Ao executar a partir do código-fonte, use python3 src/launch.py --cli no ambiente Python do OpenShot.
Os comandos --cli, --cli help e --cli --help mostram a mesma visão geral. A ajuda torna-se mais específica conforme você navega pelos comandos:
openshot-cli clip help
openshot-cli clip keyframe help
openshot-cli clip keyframe set help
openshot-cli edit help
openshot-cli text help
openshot-cli effects list
openshot-cli effects audiovisualization help
openshot-cli effects audiovisualization help --property background
A ajuda de grupo explica fluxos de trabalho com exemplos; a ajuda de operação descreve argumentos e comportamento. --help é equivalente a help no final. Todos os comandos de ajuda funcionam sem uma sessão de edição.
effects list mostra os efeitos disponíveis com descrições curtas. A ajuda dos efeitos explica suas propriedades, padrões, opções e intervalos. effects instances lista os efeitos já aplicados aos clipes, com IDs dos clipes pai. Nomes de classe, nomes exibidos e aliases com sublinhado identificam o mesmo efeito.
Trabalhando com scripts e agentes de IA
Agentes de codificação de IA como Codex e Claude Code podem usar a CLI para inspecionar e editar projetos do OpenShot por meio de comandos no terminal. Forneça ao seu agente o caminho para o executável do OpenShot, a mídia ou projeto para trabalhar, e o resultado desejado: duração, dimensões, estilo de animação e local de saída. Peça para ele ler --cli intro antes de começar. Os mesmos comandos funcionam quando você os digita ou executa a partir de um script.
Comece com intro, depois use a ajuda específica do comando conforme necessário. Um fluxo de trabalho útil é selecionar uma sessão, inspecionar o projeto, fazer um pequeno conjunto de alterações, revisar o resultado e salvar. Os comandos retornam JSON estruturado para que scripts e agentes possam usar IDs de objetos e resultados diretamente, em vez de interpretar a saída da tela.
Inspecione antes de editar. Use os IDs retornados e informações de propriedades em vez de adivinhar nomes, números de faixa ou tempo. Selecione uma sessão explicitamente quando mais de um projeto estiver aberto.
Agrupe edições repetidas. Use
edit applypara uma sequência de alterações ouedit bulkpara aplicar um modelo aos clipes selecionados. Valide com--dry-runantes de aplicar um lote.Verifique a animação. Escolha um espaço de coordenadas, comece com alguns quadros-chave e use predefinições de suavização para um movimento familiar.
keyframe previewamostra a curva para que você possa identificar pausas ou saltos antes de exportar. Revise também o movimento renderizado; uma folha de contato sozinha não pode mostrar como uma animação se sente.Salve e acompanhe as exportações. Salve o projeto explicitamente e verifique o status do trabalho de exportação antes de considerar uma saída como concluída. Se uma solicitação expirar, inspecione seu status antes de repetir uma edição.
As seções abaixo explicam esses fluxos de trabalho e suas convenções de tempo.
Sessões e saídas
Iniciando ou encontrando uma sessão
Inicie uma sessão headless (sem janela do editor):
openshot-cli session start
Para abrir um projeto existente na inicialização, adicione --project "/caminho/projeto.osp". A resposta JSON bem-sucedida contém result.session_id. Copie esse valor. Se o OpenShot já estiver em execução, ou você esqueceu o ID, encontre sessões disponíveis com:
openshot-cli session list
Escolha a sessão para o projeto que você pretende editar. Não é necessário iniciar uma nova sessão para cada comando.
Selecionando uma sessão
Dica
Defina OPENSHOT_SESSION uma vez, depois execute os comandos normalmente. Seu terminal lembra a sessão selecionada, então você não precisa passar --session com cada comando. Use o exemplo de PowerShell ou Bash abaixo.
Substitua SESSION_ID abaixo pelo session_id retornado por session start ou session list.
Windows PowerShell:
$env:OPENSHOT_SESSION = "SESSION_ID"
& .\openshot-qt-cmd.exe --cli timeline view
& .\openshot-qt-cmd.exe --cli export start "C:\path\test.mp4" --wait
Linux Bash:
export OPENSHOT_SESSION="SESSION_ID"
./OpenShot.AppImage --cli timeline view
./OpenShot.AppImage --cli export start "/path/test.mp4" --wait
No macOS, use a mesma sintaxe export. Para comandos macOS ou Snap, substitua pelo executável da sua instalação conforme Iniciando. A seleção dura para este terminal e comandos iniciados a partir dele. Defina novamente em um novo terminal ou atualize ao mudar para uma sessão diferente.
Os exemplos restantes de edição e exportação assumem que OPENSHOT_SESSION está definido. A próxima subseção mostra como capturar o ID automaticamente para scripts.
Para direcionar uma sessão diferente para apenas um comando, use --session. Isso substitui OPENSHOT_SESSION sem alterar a seleção do seu terminal:
openshot-cli --session OTHER_SESSION_ID project get
Com um executável empacotado, coloque essa substituição após --cli e antes do grupo de comandos: --cli --session OTHER_SESSION_ID project get.
A seleção automática funciona apenas quando existe exatamente uma sessão acessível. Se você vir session_required, execute session list e selecione explicitamente a sessão desejada. Se ela não estiver mais listada, inicie-a novamente e use o novo ID. Ajuda, intro e descoberta de sessão não requerem uma sessão selecionada.
Capturando o ID da sessão automaticamente
Scripts podem ler result.session_id diretamente do JSON retornado por session start e definir OPENSHOT_SESSION para comandos subsequentes. Não há necessidade de copiar o ID manualmente ou ler um arquivo de log. Verifique se a inicialização foi bem-sucedida antes de usar o ID retornado.
Windows PowerShell (defina o caminho do executável para sua instalação):
$openshot = "C:\Program Files\OpenShot Video Editor\openshot-qt-cmd.exe"
$reply = & $openshot --cli session start
if ($LASTEXITCODE -ne 0) { throw "OpenShot session startup failed" }
$session = $reply | ConvertFrom-Json
if (-not $session.ok -or -not $session.result.session_id) {
throw "OpenShot did not return a session ID"
}
$env:OPENSHOT_SESSION = $session.result.session_id
& $openshot --cli timeline view
Linux Bash (requer jq para ler JSON):
openshot="/full/path/to/OpenShot.AppImage"
export APPIMAGELAUNCHER_DISABLE=1
if reply=$("$openshot" --cli session start) &&
session_id=$(printf '%s' "$reply" | jq -er 'select(.ok == true) | .result.session_id | strings | select(length > 0)'); then
export OPENSHOT_SESSION="$session_id"
"$openshot" --cli timeline view
else
echo "OpenShot session startup failed" >&2
fi
A variável de ambiente seleciona uma sessão para comandos iniciados a partir deste terminal; não altera uma configuração do sistema. Iniciar uma sessão não define a variável automaticamente. Após parar a sessão, limpe a seleção com Remove-Item Env:OPENSHOT_SESSION no PowerShell ou unset OPENSHOT_SESSION no Bash.
Exibindo e parando uma sessão
Para mostrar a sessão selecionada no editor:
openshot-cli session show
No desktop, session show cria o editor no mesmo processo e mantém o projeto ativo, IDs, histórico, trabalhos de exportação e conexão. Chamadas repetidas trazem a janela existente para frente. session start --show abre imediatamente. Sessões iniciadas sem exibição, ou com QT_QPA_PLATFORM=offscreen/minimal, não podem mostrar uma janela de desktop depois. Para essas sessões, salve e abra o projeto em uma nova sessão de desktop. Uma vez exibida, feche a sessão pela janela do editor.
Opções globais (--session, --timeout) vão antes do comando. session serve permanece em primeiro plano para supervisores; session start retorna após o registro de um host em segundo plano. session stop recusa alterações não salvas e exportações ativas. Use --discard apenas para descartar intencionalmente edições não salvas.
Saída do comando
Os resultados são JSON na saída padrão, exceto a visualização padrão da linha do tempo em texto. Erros são JSON na saída de erro com status de saída 1; erros do analisador de argumentos saem com status 2. Mutações retornam resumos compactos com um comando inspect. get retorna JSON de objeto nativo. Respostas de projeto incluem uma revisão; respostas do catálogo de efeitos não requerem sessão. Logs de sessões headless ficam ao lado de seus registros. OPENSHOT_SESSION_DIR substitui o diretório padrão ~/.openshot_qt/sessions.
As sessões aceitam comandos localmente no seu computador. Mantenha o registro da sessão privado, pois ele contém as credenciais usadas para acessar suas sessões de edição. As exportações funcionam a partir de um instantâneo, para que você possa continuar editando enquanto um trabalho está em execução.
Abrindo e salvando projetos
Um projeto OpenShot (.osp) armazena sua linha do tempo editável. Exportar cria um vídeo finalizado; salvar o projeto permite que você retorne aos seus clipes, efeitos e quadros-chave posteriormente. Salve seu projeto separadamente mesmo quando também exportar um vídeo.
Abrindo um projeto
Inicie uma sessão com um projeto existente:
openshot-cli session start --project "/home/me/Videos/My Project.osp"
Adicione --show para abrir também a janela do editor. Para usar um editor que já está em execução, localize-o com session list. Defina OPENSHOT_SESSION para o ID da sessão retornado, então abra ou inspecione um projeto:
openshot-cli project open "/home/me/Videos/My Project.osp"
openshot-cli project get
Substitua o caminho de exemplo pelo seu próprio e coloque entre aspas os caminhos que contêm espaços. project open substitui o projeto atual da sessão selecionada. Ele se recusa a descartar edições não salvas, a menos que você adicione explicitamente --discard; salve essas edições primeiro se quiser mantê-las. Abrir via CLI não exibe diálogos interativos de mídia ausente, então mantenha a mídia fonte do projeto disponível.
Para um projeto novo e vazio, use session start sem --project, depois importe mídia e adicione clipes conforme descrito em Edição.
Salvando um projeto ou uma cópia
Salve em um arquivo novo ou crie uma versão separada antes de fazer mais alterações:
openshot-cli project save "/home/me/Videos/My Project v2.osp"
Para atualizar um arquivo existente, permita explicitamente a substituição:
openshot-cli project save "/home/me/Videos/My Project v2.osp" --overwrite
Sempre forneça o caminho de destino. Salvar um arquivo .osp não inclui todas as suas filmagens originais nesse arquivo; mantenha a mídia referenciada disponível ao mover ou reabrir o projeto.
Exportando um vídeo
Automatize a renderização e exportação a partir de scripts ou agentes de IA, usando as configurações do projeto ou escolhendo um perfil de saída diferente para cada renderização. Os trabalhos de exportação podem ser executados em segundo plano ou aguardar a conclusão antes que seu script continue. Para renderizar um MP4 usando a resolução e taxa de quadros do projeto:
openshot-cli export start "/home/me/Videos/video.mp4" --wait
Por padrão, o OpenShot usa vídeo H.264 e áudio AAC. Substitua o caminho de exemplo pelo seu destino, usando uma pasta existente e um nome de arquivo novo. Saídas existentes nunca são sobrescritas. Exportar não salva seu projeto editável .osp; use project save separadamente para manter seu trabalho de edição.
A opção --wait mantém o comando em execução até que a exportação seja concluída ou reporte uma falha. Revise o vídeo finalizado antes de compartilhá-lo.
Verificando o progresso da exportação
Não use --wait para iniciar uma exportação em segundo plano. A resposta inclui um ID de trabalho que você pode usar para verificar seu progresso:
openshot-cli export start "/home/me/Videos/video.mp4"
openshot-cli export status JOB_ID
openshot-cli export status JOB_ID --wait
openshot-cli export list
Substitua JOB_ID pelo ID retornado. Se o tempo de espera expirar, a exportação continua em execução; verifique o mesmo trabalho em vez de iniciar outra exportação. Para parar um trabalho, use export cancel JOB_ID. Cada trabalho captura a linha do tempo quando inicia, então edições posteriores não alteram uma exportação já em andamento.
O tempo de espera padrão é 600 segundos; ajuste isso com --wait-timeout. Isso é separado do --timeout global por requisição. Falhas na exportação, cancelamento e tempos de espera encerram com status 1 e incluem detalhes do trabalho.
Exportando em múltiplos perfis
Exporte a mesma linha do tempo em diferentes resoluções ou proporções escolhendo um perfil de exportação para cada saída. Um perfil de exportação se aplica apenas a esse trabalho; ele não altera o perfil do projeto de edição. Um perfil define dimensões, taxa de quadros e proporção; um preset de exportação seleciona configurações de codificação como MP4/H.264.
Encontre os perfis disponíveis e inspecione suas configurações:
openshot-cli profile list --search 720
openshot-cli profile list --search 1080
openshot-cli profile get builtin:01280x0720p0030_16-09
Por exemplo, exporte versões em paisagem em 720p e 1080p, depois uma versão quadrada em 1080 por 1080. Esses perfis usam todos 30 fps:
openshot-cli export start "/home/me/Videos/video-720p.mp4" --profile builtin:01280x0720p0030_16-09 --wait
openshot-cli export start "/home/me/Videos/video-1080p.mp4" --profile builtin:01920x1080p0030_16-09 --wait
openshot-cli export start "/home/me/Videos/video-square.mp4" --profile builtin:01080x1080p0030_01-01 --wait
Use um nome de arquivo de saída diferente para cada versão. Mantenha as edições inalteradas entre os trabalhos quando desejar versões correspondentes. Alterar a proporção pode mudar o enquadramento: revise cada saída, especialmente títulos e sujeitos animados. Para uma versão quadrada ou retrato composta separadamente, salve uma cópia do projeto, altere seu perfil de projeto e ajuste os clipes antes de exportar. Veja Perfis e as configurações de exportação abaixo para perfis personalizados e opções de codificação.
Exportação em lote de múltiplos projetos
Reutilize uma sessão headless para renderizar vários projetos salvos em sequência. Abra um projeto, exporte-o com --wait, depois abra o próximo projeto. Os exemplos abaixo usam a resolução e taxa de quadros de cada projeto e criam arquivos MP4 ao lado dos arquivos .osp. Adicione --profile PROFILE_ID ao comando de exportação para usar um perfil de saída para todos os projetos.
Execute primeiro o exemplo automático de session-ID correspondente acima com sucesso, no mesmo terminal. Ele define openshot e seleciona a nova sessão. Substitua os caminhos do projeto abaixo pelos seus próprios. Use nomes de saída distintos que ainda não existam; os exemplos verificam todos os destinos antes de iniciar o lote.
Windows PowerShell:
$projects = @(
"C:\VideoProjects\First.osp",
"C:\VideoProjects\Second.osp"
)
foreach ($project in $projects) {
if (-not (Test-Path -LiteralPath $project -PathType Leaf)) {
throw "Project not found: $project"
}
$output = [System.IO.Path]::ChangeExtension($project, ".mp4")
if (Test-Path -LiteralPath $output) { throw "Output already exists: $output" }
}
foreach ($project in $projects) {
$output = [System.IO.Path]::ChangeExtension($project, ".mp4")
& $openshot --cli project open $project
if ($LASTEXITCODE -ne 0) { throw "Could not open: $project" }
& $openshot --cli export start $output --wait --wait-timeout 86400
if ($LASTEXITCODE -ne 0) { throw "Export needs attention: $output" }
}
& $openshot --cli session stop
if ($LASTEXITCODE -ne 0) { throw "Could not stop the session" }
Remove-Item Env:OPENSHOT_SESSION
Linux Bash (os parênteses mantêm o tratamento de erros local ao lote):
(
set -e
: "${OPENSHOT_SESSION:?Run the session startup example first}"
projects=(
"/home/me/VideoProjects/First.osp"
"/home/me/VideoProjects/Second.osp"
)
for project in "${projects[@]}"; do
test -f "$project" || { echo "Project not found: $project" >&2; exit 1; }
output="${project%.osp}.mp4"
test ! -e "$output" || { echo "Output already exists: $output" >&2; exit 1; }
done
for project in "${projects[@]}"; do
"$openshot" --cli project open "$project"
"$openshot" --cli export start "${project%.osp}.mp4" --wait --wait-timeout 86400
done
"$openshot" --cli session stop
) && unset OPENSHOT_SESSION
Ambas as receitas param o lote em caso de falha de comando e deixam a sessão disponível para inspeção. O limite de espera aqui é de 24 horas por exportação. Um tempo limite de espera deixa a renderização em execução: use export list e export status JOB_ID --wait antes de tentar novamente. Vídeos concluídos permanecem no disco; remova projetos concluídos do lote antes de retomar. Após resolver uma falha, pare a sessão e limpe sua variável de ambiente quando terminar.
Escolhendo predefinições e configurações de codificação
Descubra as predefinições de exportação instaladas e as configurações suportadas:
openshot-cli export preset list
openshot-cli export preset get builtin:format_mp4_x264
openshot-cli export capabilities
openshot-cli export start /tmp/reel.mp4 --preset builtin:format_mp4_x264 --quality med --wait
Exportação também aceita --from-file FILE_ID com --create-custom opcional. As configurações são resolvidas nesta ordem: padrões do projeto, predefinição, JSON avançado, flags explícitas de perfil/qualidade/faixa. O JSON avançado expõe codecs de vídeo/áudio e taxa de bits, layout/taxa/canais de áudio, opções nativas de codec, configurações de dispositivo de hardware e contagem de threads.
Por exemplo, selecione uma opção de codificador através do JSON avançado:
openshot-cli export start /tmp/small.mp4 --profile builtin:00640x0360p0030_16-09 --json '{"video_options":{"preset":"fast"}}' --wait
Validando configurações de exportação
Verifique as configurações antes de iniciar uma renderização:
openshot-cli export validate /tmp/reel.mp4 --preset builtin:format_mp4_x264
O relatório de capacidades compila a disponibilidade de codecs, não a disponibilidade física da GPU. A validação vai além: ela abre os codificadores (incluindo codificadores de hardware) e o contêiner com as configurações exatas, em um processo separado, sem escrever um arquivo. Uma combinação que o contêiner não suporta falha com incompatible_export, a própria explicação do FFmpeg, e a configuração a ser alterada (details.cause.path):
openshot-cli export validate /tmp/song.mp3 --json '{"mode":"audio","format":"mp3","audio_codec":"aac"}'
O trabalhador de exportação executa a mesma verificação antes da renderização.
Renderizando um intervalo de quadros
Use --start-frame e --end-frame para renderizar parte da linha do tempo. Os intervalos são inclusivos e baseados em um no FPS do perfil de exportação. Por exemplo, renderize os primeiros 90 quadros a 30 fps (três segundos):
openshot-cli export start /tmp/excerpt.mp4 --profile builtin:01280x0720p0030_16-09 --start-frame 1 --end-frame 90 --wait
Exportações somente de áudio e sequências de imagens
Escolha um modo de saída com JSON avançado:
openshot-cli export start /tmp/music.wav --json '{"mode":"audio","format":"wav","audio_codec":"pcm_s16le"}' --wait
openshot-cli export start /tmp/frames --json '{"mode":"image_sequence","format":"png"}' --end-frame 3 --wait
Sequências de imagens requerem um novo diretório de saída. Saídas existentes nunca são sobrescritas.
Edição
Adicionando clipes e efeitos
Use os IDs retornados por import/add/list, e descubra os números das camadas com project get:
openshot-cli file import /absolute/path/video.mp4
openshot-cli clip add FILE_ID --layer 2000000 --position 3 --start 10 --end 17 --volume 0
openshot-cli clip set CLIP_ID --json '{"volume":0.5}'
openshot-cli clip keyframe set CLIP_ID --property volume --frame 301 --value 0
openshot-cli clip keyframe set CLIP_ID --property volume --frame 331 --value 1
openshot-cli effects add CLIP_ID saturation
openshot-cli effects set EFFECT_ID --json '{"saturation":1.2}'
openshot-cli project save /absolute/path/edit.osp
Escolha o perfil do projeto cedo quando possível; projetos populados também suportam mudanças de perfil através da conversão de FPS existente e sistema de desfazer. --audio-only na criação do clipe suprime o vídeo, incluindo a arte da capa embutida em arquivos de música. Para usar esse clipe para Visualização de Áudio, ative seu vídeo e áudio, e siga a ajuda do efeito para sobreposições transparentes e posicionamento de camadas.
Entendendo o tempo do clipe
Os keyframes do exemplo assumem um projeto de 30fps e um clipe cortado na fonte em 10s. A posição está em segundos da linha do tempo; início/fim são segundos da fonte, com fim exclusivo. Os quadros começam em 1. Quadros de miniatura de arquivo usam FPS da fonte. Quadros da linha do tempo usam FPS do projeto. Keyframes do clipe usam coordenadas da fonte no FPS do projeto, então cortar o clipe não move seu primeiro keyframe visível para o quadro 1.
Alterando propriedades
set mescla propriedades de nível superior. Escalares transformam propriedades com keyframes em constantes. Uma curva aninhada fornecida substitui essa curva; use keyframe set para alterar apenas um ponto. Argumentos JSON aceitam JSON embutido, @file.json, ou - para stdin. Nomes de propriedades, tipos, enums, keyframes, referências e temporização são validados antes da edição do projeto. Erros identificam o campo, valor esperado, valor recebido e uma correção quando possível. Faixas de sliders da GUI são consultivas onde o motor suporta valores além delas.
Adicionando transições
clip fade ID --in 0.5 --out 0.5 calcula automaticamente as coordenadas dos keyframes do corte da fonte. Substitui a curva alfa; --property volume --value 0.25 cria uma transição de áudio com ganho máximo de 0,25. As durações devem caber entre o primeiro e o último quadro visível; o fade-out atinge zero no último quadro.
Dividindo clipes
clip split ID --at 6.5 usa segundos da linha do tempo, ajusta para o quadro do projeto mais próximo e mantém ambas as metades. Retém curvas de coordenadas da fonte e duplica efeitos com novos IDs na metade direita, seguindo o comportamento de corte do editor. A metade esquerda mantém seu ID. A resposta informa os tempos de corte solicitados/atuais e ambos os resumos; um resultado nomeado do lote suporta {"$ref":"cut.right.id"}. Cortes rejeitam pontos finais e faixas bloqueadas. Desfazer restaura o clipe original em uma transação.
Adicionando e estilizando texto
text add cria um texto e o posiciona como um clipe, usando o mesmo texto da ferramenta Texto do editor. As opções que você omitir usarão o estilo padrão do editor:
openshot-cli text add --text "Opening Night" --layer 5000000 --position 2 --duration 4 \
--place lower-third --font "Noto Sans" --size 72 --bold --color "#ffffff" \
--background "#80000000" --background-padding 16 --background-corner 12
openshot-cli text get CLIP_ID
openshot-cli text set CLIP_ID --stroke black --stroke-width 3
openshot-cli text set CLIP_ID --text $'Two\nlines' --line-spacing 1.4
openshot-cli text fonts --search noto
openshot-cli text list --search opening
As palavras, fonte, tamanho, alinhamento, largura da caixa e cores padrão pertencem ao texto nos Arquivos do Projeto e são compartilhados por todos os clipes que o utilizam, assim como no editor. text set em um clipe altera todos eles e os lista em changed_clip_ids; --this-clip-only dá a esse clipe sua própria cópia primeiro. clip add FILE_ID adiciona outro clipe de um texto da lista text list. Os tamanhos estão em pixels na resolução do projeto, e as cores são #RRGGBB, #AARRGGBB (com alfa), um nome CSS ou transparent. --place posiciona a caixa no centro, em uma borda ou canto, ou em um terço inferior. --line-spacing é um múltiplo da distância normal entre linhas (1 é normal), e --background-corner arredonda os cantos do fundo e da borda por essa quantidade de pixels.
Um clipe de texto é um clipe comum. Posição, escala, rotação, opacidade, tempo, transições, predefinidos de movimento e efeitos usam os comandos normais de clip. Tamanho da fonte, espaçamento interno, largura da caixa, espaçamento entre letras e linhas definem o tamanho da caixa de texto, portanto não podem ser animados por quadros-chave; para animar o tamanho do texto, anime a escala do clipe. Cada clipe pode animar suas próprias cores de texto, contorno e larguras de borda com os mesmos comandos de quadro-chave que qualquer outra propriedade:
openshot-cli clip keyframe list CLIP_ID
openshot-cli clip keyframe set CLIP_ID --property text_color.alpha --space clip --unit seconds --at 0 --value 0
openshot-cli clip keyframe set CLIP_ID --property text_color.alpha --space clip --unit seconds --at 1 --value 255
As propriedades animadas são text_color, text_background, text_stroke e text_border (cores, com .red, .green, .blue e .alpha de 0 a 255), além de text_stroke_width, text_border_width e text_background_corner. A animação própria de um clipe prevalece sobre o estilo compartilhado, e text get lista quais estilos um clipe anima. text reset CLIP_ID retorna um clipe ao estilo padrão, como Texto → Redefinir Estilo; --keyframes-only apenas remove a animação própria do clipe. Para estilizar vários textos ao mesmo tempo, selecione-os com {"text":true}:
openshot-cli edit bulk --select '{"text":true}' --json '[{"method":"text.set","params":{"font_family":"Noto Sans","stroke_width":2}}]'
Aplicando um lote de edições
edit apply --json @edits.json --expect-revision 12 aceita até 256 comandos de mutação ordenados, usando nomes de comando pontilhados como clip.set e effects.add (a grafia antiga effect.add também funciona):
[
{"method":"project.profile.set","params":{"id":"builtin:01280x0720p0024_16-09"}},
{"method":"file.import","as":"media","params":{"path":"/tmp/video.mp4"}},
{"method":"clip.add","as":"shot","params":{"file_id":{"$ref":"media.id"},"layer":1000000,"start":10,"end":15}},
{"method":"clip.fade","params":{"id":{"$ref":"shot.id"},"fade_in":0.5,"fade_out":0.5}}
]
O opcional as vincula um resultado para comandos posteriores no mesmo lote. Um objeto {"$ref":"shot.id"} substitui o campo desse resultado. Referências resolvem apenas nomes anteriores; erros de digitação, referências futuras e nomes duplicados falham antes das atualizações ao vivo. A resposta inclui resultados compactos ordenados e um mapa refs dos IDs reais. Todas as alterações em um lote bem-sucedido formam um único passo de desfazer/refazer. project.profile.set também suporta timelines populadas. Comandos de abrir, salvar, exportar e inspeção ficam fora dos lotes de edição. A ajuda de cada comando lista os nomes dos parâmetros JSON, incluindo a grafia com sublinhado das flags do shell (por exemplo, --fps-num vira fps_num).
Validando lotes e tratando erros
Todos os comandos em lotes de edição são pré-validados contra um projeto destacado antes de quaisquer atualizações ao vivo. Entrada inválida mantém o projeto ao vivo e a revisão inalterados. Lotes válidos formam um único grupo de desfazer. Falhas inesperadas em tempo de execução ainda podem produzir alterações parciais; erros reportam operações concluídas. Um tempo limite não implica cancelamento, então inspecione o estado antes de tentar mutações novamente.
Edição precisa de quadros-chave
clip, transition e effects suportam keyframe list, set, remove, clear, transform, copy e paste. Caminhos de propriedades podem acessar curvas aninhadas, como color.red em um efeito Chroma Key. Editar uma curva aninhada preserva canais irmãos. Execute keyframe list ID sem uma propriedade para descobrir caminhos de curvas e contagem de pontos. A descoberta e listagem de pontos incluem contexto de tempo de corte/posição; listagens de pontos também reportam coordenadas nativas de quadros. get e properties expõem o objeto nativo completo e metadados da propriedade. Erros identificam campos inválidos, sugerem nomes de propriedades próximos e explicam correções de coordenadas.
Escolha coordenadas explicitamente com --space native|clip|timeline e --unit frames|seconds. Todos os quadros usam FPS do projeto e são baseados em 1; segundos começam em zero e se ajustam ao quadro mais próximo. Native é a coordenada de quadro-chave existente do motor (incluindo corte da fonte). Coordenadas do clipe começam no ponto de entrada visível do clipe; coordenadas da linha do tempo começam no tempo zero do projeto. Efeitos anexados usam o tempo do clipe pai. Essas coordenadas referem-se ao tempo da animação, não aos quadros de mídia selecionados por uma curva de remapeamento de tempo.
Para um clipe posicionado em 5 segundos, aparado em 2 segundos, em um projeto de 30 fps, o quadro do clipe 1, o quadro da linha do tempo 151 e o quadro nativo 61 correspondem ao mesmo ponto. Posição e aparo encaixam-se independentemente na grade de quadros do projeto. Listar uma curva inteira pode incluir pontos ocultos com coordenadas de clipe/linha do tempo não positivas. O legado --frame ainda significa um quadro nativo e não pode ser combinado com --at.
Exemplos:
openshot-cli clip keyframe set CLIP --property location_x --space clip --unit seconds --at 0 --value -1
openshot-cli clip keyframe set CLIP --property location_x --space clip --unit seconds --at 1 --value 0 --interpolation bezier --handles '{"handle_left":{"X":0.2,"Y":0.9}}'
openshot-cli effects keyframe set EFFECT --property color.red --space clip --at 31 --value 200
openshot-cli clip keyframe list CLIP --property location_x --space clip --unit seconds
openshot-cli clip keyframe transform CLIP --property location_x --space clip --start 1 --end 31 --scale 2 --offset 15
openshot-cli clip keyframe copy TARGET --property location_x --source-id SOURCE --space clip --start 1 --end 31 --at 1 --mode merge
openshot-cli clip keyframe remove CLIP --property location_x --space clip --at 31
openshot-cli clip keyframe clear CLIP --property location_x --value 0
Interpolação, suavização e pré-visualização
A interpolação descreve o segmento até o ponto de destino. Linear fornece uma taxa constante entre os pontos. Constante mantém o valor anterior até o destino, então salta. Os manipuladores Bezier padrão nativos suavizam em ambas as extremidades de cada segmento. Adicionar um ponto intermediário pode, portanto, introduzir uma desaceleração não intencional; para um movimento suavizado, comece com dois pontos finais. Normalmente, deixe os manipuladores intactos e escolha um predefinido nomeado para um estilo específico.
Descubra os mesmos predefinidos de suavização usados pelos menus do editor, sem uma sessão:
openshot-cli clip keyframe presets
Aplique um predefinido ao segmento de entrada definindo seu destino:
openshot-cli clip keyframe set CLIP --property scale_x --space clip --unit seconds --at 0 --value 1
openshot-cli clip keyframe set CLIP --property scale_x --space clip --unit seconds --at 4 --value 1.2 --easing ease-in-out
A opção de suavização implica Bezier. Ela define o manipulador de saída do ponto anterior e o manipulador de entrada do destino juntos, preservando outros manipuladores e valores dos pontos. Um ponto anterior deve existir. Não combine com manipuladores personalizados ou uma interpolação diferente. Predefinições funcionam em lotes e modelos em massa. O predefinido da GUI ease («Suavização (Padrão)») difere dos manipuladores nativos usados pela interpolação Bezier simples. Predefinições de retorno podem ultrapassar os valores dos pontos finais.
Inspecione o movimento antes da renderização, usando o avaliador de curva nativo:
openshot-cli clip keyframe preview CLIP --property scale_x --space clip --unit seconds --start 0 --end 4
openshot-cli clip keyframe preview CLIP --property scale_x --space clip --unit seconds --at 2
A pré-visualização é somente leitura e funciona de forma idêntica para efeitos e transições. Ela retorna valores e taxas de entrada/saída assinadas em unidades de propriedade por segundo, calculadas a partir de quadros imediatamente adjacentes. Estas são diferenças finitas, não derivadas analíticas. No quadro nativo 1, a taxa de entrada é nula. Taxas de quadros adjacentes podem inspecionar fora do intervalo solicitado. Taxas próximas de zero ao redor de um ponto interno revelam uma pausa; taxas diferentes revelam uma mudança de velocidade. A interpolação constante revela um salto no destino.
Sem um intervalo, a pré-visualização abrange os primeiros e últimos pontos da curva. Os intervalos são inclusivos, com 17 amostras espaçadas uniformemente por padrão (–count: 2–256). Keyframes e seus vizinhos imediatos dentro do intervalo também são incluídos, então uma contagem de amostras esparsa não ocultará uma parada de keyframe. O máximo é 1024 amostras; solicitações maiores requerem um intervalo mais estreito. –at amostra um quadro. A pré-visualização reporta coordenadas no espaço solicitado e quadros nativos reais; segundos encaixam-se nos quadros do projeto como na edição.
Para manipuladores personalizados avançados, tanto X quanto Y são normalizados para o segmento: X é uma fração do intervalo de quadros; Y é uma fração da mudança de valor. O primeiro controle vem do handle_right do ponto anterior, o segundo do handle_left do destino. Os padrões nativos são right=(0.5, 0), left=(0.5, 1), com tangentes planas nas extremidades. Alterar apenas o handle_type não recalcula uma tangente contínua através dos pontos ao redor. Manipuladores existentes são preservados ao mover um ponto.
Intervalos de keyframe são inclusivos, diferente dos intervalos de tempo de seleção de clipes. A listagem emite points cujos valores co.X usam o espaço/unidade de coordenadas solicitado. Passe esse array para keyframe paste --json @points.json com o mesmo espaço/unidade, escolhendo --mode merge (substitui quadros correspondentes, mantém outros) ou --mode replace (substitui toda a curva). copy aceita uma fonte do mesmo tipo de objeto, uma --source-property opcional, e ancora o primeiro ponto selecionado da fonte em --at no alvo. Outras curvas e objetos fonte permanecem inalterados.
transform aplica uma escala de tempo positiva ao redor do primeiro ponto selecionado, ou --pivot, seguido por um --offset assinado na unidade escolhida. O encaixe de quadros que cria coordenadas duplicadas é rejeitado, incluindo colisões com pontos fora do intervalo selecionado. Coordenadas nativas devem permanecer pelo menos 1. Manipuladores Bézier normalizados nativos e interpolação acompanham cada ponto; manipuladores não são coordenadas absolutas de quadro. set --handles altera apenas os manipuladores fornecidos. A interpolação pertence ao ponto de destino.
clear mantém um ponto base constante no quadro nativo 1: especifique --value ou amostre a curva existente com --at (quadro nativo 1 por padrão). Remover o último ponto também mantém uma base constante, para que adições subsequentes de keyframes permaneçam válidas.
Selecionando e editando vários clipes
Use edit apply --dry-run para validar um lote sem alterar o projeto. Use edit bulk para repetir um pequeno modelo de comando para cada clipe selecionado, com todas as alterações agrupadas em uma única etapa de desfazer.
Primeiro pré-visualize uma seleção:
openshot-cli edit select --json '{"layer":1000000,"start":5,"end":20,"effect":"Saturation"}'
Os seletores suportam ids (array de IDs únicos de clipes), layer, start/end (segundos na linha do tempo), file_id, effect (nome da classe ou alias) e text (true seleciona clipes de texto). Os filtros combinam com E. Intervalos de tempo selecionam clipes que se sobrepõem a [start, end); eles não cortam esses clipes. Os resultados são ordenados por posição, camada, depois ID, e incluem IDs, resumos, estado de bloqueio e a revisão atual. IDs desconhecidos são erros. Um seletor vazio é rejeitado; use {"all":true} explicitamente para cada clipe. As seleções são limitadas a 256 clipes e nunca são truncadas silenciosamente.
Por exemplo, salve este array como templates.json:
[
{"method":"clip.adjust","params":{"values":{"position":{"add":2},"volume":{"multiply":0.5}}}},
{"method":"effects.add","as":"look","params":{"type":"Saturation"}},
{"method":"effects.keyframe.set","params":{"id":{"$ref":"look.id"},"property":"saturation","space":"clip","at":1,"value":0}},
{"method":"effects.keyframe.set","params":{"id":{"$ref":"look.id"},"property":"saturation","space":"clip","at":31,"value":1.2}}
]
Valide-o, então aplique contra a revisão retornada pela seleção:
openshot-cli edit bulk --select '{"ids":["CLIP_A","CLIP_B"]}' --json @templates.json --dry-run
openshot-cli edit bulk --select '{"ids":["CLIP_A","CLIP_B"]}' --json @templates.json --expect-revision 42
Comandos para clipes existentes herdam id; effects.add herda clip_id. Omitir esses parâmetros de destino em templates. Edições de efeitos devem referenciar um resultado nomeado anterior. Os nomes são locais para cada clipe selecionado, então look.id refere-se a um efeito diferente para cada clipe. Para alterar instâncias existentes de efeitos por ID explícito, continue usando edit apply. O conjunto de IDs selecionados é fixo antes da expansão; mudanças na posição ou efeitos não alteram os alvos restantes.
clip set aplica propriedades absolutas; clip adjust aplica multiply e depois add a uma propriedade numérica ou a cada valor em uma curva, preservando o tempo dos pontos, interpolação e alças normalizadas. Ele valida os valores resultantes, incluindo posições não negativas e volume. Campos estruturais permanecem protegidos.
Operações em lote rejeitam seleções vazias, faixas de destino bloqueadas e mais de 256 comandos expandidos. Cada operação expandida passa por uma verificação prévia separada antes de qualquer edição ao vivo. Execuções de teste não reservam IDs gerados. Use --expect-revision para rejeitar seleções obsoletas. Lotes bem-sucedidos são um único passo de desfazer, inclusive após salvar/reabrir. Atualizações da GUI são agrupadas. Erros inesperados em tempo de execução/ouvintes ainda podem deixar uma transação parcial; o erro relata operações concluídas e o desfazer reverte esse grupo, como em edit apply.
Perfis
Descubra perfis e combine vídeos importados sem adivinhar IDs:
openshot-cli profile list --search 720
openshot-cli profile get builtin:01280x0720p0024_16-09
openshot-cli profile match --file FILE_ID
openshot-cli project profile get
openshot-cli project profile set --from-file FILE_ID
openshot-cli project profile set builtin:01280x0720p0024_16-09
openshot-cli project profile set --json '{"width":640,"height":352,"display_ratio":{"num":20,"den":11},"fps":{"num":24000,"den":1001}}'
Entradas do catálogo incluem IDs estáveis, descrições, dimensões, FPS racional, proporções e configurações de varredura. Listagem/pesquisa é paginada. A correspondência de fonte retorna IDs exatos e alternativas classificadas com diferenças explícitas. Definir a partir de um arquivo requer correspondência exata, a menos que --create-custom seja especificado; nunca escolhe silenciosamente um perfil próximo. Imagens estáticas e fontes somente de áudio não podem definir um perfil de vídeo. A correspondência usa o FPS declarado da fonte.
Configurações personalizadas são incorporadas no projeto salvo, incluindo taxas racionais, então reabrir não requer instalar um arquivo de perfil separado. Mudanças no perfil do projeto usam conversão de taxa de quadros existente e uma transação de desfazer. Desfazer/refazer restaura o tempo do clipe e keyframes, incluindo posições sensíveis a arredondamento. A exportação pode selecionar um perfil independentemente sem alterar o projeto.
O histórico de desfazer salvo segue a preferência de limite de histórico do editor. O limite é um orçamento suave de ações: todos os registros pertencentes a transações retidas são mantidos, então salvar não pode truncar um grande lote em uma ação de desfazer parcial. Zero desativa o histórico salvo. O limite separado de 256 comandos por lote ainda se aplica.
Inspecionando mídia e linhas do tempo
Inspecione o tempo do clipe e o layout da faixa como texto ou JSON, ou renderize imagens para revisar composição e enquadramento antes de exportar.
Resumos da linha do tempo
Use uma visualização em texto para uma visão rápida, ou JSON estruturado para scripts e agentes:
openshot-cli timeline view --start 5 --end 12
openshot-cli timeline view --start 5 --end 12 --format json
openshot-cli timeline overview --start 5 --end 12
timeline view padrão é texto compacto com faixas usadas, IDs de objetos, intervalos da linha do tempo/fonte, estado do fluxo, ganho e lacunas/sobreposições. Use --detail summary|clips|full para escolher o detalhe, --format json para contexto estruturado, e --start/--end, --layer e paginação para focar o resultado.
timeline overview fornece contexto estruturado compacto sem bytes de imagem: IDs ordenados, sequência por faixa, intervalos da linha do tempo/fonte, faixas de corte visíveis, coordenadas de quadros, estado de áudio/vídeo, efeitos e lacunas ou sobreposições vizinhas. Intervalos e spans de quadros são exclusivos no final; números de quadros são baseados em um. Quadros da fonte usam FPS da fonte; coordenadas da linha do tempo e keyframes usam FPS do projeto. Use --layer e --start/--end para focar, e --limit/--offset para paginar (padrão 100, máximo 500 itens). Clipes com remapeamento de tempo retêm explicitamente mapeamentos de fonte inferidos. Use a revisão retornada com edit apply --expect-revision.
Pré-visualizações de quadros e folhas de contato
Renderize um único quadro com thumbnail ou amostre um intervalo com strip. Use file para inspecionar a mídia fonte e timeline para inspecionar o vídeo composto, incluindo efeitos e clipes em camadas:
openshot-cli file thumbnail FILE_ID --frame 301 --output /tmp/source.png
openshot-cli file strip FILE_ID --start 10 --end 20 --count 12 --output /tmp/source-strip.png
openshot-cli timeline thumbnail --frame 91 --output /tmp/timeline-frame.png
openshot-cli timeline strip --start 0 --end 20 --count 12 --output /tmp/timeline-strip.png
Imagens de quadros padrão são 320x180 pixels; folhas de contato padrão são 160x90 por bloco, além de etiquetas de timecode. Use --width e --height para escolher os pixels de saída. Respostas incluem metadados exatos de amostra/quadro. Folhas de contato ajudam a revisar a composição ao longo de uma sequência; use pré-visualizações de keyframes e vídeo renderizado para avaliar o movimento entre essas amostras.
Imagens da linha do tempo
Capture o layout das faixas do editor, incluindo sua régua, miniaturas, efeitos, transições e formas de onda:
openshot-cli timeline view --start 0 --end 20 --pixels-per-second 80 --output /tmp/tracks.png
Especificar --output seleciona o formato da imagem; --format image também o seleciona explicitamente. A captura não altera a visualização ou o projeto do editor. As respostas incluem IDs dos clipes e temporização junto com os limites em pixels.
As imagens têm largura padrão de 1280 pixels, com altura ajustada às faixas usadas. Use --width, --height ou --all-tracks para ajustar o layout, e --track-size ou --track-label-width para ajustar faixas e rótulos. O intervalo de início/fim determina o zoom; --pixels-per-second deriva a largura a partir do intervalo de tempo.
Visualizações de formas de onda de áudio
Escolha --mode waveforms para inspecionar envelopes de áudio na linha do tempo:
openshot-cli timeline view --start 5 --end 12 --mode waveforms --output /tmp/waves.png
--mode auto usa a exibição de forma de onda em cache existente; --mode thumbnails mostra miniaturas em vez disso. As formas de onda representam níveis de pico/RMS da fonte com ajustes de volume e temporização do clipe, antes dos efeitos de áudio ou mixagem.
A extração de forma de onda não em cache decodifica fontes inteiras, limitada a 600 segundos por fonte e 1200 segundos-fonte por solicitação. Reduzir o intervalo visível não diminui esse trabalho de decodificação. Para fontes mais longas, gere formas de onda no editor primeiro ou use o modo miniaturas. Solicitações subsequentes podem reutilizar formas de onda em cache.
Saída e limites de imagem
Os caminhos das imagens devem ser arquivos PNG novos em diretórios existentes. As imagens são limitadas a 4096 pixels por eixo, 8.388.608 pixels totais e 64 amostras de folha de contato. Solicitações além desses limites falham antes da renderização.
As imagens são gravadas em arquivos; respostas JSON incluem seus caminhos e tamanhos image_bytes. A inspeção aguarda a conclusão da imagem, e solicitações grandes podem ocupar brevemente o editor.
Tratamento de tempos limite de comando
Um tempo limite de solicitação não significa que uma mutação falhou. Use o ID da operação no erro com operation get ID antes de tentar novamente. operation list descobre mutações recentes e seus estados, revisões e resultados. Operações concluídas mantêm seus resultados quando pequenos o suficiente, incluindo IDs de objetos retornados. O armazenamento é limitado a 100 operações e 4 MiB, com corpos de resultados individuais omitidos acima de 256 KiB. Esses registros duram apenas para a sessão em execução. Eles não restauram projetos após uma falha nem impedem que um comando repetido aplique a mesma edição novamente. Trabalhos de exportação têm seus próprios comandos de status/lista.