服务           用途                      示例格式
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，但接口要预留