CodecKoala
CodecKoala is a desktop Electron app that uses OpenRouter to generate safe FFmpeg commands, validates them, and runs ffmpeg with strict security constraints.
Developer and contributor docs live in DEVELOPER_DOCS/.
End-user guidance lives in UserGuide.md.
Release history lives in CHANGELOG.md.
Requirements
- Node.js 20+ and npm
ffmpegandffprobeavailable in your PATH- OpenRouter API key
Setup
- Install dependencies
npm install
- For local development, create a
.envfile in the project root from.env.example:
OPENROUTER_API_KEY=your_key_here
OPENROUTER_DEFAULT_MODEL=your_preferred_model_id
VIBEFFMPEG_TIMEOUT_MS=30000
OPENROUTER_DEFAULT_MODEL=your_preferred_model_id
VIBEFFMPEG_TIMEOUT_MS=30000
- Run the app
npm run dev
Build
npm run build
Linux AppImage (Pop!_OS / Ubuntu-style)
End-user prerequisites
Install FFmpeg once:
sudo apt update
sudo apt install ffmpeg
sudo apt install ffmpeg
Run the packaged app
- Download the
.AppImagerelease file. - Make it executable (one time):
chmod +x CodecKoala-*.AppImage
- Double-click it in your file manager, or run it from a terminal.
- On first launch, use the in-app OpenRouter setup banner to save your API key.
Build an AppImage (developer)
npm install
npm run dist:linux
npm run dist:linux
The AppImage will be created in dist/.
Notes
- OpenRouter models list endpoint:
https://openrouter.ai/api/v1/models - OpenRouter chat completions endpoint:
https://openrouter.ai/api/v1/chat/completions - Settings and history are stored in the app's Electron
userDatadirectory. - The repository includes
.env.exampleas a template; keep your real.envout of Git.
Scripts
npm run devstarts Vite + Electronnpm run buildbuilds renderer + mainnpm run pack:linuxpackages an AppImage from an existing buildnpm run dist:linuxbuilds and packages a Linux AppImagenpm run lintruns ESLint
Security
- API key handling stays in the main process and can come from
.envor in-app settings. - Renderer never receives the raw API key.
- ffmpeg is spawned with
shell: falseand args array.