Skip to content

Formerly KrillinAI, VideoTranslation and Dubbing Tool for 120+ Languages. Open-source AI workspace for creators, powered by Codex. Video downloader, video translation, create videos, images, audios, and edits with Agents in one place. For your Social Media like YouTube, TikTok, Instagram, etc.

5.2 KB
Raw Blame

KrillinAI CLI Contract

Build And Binary

Use the repository build script from the OpenCreator root:

pnpm krillinai:build

It builds runtime/krillinai/cmd/cli and runtime/krillinai/cmd/server. Native binaries and a manifest are written under:

.runtime/build/krillinai/<platform>-<arch>/
├── bin/krillinai-cli[.exe]
├── bin/krillinai-server[.exe]
└── manifest.json

Set reusable absolute paths from the repository root:

REPO_ROOT="$PWD"
TARGET="$(node -p "process.platform + '-' + process.arch")"
SUFFIX="$(node -p "process.platform === 'win32' ? '.exe' : ''")"
KRILLINAI_CLI="$REPO_ROOT/.runtime/build/krillinai/$TARGET/bin/krillinai-cli$SUFFIX"
KRILLINAI_CWD="$REPO_ROOT/runtime/krillinai"
WORKDIR="$REPO_ROOT/tasks/demo"
test -f "$KRILLINAI_CLI"
mkdir -p "$WORKDIR"

Execution Working Directory

The CLI loads config/config.toml relative to the process working directory.

  • Source checkout: run real commands with runtime/krillinai as the working directory. Create the ignored runtime/krillinai/config/config.toml from config-example.toml and configure only the providers needed by the requested stage.
  • Release archive: run from the unpacked package root after creating config/config.toml from config/config-example.toml.
  • OpenCreator: the Daemon prepares an isolated launcher directory and configuration automatically; do not replace that flow with a source-tree config.

Use absolute --workdir, input, subtitle, audio, and output paths when changing the process working directory.

Commands

Command Purpose
subtitle Generate source-language, target-language, bilingual, and short vertical subtitles
tts Generate TTS audio and optional dubbed video
speech Generate one audio file from text or a UTF-8 text file
render-horizontal Render landscape subtitle/dubbed videos
render-vertical Render portrait subtitle/dubbed videos
cover Generate a cover image from a complete text prompt
voices List voice codes for aliyun, openai, or minimax; Edge TTS has no CLI voice catalog
pipeline Validate output plans with --dry-run; non-dry-run execution is unsupported
status Reserved and unsupported

Manifest

Every working directory should contain:

krillinai_manifest.json

Read this file to locate stage outputs. Important default paths:

Output key Default path
origin_video <workdir>/origin_video.mp4
origin_audio <workdir>/origin_audio.mp3
origin_srt <workdir>/origin_language_srt.srt
target_srt <workdir>/target_language_srt.srt
bilingual_srt <workdir>/bilingual_srt.srt
short_origin_mixed_srt <workdir>/short_origin_mixed_srt.srt
tts_audio <workdir>/tts_final_audio.wav
video_with_tts <workdir>/video_with_tts.mp4
horizontal_video <workdir>/horizontal_bilingual.mp4
vertical_video <workdir>/vertical_bilingual.mp4
transferred_vertical_video <workdir>/transferred_vertical_video.mp4
origin_cover <workdir>/origin_cover.jpg
generated_cover <workdir>/generated_cover.png
cover_prompt <workdir>/cover_prompt.final.txt

Horizontal and vertical dubbed variants use horizontal_dubbed.mp4 and vertical_dubbed.mp4; their manifest keys remain horizontal_video and vertical_video.

JSON Lines

Parse stdout one line at a time as JSON. The terminal response is the object containing ok.

When OPENCREATOR_KRILLINAI_CLI=1, subtitle and tts can emit progress frames before the terminal response:

{"type":"progress","phase":"translating_subtitles","percent":50,"message":"正在翻译字幕"}

Success shape:

{
  "ok": true,
  "stage": "subtitle",
  "workdir": "tasks/demo",
  "task_id": "demo",
  "outputs": {}
}

Failure shape:

{
  "ok": false,
  "error": {
    "kind": "retryable",
    "code": "audio_transcription_failed",
    "message": "connection timeout",
    "retryable": true
  }
}

Exit Codes

Code Meaning
0 Success
1 Usage error
2 Retryable error
3 Dependency error

Internal errors currently also exit with code 1, so use error.kind rather than the exit code alone for classification.

Error Handling

  • usage: fix flags or missing input.
  • retryable: retry after delay or switch provider/source.
  • dependency: install or expose ffmpeg, ffprobe, or yt-dlp.
  • internal: inspect logs and generated files.

Dry Run

  • subtitle, render-horizontal, render-vertical, speech, and pipeline validate without writing a task manifest.
  • tts and cover dry-runs apply default outputs and write krillinai_manifest.json, but do not produce media.
  • voices --dry-run returns the same local voice list without an external provider call; use aliyun, openai, or minimax.

Command-Shape Verification

This check does not need provider credentials or media dependencies:

(cd "$KRILLINAI_CWD" && "$KRILLINAI_CLI" subtitle local:demo.mp4 \
  --origin-lang en \
  --target-lang zh_cn \
  --workdir "$WORKDIR" \
  --dry-run)

For rendered media, inspect the output file and optionally extract preview frames with ffmpeg.