Create a brand new Kdenlive project session.

After this call the project path is stored so subsequent tools automatically target this project.

Args: output_path: Path where the project JSON will be saved (.kdenlive-cli.json). profile: Preset profile (hd1080p30, hd1080p25, hd720p60, 4k30, 4k60, sd_pal, sd_ntsc). Overrides width/height/fps if set. name: Human-readable project name. width: Video width in pixels (ignored when profile is set). height: Video height in pixels (ignored when profile is set). fps_num: FPS numerator (ignored when profile is set). fps_den: FPS denominator (ignored when profile is set).

Load an existing .kdenlive-cli.json project into the session.

Args: project_path: Path to an existing project file.

Persist the current project state to a file.

Args: output_path: Optional path to write to. Defaults to the original project path.

Return project metadata: FPS, resolution, track layout, bin clip count.

Enumerate all available video output profiles (hd1080p30, 4k60, sd_pal, etc.).

Get the current project's video profile (resolution, FPS, aspect ratio).

Set or update the project's video profile.

Args: profile: Preset profile name (hd1080p30, hd1080p25, hd720p60, 4k30, 4k60, sd_pal, sd_ntsc). Overrides width/height/fps if set. width: Video width in pixels. height: Video height in pixels. fps_num: FPS numerator. fps_den: FPS denominator. progressive: Whether video is progressive. dar_num: Display aspect ratio numerator. dar_den: Display aspect ratio denominator.

Ingest a media file into the project bin for later timeline use.

Args: clip_path: Path to the media file (video, audio, or image). name: Optional display name. Defaults to the filename. duration: Optional duration override in seconds (useful for images). If None, auto-probed via ffprobe. clip_type: Media type hint: video, audio, image, color, title.

Delete a clip from the media bin by its ID.

Args: clip_id: The clip identifier from bin_list_clips or bin_import_clip.

List every asset in the project bin with ID, name, type, and duration.

Get detailed properties of a bin clip (length, aspect ratio, media info).

Args: clip_id: The clip identifier from the bin.

Append a video or audio track to the timeline.

Args: track_type: 'video' or 'audio'. track_name: Optional name (auto-generated if omitted). mute: Start muted. hide: Start hidden. locked: Prevent edits on this track.

Delete a track and all its clips from the timeline.

Args: track_id: Numeric track identifier (from timeline_list).

Place a bin clip onto a specific track at a given time position.

Args: clip_id: Bin clip identifier to place (from bin_list_clips). track: Target track number. position: Start time on the timeline in seconds. in_point: Media trim-in (where to start playback inside source) in seconds. out_point: Media trim-out (where to end playback inside source) in seconds. Defaults to full bin duration. Use timeline_trim_clip to adjust after placement.

Reposition a clip on the same track to a new time position.

Args: track_id: Track containing the clip. clip_index: 0-based index of the clip within the track. new_position: New timeline position in seconds.

Adjust the in/out trim handles of a timeline clip (not the crop filter).

Args: track_id: Track containing the clip. clip_index: 0-based index of the clip within the track. in_point: New trim-in in seconds. None = leave unchanged. out_point: New trim-out in seconds. None = leave unchanged.

Cut a clip into two independent pieces at a precise time offset.

Args: track_id: Track containing the clip. clip_index: 0-based index of the clip within the track. offset: Time offset in seconds from the clip's start (0 < offset < clip duration).

Delete a clip from the timeline.

Args: track_id: Track containing the clip. clip_index: 0-based index of the clip within the track.

Return all timeline tracks with clip counts, IDs, mute/lock status.

Attach a video/audio effect to a timeline clip.

Args: track_id: Track containing the clip. clip_index: 0-based clip index on that track. filter_type: Filter name (e.g. blur, brightness, frei0r.opacity, volume). Run filter_list_available for all options. params: 'key=value' parameter strings (e.g. ['radius=5.0', 'opacity=0.8']).

Detach an effect from a clip.

Args: track_id: Track containing the clip. clip_index: 0-based clip index. filter_index: 0-based filter index (see filter_list).

Update a single parameter on an active filter.

Args: track_id: Track containing the clip. clip_index: 0-based clip index. filter_index: 0-based filter index. parameter: Parameter name (e.g. radius, opacity, level). value: New value (auto-converted to int/float if numeric).

List all active filters on a specific timeline clip.

Args: track_id: Track containing the clip. clip_index: 0-based clip index.

Discover all filters the Kdenlive runtime exposes.

Args: category: Optional category filter (e.g. blur, color, audio).

Create a blend transition (crossfade, wipe, etc.) between two track layers.

Args: transition_type: Transition name (e.g. crossfade, luma, mix). track_a: Upper track index. track_b: Lower track index. position: Start time on the timeline in seconds. duration: Transition length in seconds. params: 'key=value' parameter strings.

Delete a transition by its numeric ID.

Args: transition_id: Transition identifier.

Modify a parameter on an existing transition.

Args: transition_id: Transition identifier. param_name: Parameter name. value: New value (auto-converted to numeric if applicable).

List all transitions on the timeline.

Place a navigation guide marker along the timeline.

Args: position: Time position in seconds. label: Short label for the guide. guide_type: 'default', 'chapter', or 'segment'. comment: Optional longer description.

Delete a guide marker by its ID.

Args: guide_id: Numeric guide identifier.

Return all guide markers on the timeline.

Generate Kdenlive/MLT XML for the current project.

Args: output_path: Optional file path to write the XML to (e.g. ~/Downloads/myproj.kdenlive). If None, no file is written and XML is returned in data.xml for you to copy.

List all available render presets for final video output.

Render the project to a video file via melt.

Generates MLT XML from the current project then pipes it through melt. Requires 'melt' on the system (apt install melt).

Args: output_path: Destination video file (e.g. output.mp4). preset: Optional render preset name (see export_list_presets).

Revert the most recent state change (up to 50 history entries).

Reapply the last undone operation.

Inspect session state: project loaded, modified flag, history depth.

List all undo/redo history entries with descriptions.

Alias for project_list_profiles - get available render presets.

Get timeline clip properties: in/out, duration, speed, opacity, reverse.

Set playback speed of a timeline clip (1.0=normal, 2.0=2x, 0.5=half, negative=reverse).

Reverse playback direction of a timeline clip (toggles).

Set opacity of a timeline clip (0.0 transparent .. 1.0 opaque).

Get detailed info for a single track (including clips).

Rename a track.

Lock/unlock a track.

Hide/show a track (video visibility).

Mute/unmute a track (audio).

Move track up one position (swap with previous).

Move track down one position (swap with next).

Get total timeline duration in seconds (max end time).

Get current playhead position.

Seek playhead to position (seconds).

Get timeline zoom level.

Set timeline zoom level (0.1 .. 10.0).

Get comprehensive timeline info: tracks+clips, duration, position, zoom, guides, markers, profile.

Get single guide by ID.

Update guide properties.

Add timeline or clip marker (markers separate from guides).

List all markers.

Remove marker by ID.

Add job to render queue.

List render queue jobs.

Get render queue status.

Start processing render queue (renders sequentially via melt).

Stop render queue (marks running as stopped).

Undo N steps (granular).

Redo N steps (granular).

Create folder in project bin.

Move clip to folder (or root if folder None).

Rename bin clip.

Set color label for bin clip (hex or named).

Add / update note for bin clip.