Video Timeline Editor

Use this skill when a project needs a clean editing layer between raw clips and a final render.

The goal is not to mimic Premiere's UI. The goal is a small, agent-friendly timeline DSL that can be edited safely in code.

What This Skill Gives You

• a reusable FFmpeg timeline engine at scripts/video_timeline.py
• a declarative timeline format that agents can rewrite without touching engine internals
• deterministic edits for:
• source in/out cuts
• trim from left/right edges
• clip-bound transcript tracks with real word timestamps
• word-aware trimming when transcript data exists
• speed changes
• normalized crop boxes
• cover or contain framing for vertical/horizontal outputs
• simple text overlays
• karaoke-style burned captions generated from clip transcripts
• stable concat rendering

Workflow

1. Create a dedicated working folder for the video project anywhere you keep project media.
2. Put the source clips, transcript JSON files, and final outputs inside that project folder.
3. Create the timeline file inside that same project folder.
4. Use references/timeline-template.py as a starting point, then adapt the structure to the project.
5. Run a dry pass first:

python3 skills/video-timeline-editor/scripts/video_timeline.py \
  --timeline /path/to/timeline.py \
  --dry

1. Render when timings look right:

python3 skills/video-timeline-editor/scripts/video_timeline.py \
  --timeline /path/to/timeline.py

If you prefer uv, run the packaged command from the skill folder:

uv run --project /path/to/video-timeline-editor video-timeline \
  --timeline /path/to/timeline.py \
  --dry

If you prefer uvx, run it directly from the skill folder:

uvx --from /path/to/video-timeline-editor video-timeline \
  --timeline /path/to/timeline.py

Suggested Project Layout

Create one folder per video project. The exact folder name is up to the agent or user.

Example:

my-video-project/
├── timeline.py
├── clips/
│   ├── hook.mp4
│   └── response.mp4
├── transcripts/
│   ├── hook.elevenlabs.transcript.json
│   └── response.elevenlabs.transcript.json
└── final/
    ├── timeline-render/
    └── edit.mp4

Use that as a working pattern, not a strict rule. The important part is:

• timeline file lives in the project folder
• source media lives in the project folder
• transcript JSON files live in the project folder
• outputs and temporary renders live in the project folder

Timeline Authoring Rules

• Keep the engine in the skill. Put project-specific edits in the project's own timeline file.
• Prefer take=(start, end) plus trim=(left, right) instead of hand-editing FFmpeg args.
• Attach transcript JSON directly on the clip with captions(...).
• Use trim="word" when the cut should snap to the nearest full spoken words.
• Use trim="free" when picture timing matters more than word boundaries; caption timings will still be recalculated against the final clip.
• Use cover(anchor="center") for shorts when the source aspect ratio does not match the target frame.
• Use crop_box(x, y, width, height) before fit when you need a specific region of the source.
• Put reusable hacks such as anti-content-ID transforms into named presets with transform(...).
• Keep STT generation separate from this engine. This skill assumes transcript JSON already exists and turns it into clip-local captions.

Requirements

• ffmpeg
• ffprobe
• python3

Files

• scripts/video_timeline.py: reusable engine + CLI
• pyproject.toml: package entrypoint for uv run and uvx
• references/timeline-template.py: minimal project template