Getting started

Installation

Prerequisites * Python 3.11 – 3.13 * ffmpeg (must be in system PATH)

Install via pip

pip install git+https://github.com/andrewwkimm/koffee

Usage

Video, audio, and subtitle files are all supported for translation and the translated subtitle file will be outputted to the current directory.

koffee some_dir/some_video_file.mp4

The translation method defaults to Whisper; for more accurate translations, koffee supports LLM (currently ChatGPT, Claude, Gemini, and Ollama) based translations as well.

Set your API key as an environment variable to use but it also passable as an argument.

export GEMINI_API_KEY=<your-api-key>
koffee audio_file.mp3 --provider=gemini

or

koffee audio_file.mp3 --provider=gemini --api-key=<your-api-key>

There is full feature parity between the CLI and the Python library. See the example below for basic usage:

import koffee


koffee.run("some_dir/some_video_file.mp4")