Skip to content

CLI Reference

koffee COMMAND [OPTIONS] [ARGS...]

Automatic video translation and subtitling tool.

Table of Contents

Arguments:

  • FILE_PATH: Path to the video, audio, or subtitle file

Commands:

  • convert: Convert a subtitle file between formats (SRT, VTT, ASS).
  • embed: Embed subtitles into a video without transcription or translation.
  • info: Display system information for debugging.
  • languages: List all supported language codes.
  • tracks: List embedded subtitle tracks in a video file.
  • transcribe: Transcribes audio to subtitles without translation.

Parameters:

  • --compute-type, -c: Type to use for computation
  • --device, -d: Device to use for computation
  • --transcription-model, -m: The Whisper model instance to use
  • --output-dir, -o: Directory for the output file
  • --output-name, -n: Name of the output file
  • --source-language, -s: Source language of the subtitle file (default: auto)
  • --target-language, -t: Language to which the file should be translated
  • --subtitle-format, -f: Format to use for the subtitles
  • --embed: Subtitle embed mode: none (subtitle file only), soft (muxed track), or hard (burned into video frames). Only valid for video file inputs.
  • --translator: The translation backend to use (whisper, google, openai, anthropic, ollama)
  • --translation-model: The LLM model to use for translation
  • --chunk-size: Number of subtitle entries per LLM request (auto-selected per model if unset)
  • --context-size: Number of preceding entries passed as context per request (auto-selected per model if unset)
  • --sleep: Seconds to wait between LLM requests (auto-selected per backend if unset)
  • --prompt: Custom system prompt for the LLM translation model
  • --api-key: API key for an LLM service
  • --on-translation-failure: What to do when LLM translation fails: prompt (default; ask y/n to save the raw transcription), save (save without asking), or abort (skip the save). When stdin is not a TTY, prompt falls back to save.
  • --on-collision: What to do when the output file already exists: prompt (default; ask y/n to overwrite), overwrite, skip, or abort. When stdin is not a TTY, prompt falls back to abort.

Options:

  • --config: Path to a koffee.toml configuration file
  • --vad-filter, --no-vad-filter: Voice activity detection filtering during transcription (enabled by default; pass --no-vad-filter to disable)
  • --dry-run: Preview what would be done without running transcription or translation
  • --allow-mixed-translation: Allow resuming a job whose saved chunks used a different translator or model
  • --overwrite: Overwrite existing output files instead of raising an error
  • --verbose, -v: Print debug log messages [default: False]
  • --help, -h: Display this message and exit.
  • --version, -V: Display application version.

koffee info

koffee info

Display system information for debugging.

koffee languages

koffee languages

List all supported language codes.

koffee convert

koffee convert FILE-PATH [ARGS]

Convert a subtitle file between formats (SRT, VTT, ASS).

Parameters:

  • FILE-PATH, --file-path: Path to the subtitle file [required]
  • --format, -f: Target subtitle format (srt, vtt, or ass) [default: vtt]
  • --output-dir, -o: Directory for the output file
  • --output-name, -n: Name of the output file

Options:

  • OVERWRITE, --overwrite: Overwrite existing output files instead of raising an error [default: False]

koffee embed

koffee embed VIDEO-PATH SUBTITLE-PATH [ARGS]

Embed subtitles into a video without transcription or translation.

Parameters:

  • VIDEO-PATH, --video-path: Path to the video file [required]
  • SUBTITLE-PATH, --subtitle-path: Path to the subtitle file [required]
  • --output, -o: Path for the output video file
  • --mode, -m: Embed mode: soft (muxed track) or hard (burned into video frames) [default: soft]

Options:

  • OVERWRITE, --overwrite: Overwrite existing output files instead of raising an error [default: False]

koffee tracks

koffee tracks FILE-PATH

List embedded subtitle tracks in a video file.

Parameters:

  • FILE-PATH, --file-path: [required]

koffee transcribe

koffee transcribe [OPTIONS] FILE-PATH

Transcribes audio to subtitles without translation.

Parameters:

  • FILE-PATH, --file-path: [required]
  • --compute-type, -c:
  • --device, -d:
  • --transcription-model, -m:
  • --output-dir, -o:
  • --output-name, -n:
  • --subtitle-format, -f:

Options:

  • --vad-filter, --no-vad-filter:
  • --overwrite: