kandong

Project Overview

KanDong is maintained by developer dvdmaru as an mpv-based player front end focused on Traditional Chinese dual subtitles. For foreign-language films it appends a Traditional Chinese translation under the original subtitle line; when a film has no subtitles at all, whisper.cpp transcribes the audio track first and the same pipeline translates it. Translation and speech recognition both run locally, nothing is uploaded, and the repository ships no video content and downloads no subtitles.

Item	Value
Platform	Windows 10/11 64-bit, macOS (Apple silicon)
Playback engine	mpv + uosc 5.13.0
Translation models	Hy-MT2 7B (about 4.6GB) or 1.8B (about 1.1GB)
Current version	0.3.0
License	MIT

The film plays as usual while the subtitles quietly turn into a language you read.

Key Features

• Dual subtitles: .srt, .ass and .vtt sidecar files or embedded mkv text tracks all get a translated line underneath
• Whole-film pre-translation: the entire subtitle file is translated before playback, so you never wait line by line
• Transcription when subtitles are missing: whisper.cpp turns the audio into subtitles that feed the same translation flow
• Translation cache: results land next to the video as name.ft.zh-TW.json and name.srt, so rewatching costs nothing
• Taiwanese phrasing: prompts are tuned for Traditional Chinese as used in Taiwan, preferring idiomatic renderings of slang and sports terms
• Model management: right-click, then Settings, then Translation model and server, to download, switch, or point at your own GGUF
• External translation service: connect to Ollama, LM Studio or an OpenAI-compatible endpoint on another machine

Playback and Controls

Control	Action
Right click	Playback, subtitle, audio, translation, speed and settings menus
Ctrl+t	Toggle translation on or off
Left / Right	Seek back or forward 5 seconds, 30 seconds with Shift
1-5	Speed 0.5x / 1x / 1.5x / 2x / 3x
D / A / S	Speed up 10% / slow down 10% / back to 1x
Up / Down	Volume plus or minus 5%
v	Hide the original line and keep only the translation
Space / f / q	Pause / full screen / quit

Models and Translation Service

• Built-in downloads: 7B, 1.8B and Whisper large-v3-turbo (q5_0, about 574MB) download inside the player with resume and SHA256 checks
• Model discovery: the models folder, ~/.cache/kandong/models and LM Studio's model directory are listed automatically
• Local endpoint: subtitles go to /v1/chat/completions on http://127.0.0.1:8080, with llama.cpp started by server/start-translate-server.sh
• Shared models: speech models live in ~/.cache/twtools/models/ and are shared with the offline Echoic tool instead of downloaded twice
• Persisted settings: the chosen model is stored in script-opts/kandong_settings.conf, the server address in floattranslate.conf

Target Audience

• Frequent foreign-film viewers who need Traditional Chinese subtitles
• People with subtitle-less releases who still want to follow the plot
• mpv users who would rather not hand-write configs
• Viewers who care about privacy and will not upload subtitles

Quick Start

1. Extract KanDong-windows-x64.zip or KanDong-mac.zip; on macOS first run brew install mpv ffmpeg llama.cpp whisper-cpp
2. Double-click KanDong (KanDong.command on macOS); the launcher starts the translation engine before the player
3. Right-click, open Settings, then Translation model and server, and click Download; this first step is required
4. Drag a video into the player window; films with text subtitles are translated in full before playback
5. For subtitle-less films, place a Whisper model in models or the shared folder and transcription starts automatically
6. If the server runs elsewhere, choose the external server option, enter the URL and API key, and the player tests one line before switching

System Requirements

Item	Requirement
OS	Windows 10/11 64-bit; macOS on Apple silicon
Memory	16GB or more for the 7B model, about 8GB for 1.8B
Disk	574MB to 4.6GB for models, plus room for translated subtitle files
Runtime	The Windows bundle includes mpv, FFmpeg, llama.cpp and whisper.cpp; macOS installs them via Homebrew
Subtitle scope	Text subtitle tracks mpv can read; PGS and other image subtitles are out of scope

Notes

• Image subtitles are not recognized: PGS and similar bitmap subtitles get no OCR, so those films fall back to speech recognition
• Names are usually transliterated: names such as Marcus become phonetically similar characters, even with a larger model
• Streaming services do not benefit: no subtitle downloading, no stream interception, no DRM circumvention, so Netflix-style services are out
• Less validation on Windows: the download and model-switch menus were only exercised on real Mac hardware, so Windows behavior may differ