主题
端侧程序设计详解
本文面向希望在不同芯片平台（如乐鑫、博通、杰理等平台，以及 RK 系列 Linux 平台等）上移植、扩展 JoyInside 端侧全双工对话与有声资源播放能力的开发者。文档抽象描述技术原理与设计准则，作为跨平台移植与二次开发的核心参照。
在阅读本文档前，建议先阅读 JoyInside 云端协议介绍文档，熟悉全双工对话、有声资源播放的处理流程。
目录
1. 设计目标与总体思路
JoyInside 端侧程序承担两项核心业务：
- 全双工实时语音对话：设备与云端保持全双工对话连接，持续完成音频采集、编码上行、云端音频接收、解码和播放；用户可随时打断云端回复。
- 有声资源播放：设备接收云端播放指令后，通过 HTTPS 流式获取有声资源正文并播放，支持串场词过渡、断点续播和会话保活。
为统一表述，本文使用以下术语：
- 全双工对话连接：设备与云端之间的 WebSocket 长连接，承载全双工对话音频、播放指令和心跳等消息。
- 有声资源正文：根据播放指令通过 HTTPS 获取的 MP3 内容。
端侧以“空闲态 / 对话态”为基本状态模型，围绕以下能力构建：
- 音频流水线：以多线程和有界队列组织采集、声学前端处理、编解码、正文拉流与播放环节。各环节相互解耦，可分别调整帧长、缓冲深度、队列满策略和处理资源。
- 状态与连接管理：管理对话态、有声资源会话和全双工对话连接；将重连、资源清理等耗时工作移出监控与回调路径，由事件处理路径串行执行，避免阻塞实时处理。同时持续检查连接活性、传输进度和空闲时长，及时发现异常。
- 弱网容忍：对全双工对话连接的暂态读写异常保持容忍，避免短时抖动直接触发断线；对持续无进展、心跳超时或明确不可恢复的错误及时收敛，兼顾连接连续性与故障可恢复性。
2. 设备状态模型
端侧运行期维护一个粗粒度的设备状态，用于驱动整体行为与资源调度：
| 状态 | 含义 |
|---|---|
| 启动态（Starting） | 开机后的资源初始化阶段。 |
| 空闲态（Idle） | 尚未进入对话态，音频上、下行链路均关闭。退出对话态或发生空闲超时后，设备进入该状态。 |
| 对话态（Conversing） | 存在活跃会话，音频上、下行链路可用。设备唤醒后进入该状态；全双工对话和有声资源播放均属于此状态。 |
不同设备状态下的网络连接策略
- 空闲态：除开机后会先建立全双工对话连接再进入空闲态之外，其他情况均仅在唤醒事件触发后建立全双工对话连接，并从空闲态切换到对话态；
- 对话态：对话态下应保持全双工对话连接；连接异常断开时自动重连，直到退出对话或空闲超时后主动关闭连接，并从对话态切换到空闲态。
3. 整体架构
本节从全局视角说明端侧的模块划分、线程模型、跨线程队列和运行时监控，是第 4 章全双工对话链路与第 5 章有声资源播放链路的共同基础。两条业务链路复用全双工对话连接、音频播放能力和线程安全队列等底层能力，仅在上层业务流水线中分化。
该架构将整体系统拆分为不同的逻辑角色，具备良好的跨平台扩展性，并且已在资源充裕的 Linux 平台与资源受限的 MCU/SoC 平台上落地。
3.1 分层与模块划分
端侧程序自上而下可分为四层：
| 层次 | 模块 | 职责 |
|---|---|---|
| 编排层 | 应用编排器 | 控制状态转换（包括设备状态与有声资源会话状态）、调度业务流水线、异常检测处理。 |
| 业务链路层 | 全双工对话流水线、有声资源播放流水线 | 全双工对话流水线负责全双工语音收发；有声资源播放流水线负责远端流式音频拉取、解码、播放与断点续播。 |
| 公共服务层 | 音频采集/播放、音频编解码、网络控制 | 提供音频采集/播放帧长、队列上限、队列满策略，以及音频编解码等音频公共服务；提供网络状态机处理、鉴权、建连、心跳等网络公共服务。 |
| 平台适配层 | 麦克风/扬声器驱动、编解码库、网络传输库 | 适配不同芯片的驱动接口、各种依赖库接口 |
3.2 线程模型与职责
端侧采用“单一职责线程 + 有界队列衔接”的多线程模型。下表描述逻辑职责，实际部署时可按平台资源合并线程。
| 线程 | 职责 | 数据输入队列 | 数据输出队列 |
|---|---|---|---|
| 音频采集线程 | 读取麦克风 PCM，做重采样/增益，并将结果传送到音频采集队列。 | — | 音频采集队列 |
| 声学前端处理线程 | 从音频采集队列获取 PCM，做 AEC/NS/VAD 等处理。 | 音频采集队列 | 唤醒词检测队列/Opus 编码队列 |
| 唤醒检测线程 | 空闲态下进行唤醒词检测。 | 唤醒词检测队列 | — |
| Opus 编码线程 | 从 Opus 编码队列取 PCM，累积到目标帧长后做 Opus 编码。 | Opus 编码队列 | WebSocket 发送队列 |
| 网络发送线程 | 从 WebSocket 发送队列取出 Opus 音频，经全双工对话连接发送；同时发送各类 JSON 文本消息。 | WebSocket 发送队列 | — |
| 网络心跳线程 | 经全双工对话连接定期发送心跳，维持应用层连接活性，并为失联检测提供依据。 | — | — |
| 网络接收线程 | 接收全双工对话连接下行的二进制和文本消息；二进制音频写入 Opus 解码队列，文本消息按类型分发至相应处理路径。 | — | Opus 解码队列 |
| Opus 解码线程 | 从 Opus 解码队列取 Opus 帧解码为 PCM。 | Opus 解码队列 | 音频播放队列 |
| 音频播放线程 | 从播放队列取 PCM，做重采样/增益后写入扬声器播放。 | 音频播放队列 | — |
| 设备状态监控线程 | 设备状态切换处理；各种网络异常检测与处理。 | — | — |
| 事件处理线程 | 承接建连、清理、重连和资源回收等耗时阻塞操作，并串行驱动复杂状态迁移，使网络接收和设备状态监控路径保持非阻塞。 | — | — |
| 有声资源下载线程 | 从远端 HTTPS 流式获取有声资源正文并写入 MP3 解码队列，负责背压、续传和重试。 | — | MP3 解码队列 |
| MP3 解码线程 | 从 MP3 解码队列取 MP3 字节流并解码为 PCM。 | MP3 解码队列 | 音频播放队列 |
| 有声资源状态检测线程 | 有声资源子状态切换处理；播放阻塞、下载卡顿、网络异常等各种异常检测与处理。 | — | — |
设计准则：
- 状态解耦：网络控制、有声资源正文下载、Opus 编解码和 MP3 解码等模块仅在各自职责范围内管理状态与资源。确需跨线程调用时，必须通过线程安全接口完成，避免跨线程直接修改内部状态。
- 事件路径非阻塞：网络接收和状态监控路径只负责识别事件、更新轻量状态并投递任务；建连、重连、资源回收等耗时操作由事件处理线程串行执行，保证实时处理路径不会因阻塞操作失去响应。
- 逻辑角色与线程合并：表中线程是逻辑职责而非固定线程数，可按平台资源和实际并发关系灵活合并。例如 Opus 编码与解码仅在用户打断云端回复的短暂窗口内并发，资源受限平台可合并为单线程；设备状态监控与有声资源状态检测也可合并为同一周期性巡检任务。
- 队列有界与过载控制：所有跨线程队列均设置容量上限，以防内存无限增长；同一数据流方向必须至少选择一处队列作为过载泄压点，并配置队满丢弃策略，避免背压沿整条链路持续积累。对重实时的全双工对话上行，可在队列满时丢弃最旧帧以优先发送最新语音；对重连续的下行播放链路，则通过缓冲和背压保持播放稳定。
3.3 端到端数据流总览
本节仅描述音频数据在线程与队列间的流转：
- 全双工对话上行：麦克风 → 音频采集线程 → 音频采集队列 → 声学前端处理线程 → Opus 编码队列 → Opus 编码线程 → WebSocket 发送队列 → 网络发送线程 → JoyInside 云端。
- 全双工对话下行：JoyInside 云端 → 网络接收线程 → Opus 解码队列 → Opus 解码线程 → 音频播放队列 → 音频播放线程 → 扬声器。
- 有声资源正文播放：远端 HTTPS → 有声资源下载线程 → MP3 解码队列 → MP3 解码线程 → 音频播放队列 → 音频播放线程 → 扬声器。
3.4 全双工对话连接管理（WebSocket）
全双工对话连接是设备与云端之间的 WebSocket 长连接，承载全双工对话音频、播放指令和心跳等消息；有声资源正文不经该连接传输。
核心准则：设备处于对话态时，应保持全双工对话连接可用，如断开则自动重连；设备处于空闲态时，应关闭该连接，避免不必要的资源占用和功耗。
连接健康与恢复：
- 多维度异常检测，确保及时性：全双工对话连接断开可归纳为两类：一类是“显式断开”，即端侧收到明确的断连信号；另一类是“隐式断开”，即连接已失效但端侧尚未感知，需自行做健康检测。当前方案不仅能即时响应“显式断开”，还通过发送超时、心跳响应超时、传输长时间无收发等多维度探测覆盖“隐式断开”场景，确保异常能被尽早识别并触发重连。
- 异常即刻收敛，防止脏数据：检测到全双工对话连接异常后，端侧程序会先立即停止上行发送并清理在途的收发数据，把断线的影响就地隔离；随后判断是“对话态内短暂断线”（保留对话态、清理旧连接后重连）还是“需彻底释放”（回收连接资源并切到空闲态），防止重连后旧数据污染新的对话交互。
- 高容忍度重连，确保重连成功率：全双工对话连接断开后，在设备处于对话态的前提下会自动重连，端侧不仅设置了较高的重试次数上限，而且重连失败后采用指数退避策略逐步拉大重试间隔，避免短时间内网络不稳定导致无效重试。
- 稳态确认，确保重连稳定性：重连成功后，端侧程序会进入连接观察阶段，仅当期间传输持续正常，才判定重连真正成功，以避免网络抖动情况下“连上即掉、掉了再连”反复消耗重试次数的问题。
4. 全双工对话链路
4.1 处理流程
全双工对话链路分为数据上行和数据下行两个阶段：
数据上行（音频采集 → 上传云端）：
音频采集线程：从麦克风按照固定帧长读取硬件 PCM 音频，并将音频重采样成 16 kHz 采样率、单声道、16 bit 位深，传送至音频采集队列。
声学前端处理线程：从音频采集队列按照模型所需帧长获取 PCM 音频，进行回声消除 AEC、噪声抑制 NS、语音活动检测 VAD 等处理。如果设备处于空闲态，将处理后的音频传送至唤醒词检测队列，进行后续的唤醒词检测；如果当前设备处于对话态，则处理后的音频传送至 Opus 编码队列。
唤醒检测线程：设备处于空闲态时，从唤醒词检测队列按照唤醒词模型所需帧长获取 PCM 音频，进行唤醒词检测。
Opus 编码线程：从 Opus 编码队列取 PCM，累积到目标帧长后进行 Opus 编码，产出 Opus 帧写入 WebSocket 发送队列。对于 16 kHz 采样率、单声道、16 bit 位深的音频，建议 Opus 编码比特率为 32 kbps，帧长为 40 ms。
网络发送线程：从 WebSocket 发送队列取出 Opus 帧，经 WebSocket 二进制通道以阻塞方式逐帧上传至云端。
设计建议：优先逐帧发送音频。 组包发送（合并多帧为一包）虽能减少包头与系统调用开销，却会因等待攒包而引入额外端到端时延，因此在实时对话场景下需谨慎评估。
数据下行（云端下发 → 音频播放）：
- 网络接收线程：实时接收云端下行的二进制 Opus 帧与文本 JSON 消息，二进制帧传送至 Opus 解码队列，文本消息则根据消息类型分发处理。
- Opus 解码线程：从 Opus 解码队列获取 Opus 帧进行解码，产出 PCM 写入音频播放队列。
- 音频播放线程：从音频播放队列取 PCM，做重采样/音量增益后写入扬声器播放。
4.2 队列设计
统一准则：
- 队列有界：任何极端情况下上、下行方向队列都不允许无限膨胀。队列容量应结合芯片内存预算与音频流畅度实测灵活调整，需综合考虑“该队列在极端情况下最多缓冲多少毫秒音频”与“队列达到容量上限后占用多少内存”。既要留出足够缓冲对抗抖动，也要严格控制内存上限。
- 满时策略分方向：上行链路“重实时”，宁可丢弃旧帧也要尽快发送新内容；下行链路“重连续”，在解码和播放环节尽量保持平滑。
元素大小计算（以 16 kHz 采样率、单声道、16 bit 位深、40 ms 帧、Opus 32 kbps 码率为例）：
- PCM 帧：
16,000 × 0.04 s × 2 字节 = 1,280 字节 = 1.25 KB，用于 Opus 编码队列与音频播放队列。 - Opus 帧：
32,000 bps × 0.04 s ÷ 8 = 160 字节（按 32 kbps 恒定码率和 40 ms 帧长折算），用于 WebSocket 发送队列与 Opus 解码队列。
| 队列 | 元素 | 单元素大小 | 容量上限 | 满时内存 / 可缓冲时长 | 满时策略 | 设计理由 |
|---|---|---|---|---|---|---|
| Opus 编码队列 | 40 ms PCM | 1.25 KB | 5 | 6.25 KB / 200 ms | 生产者阻塞等待 | 编码线程消费极快，理论上不会满；容量 5 帧 = 200 ms，仅为吸收采集侧瞬时抖动。满时阻塞等待，避免丢帧。 |
| WebSocket 发送队列 | 40 ms Opus | 160 B | 63 | ≈9.8 KB / 2.5 s | 丢弃最旧帧 | 容量按 2.5 s 缓冲折算，用于吸收网络抖动。网络持续变慢导致积压时，丢弃最旧帧，优先发出用户最新音频，以牺牲陈旧内容换取实时性。 |
| Opus 解码队列 | 40 ms Opus | 160 B | 150 | ≈23.4 KB / 6 s | 丢弃最新帧 | 默认容量 150 帧 = 6 s，吸收网络抖动与 CPU 过载。堆积时丢弃新帧，优先保证播放连续。 |
| 音频播放队列 | 40 ms PCM | 1.25 KB | 15 | 18.75 KB / 600 ms | 生产者阻塞等待 | 播放由声卡按固定节奏稳定消费；容量 15 帧 = 600 ms，是下行链路的主缓冲池。满时阻塞会将背压反向传导至上游解码线程，使待播数据滞留于 Opus 解码队列而非被丢弃，尽可能保证播放不断音。 |
4.3 对话打断设计
打断是全双工对话体验效果的重要影响因素。端侧需保证打断后链路状态干净、无残留音频、无错乱数据。
打断的执行链路
打断本质是“清空一条正在流动的流水线”。收到云端下发的打断事件后，端侧自上而下逐级、按序清理：
- 置位 TTS 抑制：为了防止收到云端打断事件后继续播放旧对话轮次的 TTS 音频，端侧设置“TTS 抑制”窗口：收到打断标志即开始抑制，之后到达的 TTS 下行音频一律丢弃，直到收到新一轮 ASR 识别结果再解除抑制。这样可避免打断后仍接收并处理旧语音。
- 清空接收队列：清空 Opus 解码队列中所有待解码的旧数据。
- 解码代际隔离：为解码链路引入单调递增的“代际”标记。打断时令代际自增，并清空音频播放队列；解码线程只处理当前代际的帧，滞留在队列中以及解码缓冲区的旧代际帧被丢弃。这样即使清空动作与在途数据存在时间差，也不会继续处理旧帧。
- 播放端淡出防爆音：直接硬切正在输出的 PCM 会产生咔哒爆音。打断时对当前硬件缓冲做一小段约 30 ms 的线性淡出（音量逐渐降到零）再停止，使听感更平滑。
4.4 网络异常处理
全双工对话链路仅依赖全双工对话连接，关于其网络异常检测与恢复机制，详见第 3.4 节。
4.5 性能优化
4.5.1 建连耗时优化
WebSocket 建连耗时优化的核心思路是：把建连过程中相互独立的开销（鉴权 Token 获取、DNS 解析、连接上下文创建、TLS 握手）尽量并行推进而非串行执行，并尽可能复用缓存结果。
- 鉴权与建连并行化：单次 WSS 建连需完成“鉴权 Token 获取（一次独立 HTTPS 请求）”与“WSS 连接建立（DNS 解析 + TLS 握手）”两条链路。二者由串行改为并行，发起建连时同时启动 Token 请求和 WSS 连接建立两条后台任务，仅在 TLS 握手需写入鉴权头时汇合使用 Token。建连总耗时由二者之和收敛为两条链路中的较大值。
- DNS 预取与缓存复用：在连接内维护一份带 TTL 的 DNS 缓存，并在发起建连时异步预取目标主机地址。命中且未过期则直接复用，未命中或预取超时则安全回退实时解析，从而将 DNS 解析耗时从建连关键路径中剥离。
- IPv4 优先与 socket 调优：DNS 解析仅返回 IPv4 地址并直连，规避双栈并发探测的回退等待；同时对 socket 收发缓冲区按场景调优，降低建连与首包传输阶段的时延抖动。
4.5.2 内存优化
对于资源受限的嵌入式芯片，片内 SRAM 作为高速内存，容量通常十分有限且极为宝贵；而外扩内存（如 PSRAM、SDRAM 等）虽然容量更大，但访问速度通常低于片内 SRAM。因此，内存优化应遵循优先使用外扩内存，按需使用片内 SRAM的原则：在不影响系统性能和处理耗时的前提下，尽可能将可迁移的数据放置于外扩内存，仅将实时性要求高、访问频繁或硬件受限的数据保留在片内 SRAM。这样既能充分利用外扩内存容量，又能提升片内 SRAM 的利用效率。
- 优先使用外扩内存：音频队列、TLS 收发缓冲、任务栈及各类大容量缓存等优先分配至外扩内存，降低片内 SRAM 峰值占用，释放宝贵的高速内存资源。
- 所有缓冲区均有界：队列及缓冲区容量固定，最坏情况下的内存占用可静态评估，避免突发负载导致内存耗尽；容量配置以实际积压需求为依据，避免过度预留造成长期资源浪费。
- 缓冲区复用，避免频繁分配：音频帧缓冲、编解码工作区等采用初始化一次分配、运行期循环复用的方式，优先使用对象池或环形缓冲，减少动态内存分配与释放，降低内存碎片和运行时抖动。
- 按需分配，及时释放：TLS 等大容量缓冲按需申请、按需回收，握手完成后及时释放峰值内存；关闭量产环境无需的调试、统计及追踪功能，减少常驻内存和额外运行开销。
5. 有声资源播放链路
有声资源播放链路与全双工对话链路复用统一的设备状态管理和全双工对话连接，同时新增独立的有声资源正文处理流水线，并配套有声资源会话状态机与断点续播机制。
5.1 处理流程
有声资源播放由云端经全双工对话连接下发播放指令触发。本文将通过 HTTPS 获取的 MP3 内容称为有声资源正文（下文简称“正文”），以区别于经全双工对话连接下发的串场词；将从音频播放队列到扬声器的本地输出路径称为音频播放通路。全双工对话下行与正文在任一时刻只能有一路占用该通路。有声资源正文的处理链路如下：
- 有声资源下载线程：接收云端下发的播放指令后，从远端 HTTPS 地址流式拉取 MP3 字节流并写入 MP3 解码队列。该线程依据队列高低水位施加背压以限速下载，并具备断点续传与异常重试能力。
- MP3 解码线程：从 MP3 解码队列取出 MP3 字节流进行流式解码，产出 PCM 写入音频播放队列。
- 音频播放线程：从音频播放队列取 PCM，做重采样/音量增益后写入扬声器播放。该线程与全双工对话下行复用同一音频播放通路，需保证任一时刻仅有一路音频输出。
5.2 队列设计
有声资源播放流水线由MP3 解码队列和PCM 暂存队列两级缓冲组成，共同构建了一条从播放端反压至下载端的完整背压链路。
统一准则：
- 缓冲有界：MP3 解码队列与 PCM 暂存队列均采用固定容量设计，最坏情况下的内存占用可静态评估，避免缓冲无限增长。
- 满时策略重连续：当两级缓冲达到容量上限时，均采用生产者阻塞等待策略，而非丢弃数据，以最大程度保障播放连续性。
MP3 解码队列（高低水位背压）： 下载线程持续将 MP3 字节流写入解码队列，并通过高、低水位实现自适应流控：
- 队列占用达到高水位时暂停下载，抑制内存持续增长；
- 解码线程消费数据，使队列占用降至低水位后恢复下载；
- 下载速率随解码与播放速率动态调节，内存占用始终受限于队列容量。
元素大小计算（以 MP3 解码输出：16 kHz 采样率、单声道、16 bit 位深、60 ms 帧为例）：
- PCM 帧：
16,000 × 0.06 s × 2 字节 = 1,920 字节 ≈ 1.875 KB，用于 PCM 暂存队列。
| 队列 | 元素 | 单元素大小 | 容量上限 | 满时内存 / 可缓冲时长 | 满时策略 | 设计理由 |
|---|---|---|---|---|---|---|
| MP3 解码队列 | MP3 字节流 | — | 256 KB | 256 KB | 高低水位背压 | 高水位（约 90%）暂停下载，低水位（约 50%）恢复下载，使下载速率自适应解码与播放节奏，并将内存占用稳定约束在缓冲容量内。 |
| PCM 暂存队列 | 60 ms PCM | 1.875 KB | 100 | 187.5 KB / 6 s | 生产者阻塞等待 | 对于存在串场词的场景，有声资源需待串场词播放完成后才能输出。因此，播放链路将提前解码生成的 PCM 数据暂存至 PCM 暂存队列，在等待期间完成数据预取，既降低串场结束后的播放启动时延，又能有效抵御网络抖动。 |
5.3 有声资源会话状态机设计
有声资源会话将“正文预取”和“正文接入扬声器”分开管理，确保串场词完整播完后才切换至音频播放通路，同时把正文的下载、解码工作前置：
| 状态 | 阶段含义与目的 |
|---|---|
| 空闲 | 当前没有有效的有声资源会话，是新播放请求的准入状态，也是正常播完、停止或故障后的最终收敛状态。 |
| 串场词接收 | 收到需串场词过渡的播放任务后，串场词持续接收并播放；正文同步进行预取与预处理，但尚不进入音频播放通路。目的在于将正文准备与串场词播放重叠，缩短后续切换等待，同时避免两路音频混播。 |
| 串场词排空 | 串场词已接收完毕，等待其尾部音频完整输出。通过确认待播内容与输出缓冲均已排空，确保串场词结束后再切换正文，避免截断、重叠或突变。 |
| 正文切换准备 | 串场词已确认结束；未携带串场词的播放任务也会直接进入本阶段。此时完成音频播放通路交接，使预取的正文能够开始播放。 |
| 正文播放 | 正文已接入音频播放通路，内容获取和播放持续协同进行；同时维护播放进度与有声资源会话保活，并在内容播完后结束有声资源会话。 |
交互范围约束：有声资源播放期间，仅响应上一首、下一首、退出等播控指令；普通对话输入不作为打断条件，也不触发新的云端对话，以避免误中断并保持播放体验一致。
5.4 有声资源打断设计
打断处理以“保证单一音频输出”和“明确有声资源会话归属”为原则。不同阶段的处置策略如下：
| 场景 | 适用阶段 | 处理原则 |
|---|---|---|
| 云端终止播放 | 串场词接收、串场词排空、正文切换准备、正文播放 | 立即撤销当前播放任务并释放音频播放通路。正文已开始播放时，以实际播出进度作为有声资源会话结束位置；尚未开始正文输出时，直接取消预取任务。 |
| 新播放任务到达 | 串场词接收、串场词排空、正文切换准备 | 直接替换：立即撤销尚未进入正文输出的原任务，再接受并启动新任务。此时不存在已播进度，无需等待原任务完成收尾。 |
| 新播放任务到达 | 正文播放 | 拒绝替换：继续保持当前有声资源会话，不因新任务自行中止播放。应先由云端明确终止当前任务，端侧结束有声资源会话并上报实际播放进度；后续任务由云端重新下发，以保证进度归属清晰。 |
| 云端对话语音到达 | 串场词排空、正文切换准备、正文播放 | 对话优先，有声资源让出音频播放通路；串场词接收阶段不将其自身的串场词视为抢占事件。 |
转场音量处理：对正在输出的音频进行强制打断时，先执行短时线性淡出，再释放音频播放通路，以避免音量突变和爆音。新音频按正常音量直接开始输出。
5.5 有声资源会话心跳与保活
有声资源会话心跳仅在正文实际开始播放后启用，不覆盖串场词接收、串场词排空和正文切换准备阶段。这样云端维护的是已进入播放的有效有声资源会话，避免为尚未开播的任务产生无效保活流量。
- 周期保活：正文播放期间，设备按固定周期发送心跳，云端以响应确认有声资源会话仍然有效。
- 超时判定：首个心跳成功发出后开始等待响应；后续响应持续刷新有声资源会话活性。超过规定时限未收到响应时，判定有声资源会话失联并结束当前播放。
- 随会话结束：正文正常播完、被终止或被抢占时，同时停止心跳，避免已结束的有声资源任务继续发送心跳。
5.6 异常处理
异常按有声资源正文传输、全双工对话连接和播放进度三类场景分别处理。全双工对话连接负责传递播放、终止等指令及心跳保活；各类异常均结合所在阶段设置恢复时限，在保障连续性的同时及时收敛不可恢复故障。
| 异常场景 | 适用阶段 | 处理原则 |
|---|---|---|
| 有声资源正文传输短暂中断或无进展 | 串场词接收、串场词排空、正文切换准备、正文播放 | 采用退避方式重试，并从已确认的连续位置继续获取正文。首次开播时，若在规定时限内仍无法获得可播放正文，则结束任务，避免用户长时间等待；正文播放过程中优先利用既有缓冲覆盖短暂抖动，缓冲耗尽后仅在短暂容忍期内等待恢复，超时仍未恢复则结束有声资源会话。 |
| 全双工对话连接异常断开 | 串场词接收、串场词排空、正文切换准备 | 正文尚未开始输出时，全双工对话连接断开即取消本次任务，不再切入正文播放，避免在有声资源会话状态不确定的情况下继续执行。 |
| 全双工对话连接异常断开或心跳失联 | 正文播放 | 正文已开始播放时，短暂断开不立即中止，为全双工对话连接恢复保留时间；若在规定时间内仍未恢复，或持续收不到心跳响应，则结束当前有声资源会话。 |
| 播放进度长期无增长 | 正文播放 | 若播放进度在规定时间内持续不变，说明音频输出已无法推进，应结束当前有声资源会话，避免设备长时间无声。 |
| 设备退出对话态 | 任意活跃阶段 | 当设备退出对话态，或全双工对话连接在重连时限内仍无法恢复时，无论处于哪个播放阶段，均停止有声资源任务、回到空闲态，并等待下一次进入对话态。 |
5.7 有声资源播放耗时优化
端到端时延是从收到播放任务到用户听到正文的时间。优化目标是在不影响串场词播放和资源可控性的前提下，尽早准备正文、缩短网络建立与定位时间，并降低传输抖动对播放连续性的影响。
5.7.1 串场词与正文预取并行
- 并行准备：收到播放任务后，在串场词播放期间同步获取并解码正文。正文仅在串场词完整结束后接入音频播放通路，将“串场词播放”和“正文首段准备”两个流程并行，缩短正文开播时延。
- 受控预取：串场词阶段优先保障其传输和播放，正文以受控速率预取并使用有界缓冲暂存；切换至正文后恢复正常获取速率，在开播速度、带宽竞争和内存占用之间取得平衡。
5.7.2 HTTP 连接优化
- DNS 缓存复用：对同一资源主机缓存域名解析结果，后续拉流和续传无需重复执行域名解析，减少网络建立的首段等待。
- TLS 会话复用：复用已建立的 TLS 会话信息，使后续 HTTPS 请求尽可能避免完整握手，降低加密连接建立的往返时延。
- 持久连接复用：在连接仍可用时复用既有 HTTP 连接，减少重复创建传输连接的开销；连接不可用时自动建立新连接，不影响任务继续执行。
- 启动期预热：应用启动阶段可对预配置的常用资源主机在后台提前完成 DNS、连接和 TLS 准备，使正式拉流尽可能命中已就绪的连接状态。预热失败或未命中时，自动回退至常规建连流程，不阻塞正常播放。
5.7.3 断点续传与媒体定位优化
- ID3 元数据与缩略图跳过：MP3 文件开头的 ID3v2 标签长度可变，可能包含封面缩略图等大块二进制元数据。定位前先解析标签长度及可选尾部，整体跳过元数据区域并确定真实音频起点，避免将封面数据误判为音频；头部损坏或长度异常时，回退至从头播放路径。
- 首帧定位与媒体特征识别：从真实音频起点扫描合法 MP3 帧同步字，并校验 MPEG 版本、层、采样率、码率和帧长度等关键字段。首帧既是后续解码的可靠起点，也是识别时长、帧数、目录和码率信息的基础；若首段数据不足以找到首帧，则补充获取音频起点附近的数据后再解析。
- 分级时间位置估算：按时间位置续播时，优先使用 Xing/Info 等可变码率信息中的帧数、媒体字节数和时间目录，将目标时间映射为接近的字节位置；缺少完整目录时，基于总帧数和媒体长度进行比例估算。若未发现可变码率索引，则连续校验多帧码率：码率稳定时按恒定码率换算位置，仍无法确认时才降级为基于文件长度和总时长的线性估算，以适配可变码率、恒定码率及元数据不完整等媒体形态。
- 范围探测与帧边界对齐：在粗略位置附近获取少量媒体数据，重新扫描并对齐至有效音频帧边界后再开始播放。该过程避免从任意字节切入造成噪声、解码异常或额外重同步等待；若服务端不支持范围读取或无法可靠对齐，则放弃该定位结果并采用安全的降级路径。
6. 弱网优化：全双工对话连接的暂态错误容忍
本节聚焦全双工对话连接的弱网优化。未优化时，底层 WebSocket 传输可能将一次暂态读写失败直接视为连接失效并断开；在弱网环境中，这会导致频繁重连、重复握手和实时音频中断。
6.1 优化原因
- 暂态错误不等同于连接失效：
EAGAIN、EWOULDBLOCK、EINTR及短暂读写超时通常只表示当前暂时无法完成读写，并不意味着底层连接已经失效。 - 立即断开会放大抖动：若每次暂态错误都关闭全双工对话连接，端侧必须重新建连和握手；短暂网络波动会被放大为用户可感知的对话中断。
- 容忍必须有边界：持续无进展、心跳超时、明确的传输错误或协议错误仍应视为连接失效，避免连接长期处于不可用状态。
6.2 优化方法
- 暂时不可读写时保持连接：
EAGAIN、EWOULDBLOCK、EINTR和短暂轮询超时表示当前暂时无法完成读写，并不等于连接已断开。此时保留全双工对话连接，等待下一次可读写机会后再继续处理。 - 未发送完的数据继续发送：发送受阻时，不丢弃尚未完成发送的数据；连接恢复可写后，从中断位置继续发送。系统同时记录发送是否持续推进，避免一直等待却没有任何进展。
- 持续异常才断开重连：若长时间没有读写进展，或收到明确不可恢复的传输错误、远端关闭、协议异常、心跳超时，才清理旧连接并按重试上限重新建立全双工对话连接。
6.3 优化效果
- 提升弱网容忍度：短时网络抖动不再直接导致全双工对话连接断开，减少不必要的重连和握手。
- 保障实时交互连续性：待发送数据可在连接恢复可写后继续发送，降低短暂拥塞对实时音频交互的影响。
- 保持故障可收敛：真实断线和持续异常仍会进入重连或结束流程，避免无限等待和长期不可用。
7. 常见问题
7.1 端侧处理与网络耗时优化
将可观测耗时拆分为端侧上行处理、端侧下行处理和网络传输三类指标：
- 端侧上行处理耗时：从音频采集开始，到该包编码后的音频被全双工对话连接成功发送出去为止。该指标覆盖采集、排队、编码和端侧发送等待，不包含网络传输和云端处理。
- 端侧下行处理耗时：从首个回复音频到达端侧开始，到该音频写入音频设备为止。该指标用于评估下行接收后的解码、排队和播放处理效率，不包含云端生成耗时。
- 网络传输耗时：通过心跳请求与响应的时间差观测全双工对话连接的往返时延及其波动，用于判断网络质量和连接稳定性。
- 针对性优化：端侧上行处理耗时偏高时，检查采集帧长、编码负载和上行队列积压；端侧下行处理耗时偏高时，检查解码吞吐、播放队列和音频设备写入；网络传输耗时波动显著时，检查网络质量和重连行为。
7.2 声学前端效果排查
当平台集成 AEC、NS 或 VAD 后出现识别效果下降、残留回声明显、噪声干扰严重或语音首尾被误切时，应按“输入可回放、链路可对比、场景可复现”的方法排查，而非直接调整算法参数。
- 保留关键观测点：导出或采样保存原始麦克风音频、扬声器参考信号和声学前端处理后音频，并同步记录采样率、声道数、帧长、增益和处理参数。参考信号应优先采用实际送往扬声器的播放信号。
- 先校验时序与格式：确认麦克风与扬声器参考信号的格式兼容，二者的相对延迟处于 AEC 可补偿范围。参考信号缺失、时序错位、幅度异常或设备时延不稳定时，AEC 参数调优通常无法解决问题。
- 分场景逐级验证：至少覆盖安静近讲、稳态噪声、扬声器播放时近讲、扬声器播放时静音等场景。先确认 AEC 是否有效抑制回声，再评估 NS 是否损伤语音，最后检查 VAD 是否误切语音首尾。
- 以处理前后对比定位：通过回放或频谱对比原始麦克风、扬声器参考信号和处理后音频，依据残留回声、语音失真、漏检和误检等现象定位到对应处理环节。
7.3 音频播放流畅度与缓存排查
播放卡顿、时延持续累积或出现爆音时，应结合相关队列和音频设备缓冲的占用变化定位问题，而非统一归因为网络波动。
- 先观察各环节积压情况：等待解码的 Opus 队列持续见底，且音频设备缓冲被逐步耗尽，通常说明网络到包不足；Opus 队列持续增长而 PCM 音频队列偏低，通常说明解码吞吐不足；PCM 音频队列持续增长或音频设备写入频繁阻塞，则应排查播放设备和播放线程。
- 为软件队列和音频设备缓冲设置目标区间：软件队列用于吸收网络与解码的短时波动，音频设备缓冲用于保证连续出声。两者过小都会导致断续，持续偏大则可能会增加内存占用；应分别设置容量或时长上限，并在长期越界时输出可观测告警。
- 校验满时策略与线程调度：实时上行优先保留最新语音，下行播放优先保证时间连续性。调整队列容量、满时策略或线程优先级前，应先确认瓶颈确实位于对应环节；调整后同时验证卡顿率、丢弃率和端侧下行处理耗时。
7.4 鉴权失败排查
鉴权请求包含基于系统时间生成的时间戳。设备启动后应先完成时间校准。
- 优先检查系统时间：确认 NTP 校时是否完成，系统时间是否正确。时钟漂移或时间未同步会导致签名校验失败。