cli-anything-shotcut

¿Qué hace cli-anything-shotcut?

Una interfaz de línea de comandos con estado para edición de video, construida sobre el formato XML de MLT. Diseñada para agentes de IA y usuarios avanzados que necesitan crear y editar proyectos de Shotcut sin una GUI.

Instalación

Esta CLI se instala como parte del paquete cli-anything-shotcut:

pip install cli-anything-shotcut

Requisitos previos:

• Python 3.10+
• melt (CLI de MLT) — necesario para renderizado y reproducción
• ffmpeg / ffprobe — necesario para sondear medios
• shotcut debe estar instalado en tu sistema

Uso

Comandos básicos

# Mostrar ayuda
cli-anything-shotcut --help

# Iniciar modo REPL interactivo
cli-anything-shotcut

# Crear un nuevo proyecto
cli-anything-shotcut project new -o project.json

# Ejecutar con salida JSON (para consumo de agentes)
cli-anything-shotcut --json project info -p project.json

Modo REPL

Cuando se invoca sin un subcomando, la CLI entra en una sesión REPL interactiva con soporte de deshacer/rehacer:

cli-anything-shotcut
# o con un proyecto:
cli-anything-shotcut --project my_project.mlt

Comandos REPL

Flujo de trabajo: Siempre media import primero para obtener un clip_id, luego usa add-clip para colocarlo en la línea de tiempo.

Proyecto y sesión:

• new [profile] — Crear nuevo proyecto (por defecto: hd1080p30)
• open <path> — Abrir archivo .mlt
• save [path] — Guardar proyecto
• info — Mostrar información del proyecto
• xml — Imprimir XML de MLT en bruto
• status — Mostrar estado de la sesión
• undo / redo — Navegar por el historial de operaciones

Medios (modelo de dos pasos):

• media import <file> [--caption name] — Importar archivo al contenedor del proyecto, devuelve clip_id (ej., clip0)
• media — Listar todos los medios importados
• probe <file> — Analizar un archivo multimedia

Línea de tiempo:

• add-track <video|audio> [name] — Añadir una pista
• tracks — Listar todas las pistas
• show — Vista general visual de la línea de tiempo
• add-clip <clip_id> <track> [in] [out] [--at time] — Colocar clip importado en una pista
• clips <track> — Listar clips en una pista
• remove-clip <track> <clip> — Eliminar un clip
• trim <track> <clip> [--in tc] [--out tc] — Recortar clip
• split <track> <clip> <at> — Dividir clip en un código de tiempo

Filtros:

• list-filters [video|audio] — Explorar filtros disponibles
• filter-info <name> — Mostrar detalles de un filtro
• add-filter <name> [--track n] [--clip n] [key=val ...] — Añadir filtro a un clip, pista o global
• filters [--track n] [--clip n] — Listar filtros activos
• remove-filter <idx> [--track n] [--clip n] — Eliminar filtro por índice
• set-filter <idx> <param> <value> [--track n] [--clip n] — Establecer parámetro de filtro
• volume-envelope [--track n] [--clip n] TIME=LEVEL ... — Envolvente de volumen con fotogramas clave (ej., 00:00:00.000=1.0 00:00:03.000=0.35)
• duck [--track n] [--clip n] START..END ... — Envolvente de atenuación (ej., 00:00:06.000..00:00:09.000)

Exportación:

• presets — Listar preajustes de exportación
• render <output> [--preset name] — Renderizar a archivo de video

Grupos de comandos

Proyecto

Gestión de proyectos: nuevo, abrir, guardar, información.

Comando	Descripción
new	Crear un nuevo proyecto en blanco
open	Abrir un archivo de proyecto .mlt existente
save	Guardar el proyecto actual
info	Mostrar información detallada del proyecto
profiles	Listar perfiles de video disponibles
xml	Imprimir el XML de MLT en bruto del proyecto actual

Línea de tiempo

Operaciones de línea de tiempo: pistas, clips, recorte.

Comando	Descripción
show	Mostrar la vista general de la línea de tiempo
tracks	Listar todas las pistas
add-track	Añadir una nueva pista a la línea de tiempo
remove-track	Eliminar una pista por índice
add-clip	Añadir un clip importado a una pista por clip_id; admite --at para colocación absoluta
remove-clip	Eliminar un clip de una pista
move-clip	Mover un clip entre pistas o posiciones
trim	Recortar los puntos de entrada/salida de un clip
split	Dividir un clip en dos en el código de tiempo dado
clips	Listar todos los clips en una pista
add-blank	Añadir un espacio en blanco a una pista
set-name	Establecer el nombre visible de una pista
mute	Silenciar o activar el sonido de una pista
hide	Ocultar o mostrar una pista de video

Grupo de filtros

Operaciones con filtros: añadir, eliminar, configurar efectos.

Comando	Descripción
list-available	Listar todos los filtros disponibles
info	Mostrar información detallada de un filtro y sus parámetros
add	Añadir un filtro a un clip, pista o global
remove	Eliminar un filtro por índice
set	Establecer un parámetro en un filtro
list	Listar filtros activos en un objetivo
volume-envelope	Crear o reemplazar una envolvente de volumen con fotogramas clave en una pista o clip
duck	Construir una envolvente de atenuación práctica sobre una o más ventanas de tiempo

Medios

Operaciones con medios: sondear, listar, verificar archivos.

Comando	Descripción
import	Importar un archivo multimedia al contenedor del proyecto
probe	Analizar las propiedades de un archivo multimedia
list	Listar todos los clips multimedia en el proyecto actual
check	Verificar la existencia de todos los archivos multimedia
thumbnail	Generar una miniatura a partir de un archivo de video

Exportación

Operaciones de exportación/renderizado.

Comando	Descripción
presets	Listar preajustes de exportación disponibles
preset-info	Mostrar detalles de un preajuste de exportación
render	Renderizar el proyecto a un archivo de video

Grupo de transiciones

Operaciones de transición: disolución, barrido y otras transiciones.

Comando	Descripción
list-available	Listar todos los tipos de transición disponibles
info	Mostrar información detallada de un tipo de transición
add	Añadir una transición entre dos pistas
remove	Eliminar una transición por índice
set	Establecer un parámetro en una transición
list	Listar todas las transiciones en la línea de tiempo

Grupo de composición

Composición: modos de fusión, PIP, opacidad.

Comando	Descripción
blend-modes	Listar todos los modos de fusión disponibles
set-blend	Establecer el modo de fusión para una pista
get-blend	Obtener el modo de fusión actual de una pista
set-opacity	Establecer la opacidad de una pista (0.0-1.0)
pip	Establecer la posición de imagen en imagen para un clip

Sesión

Gestión de sesión: estado, deshacer, rehacer.

Comando	Descripción
status	Mostrar el estado actual de la sesión
undo	Deshacer la última operación
redo	Rehacer la última operación deshecha
save	Guardar el estado de la sesión en disco
list	Listar todas las sesiones guardadas

Vista previa

Paquetes de vista previa y sesiones de vista previa en vivo para revisión iterativa de edición.

Comando	Descripción
preview recipes	Listar recetas de vista previa
preview capture	Renderizar un paquete de vista previa de baja resolución
preview latest	Devolver el paquete existente más reciente
preview live start	Iniciar una sesión de vista previa en vivo y publicar el primer paquete
preview live push	Publicar un nuevo paquete en la sesión en vivo
preview live status	Consultar el estado actual de la sesión en vivo sin renderizar
preview live stop	Detener la sesión en vivo sin eliminar artefactos

Contenido típico de un paquete quick:

• preview.mp4
• varios fotogramas muestreados
• punto medio hero.png
• summary.json con datos del proyecto

Se admite el modo de sondeo:

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

preview live status --json incluye referencias de sesión y un resumen compacto trajectory_summary para que los agentes puedan entender económicamente las últimas publicaciones.

Comandos del visor:

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

Ejemplos

Crear un nuevo proyecto

Crear un nuevo archivo de proyecto de Shotcut.

cli-anything-shotcut project new -o myproject.json
# O con salida JSON para uso programático
cli-anything-shotcut --json project new -o myproject.json

Sesión REPL interactiva

Iniciar una sesión interactiva con soporte de deshacer/rehacer.

cli-anything-shotcut
# Ingresar comandos de forma interactiva
# Usar 'help' para ver los comandos disponibles
# Usar 'undo' y 'redo' para navegar por el historial

Exportar proyecto

Exportar el proyecto a un formato de salida final.

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

Reconstrucción determinista de la línea de tiempo

Para reconstrucciones, prefiere la colocación absoluta sobre la inserción de clips por añadido:

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

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

• --at inserta espacios en blanco automáticamente cuando el tiempo objetivo cae en espacio vacío.
• La CLI rechaza la superposición con un clip existente.
• Prefiere valores explícitos de --in y --out para que la colocación absoluta posterior no sea ambigua.

Automatización de audio

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

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

La CLI mantiene el estado de la sesión con:

• Deshacer/Rehacer: Hasta 50 niveles de historial
• Persistencia del proyecto: Guardar/cargar el estado del proyecto como JSON
• Seguimiento de sesión: Registrar modificaciones y cambios

Formatos de salida

Todos los comandos admiten dos modos de salida:

• Legible por humanos (por defecto): Tablas, colores, texto formateado
• Legible por máquina (bandera --json): JSON estructurado para consumo de agentes

# Salida humana
cli-anything-shotcut project info -p project.json

# Salida JSON para agentes
cli-anything-shotcut --json project info -p project.json

Para agentes de IA

Al usar esta CLI de forma programática:

1. Usa siempre la bandera --json para obtener salida parseable
2. Verifica los códigos de retorno — 0 para éxito, distinto de cero para errores
3. Analiza stderr para mensajes de error en caso de fallo
4. Usa rutas absolutas para todas las operaciones con archivos
5. Verifica que las salidas existan después de las operaciones de exportación
6. Prefiere timeline add-clip --at al recrear una edición conocida
7. Revisa los renders finales después de cambios de volumen con fotogramas clave o atenuación
8. Usa preview capture o preview live ... para validar ritmo, cortes y efectos de filtro visualmente
9. Lee las rutas de artefactos devueltos como hero.png y preview.mp4; los payloads JSON referencian archivos en disco
10. Usa preview live status --json antes de leer el trajectory.json completo
11. Usa cli-hub previews ... solo para inspeccionar/abrir paquetes o sesiones en vivo existentes

Más información

• Documentación completa: Consulta README.md en el paquete
• Cobertura de pruebas: Consulta TEST.md en el paquete
• Metodología: Consulta HARNESS.md en cli-anything-plugin

Versión

1.0.0