Control Kinoklip from the command line
You will make a project, put a clip on its timeline, cut it and render it, all from a terminal or a script, without opening the window. Every command works on a project file, saves its change into that file, and can print its result as JSON for other programs.
Nothing is sent anywhere: the commands only read and write the files you name.
The idea
kinoklip <command> --option value --option value
kinoklipwith a project name (or nothing) opens the window, as always.kinoklip commandslists the commands.kinoklip commands --jsonlists them with every option, for programs.kinoklip help clip addshows the options of one command.- Add
--jsonto any command to get the result as one line of JSON instead of a sentence. - A command that works returns exit code 0. A command that fails prints the reason on the error output and returns a number above 0 (1: it could not do it; 2: the command line is wrong).
Commands that change a project take --project file.kkproj. Add --output other.kkproj to
keep the original and save the changed copy there.
Make a first cut
kinoklip project new --project demo.kkproj --width 1920 --height 1080 --fps 25
kinoklip media import --project demo.kkproj --file holiday.mp4
kinoklip media list --project demo.kkproj
kinoklip clip add --project demo.kkproj --media holiday.mp4 --source-in 00:00:10:00 --source-out 00:00:20:00
kinoklip clip list --project demo.kkproj
kinoklip clip split --project demo.kkproj --at 00:00:04:00
kinoklip clip trim --project demo.kkproj --clip 3 --edge tail --delta -12
kinoklip render --project demo.kkproj --output demo.mp4
The --clip number comes from clip list (the first clip you add is not always number 1). clip add appends after the last clip on the track. Give --at to put it somewhere else, and
--insert to push later clips to the right instead of covering them. A clip with sound brings
its audio along on the audio track with the same number, linked to the picture.
Times
A time is a number of frames (125) or a timecode (00:00:05:10), counted from the start of
the timeline. A minus sign makes it negative (--delta -8 moves an edge 8 frames earlier).
The commands
| Command | What it does |
|---|---|
version |
Shows the version. |
project new, project info |
Create a project; show its settings, timelines and media. |
media import, media list, media relink |
Add files; list them (and which are offline); find moved files again. |
timeline list, timeline new, timeline select |
List timelines; make an empty one; choose the active one. |
timeline convert-rate |
Change the frame rate of a timeline that already has clips and save the result as a new project file; see below. |
clip list, clip add, clip move, clip trim, clip split, clip delete, clip set |
Look at and edit the clips of a timeline (speed, volume, pan, on or off, name, zoom, position, rotation, opacity, crop with clip set). |
clip stabilize |
Measure the camera movement of a shaky clip and switch Stabilization on (--mode perspective, similarity or translation; --smooth, --strength, --cropping-ratio, --zoom, --camera-lock); --settings-only changes the settings without measuring again. clip set --stabilization off switches it off. See Steady a shaky clip. |
marker add, marker list, marker delete |
Timeline markers. |
transition add, transition set, transition remove |
A dissolve (or an audio cross fade) at the start or end of a clip; change its length, alignment or settings; take it off. |
effect add, effect stack, effect set, effect remove, effect enable |
Put an effect on a clip (--set radius=12), list a clip's effects, change their settings by key (checked against the range the Inspector uses), remove them, switch them on or off (--enabled false). |
title add, title set, generator add |
A text title (--text, --size, --color, --font, --bold, --align) or a generated clip (solid colour, gradient, bars, adjustment clip) at a time (--at), for a length (--duration), on a track (--track V2). |
keyframe set, keyframe list, keyframe delete |
Animate a number of a clip or an effect: keyframe set --clip 3 --param opacity --at 00:00:01:00 --value 100. |
track list, track add, track set |
The tracks and their state; add one; mute, lock, solo, enable or rename one. |
session info, project save |
Which mode the commands run in (see --live below) and which project is open; save the open project (live mode). |
export otio, export edl, import otio |
Exchange a timeline with other editors (see Move a timeline to or from another editor). |
frame export, frame view |
Render one frame of the timeline to a PNG file (--at, --file, --width); frame view hands the picture to a program that can show it (the AI assistant server below). |
transition list, effect list |
The ids of the transitions, effects, generators and titles, for transition add --type; add --id for the settings of one. |
settings export, settings import |
Write all your settings to one file, or read one back (see Move your settings to another computer). settings import can only be run by you at the command line, never with --live. |
log export |
Write the log of that run (system facts, decoders, playback statistics, warnings) to a text file: kinoklip log export --file log.txt (see Send a log file with a bug report). Like settings import it can only be run by you at the command line, never with --live. |
render |
Render to a file with a preset from the Deliver page, for example --preset youtube_1080p; progress is shown on the error output. |
Commands that look at a timeline use the active one. Add --timeline "Name" (or its number
from timeline list) to use another for that one command.
Clips are named by the number in clip list. Tracks are written like on the timeline: V1,
A2. Moving, trimming, splitting and deleting a clip also changes the clips linked to it; add
--unlinked to change only the one you named.
Change the frame rate of a timeline that has clips
The frame rate of a timeline with clips is locked in the window, because clip positions and
keyframes are counted in frames. timeline convert-rate converts them: every clip, keyframe,
marker, fade and transition stays at the same moment in time (a clip edge moves by at most half
a new frame; clips that touched still touch and gaps stay gaps). It always writes a new file,
and refuses to write over an existing one, so your original project is never changed.
kinoklip timeline convert-rate --project "My Film.kkproj" --timeline "Timeline 1" --fps 60 --output "My Film 60fps.kkproj"
--fpsis the new rate:60,29.97,59.94,23.976.--timelineis the timeline name or number; leave it out for the active one.- A timeline that follows the project settings takes the project's frame rate along (the other timelines that follow it must be empty). Otherwise only that timeline changes and keeps its own rate.
- Compound and multicam clips that run at the timeline's old rate are converted with it; add
--with-compounds falseto leave them. - Source in and out points are in time, not frames, so the pictures shown stay the same. Effect settings counted in frames (Motion Trails spacing, Time Window) are converted too.
- A single-file project (
.kinoklip) is not read by the commands: unpack it first (File > Unpack Project) and give the.kkprojit makes.
Run a command in the open window
With Preferences > System > Local Control > Let local tools control Kinoklip (MCP) switched
on (it is off by default), add --live to any command to run it in the Kinoklip window that is
open, on the project open there, instead of on a project file:
kinoklip marker add --at 00:00:10:00 --name Intro --live
You see the change at once and Edit > Undo takes it back (one step per command); --project can
be left out. If no window accepts, the command says so and stops. Only your own user can connect
and nothing is opened on the network. See
Control Kinoklip from an AI assistant for details.
Use it from a script
kinoklip clip list --project demo.kkproj --json
prints
{"ok":true,"result":{"timeline":1,"fps":25,"clips":[{"id":1,"track":"V1","start":0, ...}]}}
and a failure looks like
{"ok":false,"error":{"code":"unknown_clip","message":"no clip with id 9 in this timeline"}}
The code stays the same between versions; the message is for people. The same commands are
the base of kinoklip mcp, which lets an AI assistant control Kinoklip; see
Control Kinoklip from an AI assistant.
If something goes wrong
- "unknown command". Check the spelling with
kinoklip commands. - "project file ... does not exist". The path after
--projectis wrong; commands do not create projects exceptproject new. - "out_of_range" when trimming. The edge cannot move that far: the file has no more picture, the next clip is in the way, or the clip would be shorter than one frame.
- A packed (single-file) project does not open. The commands read ordinary project files only.
- No window opens. That is intended for the commands above; open the window with
kinoklip demo.kkproj.
Found a mistake? Edit this article on GitHub.