Interfaccia a riga di comando
Integra OpenShot nel tuo flusso di lavoro da riga di comando. Importa filmati, taglia e organizza clip, applica effetti, anima proprietà con fotogrammi chiave ed esporta video dal terminale. Usa pochi comandi per automatizzare modifiche ripetitive, scrivere uno script per un progetto ricorrente o lascia che un agente AI aiuti a assemblare e perfezionare un video.
La riga di comando funziona con gli stessi progetti dell’editor. Puoi controllare un editor aperto e rivedere le modifiche mentre procedi, oppure lavorare in una sessione headless senza aprire una finestra. Una sessione mantiene il progetto aperto tra i comandi, incluse le modifiche, la cronologia annulla e i lavori di esportazione. Salvalo come progetto .osp ogni volta che vuoi continuare a modificare in seguito.
Per iniziare
Usa l’eseguibile OpenShot installato seguito da --cli. Inizia con intro per una breve guida su sessioni, modifica, animazione e salvataggio, oppure help per una panoramica dei comandi. Questi comandi non richiedono una sessione attiva. Gli esempi seguenti richiedono una build di OpenShot che includa la modifica da riga di comando.
Linux AppImage
Dalla directory contenente il tuo AppImage scaricato:
./OpenShot.AppImage --cli intro
./OpenShot.AppImage --cli help
Sostituisci OpenShot.AppImage con il nome del file scaricato. Se AppImageLauncher mostra finestre di integrazione desktop, imposta APPIMAGELAUNCHER_DISABLE=1 prima di eseguire il comando:
APPIMAGELAUNCHER_DISABLE=1 ./OpenShot.AppImage --cli intro
Per script o comandi ripetuti, impostalo una volta nella shell corrente:
export APPIMAGELAUNCHER_DISABLE=1
./OpenShot.AppImage --cli session start
La variabile deve essere impostata prima di avviare l’AppImage: AppImageLauncher può intercettarla prima che OpenShot riceva --cli. I percorsi relativi dei media e i file @batch.json sono risolti dalla tua directory di lavoro. Mantieni il file AppImage disponibile mentre le sue sessioni o esportazioni sono in esecuzione.
Linux Snap
Per il OpenShot Snap, usa:
snap run openshot-qt --cli intro
snap run openshot-qt --cli help
snap run openshot-qt --cli session start
I permessi dei file di Snap si applicano anche alla modifica da riga di comando. Conserva media, progetti ed esportazioni in posizioni accessibili da Snap, come la tua cartella home. Per consentire l’accesso a unità esterne, connetti il permesso removable-media:
sudo snap connect openshot-qt:removable-media
Windows
Importante
Usa openshot-qt-cmd.exe per la modifica da riga di comando su Windows. Questo eseguibile da console mostra risultati dei comandi, aiuto ed errori nel terminale. L’eseguibile desktop, openshot-qt.exe, non mostra l’output standard in un terminale interattivo, lasciando i comandi senza feedback visibile e rendendo difficile l’uso della CLI.
In PowerShell, dalla directory di installazione di OpenShot:
& .\openshot-qt-cmd.exe --cli intro
& .\openshot-qt-cmd.exe --cli help
& .\openshot-qt-cmd.exe --cli session start
Se ti trovi in una directory diversa, usa il percorso completo di openshot-qt-cmd.exe. Mantieni --cli dopo il nome dell’eseguibile.
macOS
Per un’installazione in Applications:
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli intro
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli help
Trovare i comandi
In questa guida, openshot-cli è un’abbreviazione per il comando della tua installazione sopra, come snap run openshot-qt --cli o ./OpenShot.AppImage --cli. Alcune installazioni forniscono anche un comando openshot-cli direttamente. Quando esegui dal sorgente, usa python3 src/launch.py --cli nell’ambiente Python di OpenShot.
I comandi --cli, --cli help e --cli --help mostrano la stessa panoramica. L’aiuto diventa più specifico man mano che navighi tra i comandi:
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
L’aiuto di gruppo spiega i flussi di lavoro con esempi; l’aiuto operativo descrive argomenti e comportamento. --help è equivalente a help finale. Tutti i comandi di aiuto funzionano senza una sessione di modifica.
effects list mostra gli effetti disponibili con brevi descrizioni. L’aiuto sugli effetti spiega proprietà, valori predefiniti, scelte e intervalli. effects instances elenca gli effetti già applicati ai clip, con gli ID dei clip genitori. Nomi di classe, nomi visualizzati e alias con underscore identificano lo stesso effetto.
Lavorare con script e agenti AI
Agenti di codifica AI come Codex e Claude Code possono usare la CLI per ispezionare e modificare progetti OpenShot tramite comandi terminale. Fornisci al tuo agente il percorso dell’eseguibile OpenShot, i media o il progetto su cui lavorare e il risultato desiderato: durata, dimensioni, stile di animazione e posizione di output. Chiedigli di leggere --cli intro prima di iniziare. Gli stessi comandi funzionano sia se li digiti tu stesso sia se li esegui da uno script.
Inizia con intro, poi usa l’aiuto specifico per comando secondo necessità. Un flusso di lavoro utile è selezionare una sessione, ispezionare il progetto, apportare un piccolo insieme di modifiche, rivedere il risultato e salvare. I comandi restituiscono JSON strutturato così che script e agenti possano usare direttamente gli ID degli oggetti e i risultati invece di interpretare l’output a schermo.
Ispeziona prima di modificare. Usa gli ID restituiti e le informazioni sulle proprietà invece di indovinare nomi, numeri di traccia o tempi. Seleziona esplicitamente una sessione quando più di un progetto è aperto.
Raggruppa le modifiche ripetute. Usa
edit applyper una sequenza di modifiche oedit bulkper applicare un modello ai clip selezionati. Valida con--dry-runprima di applicare un batch.Controlla l’animazione. Scegli uno spazio di coordinate, inizia con alcune keyframe e usa i preset di easing per un movimento familiare.
keyframe previewcampiona la curva così puoi individuare pause o salti prima dell’esportazione. Controlla anche il movimento renderizzato; una semplice tabella di contatti non può mostrare come si percepisce un’animazione.Salva e segui le esportazioni. Salva esplicitamente il progetto e controlla lo stato del lavoro di esportazione prima di considerare un output come completo. Se una richiesta scade, verifica il suo stato prima di ripetere una modifica.
Le sezioni seguenti spiegano questi flussi di lavoro e le loro convenzioni temporali.
Sessioni e output
Avviare o trovare una sessione
Avvia una sessione headless (senza finestra dell’editor):
openshot-cli session start
Per aprire un progetto esistente all’avvio, aggiungi --project "/path/project.osp". La risposta JSON di successo contiene result.session_id. Copia quel valore. Se OpenShot è già in esecuzione, o hai dimenticato l’ID, trova le sessioni disponibili con:
openshot-cli session list
Scegli la sessione per il progetto che intendi modificare. Non è necessario avviare una nuova sessione per ogni comando.
Selezionare una sessione
Suggerimento
Imposta OPENSHOT_SESSION una volta, poi esegui i comandi normalmente. Il tuo terminale ricorda la sessione selezionata, quindi non devi passare --session con ogni comando. Usa l’esempio PowerShell o Bash qui sotto.
Sostituisci SESSION_ID qui sotto con il session_id restituito da session start o 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
Su macOS, usa la stessa sintassi export. Per i comandi macOS o Snap, sostituisci l’eseguibile della tua installazione come indicato in Getting started. La selezione dura per questo terminale e i comandi lanciati da esso. Impostalo di nuovo in un nuovo terminale, o aggiornalo quando cambi sessione.
Gli esempi rimanenti di modifica ed esportazione presumono che OPENSHOT_SESSION sia impostato. La sottosezione successiva mostra come catturare automaticamente l’ID per gli script.
Per indirizzare una sessione diversa per un solo comando, usa --session. Sovrascrive OPENSHOT_SESSION senza cambiare la selezione del terminale:
openshot-cli --session OTHER_SESSION_ID project get
Con un eseguibile pacchettizzato, metti questa sovrascrittura dopo --cli e prima del gruppo di comandi: --cli --session OTHER_SESSION_ID project get.
La selezione automatica funziona solo quando esiste esattamente una sessione raggiungibile. Se vedi session_required, esegui session list e seleziona esplicitamente la sessione desiderata. Se non è più elencata, avviala di nuovo e usa il nuovo ID. Help, intro e la scoperta delle sessioni non richiedono una sessione selezionata.
Catturare automaticamente l’ID della sessione
Gli script possono leggere result.session_id direttamente dal JSON restituito da session start e impostare OPENSHOT_SESSION per i comandi successivi. Non è necessario copiare manualmente l’ID o leggere un file di log. Verifica che l’avvio sia riuscito prima di usare l’ID restituito.
Windows PowerShell (imposta il percorso dell’eseguibile per la tua installazione):
$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 (richiede jq per leggere 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
La variabile d’ambiente seleziona una sessione per i comandi lanciati da questo terminale; non cambia un’impostazione a livello di sistema. Avviare una sessione non imposta automaticamente la variabile. Dopo aver fermato la sessione, cancella la selezione con Remove-Item Env:OPENSHOT_SESSION in PowerShell o unset OPENSHOT_SESSION in Bash.
Mostrare e fermare una sessione
Per mostrare la sessione selezionata nell’editor:
openshot-cli session show
Su desktop, session show crea l’editor nello stesso processo e mantiene il progetto attivo, gli ID, la cronologia, i lavori di esportazione e la connessione. Chiamate ripetute portano in primo piano la finestra esistente. session start --show la apre immediatamente. Le sessioni avviate senza display, o con QT_QPA_PLATFORM=offscreen/minimal, non possono poi mostrare una finestra desktop. Per queste sessioni, salva e apri il progetto in una nuova sessione desktop. Una volta mostrata, chiudi la sessione tramite la finestra dell’editor.
Le opzioni globali (--session, --timeout) vanno prima del comando. session serve rimane in primo piano per i supervisori; session start ritorna dopo che un host in background si registra. session stop rifiuta modifiche non salvate ed esportazioni attive. Usa --discard solo per scartare intenzionalmente modifiche non salvate.
Output del comando
I risultati sono JSON su stdout, tranne la vista timeline testuale predefinita. Gli errori sono JSON su stderr con stato di uscita 1; gli errori del parser degli argomenti escono con 2. Le mutazioni restituiscono riepiloghi compatti con un comando inspect. get restituisce JSON di oggetti nativi. Le risposte del progetto includono una revisione; le risposte del catalogo effetti non richiedono una sessione. I log delle sessioni headless si trovano accanto ai loro record di registro. OPENSHOT_SESSION_DIR sovrascrive la directory predefinita ~/.openshot_qt/sessions.
Le sessioni accettano comandi localmente sul tuo computer. Mantieni privato il registro delle sessioni, poiché contiene le credenziali utilizzate per accedere alle tue sessioni di editing. Le esportazioni funzionano da uno snapshot, così puoi continuare a modificare mentre un lavoro è in esecuzione.
Apertura e salvataggio dei progetti
Un progetto OpenShot (.osp) memorizza la tua timeline modificabile. L’esportazione crea un video finito; salvare il progetto ti permette di tornare in seguito ai suoi clip, effetti e fotogrammi chiave. Salva il tuo progetto separatamente anche quando esporti un video.
Apertura di un progetto
Avvia una sessione con un progetto esistente:
openshot-cli session start --project "/home/me/Videos/My Project.osp"
Aggiungi --show per aprire anche la sua finestra dell’editor. Per usare un editor già in esecuzione, trovalo con session list. Imposta OPENSHOT_SESSION sull’ID sessione restituito, quindi apri o ispeziona un progetto:
openshot-cli project open "/home/me/Videos/My Project.osp"
openshot-cli project get
Sostituisci il percorso di esempio con il tuo e racchiudi tra virgolette i percorsi contenenti spazi. project open sostituisce il progetto corrente della sessione selezionata. Rifiuta di scartare modifiche non salvate a meno che non aggiungi esplicitamente --discard; salva prima quelle modifiche se vuoi conservarle. L’apertura tramite CLI non mostra finestre interattive per media mancanti, quindi tieni disponibili i media sorgente del progetto.
Per un progetto nuovo e vuoto, usa session start senza --project, quindi importa media e aggiungi clip come descritto nella sezione Editing.
Salvataggio di un progetto o di una copia
Salva in un nuovo file o crea una versione separata prima di apportare ulteriori modifiche:
openshot-cli project save "/home/me/Videos/My Project v2.osp"
Per aggiornare un file esistente, consenti esplicitamente la sostituzione:
openshot-cli project save "/home/me/Videos/My Project v2.osp" --overwrite
Fornisci sempre il percorso di destinazione. Salvare un file .osp non include tutto il materiale sorgente in quel file; tieni disponibili i media referenziati quando sposti o riapri il progetto.
Esportazione di un video
Automatizza il rendering e l’esportazione da script o agenti AI, usando le impostazioni del progetto o scegliendo un profilo di output diverso per ogni rendering. I lavori di esportazione possono essere eseguiti in background o attendere il completamento prima che il tuo script continui. Per eseguire il rendering di un MP4 usando la risoluzione e il frame rate del progetto:
openshot-cli export start "/home/me/Videos/video.mp4" --wait
Per impostazione predefinita, OpenShot usa video H.264 e audio AAC. Sostituisci il percorso di esempio con la tua destinazione, usando una cartella esistente e un nuovo nome file. I file di output esistenti non vengono mai sovrascritti. L’esportazione non salva il tuo progetto .osp modificabile; usa project save separatamente per conservare il lavoro di editing.
L’opzione --wait mantiene il comando in esecuzione fino al completamento dell’esportazione o al segnalare un errore. Controlla il video finito prima di condividerlo.
Controllo del progresso dell’esportazione
Non usare --wait per avviare un’esportazione in background. La risposta include un ID lavoro che puoi usare per controllarne il 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
Sostituisci JOB_ID con l’ID restituito. Se il tempo di attesa scade, l’esportazione continua; controlla lo stesso lavoro invece di avviarne un altro. Per fermare un lavoro, usa export cancel JOB_ID. Ogni lavoro cattura la timeline all’avvio, quindi modifiche successive non cambiano un’esportazione già in corso.
L’attesa predefinita è di 600 secondi; modificala con --wait-timeout. Questo è separato dal --timeout globale per richiesta. Fallimenti di esportazione, cancellazioni e timeout di attesa terminano con stato 1 e includono dettagli del lavoro.
Esportazione in più profili
Esporta la stessa timeline a risoluzioni o rapporti d’aspetto diversi scegliendo un profilo di esportazione per ogni output. Un profilo di esportazione si applica solo a quel lavoro; non cambia il profilo del progetto di editing. Un profilo imposta dimensioni, frame rate e rapporto d’aspetto; un preset di esportazione seleziona le impostazioni di codifica come MP4/H.264.
Trova i profili disponibili e controlla le loro impostazioni:
openshot-cli profile list --search 720
openshot-cli profile list --search 1080
openshot-cli profile get builtin:01280x0720p0030_16-09
Ad esempio, esporta versioni in orizzontale a 720p e 1080p, poi una versione quadrata a 1080 per 1080. Questi profili usano tutti 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
Usa un nome file di output diverso per ogni versione. Mantieni le modifiche invariate tra i lavori quando vuoi versioni corrispondenti. Cambiare il rapporto d’aspetto può modificare l’inquadratura: controlla ogni output, specialmente titoli e soggetti animati. Per una versione quadrata o verticale composta separatamente, salva una copia del progetto, cambia il suo profilo progetto e regola i clip prima di esportare. Consulta Profili e impostazioni di esportazione qui sotto per profili personalizzati e opzioni di codifica.
Esportazione batch di più progetti
Riutilizza una sessione headless per renderizzare diversi progetti salvati in sequenza. Apri un progetto, esportalo con --wait, poi apri il progetto successivo. Gli esempi seguenti usano la risoluzione e il frame rate di ogni progetto e creano file MP4 accanto ai file .osp. Aggiungi --profile PROFILE_ID al comando di esportazione per usare un profilo di output unico per ogni progetto.
Esegui prima con successo l’esempio corrispondente di session-ID automatico sopra, nello stesso terminale. Definisce openshot e seleziona la nuova sessione. Sostituisci i percorsi del progetto sottostanti con i tuoi. Usa nomi di output distinti che non esistono già; gli esempi controllano tutte le destinazioni prima di avviare il batch.
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 (le parentesi mantengono la gestione degli errori locale al batch):
(
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
Entrambe le procedure interrompono il batch in caso di errore di comando e lasciano la sessione disponibile per l’ispezione. Il limite di attesa qui è di 24 ore per esportazione. Un timeout di attesa lascia il rendering in esecuzione: usa export list e export status JOB_ID --wait prima di riprovare. I video completati rimangono sul disco; rimuovi i progetti completati dal batch prima di riprendere. Dopo aver risolto un errore, interrompi la sessione e cancella la sua variabile d’ambiente quando hai finito.
Scelta dei preset e delle impostazioni di codifica
Scopri i preset di esportazione installati e le impostazioni supportate:
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
Export accetta anche --from-file FILE_ID con l’opzione --create-custom. Le impostazioni si risolvono in questo ordine: predefiniti del progetto, preset, JSON avanzato, flag espliciti di profilo/qualità/intervallo. Il JSON avanzato espone codec video/audio e bitrate, layout/rate/canali audio, opzioni codec native, impostazioni dispositivo hardware e conteggio dei thread.
Ad esempio, seleziona un’opzione di codificatore tramite JSON avanzato:
openshot-cli export start /tmp/small.mp4 --profile builtin:00640x0360p0030_16-09 --json '{"video_options":{"preset":"fast"}}' --wait
Validazione delle impostazioni di esportazione
Controlla le impostazioni prima di avviare un rendering:
openshot-cli export validate /tmp/reel.mp4 --preset builtin:format_mp4_x264
Il report delle capacità indica la disponibilità dei codec compilati, non la disponibilità fisica della GPU. La validazione va oltre: apre i codificatori (inclusi quelli hardware) e il contenitore con le impostazioni esatte, in un processo separato, senza scrivere un file. Una combinazione che il contenitore non può contenere fallisce con incompatible_export, la spiegazione di FFmpeg e l’impostazione da modificare (details.cause.path):
openshot-cli export validate /tmp/song.mp3 --json '{"mode":"audio","format":"mp3","audio_codec":"aac"}'
Il processo di esportazione esegue lo stesso controllo prima del rendering.
Rendering di un intervallo di fotogrammi
Usa --start-frame e --end-frame per renderizzare una parte della timeline. Gli intervalli sono inclusivi e basati su 1 al FPS del profilo di esportazione. Ad esempio, renderizza i primi 90 fotogrammi a 30 fps (tre secondi):
openshot-cli export start /tmp/excerpt.mp4 --profile builtin:01280x0720p0030_16-09 --start-frame 1 --end-frame 90 --wait
Esportazioni solo audio e sequenze di immagini
Scegli una modalità di output con JSON avanzato:
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
Le sequenze di immagini richiedono una nuova directory di output. Gli output esistenti non vengono mai sovrascritti.
Modifica
Aggiunta di clip ed effetti
Usa gli ID restituiti da import/add/list e scopri i numeri dei livelli con 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
Scegli il profilo del progetto il prima possibile; i progetti popolati supportano anche modifiche del profilo tramite la conversione FPS esistente e il sistema di annullamento. --audio-only alla creazione della clip sopprime il video, inclusa la copertina incorporata nei file musicali. Per usare quella clip per la Visualizzazione Audio, abilita video e audio e segui l’aiuto dell’effetto per sovrapposizioni trasparenti e posizionamento dei livelli.
Comprendere la temporizzazione della clip
Gli esempi di keyframe assumono un progetto a 30fps e una clip tagliata a 10s di sorgente. La posizione è in secondi della timeline; inizio/fine sono secondi di sorgente, con fine esclusa. I fotogrammi iniziano da 1. I fotogrammi delle miniature usano il FPS sorgente. I fotogrammi della timeline usano il FPS del progetto. I keyframe della clip usano coordinate sorgente al FPS del progetto, quindi tagliare la clip non sposta il primo keyframe visibile al fotogramma 1.
Modifica delle proprietà
set unisce le proprietà di primo livello. Gli scalari trasformano le proprietà con keyframe in costanti. Una curva annidata fornita sostituisce quella curva; usa keyframe set per modificare un solo punto. Gli argomenti JSON accettano JSON inline, @file.json o - per stdin. Nomi delle proprietà, tipi, enum, keyframe, riferimenti e temporizzazione sono validati prima della modifica del progetto. Gli errori identificano il campo, il valore atteso, il valore ricevuto e una correzione quando possibile. Gli intervalli degli slider GUI sono indicativi dove il motore supporta valori oltre questi.
Aggiunta di dissolvenze
clip fade ID --in 0.5 --out 0.5 calcola automaticamente le coordinate dei keyframe del trim sorgente. Sostituisce la curva alpha; --property volume --value 0.25 crea invece una dissolvenza audio con un guadagno massimo di 0.25. Le durate devono rientrare tra il primo e l’ultimo fotogramma visibile; la dissolvenza in uscita raggiunge zero sull’ultimo fotogramma.
Divisione delle clip
clip split ID --at 6.5 usa secondi della timeline, si aggancia al fotogramma di progetto più vicino e mantiene entrambe le metà. Mantiene le curve a coordinate sorgente e duplica gli effetti con nuovi ID sulla metà destra, seguendo il comportamento di taglio dell’editor. La metà sinistra mantiene il suo ID. La risposta riporta i tempi di divisione richiesti/reali e entrambi i riepiloghi; un risultato batch nominato supporta {"$ref":"cut.right.id"}. Le divisioni rifiutano punti finali e tracce bloccate. Annulla ripristina la clip originale in un’unica transazione.
Aggiunta e stile del testo
text add crea un testo e lo posiziona come clip, usando lo stesso testo dello strumento Testo dell’editor. Le opzioni omesse usano lo stile predefinito dell’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
Le parole, il font, la dimensione, l’allineamento, la larghezza della casella e i colori predefiniti appartengono al testo nei File di Progetto e sono condivisi da ogni clip che lo usa, proprio come nell’editor. text set su un clip li modifica tutti e li elenca in changed_clip_ids; --this-clip-only assegna prima a quel clip una copia propria. clip add FILE_ID posiziona un altro clip di un testo da text list. Le dimensioni sono in pixel alla risoluzione del progetto, e i colori sono #RRGGBB, #AARRGGBB (con alfa), un nome CSS, o transparent. --place posiziona la casella al centro, a un bordo o angolo, o in un terzo inferiore. --line-spacing è un multiplo della distanza normale tra le righe (1 è normale), e --background-corner arrotonda gli angoli dello sfondo e del bordo di tanti pixel.
Un clip di testo è un clip ordinario. Posizione, scala, rotazione, opacità, temporizzazione, dissolvenze, preset di movimento ed effetti usano tutti i normali comandi clip. Dimensione del font, padding, larghezza della casella, e spaziatura tra lettere e righe impostano la dimensione della casella di testo, quindi non possono essere animati con fotogrammi chiave; per animare la dimensione del testo, anima la scala del clip. Ogni clip può animare i propri colori del testo, contorno e larghezze di bordo con gli stessi comandi di fotogrammi chiave di qualsiasi altra proprietà:
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
Le proprietà animate sono text_color, text_background, text_stroke e text_border (colori, con .red, .green, .blue e .alpha da 0 a 255), più text_stroke_width, text_border_width e text_background_corner. L’animazione propria di un clip prevale sullo stile condiviso, e text get elenca quali stili un clip anima. text reset CLIP_ID riporta un clip allo stile predefinito, come Testo → Reimposta Stile; --keyframes-only rimuove solo l’animazione propria del clip. Per stilizzare molti testi contemporaneamente, selezionali con {"text":true}:
openshot-cli edit bulk --select '{"text":true}' --json '[{"method":"text.set","params":{"font_family":"Noto Sans","stroke_width":2}}]'
Applicazione di un batch di modifiche
edit apply --json @edits.json --expect-revision 12 accetta fino a 256 comandi di mutazione ordinati, usando nomi di comando puntati come clip.set e effects.add (funziona anche la vecchia grafia effect.add):
[
{"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}}
]
L’opzionale as associa un risultato per comandi successivi nello stesso batch. Un oggetto {"$ref":"shot.id"} sostituisce il campo di quel risultato. I riferimenti risolvono solo nomi precedenti; errori di battitura, riferimenti in avanti e nomi duplicati falliscono prima degli aggiornamenti live. La risposta include risultati compatti ordinati e una mappa refs degli ID reali. Tutte le modifiche in un batch riuscito formano un singolo passo di annulla/ripristina. project.profile.set supporta anche timeline popolate. I comandi di apertura, salvataggio, esportazione e ispezione restano fuori dai batch di modifica. L’aiuto di ogni comando elenca i nomi dei parametri JSON, inclusa la grafia con underscore delle flag shell (per esempio, --fps-num diventa fps_num).
Validazione dei batch e gestione degli errori
Tutti i comandi nei batch di modifica vengono precontrollati su un progetto staccato prima di qualsiasi aggiornamento live. Input non valido lascia il progetto live e la revisione invariati. I batch validi formano un unico gruppo di annullamento. Fallimenti imprevisti in fase di esecuzione possono comunque produrre modifiche parziali; gli errori riportano le operazioni completate. Un timeout non implica cancellazione, quindi ispeziona lo stato prima di ritentare le mutazioni.
Modifica precisa dei fotogrammi chiave
clip, transition ed effects supportano keyframe list, set, remove, clear, transform, copy e paste. I percorsi delle proprietà possono indirizzare curve annidate, come color.red su un effetto Chroma Key. Modificare una curva annidata preserva i canali fratelli. Esegui keyframe list ID senza proprietà per scoprire i percorsi delle curve e il numero di punti. La scoperta e l’elenco dei punti includono il contesto temporale di trim/posizione; l’elenco dei punti riporta anche le coordinate native del fotogramma. get e properties espongono l’oggetto nativo completo e i metadati delle proprietà. Gli errori identificano campi non validi, suggeriscono nomi di proprietà simili e spiegano correzioni di coordinate.
Scegli le coordinate esplicitamente con --space native|clip|timeline e --unit frames|seconds. Tutti i fotogrammi usano FPS del progetto e sono indicizzati da 1; i secondi iniziano da zero e si agganciano al fotogramma più vicino. Native è la coordinata del fotogramma chiave esistente del motore (incluso il trim sorgente). Le coordinate clip iniziano dal punto di ingresso visibile del clip; le coordinate timeline iniziano dal tempo zero del progetto. Gli effetti allegati usano la temporizzazione del clip padre. Queste coordinate si riferiscono al tempo di animazione, non ai fotogrammi media selezionati da una curva di rimappatura temporale.
Per una clip posizionata a 5 secondi, tagliata a 2 secondi, in un progetto a 30 fps, il frame della clip 1, il frame della timeline 151 e il frame nativo 61 indicano lo stesso punto. Posizione e taglio si agganciano indipendentemente alla griglia dei frame del progetto. Elencare un’intera curva può includere punti nascosti con coordinate clip/timeline non positive. Il vecchio --frame indica ancora un frame nativo e non può essere combinato con --at.
Esempi:
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
Interpolazione, easing e anteprima
L’interpolazione descrive il segmento fino al punto di destinazione. Lineare fornisce una velocità costante tra i punti. Costante mantiene il valore precedente fino alla destinazione, poi salta. Le maniglie Bezier predefinite native gestiscono l’easing a entrambe le estremità di ogni segmento. Aggiungere un punto intermedio può quindi introdurre un rallentamento indesiderato; per un movimento eased, inizia con due punti finali. Normalmente lascia le maniglie inalterate e scegli un preset nominato per uno stile specifico.
Scopri gli stessi preset di easing usati dai menu dell’editor, senza una sessione:
openshot-cli clip keyframe presets
Applica un preset al segmento in arrivo impostandone la destinazione:
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
L’opzione easing implica Bezier. Imposta insieme la maniglia uscente del punto precedente e la maniglia entrante della destinazione, preservando le altre maniglie e i valori dei punti. Deve esistere un punto precedente. Non combinarla con maniglie personalizzate o un’interpolazione diversa. I preset funzionano in batch e modelli di massa. Il preset GUI ease («Ease (Default)») differisce dalle maniglie native usate dall’interpolazione Bezier semplice. I preset Back possono superare i valori finali.
Ispeziona il movimento prima del rendering, usando il valutatore di 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
L’anteprima è di sola lettura e funziona allo stesso modo per effetti e transizioni. Restituisce valori e tassi entranti/usciti firmati in unità di proprietà per secondo, calcolati dai frame immediatamente adiacenti. Queste sono differenze finite, non derivate analitiche. Al frame nativo 1 il tasso entrante è nullo. I tassi dei frame adiacenti possono ispezionare oltre l’intervallo richiesto. Tassi quasi nulli attorno a un punto interno indicano una pausa; tassi differenti indicano un cambiamento di velocità. L’interpolazione costante mostra un salto alla destinazione.
Senza un intervallo, l’anteprima copre i primi e gli ultimi punti della curva. Gli intervalli sono inclusivi, con 17 campioni equamente distribuiti per default (–count: 2–256). Sono inclusi anche i keyframe e i loro vicini immediati all’interno dell’intervallo, quindi un numero ridotto di campioni non nasconderà un blocco di keyframe. Il massimo è 1024 campioni; richieste maggiori richiedono un intervallo più stretto. –at campiona un frame. L’anteprima riporta coordinate nello spazio richiesto e frame nativi effettivi; i secondi si agganciano ai frame del progetto come nell’editing.
Per maniglie personalizzate avanzate, sia X che Y sono normalizzate al segmento: X è una frazione della sua estensione in frame; Y è una frazione della variazione di valore. Il primo controllo proviene dalla maniglia destra del punto precedente, il secondo dalla maniglia sinistra della destinazione. I valori predefiniti nativi sono right=(0.5, 0), left=(0.5, 1), con tangenti agli estremi piatte. Cambiare solo handle_type non ricalcola una tangente continua attraverso i punti circostanti. Le maniglie esistenti sono preservate quando si sposta un punto.
Gli intervalli di keyframe sono inclusivi, a differenza degli intervalli temporali di selezione clip. List emette points i cui valori co.X usano lo spazio/unità di coordinate richiesto. Passa quell’array a keyframe paste --json @points.json con lo stesso spazio/unità, scegliendo --mode merge (sostituisce i frame corrispondenti, mantiene gli altri) o --mode replace (sostituisce l’intera curva). copy accetta una sorgente dello stesso tipo di oggetto, un opzionale --source-property, e ancora il primo punto sorgente selezionato a --at sul target. Altre curve e oggetti sorgente rimangono invariati.
transform applica una scala temporale positiva attorno al primo punto selezionato, o --pivot, seguito da un --offset firmato nell’unità scelta. L’aggancio ai frame che crea coordinate duplicate è rifiutato, incluse collisioni con punti fuori dall’intervallo selezionato. Le coordinate native devono rimanere almeno 1. Le maniglie Bézier normalizzate native e l’interpolazione si muovono con ogni punto; le maniglie non sono coordinate frame assolute. set --handles modifica solo le maniglie fornite. L’interpolazione appartiene al punto di destinazione.
clear mantiene un punto base costante al frame nativo 1: specifica --value o campiona la curva esistente con --at (default frame nativo 1). Rimuovere l’ultimo punto mantiene anch’esso una base costante, quindi le aggiunte successive di keyframe rimangono valide.
Selezionare e modificare molte clip
Usa edit apply --dry-run per convalidare un batch senza modificare il progetto. Usa edit bulk per ripetere un piccolo modello di comando per ogni clip selezionata, con tutte le modifiche raggruppate in un unico passo di annullamento.
Prima visualizza in anteprima una selezione:
openshot-cli edit select --json '{"layer":1000000,"start":5,"end":20,"effect":"Saturation"}'
I selettori supportano ids (array di ID clip unici), layer, start/end (secondi sulla timeline), file_id, effect (nome della classe o alias) e text (true seleziona clip di testo). I filtri si combinano con AND. Gli intervalli temporali selezionano clip che si sovrappongono a [start, end); non tagliano quei clip. I risultati sono ordinati per posizione, layer, poi ID, e includono ID, sommari, stato di blocco e la revisione corrente. ID sconosciuti sono errori. Un selettore vuoto è rifiutato; usa esplicitamente {"all":true} per ogni clip. Le selezioni sono limitate a 256 clip e non vengono mai troncate silenziosamente.
Per esempio, salva questo array come 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}}
]
Validalo, quindi applicalo contro la revisione restituita dalla selezione:
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
I comandi per clip esistenti ereditano id; effects.add eredita clip_id. Ommetti questi parametri target nei template. Le modifiche agli effetti devono fare riferimento a un risultato nominato precedente. I nomi sono locali a ogni clip selezionato, quindi look.id si riferisce a un effetto diverso per ogni clip. Per modificare istanze di effetti esistenti tramite ID esplicito, continua a usare edit apply. Il set di ID selezionati è fisso prima dell’espansione; modifiche a posizione o effetti non cambiano gli obiettivi rimanenti.
clip set applica proprietà assolute; clip adjust applica multiply poi add a una proprietà numerica o a ogni valore in una curva, preservando il timing dei punti, l’interpolazione e le maniglie normalizzate. Valida i valori risultanti, incluse posizioni non negative e volume. I campi strutturali rimangono protetti.
Le operazioni in blocco rifiutano selezioni vuote, tracce target bloccate e più di 256 comandi espansi. Ogni operazione espansa supera un preflight separato prima di qualsiasi modifica live. Le esecuzioni di prova non riservano ID generati. Usa --expect-revision per rifiutare selezioni obsolete. I batch riusciti costituiscono un singolo passo di annullamento, anche dopo salvataggio/riapertura. Gli aggiornamenti GUI sono raggruppati. Errori imprevisti di runtime/listener possono comunque lasciare una transazione parziale; l’errore riporta le operazioni completate e l’annullamento ripristina quel gruppo, come con edit apply.
Profili
Scopri profili e abbina video importati senza indovinare gli ID:
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}}'
Le voci del catalogo includono ID stabili, descrizioni, dimensioni, FPS razionali, rapporti d’aspetto e impostazioni di scansione. La lista/ricerca è paginata. L’abbinamento della sorgente restituisce ID esatti e alternative classificate con differenze esplicite. L’impostazione da file richiede una corrispondenza esatta a meno che non sia specificato --create-custom; non sceglie mai silenziosamente un profilo vicino. Immagini statiche e sorgenti solo audio non possono definire un profilo video. L’abbinamento usa l’FPS dichiarato della sorgente.
Le impostazioni personalizzate sono incorporate nel progetto salvato, inclusi i tassi razionali, quindi la riapertura non richiede l’installazione di un file profilo separato. Le modifiche al profilo del progetto utilizzano la conversione del frame rate esistente e una singola transazione di annullamento. Annulla/ripeti ripristina il timing del clip e i keyframe, incluse le posizioni sensibili all’arrotondamento. L’esportazione può selezionare indipendentemente un profilo senza modificare il progetto.
La cronologia di annullamento salvata segue la preferenza history-limit dell’editor. Il limite è un budget di azioni soft: tutti i record appartenenti a transazioni mantenute sono conservati, quindi il salvataggio non può troncare un grande batch in un’azione di annullamento parziale. Zero disabilita la cronologia salvata. Vale ancora il limite separato di 256 comandi per batch.
Ispezione di media e timeline
Ispeziona il timing dei clip e la disposizione delle tracce come testo o JSON, oppure genera immagini per rivedere composizione e inquadratura prima dell’esportazione.
Sommari della timeline
Usa una vista testuale per una panoramica rapida, o JSON strutturato per script e agenti:
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 predefinito è testo compatto con tracce usate, ID oggetti, intervalli timeline/sorgente, stato stream, guadagno e gap/sovrapposizioni. Usa --detail summary|clips|full per scegliere il dettaglio, --format json per contesto strutturato, e --start/--end, --layer e paginazione per focalizzare il risultato.
timeline overview fornisce un contesto strutturato compatto senza byte immagine: ID ordinati, sequenza per traccia, intervalli timeline/sorgente, intervalli di ritaglio visibili, coordinate frame, stato audio/video, effetti e gap o sovrapposizioni vicine. Intervalli e span di frame sono esclusivi alla fine; i numeri dei frame sono basati su uno. I frame sorgente usano FPS sorgente; timeline e coordinate keyframe usano FPS progetto. Usa --layer e --start/--end per focalizzare, e --limit/--offset per paginare (default 100, massimo 500 elementi). I clip con rimappatura temporale trattengono esplicitamente le mappature sorgente inferite. Usa la revisione restituita con edit apply --expect-revision.
Anteprime frame e contact sheet
Genera un singolo frame con thumbnail o campiona un intervallo con strip. Usa file per ispezionare i media sorgente e timeline per ispezionare il video composto, inclusi effetti e clip stratificati:
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
Le immagini dei frame hanno dimensione predefinita 320x180 pixel; i contact sheet predefiniti sono 160x90 per riquadro, più etichette timecode. Usa --width e --height per scegliere i pixel di output. Le risposte includono metadati esatti di campione/frame. I contact sheet aiutano a rivedere la composizione lungo una sequenza; usa anteprime keyframe e video renderizzato per valutare il movimento tra quei campioni.
Immagini della timeline
Cattura la disposizione delle tracce dell’editor, inclusi righello, miniature, effetti, transizioni e forme d’onda:
openshot-cli timeline view --start 0 --end 20 --pixels-per-second 80 --output /tmp/tracks.png
Specificare --output seleziona il formato immagine; --format image lo seleziona esplicitamente. La cattura non modifica la vista o il progetto dell’editor. Le risposte includono ID clip e tempi insieme ai limiti in pixel.
Le immagini hanno larghezza predefinita di 1280 pixel, con altezza adattata alle tracce usate. Usa --width, --height o --all-tracks per regolare il layout, e --track-size o --track-label-width per regolare tracce ed etichette. L’intervallo di inizio/fine determina lo zoom; --pixels-per-second invece ricava la larghezza dall’intervallo temporale.
Visualizzazioni delle forme d’onda audio
Scegli --mode waveforms per ispezionare gli inviluppi audio sulla timeline:
openshot-cli timeline view --start 5 --end 12 --mode waveforms --output /tmp/waves.png
--mode auto usa la visualizzazione delle forme d’onda memorizzata nella cache; --mode thumbnails mostra invece le miniature. Le forme d’onda rappresentano i livelli di picco/RMS della sorgente con regolazioni di volume e tempo del clip, prima degli effetti audio o del mixaggio.
L’estrazione delle forme d’onda non memorizzate in cache decodifica intere sorgenti, limitata a 600 secondi per sorgente e 1200 secondi-sorgente per richiesta. Restringere l’intervallo visibile non riduce questo lavoro di decodifica. Per sorgenti più lunghe, genera prima le forme d’onda nell’editor o usa la modalità miniature. Le richieste successive possono riutilizzare le forme d’onda memorizzate in cache.
Output e limiti delle immagini
I percorsi delle immagini devono essere nuovi file PNG in directory esistenti. Le immagini sono limitate a 4096 pixel per asse, 8.388.608 pixel totali e 64 campioni per contact-sheet. Le richieste oltre questi limiti falliscono prima del rendering.
Le immagini vengono scritte su file; le risposte JSON includono i loro percorsi e le dimensioni in image_bytes. L’ispezione attende il completamento dell’immagine, e richieste grandi possono occupare brevemente l’editor.
Gestione dei timeout dei comandi
Un timeout di richiesta non significa che una mutazione sia fallita. Usa l’ID dell’operazione nell’errore con operation get ID prima di riprovare. operation list scopre le mutazioni recenti e i loro stati, revisioni e risultati. Le operazioni completate mantengono i loro risultati se abbastanza piccoli, inclusi gli ID degli oggetti restituiti. Lo spazio di archiviazione è limitato a 100 operazioni e 4 MiB, con corpi di risultato individuali omessi sopra 256 KiB. Questi record durano solo per la sessione in corso. Non ripristinano i progetti dopo un crash né impediscono che un comando ripetuto applichi di nuovo la stessa modifica. I lavori di esportazione hanno comandi propri di stato/lista.