docs(ios): plan PiP voice session lifecycle
Define a phased, privacy-first path for keeping keyboard dictation responsive while releasing the microphone between utterances.
This commit is contained in:
Rocky
@@ -0,0 +1,385 @@
|
||||
# iOS PiP 语音会话保活规划
|
||||
|
||||
> **文档状态**：产品与架构规划（待验证，未进入实现）
|
||||
> **适用范围**：iOS 主 App + 键盘扩展 + Live Activity
|
||||
> **目标版本**：待产品验证后确定
|
||||
> **创建日期**：2026-07-26
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
### 1.1 目标
|
||||
|
||||
在不要求 OSGKeyboard 长时间占用麦克风的前提下，尽量保持主 App 可响应键盘扩展的听写指令，降低用户在宿主 App 与 OSGKeyboard 之间反复切换的频率。
|
||||
|
||||
核心方向是将两个当前耦合的能力拆开：
|
||||
|
||||
1. **会话可用性**：主 App 仍可接收键盘命令。
|
||||
2. **麦克风采集**：仅在用户明确开始听写时启用，完成后立即释放。
|
||||
|
||||
PiP（画中画）只承担系统可见的多任务会话载体，不绕过麦克风授权，也不应使用静音音频循环伪造后台活动。
|
||||
|
||||
### 1.2 核心结论
|
||||
|
||||
| 决策 | 规划选择 |
|
||||
|------|----------|
|
||||
| 产品定位 | 将 PiP 作为可选的「免切换模式」，不替代普通 Flow |
|
||||
| 麦克风策略 | PiP 空闲时关闭；键盘点按听写后按需激活 |
|
||||
| 默认策略 | 保留当前隐私友好的 5 分钟 Flow；PiP 由用户主动开启 |
|
||||
| 降级路径 | PiP 不可用或失效时回落到现有 `startflow` 冷启动流程 |
|
||||
| 状态展示 | PiP 显示有意义的语音会话状态；Live Activity 继续负责锁屏与灵动岛 |
|
||||
| 禁止方案 | 不播放静音文件保活，不使用定位或 VoIP 等无关后台模式 |
|
||||
| 上线方式 | 先做真机技术验证和 TestFlight 审核验证，再决定正式产品化 |
|
||||
|
||||
### 1.3 非目标
|
||||
|
||||
- 不让键盘扩展直接访问麦克风；这是 iOS 平台限制。
|
||||
- 不承诺 App 被用户强制退出后仍可免切换听写。
|
||||
- 不承诺电话、Siri、相机或其他录音 App 抢占音频设备时继续录音。
|
||||
- 不用 PiP 绕过麦克风权限、隐私提示或系统音频策略。
|
||||
- 第一阶段不重写 ASR、润色、App Group 或 Darwin 通知管线。
|
||||
|
||||
---
|
||||
|
||||
## 2. 问题定义
|
||||
|
||||
### 2.1 平台约束
|
||||
|
||||
iOS 键盘扩展无法直接申请或使用麦克风。系统级语音键盘因此必须采用：
|
||||
|
||||
```text
|
||||
键盘扩展
|
||||
→ 发送开始/停止命令
|
||||
→ 主 App 采集并转写
|
||||
→ App Group 返回结果
|
||||
→ 键盘插入文本
|
||||
```
|
||||
|
||||
当主 App 被系统挂起或终止时，键盘无法即时启动录音，只能打开主 App 重新建立会话。当前 Flow 通过持续运行 `AVAudioEngine` 输入链路换取后台可用性，但会带来麦克风长期占用、橙色隐私指示、电量消耗和音频冲突。
|
||||
|
||||
### 2.2 用户问题
|
||||
|
||||
| 用户感知 | 当前根因 | 目标变化 |
|
||||
|----------|----------|----------|
|
||||
| 频繁跳转主 App | 后台主进程不可响应 | PiP 有效时直接响应键盘命令 |
|
||||
| 麦克风指示长时间亮起 | Flow 会话级连续采集 | 空闲时释放麦克风 |
|
||||
| 耗电或发热 | 音频引擎持续采样和处理 | 仅听写期间采样 |
|
||||
| 其他 App 无法使用麦克风 | OSGKeyboard 持有输入设备 | 听写结束后主动释放 |
|
||||
| 不知道会话是否可用 | Flow、麦克风和进程状态混为一体 | 分开展示「免切换已就绪」和「正在录音」 |
|
||||
|
||||
### 2.3 成功定义
|
||||
|
||||
PiP 模式下，用户应能：
|
||||
|
||||
1. 在 OSGKeyboard 主 App 中主动开启免切换模式。
|
||||
2. 将 PiP 小窗收纳到屏幕边缘。
|
||||
3. 回到微信、邮件等宿主 App。
|
||||
4. 点击键盘麦克风后直接开始听写。
|
||||
5. 停止听写后收到文本，同时麦克风在短时间内释放。
|
||||
6. PiP 失效时收到明确提示，并能通过现有冷启动路径恢复。
|
||||
|
||||
---
|
||||
|
||||
## 3. 竞品与行业模式
|
||||
|
||||
### 3.1 Typeless
|
||||
|
||||
Typeless iOS 1.9.0 将该能力命名为 Picture in picture / Skip app switching：
|
||||
|
||||
- 用户先在主 App 中主动开启。
|
||||
- PiP 可拖到屏幕边缘收纳。
|
||||
- 用户在其他 App 的 Typeless 键盘中开始说话。
|
||||
- 官方产品说明强调麦克风空闲时关闭，以降低电量消耗。
|
||||
|
||||
其公开资料无法证明具体内部实现，因此本规划只借鉴产品模型，不假定其私有代码结构。
|
||||
|
||||
### 3.2 Wispr Flow、TypeWhisper 与同类开源项目
|
||||
|
||||
常见架构是主 App 持有 `AVAudioEngine`，键盘通过 App Group 与 Darwin 通知控制句子开始和停止。优点是首字延迟低，缺点是会话期间通常持续占用音频输入。
|
||||
|
||||
OSGKeyboard 当前 Flow 已属于此模式，并已具备：
|
||||
|
||||
- 主 App 会话所有权；
|
||||
- 键盘与主 App IPC；
|
||||
- 连续采集与 utterance gate；
|
||||
- App Group 结果回传；
|
||||
- Live Activity；
|
||||
- 冷启动与恢复流程。
|
||||
|
||||
因此 PiP 应作为会话生命周期的新载体，而不是重建整条语音管线。
|
||||
|
||||
### 3.3 SuperWhisper / App Intents 路线
|
||||
|
||||
更保守的方案是不做长期后台保活，使用 App Intents、Action Button、快捷指令或显式 App 切换启动录音。该方案最符合系统预期，但无法完全满足键盘内即时听写。
|
||||
|
||||
OSGKeyboard 应保留这类入口作为稳定降级，而不是依赖 PiP 达到 100% 可用。
|
||||
|
||||
### 3.4 合规边界
|
||||
|
||||
以下方式不应采用：
|
||||
|
||||
- 循环播放静音音频以防止挂起；
|
||||
- 声明与产品无关的定位、VoIP 后台能力；
|
||||
- 使用不可见或无实际产品意义的伪视频，仅为延长进程生命；
|
||||
- 在用户未明确开启会话时自动恢复麦克风。
|
||||
|
||||
PiP 内容需要能被解释为真实的语音会话控制面，例如展示：
|
||||
|
||||
- 「免切换已就绪」；
|
||||
- 「正在聆听」及音量反馈；
|
||||
- 「正在转写」；
|
||||
- 暂停、结束或返回 App 操作。
|
||||
|
||||
---
|
||||
|
||||
## 4. 目标产品模型
|
||||
|
||||
### 4.1 三层可用性
|
||||
|
||||
```text
|
||||
层级 0：冷启动
|
||||
主 App 不可用
|
||||
→ 键盘打开 startflow
|
||||
→ 主 App 建立语音会话
|
||||
|
||||
层级 1：短时 Flow
|
||||
AVAudioEngine 会话保持
|
||||
→ 最低首字延迟
|
||||
→ 默认 5 分钟无活动后结束
|
||||
|
||||
层级 2：PiP 免切换模式
|
||||
PiP 保持用户可见的多任务会话
|
||||
→ 空闲时麦克风关闭
|
||||
→ 键盘命令触发按需开麦
|
||||
```
|
||||
|
||||
三个层级必须共用同一份 `FlowSessionBridge` 状态合约，键盘不应根据实现细节分别写三套逻辑。
|
||||
|
||||
### 4.2 用户入口
|
||||
|
||||
建议在首页提供独立状态卡，而不是继续扩张设置开关：
|
||||
|
||||
- 未开启：`开启免切换模式`
|
||||
- 启动中：`正在准备画中画`
|
||||
- 已就绪：`免切换已就绪 · 麦克风未使用`
|
||||
- 录音中：`正在聆听`
|
||||
- 失效：`会话已断开，点击恢复`
|
||||
|
||||
首次开启时应明确说明：
|
||||
|
||||
1. 屏幕上会出现可收纳的 PiP 小窗。
|
||||
2. 空闲时不会使用麦克风。
|
||||
3. 用户关闭 PiP、强制退出 App 或系统回收进程后，需要重新开启。
|
||||
|
||||
### 4.3 键盘状态
|
||||
|
||||
键盘麦克风状态应从「主 App 是否活着」升级为明确能力状态：
|
||||
|
||||
| 状态 | 表现 | 点击结果 |
|
||||
|------|------|----------|
|
||||
| 不可用 | 灰色 | 引导权限或 Full Access |
|
||||
| 需恢复 | 橙色 | 打开主 App 恢复会话 |
|
||||
| PiP 就绪、麦克风关闭 | 绿色 | 请求主 App 按需开麦 |
|
||||
| 正在激活麦克风 | 绿色加载态 | 等待真实音频 proof |
|
||||
| 正在录音 | 红色/波形 | 发送停止命令 |
|
||||
| 正在转写 | 处理中 | 等待结果 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 目标架构
|
||||
|
||||
### 5.1 组件边界
|
||||
|
||||
```text
|
||||
Keyboard Extension
|
||||
└─ FlowSessionBridge / Darwin command
|
||||
↓
|
||||
Host App
|
||||
├─ VoiceSessionCoordinator
|
||||
│ ├─ FlowSessionManager
|
||||
│ ├─ PiPVoiceSessionController
|
||||
│ └─ AudioCaptureLifecycle
|
||||
├─ FlowContinuousCapture
|
||||
├─ ASR + Polish pipeline
|
||||
└─ Live Activity
|
||||
```
|
||||
|
||||
规划职责：
|
||||
|
||||
- `PiPVoiceSessionController`：只管理 PiP 生命周期和展示状态。
|
||||
- `AudioCaptureLifecycle`：管理按需激活、音频 proof、停止及释放。
|
||||
- `FlowSessionManager`：继续负责命令、ASR、润色和结果回传。
|
||||
- `FlowSessionBridge`：发布跨进程能力快照，不让键盘猜测主 App 状态。
|
||||
|
||||
### 5.2 状态机
|
||||
|
||||
```text
|
||||
inactive
|
||||
→ preparingPiP
|
||||
→ pipReadyMicOff
|
||||
→ activatingMic
|
||||
→ recording
|
||||
→ processing
|
||||
→ releasingMic
|
||||
→ pipReadyMicOff
|
||||
|
||||
任意状态
|
||||
→ interrupted
|
||||
→ recovering 或 inactive
|
||||
```
|
||||
|
||||
重要不变量：
|
||||
|
||||
1. `pipReadyMicOff` 必须确认音频输入已停止并释放。
|
||||
2. 键盘只有在收到 `recording` 和真实 audio proof 后才显示正在录音。
|
||||
3. PiP 存活不能等价于麦克风可用。
|
||||
4. 电话/Siri 中断后不得静默恢复录音。
|
||||
5. 任何超时都要回收麦克风并写入明确错误。
|
||||
|
||||
### 5.3 PiP 内容方案
|
||||
|
||||
技术验证阶段应比较两类 Apple 官方能力：
|
||||
|
||||
1. 基于 `AVPlayerLayer` 的媒体 PiP；
|
||||
2. 基于 `AVSampleBufferDisplayLayer` / 视频通话内容源的实时 PiP。
|
||||
|
||||
选择标准不是「哪种最容易保活」，而是：
|
||||
|
||||
- 是否符合 OSGKeyboard 的真实产品用途；
|
||||
- 能否展示动态语音会话状态；
|
||||
- 麦克风激活/释放是否稳定；
|
||||
- 收纳、锁屏、音频中断行为是否可预测；
|
||||
- App Review 是否能清楚理解其用途。
|
||||
|
||||
在完成真机和审核验证前，不冻结具体 AVKit 实现。
|
||||
|
||||
---
|
||||
|
||||
## 6. 实施阶段
|
||||
|
||||
### Phase 0：技术与审核可行性验证
|
||||
|
||||
目标：证明「PiP 存活 + 闲时关麦 + 键盘触发按需开麦」在目标 iOS 版本可行。
|
||||
|
||||
验证项：
|
||||
|
||||
- PiP 启动、收纳、恢复与关闭；
|
||||
- 空闲 30 分钟后主 App 是否仍能响应；
|
||||
- 空闲期间系统麦克风指示是否消失；
|
||||
- 键盘命令到首个有效音频帧的延迟；
|
||||
- 连续 20 次开始/停止是否稳定；
|
||||
- 电话、Siri、蓝牙切换、锁屏、低电量模式；
|
||||
- 用户关闭 PiP 后的降级行为；
|
||||
- TestFlight / App Review 说明是否被接受。
|
||||
|
||||
退出标准：
|
||||
|
||||
- 空闲时没有麦克风占用；
|
||||
- P95 命令到有效音频帧小于 1 秒；
|
||||
- 20 次连续听写无僵尸录音或失联状态；
|
||||
- 失败后都能回到冷启动路径；
|
||||
- 没有使用静音循环或无关后台能力。
|
||||
|
||||
### Phase 1：内部可用版本
|
||||
|
||||
- 新增 PiP 会话控制器；
|
||||
- 将持续采集改造成可重复激活/释放；
|
||||
- 扩展跨进程状态快照；
|
||||
- 键盘增加激活中、PiP 就绪和失效状态；
|
||||
- 复用现有 ASR、润色、结果回传和 Live Activity；
|
||||
- 添加状态机与 IPC 单元测试。
|
||||
|
||||
### Phase 2：产品化
|
||||
|
||||
- 首页免切换状态卡；
|
||||
- 首次开启说明与 PiP 收纳引导；
|
||||
- 中英文文案与隐私说明；
|
||||
- 诊断页增加 PiP、音频会话和最近中断原因；
|
||||
- 增加遥测指标，但不采集音频内容。
|
||||
|
||||
### Phase 3：灰度与决策
|
||||
|
||||
- TestFlight 小流量开启；
|
||||
- 比较 PiP 与普通 Flow 的成功率、首字延迟和耗电；
|
||||
- 根据审核反馈决定默认入口和长期支持范围；
|
||||
- 若 PiP 不稳定或审核风险不可接受，保留为实验功能或停止上线。
|
||||
|
||||
---
|
||||
|
||||
## 7. 测试矩阵
|
||||
|
||||
### 7.1 功能场景
|
||||
|
||||
| 场景 | 预期 |
|
||||
|------|------|
|
||||
| PiP 空闲 | 主 App 可响应，麦克风未占用 |
|
||||
| 键盘开始听写 | 按需激活并获得真实音频帧 |
|
||||
| 停止听写 | 完成转写并及时释放麦克风 |
|
||||
| 连续多句 | 每句均重新激活成功，无第二句无音频 |
|
||||
| PiP 被关闭 | 键盘切为需恢复，不显示假就绪 |
|
||||
| App 被强退 | 清除旧 generation 和僵尸状态 |
|
||||
| 电话/Siri 中断 | 当前句失败并提示，不自动偷录 |
|
||||
| 蓝牙设备变化 | 音频格式重建，不崩溃 |
|
||||
| 网络失败 | 本地 ASR 保留；润色按现有策略降级 |
|
||||
|
||||
### 7.2 设备与系统
|
||||
|
||||
- 最低支持 iOS 版本、当前稳定版和最新 beta；
|
||||
- 刘海机、灵动岛机型、iPad；
|
||||
- AirPods、普通蓝牙耳机、车载音频、有线设备；
|
||||
- 微信、信息、邮件、Slack、Notes 及自定义文本输入控件；
|
||||
- 锁屏、横竖屏、多窗口、低电量和后台刷新关闭状态。
|
||||
|
||||
---
|
||||
|
||||
## 8. 指标与验收
|
||||
|
||||
### 8.1 核心指标
|
||||
|
||||
| 指标 | 定义 | 目标 |
|
||||
|------|------|------|
|
||||
| 免切换成功率 | PiP 就绪时无需打开主 App完成听写 | ≥ 98% |
|
||||
| 麦克风空闲占用 | 非录音期间仍占麦的时长比例 | 接近 0 |
|
||||
| 首帧延迟 P95 | 键盘点击到真实音频 proof | < 1 秒 |
|
||||
| 结果回传成功率 | 停止后键盘收到最终结果 | ≥ 99% |
|
||||
| 僵尸状态率 | 键盘显示可用但主 App无法响应 | < 0.5% |
|
||||
| 恢复成功率 | 失效后通过冷启动恢复 | ≥ 99% |
|
||||
|
||||
### 8.2 观察指标
|
||||
|
||||
- 每日 PiP 开启人数与启用留存；
|
||||
- PiP 被用户主动关闭的比例；
|
||||
- 每小时耗电和温升相对普通 Flow 的变化；
|
||||
- 音频中断类型分布；
|
||||
- 用户因橙色麦克风指示或隐私产生的反馈；
|
||||
- App Review 反馈和政策变化。
|
||||
|
||||
---
|
||||
|
||||
## 9. 风险与应对
|
||||
|
||||
| 风险 | 等级 | 应对 |
|
||||
|------|------|------|
|
||||
| PiP 被认定与媒体用途不匹配 | 高 | 提供真实会话 UI、明确审核说明；先 TestFlight/审核验证 |
|
||||
| 系统版本改变 PiP 行为 | 高 | 保持冷启动降级；按系统版本做兼容验证 |
|
||||
| 按需开麦首字丢失 | 中 | 激活态 + audio proof + 预录缓冲，不提前向键盘宣告录音 |
|
||||
| 频繁激活导致音频路由异常 | 中 | 串行状态机、格式重建、媒体服务重置恢复 |
|
||||
| PiP 与 Live Activity 状态冲突 | 中 | 单一 coordinator 发布状态，两个 UI 只消费 |
|
||||
| 用户误解 PiP 仍在监听 | 中 | 空闲状态明确写「麦克风未使用」，隐私说明可验证 |
|
||||
| 其他 App 抢占麦克风 | 中 | 显式中断提示，不承诺并发录音 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 产品决策门
|
||||
|
||||
进入代码实现前，需要确认：
|
||||
|
||||
1. 是否接受 PiP 作为用户主动开启、系统可见且可收纳的产品形态；
|
||||
2. 是否优先「空闲关麦」而接受约数百毫秒的重新激活延迟；
|
||||
3. PiP 中展示哪些真实功能，确保它不是纯保活黑窗；
|
||||
4. 是否将现有「跳过 App 切换」重命名并拆为普通 Flow / PiP 两种模式；
|
||||
5. 最低支持系统和目标测试设备；
|
||||
6. 技术验证失败或审核风险过高时，是否接受回退到短 Flow + App Intents。
|
||||
|
||||
在上述决策和 Phase 0 证据完成前，不建议直接进入正式实现。
|
||||
Reference in New Issue
Block a user