Vedit

An open-source AI video editor for content creators. Raw footage in, finished video out.

Features · Installation · Quick start · Fact Reels kit · Commands · How it works · Contributing

---

Overview

Editing a talking-head video takes hours of repetitive work: cutting pauses and filler words, removing bad takes, adding captions, reframing for vertical platforms, balancing audio and making thumbnails.

vedit automates that work. It runs as:

• A command-line tool. One command turns a raw recording into a platform-ready video.
• A Claude Code skill. Claude reads the word-level transcript, looks at frames from the video, and makes editorial decisions: picking the hook, removing tangents, choosing the best moments for Shorts. Then it renders the result.

vedit auto raw.mp4 --preset youtube --formats 9:16 --thumbs

Every edit is stored as a plain JSON file (edl.json, an edit decision list). That makes edits reviewable, repeatable, version-controllable, and easy for both people and AI to change.

Demo: add a GIF or before/after video here (docs/assets/demo.gif)

Features

Editing

• Smart cuts. Removes dead air, filler words (um, uh) and flubbed takes, keeping the final take. Cuts are word-accurate, so a word is never cut in half.
• Jump-cut masking. Alternating punch-in zooms hide cuts in single-camera footage.
• Platform presets. YouTube, Shorts, TikTok, Reels, LinkedIn (square), podcast, tutorial.
• Multi-format export. Render one edit as 16:9, 9:16, 1:1 and 4:5, with face-aware cropping.
• Overlays. Titles, lower thirds, b-roll, picture-in-picture, images, sound effects.
• Motion and color. Ken Burns zoom and pan, speed ramps, fades, color adjustment, 3D LUTs.

Captions

• Animated word-by-word captions (pop, box) or standard subtitles (clean)
• .srt export for upload to YouTube and other platforms
• Custom spelling fixes and caption colors per speaker

Audio

• Voice enhancement (compression and presence EQ) and optional noise reduction
• Background music that ducks automatically under speech
• Loudness normalization to platform targets (EBU R128)

Creator tools

• Brand kit. Fonts, caption colors, logo watermark, intro/outro, music and LUT, applied to every video
• Thumbnails. Scores frames for sharpness, exposure and faces, then builds a 1280×720 thumbnail with a title
• YouTube chapters. Generated from the edit timeline
• Batch processing. Edit a whole folder in one command

Podcasts and multicam

• Camera synchronization by audio cross-correlation
• Active-speaker detection from separate microphones, for automatic camera switching

Story mode

• Turn photos plus a script into a voiced, captioned video or skit
• A different AI voice per character: free edge-tts voices, or OpenAI, ElevenLabs or Piper
• Automatic close-ups on whoever is speaking, scene transitions, titles and sound effects
• Continuous narration: the whole script is voiced in one take and long TTS pauses are tightened, so it flows like a real narrator
• Pronunciation fixes (say): the voice reads a phonetic spelling while the subtitle shows the real one, kept word-for-word in sync
• Motion-graphics cards: flat fact cards are split into elements that pop in, pulse on each line and snap out

Fact Reels kit

• Make fact Reels like Juan Fact a Day from your own raw photos and clips. You bring plain footage and the tool adds the animated cards, narration, word-by-word subtitles, sound effects and music
• Three scene types: card/photo + AI narration, raw B-roll + AI narration, and you talking on camera (your real voice, auto-transcribed into subtitles)
• Your own name and colors from one brand.json; a card background is generated for you
• Step-by-step guide

Requirements

Requirement	Notes
Python 3.9+
FFmpeg	Must include libass (standard builds do)
Optional: NVIDIA GPU	Speeds up transcription automatically
Optional: OPENAI_API_KEY / ELEVENLABS_API_KEY	Premium voices in story mode

Installation

1. Install FFmpeg

winget install Gyan.FFmpeg      # Windows
brew install ffmpeg             # macOS
sudo apt install ffmpeg         # Debian / Ubuntu

2. Install vedit

git clone https://github.com/onetwothird/vedit.git
cd vedit
pip install -e ".[all]"

3. Verify the setup

vedit doctor

Minimal install (no transcription, voices or face detection)

pip install -e .

Optional extras: transcribe (faster-whisper), voices (edge-tts), face (OpenCV), all, dev.

Quick start

Option A: Command line

Put your raw video in a folder and run:

cd path/to/my-video
vedit auto raw.mp4 --preset youtube

The output is written next to the source file:

my-video/
├── raw.mp4                 original (never modified)
├── raw_youtube.mp4         finished video
├── raw_youtube.srt         subtitles
└── raw.edit/               transcript, edit decision list, thumbnails, cache

More examples:

vedit auto raw.mp4 --preset shorts                       # vertical, fast-paced, animated captions
vedit auto *.mp4 --preset tiktok                         # batch a folder
vedit auto raw.mp4 --preset youtube --formats 9:16,1:1   # one edit, three formats
vedit auto raw.mp4 --preset youtube --thumbs             # plus thumbnail candidates
vedit auto raw.mp4 --preset podcast --language tl        # force transcription language

Option B: Claude Code (recommended)

Register vedit as a Claude Code skill:

# macOS / Linux
mkdir -p ~/.claude/skills && ln -s "$(pwd)" ~/.claude/skills/vedit

# Windows (PowerShell, no admin required)
New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null
New-Item -ItemType Junction -Path "$HOME\.claude\skills\vedit" -Target (Get-Location)

Then open Claude Code in your video folder and describe the result you want:

"Edit raw.mp4 into a tight YouTube video. Remove mistakes and slow parts, add captions and chapters, and suggest three titles."

"Create three TikToks from podcast_ep12.mp4, each with a strong hook."

"Make a 30-second skit from these four photos with a different voice for each character."

Claude analyzes the footage, drafts and refines the edit, renders a preview, checks it visually and delivers the final files.

Presets

Preset	Use case	Aspect	Max pause	Captions	Loudness
youtube	Long-form, vlogs	source	0.45 s + punch-ins	clean	−14 LUFS
shorts	YouTube Shorts	9:16	0.28 s	pop	−14 LUFS
tiktok	TikTok	9:16	0.25 s	pop	−14 LUFS
reels	Instagram Reels	9:16	0.28 s	pop	−14 LUFS
square	LinkedIn, feeds	1:1	0.35 s	box	−14 LUFS
podcast	Interviews	source	0.8 s, keeps fillers	clean	−16 LUFS
tutorial	Screen recordings	source	0.5 s, no zoom	clean	−14 LUFS
clean	Dead-air removal only	source	0.45 s	none	−14 LUFS

Run vedit auto --list-presets to see them in the terminal.

Brand kit

Create a brand.json next to your videos, or at ~/.vedit/brand.json to apply it everywhere:

{
  "font": "Montserrat",
  "highlight": "#00E5FF",
  "logo": { "path": "logo.png", "position": "top-right", "scale": 0.12, "opacity": 0.85 },
  "intro": "intro.mp4",
  "outro": "outro.mp4",
  "music": { "path": "bgm.mp3", "volume": 0.12 },
  "lut": "my-look.cube",
  "replace": { "my brand": "MyBrand" }
}

See examples/brand.example.json for every option.

Story mode

vedit story grid  story.json    # gridded photos for choosing focus points
vedit story voices story.json   # synthesize voice lines and review timing
vedit story build story.json    # render the final video

Start from examples/story.example.json. The full schema is in references/story.md.

For a complete real-world series, see juan_fact_a_day/: 60-second Filipino "Alam mo ba?" fact Reels with shared channel settings, a card and cover generator, and one folder per video.

Make fact Reels from your own footage

The Fact Reels starter kit packages the Juan Fact a Day format so anyone can make the same kind of video with their own brand. You supply raw photos and clips with nothing on them, and write one story.json per video. The tool does all the editing.

vedit reels new my_channel                  # copy the kit
vedit reels build my_channel                # builds the example video (makes its own sample footage)
vedit reels story my_channel 002_my_topic   # start your own video: put files in photos/ and clips/
vedit reels build my_channel/stories/002_my_topic

Each scene in story.json is one of:

Scene	You provide	The tool adds
"image" + "card"	text for the card (optionally your photo)	animated card, AI narration, subtitles, sfx
"video" + "lines"	a raw clip (sound not needed)	AI narration over it, card over the footage, subtitles; short clips loop
"video" + "keep_audio": true	a raw clip of you talking	your real voice, auto-transcribed word-by-word subtitles, card for the first seconds

Read the step-by-step guide for installation, branding, every option and troubleshooting.

Command reference

Command	Description
vedit doctor	Check FFmpeg, Python dependencies and voice engines
vedit auto VIDEO… --preset NAME	Full pipeline: analyze → cut → brand → render
vedit analyze VIDEO…	Transcript, silences, scene cuts, loudness, contact sheets
vedit autocut WORKDIR	Generate a draft edl.json
vedit render EDL	Render an edit (--preview, --formats, --clips)
vedit frames VIDEO	Contact sheets for visual review
vedit thumbs VIDEO	Thumbnail candidates and final thumbnail (--title)
vedit captions EDL	Build caption files only
vedit multicam sync|speakers	Multicam synchronization and speaker detection
vedit reframe VIDEO	Subject position for vertical crops
vedit tts "TEXT"	Text-to-speech with word timings
vedit story grid|voices|build	Photo-and-script video creation
vedit reels new|story|build|demo	Fact Reels kit: your photos and clips → branded fact Reels

Run vedit <command> -h for all options.

How it works

             ┌──────────── analyze ────────────┐
raw.mp4 ───▶ │ transcript (word timings)        │ ──▶ autocut ──▶ edl.json ──▶ render ──▶ final.mp4
             │ silences · scenes · loudness     │                  ▲                     + .srt
             │ contact sheets (frames)          │                  │                     + chapters
             └──────────────────────────────────┘                  │                     + thumbnail
                                                     Claude Code / you refine the edit

1. Analyze extracts facts: a word-level transcript (faster-whisper), silences, scene changes, loudness and frame contact sheets.
2. Autocut writes a draft edit decision list from those facts, using the preset and brand kit.
3. Refine. Claude Code (or you) edits edl.json: reorders clips, adds overlays, chapters, and so on.
4. Render encodes each clip into a cached segment, then runs one final pass for captions, overlays and audio. Only changed clips are re-rendered.

The full edl.json schema is documented in references/edl.md.

Project structure

vedit/
├── SKILL.md               Claude Code skill instructions
├── scripts/               Python package (installed as `vedit`)
│   ├── vedit.py           CLI entry point
│   ├── auto.py            one-command pipeline
│   ├── analyze.py         footage analysis
│   ├── transcribe.py      word-level transcription
│   ├── autocut.py         draft edit generation
│   ├── presets.py         platform presets and brand kit
│   ├── edl.py             edit decision list → timeline
│   ├── render.py          FFmpeg renderer with caching
│   ├── captions.py        ASS/SRT caption builder
│   ├── thumbs.py          thumbnail generator
│   ├── multicam.py        sync and speaker detection
│   ├── reframe.py         face-aware cropping
│   ├── frames.py          contact sheets
│   ├── tts.py             text-to-speech engines
│   ├── story.py           photo-and-script videos
│   ├── animate_card.py    motion-graphics animation for fact cards (over images or video)
│   ├── reels.py           Fact Reels kit: new / story / build / demo
│   ├── cards.py           fact cards + thumbnails from brand.json
│   ├── brand.py           brand.json loader + generated card background
│   └── sfx.py             royalty-free whoosh / ding / pop generator
├── references/            edl.json and story.json schemas
├── examples/              sample brand kit and story
├── templates/fact_reels/  starter kit to make fact Reels with your own brand and footage
├── juan_fact_a_day/       example series: Filipino fact Reels (see its README)
├── fonts/                 Poppins (SIL Open Font License, see fonts/OFL.txt)
├── docs/                  usage guide
└── tests/                 pytest suite (no models or network required)

Troubleshooting

Problem	Solution
ffmpeg not found	Install FFmpeg and open a new terminal so PATH refreshes
First run is slow	The Whisper model is downloaded once (~500 MB for small). Use --model base on slower machines
Wrong transcription language	Pass --language en (or tl, es, ja, …)
Captions use the wrong font	Set captions.font to an installed font, or add .ttf files to fonts/
Vertical crop misses the subject	pip install opencv-python, or set crop_x per clip (see vedit frames VIDEO --grid)
Render error	The message names the failing clip; the full FFmpeg command is saved in <workdir>/.render_cache/last_final_cmd.txt

See docs/USAGE.md for a step-by-step guide.

Roadmap

• Crossfade and whip transitions
• Automatic b-roll suggestions from the transcript
• Speaker diarization for single-microphone podcasts
• Karaoke and emoji caption styles
• Claude Code plugin marketplace listing
• PyPI release

Contributing

Contributions are welcome. Read CONTRIBUTING.md to get started.

pip install -e ".[all,dev]"
ruff check scripts tests
pytest -q

Acknowledgements

Built on FFmpeg, libass, faster-whisper, edge-tts, OpenCV and NumPy.

License

The code is released under the MIT License. © 2026 Angelito P. Decatoria III

• Fonts in fonts/ are Poppins, under the SIL Open Font License 1.1.
• The Juan Fact a Day name, mascot, logo and artwork in juan_fact_a_day/ are not covered by the MIT License; see juan_fact_a_day/LICENSE.md.