# Mimi 使用说明

[返回 README](../README.md)

[English](usage.md) · [简体中文](usage.zh-CN.md) · [繁體中文](usage.zh-TW.md) · [日本語](usage.ja.md) · [ภาษาไทย](usage.th.md) · [한국어](usage.ko.md) · [Français](usage.fr.md) · [Deutsch](usage.de.md)

各家服务的开通入口、凭证字段和当前模型，见[服务开通指南](provider-setup.zh-CN.md)。

按需要查阅：

- [安装与更新](#start)
- [字幕显示](#subtitles)
- [音频与保存记录](#saving)
- [识别错误](#errors)

旧版将「模型与服务」称为「语音与翻译」。

<a id="start"></a>

## 安装与更新

1. 从 [Latest Release](https://github.com/yuxino/mimi/releases/latest) 下载 macOS Apple Silicon 或 Intel DMG，Windows x64 EXE、MSI、绿色版 ZIP，或 Linux x86_64 .deb / AppImage；也可以从源码构建。
2. 打开「设置 → 模型与服务」，添加配置，按提示填入服务商凭证并保存，再选择识别和翻译语言。
3. 播放内容，在「字幕」页开启「实时字幕」，也可从菜单栏/系统托盘的 mimi 图标打开系统菜单，点击「开始字幕」。macOS 14.2 及以上，采集「全部应用」或指定单个应用均支持「仅系统录音」权限；已有录屏授权会继续复用，无需另外授予仅系统录音权限。macOS 13–14.1 需要「录屏与系统录音」权限。

mimi 托盘图标使用系统菜单，提供开始／停止字幕、字幕显示、设置和退出；macOS 另有「在 Dock 中显示」。服务、语言、锁定和沉浸模式在设置窗口调整。符合条件的 Mac 可使用免费的 Apple 本地语音识别，无需 API 密钥；按提示准备语言资源，文字翻译服务另行选择。

使用云服务时，需自备服务商 API 凭证，调用可能产生费用。桌面端凭据保存在由文件权限保护的本机私有明文文件中。

macOS、Windows 安装版和 Linux AppImage 更新时，打开 设置 → 通用 → 版本更新。Mimi 会显示下载进度，下载完成后可直接安装。
Windows 安装完成后会重新打开 Mimi；macOS 和 Linux AppImage 可点击 重新启动并完成更新。
早于 v1.3.8 的旧版本需要先手动安装一次，之后即可在应用内更新。

三方识别怎么填、该选自动还是具体语言，请看[语音服务配置与语言参数](speech-language-setup.md#中文)：包含 WebSocket 示例、参数含义和各接入的当前范围。

### 平台支持

- macOS 13+（Apple 芯片和 Intel）：Apple 芯片选择 `_aarch64.dmg`，Intel 选择 `_x64.dmg`。从 v1.4.4 起提供 Intel 包，已通过构建和签名检查，Intel 实机采集和权限行为仍待验证。提供未经 Apple 公证的 DMG；若首次打开被拦截，请在「系统设置 → 隐私与安全性」中选择「仍要打开」。从旧版本升级时，请留意下方的权限说明。
- Windows x64：提供未签名的预览版 EXE / MSI；从 v1.4.3 起还提供绿色版 ZIP。SmartScreen 可能显示提示。下载 `mimi_<version>_x64-portable.zip` 解压后，直接运行 `mimi.exe`。电脑需已安装 WebView2（Windows 11 通常自带）。ZIP 不会把设置、服务凭证或已导出文件搬到自身目录；设置和私有凭据文件仍保存在应用的用户目录，导出文件保存在你选择的位置。更新绿色版时，先退出 Mimi，再从 Releases 下载新版 ZIP 替换；绿色版不会运行应用内安装器更新。

- Linux x86_64 预览版（以 Ubuntu 22.04+ 为基线）：提供 `.deb` 和 AppImage。需要 PulseAudio 或启用了 `pipewire-pulse` 的 PipeWire、可用的默认输出设备，以及对本机私有凭据文件的访问权限。系统音频只使用输出设备的监听源。切换输出设备后请重新开始会话。建议使用 X11；Wayland 的窗口定位、置顶和点击穿透可能受桌面环境限制；快捷键请使用 Mimi 设置里显示的命令，在系统键盘设置中配置。没有托盘图标时可从设置窗口操作；最小化会继续运行，关闭设置窗口则退出 Mimi。暂不提供 Linux ARM64 安装包。详见 [Linux 安装与验证（英文）](development/linux.md)。

### macOS 系统录音权限

macOS 14.2 及以上，新安装采集「全部应用」或指定单个应用时会请求「仅系统录音」。如果已有旧授权并希望切换，先退出 Mimi，在「系统设置 → 隐私与安全性」中移除或关闭它的「录屏与系统录音」授权，再重新打开 Mimi 并启动字幕，按提示允许「仅系统录音」，或在该分组中开启 Mimi。系统要求重启应用时，请重启。切换是可选的，已有录屏授权可以继续使用。未获得录音授权时，可从错误提示打开系统权限页，授权并按系统提示重启 Mimi 后重试。

### macOS 更新后重复授权

发布流程现已要求 macOS 各版本沿用同一张固定自签名证书。v1.4.1 及更早的发布版使用随构建变化的临时签名；首次升级到固定身份的版本时，可能需要重新授予一次录音权限。源码中的修复不会改变已经安装的旧版本。固定签名消除了每次构建更换身份的原因，但不代表 macOS 永远不会再询问授权。删除本地签名证书不会改变已安装应用的身份，也不能解决这个问题。正式版请放在 `/Applications/mimi.app`，开发测试使用 `/Applications/mimi-dev.app`。两者各自保留签名配置和录音授权；开发版不能继承正式版变更后的签名身份。

录音权限已开启，但 Mimi 仍提示无权限：先退出并重新打开 Mimi，按正常提示授权。如果仍无法采集：

1. 退出出现问题的应用。打开「系统设置 → 隐私与安全性 → 录屏与系统录音」（名称随 macOS 版本略有不同），只选中并移除对应的旧条目：正式版为 **mimi**，开发版为 **mimi-dev**。
2. 点击 +，重新添加对应的 `/Applications/mimi.app` 或 `/Applications/mimi-dev.app` 并开启权限；系统要求认证时由你本人完成。保留另一版本和其他应用的条目。
3. 重新打开同一个应用，用快捷键或开始按钮开启字幕，播放带人声的音频，确认实际出现字幕。仅看到权限开关开启，不代表已经恢复。

这里移除的是旧录音授权，不是证书或 API Key。尝试一次仍未恢复，请停止反复重置，携带 macOS 版本、Mimi 版本、安装来源和错误提示[反馈问题](https://github.com/yuxino/mimi/issues)，不要附带 API Key 或字幕内容。

桌面端凭据保存在由文件权限保护的本机私有明文文件中。旧系统凭据会自动迁移一次，校验保存成功后删除原条目；迁移时可能需要授权读取旧凭据，完成后切换、保存和更新均只使用本地文件。文件丢失或损坏也不会退回钥匙串。`codesign` 请求访问开发签名私钥属于独立的构建时弹窗。

## 服务配置

桌面端每个服务配置都可保存识别与翻译语言组合。先启用配置并选择语言，再到「设置 → 模型与服务」打开配置详情，点击「**记住当前语言组合**」。需要修改或移除时，显式点击「**更新为当前语言**」或「**取消绑定**」。

切换或重新应用配置时，会恢复其已保存的组合；临时更改语言不会覆盖它。悬浮控制面板会在配置名下方显示保存的组合。点击字幕顶部的服务信息，可打开当前配置详情。

<a id="saving"></a>

## 音频与保存记录

桌面端默认使用系统声音，可在设置或悬浮控制中选择系统声音、麦克风，或同时开启两路。麦克风使用系统默认输入设备，实际开始采集时才按需申请权限。双路各自建立识别连接、显示字幕并产生服务用量。更换来源会关闭音频录制，需要时请在「保存与导出」重新开启。

macOS 和 Windows build 20348+ 可通过应用选择器，选择要翻译的应用声音。Linux 采集系统输出监听通道，不提供应用选择器。

在「设置 → 保存与导出」选择保存字幕或录制已选择的音频来源。两个开关默认关闭；开启后随会话写入本机私有文件，系统声音与麦克风音频分别保存。关闭开关会清空本次对应内容，已保存的记录需自行删除。

开始下一次桌面会话时，会保留当前屏幕内有数量限制的已确认字幕，点击清空可移除。这不会开启字幕保存、把旧字幕复制到新会话的保存记录中，也不会在退出应用后恢复未保存的字幕。

字幕最多保留 10,000 条已确认记录／2 MiB 文字，音频最多 64 MiB。达到上限会停止保留并提示。字幕时间戳是确认时间；WAV 不含暂停和重连间隙，两者不能直接对齐。

<a id="subtitles"></a>

## 字幕显示

在「设置 → 通用」选择桌面界面语言：简体中文、繁体中文、英语、日语、德语、韩语、法语或泰语。「跟随系统」会使用对应系统语言；切换界面语言会保留当前编辑内容和字幕状态。识别和翻译语言需分别选择。

桌面端可在设置中点选五种预设色块（默认白色），或点击预设后面的自定义色块打开系统调色板。系统声音与麦克风分别设置颜色。预览与悬浮字幕立即更新，沉浸模式同样生效。双语模式下，原文以更柔和的明暗层级与译文区分。

字幕设置和悬浮控制中的「显示时间」默认关闭。开启后，系统声音和麦克风的已确认字幕旁都会显示本机确认时间（HH:mm:ss），沉浸模式同样生效。它表示字幕确认的时刻，不是说话的起点。切回系统声音后，保留的麦克风字幕仍带一个小来源图标。悬浮控制也提供暂停／继续。

在设置、浮窗控制面板或托盘中选择 仅译文、原文＋译文 或 仅原文。
macOS 使用 ⌘⇧B，Windows/Linux X11 使用 Ctrl+Shift+B 快速切换，不会中断翻译。Wayland 请在系统设置中为 `mimi --cycle-subtitle-display` 绑定快捷键。
双语模式成对显示已确认的原文与译文，等待翻译时先预览识别到的原文。

开启「更早显示字幕」时，浮窗会显示仍可能修改的草稿；关闭后等待确认结果，
连续讲话可能需要等更久。这个显示选项不会把草稿变成已保存的历史。

<a id="errors"></a>

## 识别错误

识别失败时，浮窗会保留已有字幕并持续显示原因。展开悬浮控制面板可查看
完整说明和恢复操作。已识别的配置错误提供「模型与服务」设置入口，临时
连接或服务故障提供重试。修正或切换相关配置后，失败的会话返回待机，
不会自动开始采音；准备好后再开启「实时字幕」。

## 更多文档

[贡献指南（中英）](../.github/CONTRIBUTING.md) · [安全与隐私（中英）](../.github/SECURITY.md) · [平台差异与验证范围（英文）](development/platform-parity.md)