CutSmith is an AI-assisted, non-destructive video editor controlled via natural language directly in your browser. Editing commands—such as cuts, crossfades, blur transitions, and independent audio track management—compile directly into a single-pass FFmpeg filter_complex pipeline built on a strict Model-View-Controller (MVC) architecture.
Author: Erno Pakarinen / CODESMITH
Open source - Free - MIT LICENSE
- Natural Language Editing: Cut scenes, split clips at timestamps or the playhead marker, apply transitions, and manage audio tracks in English or Finnish.
- Non-Destructive Timeline: All edits are persisted in a lightweight JSON project state (
workspace/project_state.json) without modifying original source media files. - Precision Range Selection: Highlight exact ranges directly on the timeline (
Shift + drag) to target cuts, blur transitions, or crossfades across clip boundaries. - Transitions & Effects: Seamless boundary crossfades (
xfade/acrossfade) and stepped focus-in/focus-out blur transitions (gblur). - Independent Audio Track Control: Detach or mute the original video audio track, edit video cuts and crossfades freely without audio glitches, and attach a continuous audio track across the entire timeline.
- Separate Audio Timeline: Detach video audio onto its own
audio_clipslane so picture and sound can be cut, moved, and leveled independently (J-cuts / L-cuts). - Timeline Fade In / Fade Out: Apply whole-timeline fades from/to black on both video and audio (e.g. "Tee videon alkuun 5 sekunnin fade in ja videon loppuun sama 5 sekunnin fade out").
Before installing, ensure the following are available on your system:
- Python 3.11+ (3.11 or 3.12 recommended)
- FFmpeg & FFprobe installed and available in your system
PATH - A local LLM runtime (e.g., Ollama) or an OpenAI-compatible API endpoint
Linux (Ubuntu / Debian / Linux Mint):
sudo apt update && sudo apt install -y ffmpeg python3-venv python3-pipmacOS (Homebrew):
brew install ffmpeg pythonWindows (winget):
winget install Gyan.FFmpeg Python.Python.3.12CutSmith is tested with the local Qwen3-8B model:
# Install Ollama (https://ollama.com) and pull the model:
ollama pull qwen3:8b-
Clone the repository and enter the directory:
git clone https://github.com/codesmith-fi/smithcut.git cd smithcut -
Create and activate a virtual environment:
python3 -m venv .venv source .venv/bin/activate # Linux / macOS # .venv\Scripts\activate # Windows
-
Install Python dependencies:
pip install --upgrade pip pip install -r requirements.txt
-
Configure environment variables (optional): If
.env.exampleis present, copy it and adjust the model endpoint or name if needed:cp .env.example .env
Start the server using the launch script or directly via Uvicorn:
chmod +x run.sh
./run.shOr manually:
.venv/bin/uvicorn web.api:app --reload \
--reload-dir agent --reload-dir compiler --reload-dir controller \
--reload-dir mcp_server --reload-dir models --reload-dir web \
--reload-exclude 'workspace/*' --port 8000Open http://localhost:8000 in your browser.
- Import Media: Drag and drop a video file (e.g.,
.mp4) onto the preview or import area. - Split or Cut:
- Click the timeline to position the playhead and type: "Split the video into two clips here" or "Split the video at 2:20".
- Hold Shift and drag across the timeline to select a range, then type: "Cut out the selected range".
- Add a Crossfade:
- Highlight a range spanning the boundary between two clips and type: "Apply a crossfade to the selected range", or specify exact durations: "Take 5 seconds from the end of clip 1 and 5 seconds from the start of clip 2 and create a crossfade".
- Add a Blur Transition:
- Highlight a scene and type: "Add a smooth blur transition to the start and end of the selected range".
- Manage Audio Independently:
- "Remove audio track from the video" → edit video clips and crossfades → "Attach audio track 1 to the video".
- Separate Audio Timeline:
- "Erota videosta ääni omalle raidalleen" → cut/move audio alone ("Siirrä ääniklippi 2 alkamaan kohdasta 0:08", "Laske ääniraidan voimakkuus puoleen").
- Timeline Fade In / Out:
- "Tee videon alkuun 5 sekunnin fade in ja videon loppuun sama 5 sekunnin fade out" or "Lisää 3 sekunnin loppuhäivytys".
Run the unit and FFmpeg integration test suite with pytest:
.venv/bin/pytestcutsmith/
├── models/ # Data models (Timeline, VideoClip, Transition, BlurEffect, AudioTrack)
├── compiler/ # FFmpeg filter_complex compiler and preview renderer
├── controller/ # EditorController, state management, and workspace/project_state.json
├── mcp_server/ # AI agent tool interfaces
├── agent/ # LLM integration and natural language command parsing
├── web/ # FastAPI backend and browser UI
└── tests/ # Automated unit and integration tests