面向 Windows 的本地优先语音听写助手，带有轻量、紧凑的顶部悬浮控制条。
Local STT 提供类似 Win+H 的跨应用听写体验：按下快捷键开始录音，再次按下完成当前片段，本地 Faster-Whisper 识别后自动粘贴回原来的输入窗口。
默认情况下，音频留在本机处理；可选的云端服务只接收本地识别完成后的文字，用于标点、术语和轻度文本校正。
- 本地语音识别：支持中文、英文和中英混合语音，默认使用 Faster-Whisper small 模型；
- 紧凑悬浮控制条：黑色顶部小刘海风格，约
325×50，包含动态柔光球、状态文字、计时、音波和进度提示； - 流畅状态切换：录音、识别、粘贴、暂停和错误状态使用弹簧式尺寸、配色和内容过渡；
- 跨应用粘贴：自动记住开始录音时的目标输入窗口，不需要手动切换焦点；
- 双快捷键操作：
Ctrl+F1控制完整听写会话，Ctrl+↓控制暂停与继续； - 术语表：通过
technical_terms.txt固定产品名、英文术语和专有名词的标准拼写； - 可选文字增强：支持 OpenCode Go 主通路与 DeepSeek 备用通路，仅处理本地识别后的文字；
- 后台运行：可以作为 Windows 开机启动项运行，无托盘图标、无控制台窗口。
Ctrl+F1
│
├─ 捕获当前输入窗口
├─ 打开录音与悬浮控制条
├─ 再次按下后停止当前片段
├─ 本地 Faster-Whisper 转写
├─ 可选：文字标点与术语校正
└─ 粘贴回原输入窗口
local-stt/
├─ app/ # 核心应用代码
│ ├─ main.py # 应用控制器与会话流程
│ ├─ floating_bar.py # 悬浮条 UI、字体与动画
│ ├─ audio.py # 麦克风录音
│ ├─ transcriber.py # Faster-Whisper 识别与分段处理
│ ├─ text_enhancer.py # 可选文字校正
│ ├─ worker.py # 后台识别任务
│ ├─ paste.py # 目标窗口捕获与粘贴
│ ├─ hotkey.py # Windows 全局快捷键
│ ├─ state_machine.py # 听写状态机
│ └─ config.py # 模型、快捷键与环境变量配置
├─ scripts/ # Windows 启动项脚本
│ ├─ install_startup.ps1
│ └─ uninstall_startup.ps1
├─ tests/ # 单元测试
├─ background.pyw # 无控制台后台入口
├─ main.py # 保留兼容性的调试入口
├─ technical_terms.txt # 自定义术语表
├─ requirements.txt # Python 依赖
├─ .env.example # 环境变量参考
└─ README.md
根目录的 main.py 和 background.pyw 是有意保留的薄入口，方便现有快捷方式、开机启动项和调试命令继续使用；实际实现集中在 app/ 中。
- Windows 10 或 Windows 11；
- Python 3.11 或更新版本；
- 可用麦克风；
- 首次准备 Faster-Whisper 模型时需要网络。
git clone https://github.com/Elong-svg/local-stt.git
cd local-stt
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt默认模型目录为仓库下的 models\faster-whisper-small。请使用 Faster-Whisper / Hugging Face 的公开模型下载方式，将 Systran/faster-whisper-small 保存到该目录。
也可以通过用户环境变量指定其他模型目录：
[Environment]::SetEnvironmentVariable(
'LOCAL_STT_MODEL',
'D:\models\faster-whisper-small',
'User'
)模型文件不会提交到 GitHub，.gitignore 已排除 models/。
| 操作 | 快捷键 | 说明 |
|---|---|---|
| 开始/结束听写会话 | Ctrl+F1 |
开始录音；再次按下完成当前会话 |
| 暂停并粘贴 | Ctrl+↓ |
停止当前片段、识别并粘贴 |
| 继续录音 | Ctrl+↓ 或点击悬浮条 |
继续使用原来的目标输入窗口 |
| 完成当前片段 | 点击悬浮条 | 识别并粘贴当前录音 |
保留控制台输出，适合查看启动和识别日志：
.\.venv\Scripts\python.exe main.py无控制台、无托盘图标地启动：
Start-Process `
-FilePath (Join-Path $PWD '.venv\Scripts\pythonw.exe') `
-ArgumentList (Join-Path $PWD 'background.pyw') `
-WorkingDirectory $PWD `
-WindowStyle Hidden安装当前 Windows 用户的开机启动项：
.\scripts\install_startup.ps1 -PythonwPath (Join-Path $PWD '.venv\Scripts\pythonw.exe')移除启动项：
.\scripts\uninstall_startup.ps1.env.example 仅作为配置参考，程序不会自动加载 .env 文件。请使用 Windows 用户环境变量，设置后重启后台程序。
| 变量 | 默认值 | 作用 |
|---|---|---|
LOCAL_STT_MODEL |
models\faster-whisper-small |
Faster-Whisper 模型目录 |
LOCAL_STT_LANGUAGE |
auto |
识别语言，可设为 zh、en 或 auto |
LOCAL_STT_TERMS_FILE |
technical_terms.txt |
自定义术语表路径 |
LOCAL_STT_TEXT_ENHANCEMENT |
1 |
是否启用文字校正，设为 0 可关闭 |
LOCAL_STT_TEXT_API_KEY |
空 | 文字校正主通路 API key |
DEEPSEEK_API_KEY |
空 | 主通路失败时使用的备用 API key |
OPENCODE_API_KEY 仍然兼容，可作为 LOCAL_STT_TEXT_API_KEY 的旧配置名使用。音频不会发送到这些 API；云端只会收到本地识别后的文字。
[Environment]::SetEnvironmentVariable('LOCAL_STT_TEXT_API_KEY', '你的 OpenCode key', 'User')
[Environment]::SetEnvironmentVariable('DEEPSEEK_API_KEY', '你的 DeepSeek key', 'User')OpenCode Go 使用 mimo-v2.5 作为主通路，超时或失败时自动切换到 DeepSeek 官方的 deepseek-v4-flash；两条通路都失败时回退到本地识别结果。请不要把 key 写入代码、.env 文件或提交到 GitHub。
编辑 technical_terms.txt，每行写一个希望保留的标准拼写；# 后面的内容会被当作注释。修改后重启后台程序。
运行现有单元测试：
.\.venv\Scripts\python.exe -m unittest discover -s tests -p "test_*.py" -v检查应用代码语法：
Get-ChildItem app -Filter *.py | ForEach-Object {
.\.venv\Scripts\python.exe -m py_compile $_.FullName
}修改悬浮条视觉层后，建议额外检查录音、识别、粘贴、暂停、错误五种状态，以及快速连续切换时窗口是否保持居中。
悬浮条采用“顶部小刘海”方向：
- 纯黑、低干扰的横向托盘；
- 顶部直边与屏幕顶部贴合；
- 下方保留克制圆角；
- 动态柔光球承担主要视觉焦点；
- 文字保持中性白色，英文使用 Times New Roman，中文使用 Microsoft YaHei；
- 音波固定在右侧，以低透明度光晕和亮度变化表现动态。
- 本地语音识别默认在 CPU 上运行；
- 本项目不会自动上传录音；
- 云端文字校正是可选功能，使用第三方 API 时请自行确认服务条款和数据政策；
- small 模型对诗歌、古文、强口音和嘈杂环境的识别能力有限。
- 完成顶部小刘海式悬浮条；
- 调整为
325×50的更宽、更薄比例； - 优化动态柔光球，移除黑色边缘液态效果；
- 保持录音、识别、粘贴、快捷键和窗口焦点行为不变；
- 将应用代码、测试和启动脚本按职责分目录管理。
MIT License，详见 LICENSE。