Interfaz de Línea de Comandos
Integra OpenShot en tu flujo de trabajo de línea de comandos. Importa material, recorta y organiza clips, aplica efectos, anima propiedades con fotogramas clave y exporta videos desde tu terminal. Usa unos pocos comandos para automatizar ediciones repetitivas, escribir un script para un proyecto recurrente o dejar que un agente de IA ayude a ensamblar y refinar un video.
La línea de comandos funciona con los mismos proyectos que el editor. Puedes controlar un editor abierto y revisar los cambios a medida que avanzas, o trabajar en una sesión sin interfaz gráfica sin abrir una ventana. Una sesión mantiene tu proyecto abierto entre comandos, incluyendo sus ediciones, historial de deshacer y trabajos de exportación. Guárdalo como un proyecto .osp cuando quieras continuar editando más tarde.
Primeros pasos
Usa tu ejecutable de OpenShot instalado seguido de --cli. Comienza con intro para una guía breve sobre sesiones, edición, animación y guardado, o help para la visión general de comandos. Estos comandos no requieren una sesión activa. Los ejemplos a continuación requieren una versión de OpenShot que incluya edición por línea de comandos.
Linux AppImage
Desde el directorio que contiene tu AppImage descargado:
./OpenShot.AppImage --cli intro
./OpenShot.AppImage --cli help
Reemplaza OpenShot.AppImage con el nombre de archivo que descargaste. Si AppImageLauncher muestra diálogos de integración de escritorio, configura APPIMAGELAUNCHER_DISABLE=1 antes de ejecutar el comando:
APPIMAGELAUNCHER_DISABLE=1 ./OpenShot.AppImage --cli intro
Para scripts o comandos repetidos, configúralo una vez en tu shell actual:
export APPIMAGELAUNCHER_DISABLE=1
./OpenShot.AppImage --cli session start
La variable debe establecerse antes de lanzar el AppImage: AppImageLauncher puede interceptarla antes de que OpenShot reciba --cli. Las rutas relativas de medios y los archivos @batch.json se resuelven desde tu directorio de trabajo. Mantén el archivo AppImage disponible mientras sus sesiones o exportaciones estén en ejecución.
Linux Snap
Para el OpenShot Snap, usa:
snap run openshot-qt --cli intro
snap run openshot-qt --cli help
snap run openshot-qt --cli session start
Los permisos de archivos de Snap también se aplican a la edición por línea de comandos. Mantén los medios, proyectos y exportaciones en ubicaciones a las que Snap pueda acceder, como tu carpeta personal. Para permitir acceso a unidades externas, conecta el permiso removable-media:
sudo snap connect openshot-qt:removable-media
Windows
Importante
Usa openshot-qt-cmd.exe para la edición por línea de comandos en Windows. Este ejecutable de consola muestra resultados de comandos, ayuda y errores en tu terminal. El ejecutable de escritorio, openshot-qt.exe, no muestra salida estándar en un terminal interactivo, dejando los comandos sin retroalimentación visible y dificultando el uso de la CLI.
En PowerShell, desde el directorio de instalación de OpenShot:
& .\openshot-qt-cmd.exe --cli intro
& .\openshot-qt-cmd.exe --cli help
& .\openshot-qt-cmd.exe --cli session start
Si estás en un directorio diferente, usa la ruta completa a openshot-qt-cmd.exe. Mantén --cli después del nombre del ejecutable.
macOS
Para una instalación en Aplicaciones:
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli intro
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli help
Encontrar comandos
A lo largo de esta guía, openshot-cli es una abreviatura para el comando de tu instalación mencionado arriba, como snap run openshot-qt --cli o ./OpenShot.AppImage --cli. Algunas instalaciones también proporcionan un comando openshot-cli directamente. Al ejecutar desde el código fuente, usa python3 src/launch.py --cli en el entorno Python de OpenShot.
Los comandos --cli, --cli help y --cli --help muestran la misma visión general. La ayuda se vuelve más específica a medida que navegas por los 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
La ayuda de grupo explica flujos de trabajo con ejemplos; la ayuda de operación describe argumentos y comportamiento. --help es equivalente a usar help al final. Todos los comandos de ayuda funcionan sin una sesión de edición.
effects list muestra los efectos disponibles con descripciones breves. La ayuda de efectos explica sus propiedades, valores predeterminados, opciones y rangos. effects instances lista los efectos ya adjuntos a clips, con los IDs de clips padres. Los nombres de clase, nombres para mostrar y alias con guiones bajos identifican el mismo efecto.
Trabajando con scripts y agentes de IA
Agentes de codificación de IA como Codex y Claude Code pueden usar la CLI para inspeccionar y editar proyectos de OpenShot mediante comandos de terminal. Proporciónale a tu agente la ruta al ejecutable de OpenShot, los medios o proyecto con los que trabajar, y el resultado deseado: duración, dimensiones, estilo de animación y ubicación de salida. Pídele que lea --cli intro antes de comenzar. Los mismos comandos funcionan cuando los escribes tú mismo o los ejecutas desde un script.
Comienza con intro, luego usa la ayuda específica de comandos según sea necesario. Un flujo de trabajo útil es seleccionar una sesión, inspeccionar el proyecto, hacer un pequeño conjunto de cambios, revisar el resultado y guardar. Los comandos devuelven JSON estructurado para que scripts y agentes puedan usar directamente los IDs de objetos y resultados en lugar de interpretar la salida en pantalla.
Inspecciona antes de editar. Usa los IDs y la información de propiedades devueltos en lugar de adivinar nombres, números de pista o tiempos. Selecciona una sesión explícitamente cuando haya más de un proyecto abierto.
Agrupa ediciones repetidas. Usa
edit applypara una secuencia de cambios oedit bulkpara aplicar una plantilla a clips seleccionados. Valida con--dry-runantes de aplicar un lote.Verificar animación. Elija un espacio de coordenadas, comience con algunos fotogramas clave y use preajustes de suavizado para un movimiento familiar.
keyframe previewmuestrea la curva para que pueda detectar pausas o saltos antes de exportar. También revise el movimiento renderizado; una hoja de contacto por sí sola no puede mostrar cómo se siente una animación.Guardar y seguir exportaciones. Guarde el proyecto explícitamente y verifique el estado del trabajo de exportación antes de considerar una salida como completa. Si una solicitud expira, inspeccione su estado antes de repetir una edición.
Las secciones a continuación explican estos flujos de trabajo y sus convenciones de tiempo.
Sesiones y salidas
Iniciar o encontrar una sesión
Inicie una sesión sin interfaz gráfica (sin ventana del editor):
openshot-cli session start
Para abrir un proyecto existente al iniciar, agregue --project "/ruta/proyecto.osp". La respuesta JSON exitosa contiene result.session_id. Copie ese valor. Si OpenShot ya está en ejecución o ha olvidado el ID, encuentre las sesiones disponibles con:
openshot-cli session list
Elija la sesión para el proyecto que desea editar. No es necesario iniciar una nueva sesión para cada comando.
Seleccionar una sesión
Truco
Configure OPENSHOT_SESSION una vez, luego ejecute los comandos normalmente. Su terminal recuerda la sesión seleccionada, por lo que no necesita pasar --session con cada comando. Use el ejemplo de PowerShell o Bash a continuación.
Reemplace SESSION_ID abajo con el session_id devuelto por 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
En macOS, use la misma sintaxis export. Para comandos en macOS o Snap, sustituya el ejecutable de su instalación según la sección Comenzando. La selección dura para este terminal y los comandos lanzados desde él. Establézcalo nuevamente en un terminal nuevo o actualícelo al cambiar a una sesión diferente.
Los ejemplos restantes de edición y exportación asumen que OPENSHOT_SESSION está configurado. La siguiente subsección muestra cómo capturar el ID automáticamente para scripts.
Para dirigir un comando a una sesión diferente solo para ese comando, use --session. Esto anula OPENSHOT_SESSION sin cambiar la selección de su terminal:
openshot-cli --session OTHER_SESSION_ID project get
Con un ejecutable empaquetado, coloque esta anulación después de --cli y antes del grupo de comandos: --cli --session OTHER_SESSION_ID project get.
La selección automática solo funciona cuando existe exactamente una sesión accesible. Si ve session_required, ejecute session list y seleccione explícitamente la sesión deseada. Si ya no aparece en la lista, iníciela nuevamente y use el nuevo ID. Ayuda, intro y el descubrimiento de sesiones no requieren una sesión seleccionada.
Capturar el ID de sesión automáticamente
Los scripts pueden leer result.session_id directamente del JSON devuelto por session start y establecer OPENSHOT_SESSION para comandos posteriores. No es necesario copiar el ID manualmente ni leer un archivo de registro. Verifique que el inicio haya sido exitoso antes de usar el ID devuelto.
Windows PowerShell (configure la ruta del ejecutable para su instalación):
$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 (requiere jq para leer 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 variable de entorno selecciona una sesión para los comandos lanzados desde este terminal; no cambia una configuración a nivel del sistema. Iniciar una sesión no establece la variable automáticamente. Después de detener la sesión, borre la selección con Remove-Item Env:OPENSHOT_SESSION en PowerShell o unset OPENSHOT_SESSION en Bash.
Mostrar y detener una sesión
Para mostrar la sesión seleccionada en el editor:
openshot-cli session show
En un escritorio, session show crea el editor en el mismo proceso y mantiene el proyecto activo, IDs, historial, trabajos de exportación y conexión. Llamadas repetidas elevan la ventana existente. session start --show lo abre inmediatamente. Las sesiones iniciadas sin pantalla, o con QT_QPA_PLATFORM=offscreen/minimal, no pueden mostrar luego una ventana de escritorio. Para esas sesiones, guarde y abra el proyecto en una nueva sesión de escritorio. Una vez mostrada, cierre la sesión desde la ventana del editor.
Las opciones globales (--session, --timeout) van antes del comando. session serve permanece en primer plano para supervisores; session start retorna después de que un host en segundo plano se registra. session stop rechaza cambios no guardados y exportaciones activas. Use --discard solo para descartar intencionalmente ediciones no guardadas.
Salida del comando
Los resultados son JSON en stdout, excepto la vista predeterminada de línea de tiempo en texto. Los errores son JSON en stderr con estado de salida 1; errores del analizador de argumentos salen con 2. Las mutaciones devuelven resúmenes compactos con un comando inspect. get devuelve JSON de objeto nativo. Las respuestas del proyecto incluyen una revisión; las respuestas del catálogo de efectos no requieren sesión. Los registros de sesiones sin interfaz gráfica se almacenan junto a sus registros en el registro. OPENSHOT_SESSION_DIR anula el directorio predeterminado ~/.openshot_qt/sessions.
Las sesiones aceptan comandos localmente en su computadora. Mantenga el registro de sesiones privado, ya que contiene las credenciales usadas para acceder a sus sesiones de edición. Las exportaciones funcionan a partir de una instantánea, por lo que puede continuar editando mientras se ejecuta un trabajo.
Abrir y guardar proyectos
Un proyecto de OpenShot (.osp) almacena su línea de tiempo editable. Exportar crea un video terminado; guardar el proyecto le permite volver a sus clips, efectos y fotogramas clave más tarde. Guarde su proyecto por separado incluso cuando también exporte un video.
Abrir un proyecto
Inicie una sesión con un proyecto existente:
openshot-cli session start --project "/home/me/Videos/My Project.osp"
Agregue --show para abrir también su ventana del editor. Para usar un editor que ya está en ejecución, encuéntrelo con session list. Configure OPENSHOT_SESSION con el ID de sesión devuelto, luego abra o inspeccione un proyecto:
openshot-cli project open "/home/me/Videos/My Project.osp"
openshot-cli project get
Reemplace la ruta de ejemplo con la suya y ponga entre comillas las rutas que contengan espacios. project open reemplaza el proyecto actual de la sesión seleccionada. Se niega a descartar ediciones no guardadas a menos que agregue explícitamente --discard; guarde esas ediciones primero si desea conservarlas. Abrir a través de la CLI no muestra diálogos interactivos de medios faltantes, así que mantenga disponible el material fuente del proyecto.
Para un proyecto nuevo y vacío, use session start sin --project, luego importe medios y agregue clips como se describe en Edición.
Guardar un proyecto o una copia
Guarde en un archivo nuevo o cree una versión separada antes de hacer más cambios:
openshot-cli project save "/home/me/Videos/My Project v2.osp"
Para actualizar un archivo existente, permita explícitamente la sustitución:
openshot-cli project save "/home/me/Videos/My Project v2.osp" --overwrite
Siempre proporcione la ruta de destino. Guardar un archivo .osp no empaqueta todo su material fuente en ese archivo; mantenga los medios referenciados disponibles al mover o reabrir el proyecto.
Exportar un video
Automatice el renderizado y la exportación desde scripts o agentes de IA, usando la configuración del proyecto o eligiendo un perfil de salida diferente para cada renderizado. Los trabajos de exportación pueden ejecutarse en segundo plano o esperar a que terminen antes de que su script continúe. Para renderizar un MP4 usando la resolución y la tasa de cuadros del proyecto:
openshot-cli export start "/home/me/Videos/video.mp4" --wait
Por defecto, OpenShot usa video H.264 y audio AAC. Reemplace la ruta de ejemplo con su destino, usando una carpeta existente y un nombre de archivo nuevo. Los archivos de salida existentes nunca se sobrescriben. Exportar no guarda su proyecto editable .osp; use project save por separado para conservar su trabajo de edición.
La opción --wait mantiene el comando en ejecución hasta que la exportación se complete o reporte un fallo. Revise el video terminado antes de compartirlo.
Comprobando el progreso de la exportación
No use --wait para iniciar una exportación en segundo plano. La respuesta incluye un ID de trabajo que puede usar para verificar su progreso:
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
Reemplace JOB_ID con el ID devuelto. Si el tiempo de espera expira, la exportación continúa ejecutándose; verifique el mismo trabajo en lugar de iniciar otra exportación. Para detener un trabajo, use export cancel JOB_ID. Cada trabajo captura la línea de tiempo cuando comienza, por lo que las ediciones posteriores no cambian una exportación ya en curso.
El tiempo de espera predeterminado es de 600 segundos; ajústelo con --wait-timeout. Esto es independiente del --timeout global por solicitud. Fallos en la exportación, cancelaciones y tiempos de espera terminan con estado 1 e incluyen detalles del trabajo.
Exportar en múltiples perfiles
Exporte la misma línea de tiempo en diferentes resoluciones o relaciones de aspecto eligiendo un perfil de exportación para cada salida. Un perfil de exportación se aplica solo a ese trabajo; no cambia el perfil del proyecto de edición. Un perfil establece dimensiones, tasa de cuadros y relación de aspecto; un preajuste de exportación selecciona configuraciones de codificación como MP4/H.264.
Encuentre los perfiles disponibles e inspeccione sus configuraciones:
openshot-cli profile list --search 720
openshot-cli profile list --search 1080
openshot-cli profile get builtin:01280x0720p0030_16-09
Por ejemplo, exporte versiones en formato horizontal a 720p y 1080p, luego una versión cuadrada a 1080 por 1080. Estos perfiles usan 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 un nombre de archivo de salida diferente para cada versión. Mantenga las ediciones sin cambios entre trabajos cuando desee versiones coincidentes. Cambiar la relación de aspecto puede cambiar el encuadre: revise cada salida, especialmente títulos y sujetos animados. Para una versión cuadrada o vertical compuesta por separado, guarde una copia del proyecto, cambie su perfil de proyecto y ajuste los clips antes de exportar. Consulte Perfiles y la configuración de exportación a continuación para perfiles personalizados y opciones de codificación.
Exportación por lotes de múltiples proyectos
Reutilice una sesión sin interfaz para renderizar varios proyectos guardados en secuencia. Abra un proyecto, expórtelo con --wait, luego abra el siguiente proyecto. Los ejemplos a continuación usan la resolución y tasa de cuadros propias de cada proyecto y crean archivos MP4 junto a los archivos .osp. Agregue --profile PROFILE_ID al comando de exportación para usar un perfil de salida para cada proyecto.
Primero ejecuta con éxito el ejemplo automático de session-ID correspondiente arriba, en el mismo terminal. Define openshot y selecciona la nueva sesión. Reemplaza las rutas del proyecto abajo con las tuyas. Usa nombres de salida distintos que no existan ya; los ejemplos verifican todos los destinos antes de iniciar el 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 (los paréntesis mantienen el manejo de errores local al 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 recetas detienen el lote ante un fallo de comando y dejan la sesión disponible para inspección. El límite de espera aquí es de 24 horas por exportación. Un tiempo de espera deja la renderización en ejecución: usa export list y export status JOB_ID --wait antes de reintentar. Los videos completados permanecen en disco; elimina los proyectos completados del lote antes de continuar. Tras resolver un fallo, detén la sesión y limpia su variable de entorno cuando termines.
Elegir preajustes y configuraciones de codificación
Descubre los preajustes de exportación instalados y las configuraciones soportadas:
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 también acepta --from-file FILE_ID con --create-custom opcional. Las configuraciones se resuelven en este orden: valores predeterminados del proyecto, preajuste, JSON avanzado, flags explícitos de perfil/calidad/rango. El JSON avanzado expone códecs de video/audio y bitrate, disposición/tasa/canales de audio, opciones nativas de códec, configuraciones de dispositivos hardware y conteo de hilos.
Por ejemplo, selecciona una opción de codificador mediante JSON avanzado:
openshot-cli export start /tmp/small.mp4 --profile builtin:00640x0360p0030_16-09 --json '{"video_options":{"preset":"fast"}}' --wait
Validando configuraciones de exportación
Verifica las configuraciones antes de iniciar una renderización:
openshot-cli export validate /tmp/reel.mp4 --preset builtin:format_mp4_x264
El informe de capacidades muestra la disponibilidad compilada de códecs, no la disponibilidad física de la GPU. La validación va más allá: abre los codificadores (incluidos los hardware) y el contenedor con las configuraciones exactas, en un proceso separado, sin escribir un archivo. Una combinación que el contenedor no puede soportar falla con incompatible_export, la explicación propia de FFmpeg, y la configuración a cambiar (details.cause.path):
openshot-cli export validate /tmp/song.mp3 --json '{"mode":"audio","format":"mp3","audio_codec":"aac"}'
El trabajador de exportación realiza la misma verificación antes de renderizar.
Renderizando un rango de fotogramas
Usa --start-frame y --end-frame para renderizar parte de la línea de tiempo. Los rangos son inclusivos y comienzan en uno según los FPS del perfil de exportación. Por ejemplo, renderiza los primeros 90 fotogramas a 30 fps (tres segundos):
openshot-cli export start /tmp/excerpt.mp4 --profile builtin:01280x0720p0030_16-09 --start-frame 1 --end-frame 90 --wait
Exportaciones solo de audio y secuencias de imágenes
Elige un modo de salida con JSON avanzado:
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
Las secuencias de imágenes requieren un nuevo directorio de salida. Las salidas existentes nunca se sobrescriben.
Edición
Añadiendo clips y efectos
Usa los IDs devueltos por import/add/list, y descubre los números de capa 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
Elige el perfil del proyecto temprano cuando sea posible; los proyectos poblados también soportan cambios de perfil mediante la conversión de FPS existente y el sistema de deshacer. --audio-only al crear un clip suprime el video, incluyendo la carátula incrustada en archivos de música. Para usar ese clip para Visualización de Audio en su lugar, habilita su video y audio, y sigue la ayuda del efecto para superposiciones transparentes y colocación de capas.
Entendiendo la sincronización del clip
Los fotogramas clave del ejemplo asumen un proyecto a 30fps y un clip recortado en la fuente a 10s. La posición está en segundos de la línea de tiempo; inicio/fin son segundos de la fuente, con fin exclusivo. Los fotogramas comienzan en 1. Los fotogramas de miniatura usan FPS de la fuente. Los fotogramas de la línea de tiempo usan FPS del proyecto. Los fotogramas clave del clip usan coordenadas de la fuente a FPS del proyecto, por lo que recortar el clip no mueve su primer fotograma clave visible al fotograma 1.
Cambiando propiedades
set fusiona propiedades de nivel superior. Los escalares convierten propiedades con fotogramas clave en constantes. Una curva anidada suministrada reemplaza esa curva; usa keyframe set para cambiar solo un punto. Los argumentos JSON aceptan JSON en línea, @file.json, o - para stdin. Los nombres de propiedades, tipos, enumeraciones, fotogramas clave, referencias y sincronización se validan antes de editar el proyecto. Los errores identifican el campo, valor esperado, valor recibido y una corrección cuando es posible. Los rangos de los deslizadores GUI son orientativos cuando el motor soporta valores más allá de ellos.
Añadiendo fundidos
clip fade ID --in 0.5 --out 0.5 calcula automáticamente las coordenadas de fotogramas clave del recorte de fuente. Reemplaza la curva alfa; --property volume --value 0.25 en cambio crea un fundido de audio con ganancia máxima de 0.25. Las duraciones deben caber entre el primer y último fotograma visible; el fundido de salida llega a cero en el último fotograma.
Dividiendo clips
clip split ID --at 6.5 usa segundos de la línea de tiempo, se ajusta al fotograma de proyecto más cercano y mantiene ambas mitades. Conserva curvas de coordenadas fuente y duplica efectos con IDs nuevos en la mitad derecha, siguiendo el comportamiento de corte del editor. La mitad izquierda conserva su ID. La respuesta informa tiempos de corte solicitados/actuales y ambos resúmenes; un resultado de lote nombrado soporta {"$ref":"cut.right.id"}. Los cortes rechazan puntos finales y pistas bloqueadas. Deshacer restaura el clip original en una sola transacción.
Agregar y dar estilo al texto
text add crea un texto y lo coloca como un clip, usando el mismo texto que la herramienta Texto del editor. Las opciones que omitas usarán el estilo predeterminado del 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
Las palabras, fuente, tamaño, alineación, ancho del cuadro y colores predeterminados pertenecen al texto en los Archivos del Proyecto y son compartidos por cada clip que lo usa, igual que en el editor. text set en un clip cambia todos y los lista en changed_clip_ids; --this-clip-only da a ese clip su propia copia primero. clip add FILE_ID coloca otro clip de un texto de text list. Los tamaños están en píxeles a la resolución del proyecto, y los colores son #RRGGBB, #AARRGGBB (con alfa), un nombre CSS o transparent. --place coloca el cuadro en el centro, un borde o esquina, o un tercio inferior. --line-spacing es un múltiplo de la distancia normal entre líneas (1 es normal), y --background-corner redondea las esquinas del fondo y borde por esa cantidad de píxeles.
Un clip de texto es un clip ordinario. Posición, escala, rotación, opacidad, sincronización, fundidos, ajustes preestablecidos de movimiento y efectos usan los comandos normales de clip. El tamaño de fuente, relleno, ancho del cuadro, y el espaciado entre letras y líneas definen el tamaño del cuadro de texto, por lo que no pueden tener fotogramas clave; para animar el tamaño del texto, anima la escala del clip. Cada clip puede animar sus propios colores de texto y los anchos de contorno y borde con los mismos comandos de fotogramas clave que cualquier otra propiedad:
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
Las propiedades animadas son text_color, text_background, text_stroke y text_border (colores, con .red, .green, .blue y .alpha de 0 a 255), además de text_stroke_width, text_border_width y text_background_corner. La animación propia de un clip prevalece sobre el estilo compartido, y text get lista qué estilos anima un clip. text reset CLIP_ID devuelve un clip al estilo predeterminado, como Texto → Restablecer estilo; --keyframes-only solo elimina la animación propia del clip. Para dar estilo a muchos textos a la vez, selecciónalos con {"text":true}:
openshot-cli edit bulk --select '{"text":true}' --json '[{"method":"text.set","params":{"font_family":"Noto Sans","stroke_width":2}}]'
Aplicando un lote de ediciones
edit apply --json @edits.json --expect-revision 12 acepta hasta 256 comandos de mutación ordenados, usando nombres de comando con puntos como clip.set y effects.add (la ortografía antigua effect.add también 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}}
]
El opcional as vincula un resultado para comandos posteriores en el mismo lote. Un objeto {"$ref":"shot.id"} sustituye el campo de ese resultado. Las referencias solo resuelven nombres anteriores; errores ortográficos, referencias adelantadas y nombres duplicados fallan antes de las actualizaciones en vivo. La respuesta incluye resultados compactos ordenados y un mapa refs de IDs reales. Todos los cambios en un lote exitoso forman un solo paso de deshacer/rehacer. project.profile.set también soporta líneas de tiempo pobladas. Los comandos de abrir, guardar, exportar e inspeccionar permanecen fuera de los lotes de edición. La ayuda de cada comando lista los nombres de parámetros JSON, incluyendo la ortografía con guion bajo de las banderas de shell (por ejemplo, --fps-num se convierte en fps_num).
Validando lotes y manejando errores
Todos los comandos en lotes de edición se prueban contra un proyecto separado antes de cualquier actualización en vivo. La entrada inválida deja el proyecto en vivo y la revisión sin cambios. Los lotes válidos forman un solo grupo de deshacer. Fallos inesperados en tiempo de ejecución aún pueden producir cambios parciales; los errores reportan operaciones completadas. Un tiempo de espera no implica cancelación, así que inspecciona el estado antes de reintentar mutaciones.
Edición precisa de fotogramas clave
clip, transition y effects soportan keyframe list, set, remove, clear, transform, copy y paste. Las rutas de propiedades pueden dirigirse a curvas anidadas, como color.red en un efecto Chroma Key. Editar una curva anidada preserva canales hermanos. Ejecuta keyframe list ID sin propiedad para descubrir rutas de curvas y conteos de puntos. El descubrimiento y listado de puntos incluyen contexto de sincronización de recorte/posición; los listados de puntos también reportan coordenadas nativas de fotogramas. get y properties exponen el objeto nativo completo y metadatos de propiedades. Los errores identifican campos inválidos, sugieren nombres de propiedades cercanos y explican correcciones de coordenadas.
Elige las coordenadas explícitamente con --space native|clip|timeline y --unit frames|seconds. Todos los fotogramas usan FPS del proyecto y son base 1; los segundos comienzan en cero y se ajustan al fotograma más cercano. Native es la coordenada de fotograma clave del motor existente (incluyendo recorte de origen). Las coordenadas de clip comienzan en el punto de entrada visible del clip; las coordenadas de línea de tiempo comienzan en el tiempo cero del proyecto. Los efectos adjuntos usan la sincronización de su clip padre. Estas coordenadas se refieren al tiempo de animación, no a los fotogramas de medios seleccionados por una curva de remapeo de tiempo.
Para un clip posicionado a 5 segundos, recortado a 2 segundos, en un proyecto de 30 fps, el fotograma del clip 1, el fotograma de la línea de tiempo 151 y el fotograma nativo 61 corresponden al mismo punto. La posición y el recorte se ajustan independientemente a la cuadrícula de fotogramas del proyecto. Listar toda una curva puede incluir puntos ocultos con coordenadas de clip/línea de tiempo no positivas. El antiguo --frame sigue significando un fotograma nativo y no puede combinarse con --at.
Ejemplos:
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
Interpolación, suavizado y vista previa
La interpolación describe el segmento hacia el punto de destino. Lineal ofrece una tasa constante entre puntos. Constante mantiene el valor anterior hasta el destino, luego salta. Los manejadores Bezier predeterminados nativos suavizan en ambos extremos de cada segmento. Agregar un punto intermedio puede introducir una desaceleración no deseada; para un movimiento suavizado, comienza con dos puntos finales. Normalmente, deja los manejadores tal cual y elige un preajuste nombrado para un estilo específico.
Descubre los mismos preajustes de suavizado usados por los menús del editor, sin una sesión:
openshot-cli clip keyframe presets
Aplica un preajuste al segmento entrante configurando su 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
La opción de suavizado implica Bezier. Configura conjuntamente el manejador saliente del punto anterior y el manejador entrante del destino, preservando otros manejadores y valores de puntos. Debe existir un punto anterior. No lo combines con manejadores personalizados o una interpolación diferente. Los preajustes funcionan en lotes y plantillas masivas. El preajuste de la GUI ease («Suavizado (Predeterminado)») difiere de los manejadores nativos usados por la interpolación Bezier simple. Los preajustes de retroceso pueden sobrepasar los valores de los puntos finales.
Inspecciona el movimiento antes de renderizar, usando el evaluador nativo de curvas:
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
La vista previa es de solo lectura y funciona igual para efectos y transiciones. Devuelve valores y tasas entrantes/salientes con signo en unidades de propiedad por segundo, calculadas a partir de fotogramas adyacentes inmediatos. Estas son diferencias finitas, no derivadas analíticas. En el fotograma nativo 1, la tasa entrante es nula. Las tasas de fotogramas adyacentes pueden inspeccionar fuera del rango solicitado. Tasas cercanas a cero alrededor de un punto interior revelan una pausa; tasas diferentes revelan un cambio de velocidad. La interpolación constante revela un salto en el destino.
Sin un rango, la vista previa abarca los primeros y últimos puntos de la curva. Los rangos son inclusivos, con 17 muestras espaciadas uniformemente por defecto (–count: 2–256). También se incluyen fotogramas clave y sus vecinos inmediatos dentro del rango, por lo que un conteo de muestras escaso no ocultará una pausa en un fotograma clave. El máximo es 1024 muestras; solicitudes mayores requieren un rango más estrecho. –at muestrea un fotograma. La vista previa reporta coordenadas en el espacio solicitado y fotogramas nativos reales; los segundos se ajustan a los fotogramas del proyecto como en la edición.
Para manejadores personalizados avanzados, tanto X como Y se normalizan al segmento: X es una fracción de su extensión en fotogramas; Y es una fracción del cambio de valor. El primer control proviene del manejador derecho del punto anterior, el segundo del manejador izquierdo del destino. Los valores predeterminados nativos son right=(0.5, 0), left=(0.5, 1), con tangentes planas en los extremos. Cambiar solo el tipo de manejador no recalcula una tangente continua a través de los puntos circundantes. Los manejadores existentes se preservan al mover un punto.
Los rangos de fotogramas clave son inclusivos, a diferencia de los rangos de tiempo de selección de clips. List emite points cuyos valores co.X usan el espacio/unidad de coordenadas solicitado. Pasa ese arreglo a keyframe paste --json @points.json con el mismo espacio/unidad, eligiendo --mode merge (reemplaza fotogramas coincidentes, conserva otros) o --mode replace (reemplaza toda la curva). copy acepta una fuente del mismo tipo de objeto, una opción --source-property, y ancla el primer punto fuente seleccionado en --at sobre el objetivo. Otras curvas y objetos fuente permanecen sin cambios.
transform aplica una escala de tiempo positiva alrededor del primer punto seleccionado, o --pivot, seguido de un --offset con signo en la unidad elegida. Se rechaza el ajuste de fotogramas que crea coordenadas duplicadas, incluyendo colisiones con puntos fuera del rango seleccionado. Las coordenadas nativas deben ser al menos 1. Los manejadores Bézier normalizados nativos y la interpolación se desplazan con cada punto; los manejadores no son coordenadas absolutas de fotogramas. set --handles cambia solo los manejadores suministrados. La interpolación pertenece al punto de destino.
clear mantiene un punto base constante en el fotograma nativo 1: especifica --value o muestrea la curva existente con --at (fotograma nativo 1 por defecto). Eliminar el último punto también mantiene una base constante, por lo que las adiciones posteriores de fotogramas clave siguen siendo válidas.
Seleccionar y editar muchos clips
Usa edit apply --dry-run para validar un lote sin cambiar el proyecto. Usa edit bulk para repetir una plantilla de comando pequeña para cada clip seleccionado, con todos los cambios agrupados en un solo paso de deshacer.
Primero previsualiza una selección:
openshot-cli edit select --json '{"layer":1000000,"start":5,"end":20,"effect":"Saturation"}'
Los selectores soportan ids (matriz única de ID de clips), layer, start/end (segundos en la línea de tiempo), file_id, effect (nombre de clase o alias), y text (true selecciona clips de texto). Los filtros se combinan con AND. Los rangos de tiempo seleccionan clips que se superponen a [start, end); no recortan esos clips. Los resultados se ordenan por posición, capa y luego ID, e incluyen IDs, resúmenes, estado de bloqueo y la revisión actual. Los IDs desconocidos son errores. Un selector vacío es rechazado; use {"all":true} explícitamente para cada clip. Las selecciones están limitadas a 256 clips y nunca se truncan silenciosamente.
Por ejemplo, guarde esta matriz 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}}
]
Valídelo, luego aplíquelo contra la revisión devuelta por la selección:
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
Los comandos de clips existentes heredan id; effects.add hereda clip_id. Omita estos parámetros de destino en las plantillas. Las ediciones de efectos deben referenciar un resultado nombrado anterior. Los nombres son locales a cada clip seleccionado, por lo que look.id se refiere a un efecto diferente para cada clip. Para cambiar instancias de efectos existentes por ID explícito, continúe usando edit apply. El conjunto de IDs seleccionado está fijo antes de la expansión; los cambios en posición o efectos no modifican los objetivos restantes.
clip set aplica propiedades absolutas; clip adjust aplica multiply y luego add a una propiedad numérica o a cada valor en una curva, preservando el tiempo de los puntos, la interpolación y los manejadores normalizados. Valida los valores resultantes, incluyendo posiciones no negativas y volumen. Los campos estructurales permanecen protegidos.
Las operaciones masivas rechazan selecciones vacías, pistas objetivo bloqueadas y más de 256 comandos expandidos. Cada operación expandida pasa una preinspección independiente antes de cualquier edición en vivo. Las ejecuciones de prueba no reservan IDs generados. Use --expect-revision para rechazar selecciones obsoletas. Los lotes exitosos son un solo paso de deshacer, incluso después de guardar/reabrir. Las actualizaciones de la GUI se agrupan. Errores inesperados en tiempo de ejecución/escucha aún pueden dejar una transacción parcial; el error informa las operaciones completadas y deshacer revierte ese grupo, como con edit apply.
Perfiles
Descubrir perfiles y coincidir video importado sin adivinar 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}}'
Las entradas del catálogo incluyen IDs estables, descripciones, dimensiones, FPS racional, relaciones de aspecto y configuraciones de escaneo. La lista/búsqueda está paginada. La coincidencia de fuente devuelve IDs exactos y alternativas clasificadas con diferencias explícitas. Configurar desde un archivo requiere una coincidencia exacta a menos que se especifique --create-custom; nunca elige silenciosamente un perfil cercano. Las imágenes fijas y fuentes solo de audio no pueden definir un perfil de video. La coincidencia usa el FPS declarado de la fuente.
Las configuraciones personalizadas están integradas en el proyecto guardado, incluyendo tasas racionales, por lo que reabrir no requiere instalar un archivo de perfil separado. Los cambios de perfil del proyecto usan la conversión de tasa de cuadros existente y una transacción de deshacer. Deshacer/rehacer restaura el tiempo del clip y los fotogramas clave, incluyendo posiciones sensibles al redondeo. La exportación puede seleccionar un perfil independientemente sin cambiar el proyecto.
El historial de deshacer guardado sigue la preferencia de límite de historial del editor. El límite es un presupuesto suave de acciones: todos los registros pertenecientes a transacciones retenidas se mantienen, por lo que guardar no puede truncar un lote grande en una acción de deshacer parcial. Cero desactiva el historial guardado. El límite separado de solicitud por lotes de 256 comandos aún se aplica.
Inspeccionando medios y líneas de tiempo
Inspeccione el tiempo del clip y la disposición de pistas como texto o JSON, o renderice imágenes para revisar la composición y el encuadre antes de exportar.
Resúmenes de la línea de tiempo
Use una vista de texto para una visión rápida, o JSON estructurado para scripts y 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 por defecto muestra texto compacto con pistas usadas, IDs de objetos, intervalos de línea de tiempo/fuente, estado de flujo, ganancia y huecos/superposiciones. Use --detail summary|clips|full para elegir detalle, --format json para contexto estructurado, y --start/--end, --layer y paginación para enfocar el resultado.
timeline overview proporciona contexto estructurado compacto sin bytes de imagen: IDs ordenados, secuencia por pista, intervalos de línea de tiempo/fuente, rangos visibles de recorte, coordenadas de fotogramas, estado de audio/video, efectos y huecos o superposiciones vecinos. Los intervalos y rangos de fotogramas son exclusivos al final; los números de fotogramas son base uno. Los fotogramas fuente usan FPS de la fuente; las coordenadas de línea de tiempo y fotogramas clave usan FPS del proyecto. Use --layer y --start/--end para enfocar, y --limit/--offset para paginar (por defecto 100, máximo 500 ítems). Los clips con remapeo de tiempo retienen explícitamente los mapeos de fuente inferidos. Use la revisión devuelta con edit apply --expect-revision.
Previsualizaciones de fotogramas y hojas de contacto
Renderice un solo fotograma con thumbnail o muestree un rango con strip. Use file para inspeccionar medios fuente y timeline para inspeccionar el video compuesto, incluyendo efectos y clips en capas:
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
Las imágenes de fotogramas por defecto son de 320x180 píxeles; las hojas de contacto por defecto son de 160x90 por mosaico, más etiquetas de código de tiempo. Use --width y --height para elegir los píxeles de salida. Las respuestas incluyen metadatos exactos de muestra/fotograma. Las hojas de contacto ayudan a revisar la composición a lo largo de una secuencia; use previsualizaciones de fotogramas clave y video renderizado para evaluar el movimiento entre esas muestras.
Imágenes de la línea de tiempo
Captura la disposición de las pistas del editor, incluyendo su regla, miniaturas, efectos, transiciones y formas de onda:
openshot-cli timeline view --start 0 --end 20 --pixels-per-second 80 --output /tmp/tracks.png
Especificar --output selecciona el formato de imagen; --format image también lo selecciona explícitamente. La captura no cambia la vista ni el proyecto del editor. Las respuestas incluyen IDs de clips y tiempos junto con los límites en píxeles.
Las imágenes tienen por defecto 1280 píxeles de ancho, con altura ajustada a las pistas usadas. Usa --width, --height o --all-tracks para ajustar el diseño, y --track-size o --track-label-width para ajustar pistas y etiquetas. El rango de inicio/fin determina el zoom; --pixels-per-second deriva el ancho a partir del rango de tiempo.
Vistas de formas de onda de audio
Elige --mode waveforms para inspeccionar envolventes de audio en la línea de tiempo:
openshot-cli timeline view --start 5 --end 12 --mode waveforms --output /tmp/waves.png
--mode auto usa la visualización de forma de onda en caché existente; --mode thumbnails muestra miniaturas en su lugar. Las formas de onda representan niveles pico/RMS de la fuente con ajustes de volumen y tiempo del clip, antes de efectos de audio o mezcla.
La extracción de formas de onda sin caché decodifica fuentes completas, limitada a 600 segundos por fuente y 1200 segundos-fuente por solicitud. Reducir el rango visible no disminuye ese trabajo de decodificación. Para fuentes más largas, genera formas de onda primero en el editor o usa el modo miniaturas. Las solicitudes posteriores pueden reutilizar formas de onda en caché.
Salida de imagen y límites
Las rutas de imagen deben ser archivos PNG nuevos en directorios existentes. Las imágenes están limitadas a 4096 píxeles por eje, 8,388,608 píxeles totales y 64 muestras de hoja de contacto. Las solicitudes que excedan estos límites fallan antes de renderizar.
Las imágenes se escriben en archivos; las respuestas JSON incluyen sus rutas y tamaños en image_bytes. La inspección espera a que la imagen termine, y las solicitudes grandes pueden ocupar brevemente el editor.
Manejo de tiempos de espera de comandos
Un tiempo de espera de solicitud no significa que una mutación haya fallado. Usa el ID de operación en el error con operation get ID antes de reintentar. operation list descubre mutaciones recientes y sus estados, revisiones y resultados. Las operaciones completadas retienen sus resultados cuando son lo suficientemente pequeños, incluyendo los IDs de objetos devueltos. El almacenamiento está limitado a 100 operaciones y 4 MiB, con cuerpos de resultados individuales omitidos por encima de 256 KiB. Estos registros duran solo durante la sesión activa. No restauran proyectos tras un fallo ni evitan que un comando repetido aplique la misma edición nuevamente. Los trabajos de exportación tienen sus propios comandos de estado/lista.