# Cutr

> Explains and uses cutr, a minimal Kdenlive-as-code DSL that compiles video timelines to ffmpeg. Use when editing .cutr files, validating cutr projects, generating ffmpeg/render commands, or explaining how cutr's timeline, assets, filters, transitions, audio, subtitles, and output options work.

- Skill: `luisfer-cli/cutr` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add luisfer-cli/cutr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luisfer-cli/cutr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: luisfer-cli (https://skillmd.com/u/luisfer-cli)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/luisfer-cli/cutr

---


# cutr

Use this skill when the user works with `cutr` or `.cutr` timeline files.

## What cutr is

`cutr` is a tiny video DSL: one line per timeline item, `key=value` options, compiled to an `ffmpeg` command.

Basic flow:

1. Declare reusable inputs with `asset id=... path=...`.
2. Add timeline items: `video`, `image`, `gif`, `audio`, `text`, `subtitle`, `concat`.
3. Set final export with `output ...`.
4. Run `cutr check`, `cutr ffmpeg`, or `cutr render`.

## Commands

```bash
cargo run -- check proyecto.cutr
cargo run -- ffmpeg proyecto.cutr
cargo run -- render proyecto.cutr --from 10 --to 20
cargo run -- ffmpeg proyecto.cutr --preview
cargo run -- proyecto.cutr
```

Use `ffmpeg` mode first when debugging; it prints the generated command without rendering.

## Minimal file

```cutr
asset id=clip path=video.mp4

video asset=clip at=0 duration=5
text text="Hola" at=1 duration=2 align=center y=80 size=56 color=white

output path=out.mp4 duration=5 size=1920x1080 fps=30 preset=youtube
```

## Timeline model

- `at` places an item on the timeline.
- `from`, `to`, `duration` trim or bound input/time.
- Items layer by `track` or `z_index`; higher values render later/on top.
- `x/y`, `anchor_x/anchor_y`, `scale`, `rotate`, `opacity` control overlay placement.
- `*_kf` values are keyframes: `time:value[:linear|ease-in|ease-out]|...`.

## Common features

Video/image/GIF:

```cutr
video asset=clip at=0 from=2 duration=5 track=1 \
  x_kf=0:0|2:400:ease-out y=0 scale_kf=0:1|2:1.2 \
  fade_in=0.3 fade_out=0.3 transition=slide transition_from=left transition_duration=0.5
```

Audio:

```cutr
audio asset=music at=0 duration=8 volume=0.8 fade_in=1 normalize=true compressor=true
```

Subtitles/text:

```cutr
text text="Mi título" at=1 duration=3 align=center y=80 size=56 color=white outline=2 shadowx=2 shadowy=2
subtitle text="hola mundo" at=4 duration=2 y=900 size=36 outline=2
```

Output:

```cutr
output path=out.mp4 duration=8 size=1920x1080 fps=30 preset=youtube bitrate=8M
```

## Agent rules

- Prefer the smallest valid `.cutr` file that renders the requested result.
- Reuse existing assets by `id`; do not duplicate asset declarations.
- Run `cutr check` before render when possible.
- If render is slow, use `--preview` or `--from/--to`.
- For exact supported keys and edge cases, read `references/cutr-reference.md`.