README.md
video-editor-tools
CPU-only command-line toolkit for an AI video editor (built for a Grok Bot agent, usable by any agent or human on Ubuntu/Debian). It covers talking-head clean-up, creator-style research, HyperFrames motion graphics, graphics behind the speaker, sound design and delivery. Everything runs on a box without a GPU. No keys, media or model weights ship in this repo.
Get your own keys
This is an opinionated kit and it ships with no credentials. Whoever uses it signs up for each service themselves and creates their own accounts and keys. Nothing is shared or preconfigured.
- Context.dev (https://www.context.dev/signup): pulls brand assets (logos, colours, fonts) from a domain. In Grok Bot, connect the Context.dev connector.
- VideoDatabase (https://videodatabase.io/signup, setup guide https://videodatabase.io/mcp/install): reference clips and editing briefs. Add a custom MCP connector with URL
https://videodatabase.io/mcpand your own bearer token from VideoDatabase Profile Settings. - CloudConvert (https://cloudconvert.com, keys at https://cloudconvert.com/dashboard/api/v2/keys): optional and paid per conversion. Env var
CLOUDCONVERT_API_KEY. - Pexels (https://www.pexels.com/api/), Pixabay (https://pixabay.com/api/docs/), Coverr (https://coverr.co/developers): optional stock B-roll. Env vars
PEXELS_API_KEY,PIXABAY_API_KEY,COVERR_API_KEY. - Google Drive and Notion: connect your own accounts in Grok Bot.
- HyperFrames, ffmpeg, HandBrake, yt-dlp, DeepFilterNet, etc.: free and local, installed by
install.sh. No keys needed.
Keys go in environment variables. In Grok Bot, enter them through its secure secret prompt. Never paste a key into chat or commit it to a repo.
Install (anonymous, no account needed)
| 1 | git clone https://git.cafe/done/video-editor-tools /workspace/video-editor-tools && bash /workspace/video-editor-tools/install.sh |
install.sh is idempotent (re-run any time), uses sudo apt-get for system packages when available, and installs everything else under /workspace/video-editor-tools (VET_HOME). Then:
| 1 | source ~/.bashrc # adds $VET_HOME/bin and the venv to PATH |
| 2 | hyperframes doctor |
| 3 | $VET_HOME/tools/smoke_test.sh # 5 s HyperFrames render + the audio chain on a sample |
What's inside
| Path | What |
|---|---|
tools/research/taste.py (+ analyze.py, normcuts.py) | taste scorer: pauses (landing vs thinking), fillers, stumbles, wpm per 15 s, jump cuts, hook timeline, you/I % |
tools/qa/cutstats.py | cut-rate stats for any render (first 5 s, 0-30 s, body cuts/min) |
tools/audio/ | audio_chain.sh (MelBand-Roformer dereverb -> DeepFilterNet3 -> -14 LUFS), voice_master.py, sfx_synth.py, bed/gap/kit checks |
tools/motion/ | HyperFrames helpers: offline vendoring, QA gate, filler removal, audio prep, b-roll grade |
tools/behind-speaker/ | plate -> RVM matte -> behind-speaker cards/bars/arrows -> composite + HandBrake web copy |
tools/screen/ | scroll tracking and redaction for screen recordings |
hf-templates/ | parameterised HyperFrames templates (build.py + params.json) |
hyperframes-blocks/ | drop-in HyperFrames compositions (captions, lower thirds, follow cards, transitions) |
luts/ | luxe-noir-33.cube (CC0, generated by make_luxe_lut.py) |
fonts/ | fonts.css + FONTS.md; the OFL font files are downloaded by install.sh |
See tools/README.md for every script.
The stack: what each piece does and where to get it
Local tools (installed by install.sh):
| Tool | Used for | Link |
|---|---|---|
| HyperFrames | HTML-to-video motion graphics: captions, lower thirds, end cards, templates, 3D plates | https://hyperframes.heygen.com , https://github.com/heygen-com/hyperframes |
| ffmpeg | every cut, grade, mix, loudness pass and master | https://ffmpeg.org/download.html |
| HandBrakeCLI | small web/Drive delivery copies (-e x264 -q 23 --encoder-preset medium -E copy:aac --optimize --crop 0:0:0:0; the --crop 0:0:0:0 stops HandBrake auto-cropping your frame) | https://handbrake.fr/docs/en/latest/cli/cli-options.html |
| audio-separator + MelBand-Roformer (anvuew mono dereverb) | removes room reverb from dialogue | https://github.com/nomadkaraoke/python-audio-separator , https://huggingface.co/anvuew/dereverb_mel_band_roformer |
| DeepFilterNet3 | residual noise removal after dereverb (-a 12 -D) | https://github.com/Rikorose/DeepFilterNet |
| Robust Video Matting | CPU person matte for graphics behind the speaker | https://github.com/PeterL1n/RobustVideoMatting |
| Node.js 22 | runs HyperFrames (installed next to any older system Node) | https://nodejs.org |
| yt-dlp | downloads reference videos and their subtitles (word-timed VTT) for creator breakdowns and transcripts | https://github.com/yt-dlp/yt-dlp |
Optional add-ons (not installed by install.sh):
| Tool | Used for | Link |
|---|---|---|
| faster-whisper | local transcription when a video has no captions (.venv/bin/pip install faster-whisper) | https://github.com/SYSTRAN/faster-whisper |
| whisper.cpp | HyperFrames' own hyperframes transcribe for word-timed captions | https://github.com/ggml-org/whisper.cpp |
Services (bring your own account and key; nothing is preconfigured):
| Service | Used for | Sign up / install | How to connect |
|---|---|---|---|
| CloudConvert | conversions local tools handle badly: ProRes/MOV deliverables, GIFs, unusual audio formats, documents and images. Paid per conversion, so local ffmpeg/HandBrake come first | https://cloudconvert.com , CLI: https://github.com/cloudconvert/cloudconvert-cli (npm i -g cloudconvert-cli) | create a key at https://cloudconvert.com/dashboard/api/v2/keys and store it as the secret CLOUDCONVERT_API_KEY; test with --sandbox |
| VideoDatabase | reference library of analysed short-form videos: search proven hooks/formats and read a video's "Video DNA" before planning an edit | https://videodatabase.io/signup , MCP guide: https://videodatabase.io/mcp/install | add a custom MCP connector with URL https://videodatabase.io/mcp and header Authorization: Bearer <your scoped token> (create the token in VideoDatabase Profile Settings). Generation tools spend your account's AI budget |
| Context.dev | pulls a brand's logos, colours, fonts and social links from its domain so lower thirds and end cards match the brand | https://www.context.dev/signup , MCP guide: https://docs.context.dev/install-mcp.md | add a custom MCP connector with URL https://mcp.context.dev/mcp and sign in (OAuth), or use your own API key as CONTEXT_DEV_API_KEY |
| Google Drive | delivery: finished videos are uploaded to a folder you choose and the link is shared | https://www.google.com/drive/ | Grok Bot Google Drive connector |
| Notion (optional) | an editing-queue board (idea -> edit -> review -> delivered) with links to each finished video | https://www.notion.com | Grok Bot Notion connector |
Optional stock-footage keys (only if you have them): PEXELS_API_KEY, PIXABAY_API_KEY, COVERR_API_KEY.
Licenses
Our code: MIT (see LICENSE). Robust Video Matting is GPL-3.0 and is downloaded separately from its official release; it is not part of this repo. HyperFrames registry blocks are Apache-2.0. Fonts are SIL OFL 1.1. Sound sources and every downloaded component are listed in THIRD_PARTY.md.