Project YAML reference

Every key a project file accepts, what it means and its default. For a walk-through instead, see docs/making-a-video.md; for working files, see examples/simple/ and examples/scenes/.

Times are seconds (decimals allowed) unless said otherwise. Colours are [r, g, b, a], 0-255. A key left out takes its default; an unknown key where only known ones make sense (the top level, derive:) is an error, so a typo doesn't go unnoticed there.

project: {...}       # required: canvas, frame rate, where sources come from
bin: [...]           # the files (and titles) the video uses
timeline:
  tracks: [...]      # low level: every clip placed by hand
scenes: [...]        # high level: lists of clips with timing worked out
guides: [...]        # timeline markers
transitions: [...]   # wipe/affine transitions between two tracks
presets: {...}       # named sets of keys, used with use: (below)
presets_file: ...    # a file of presets shared by several projects
parts: [...]         # instead of the rest: the project in several files (below)

timeline: and scenes: can be mixed: scenes compile into extra tracks before anything else runs.

Two more top-level keys are written by the tool itself and only kept, not interpreted: x_kdenlive_raw (what import couldn't map, carried back on build) and x_reconstruct_unmatched (the stretches reconstruct couldn't match, for a person to review).

project:

project.sources:

bin:

A list of entries, each with an id (how the timeline refers to it) and exactly one way to get its file:

Other keys every entry may have:

derive:

Exactly one input:

Then any of these operations, applied in this order:

A gif stays a gif, a still becomes .png, audio .m4a and video .mp4. Outputs are cached in <dir>/.derived/ and regenerated only when the spec or the input changes.

Lottie animations (type: animation)

A .json Lottie animation (LottieFiles' format) or a .tgs one (Telegram's, gzipped) is a bin clip like a video: played by melt's glaxnimate module - kdenlive's "Animation" clips - with its own transparency, so on a track above it plays over what's below; as long as its own frames say (ip to op at fr per second). The distributions' melt has the module; one without it is an error that says so.

Title cards (type: title)

font takes any font installed on the machine that renders (fc-list lists them, e.g. "DejaVu Serif", "Ubuntu"); one it doesn't have is replaced by a default one without warning.

timeline.tracks:

timeline: holds one key, tracks: a list of tracks. Later tracks are stacked above earlier ones: a clip with fade_in on a later track fades in over what plays below it.

Clips on a track

Each is {clip: <bin id>, start: <seconds>, ...}. clip and start are required.

Which part of the source, and for how long

Speed

Fades and sound

Framing

Effects

scenes:

The high-level form: each scene is a list of clips that play one after another, with their timing worked out. Scenes follow each other, starting at second 0.

A scene's clip is a file path (photos/beach.jpg, added to the bin by itself), {path: ...}, or {clip: <bin id>}; the two map forms may also carry mute, speed (with preserve_pitch), position, size, chroma_key, chroma_key_distance, lut (with lut_interp) and melt, as on a timeline clip.

guides:

Timeline markers: [{at: 12.5, text: "Chorus", category: 0}, ...].

transitions:

A transition between two tracks over a time window, written directly (scenes: produces these by itself; import writes them too):

melt: and melt/<service>

For what there's no key of its own for: any filter or transition the melt that renders the project has (melt -query filters, melt -query transitions list them - frei0r's ~100, ffmpeg's as avfilter.*, MLT's own), by its service name.

timeline:
  tracks:
    - type: video
      clips:
        - clip: beach
          start: 0
          duration: 4
          melt:
            - frei0r.cartoon: {diffspace: 0.4}
            - avfilter.hue: {av.h: "0=0;100=180"}   # keyframes, MLT's own syntax
            - frei0r.invert0r                       # no properties
scenes:
  - transition: melt/composite
    transition_properties: {geometry: "0=50%/50%:0%x0%;-1=0/0:100%x100%"}
    clips: [a.jpg, b.jpg]

Each melt: entry becomes one filter on the clip, after those of the clip's own keys, in the order given; a melt/<service> transition goes between the scene's two alternating tracks over each overlap (on transitions:, between track_a and track_b over start-end), with no fade on either clip, as wipe does. Values are written as they are: MLT's own units, ranges (frei0r's parameters go from 0 to 1) and keyframe syntax. A frei0r parameter may be named by its number or by its name (melt -query filter=frei0r.cartoon shows both).

When there's a melt to ask, an unknown service or property is an error (with the closest names) instead of a render that silently does nothing; a service melt doesn't describe takes any property. Opened in kdenlive, a filter it has no description of renders but may not show in its effect stack. import brings any filter over the whole clip and any transition between two tracks that the installed melt has, and that it doesn't otherwise recognize, back as these entries.

transition: gl

The 125 transitions of gl-transitions - a cube turning, doors opening, a page curling, a morph, ripples, a burn... - each a GLSL shader run on the GPU:

scenes:
  - transition: gl
    gl: cube
    gl_params: {persp: 0.5, reflection: 0.2}   # optional
    clips: [a.jpg, b.jpg]

video-as-code gallery shows every one playing, with its name; each one's parameters, their types (float, bool, vec2/vec3/vec4 as lists of numbers, ivec2 as whole numbers) and ranges are in src/video_as_code/gltransitions_data/catalog.json, and a wrong one is an error that says what it takes.

They need a small plugin built once: video-as-code install-gl-transitions (a C compiler and the EGL, GLES and frei0r headers - libegl-dev, libgles-dev, frei0r-plugins-dev on Debian/Ubuntu). In the .kdenlive they're a frei0r.gltransition transition, which kdenlive renders as long as its melt finds the plugin (FREI0R_PATH). A machine with no GPU renders them on the CPU (Mesa's llvmpipe), more slowly.

presets:, presets_file: and use:

Named sets of keys, written once and used wherever a project file has a map - a scene, a clip (on a track or in a scene), a bin entry, a transitions: entry:

presets:
  page: {transition: gl, gl: BookFlip, transition_duration: 0.8}
  warm: {lut: looks/warm.cube, film_grain: {noise: 12}}
  warm-page: {use: [page, warm]}          # a preset may use others

scenes:
  - use: page
    clips: [a.jpg, {path: b.jpg, use: warm}]
  - use: page
    transition_duration: 1.5               # written here: wins over the preset's
    clips: [c.jpg, d.jpg]

use: is expanded before anything else reads the file, so it works with every key. A name that isn't a preset, or presets that use each other in a circle, is an error that says where. Relative paths inside a preset (a lut:, a path:) are relative to the project file that uses it, like the rest of that file's: a presets file shared by projects in other folders takes absolute paths.

# presets.yaml, next to several projects' files
presets:
  page: {transition: gl, gl: BookFlip}
  title-style: {font: "DejaVu Serif", font_weight: bold, shadow: true}

# a project
project: {...}
presets_file: presets.yaml
bin:
  - {id: card, type: title, text: "Day one", use: title-style}

parts: - a project in several files

The main file has project: and, instead of bin:/scenes:/timeline:, a list of parts, each a file of its own; a part may list parts in turn:

# trip.yaml
project: {id: trip, title: Trip, fps: 25, width: 1920, height: 1080}
presets_file: presets.yaml
parts:
  - intro.yaml
  - beach.yaml
  - {file: mountains/all.yaml, transition: gl, gl: cube, transition_duration: 1.2}

# beach.yaml - a part: no project:, the rest as in any project file
bin:
  - {id: wave, path: media/wave.mp4}
scenes:
  - use: page
    clips: [{clip: wave}, media/sand.jpg]

• Each part is a sequence of its own in the .kdenlive - kdenlive's nested sequences, named after the part's file - placed in the one that lists it; the main file's is the timeline kdenlive opens.
• A part has no project:: it takes the main file's. Its relative paths are its own folder's, so a part can be moved with its media.
• A part's bin ids are its own: two parts may both have a clip a.
• Presets: the main file's (and its presets_file:) are in force in every part; a part's own add to them for itself and the parts it lists.
• A part that lists itself, through any number of others, is an error that shows the chain.
• --part <path> (on build, render, validate) takes one part alone: its file's path from the main file's folder, without .yaml (--part mountains/all); the output is named after both (trip-mountains-all.mp4).
• fetch (and --fetch) goes through the parts one by one, each in its own folder - its own sources.lock.yaml, its own downloads - and a fix asked for in the terminal is written into the part's file, where the clip is. Old files are pruned before a render in each part's folder; not with --part, whose render doesn't read the other parts' files.
• --proxy makes each part's light copies in that part's own .proxies/; --split cuts segments on the whole timeline, a part's clips counted where the part plays.
• import of a .kdenlive whose timeline is parts in turn (the shape a build gives it: sequences placed whole, each once, one after the other or overlapping by a transition it knows) writes the main file with parts: and a file per part, named after its sequence and next to the main one, its paths absolute. Nested sequences in any other shape stay in x_kdenlive_raw.

glsl: shaders

glsl: on a clip runs a GLSL ES 3.00 shader over its picture on the GPU, through a small plugin built once with video-as-code install-gl-transitions (the one transition: gl uses has this sibling).

A shader of your own is a .glsl file with vec4 effect(vec2 uv): it reads the picture with getColor(uv) (uv from 0 to 1, origin bottom left) and has time (seconds into the clip), progress (0 to 1 over it), ratio (width / height) and resolution (in pixels); its own uniforms get the values in params (numbers, true/false, lists of 2-4 numbers for vec2-vec4) - one not given is 0.

// warm.glsl
uniform float amount;
vec4 effect(vec2 uv) {
  vec4 c = getColor(uv);
  return vec4(c.r + amount, c.g, c.b - amount, 1.0);
}

- {clip: beach, start: 0, duration: 4, glsl: {shader: looks/warm.glsl, params: {amount: 0.1}}}