2026-04-09

发布时间 : 2026-04-21 01:00

04月09日

04月09日

一、今日完成情况

✅ 调研 SKILL PPT 插件
✅ 遍历市面语言流式软件，评估可用性
✅ 自主开发语言流式系统（火山引擎 ASR + Hammerspoon 快捷键控制），实现端到端语音转文字输入

二、今日感悟

核心业务数据：
- 完成 5 个核心模块开发：音频采样、识别协议、流式演示、守护服务、系统集成
- 打通端到端链路：麦克风 → PCM 流式 → 火山引擎 ASR → 文本 → 输入框
- 建立 HTTP 守护服务（端口 8765），提供 /start /stop /status 接口
- 实现 Option+V 全局快捷键控制，Phase 1 版本可稳定工作
今日工作总结：
- 协议对接：跑通火山引擎 SAUC WebSocket 双向流式通信，实现 bigmodel_nostream 和 bigmodel_async 两种模式，补齐 4 项鉴权 Header
- 音频处理：开发实时音频采样模块（16kHz/单声道/16-bit PCM），解决 WAV 格式错误问题，改用 PCM 流式传输避免 invalid WAV file format
- 服务架构：创建常驻守护服务 asr_daemon.py，实现状态机与互斥锁，避免 start/stop 冲突，Phase 1 策略为停录后一次性返回最终文本
- 系统集成：通过 Hammerspoon 实现全局快捷键（Option+V）控制录音和文本注入，验证 macOS Accessibility 权限，文本通过 hs.eventtap.keyStrokes() 注入到当前输入框
- 工程实践：使用虚拟环境解决 Homebrew Python PEP 668 限制，配置 .env 管理密钥，完善 .gitignore 避免敏感信息入库
- 问题排查：解决 init.lua 配置污染问题，定位 Option+V 可能的冲突点（Secure Input 拦截）
明日工作计划（基于今日 Phase 1 完成的连续性优化）：
- Phase 1.1：优化识别准确率
  - 调试音频参数（采样率、分包时长）降低误识率
  - 实现噪音过滤与声学优化
  - 测试不同场景（安静环境、背景噪音）下的识别效果
- Phase 1.2：完善用户反馈
  - 添加录音状态可视化（菜单栏图标 / 通知提示）
  - 实时显示识别进度（partial 结果预览）
  - 错误场景降级提示（网络失败 / 权限缺失）
- Phase 2：功能扩展与体验提升
  - 多语言识别切换（中文/英文自动检测）
  - 智能标点添加（基于语音停顿）
  - 文本二次编辑功能（退格删除整段）
今日学习成长：
- 协议层：掌握火山引擎 SAUC WebSocket 协议细节（鉴权机制、包格式、PCM 流式传输）
- 系统层：深入理解 macOS 权限模型（Accessibility、Secure Input），学会处理系统级输入拦截问题
- 自动化：熟练运用 Hammerspoon 进行 macOS 系统级自动化开发（快捷键、文本注入、状态控制）
- 架构设计：实践状态机模式在守护服务中的应用，理解互斥锁防止并发冲突的重要性
- 音频处理：掌握 PCM/WAV 音频格式差异，理解实时采样的缓冲区设计

三、备注

项目代码仓库：luduihang/realtime-whisper

四、项目技术架构

4.1 系统总览

用户语音 → 麦克风采样 → PCM 流式 → 火山引擎 ASR → 最终文本 → Hammerspoon 注入 → 当前输入框
         ↑                                        ↓
    realtime_audio.py                       asr_daemon.py (端口 8765)
                                              (HTTP 服务)
         ↑                                        ↑
    Hammerspoon (Option+V) ←─────────────┘

4.2 核心模块

模块	文件	功能
音频采样	`realtime_audio.py`	16kHz/单声道/16-bit PCM 实时采集
识别协议	`sauc_websocket_demo.py`	火山引擎 SAUC WebSocket 双向流式通信
流式演示	`realtime_asr_stream_demo.py`	麦克风→WebSocket 端到端测试
守护服务	`asr_daemon.py`	HTTP API 服务（/start, /stop, /status）
系统集成	`~/.hammerspoon/init.lua`	全局快捷键控制与文本注入

4.3 技术栈

后端：Python 3 + asyncio + aiohttp
音频处理：sounddevice + numpy（PCM 编解码）
云服务：火山引擎 SAUC 流式语音识别
系统自动化：Hammerspoon（Lua）
配置管理：python-dotenv + .gitignore

4.4 已知问题

Option+V 输入 √：热键回调未触发（配置错误 / Secure Input 拦截）
配置污染：init.lua 语法错误需手动修复并 Reload Config

五、配置资源

5.1 火山引擎控制台

语音识别控制台

5.2 Hammerspoon 配置恢复

当 Dock 图标和菜单图标均禁用时，可通过以下方式重新打开设置窗口：

# 方法1：Spotlight 搜索 "Hammerspoon"
# 方法2：终端运行
open -a Hammerspoon
# 然后按 Command + Comma 打开 Preferences

5.3 .env 配置示例

VOLC_ASR_WS_URL=wss://openspeech.bytedance.com/api/v2/asr
VOLC_ASR_RESOURCE_ID=your_resource_id
VOLC_ASR_APP_KEY=your_app_key
VOLC_ASR_ACCESS_KEY=your_access_key
VOLC_ASR_SEG_DURATION_MS=200

个人心得：无他，唯手熟尔。

转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论，也可以邮件至 kipleyarch@gmail.com