PeakCut in Action: Build Your Own AI Short-Video Editing Tool
The most time-consuming part of making short videos isn't editing—it's finding the few dozen seconds worth sharing from a one- or two-hour livestream or long video. PeakCut automates this pipeline: it runs speech recognition locally, uses AI to pick highlight moments, automatically cuts them into 9:16 vertical format, and adds word-by-word subtitles. The most appealing part is that the entire process can run entirely on your own computer, and your video and audio data never leave your machine.
Its workflow is straightforward: transcribe the audio, let AI judge which clips can hold a stranger's attention, then use FFmpeg to render vertical short videos with subtitles. Transcription uses sherpa-onnx and the Parakeet model, running completely locally; AI is only responsible for selecting clips and writing titles—you can use any provider, as long as it's OpenAI-compatible.
If you'd rather not use the official ChatGPT API, Defapi is a good choice. Its pricing is half of the official one, and its models are basically compatible with mainstream protocols like v1/chat/completions, v1/messages, and v1beta/models/, so PeakCut's Custom provider can directly connect, and the configuration method is exactly the same as step 3 below.
Core Dependencies and Environment
Before you begin, make sure you have these things:
- Python 3.10+: The main program's runtime environment.
- FFmpeg: Handles all video and audio processing. On Windows, use
winget install Gyan.FFmpeg; on macOS, usebrew install ffmpeg; on Linux, usesudo apt install ffmpeg. - Network and Storage: The first launch requires downloading about 480MB of speech models. Video files themselves are not small, so it's recommended to reserve more than 20GB of disk space.
- AI Key (Optional): You can use it without configuring one; in that case, PeakCut will select clips based on loudness but won't generate AI titles.
PeakCut recommends placing the project at a fixed path, such as C:\peakcut (Windows) or ~/peakcut (macOS/Linux). Don't put it in a temporary directory; on Windows, paths that are too deep can cause speech model loading to fail.
Project Structure Tree
peakcut/
├── studio/ # Server-side main code
│ ├── server.py # FastAPI entry point
│ ├── ai.py # AI service adapter layer (add new providers here)
│ ├── transcribe.py # Local speech transcription
│ ├── jobs.py # Editing task pipeline
│ ├── render.py # Subtitle rendering and video composition
│ └── fonts/ # Subtitle font files
├── web/ # Frontend pages (pure HTML/CSS/JS)
├── deploy/ # Docker deployment configuration
├── tests/ # Automated tests
├── requirements.txt # Python dependencies
├── .env.example # Environment variable template
└── Dockerfile
Step-by-Step Guide
1. Clone the Repository and Install Dependencies
git clone https://github.com/haziqahmedqasmi/peakcut.git ~/peakcut
cd ~/peakcut
pip install -r requirements.txt
It's recommended to use a virtual environment to avoid polluting global Python packages.
2. Start the Local Service
python -m studio.server
The first launch will automatically download the speech model (about 480MB), so you'll need to wait a bit. When you see output like Uvicorn running on http://127.0.0.1:8765, the service is up.
Open http://127.0.0.1:8765 in your browser to directly access the console without logging in.
3. Configure the AI Service
Go to Settings → AI page. Here, choose your AI service provider. PeakCut's AI is responsible for two things: deciding which clips are worth cutting and writing titles for the clips. It needs a chat model that can return JSON, not a speech-to-text service—transcription always runs locally.
Select Custom (OpenAI-compatible) from the dropdown. A Base URL input will appear. Fill in your provider's address, paste your API Key in the Key field, manually enter a chat model name that supports JSON output, then click Find models to fetch the available model list (if the provider supports it), and finally click Save and test.
For example, Defapi provides an OpenAI-compatible API at half the official price. Configuration is as follows:
- Base URL:
https://api.defapi.org/v1 - Key: Obtain it from the Defapi platform console
- Model: Enter a chat model ID that supports JSON output, like
your-model-id(the specific ID depends on the list in your account dashboard)
Defapi is compatible with mainstream protocols like v1/chat/completions, v1/messages, and v1beta/models/, so PeakCut's Custom provider can directly connect.
Note: If you previously configured AI parameters via the .env file, settings saved in the console will override the .env settings. If you want to use .env, the corresponding variables are:
PEAKCUT_AI_PROVIDER=custom
PEAKCUT_AI_MODELS=your-model-id
PEAKCUT_AI_KEY=your-key
PEAKCUT_AI_BASE_URL=https://api.defapi.org/v1
4. Import Videos
On the homepage, there's a paste box at the top that supports YouTube, Twitch, and Kick links, and you can also directly upload local video files.
In Options, you can set the number of generated clips (1-20), minimum/maximum duration (minimum 5 seconds, maximum 180 seconds), subtitle style (Bounce/Hype/Clean), layout (blurred fill/zoom/crop/game with webcam), resolution (720p/1080p), and also restrict processing to only a certain segment of the video.
There's an option called Generate captions, enabled by default. Subtitles are highlighted word by word, which requires the speech model to output recognition results with timestamps. The default model supports English best; if you need another language, you'll have to switch models, as covered in the troubleshooting section later.
Once you've filled in the link, click Make clips to start processing.
5. Filter Clips and Adjust Subtitles
After processing is complete, go to the video detail page to see all generated clips. Each clip allows you to:
- Preview: Check if you're satisfied with the result
- Adjust start/end points: Fine-tune by dragging on the timeline
- Edit subtitles: Manually correct words if recognition is wrong
- Change subtitle style: Switch freely among the three styles
PeakCut generates a cover image and an engaging title (written by AI) for each clip. You can directly edit the title if you don't like it.
6. Export Vertical Short Videos
Once you've confirmed the clips are fine, click Download to export. Rendering is done by FFmpeg, producing a final 9:16 vertical format with subtitles burned into the frame.
If you've configured YouTube, Instagram, or TikTok account connections, you can also publish directly from here. For standalone use, it's recommended to download first and then upload manually.
Common Issues and Troubleshooting
FFmpeg Missing
After startup, the console will indicate FFmpeg is not found. Make sure ffmpeg -version produces output; if not, reinstall and ensure it's in your PATH.
Speech Model Download Failure
If the model download is interrupted on first launch, delete the corresponding folder under data/models/ and restart the service to let it download again. If the network is unstable, you can manually download from Hugging Face and place it in the specified directory.
Saved AI Configuration Not Taking Effect
Check if Settings → AI page shows the configuration is saved. Configurations saved in the console take precedence over the .env file. If you previously wrote AI variables in .env, once the console has been saved, the .env values are ignored. To go back to .env configuration, you need to reselect the provider in the console and save again.
AI Returns Invalid JSON Format
Confirm the model ID is a chat model that supports JSON output. Some models (especially pure reasoning models) don't guarantee valid JSON; try a different model. You can also check the AI usage page, which has detailed request logs.
Subtitle Language Is Wrong
The default Parakeet model only supports English. For Chinese videos, either switch to a sherpa-onnx model that supports Chinese (you need to change ASR_MODEL_NAME in studio/config.py), or use YouTube's built-in Chinese transcription (this feature is on by default and will prioritize YouTube's transcription text).
Insufficient Disk Space
The data/ directory stores all videos and generated results. Check disk space is sufficient before processing long videos. Go to Settings → Storage to see the current storage path and remaining space, and you can also migrate the data directory to another drive.
Further Reading / Advanced Directions
PeakCut can not only edit pre-recorded videos but also record and edit highlight clips in real time during a livestream. Create a workspace for each creator, set up the channel, and it will automatically monitor and produce clips during the stream.
For team collaboration or public deployment, refer to DEPLOY.md: use Docker to run the app with PostgreSQL and Caddy for automatic HTTPS, supporting email registration and Google login. Note that for public deployment, you must enable PEAKCUT_ACCOUNTS=1; otherwise, anyone who knows the address can use your AI Key.
Connecting social media accounts (YouTube/Instagram/TikTok) requires registering developer apps on each platform. During platform review, uploaded videos are set to private by default, which is a platform limitation, not an issue with PeakCut itself.
If you want to go deeper, studio/ai.py is the only file that interacts with AI services—adding a new provider or debugging request logic starts there. The code also includes a test suite (python tests/run.py); running it after code changes helps prevent regressions.