AI Clip Assembler

Website · Releases · User guide

AI Clip Assembler is a free, local-first macOS app for turning raw drone, action-camera, or event footage into a clean, editable timeline. Import a folder of clips, let the app score and detect useful moments locally, review the suggestions, adjust the timeline, and export to Final Cut Pro, DaVinci Resolve, or any editor that accepts EDL.

The project is built for creators who come home with hours of raw footage and need a fast first assembly. Analysis and scoring run locally by default; provider-backed AI harnesses are available but only run after you opt in per project.

The problem

Raw video review is slow. A short finished edit can start with hours of shaky, duplicated, poorly exposed, or visually uninteresting footage. Most AI video tools either hide the editing decisions, require uploading footage, or produce a final render that is hard to refine in a professional editor.

AI Clip Assembler solves the first-pass assembly problem:

• Keep footage on your machine.
• Find candidate clips using technical scoring, scene detection, motion analysis, and optional AI harnesses.
• Let the human editor accept, reject, trim, reorder, and refine the results.
• Export an editable timeline instead of a locked-in final video.

Current status

AI Clip Assembler is an active MVP. The end-to-end drone-first workflow works locally: import, analyze, review, timeline editing, and export to DaVinci Resolve XML, FCPXML, or EDL.

The app is still early. Expect rough edges, macOS-first setup, and active changes to the project format while the editor matures.

Features

• Local FastAPI backend for video analysis and export.
• Electron + React desktop app for import, review, timeline editing, and export.
• FFmpeg/OpenCV/PySceneDetect pipeline for frame sampling, quality scoring, scene boundaries, and motion stability.
• Pluggable harness system with a default no-AI manual harness and opt-in cloud AI harnesses.
• Review board for accepting or rejecting candidate clips.
• Backend-authoritative timeline with split, retrim, reorder, speed, transform, undo, and redo support.
• Export to Final Cut Pro XML, DaVinci Resolve XML, and EDL.

Privacy model

AI Clip Assembler is local by default. Source videos are processed on your machine, project data is stored as files, and there is no database service.

Cloud AI is opt-in per project. Provider-backed harnesses may send sampled frames or clip metadata to tools or providers you configure yourself, and the backend refuses to run those harnesses until project consent is saved. If you use a provider-backed harness, review that provider's data policy before sending frames or metadata through it. The manual harness runs without AI.

Connecting an external AI assistant through MCP is a separate trust boundary. If you ask that assistant to inspect clip metadata or sampled frame paths, what it reads becomes part of that external provider interaction and is governed by the provider's privacy policy; the harness consent gate does not cover this MCP path.

Tech stack

• Desktop: Electron, React, Vite, Tailwind CSS
• Backend: FastAPI, Python, FFmpeg, OpenCV, PySceneDetect
• Data: project folders, JSON metadata, FFmpeg-derived media metadata
• AI: modular harnesses for manual rules, local models, and user-chosen agent/provider workflows

Install the app

Download the macOS DMG from Releases, drag AI Clip Assembler into Applications, and open it. Release builds include the Python backend and a private FFmpeg runtime with motion-analysis support; no Python, Homebrew, or terminal setup is required.

The app tells you when a newer release is out. To update or remove an installed copy from the terminal:

./scripts/app-wizard.sh          # status, update, or uninstall

See docs/UPDATING.md for what the wizard touches (and what it never touches).

The instructions below are for contributors running the project from source.

Getting started

Prerequisites

AI Clip Assembler currently targets macOS development.

Install the system tools:

brew install python@3.11 node ffmpeg

FFmpeg must include the vidstabdetect filter for motion analysis:

ffmpeg -hide_banner -filters | grep vidstabdetect

If that prints nothing, your FFmpeg build does not include libvidstab. The standard Homebrew bottle may not include it. Build FFmpeg from the homebrew-ffmpeg tap instead:

brew uninstall ffmpeg
brew tap homebrew-ffmpeg/ffmpeg
brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-libvidstab
ffmpeg -hide_banner -filters | grep vidstab

The source build can take 10-30 minutes. This is only required for local development: release DMGs bundle a verified FFmpeg runtime with vidstabdetect, so normal users do not install Python, Homebrew, or FFmpeg.

Run the app

git clone https://github.com/evilkels/ai-clip-assembler.git
cd ai-clip-assembler

Set up the backend:

cd backend
python3.11 -m venv .venv
.venv/bin/pip install -r requirements.txt

Set up the frontend:

cd ../frontend
npm install

Run the backend and Electron app together:

npm run dev:with-backend

The backend runs on http://127.0.0.1:8000. The Electron app opens in development mode.

Optional cloud AI harness setup

The default harness is manual, which runs without AI. The optional pi_agent harness drives the pi coding-agent CLI to score candidate clips with a configured provider. It requires explicit project consent before it can run.

Install and authenticate it if you want AI-assisted visual-interest scoring:

npm install -g @earendil-works/pi-coding-agent
pi /login

You can tune the harness with environment variables such as PI_PROVIDER, PI_MODEL, PI_BIN, and PI_TIMEOUT_SEC. Put local defaults in a repo-root .env; use .env.example as the template.

For a no-AI workflow, use the manual harness.

Basic workflow

1. Import a folder of MP4 source footage.
2. Run analysis to detect scenes, score quality, measure motion stability, and assemble candidate clips.
3. Review candidate clips and accept the useful ones.
4. Adjust the timeline with trims, ordering, speed, and transform changes.
5. Export to FCPXML, DaVinci Resolve XML, or EDL.

See the User Guide for a fuller walkthrough.

Development

Run backend tests:

cd backend
PYTHONPATH=. .venv/bin/python -m pytest

Run frontend checks:

cd frontend
npm run typecheck
npm run build

Run the synthetic end-to-end check from the repo root:

backend/.venv/bin/python scripts/synthetic_e2e_qa.py

Useful scripts from frontend/:

• npm run dev:with-backend - run backend and Electron together
• npm run dev:backend - run only the backend
• npm run dev - run only the Electron app
• npm run test:backend - run the backend test suite
• npm run test:e2e - run Playwright end-to-end tests

Project structure

ai-clip-assembler/
├── backend/      FastAPI video analysis, timeline, harness, and export code
├── frontend/     Electron + React desktop app
├── harness/      AI harness configuration and local harness docs
├── docs/         architecture, setup, QA, MCP, plans, and product docs
└── scripts/      smoke tests, synthetic QA, and benchmark helpers

Documentation

• User Guide - import, review, timeline, and export workflow
• Developer Setup - local environment and test commands
• Troubleshooting - common setup and runtime issues
• Architecture - system design
• Harness Spec - pluggable AI harness contract
• Media Prompt Ideas - logo, hero, and screenshot generation prompts
• PRD - product requirements

Contributing

Issues and pull requests are welcome. This project is early, so the most useful contributions are bug reports with reproducible footage/setup details, focused fixes, test coverage, export compatibility improvements, and docs that make local setup easier.

Before opening a PR, read CONTRIBUTING.md and run the relevant checks locally.

Security

Please do not open a public issue for a vulnerability. See SECURITY.md for the reporting process.

License

AI Clip Assembler is released under the MIT License.