edit-reel
Fully autonomous, zero-interaction video editing pipeline for Instagram Reels and TikTok. Designed for high-signal talking-head educational, scientific, tech, financial, and explanatory content across worldwide languages (English, Spanish, Mandarin, Hindi, Arabic, French, Portuguese, German, Japanese). Features the signature 'Paper & Objects' editorial aesthetic: real camera studio footage for conversational hooks, selective MediaPipe AI person cutout onto warm paper canvas (#E2DDD1) during animated explanations, tangible physical objects (hanging cream tags with gold eyelets, 3D coin stacks, dimensional arrows, rounded icon chips), authentic academic notebook cutoffs for peer-reviewed citations, side-by-side comparative parallel coordinate plots, dynamic rolling odometer counters, kinetic subtitles, broadcast vocal mastering (-11.5 LUFS), ambient background music bed (0.045), and keyframe-locked SFX. Delivers the final production reel autonomously with zero mid-process questions. Trigger with /edit-reel or /reel.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 17 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/MMhaidra/edit-reel with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/MMhaidra/edit-reel'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/mmhaidra--edit-reel)HTML
<a href="/listings/mmhaidra--edit-reel"><img src="/api/listings/mmhaidra--edit-reel/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
1. One-Line Universal Install
curl -fsSL https://raw.githubusercontent.com/MMhaidra/edit-reel/main/install.sh | bash
The script configures a virtual environment, installs vision and acoustic alignment dependencies, and symlinks the skill into your agentic IDEs.
2. Manual Setup
git clone https://github.com/MMhaidra/edit-reel.git cd edit-reel python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt # Ensure FFmpeg is available # macOS: brew install ffmpeg # Ubuntu / Debian: sudo apt-get install -y ffmpeg
3. Run Pipeline on Video
python scripts/pipeline.py \ -i ~/Desktop/projects/reels_IG/raw_footage.mp4 \ -s ~/Desktop/projects/reels_IG/script.docx \ -o ~/Desktop/projects/reels_IG/edited_output \ --lang en
4. Preview Scene Stills
python scripts/preview_reel_stills.py /tmp/reel_previews
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 235 lines
- ---
- name: edit-reel
- description: >-
- Fully autonomous, zero-interaction video editing pipeline for Instagram Reels and TikTok.
- Designed for high-signal talking-head educational, scientific, tech, financial, and explanatory content
- across worldwide languages (English, Spanish, Mandarin, Hindi, Arabic, French, Portuguese, German, Japanese).
- Features the signature 'Paper & Objects' editorial aesthetic: real camera studio footage for conversational hooks,
- selective MediaPipe AI person cutout onto warm paper canvas (#E2DDD1) during animated explanations, tangible physical
- objects (hanging cream tags with gold eyelets, 3D coin stacks, dimensional arrows, rounded icon chips), authentic
- academic notebook cutoffs for peer-reviewed citations, side-by-side comparative parallel coordinate plots, dynamic
- rolling odometer counters, kinetic subtitles, broadcast vocal mastering (-11.5 LUFS), ambient background music bed
- (0.045), and keyframe-locked SFX. Delivers the final production reel autonomously with zero mid-process questions.
- Trigger with /edit-reel or /reel.
- ---
- # Reel Auto-Editor: Autonomous Production Pipeline for Instagram Reels
- This skill enables Antigravity to monitor your raw video folder (`~/Desktop/projects/reels_IG/`) and autonomously produce high-engagement, production-ready 9:16 vertical Instagram Reels with zero user interaction during execution.
- ### Content Scope & Language Versatility
- The pipeline supports educational, scientific, academic, macroeconomic, business, coding, and explanatory creators worldwide:
- 1. **Global Languages**: English (`en`), Spanish (`es`), Mandarin Chinese (`zh`), Hindi (`hi`), French (`fr`), Portuguese (`pt`), German (`de`), Japanese (`ja`), Arabic (`ar` - Modern Standard Arabic and regional dialects including Moroccan Darija `ary`).
- 2. **Universal Ground-Truth Policy**: All academic study names, journal titles, and researcher citations are preserved with typographic integrity.
- ---
- ## The Signature "Paper & Objects" Aesthetic (Primary Default)
- Unless `--design glass` is explicitly requested, every pipeline run defaults to (`--design paper`), using an authentic, tactile physical-object visual language:
- ### 1. 3-State Alternating Dynamic Rhythm
- - **State 1 — Real Studio Footage + Typographic Hook Stamp**:
- - Preserves the speaker's authentic camera background during conversational delivery:
- - Opening hook (first 5–12 seconds) with optional minimal editorial header stamp above the head.
- - Natural thought transitions and breathers between visual concepts.
- - Final takeaway and outro.
- - Alternates subtle `1.04x` punch-in camera zooms on alternating sentences for viral eye-tracking retention.
- - Mixed-script captions (`Arial Bold` Arabic + left-to-right `Helvetica Neue` English runs) float cleanly with soft Gaussian drop shadow.
- - **State 2 — 3D Pop-Out Speaker Card on Warm Alabaster Paper (`#F3F0E8`) + Editorial Infographics Above**:
- - Frames the speaker's torso and hand gestures cleanly inside an elevated rounded studio card (`190..890, 1155..1730`, zero chopped wrists or floating hand artifacts) while MediaPipe connected-head segmentation pops the speaker's head smoothly out above the card's top border.
- - Keeps subtle left/right (`190px`) and bottom (`190px`) buffers completely clear of native Reels UI buttons.
- - The upper stage (`y = 156..835`) displays micro-provenance academic eyebrow headers, tactile layered stacks, progressive blush-highlighted Georgia Serif archival excerpts, horizontal benchmark bar charts, label-switch sliders, or paper/notebook objects.
- - **State 3 — Full-Canvas Editorial Infographics (No Speaker)**:
- - Takes over the entire `#F3F0E8` canvas for deep conceptual breakdowns:
- - Side-by-side 2-column contrast layouts (deep charcoal `#141412` vs stacked sand/blush columns).
- - Side-by-side parallel coordinate charts (e.g. Linear Myth vs. Logarithmic Reality) and global comparisons.
- ### 2. Editorial & Tactile Visual Components (`motion_library/paper_objects.py`)
- - **Micro-Provenance Citations & Academic Notebook Cutoffs**: Single-line editorial citations pinned safely at `y=156` alongside classic torn ruled notebook slips with faint blue-gray rules and Scotch tape.
- - **Layered Stack Plates & Callouts**: Staggered tactile plates with strikethrough and terracotta coral (`#CC5A43`) focal transitions.
- - **Archival Serif Quote Sheets**: Off-white Georgia Serif document pages with acoustic-synced coral-blush (`#E8C6BC`) highlighter sweeps.
- - **Benchmark Charts, Sliders & Physical Objects**: Horizontal bar charts with dashed reference lines, horizontal label-switch sliders, hanging cream tags on strings with gold eyelets, 3D coin stacks, and dimensional arrows.
- ---
- ## Autonomous Execution Rules
- - **Zero Mid-Process Questions**: Never pause to ask clarifying questions, solicit confirmation, or request manual inputs during editing. Start immediately and execute all steps end-to-end.
- - **Auto Language Determination**:
- - If `/edit-reel <lang>` or `/reel <lang>` is given, use that language code (e.g. `en`, `es`, `zh`, `hi`, `ar`, `fr`, `pt`, `de`, `ja`, `darija`).
- - If triggered without language, default directly to `en`.
- - **Reference Script Ground-Truth Workflow**:
- - **Auto-Discovery**: Ingests companion script files (`<video_stem>.txt`, `.md`, `.docx`, `script.txt`) as ground-truth for subtitles, equations, and technical spelling.
- - **Script-Guided Forced Alignment**: Aligns exact script words to acoustic timestamps via time-constrained monotonic anchors.
- - **Intelligent Silence, Stumble & Repeated-Word Cutter (`detect_cuts.py`)**:
- - Uses `faster-whisper` (`word_timestamps=True`) to protect every valid spoken syllable.
- - Excises stumbles, false starts, and repeated takes.
- - **Anti-Arm-Reach Cutoff**: Identifies the calm frame after the last spoken word and stops cleanly before the speaker reaches out to turn off the camera.
- - **Natural Camera Exposure & Skin Tone Grading**:
- - Eliminates over-white highlight blowout from 10-bit Apple HLG / BT.2020 camera footage with gentle gamma compression and selective color balance.
- - Standard SDR tonemapping and reddish-warmth filter chain:
- `scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,eq=gamma=0.85:contrast=0.95:brightness=-0.035:saturation=1.02,colorbalance=rh=0.04:gh=-0.02:bh=-0.03:rm=0.03:gm=-0.01:bm=-0.02:pl=1,unsharp=5:5:0.25:5:5:0.10`
- - Yields rich, healthy, reddish hemoglobin glow (R ~ 124, G ~ 108, B ~ 96) with zero blown-out pixels above 248.
- - **Safe Layout Geometry & Zero-Overlap Guarantee**:
- - Safe mobile Reels/TikTok top margin buffer: `y = 0..158` (leaves room for search bar, camera notch, and audio pills).
- - Reference academic notebook cutoffs strictly anchored at `NOTE_Y_SPEAKER = 230` (`y = 158..302`).
- - Secondary tactile objects, chips, and curve plots placed in `y = 315..620` with zero overlap.
- - Speaker cutout active at `y >= 680..720`.
- - All chip and notebook bounding boxes (`label_chip`, `notebook_cutoff`) auto-expand dynamically with at least 32px safe horizontal padding, mathematically guaranteeing zero text clipping.
- - **Natural Broadcast Audio Mastering & Room Hiss Suppression**:
- - Strict prohibition against heavy FFT spectral noise cancellation (`afftdn=nr=24`) and aggressive downward gates (`agate`), which cause watery phase artifacts and hollow barrel resonance.
- - Clean, transparent broadcast vocal chain with gentle, smooth hiss reduction (`afftdn=nr=10:nf=-52:tn=1:gs=5`) and `lowpass=f=14000`:
- `highpass=f=75,lowpass=f=14000,afftdn=nr=10:nf=-52:tn=1:gs=5,equalizer=f=220:t=q:w=1.0:g=-1.0,equalizer=f=3800:t=q:w=1.0:g=1.5,acompressor=threshold=-18dB:ratio=2.2:attack=15:release=100:makeup=2.0dB,loudnorm=I=-11.5:LRA=6.0:TP=-0.5`
- - Drops room preamp hiss during pauses from -45 dB to -51 dB while preserving full vocal tone and chest resonance mastered to **-11.5 LUFS**.
- - **Background Music**: Warm ambient music bed (`ambient_bed.wav`) low-passed at `850 Hz` at `volume=0.045`.
- - **Keyframe-Locked SFX**: Micro-accents (`0.036..0.048` volume) synchronized to object reveal milestones (`paper_turn.wav`, `cash_chime.wav`, `tech_tick.wav`, `subtle_whoosh.wav`).
- - **Automated Output Naming & Summary Export (`pipeline.py`)**:
- - Automatically exports cleanly titled MP4 filenames (e.g., `Reel_<Title>_<Lang>.mp4`) alongside per-reel `<Video_Stem>_summary_and_titles.txt` and cumulative `reels_summary_and_titles.txt` inside `edited_output/`.
- - **100% Subscription-Free Tooling**:
- - Uses local open-source tools only (`faster-whisper`, MediaPipe, FFmpeg, PIL, `yt-dlp`, `hyperframes`), zero paid cloud APIs or subscriptions.
- ---
- ## Directory Structure
- - **Raw recordings input folder**:
- ```text
- ~/Desktop/projects/reels_IG/
- ```
- - **Motion assets & sound effects**:
- ```text
- ~/.gemini/config/skills/edit-reel/motion_library/sfx/
- ~/.gemini/config/skills/edit-reel/models/selfie_segmenter.tflite
- ```
- - **Processed production reels output folder**:
- ```text
- ~/Desktop/projects/reels_IG/edited_output/
- ```
- ---
- ## Autonomous Execution Commands
- ### Full Pipeline Run (English):
- ```bash
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/pipeline.py \
- --input-folder ~/Desktop/projects/reels_IG \
- --output-dir ~/Desktop/projects/reels_IG/edited_output \
- --lang en
- ```
- ### Full Pipeline Run (Spanish / Arabic / French / German):
- ```bash
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/pipeline.py \
- --input-folder ~/Desktop/projects/reels_IG \
- --output-dir ~/Desktop/projects/reels_IG/edited_output \
- --lang es
- ```
- ### Video with Companion Script:
- ```bash
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/pipeline.py \
- -i ~/Desktop/projects/reels_IG/sample_video.MP4 \
- -s ~/Desktop/projects/reels_IG/script.docx \
- --output-dir ~/Desktop/projects/reels_IG/edited_output \
- --lang en
- ```
- ### Direct Master Renderer (Instant Execution):
- ```bash
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/render_reel.py
- ```
- ### Preview All Scene Stills & Contact Sheet:
- ```bash
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/preview_reel_stills.py /tmp/reel_previews
- ```
- ### Download Reference Media & B-Roll (yt-dlp):
- ```bash
- # Download reference video / viral clip
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/download_ref.py "https://youtube.com/watch?v=..." -n ref_broll
- # Download and trim specific scene
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/download_ref.py "https://youtube.com/watch?v=..." -s 00:01:10 -e 00:01:25 -n broll_clip
- # Download audio only (WAV)
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/download_ref.py "https://..." --audio-only -n reference_audio
- ```
- ### Secondary Design & Framing Options (`--design`, `--speaker-style`, `--subtitle-style`, `--no-hook-stamp`):
- ```bash
- # Default (Editorial Paper + 3D Pop-Out Speaker Card + All Editorial Tricks):
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/pipeline.py \
- -i ~/Desktop/projects/reels_IG/raw_video.MP4 \
- --lang darija
- # Classic Paper Mode (Original warm #E2DDD1 kraft + full torso cutout + bold-stroke captions):
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/pipeline.py \
- -i ~/Desktop/projects/reels_IG/raw_video.MP4 \
- --design classic-paper --subtitle-style bold-stroke
- # Editorial Paper with Classic Cutout Torso (mix & match framing styles):
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/pipeline.py \
- -i ~/Desktop/projects/reels_IG/raw_video.MP4 \
- --design paper --speaker-style cutout --no-hook-stamp
- # Obsidian Glass & HyperFrames Mode (Secondary dark tech studio aesthetic):
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/pipeline.py \
- --input-folder ~/Desktop/projects/reels_IG \
- --output-dir ~/Desktop/projects/reels_IG/edited_output \
- --lang darija \
- --design glass
- # HyperFrames Standalone Card Scaffolding & Rendering:
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/hyperframes_engine.py init stat_card -d 6
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/hyperframes_engine.py render ~/Desktop/projects/reels_IG/motion_hyperframes/stat_card
- ~/.gemini/config/skills/edit-reel/.venv/bin/python3 \
- ~/.gemini/config/skills/edit-reel/scripts/hyperframes_engine.py render ~/Desktop/projects/reels_IG/motion_hyperframes/stat_card --transparent
- ```
- #### Available Options Summary
- - `--design {paper, classic-paper, glass}`:
- - `paper` *(default)*: Warm alabaster `#F3F0E8`, terracotta `#CC5A43` focal accents, `popout` rounded speaker card, micro-provenance eyebrow header, and generic data-driven storytelling templates (`layered_stack`, `quote_excerpt`, `benchmark_bars`, `label_slider`, `two_col_compare`).
- - `classic-paper`: Restores original `#E2DDD1` warm kraft paper, full-body MediaPipe cutout (`cutout`), and torn notebook citations without rounded card frame.
- - `glass`: Dark obsidian studio gradient with frosted HyperFrames glassmorphic cards.
- - `--speaker-style {auto, popout, cutout}`: Switch between **3D Pop-Out Floating Card** (`popout`, protects hand gestures) and **Full Body Cutout** (`cutout`).
- - `--subtitle-style {editorial, bold-stroke}`: Switch between crisp soft-shadow editorial text and classic thick dark outline captions.
- - `--no-hook-stamp`: Disables the State 1 top-of-head opening typographic badge + title stamp.
- ---
- ## Packaging & Sharing this Skill
- The entire self-contained skill is located at:
- ```text
- ~/.gemini/config/skills/edit-reel/
- ```
- To share it with a colleague or transfer to another workstation:
- 1. **Archive the skill directory** (excluding `.venv` and cache):
- ```bash
- tar -czf edit-reel-skill.tar.gz -C ~/.gemini/config/skills/edit-reel --exclude=".venv" --exclude=".reel_cache*" .
- ```
- 2. **On the target machine**, extract into the skills directory:
- ```bash
- mkdir -p ~/.gemini/config/skills/edit-reel
- tar -xzf edit-reel-skill.tar.gz -C ~/.gemini/config/skills/edit-reel
- python3 -m venv ~/.gemini/config/skills/edit-reel/.venv
- ~/.gemini/config/skills/edit-reel/.venv/bin/pip install -r ~/.gemini/config/skills/edit-reel/requirements.txt
- ```
README.md · README · 521 lines · 2 findings marked
- <div align="center">
- # edit-reel: Open-Source AI Video Editor & Auto Subtitles Generator
- ### Autonomous Short-Form Video Editing Agent for Instagram Reels, TikTok, and YouTube Shorts
- **Signature Tactile "Paper and Objects" Motion Graphics Engine for Claude Code, Cursor, Codex, and Google Antigravity**
- <p align="center">
- <b>English</b> |
- <a href="#multilingual-support">Español</a> |
- <a href="#multilingual-support">العربية</a> |
- <a href="#multilingual-support">中文</a> |
- <a href="#multilingual-support">Français</a> |
- <a href="#multilingual-support">Deutsch</a> |
- <a href="#multilingual-support">Português</a> |
- <a href="#multilingual-support">日本語</a>
- </p>
- [](https://github.com/MMhaidra/edit-reel/releases/latest)
- [](https://colab.research.google.com/github/MMhaidra/edit-reel/blob/main/demo.ipynb)
- [](https://github.com/MMhaidra/edit-reel/actions)
- [](https://github.com/MMhaidra/edit-reel#packages)
- [](https://github.com/MMhaidra/edit-reel/stargazers)
- [](https://github.com/MMhaidra/edit-reel/discussions)
- [](https://opensource.org/licenses/MIT)
- [](https://www.python.org/downloads/)
- [](https://developers.google.com/mediapipe)
- [](https://ffmpeg.org/)
- [](https://github.com/MMhaidra/edit-reel)
- [](https://claude.ai)
- [](https://cursor.com)
- [](https://twitter.com/intent/tweet?text=edit-reel%3A%20Autonomous%20Open-Source%20AI%20Video%20Editor%20for%20Reels%2C%20TikTok%20%26%20Shorts!%20Check%20it%20out%3A%20https%3A%2F%2Fgithub.com%2FMMhaidra%2Fedit-reel)
- <p align="center">
- <a href="#try-without-installation-google-colab">Try in Colab</a> |
- <a href="#problem-and-solution">Problem and Solution</a> |
- <a href="#quickstart-30-seconds">Quickstart</a> |
- <a href="#agentic-install">Agentic Install</a> |
- <a href="#feature-matrix">Feature Matrix</a> |
- <a href="#releases">Releases</a> |
- <a href="#packages">Packages</a> |
- <a href="#aesthetic-engine">Aesthetic Engine</a> |
- <a href="#multilingual-support">Multilingual Support</a> |
- <a href="#universal-scene-blueprint">Scene Blueprint</a> |
- <a href="#audio-mastering-suite">Audio Suite</a> |
- <a href="#frequently-asked-questions-faq">FAQ</a> |
- <a href="#star-history">Star History</a>
- </p>
- ---
- </div>
- <p align="center">
- <img src="assets/pipeline_flow.gif" alt="edit-reel Open-Source AI Video Editor and Auto Subtitles Pipeline Flowchart" width="100%" style="border-radius: 12px; box-shadow: 0 8px 30px rgba(0,0,0,0.35);" />
- </p>
- ## Problem and Solution
- **edit-reel** is a free, local-first, **open-source AI video editor** and **auto subtitles generator** built in Python for automated **short-form video production** (Instagram Reels, TikTok, and YouTube Shorts). It operates both as a standalone CLI tool and as a native **AI video editing agent skill** for **Claude Code**, **Cursor**, **Windsurf**, **OpenAI Codex**, and **Google Antigravity**.
- Vertical short-form video commands hundreds of billions of daily views worldwide, yet editing educational, technical, scientific, or business talking-head videos by hand requires hours of manual rotoscoping, silence cutting, keyframing, and audio mastering. Meanwhile, commercial cloud clippers and generic AI video generators produce watermarked videos cluttered with neon subtitle boxes or floating web-cards that look artificial and trigger immediate viewer swipe-away.
- Serving as a local-first, no-watermark **open-source alternative to CapCut, Submagic, Descript, OpusClip, and Veed.io**, **edit-reel** introduces an autonomous, zero-interaction editorial pipeline powered by Faster-Whisper, MediaPipe AI Vision, and FFmpeg using the signature tactile **"Paper and Objects"** aesthetic:
- - **Warm Textured Canvas**: Natural cream paper backdrop (`#E2DDD1`) with organic paper grain.
- - **Tangible Physical Primitives**: Hanging cream price tags with brass eyelets, 3D multi-tier coin stacks, and dimensional arrows.
- - **Dynamic Numerical Odometers**: Smooth rolling counters that visually build up to numerical milestones before stamping a conclusion.
- - **Academic Notebook Cutoffs**: Authentic ruled notebook slips with red margin lines, torn bottom edges, and Scotch tape for peer-reviewed citations.
- - **Parallel Coordinate Plots**: Clear side-by-side comparative graphs (such as Linear Myth vs. Logarithmic Reality).
- - **Speech-Protected Silence Removal & Auto Subtitles**: Millisecond-accurate Whisper word-boundary preservation, automatic filler-word and retake cutting, kinetic word-by-word animated captions, and anti-arm-reach tail cutoff.
- - **Broadcast Audio Mastering**: -11.5 LUFS mastered dialogue with spectral noise suppression, highpass gating, ambient bed ducking, and motion-locked micro-SFX.
- ---
- ## Quickstart (30 Seconds)
- ### 1. One-Line Universal Install
- ```bash
- curl -fsSL https://raw.githubusercontent.com/MMhaidra/edit-reel/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 79 on GitHub
- ```
- The script configures a virtual environment, installs vision and acoustic alignment dependencies, and symlinks the skill into your agentic IDEs.
- ### 2. Manual Setup
- ```bash
- git clone https://github.com/MMhaidra/edit-reel.git
- cd edit-reel
- python3 -m venv .venv
- source .venv/bin/activate
- pip install -r requirements.txt
- # Ensure FFmpeg is available
- # macOS:
- brew install ffmpeg
- # Ubuntu / Debian:
- sudo apt-get install -y ffmpeg
- ```
- ### 3. Run Pipeline on Video
- ```bash
- python scripts/pipeline.py \
- -i ~/Desktop/projects/reels_IG/raw_footage.mp4 \
- -s ~/Desktop/projects/reels_IG/script.docx \
- -o ~/Desktop/projects/reels_IG/edited_output \
- --lang en
- ```
- ### 4. Preview Scene Stills
- ```bash
- python scripts/preview_reel_stills.py /tmp/reel_previews
- ```
- ---
- ## Try Without Installation (Google Colab)
- You can run and test edit-reel entirely in the cloud without installing Python or FFmpeg on your machine:
- [](https://colab.research.google.com/github/MMhaidra/edit-reel/blob/main/demo.ipynb)
- The interactive notebook walks through:
- - Automated Faster-Whisper acoustic extraction
- - MediaPipe person segmentation on warm paper canvas
- - Physical objects rendering (hanging tags, 3D coins, and notebook citations)
- - Broadcast audio mastering preview
- ---
- ## Agentic Install
- edit-reel is natively structured for autonomous AI coding agents:
- ### Install Prompt for AI Agents
- Paste this single line into **Claude Code**, **ChatGPT Desktop**, or **Cursor**:
- ```text
- Install the /edit-reel skill globally from https://github.com/MMhaidra/edit-reel
- ```
- ### Google Antigravity
- The skill is defined in `SKILL.md` and registered at `~/.gemini/config/skills/edit-reel/`.
- Trigger in conversation:
- ```text
- /edit-reel en
- /edit-reel es
- /edit-reel ar
- ```
- Antigravity scans your recordings directory (`~/Desktop/projects/reels_IG/`), matches companion scripts, trims dead air, generates physical graphics, masters audio, and delivers the finished MP4 with zero mid-process interruptions.
- ### Claude Code
- The repository provides [`CLAUDE.md`](CLAUDE.md) for terminal execution:
- ```bash
- claude
- > "Run edit-reel pipeline on my raw video in ~/Desktop/projects/reels_IG"
- ```
- ### Cursor and Windsurf
- The repository includes [`.cursorrules`](.cursorrules) configuring code style, safe margins, and testing commands.
- ---
- ## Feature Matrix
- | Feature | edit-reel (Open-Source) | Commercial Cloud AI Editors (Submagic / Veed / OpusClip) | Manual Video Editing (Premiere / CapCut / DaVinci) |
- |:---|:---:|:---:|:---:|
- | **Zero User Interaction During Run** | Yes (100% Autonomous) | No (requires manual web UI clicks) | No (hours of manual timeline labor) |
- | **Visual Aesthetic** | Tactile Paper and Physical Objects | Neon web-cards / generic templates | Custom (labor-intensive) |
- | **AI Background Removal** | Local MediaPipe AI (`selfie_segmenter`) | Paid cloud chromakey or None | Manual Rotoscoping / Masking |
- | **Auto Subtitles & Kinetic Captions** | Word-level Faster-Whisper forced alignment | Cloud ASR (often drifts on technical terms) | Manual caption correction |
- | **Academic Notebook Citations** | Ruled slips with Scotch tape | Plain text boxes | Manual graphic design |
- | **Rolling Numerical Odometers** | Physics-based ease counters | Static text | After Effects expression rigging |
- | **Speech-Protected Silence Cutting** | Whisper word-level boundary locks | Hard silence decibel cuts | Manual waveform slicing |
- | **Anti-Arm-Reach Cutoff** | Automatic post-speech hold | None (speaker reaches to lens) | Manual clip trimming |
- | **Broadcast Audio Mastering** | -11.5 LUFS vocal chain + ambient bed | Raw microphone audio | Multi-plugin DAW mastering |
- | **Multilingual Support** | 12+ languages (Latin, RTL, CJK) | Limited or paid tier | Dependent on editor |
- | **Cost & Watermarks** | 100% Free, Local-First, No Watermark | Monthly SaaS subscription / Watermarked | Software license + high time cost |
- ---
- ## Releases
- Official production releases and downloadable archives:
- - **Latest Stable Release**: [v1.0.0](https://github.com/MMhaidra/edit-reel/releases/tag/v1.0.0)
- - **Source Code (tar.gz)**: [edit-reel-1.0.0.tar.gz](https://github.com/MMhaidra/edit-reel/archive/refs/tags/v1.0.0.tar.gz)
- - **Source Code (zip)**: [edit-reel-1.0.0.zip](https://github.com/MMhaidra/edit-reel/archive/refs/tags/v1.0.0.zip)
- To download and extract the release:
- ```bash
- curl -fsSL https://github.com/MMhaidra/edit-reel/archive/refs/tags/v1.0.0.tar.gz | tar -xz
- cd edit-reel-1.0.0
- ```
- ---
- ## Packages
- ### Direct Install via pip (GitHub)
- ```bash
- pip install git+https://github.com/MMhaidra/edit-reel.git
- ```
- ### Editable Developer Install
- ```bash
- git clone https://github.com/MMhaidra/edit-reel.git
- cd edit-reel
- pip install -e .
- ```
- After installation, the CLI command `edit-reel` is globally available:
- ```bash
- edit-reel -i raw_video.mp4 -o ./output --lang en
- ```
- ---
- ## Universal Scene Blueprint
- The rendering engine follows an 8-scene editorial blueprint designed to maintain engagement across 45-to-90 second reels:
- | Scene | Editorial Purpose | Visual State | Graphic Primitives | Audio Milestone |
- |:---:|:---|:---:|:---|:---:|
- | **1** | Problem Statement / Direct Hook | Real Camera Studio | 1.04x camera punch-in on alternating sentences | Crisp voice, ambient bed introduction |
- | **2** | Critical Number / Pivot Metric | Lowered Cutout on Paper | Hanging cream tag with string and rolling odometer | Clean pop, cash chime SFX |
- | **3** | Acceleration / Upward Trajectory | Lowered Cutout on Paper | 3D coin stack, dimensional directional arrow | Paper turn SFX |
- | **4** | Comparative Breakdown (Myth vs. Reality) | Full-Screen Infographic | Dual parallel coordinate plots | Subtle whoosh SFX |
- | **5** | Empirical Evidence / Study Citation | Lowered Cutout on Paper | Ruled notebook paper cutoff with Scotch tape | Tech tick SFX |
- | **6** | Global Context / Entity Rankings | Full-Screen Infographic | Circular entity badges and distribution ranks | Subtle whoosh SFX |
- | **7** | Counter-Intuitive Truth / Metric Contrast | Lowered Cutout on Paper | Split bar comparison, contrast cards | Tech tick SFX |
- | **8** | Strategic Takeaway / Actionable Synthesis | Lowered Cutout on Paper | Triple rounded icon chips and takeaway card | Clean pop, outro bed |
- ---
- ## Multilingual Support
- edit-reel provides native speech-protected transcription, acoustic alignment, and typographic rendering across worldwide languages:
- | Language | ISO Code | Script Family | Subtitle Typography | Ground-Truth Citation Handling |
- |:---|:---:|:---:|:---|:---|
- | **English** | `en` | Latin | Bold Sans-Serif (`#FFFFFF` with `#000000` shadow) | Technical spelling and formulas preserved |
- | **Spanish** | `es` | Latin | Bold Sans-Serif | Academic titles and journal citations preserved |
- | **Mandarin Chinese** | `zh` | Simplified / Traditional | PingFang SC / Noto Sans CJK | Automatic CJK character tokenization |
- | **Hindi** | `hi` | Devanagari | Devanagari MT / Noto Sans Devanagari | Conjunct ligature and matra support |
- | **Arabic** | `ar` | Arabic (RTL) | Al Bayan / Geeza Pro / Naskh | Monotonic right-to-left word highlighting |
- | **French** | `fr` | Latin | Bold Sans-Serif | Accent-preserved phonetics |
- | **Portuguese** | `pt` | Latin | Bold Sans-Serif | Brazilian and European Portuguese phonetics |
- | **German** | `de` | Latin | Bold Sans-Serif | Compound noun protection during speech cuts |
- | **Japanese** | `ja` | Kanji / Kana | Hiragino Sans / Noto Sans JP | Boundary-aware acoustic alignment |
- | **Italian** | `it` | Latin | Bold Sans-Serif | Latin typographic layout |
- | **Russian** | `ru` | Cyrillic | Arial Bold / Helvetica Cyrillic | Cyrillic character set support |
- | **Korean** | `ko` | Hangul | AppleGothic / Noto Sans KR | Syllable-block acoustic synchronization |
- | **Regional Dialects** | `ary`, `darija` | Arabic / Arabizi | Naskh / Latin | Phonetic Darija alignment with English citations |
- Run with your target language:
- ```bash
- python scripts/pipeline.py -i video.mp4 --lang es
- python scripts/pipeline.py -i video.mp4 --lang zh
- python scripts/pipeline.py -i video.mp4 --lang ar
- ```
- ---
- ## Aesthetic Engine
- ```text
- 3-STATE ALTERNATING VISUAL RHYTHM
- -------------------------------------------------------------
- State 1: REAL CAMERA STUDIO (Camera A/B)
- - Authentic studio background preserved for hook and pauses
- - 1.04x punch-in zooms on sentence transitions for retention
- State 2: LOWERED CUTOUT SPEAKER + PHYSICAL OBJECTS
- - MediaPipe AI segmentation (selfie_segmenter.tflite)
- - Speaker positioned on warm paper canvas (y = 800..1920)
- - Upper canvas displays hanging tags, counters, and coin stacks
- State 3: FULL-SCREEN INFOGRAPHIC
- - Side-by-side comparative plots (Linear vs. Logarithmic)
- - Academic notebook cutoffs with ruled lines and tape
- ```
- ### 1. Tangible Physical Objects
- - **Hanging Price Tags**: Cream cards with angled corners, inner stroke border, and gold metal eyelet hanging from a string. Includes physics-based pendulum sway upon entry.
- - **Dynamic Loading Numbers**: Numerical milestones animate as rolling odometer counters.
- - **3D Coin Stacks**: Multi-tier gold coin stacks with rim bevels, accompanied by green (`#00704A`) up-arrows and red (`#BA1828`) down-arrows.
- - **Academic Notebook Cutoffs**: Authentic pinned notebook paper slips with ruled blue-gray lines (`#CBD5E1`), red vertical margin lines (`#F87171`), torn bottom edges, and semi-transparent top Scotch tape. Positioned lower down (`y = 165` on speaker scenes, `y = 210` on full-screen scenes) to safely clear mobile camera cutouts and platform status bars.
- - **Vector Icon Chips**: Rounded white label chips (`border-radius: 18px`) with high-resolution vector icons.
- ### 2. Speech-Protected Trimming and Anti-Arm-Reach Cutoff
- - `detect_cuts.py` leverages Faster-Whisper with word-level timestamps to protect every valid spoken syllable.
- - Automatically removes dead-air pauses, throat clears, stumbles, and repeated takes.
- - **Anti-Arm-Reach Cutoff**: Trims cleanly at the calm, smiling frame following the final word, eliminating the motion of the speaker reaching forward to turn off the camera.
- ---
- ## Audio Mastering Suite
- Every video rendered by edit-reel passes through an automated broadcast audio mastering chain:
- ```text
- Raw Microphone Audio
- |
- v
- FFT Spectral Denoiser (afftdn=nr=24:nf=-48:tn=1)
- |
- v
- Highpass Filter (85 Hz cutoff)
- |
- v
- Downward Expander Gate (agate, eliminates room hiss)
- |
- v
- Studio Vocal Compressor (attack=15ms, release=100ms)
- |
- v
- Broadcast Loudness Normalizer (loudnorm -> -11.5 LUFS)
- |
- v
- Ambient Music Bed Ducking (850 Hz low-pass at volume 0.045)
- |
- v
- Keyframe-Locked Micro-SFX (paper turns, pops, chimes at volume 0.04)
- |
- v
- Final Mastered Multi-Track Audio (.MP4)
- ```
- ---
- ## Pipeline Architecture
- The end-to-end autonomous pipeline continuously executes through six discrete stages visualized in the looping workflow flowchart at the top:
- | Stage | Module | Key Transformation |
- |:---:|:---|:---|
- | **01** | `detect_cuts.py` | Ingests raw video footage (.mp4/.mov) and companion script (.docx/.txt) |
- | **02** | `transcribe_align.py` | Extracts Whisper millisecond word timestamps and applies acoustic silence/stumble trimming |
- | **03** | `storyboard_planner.py` | Synthesizes an 8-scene beat map alternating between Studio, Cutout, and Infographic |
- | **04** | `paper_objects.py` | Isolates speaker with MediaPipe and composites hanging tags, odometers, and notebook citations |
- | **05** | `FFmpeg Vocal Chain` | Applies adaptive spectral denoising, 85Hz highpass gate, -11.5 LUFS loudness, and motion SFX |
- | **06** | `render_reel.py` | Exports the production-ready 1080x1920 9:16 vertical reel autonomously |
- ---
- ## Customization (Make It Yours)
- Brand styling, color palettes, and audio parameters can be customized via `templates/config.json`:
- ```json
- {
- "canvas": {
- "paper_color": "#E2DDD1",
- "ink_color": "#262320",
- "accent_green": "#00704A",
- "accent_red": "#BA1828"
- },
- "audio": {
- "target_lufs": -11.5,
- "bgm_volume": 0.045,
- "sfx_volume": 0.040,
- "bgm_lowpass_hz": 850
- },
- "safe_zones": {
- "speaker_y": 800,
- "notebook_speaker_y": 165,
- "notebook_fullscreen_y": 210,
- "subtitles_y": 1555
- }
- }
- ```
- ---
- ## Repository Structure
- ```text
- edit-reel/
- ├── SKILL.md # Antigravity and Claude Code skill definition
- ├── README.md # Public documentation and specifications
- ├── LICENSE # MIT License
- ├── requirements.txt # Python dependencies
- ├── pyproject.toml # Package metadata and CLI entry points
- ├── install.sh # Universal installer script
- ├── CLAUDE.md # Claude Code developer guide
- ├── .cursorrules # Cursor and Windsurf prompt rules
- ├── .gitignore # Git ignore rules
- ├── credit_ledger.example.json # Template for API token and cost tracking
- │
- ├── assets/ # Animated pipeline flowchart assets
- │ └── pipeline_flow.gif
- │
- ├── models/ # Bundled edge AI vision models
- │ ├── selfie_segmenter.tflite # Fast 244KB person segmentation model
- │ └── selfie_multiclass.tflite # High-precision multiclass model
- │
- ├── motion_library/ # Tangible physical objects and styling
- │ ├── paper_objects.py # Canonical objects (tags, odometers, coins, notebooks)
- │ ├── renderers.py # Motion renderers and canvas drawing
- │ ├── palette.py # Editorial color system (#E2DDD1, #00704A, #BA1828)
- │ ├── catalog.py # Metadata and object definitions
- │ ├── icons/ # Over 150+ vector icons across science, tech, and finance
- │ ├── broll/ # Curated ambient B-roll textures
- │ └── sfx/ # Mastered sound effects (pops, paper turns, chimes)
- │
- ├── references/ # Safe-zone specs and phonetic dictionaries
- │ ├── safe_zone_layout.md # 9:16 mobile safe zone boundaries
- │ ├── animation_catalog.md # Visual primitives reference
- │ └── darija_transcription.md # Phonetic Moroccan Darija dictionary
- │
- ├── scripts/ # Execution pipeline
- │ ├── pipeline.py # Master end-to-end pipeline runner
- │ ├── render_reel.py # Core video renderer and audio mixer
- │ ├── detect_cuts.py # Speech-protected silence and stumble trimmer
- │ ├── transcribe_align.py # Whisper forced aligner
- │ ├── storyboard_planner.py # 3-state scene scheduler
- │ ├── preview_reel_stills.py # Scene still and contact sheet previewer
- │ ├── generate_animated_flowchart.py# Looping pipeline GIF generator
- │ └── progress_tracker.py # Real-time terminal progress logger
- │
- └── templates/
- └── config.json # Production defaults
- ```
- ---
- ## Frequently Asked Questions (FAQ)
- <details open>
- <summary><b>What is the best free open-source AI video editor for Instagram Reels, TikTok, and YouTube Shorts?</b></summary>
- <br>
- **edit-reel** is a 100% free, MIT-licensed open-source AI video editor written in Python that runs locally on macOS and Linux with zero watermarks. Unlike web-based SaaS clippers, it combines word-accurate Faster-Whisper speech trimming, MediaPipe AI person background segmentation, tactile physical motion graphics, and -11.5 LUFS broadcast audio mastering in a single command.
- </details>
- <details>
- <summary><b>How do I automatically add animated subtitles and remove silences from talking-head videos in Python?</b></summary>
- <br>
- Run `python scripts/pipeline.py -i input.mp4 --lang en`. The pipeline executes `detect_cuts.py` to remove dead air, false starts, and stumbles while protecting spoken syllables, aligns your script to millisecond acoustic timestamps via `transcribe_align.py`, and burns word-by-word kinetic subtitles directly onto the 9:16 vertical canvas.
- </details>
- <details>
- <summary><b>How does edit-reel work as a Claude Code skill, Cursor rule, or Google Antigravity skill?</b></summary>
- <br>
- The repository includes native agent definitions (`SKILL.md`, `CLAUDE.md`, and `.cursorrules`). Running the one-line installer (`curl -fsSL https://raw.githubusercontent.com/MMhaidra/edit-reel/main/install.sh | bash`) registers the `/edit-reel` command globally so your AI coding agent can autonomously edit raw recordings from start to finish.
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 453 on GitHub
- </details>
- <details>
- <summary><b>Does edit-reel require Adobe After Effects, Premiere Pro, or paid cloud APIs?</b></summary>
- <br>
- No. All computer vision segmentation (`selfie_segmenter.tflite`), acoustic forced alignment (`faster-whisper`), procedural motion graphics (`Pillow` / `OpenCV`), and multi-track audio mastering (`FFmpeg`) execute locally on your machine at zero cost.
- </details>
- ---
- ## Star History
- If you find edit-reel useful for your content creation or agent workflows, please consider starring the repository to help other developers and creators discover it:
- <p align="center">
- <a href="https://star-history.com/#MMhaidra/edit-reel&Date">
- <img src="https://api.star-history.com/svg?repos=MMhaidra/edit-reel&type=Date" alt="edit-reel Star History Chart" width="100%" />
- </a>
- </p>
- ---
- ## Citation
- If you use edit-reel in your research, academic publications, or production frameworks, please cite it as follows:
- ```bibtex
- @software{mhaidra2026editreel,
- author = {Mhaidra, Mohammed},
- title = {edit-reel: Autonomous Open-Source AI Video Editor & Auto Subtitles Generator},
- year = {2026},
- url = {https://github.com/MMhaidra/edit-reel},
- version = {1.0.0}
- }
- ```
- ---
- ## Community and Launch Playbook
- Looking to share edit-reel with your community, submit to Awesome lists, or post a launch thread? Check out our complete guide:
- - [`docs/VIRAL_LAUNCH_PLAYBOOK.md`](docs/VIRAL_LAUNCH_PLAYBOOK.md): Ready-to-copy launch templates for Hacker News (Show HN), Reddit (`r/Python`, `r/LocalLLaMA`, `r/ClaudeAI`), Twitter/X launch threads, and curated directory PR submissions.
- ---
- ## Contributing
- Contributions, feature requests, and new motion primitives are welcome:
- 1. Fork the Project (`https://github.com/MMhaidra/edit-reel/fork`).
- 2. Create your Feature Branch (`git checkout -b feature/NewMotionPrimitive`).
- 3. Commit your Changes (`git commit -m 'feat: Add animated dual-gauge metric primitive'`).
- 4. Push to the Branch (`git push origin feature/NewMotionPrimitive`).
- 5. Open a Pull Request.
- ---
- ## License
- Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information.
- ---
- <div align="center">
- <b>Author: <a href="https://github.com/MMhaidra">Mohammed Mhaidra</a></b>
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.