1---
2name: video-timeline-editor
3description: Build or revise a reusable FFmpeg timeline for short-form video editing. Use when the user wants an agent-editable API for trimming clips, cropping, fitting to frame, changing speed, adding simple text overlays, and assembling a deterministic final video from existing media.
4---
5 
6# Video Timeline Editor
7 
8Use this skill when a project needs a clean editing layer between raw clips and a final render.
9 
10The goal is not to mimic Premiere's UI. The goal is a small, agent-friendly timeline DSL that can be edited safely in code.
11 
12## What This Skill Gives You
13 
14- a reusable FFmpeg timeline engine at `scripts/video_timeline.py`
15- a declarative timeline format that agents can rewrite without touching engine internals
16- deterministic edits for:
17  - source in/out cuts
18  - trim from left/right edges
19  - clip-bound transcript tracks with real word timestamps
20  - word-aware trimming when transcript data exists
21  - speed changes
22  - normalized crop boxes
23  - `cover` or `contain` framing for vertical/horizontal outputs
24  - simple text overlays
25  - karaoke-style burned captions generated from clip transcripts
26  - stable concat rendering
27 
28## Workflow
29 
301. Create a dedicated working folder for the video project anywhere you keep project media.
312. Put the source clips, transcript JSON files, and final outputs inside that project folder.
323. Create the timeline file inside that same project folder.
334. Use `references/timeline-template.py` as a starting point, then adapt the structure to the project.
345. Run a dry pass first:
35 
36```bash
37python3 skills/video-timeline-editor/scripts/video_timeline.py \
38  --timeline /path/to/timeline.py \
39  --dry
40```
41 
426. Render when timings look right:
43 
44```bash
45python3 skills/video-timeline-editor/scripts/video_timeline.py \
46  --timeline /path/to/timeline.py
47```
48 
49If you prefer `uv`, run the packaged command from the skill folder:
50 
51```bash
52uv run --project /path/to/video-timeline-editor video-timeline \
53  --timeline /path/to/timeline.py \
54  --dry
55```
56 
57If you prefer `uvx`, run it directly from the skill folder:
58 
59```bash
60uvx --from /path/to/video-timeline-editor video-timeline \
61  --timeline /path/to/timeline.py
62```
63 
64## Suggested Project Layout
65 
66Create one folder per video project. The exact folder name is up to the agent or user.
67 
68Example:
69 
70```text
71my-video-project/
72├── timeline.py
73├── clips/
74│   ├── hook.mp4
75│   └── response.mp4
76├── transcripts/
77│   ├── hook.elevenlabs.transcript.json
78│   └── response.elevenlabs.transcript.json
79└── final/
80    ├── timeline-render/
81    └── edit.mp4
82```
83 
84Use that as a working pattern, not a strict rule. The important part is:
85 
86- timeline file lives in the project folder
87- source media lives in the project folder
88- transcript JSON files live in the project folder
89- outputs and temporary renders live in the project folder
90 
91## Timeline Authoring Rules
92 
93- Keep the engine in the skill. Put project-specific edits in the project's own timeline file.
94- Prefer `take=(start, end)` plus `trim=(left, right)` instead of hand-editing FFmpeg args.
95- Attach transcript JSON directly on the clip with `captions(...)`.
96- Use `trim="word"` when the cut should snap to the nearest full spoken words.
97- Use `trim="free"` when picture timing matters more than word boundaries; caption timings will still be recalculated against the final clip.
98- Use `cover(anchor="center")` for shorts when the source aspect ratio does not match the target frame.
99- Use `crop_box(x, y, width, height)` before fit when you need a specific region of the source.
100- Put reusable hacks such as anti-content-ID transforms into named presets with `transform(...)`.
101- Keep STT generation separate from this engine. This skill assumes transcript JSON already exists and turns it into clip-local captions.
102 
103## Requirements
104 
105- `ffmpeg`
106- `ffprobe`
107- `python3`
108 
109## Files
110 
111- `scripts/video_timeline.py`: reusable engine + CLI
112- `pyproject.toml`: package entrypoint for `uv run` and `uvx`
113- `references/timeline-template.py`: minimal project template
114