kandong

项目概述

看懂由开发者 dvdmaru 维护，是 mpv 生态里专做台湾繁中双语字幕的一层播放器外壳。播放外语片时它在原文字幕下方追加繁中译文；没有字幕的片，先用 whisper.cpp 把音轨听写成字幕再翻译。翻译与语音识别都跑在本机，影片与字幕不上传，仓库本身也不提供片源、不下载字幕。

项目	内容
平台	Windows 10/11 64 位、macOS（Apple 芯片）
播放核心	mpv + uosc 5.13.0
翻译模型	Hy-MT2 7B（约 4.6GB）或 1.8B（约 1.1GB）
当前版本	0.3.0
许可	MIT

片照常播，字幕自己在旁边变成你看得懂的语言。

主要功能

• 双语字幕：.srt、.ass、.vtt 外挂字幕或 mkv 内嵌文字字幕，都在原文下方叠加繁中译文
• 整片预译：开播前先把整部字幕翻完，播放时不必一句一句等
• 无字幕听写：音轨交给 whisper.cpp 识别出字幕，再走同一套翻译流程
• 译文缓存：结果写在影片同目录的 影片名.ft.zh-TW.json 与 影片名.srt，重看不重翻
• 台湾用语：提示词按台湾繁中调整，口语、俚语与运动术语走意译而非逐字直翻
• 模型管理：右键 → 设定 → 翻译模型与伺服器，可下载、切换模型或指定自己的 GGUF
• 外接翻译服务：可连 Ollama、LM Studio 或区网另一台机器的 OpenAI 相容端点

播放与操作

操作	作用
鼠标右键	播放、字幕、音讯、翻译、倍速、设定菜单
Ctrl+t	翻译开 / 关
← / →	后退 / 前进 5 秒，按住 Shift 为 30 秒
1–5	倍速 0.5x / 1x / 1.5x / 2x / 3x
D / A / S	加速 10% / 减速 10% / 回到 1x
↑ / ↓	音量 ±5%
v	隐藏原文字幕，只看译文
空格 / f / q	暂停 / 全屏 / 退出

模型与翻译服务

• 内建下载：7B、1.8B 与 Whisper large-v3-turbo（q5_0，约 574MB）都能在播放器里下载，支持续传与 SHA256 校验
• 模型来源：models 文件夹、~/.cache/kandong/models 与 LM Studio 的模型目录都会被自动列出
• 本机端点：字幕送到 http://127.0.0.1:8080 的 /v1/chat/completions，由 server/start-translate-server.sh 拉起 llama.cpp
• 共用模型：语音辨识模型放在 ~/.cache/twtools/models/，与 Echoic 离线版共用一份，不重复下载
• 设定落盘：模型选择记在 script-opts/kandong_settings.conf，伺服器地址在 floattranslate.conf

适用人群

• 常看外语片、需要繁中字幕的人
• 拿到无字幕片源也想直接看懂的人
• 习惯 mpv 但不想自己写配置的用户
• 在意隐私、不接受上传字幕的人

快速上手

1. 解压 KanDong-windows-x64.zip 或 KanDong-mac.zip；Mac 版先执行 brew install mpv ffmpeg llama.cpp whisper-cpp
2. 双击「看懂」（Mac 为「看懂.command」），启动器先开翻译引擎，再开播放器
3. 右键 → 设定 → 翻译模型与伺服器，点「下载」取模型，首次使用必须先做这一步
4. 把影片拖进播放器窗口，有文字字幕的片会先整片翻好再播
5. 看无字幕影片时，把 Whisper 模型放进 models 或共用目录，播放时自动启用听写
6. 伺服器在另一台机器时，选「连到其他翻译伺服器」填网址与 API key，会先试翻一句再切换

系统要求

项目	要求
操作系统	Windows 10/11 64 位；macOS（Apple 芯片）
内存	7B 模型建议 16GB 以上，1.8B 约 8GB 可跑
磁盘	模型占 574MB～4.6GB，另需存放译文字幕的空间
运行时依赖	Windows 包已含 mpv、FFmpeg、llama.cpp、whisper.cpp；Mac 用 Homebrew 安装
字幕范围	mpv 支持的文字字幕轨，不含 PGS 等图形字幕识别

注意事项

• 图形字幕不识别：蓝光 PGS 一类图形字幕不做 OCR，这类片只能走语音辨识
• 人名多为音译：Marcus 之类人名常被译成音近汉字，换更大的模型也一样
• 串流平台用不上：不下载字幕、不拦截串流、不破 DRM，Netflix 一类服务拿不到字幕轨
• Windows 端验证较少：设定菜单的下载与换模型只在 Mac 实机跑通过，Windows 上行为可能不同