添加语音websocket等，还没测试

2026-01-16 13:38:03 +08:00
parent 169a1929d7
commit b021fd308f
33 changed files with 5098 additions and 8 deletions
--- a/keyBoard/Class/AiTalk/AI技术分析.txt
+++ b/keyBoard/Class/AiTalk/AI技术分析.txt
@@ -0,0 +1,521 @@
+   服务           用途                      示例格式
+ASR 服务器    语音识别（WebSocket）     wss://api.example.com/asr
+LLM 服务器    AI 对话（HTTP SSE）      https://api.example.com/chat
+TTS 服务器    语音合成                 https://api.example.com/tts
+
+iOS（Objective-C，iOS 15+）端技术实现文档
+低延迟流式语音陪伴聊天（按住说话，类似猫箱首页）
+0. 范围与目标
+
+实现首页语音陪伴对话：
+
+按住说话：开始录音并实时流式发送到 ASR
+
+松开结束：ASR 立即 finalize，返回最终文本并显示
+
+AI 回复：边显示文字（打字机效果）边播放服务端 TTS 音频
+
+延迟低优先：不等待完整回答/完整音频，采用“分句触发 + 流式/准流式播放”
+
+打断（Barge-in）：AI 正在播报时用户再次按住 → 立即停止播报/取消请求，进入新一轮录音
+
+iOS 最低版本：iOS 15
+
+1. 总体架构（客户端模块）
+KBAiMainVC
+ └─ ConversationOrchestrator (核心状态机 / 串联模块 / 取消与打断)
+     ├─ AudioSessionManager     (AVAudioSession 配置与中断处理)
+     ├─ AudioCaptureManager     (AVAudioEngine input tap -> 20ms PCM frames)
+     ├─ ASRStreamClient         (NSURLSessionWebSocketTask 流式识别)
+     ├─ LLMStreamClient         (SSE/WS token stream)
+     ├─ Segmenter               (句子切分：够一句就触发 TTS)
+     ├─ TTSServiceClient        (请求 TTS，适配多种返回形态)
+     ├─ TTSPlaybackPipeline     (可插拔：URL播放器 / AAC解码 / PCM直喂)
+     ├─ AudioStreamPlayer       (AVAudioEngine + AVAudioPlayerNode 播 PCM)
+     └─ SubtitleSync            (按播放进度映射文字进度)
+
+2. 音频会话（AVAudioSession）与权限
+2.1 麦克风权限
+
+仅在用户第一次按住说话前请求
+
+若用户拒绝：提示到设置开启
+
+2.2 AudioSession 配置（对话模式）
+
+Objective-C（建议参数）：
+
+category：AVAudioSessionCategoryPlayAndRecord
+
+mode：AVAudioSessionModeVoiceChat
+
+options：
+
+AVAudioSessionCategoryOptionDefaultToSpeaker
+
+AVAudioSessionCategoryOptionAllowBluetooth
+
+（可选）AVAudioSessionCategoryOptionMixWithOthers：若你希望不打断宿主音频（看产品）
+
+2.3 中断与路由变化处理（必须）
+
+监听：
+
+AVAudioSessionInterruptionNotification
+
+AVAudioSessionRouteChangeNotification
+
+处理原则：
+
+来电/中断开始：停止采集 + 停止播放 + cancel 网络会话
+
+中断结束：回到 Idle，等待用户重新按住
+
+3. 音频采集（按住期间流式上传）
+3.1 固定音频参数（锁死，便于端到端稳定）
+
+Sample Rate：16000 Hz
+
+Channels：1
+
+Format：PCM Int16（pcm_s16le）
+
+Frame Duration：20ms
+
+16kHz * 0.02s = 320 samples
+
+每帧 bytes = 320 * 2 = 640 bytes
+
+3.2 AudioCaptureManager（AVAudioEngine 输入 tap）
+
+使用：
+
+AVAudioEngine
+
+inputNode installTapOnBus:bufferSize:format:block:
+
+关键点：
+
+tap 回调线程不可做重活：只做拷贝 + dispatch 到 audioQueue
+
+将 AVAudioPCMBuffer 转成 Int16 PCM NSData
+
+确保稳定输出“20ms帧”，如果 tap 回调 buffer 不刚好是 20ms，需要做 帧拼接/切片（ring buffer）
+
+3.3 接口定义（OC）
+@protocol AudioCaptureManagerDelegate <NSObject>
+- (void)audioCaptureManagerDidOutputPCMFrame:(NSData *)pcmFrame; // 20ms/640B
+- (void)audioCaptureManagerDidUpdateRMS:(float)rms;             // 可选：UI波形
+@end
+
+@interface AudioCaptureManager : NSObject
+@property (nonatomic, weak) id<AudioCaptureManagerDelegate> delegate;
+- (BOOL)startCapture:(NSError **)error;
+- (void)stopCapture;
+@end
+
+4. ASR 流式识别（iOS15：NSURLSessionWebSocketTask）
+4.1 建议协议（控制帧 JSON + 音频帧二进制）
+
+Start（文本帧）
+
+{
+  "type":"start",
+  "sessionId":"uuid",
+  "format":"pcm_s16le",
+  "sampleRate":16000,
+  "channels":1
+}
+
+
+Audio（二进制帧）
+
+直接发送 640B/帧 PCM
+
+频率：50fps（每秒 50 帧）
+
+Finalize（文本帧）
+
+{ "type":"finalize", "sessionId":"uuid" }
+
+4.2 下行事件
+{ "type":"partial", "text":"今天" }
+{ "type":"final",   "text":"今天天气怎么样" }
+{ "type":"error",   "code":123, "message":"..." }
+
+4.3 ASRStreamClient 接口（OC）
+@protocol ASRStreamClientDelegate <NSObject>
+- (void)asrClientDidReceivePartialText:(NSString *)text;
+- (void)asrClientDidReceiveFinalText:(NSString *)text;
+- (void)asrClientDidFail:(NSError *)error;
+@end
+
+@interface ASRStreamClient : NSObject
+@property (nonatomic, weak) id<ASRStreamClientDelegate> delegate;
+- (void)startWithSessionId:(NSString *)sessionId;
+- (void)sendAudioPCMFrame:(NSData *)pcmFrame; // 20ms frame
+- (void)finalize;
+- (void)cancel;
+@end
+
+5. LLM 流式生成（token stream）
+5.1 目标
+
+低延迟：不要等整段回答
+
+使用 SSE 或 WS 收 token
+
+token 进入 Segmenter，够一句就触发 TTS
+
+5.2 LLMStreamClient 接口（OC）
+@protocol LLMStreamClientDelegate <NSObject>
+- (void)llmClientDidReceiveToken:(NSString *)token;
+- (void)llmClientDidComplete;
+- (void)llmClientDidFail:(NSError *)error;
+@end
+
+@interface LLMStreamClient : NSObject
+@property (nonatomic, weak) id<LLMStreamClientDelegate> delegate;
+- (void)sendUserText:(NSString *)text conversationId:(NSString *)cid;
+- (void)cancel;
+@end
+
+6. Segmenter（句子切分：先播第一句）
+6.1 切分规则（推荐）
+
+任一满足则切分成 segment：
+
+遇到 。！？\n 之一
+
+或累积字符数 ≥ 30（可配置）
+
+6.2 Segmenter 接口（OC）
+@interface Segmenter : NSObject
+- (void)appendToken:(NSString *)token;
+- (NSArray<NSString *> *)popReadySegments; // 返回立即可TTS的片段数组
+- (void)reset;
+@end
+
+7. TTS：返回形态未定 → 客户端做“可插拔播放管线”
+
+由于服务端同事未定输出格式，客户端必须支持以下 四种 TTS 输出模式 的任意一种：
+
+模式 A：返回 m4a/MP3 URL（最容易落地）
+
+服务端返回 URL（或 base64 文件）
+
+客户端用 AVPlayer / AVAudioPlayer 播放
+
+字幕同步用“音频时长映射”（可拿到 duration）
+
+优点：服务端简单
+缺点：首帧延迟通常更高（要等整段生成、至少等首包）
+
+模式 B：返回 AAC chunk（流式）
+
+服务端 WS 推 AAC 帧
+
+客户端需要 AAC 解码成 PCM，再喂 AudioStreamPlayer
+
+模式 C：返回 Opus chunk（流式）
+
+需 Opus 解码库（服务端/客户端成本更高）
+
+解码后喂 PCM 播放
+
+模式 D：返回 PCM chunk（最适合低延迟）
+
+服务端直接推 PCM16 chunk（比如 100ms 一块）
+
+客户端直接转 AVAudioPCMBuffer schedule
+
+延迟最低、实现最稳
+
+8. TTSServiceClient（统一网络层接口）
+8.1 统一回调事件（抽象）
+typedef NS_ENUM(NSInteger, TTSPayloadType) {
+    TTSPayloadTypeURL,        // A
+    TTSPayloadTypePCMChunk,   // D
+    TTSPayloadTypeAACChunk,   // B
+    TTSPayloadTypeOpusChunk   // C
+};
+
+@protocol TTSServiceClientDelegate <NSObject>
+- (void)ttsClientDidReceiveURL:(NSURL *)url segmentId:(NSString *)segmentId;
+- (void)ttsClientDidReceiveAudioChunk:(NSData *)chunk
+                           payloadType:(TTSPayloadType)type
+                             segmentId:(NSString *)segmentId;
+- (void)ttsClientDidFinishSegment:(NSString *)segmentId;
+- (void)ttsClientDidFail:(NSError *)error;
+@end
+
+@interface TTSServiceClient : NSObject
+@property (nonatomic, weak) id<TTSServiceClientDelegate> delegate;
+- (void)requestTTSForText:(NSString *)text segmentId:(NSString *)segmentId;
+- (void)cancel;
+@end
+
+
+这样服务端最后选哪种输出，你只需实现对应分支即可，不需要推翻客户端架构。
+
+9. TTSPlaybackPipeline（播放管线：根据 payloadType 路由）
+9.1 设计目标
+
+支持 URL 播放与流式 chunk 播放
+
+提供统一的“开始播放/停止/进度”接口供字幕同步与打断使用
+
+9.2 Pipeline 结构（建议）
+
+TTSPlaybackPipeline 只做路由与队列管理
+
+URL → TTSURLPlayer（AVPlayer）
+
+PCM → AudioStreamPlayer（AVAudioEngine）
+
+AAC/Opus → Decoder → PCM → AudioStreamPlayer
+
+9.3 Pipeline 接口（OC）
+@protocol TTSPlaybackPipelineDelegate <NSObject>
+- (void)pipelineDidStartSegment:(NSString *)segmentId duration:(NSTimeInterval)duration;
+- (void)pipelineDidUpdatePlaybackTime:(NSTimeInterval)time segmentId:(NSString *)segmentId;
+- (void)pipelineDidFinishSegment:(NSString *)segmentId;
+@end
+
+@interface TTSPlaybackPipeline : NSObject
+@property (nonatomic, weak) id<TTSPlaybackPipelineDelegate> delegate;
+
+- (BOOL)start:(NSError **)error; // 启动音频引擎等
+- (void)stop;                    // 立即停止（打断）
+
+- (void)enqueueURL:(NSURL *)url segmentId:(NSString *)segmentId;
+- (void)enqueueChunk:(NSData *)chunk payloadType:(TTSPayloadType)type segmentId:(NSString *)segmentId;
+
+// 可选：用于字幕同步
+- (NSTimeInterval)currentTimeForSegment:(NSString *)segmentId;
+- (NSTimeInterval)durationForSegment:(NSString *)segmentId;
+@end
+
+10. AudioStreamPlayer（PCM 流式播放，低延迟核心）
+10.1 使用 AVAudioEngine + AVAudioPlayerNode
+
+将 PCM chunk 转 AVAudioPCMBuffer
+
+scheduleBuffer 播放
+
+维护“当前 segment 的播放时间/总时长”（可估算或累加 chunk 时长）
+
+10.2 接口（OC）
+@interface AudioStreamPlayer : NSObject
+- (BOOL)start:(NSError **)error;
+- (void)stop;
+- (void)enqueuePCMChunk:(NSData *)pcmData
+             sampleRate:(double)sampleRate
+               channels:(int)channels
+              segmentId:(NSString *)segmentId;
+
+- (NSTimeInterval)playbackTimeForSegment:(NSString *)segmentId;
+- (NSTimeInterval)durationForSegment:(NSString *)segmentId;
+@end
+
+
+PCM chunk 的粒度建议：50ms~200ms（太小 schedule 太频繁，太大延迟高）。
+
+11. 字幕同步（延迟优先）
+11.1 策略
+
+对每个 segment 的文本 text，按播放进度映射显示字符数：
+
+visibleCount = round(text.length * (t / T))
+
+t：segment 当前播放进度（pipeline 提供）
+
+T：segment 总时长（URL 模式直接取；chunk 模式可累加估算）
+
+11.2 SubtitleSync 接口（OC）
+@interface SubtitleSync : NSObject
+- (NSString *)visibleTextForFullText:(NSString *)fullText
+                         currentTime:(NSTimeInterval)t
+                            duration:(NSTimeInterval)T;
+@end
+
+12. ConversationOrchestrator（状态机 + 打断 + 队列）
+12.1 状态
+typedef NS_ENUM(NSInteger, ConversationState) {
+    ConversationStateIdle,
+    ConversationStateListening,
+    ConversationStateRecognizing,
+    ConversationStateThinking,
+    ConversationStateSpeaking
+};
+
+12.2 关键流程
+事件：用户按住（userDidPressRecord）
+
+如果正在 Speaking/Thinking：
+
+[ttsService cancel]
+
+[llmClient cancel]
+
+[asrClient cancel]（如仍在识别）
+
+[pipeline stop]（立即停播）
+
+清空 segment 队列、字幕队列
+
+配置/激活 AudioSession
+
+新建 sessionId
+
+[asrClient startWithSessionId:]
+
+[audioCapture startCapture:]
+
+state = Listening
+
+事件：用户松开（userDidReleaseRecord）
+
+[audioCapture stopCapture]
+
+[asrClient finalize]
+
+state = Recognizing
+
+回调：ASR final text
+
+UI 显示用户最终文本
+
+state = Thinking
+
+开始 LLM stream：[llmClient sendUserText:conversationId:]
+
+回调：LLM token
+
+segmenter appendToken
+
+segments = [segmenter popReadySegments]
+
+对每个 segment：
+
+生成 segmentId
+
+记录 segmentTextMap[segmentId] = segmentText
+
+[ttsService requestTTSForText:segmentId:]
+
+当收到第一个可播放音频并开始播：
+
+state = Speaking
+
+回调：TTS 音频到达
+
+URL：[pipeline enqueueURL:segmentId:]
+
+chunk：[pipeline enqueueChunk:payloadType:segmentId:]
+
+回调：pipeline 播放时间更新（每 30-60fps 或定时器）
+
+根据当前 segmentId 取到 fullText
+
+visible = [subtitleSync visibleTextForFullText:currentTime:duration:]
+
+UI 更新 AI 可见文本
+
+12.3 打断（Barge-in）
+
+当用户再次按住：
+
+立即 stop 播放
+
+取消所有未完成网络请求
+
+丢弃所有未播放 segments
+
+开始新一轮录音
+
+12.4 Orchestrator 接口（OC）
+@interface ConversationOrchestrator : NSObject
+@property (nonatomic, assign, readonly) ConversationState state;
+
+- (void)userDidPressRecord;
+- (void)userDidReleaseRecord;
+
+@property (nonatomic, copy) void (^onUserFinalText)(NSString *text);
+@property (nonatomic, copy) void (^onAssistantVisibleText)(NSString *text);
+@property (nonatomic, copy) void (^onError)(NSError *error);
+@end
+
+13. 线程/队列模型（强制要求，避免竞态）
+
+建议三条队列 + 一条 orchestrator 串行队列：
+
+dispatch_queue_t audioQueue;（采集帧处理、ring buffer）
+
+dispatch_queue_t networkQueue;（WS 收发解析）
+
+dispatch_queue_t orchestratorQueue;（状态机串行，唯一修改 state/队列的地方）
+
+UI 更新统一回主线程
+
+规则：
+
+任何网络/音频回调 → dispatch_async(orchestratorQueue, ^{ ... })
+
+Orchestrator 内部再决定是否发 UI 回调（主线程）
+
+14. 关键参数（延迟与稳定性）
+
+音频帧：20ms
+
+PCM：16k/mono/int16
+
+ASR 上传：WS 二进制
+
+LLM：token stream
+
+TTS：优先 chunk；若 URL 模式也要尽快开始下载与播放
+
+chunk 播放缓冲：100~200ms（防抖动）
+
+15. 开发落地建议（服务端未定情况下的迭代路径）
+Phase 1：先跑通端到端（用“URL 模式”模拟）
+
+TTSServiceClient 先假定服务端返回 m4a URL（或本地 mock URL）
+
+Pipeline 实现 URL 播放（AVPlayer）
+
+打断 + 字幕同步先跑通
+
+Phase 2：服务端定了输出后再替换
+
+若服务端给 PCM chunk：直接走 AudioStreamPlayer（最推荐）
+
+若给 AAC chunk：补 AAC 解码模块（AudioConverter 或第三方）
+
+若给 Opus chunk：集成 Opus 解码库，再喂 PCM
+
+关键：Orchestrator/Segmenter/ASR/字幕同步都不需要改，只替换 TTSPlaybackPipeline 分支。
+
+16. 合规/体验注意
+
+录音必须由用户动作触发（按住）
+
+明确的“正在录音”提示与波形
+
+避免自动偷录
+
+播放时允许随时打断
+
+文档结束
+给“写代码的 AI”的额外要求（建议你一并附上）
+
+语言：Objective-C（.h/.m）
+
+iOS 15+，WebSocket 用 NSURLSessionWebSocketTask
+
+音频采集用 AVAudioEngine + ring buffer 切 20ms 帧
+
+播放管线必须支持：URL 播放（AVPlayer）+ PCM chunk 播放（AVAudioEngine）
+
+其余 AAC/Opus 分支可留 TODO / stub，但接口要预留