Интерфейс командной строки
Интегрируйте OpenShot в ваш командный рабочий процесс. Импортируйте видео, обрезайте и упорядочивайте клипы, применяйте эффекты, анимируйте свойства с помощью ключевых кадров и экспортируйте видео из терминала. Используйте несколько команд для автоматизации повторяющихся правок, написания скрипта для регулярного проекта или позвольте AI-агенту помочь собрать и улучшить видео.
Командная строка работает с теми же проектами, что и редактор. Вы можете управлять открытым редактором и просматривать изменения по ходу работы или работать в безголовой сессии без открытия окна. Сессия сохраняет ваш проект открытым между командами, включая правки, историю отмен и задания на экспорт. Сохраняйте его как проект .osp, когда захотите продолжить редактирование позже.
Начало работы
Используйте установленный исполняемый файл OpenShot с параметром --cli. Начните с intro для краткого руководства по сессиям, редактированию, анимации и сохранению, или с help для обзора команд. Эти команды не требуют активной сессии. Примеры ниже требуют сборку OpenShot с поддержкой редактирования из командной строки.
Linux AppImage
Из каталога, содержащего загруженный AppImage:
./OpenShot.AppImage --cli intro
./OpenShot.AppImage --cli help
Замените OpenShot.AppImage на имя вашего загруженного файла. Если AppImageLauncher показывает диалоги интеграции с рабочим столом, установите APPIMAGELAUNCHER_DISABLE=1 перед запуском команды:
APPIMAGELAUNCHER_DISABLE=1 ./OpenShot.AppImage --cli intro
Для скриптов или повторяющихся команд установите переменную один раз в текущей оболочке:
export APPIMAGELAUNCHER_DISABLE=1
./OpenShot.AppImage --cli session start
Переменная должна быть установлена до запуска AppImage: AppImageLauncher может перехватить её до того, как OpenShot получит --cli. Относительные пути к медиа и файлы @batch.json разрешаются относительно вашей рабочей директории. Держите файл AppImage доступным, пока сессии или экспорты выполняются.
Linux Snap
Для OpenShot Snap используйте:
snap run openshot-qt --cli intro
snap run openshot-qt --cli help
snap run openshot-qt --cli session start
Разрешения файлов Snap также применяются к редактированию из командной строки. Храните медиа, проекты и экспорты в местах, доступных Snap, например, в домашней папке. Чтобы разрешить доступ к внешним дискам, подключите разрешение removable-media:
sudo snap connect openshot-qt:removable-media
Windows
Важно
Используйте openshot-qt-cmd.exe для редактирования из командной строки в Windows. Этот консольный исполняемый файл отображает результаты команд, помощь и ошибки в вашем терминале. Десктопный исполняемый файл openshot-qt.exe не выводит стандартный вывод в интерактивном терминале, оставляя команды без видимой обратной связи и затрудняя использование CLI.
В PowerShell из каталога установки OpenShot:
& .\openshot-qt-cmd.exe --cli intro
& .\openshot-qt-cmd.exe --cli help
& .\openshot-qt-cmd.exe --cli session start
Если вы находитесь в другом каталоге, используйте полный путь к openshot-qt-cmd.exe. Сохраняйте --cli после имени исполняемого файла.
macOS
Для установки в Applications:
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli intro
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli help
Поиск команд
В этом руководстве openshot-cli — сокращение для команды вашей установки, например, snap run openshot-qt --cli или ./OpenShot.AppImage --cli. Некоторые установки также предоставляют команду openshot-cli напрямую. При запуске из исходников используйте python3 src/launch.py --cli в Python-среде OpenShot.
Простые команды --cli, --cli help и --cli --help показывают одинаковый обзор. Помощь становится более конкретной по мере навигации по командам:
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
Групповая помощь объясняет рабочие процессы с примерами; помощь по операциям описывает аргументы и поведение. --help эквивалентно добавлению help в конце. Все команды помощи работают без сессии редактирования.
effects list показывает доступные эффекты с краткими описаниями. Помощь по эффектам объясняет их свойства, значения по умолчанию, варианты и диапазоны. effects instances перечисляет эффекты, уже применённые к клипам, с идентификаторами родительских клипов. Имена классов, отображаемые имена и псевдонимы с подчёркиванием идентифицируют один и тот же эффект.
Работа со скриптами и AI-агентами
AI-агенты программирования, такие как Codex и Claude Code, могут использовать CLI для просмотра и редактирования проектов OpenShot через команды терминала. Укажите агенту путь к исполняемому файлу OpenShot, медиа или проект для работы, а также желаемый результат: длительность, размеры, стиль анимации и место вывода. Попросите его прочитать --cli intro перед началом. Те же команды работают, когда вы вводите их сами или запускаете из скрипта.
Начните с intro, затем используйте помощь по конкретным командам по мере необходимости. Полезный рабочий процесс — выбрать сессию, просмотреть проект, внести небольшой набор изменений, проверить результат и сохранить. Команды возвращают структурированный JSON, чтобы скрипты и агенты могли использовать идентификаторы объектов и результаты напрямую, не интерпретируя вывод на экране.
Проверяйте перед редактированием. Используйте возвращённые идентификаторы и информацию о свойствах вместо угадывания имён, номеров дорожек или времени. Явно выбирайте сессию, если открыто несколько проектов.
Группируйте повторяющиеся правки. Используйте
edit applyдля последовательности изменений илиedit bulkдля применения шаблона к выбранным клипам. Проверьте с помощью--dry-runперед применением пакета.Проверьте анимацию. Выберите систему координат, начните с нескольких ключевых кадров и используйте пресеты сглаживания для привычного движения.
keyframe previewвыбирает точки кривой, чтобы вы могли заметить паузы или скачки до экспорта. Также просмотрите отрендеренное движение; один только контактный лист не покажет, как ощущается анимация.Сохраняйте и отслеживайте экспорт. Явно сохраняйте проект и проверяйте статус задания экспорта перед тем, как считать вывод завершённым. Если запрос истекает по времени, проверьте его статус перед повторным редактированием.
Ниже описаны эти рабочие процессы и их временные соглашения.
Сессии и выводы
Запуск или поиск сессии
Запустите одну безголовую сессию (без окна редактора):
openshot-cli session start
Чтобы открыть существующий проект при запуске, добавьте --project "/path/project.osp". Успешный JSON-ответ содержит result.session_id. Скопируйте это значение. Если OpenShot уже запущен или вы забыли ID, найдите доступные сессии с помощью:
openshot-cli session list
Выберите сессию для проекта, который собираетесь редактировать. Нет необходимости запускать новую сессию для каждой команды.
Выбор сессии
Совет
Установите OPENSHOT_SESSION один раз, затем выполняйте команды как обычно. Ваш терминал запоминает выбранную сессию, поэтому не нужно передавать --session с каждой командой. Используйте приведённые ниже примеры для PowerShell или Bash.
Замените SESSION_ID ниже на session_id, возвращённый командами session start или 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
На macOS используйте тот же синтаксис export. Для команд macOS или Snap подставьте исполняемый файл вашей установки из раздела «Начало работы». Выбор действует для этого терминала и команд, запущенных из него. Установите заново в новом терминале или обновите при переключении на другую сессию.
Оставшиеся примеры редактирования и экспорта предполагают, что OPENSHOT_SESSION установлен. Следующий подраздел показывает, как автоматически получить ID для скриптов.
Чтобы указать другую сессию только для одной команды, используйте --session. Это переопределяет OPENSHOT_SESSION без изменения выбора терминала:
openshot-cli --session OTHER_SESSION_ID project get
В упакованном исполняемом файле поместите это переопределение после --cli и перед группой команд: --cli --session OTHER_SESSION_ID project get.
Автоматический выбор работает только если существует ровно одна доступная сессия. Если вы видите session_required, выполните session list и явно выберите нужную сессию. Если она больше не отображается, запустите её снова и используйте новый ID. Помощь, intro и обнаружение сессий не требуют выбранной сессии.
Автоматическое получение ID сессии
Скрипты могут читать result.session_id напрямую из JSON, возвращённого командой session start, и устанавливать OPENSHOT_SESSION для последующих команд. Нет необходимости копировать ID вручную или читать файл журнала. Проверьте успешность запуска перед использованием возвращённого ID.
Windows PowerShell (установите путь к исполняемому файлу вашей установки):
$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 (требуется jq для чтения 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
Переменная окружения выбирает сессию для команд, запущенных из этого терминала; она не изменяет системные настройки. Запуск сессии не устанавливает переменную автоматически. После остановки сессии очистите выбор с помощью Remove-Item Env:OPENSHOT_SESSION в PowerShell или unset OPENSHOT_SESSION в Bash.
Отображение и остановка сессии
Чтобы показать выбранную сессию в редакторе:
openshot-cli session show
На рабочем столе команда session show создаёт редактор в том же процессе и сохраняет живой проект, ID, историю, задания экспорта и соединение. Повторные вызовы поднимают существующее окно. session start --show открывает его сразу. Сессии, запущенные без дисплея или с QT_QPA_PLATFORM=offscreen/minimal, не могут позже показать окно рабочего стола. Для таких сессий сохраните и откройте проект в новой сессии рабочего стола. После отображения закройте сессию через окно редактора.
Глобальные опции (--session, --timeout) ставятся перед командой. session serve остаётся на переднем плане для супервизоров; session start возвращается после регистрации фонового хоста. session stop отказывается при несохранённых изменениях и активных экспортных заданиях. Используйте --discard только для намеренного отбрасывания несохранённых изменений.
Вывод команды
Результаты выводятся в формате JSON в stdout, кроме стандартного текстового вида таймлайна. Ошибки выводятся в формате JSON в stderr с кодом выхода 1; ошибки парсера аргументов — с кодом 2. Мутации возвращают компактные сводки с помощью команды inspect. get возвращает JSON нативного объекта. Ответы проекта включают ревизию; ответы каталога эффектов не требуют сессии. Логи безголовых сессий хранятся рядом с их записями в реестре. OPENSHOT_SESSION_DIR переопределяет стандартный каталог ~/.openshot_qt/sessions.
Сессии принимают команды локально на вашем компьютере. Храните реестр сессий в секрете, так как он содержит учетные данные для доступа к вашим сессиям редактирования. Экспорт выполняется из снимка, поэтому вы можете продолжать редактирование, пока выполняется задача.
Открытие и сохранение проектов
Проект OpenShot (.osp) сохраняет вашу редактируемую временную шкалу. Экспорт создает готовое видео; сохранение проекта позволяет вернуться к его клипам, эффектам и ключевым кадрам позже. Сохраняйте проект отдельно, даже если вы также экспортируете видео.
Открытие проекта
Запустите сессию с существующим проектом:
openshot-cli session start --project "/home/me/Videos/My Project.osp"
Добавьте --show, чтобы также открыть окно редактора. Чтобы использовать уже запущенный редактор, найдите его с помощью session list. Установите OPENSHOT_SESSION в возвращенный идентификатор сессии, затем откройте или просмотрите проект:
openshot-cli project open "/home/me/Videos/My Project.osp"
openshot-cli project get
Замените пример пути на свой собственный и заключайте пути с пробелами в кавычки. project open заменяет текущий проект выбранной сессии. Он отказывается отбрасывать несохранённые изменения, если вы явно не добавите --discard; сначала сохраните эти изменения, если хотите их сохранить. Открытие через CLI не показывает интерактивные диалоги о недостающих медиа, поэтому держите исходные медиа проекта доступными.
Для нового пустого проекта используйте session start без --project, затем импортируйте медиа и добавляйте клипы, как описано в разделе Редактирование.
Сохранение проекта или его копии
Сохраните в новый файл или создайте отдельную версию перед внесением дополнительных изменений:
openshot-cli project save "/home/me/Videos/My Project v2.osp"
Чтобы обновить существующий файл, явно разрешите замену:
openshot-cli project save "/home/me/Videos/My Project v2.osp" --overwrite
Всегда указывайте путь назначения. Сохранение .osp не упаковывает все исходные материалы в этот файл; сохраняйте доступность ссылочных медиа при перемещении или повторном открытии проекта.
Экспорт видео
Автоматизируйте рендеринг и экспорт из скриптов или AI-агентов, используя настройки проекта или выбирая другой профиль вывода для каждого рендера. Задачи экспорта могут выполняться в фоновом режиме или ждать завершения перед продолжением вашего скрипта. Чтобы отрендерить MP4 с разрешением и частотой кадров проекта:
openshot-cli export start "/home/me/Videos/video.mp4" --wait
По умолчанию OpenShot использует видео H.264 и аудио AAC. Замените пример пути на ваш путь назначения, используя существующую папку и новое имя файла. Существующие выходные файлы никогда не перезаписываются. Экспорт не сохраняет ваш редактируемый проект .osp; используйте project save отдельно, чтобы сохранить вашу работу.
Опция --wait удерживает команду в работе до завершения экспорта или сообщения об ошибке. Просмотрите готовое видео перед его распространением.
Проверка прогресса экспорта
Не используйте --wait, чтобы запустить экспорт в фоновом режиме. Ответ включает идентификатор задачи, который можно использовать для проверки прогресса:
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
Замените JOB_ID на возвращенный идентификатор. Если время ожидания истекает, экспорт продолжает работу; проверяйте ту же задачу вместо запуска нового экспорта. Чтобы остановить задачу, используйте export cancel JOB_ID. Каждая задача фиксирует временную шкалу при запуске, поэтому последующие изменения не влияют на уже запущенный экспорт.
Время ожидания по умолчанию — 600 секунд; измените его с помощью --wait-timeout. Это отличается от глобального --timeout для каждого запроса. Ошибки экспорта, отмена и тайм-ауты ожидания завершаются с кодом 1 и содержат детали задачи.
Экспорт в нескольких профилях
Экспортируйте одну и ту же временную шкалу в разных разрешениях или соотношениях сторон, выбирая профиль экспорта для каждого вывода. Профиль экспорта применяется только к этой задаче; он не изменяет профиль редактируемого проекта. Профиль задает размеры, частоту кадров и соотношение сторон; пресет экспорта выбирает настройки кодирования, например MP4/H.264.
Найдите доступные профили и просмотрите их настройки:
openshot-cli profile list --search 720
openshot-cli profile list --search 1080
openshot-cli profile get builtin:01280x0720p0030_16-09
Например, экспортируйте версии в ландшафтном формате с разрешением 720p и 1080p, затем квадратную версию 1080 на 1080. Все эти профили используют 30 кадров в секунду:
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
Используйте разные имена файлов вывода для каждой версии. Сохраняйте изменения неизменными между задачами, если хотите получить совпадающие версии. Изменение соотношения сторон может изменить кадрирование: проверьте каждый вывод, особенно заголовки и анимированные объекты. Для отдельно составленной квадратной или портретной версии сохраните копию проекта, измените профиль проекта и отрегулируйте клипы перед экспортом. См. раздел Профили и настройки экспорта ниже для пользовательских профилей и параметров кодирования.
Пакетный экспорт нескольких проектов
Используйте одну безголовую сессию для последовательного рендеринга нескольких сохранённых проектов. Откройте проект, экспортируйте его с --wait, затем откройте следующий проект. Примеры ниже используют разрешение и частоту кадров каждого проекта и создают MP4-файлы рядом с файлами .osp. Добавьте --profile PROFILE_ID к команде экспорта, чтобы использовать один профиль вывода для всех проектов.
Сначала успешно выполните приведённый выше пример автоматического определения session-ID в том же терминале. Он определяет openshot и выбирает новую сессию. Замените пути к проектам ниже на свои. Используйте уникальные имена выходных файлов, которые ещё не существуют; примеры проверяют все назначения перед запуском пакета.
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 (скобки ограничивают обработку ошибок локально для пакета):
(
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
Оба варианта останавливают пакет при ошибке команды и оставляют сессию доступной для проверки. Лимит ожидания здесь — 24 часа на экспорт. Таймаут ожидания оставляет рендер запущенным: используйте export list и export status JOB_ID --wait перед повторной попыткой. Завершённые видео остаются на диске; удалите завершённые проекты из пакета перед возобновлением. После устранения ошибки остановите сессию и очистите её переменную окружения, когда закончите.
Выбор пресетов и настроек кодирования
Просмотрите установленные пресеты экспорта и поддерживаемые настройки:
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
Экспорт также принимает --from-file FILE_ID с опциональным --create-custom. Настройки разрешаются в следующем порядке: значения по умолчанию проекта, пресет, расширенный JSON, явные флаги профиля/качества/диапазона. Расширенный JSON раскрывает видео/аудио кодеки и битрейт, расположение/частоту/каналы аудио, нативные опции кодека, настройки аппаратных устройств и количество потоков.
Например, выберите опцию кодера через расширенный JSON:
openshot-cli export start /tmp/small.mp4 --profile builtin:00640x0360p0030_16-09 --json '{"video_options":{"preset":"fast"}}' --wait
Проверка настроек экспорта
Проверьте настройки перед началом рендеринга:
openshot-cli export validate /tmp/reel.mp4 --preset builtin:format_mp4_x264
Отчёт о возможностях показывает доступность скомпилированных кодеков, а не физическую доступность GPU. Проверка идёт дальше: она открывает кодеки (включая аппаратные) и контейнер с точными настройками в отдельном процессе без записи файла. Комбинация, которую контейнер не поддерживает, завершается ошибкой incompatible_export с объяснением FFmpeg и указанием настройки для изменения (details.cause.path):
openshot-cli export validate /tmp/song.mp3 --json '{"mode":"audio","format":"mp3","audio_codec":"aac"}'
Рабочий процесс экспорта выполняет ту же проверку перед рендерингом.
Рендеринг диапазона кадров
Используйте --start-frame и --end-frame для рендеринга части таймлайна. Диапазоны включают границы и нумеруются с единицы по FPS профиля экспорта. Например, отрендерьте первые 90 кадров при 30 fps (три секунды):
openshot-cli export start /tmp/excerpt.mp4 --profile builtin:01280x0720p0030_16-09 --start-frame 1 --end-frame 90 --wait
Экспорт только аудио и последовательности изображений
Выберите режим вывода с помощью расширенного JSON:
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
Последовательности изображений требуют новой выходной директории. Существующие выходные данные никогда не перезаписываются.
Редактирование
Добавление клипов и эффектов
Используйте ID, возвращаемые командами import/add/list, и узнайте номера слоёв с помощью 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
Выбирайте профиль проекта как можно раньше; заполненные проекты также поддерживают изменение профиля через существующую систему конвертации FPS и отмены. --audio-only при создании клипа подавляет видео, включая встроенные обложки в музыкальных файлах. Чтобы использовать этот клип для аудиовизуализации, включите его видео и аудио и следуйте подсказкам эффекта для прозрачных наложений и размещения слоёв.
Понимание временных характеристик клипа
Пример ключевых кадров предполагает проект с 30 fps и клип, обрезанный на исходном 10-секундном участке. Позиция указана в секундах таймлайна; начало/конец — в исходных секундах, конец исключён. Кадры нумеруются с 1. Кадры миниатюр файлов используют исходный FPS. Кадры таймлайна используют FPS проекта. Ключевые кадры клипа используют исходные координаты при FPS проекта, поэтому обрезка клипа не сдвигает первый видимый ключевой кадр к кадру 1.
Изменение свойств
set объединяет свойства верхнего уровня. Скаляры превращают анимированные свойства в константы. Переданная вложенная кривая заменяет эту кривую; используйте keyframe set для изменения только одной точки. Аргументы JSON принимают встроенный JSON, @file.json или - для stdin. Имена свойств, типы, перечисления, ключевые кадры, ссылки и тайминги проверяются перед редактированием проекта. Ошибки указывают поле, ожидаемое значение, полученное значение и возможное исправление. Диапазоны слайдеров GUI являются рекомендательными, если движок поддерживает значения за их пределами.
Добавление затуханий
clip fade ID --in 0.5 --out 0.5 автоматически вычисляет координаты ключевых кадров обрезки источника. Это заменяет альфа-кривую; --property volume --value 0.25 создаёт аудиозатухание с пиковым усилением 0.25. Продолжительности должны помещаться между первым и последним видимыми кадрами; затухание достигает нуля на последнем кадре.
Разделение клипов
clip split ID --at 6.5 использует секунды таймлайна, привязывается к ближайшему кадру проекта и сохраняет обе половины. Он сохраняет кривые исходных координат и дублирует эффекты с новыми ID на правой половине, следуя поведению редактора при разрезании. Левая половина сохраняет свой ID. Ответ содержит запрошенное/фактическое время разреза и оба сводных отчёта; именованный результат пакета поддерживает {"$ref":"cut.right.id"}. Разрезы отклоняют конечные точки и заблокированные дорожки. Отмена восстанавливает исходный клип одной транзакцией.
Добавление и оформление текста
text add создаёт текст и размещает его как клип, используя тот же текст, что и инструмент Текст редактора. Опции, которые вы пропускаете, используют стиль по умолчанию редактора:
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
Слова, шрифт, размер, выравнивание, ширина блока и цвета по умолчанию принадлежат тексту в файлах проекта и используются всеми клипами, которые его используют, так же, как и в редакторе. text set для одного клипа изменяет их все и перечисляет их в changed_clip_ids; --this-clip-only сначала даёт этому клипу его собственную копию. clip add FILE_ID добавляет другой клип текста из text list. Размеры указаны в пикселях при разрешении проекта, а цвета — в формате #RRGGBB, #AARRGGBB (с альфа-каналом), CSS-имени или transparent. --place размещает блок в центре, на краю или углу, либо в нижней трети. --line-spacing — это множитель нормального расстояния между строками (1 — нормально), а --background-corner скругляет углы фона и рамки на указанное количество пикселей.
Текстовый клип — это обычный клип. Положение, масштаб, вращение, непрозрачность, тайминг, затухания, предустановки движения и эффекты используют обычные команды clip. Размер шрифта, отступы, ширина блока, а также межбуквенное и межстрочное расстояния задают размер текстового блока, поэтому их нельзя анимировать с помощью ключевых кадров; чтобы анимировать размер текста, анимируйте масштаб клипа. Каждый клип может анимировать свои собственные цвета текста, контур и ширину рамки с помощью тех же команд ключевых кадров, что и для любых других свойств:
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
Анимируемые свойства: text_color, text_background, text_stroke и text_border (цвета с компонентами .red, .green, .blue и .alpha от 0 до 255), а также text_stroke_width, text_border_width и text_background_corner. Собственная анимация клипа имеет приоритет над общим стилем, а команда text get показывает, какие стили анимирует клип. text reset CLIP_ID возвращает клип к стилю по умолчанию, как в Текст → Сбросить стиль; --keyframes-only просто удаляет собственную анимацию клипа. Чтобы оформить сразу много текстов, выберите их с помощью {"text":true}:
openshot-cli edit bulk --select '{"text":true}' --json '[{"method":"text.set","params":{"font_family":"Noto Sans","stroke_width":2}}]'
Применение пакета правок
edit apply --json @edits.json --expect-revision 12 принимает до 256 упорядоченных команд мутации, используя имена команд с точками, такие как clip.set и effects.add (старое написание 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}}
]
Опциональный параметр as связывает результат для последующих команд в том же пакете. Объект {"$ref":"shot.id"} подставляет поле этого результата. Ссылки разрешаются только на ранее объявленные имена; опечатки, ссылки вперёд и дублирующиеся имена вызывают ошибку до живых обновлений. Ответ включает упорядоченные компактные результаты и карту refs с реальными ID. Все изменения в успешном пакете формируют один шаг отмены/повтора. project.profile.set также поддерживает заполненные таймлайны. Команды открытия, сохранения, экспорта и инспекции остаются вне пакетов правок. Справка каждой команды перечисляет имена параметров JSON, включая написание с подчёркиванием для флагов оболочки (например, --fps-num становится fps_num).
Проверка пакетов и обработка ошибок
Все команды в пакетах правок предварительно проверяются на отдельном проекте перед любыми живыми обновлениями. Некорректный ввод не изменяет живой проект и ревизию. Корректные пакеты формируют одну группу отмены. Неожиданные ошибки выполнения могут привести к частичным изменениям; ошибки сообщают о выполненных операциях. Таймаут не означает отмену, поэтому проверяйте состояние перед повторной попыткой мутаций.
Точное редактирование ключевых кадров
clip, transition и effects поддерживают команды keyframe list, set, remove, clear, transform, copy и paste. Пути свойств могут обращаться к вложенным кривым, например, color.red в эффекте Chroma Key. Редактирование вложенной кривой сохраняет соседние каналы. Выполните keyframe list ID без свойства, чтобы узнать пути кривых и количество точек. Обнаружение и списки точек включают контекст тайминга обрезки/позиции; списки точек также показывают координаты в исходных кадрах. get и properties показывают полный исходный объект и метаданные свойств. Ошибки указывают недопустимые поля, предлагают похожие имена свойств и объясняют корректировки координат.
Явно выбирайте координаты с помощью --space native|clip|timeline и --unit frames|seconds. Все кадры используют FPS проекта и нумеруются с 1; секунды начинаются с нуля и привязываются к ближайшему кадру. Native — это существующая координата ключевого кадра движка (включая обрезку источника). Координаты клипа начинаются с видимой точки входа клипа; координаты таймлайна начинаются с нуля времени проекта. Прикреплённые эффекты используют тайминг родительского клипа. Эти координаты относятся к времени анимации, а не к медиа-кадрам, выбранным кривой ремаппинга времени.
Для клипа, расположенного на 5-й секунде, обрезанного на 2 секунде, в проекте с 30 кадрами в секунду, кадр клипа 1, кадр на временной шкале 151 и нативный кадр 61 соответствуют одной и той же точке. Позиция и обрезка привязываются независимо к сетке кадров проекта. Перечисление всей кривой может включать скрытые точки с неположительными координатами клипа/временной шкалы. Устаревший параметр --frame по-прежнему означает нативный кадр и не может использоваться вместе с --at.
Примеры:
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
Интерполяция, сглаживание и предварительный просмотр
Интерполяция описывает сегмент до конечной точки. Линейная обеспечивает равномерную скорость между точками. Константная удерживает предыдущее значение до конечной точки, затем происходит скачок. Нативные стандартные Безье-ручки обеспечивают сглаживание на обоих концах каждого сегмента. Добавление промежуточной точки может вызвать нежелательное замедление; для одного сглаженного движения начните с двух конечных точек. Обычно ручки оставляют без изменений и выбирают именованный пресет для конкретного стиля.
Ознакомьтесь с теми же пресетами сглаживания, которые используются в меню редактора, без сессии:
openshot-cli clip keyframe presets
Примените пресет к входящему сегменту, задав его конечную точку:
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
Опция сглаживания подразумевает Безье. Она устанавливает исходящую ручку предыдущей точки и входящую ручку конечной точки вместе, сохраняя остальные ручки и значения точек. Предыдущая точка должна существовать. Не комбинируйте это с пользовательскими ручками или другой интерполяцией. Пресеты работают пакетами и массовыми шаблонами. Пресет GUI ease («Ease (Default)») отличается от нативных ручек, используемых в простой Безье-интерполяции. Обратные пресеты могут превышать значения конечных точек.
Просмотрите движение до рендеринга, используя нативный оценщик кривых:
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
Предварительный просмотр доступен только для чтения и работает одинаково для эффектов и переходов. Он возвращает значения и знаковые входящие/исходящие скорости в единицах свойства в секунду, вычисленные по соседним кадрам. Это конечные разности, а не аналитические производные. В нативном кадре 1 входящая скорость равна нулю. Скорости соседних кадров могут выходить за запрошенный диапазон. Почти нулевые скорости вокруг внутренней точки указывают на паузу; разные скорости показывают изменение скорости. Константная интерполяция показывает скачок в конечной точке.
Без указания диапазона предварительный просмотр охватывает первые и последние точки кривой. Диапазоны включают границы, по умолчанию 17 равномерно распределённых выборок (–count: 2–256). Включаются ключевые кадры и их ближайшие соседи внутри диапазона, поэтому малое количество выборок не скроет зависание ключевого кадра. Максимум — 1024 выборки; для больших запросов требуется более узкий диапазон. –at выбирает один кадр. Предварительный просмотр показывает координаты в запрошенном пространстве и фактические нативные кадры; секунды привязываются к кадрам проекта, как и при редактировании.
Для продвинутых пользовательских ручек координаты X и Y нормализованы относительно сегмента: X — доля длины сегмента в кадрах; Y — доля изменения значения. Первый контроль берётся из handle_right предыдущей точки, второй — из handle_left конечной точки. Нативные значения по умолчанию: right=(0.5, 0), left=(0.5, 1), с плоскими касательными на концах. Изменение только handle_type не пересчитывает непрерывную касательную через соседние точки. Существующие ручки сохраняются при перемещении точки.
Диапазоны ключевых кадров включают границы, в отличие от временных диапазонов выбора клипа. Команда list выводит points, у которых значения co.X используют запрошенное пространство/единицу координат. Передайте этот массив в keyframe paste --json @points.json с тем же пространством/единицей, выбрав --mode merge (заменить совпадающие кадры, сохранить остальные) или --mode replace (заменить всю кривую). copy принимает источник того же типа объекта, необязательный параметр --source-property и закрепляет первую выбранную точку источника на --at в цели. Другие кривые и исходные объекты остаются без изменений.
transform применяет положительный масштаб времени вокруг первой выбранной точки или --pivot, за которым следует знаковый --offset в выбранной единице. Привязка к кадрам, создающая дублирующиеся координаты, отклоняется, включая столкновения с точками вне выбранного диапазона. Нативные координаты должны оставаться не меньше 1. Нативные нормализованные Безье-ручки и интерполяция перемещаются вместе с каждой точкой; ручки не являются абсолютными координатами кадров. set --handles изменяет только указанные ручки. Интерполяция принадлежит конечной точке.
clear сохраняет постоянную базовую точку в нативном кадре 1: укажите --value или возьмите выборку существующей кривой с помощью --at (по умолчанию нативный кадр 1). Удаление последней точки также сохраняет постоянную базу, поэтому последующее добавление ключевых кадров остаётся корректным.
Выбор и редактирование множества клипов
Используйте edit apply --dry-run для проверки пакета без изменений в проекте. Используйте edit bulk для повторения небольшого шаблона команды для каждого выбранного клипа, при этом все изменения объединяются в один шаг отмены.
Сначала предварительно просмотрите выбор:
openshot-cli edit select --json '{"layer":1000000,"start":5,"end":20,"effect":"Saturation"}'
Селекторы поддерживают ids (уникальный массив ID клипов), layer, start/end (секунды на временной шкале), file_id, effect (имя класса или псевдоним) и text (true выбирает текстовые клипы). Фильтры комбинируются с помощью И. Временные диапазоны выбирают клипы, пересекающиеся с [start, end); они не обрезают эти клипы. Результаты упорядочены по позиции, слою, затем ID, и включают ID, сводки, состояние блокировки и текущую ревизию. Неизвестные ID считаются ошибками. Пустой селектор отклоняется; используйте явно {"all":true} для каждого клипа. Выбор ограничен 256 клипами и никогда не обрезается без уведомления.
Например, сохраните этот массив как 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}}
]
Проверьте его, затем примените к ревизии, возвращённой выбором:
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
Команды для существующих клипов наследуют id; effects.add наследует clip_id. Опускайте эти целевые параметры в шаблонах. Редактирование эффектов должно ссылаться на ранее именованный результат. Имена локальны для каждого выбранного клипа, поэтому look.id относится к разным эффектам для каждого клипа. Чтобы изменить существующие экземпляры эффектов по явному ID, продолжайте использовать edit apply. Выбранный набор ID фиксируется до расширения; изменения позиции или эффектов не изменяют оставшиеся цели.
clip set применяет абсолютные свойства; clip adjust применяет multiply, затем add к числовому свойству или каждому значению кривой, сохраняя время точек, интерполяцию и нормализованные ручки. Он проверяет полученные значения, включая неотрицательные позиции и громкость. Структурные поля остаются защищёнными.
Массовые операции отклоняют пустые выборки, заблокированные целевые дорожки и более 256 расширенных команд. Каждая расширенная операция проходит отдельную проверку перед любым живым редактированием. Тестовые прогоны не резервируют сгенерированные ID. Используйте --expect-revision, чтобы отклонять устаревшие выборки. Успешные пакеты составляют один шаг отмены, включая после сохранения/повторного открытия. Обновления GUI группируются. Неожиданные ошибки времени выполнения/слушателя могут оставить частичную транзакцию; ошибка сообщает о выполненных операциях, а отмена откатывает эту группу, как и с edit apply.
Профили
Обнаружение профилей и сопоставление импортированного видео без угадывания 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}}'
Записи каталога включают стабильные ID, описания, размеры, рациональный FPS, соотношения сторон и настройки сканирования. Список/поиск разбиты на страницы. Сопоставление источника возвращает точные ID и ранжированные альтернативы с явными отличиями. Установка из файла требует точного совпадения, если не указан --create-custom; он никогда не выбирает близкий профиль без уведомления. Статичные изображения и источники только с аудио не могут определять видео профиль. Сопоставление использует объявленный FPS источника.
Пользовательские настройки встроены в сохранённый проект, включая рациональные частоты кадров, поэтому повторное открытие не требует установки отдельного файла профиля. Изменения профиля проекта используют существующее преобразование частоты кадров и одну транзакцию отмены. Отмена/повтор восстанавливает тайминг клипов и ключевые кадры, включая позиции, чувствительные к округлению. Экспорт может независимо выбирать профиль без изменения проекта.
Сохранённая история отмены следует предпочтению редактора по лимиту истории. Лимит — это мягкий бюджет действий: все записи, принадлежащие сохранённым транзакциям, сохраняются, поэтому сохранение не может усечь большую партию до частичного действия отмены. Ноль отключает сохранённую историю. Отдельное ограничение на пакет из 256 команд всё ещё применяется.
Просмотр медиа и временных шкал
Просматривайте тайминг клипов и расположение дорожек в виде текста или JSON, или рендерьте изображения для проверки композиции и кадрирования перед экспортом.
Сводки временной шкалы
Используйте текстовый вид для быстрого обзора или структурированный JSON для скриптов и агентов:
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 по умолчанию отображает компактный текст с используемыми дорожками, ID объектов, интервалами временной шкалы/источника, состоянием потока, усилением и пропусками/перекрытиями. Используйте --detail summary|clips|full для выбора детализации, --format json для структурированного контекста, а также --start/--end, --layer и пагинацию для фокусировки результата.
timeline overview предоставляет компактный структурированный контекст без байтов изображений: упорядоченные ID, последовательность по дорожкам, интервалы временной шкалы/источника, видимые диапазоны обрезки, координаты кадров, состояние аудио/видео, эффекты и соседние пропуски или перекрытия. Интервалы и диапазоны кадров исключают конец; номера кадров начинаются с единицы. Кадры источника используют FPS источника; координаты временной шкалы и ключевых кадров используют FPS проекта. Используйте --layer и --start/--end для фокусировки, а --limit/--offset для пагинации (по умолчанию 100, максимум 500 элементов). Клип с временным ремаппингом явно скрывает выводимые сопоставления источника. Используйте возвращённую ревизию с edit apply --expect-revision.
Предпросмотры кадров и контактные листы
Отрендерьте один кадр с помощью thumbnail или выберите диапазон с помощью strip. Используйте file для просмотра исходного медиа и timeline для просмотра смонтированного видео, включая эффекты и слоистые клипы:
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
Изображения кадров по умолчанию имеют размер 320x180 пикселей; контактные листы — 160x90 на плиту, плюс метки таймкода. Используйте --width и --height для выбора размера вывода в пикселях. Ответы включают точные метаданные образца/кадра. Контактные листы помогают оценить композицию по последовательности; используйте предпросмотр ключевых кадров и отрендеренное видео для оценки движения между этими образцами.
Изображения временной шкалы
Снимите расположение дорожек редактора, включая линейку, миниатюры, эффекты, переходы и формы волн:
openshot-cli timeline view --start 0 --end 20 --pixels-per-second 80 --output /tmp/tracks.png
Указание --output выбирает формат изображения; --format image также явно его выбирает. Захват не изменяет область просмотра редактора или проект. Ответы включают идентификаторы клипов и временные метки вместе с пиксельными границами.
По умолчанию изображения имеют ширину 1280 пикселей, а высота подгоняется под используемые дорожки. Используйте --width, --height или --all-tracks для настройки макета, а --track-size или --track-label-width для настройки дорожек и меток. Диапазон начала/конца определяет масштаб; --pixels-per-second вместо этого вычисляет ширину из временного диапазона.
Просмотр аудиоформ волн
Выберите --mode waveforms для просмотра аудиоконтуров на временной шкале:
openshot-cli timeline view --start 5 --end 12 --mode waveforms --output /tmp/waves.png
--mode auto использует существующее кэшированное отображение формы волны; --mode thumbnails вместо этого показывает миниатюры. Формы волн отображают пиковые/RMS уровни источника с учетом громкости клипа и временных настроек, до применения аудиоэффектов или микширования.
Извлечение формы волны без кэша декодирует целые источники, ограниченные 600 секундами на источник и 1200 секунд-источников на запрос. Сужение видимого диапазона не уменьшает объем декодирования. Для более длинных источников сначала создайте формы волн в редакторе или используйте режим миниатюр. Последующие запросы могут повторно использовать кэшированные формы волн.
Вывод изображений и ограничения
Пути к изображениям должны указывать на новые PNG-файлы в существующих каталогах. Изображения ограничены 4096 пикселями по каждой оси, 8 388 608 общими пикселями и 64 образцами контактных листов. Запросы, превышающие эти ограничения, завершаются с ошибкой до рендеринга.
Изображения записываются в файлы; JSON-ответы включают их пути и размеры image_bytes. Проверка ожидает завершения создания изображения, и большие запросы могут временно занять редактор.
Обработка таймаутов команд
Таймаут запроса не означает, что изменение не удалось. Используйте идентификатор операции из ошибки с командой operation get ID перед повторной попыткой. operation list показывает недавние изменения и их состояния, ревизии и результаты. Завершённые операции сохраняют результаты, если они достаточно малы, включая возвращённые идентификаторы объектов. Хранилище ограничено 100 операциями и 4 МиБ, при этом отдельные тела результатов пропускаются при размере более 256 КиБ. Эти записи сохраняются только в течение текущей сессии. Они не восстанавливают проекты после сбоя и не предотвращают повторное применение одной и той же правки при повторной команде. Экспортные задания имеют собственные команды статуса/списка.