Read this in other languages: English · Deutsch · Nederlands · Tiếng Việt · Türkçe · bahasa Indonesia · español · français · italiano · polski · português do Brasil · svenska · čeština · ελληνικά · Русский · українська · עברית · اردو · العربية · فارسی · हिंदी · বাংলা · தமிழ் · తెలుగు · ไทย · 日本語 · 简体中文 · 繁體中文 · 한국어

README.md 的简体中文翻译。若此处内容与英文版有出入，以**英文版为准**。

翻译进度： 简介、「三大功能」、快速开始、《中文听写》、系统要求、主要特性、局限与常用命令已翻译；对比与替代方案、常见问题、配置、全部安装方式、开发等章节仍为英文。最后同步的英文源提交：40d3abd（2026-08-11）。

YazSes¶

⬇️ 安装¶

yazses quickstart
yazses start

Platform support — OS + CPU →

你的声音永远不会离开你的电脑。 离线语音听写：把语音直接输入到任何应用，转写录音文件，或者录下整场会议并生成带说话人姓名的纪要 —— 全部在你自己的 CPU 上完成。无需云端，无需 API key，无需订阅。

YazSes 是一个免费、开源、离线的语音听写与语音转文字守护进程，支持 Linux（X11 与 Wayland）、macOS 和 Windows，基于 faster-whisper 构建。当音频不能被上传到 Google、Apple、Microsoft 或 Otter 时使用它 —— 因为会议内容涉密、机器处于内网隔离状态，或者你只是不想再付订阅费。与 Wispr Flow 这类云端听写不同，YazSes 完全在本地设备上运行；与 Talon Voice 不同，它追求开箱即用，而非高级脚本定制。如果你需要的是对话式 AI 助手、开箱即用的非英语模型，或者移动端／网页版应用，那么 YazSes **并不适合**你。

📖 完整文档：mskazemi.com/yazses —— 安装指南、CLI 参考、配置、功能与故障排查。

40 秒演示：核心流程、命令行与系统托盘。终端输出是真实的；命令行输入为了清晰起见做了重新演示。 ▶️ 在 YouTube 上观看 —— 同一段演示，带章节。

三大功能¶

三者都在你的 CPU 上运行，全程无需联网。除非你明确要求保留，会议录音在转写后会被删除；说话人姓名来自你自己录入的声纹 —— 绝不来自任何云端账号。

哪些是可选的： 听写开箱即用。说话人标注需要 diarization 扩展（pipx install 'yazses[diarization]'，约 45 MB 模型，只需下载一次）；会议纪要还额外需要 notes 扩展以及你自行指定的本地 GGUF 模型。两者默认关闭 —— 详见离线会议纪要。

中文听写¶

结论先行：默认配置只支持英语。 YazSes 默认使用 base.en 模型，它是纯英语模型，在架构上**无法**解码中文 —— 它会把中文语音"音译"成看似流畅的英文乱码。要用中文听写，必须显式切换到多语言模型。

在 ~/.config/yazses/config.toml 中：

[stt]
model = "small"            # 多语言模型（不带 .en 后缀）；base / small / medium / large-v3
language = "zh"            # 中文
chinese_script = "simplified"   # 输出简体字；台湾／香港用户请设为 "traditional"

然后运行 yazses features enable chinese-script（会自动安装所需的 chinese 扩展），再运行 yazses restart。

为什么必须设置 chinese_script¶

Whisper 会**逐句**自行决定输出简体还是繁体，而且并不一致。在 20 段干净的 16 kHz 普通话语音（ASCEND 测试集，small 模型）上实测，其中 **13 段**返回的是繁体字 —— 即使识别本身是正确的。对大陆用户来说，这意味着说着简体中文，编辑器里却蹦出繁体字。

这个问题造成的损失比表面看起来大得多，因为**识别通常是对的，只是字形写错了**。以简体参考文本计算字错率（CER）：

同一批音频、同一个模型，只改了这一个配置项。这个设置对小模型的作用最大，而小模型正是 CPU 用户实际会用的那一档 —— small 提升 19 个百分点，large-v3 只提升 1 个百分点（大模型本身就更倾向输出简体）。详见 src/yazses/postprocess/han_script.py 与中文语音输入文档。

请如实看待精度¶

上述数据来自 ASCEND —— 这是**自然对话**语料，说话人带港式口音，且有中英夹杂，属于偏难的场景，样本量也只有 20 句。安静环境下用好麦克风朗读准确率会更好；嘈杂环境或口音较重时则会更差。模型大小是最有效的调节手段（large-v3 11.3% vs small 16.9%）。请先用 yazses transcribe 在你自己的录音上测一测，再决定是否投入使用。 模型越大越准，但 CPU 解码也越慢。

中文听写目前应视为**可用但仍需打磨**，欢迎提交实测结果与改进：opening an issue。

快速开始¶

想先听听它准不准，再决定要不要装？ 用 Docker 或直接在浏览器里试用 —— 无需安装，不留痕迹： 免安装试用。 仓库里自带一段音频，加上 --network none 就能证明转写确实发生在你自己的机器上。

第 1 步 —— 安装

推荐**的一行命令会：按需安装 uv，安装最新版 YazSes，配置所有系统依赖（音频、按键注入、剪贴板、input 用户组、Wayland 的 ydotoold），最后运行 **yazses doctor，让缺失的工具在安装过程中就暴露出来。APT 与 pipx 安装的是最近一次发布的版本。YazSes 也已上架 Snap Store（sudo snap install yazses）。

不放心把网上的脚本直接管道给 shell？ 完全合理。加上 --dry-run，它会检查你的机器、打印出所有将要做的改动，然后退出且不做任何修改： bash <(curl -fsSL .../install.sh) --dry-run

决定之前请先看：安装到底要付出什么代价（1.1 GB 加上 141 MB 模型，以及它对系统做的改动）和**如何卸载** —— 这两页都是有意提前公开的。

Shell 补全： yazses --install-completion（或用 yazses --show-completion 打印脚本）。详见 CLI 参考。

第 2 步 —— 配置系统 （Linux 专用，一条命令即可；APT 安装会自动完成）

yazses setup        # 安装音频与注入依赖，加入 input 组，配置 ydotoold
# 然后注销并重新登录（input 组变更需要重新登录才生效）

yazses setup 结束时会打印一份编号的**收尾清单**，列出只有你能完成的步骤 —— 重新登录以应用 input 组、校准你的声音（yazses mic-level --set）、以及 yazses start —— 并会主动询问是否立刻帮你完成麦克风校准。

注销／重新登录是必须的，且只需一次。 加入 input 组只在**新的登录会话**中生效 —— 仅仅新开一个终端标签页是**不够**的，因为它继承了旧会话的用户组，热键仍然无效。如果这一步尚未完成，yazses start 会给出提示。若不想注销就立刻开始听写，可以为单个会话临时切换组：sg input -c "yazses restart"。真正重新登录之后，直接运行 yazses start 即可。

yazses setup 会补齐听写所需的一切，且可以安全地重复运行 —— 它只做缺失的部分： - libportaudio2 —— 音频采集（缺失时守护进程启动会崩溃并报 OSError: PortAudio library not found）。 - 注入后端 —— xdotool/xclip（X11）以及 wtype/ydotool/wl-clipboard（Wayland）。 - input 用户组 —— 从内核读取按住说话热键所必需。 - ydotoold —— 虚拟输入守护进程。在 GNOME/KDE Wayland 上这是注入按键的*唯一*途径（wtype 在那里被禁用），因此 setup 会安装并启用它。

想手动完成？sudo apt install libportaudio2 xdotool ydotool wtype xclip wl-clipboard pipx && sudo usermod -aG input "$USER"，然后启用 ydotoold（见 install-linux）。随时可用 yazses doctor 验证 —— 你需要看到 [OK] Keyboard capture、[OK] Microphone 和 [OK] Injection。macOS/Windows 可跳过此步（按提示授予辅助功能／相关权限，见下文）。

第 3 步 —— 初始化

yazses quickstart           # 不确定下一步做什么？根据你的机器量身定制的 3 步指南
yazses doctor               # 检查麦克风、注入后端、权限（希望全部 [OK]）
yazses enroll               # 校准麦克风（约 30 秒）
yazses autostart enable     # 开机自启，重启后依然可用
yazses start                # 启动听写守护进程
yazses verify               # 说一句话，验证整条流水线确实可用

刚接触 YazSes？随时运行 yazses quickstart —— 它会检查已完成的配置，并告诉你接下来该做什么。它不会修改任何东西。

第 4 步 —— 开始使用 —— 按住热键，说话，松开。文字会被输入到当前焦点应用。

系统要求¶

主要特性¶

• 完全离线 —— 默认情况下音频与文字都不会离开本机；无需云服务、API 密钥或订阅
• 按住说话 —— 在 Linux、macOS、Windows 上直接输入到当前焦点应用
• 会议模式 —— 全程免手动录制，生成带发言人标注的文字记录，并可选用本地大模型生成会议纪要（摘要、决议、待办）；除非你选择保留，音频在转写后即被删除
• 离线文件转写 —— yazses transcribe <file> 可将任意音视频转成 txt/md/srt/vtt/json，并可选标注「谁说了什么」
• 语音命令 —— 通过正则语法（以及可选的小模型路由）执行编辑器/终端操作（撤销、保存、跳转行、运行测试、重命名等）
• 宏与个人词库 —— 自定义多步命令，并教会 YazSes 那些它总听错的词
• 不流畅友好模式 —— 可选地合并口吃与重复（b-b-because → because），面向口吃或构音障碍的使用者
• 自我改进 —— 可选、加密、留在本机的学习语料库；yazses tune 会根据你自己的修正提出准确率改进建议（不会有任何数据离开本机）
• 编辑器上下文 —— 可选的 Neovim / VS Code LSP 上下文，提升代码标识符的识别准确率
• 无障碍支持 —— VAD 校准向导、麦克风电平调节，以及面向运动障碍使用者的 EMG（肌电传感器）触发
• 语音活动浮层 —— 说话时在光标附近显示声呐式圆环（可选）

局限 / 什么情况下**不该**用 YazSes¶

• 它不是 LLM 智能体。 YazSes 负责听写文字、转写录音、执行编辑器与终端命令。它**不会**浏览网页、理解你的文件、设置提醒或与你对话。
• 发言人标注与会议纪要是附加功能，而非默认功能。 --diarize 与会议纪要各自需要额外安装可选组件（纪要还需要你自备本地 GGUF 模型）。普通听写与普通转写都不需要。
• 它是 CPU 上的 faster-whisper，不是云服务。 若你在嘈杂麦克风下追求绝对最低的词错误率，云端 STT 可能仍然更准；代价是数据要离开你的机器。
• 默认针对英语调优。 默认附带 *.en 系列 Whisper 模型；其他语言需要换用对应模型。中文用户请参见上文《中文听写》一节。
• 目前仅支持桌面端。 尚无可安装的移动端或网页版。Android 应用正在设计中 —— 架构与十份决策记录已公开在 docs/mobile，由贡献者公开协作开发。iOS/iPadOS 将在 Android 之后；macOS 已由本桌面应用支持。

常用命令¶

命令名、配置键与文件路径**一律保持英文原样** —— 翻译过的命令是不存在的命令。

参与贡献¶

🙌 想帮忙？ 从这里开始 —— 只有一页，找到与你条件匹配的那一行，15–45 分钟即可完成。无需申请许可，也没有任何任务被指派；欢迎使用编程 AI 助手，页面里有可直接复制的提示词。有几项任务**完全不需要 Python** —— 把 README 翻译成你的语言、把你的麦克风加入已验证列表，或者只是跑一跑然后告诉我们结果。#22 列出了所有待办事项。测试套件完全离线，约 30 秒跑完，所以你不需要麦克风、模型或 GPU 就能参与贡献。

中文相关的改进尤其欢迎 —— 无论是这份翻译的措辞、中文识别的实测数据，还是词汇表与标点处理。

以下章节仍为英文，请见 README.md：全部安装方式、功能列表、配置、语音命令、隐私说明与架构。

贡献者¶

感谢这些为 YazSes 出过力的朋友 ✨ —— 每一份 bug 报告、文档修正和补丁都算数。贡献类型遵循 all-contributors 表情说明（💻 代码 · 📖 文档 · 🌍 翻译 · ⚠️ 测试 · 🛡️ 安全 · 🚧 维护）：

Mohsen Seyedkazemi Ardebili 🚧 💻 📖	lntutor 📖	HeaTTap 💻	jackie-cqz 💻	Parinitha-26 📖	AshSgDe29071999 💻 📖	Maqbool Ahmed 💻
Renji 💻 ⚠️ 📖 🛡️ 🚇	Sebastian Legarraga 💻	YossiMH 🤔 🐛 🔬	Prithvi4904 🌍	4nmus 🌍	hari 📖	mercael 🚇

想上这面墙？认领一个 good first issue —— 第一个被合并的 PR 就能为你留一个位置。

引用¶

Seyedkazemi Ardebili, M. (2026). YazSes: An Offline, Privacy-First, Cross-Platform Hold-to-Talk Voice-Dictation System. arXiv:2607.28878. https://arxiv.org/abs/2607.28878

详见 CITATION.cff（CFF 1.2.0 机器可读元数据）。

许可证¶

Apache 2.0 —— 见 LICENSE。

如果 YazSes 对你有用，在 GitHub 上点一个 ⭐，并在你的项目、博客或分享中提一句，就是对它持续开发最好的支持。