lucky-cat/docs/knowledge vault/downstream-audio-stutter-fix-analysis.zh-CN.md

下行音频高频卡顿问题分析、修复实现与诊断说明

1. 文档范围

本文说明下行 TTS 音频播放过程中出现短暂停顿、高频卡顿以及类似死机噪声的问题，包括：

• 问题产生原因和现场日志证据；
• 基于上次提交之后的具体修改；
• 修改后的实际效果；
• 预缓冲、自适应重缓冲、静音保护、超时保护和 generation 隔离的实现方法；
• 新增诊断日志、保护证明日志及其解读方法；
• 现场验证结果、资源影响和当前仍需验证的边界。

本次修改以当前分支上次提交为基线：

b60a037 fix(control_plane): serialize wake prompt after barge-in

相对该提交，当前工作区修改如下：

5 files changed, 692 insertions(+), 10 deletions(-)

涉及文件：

components/platform/src/multimodal/audio_pipeline.c
components/platform/src/multimodal/audio_pipeline/audio_pipeline_codec_impl.c
components/platform/src/multimodal/audio_pipeline/audio_pipeline_runtime_impl.c
main/Kconfig.projbuild
sdkconfig.defaults

2. 问题现象

现场出现过两类相关现象。

2.1 播放中途短暂停顿

典型表现是 TTS 已经开始，例如播放到“哟”之后停住一小会儿，然后继续播放。

对应日志：

W multimodal_audio: Downstream diagnostics active_wait:
response_age_ms=740
first_packet=1
last_packet_age_ms=520
first_playback=1
last_playback_age_ms=250
queued=7
played=7
pending_estimate=0
enqueue_failures=0
playback_failures=0

W multimodal_audio: Downstream diagnostics:
queue recovered after 430 ms empty

这里可以直接看出：

• 已经收到首包并开始播放；
• 总共入队 7 包，也已经播放 7 包；
• pending_estimate=0，说明播放队列已经完全耗空；
• 520 ms 没有收到新包；
• 队列实际保持空状态约 430 ms；
• 没有入队失败；
• 没有 Opus 解码或 codec 写入失败。

结合两条日志的时间差，连续音频包之间存在约 720 ms 的到包空洞。已有库存吸收其中一部分，最终仍产生约 430 ms 的可听暂停。

2.2 长时间高频卡顿或类似死机噪声

另一类现象是响应已经开始，但首包或后续音频长时间不再到达。设备其他任务和 WebSocket 心跳仍然正常，但扬声器输出可能持续异常。

这说明问题不是整机死机，而是：

下行响应仍处于 active
        ↓
没有新的音频包或播放进展
        ↓
播放队列耗空
        ↓
输出路径没有及时进入安全静音
        ↓
I2S/DMA 可能保持残留输出
        ↓
出现持续高频声或类似死机的卡顿感

3. 问题产生原因

问题不是单一故障，而是“上游供包空洞”和“设备端缺少抗抖动及失效保护”共同形成的。

3.1 直接触发原因：下行音频供包不连续

现场已经明确观察到：

last_packet_age_ms=520
queued=7
played=7
pending_estimate=0
queue recovered after 430 ms empty

因此直接触发原因是下行音频包没有按正常节奏持续进入播放器。

空洞可能来自：

• 服务端 TTS 流式生成节奏不连续；
• 服务端或代理层批量发送；
• Wi-Fi 或公网传输抖动；
• WebSocket 接收任务调度延迟。

现有 WebSocket 采样日志显示，在被采样的时刻，event、worker 和会话回调通常只相差 0～10 ms，队列深度通常为 0～1，暂时没有发现本地 WebSocket worker 长时间积压。因此目前更倾向于服务端供包节奏或网络传输抖动。

但现有 WebSocket 日志是定期采样，不是逐异常包链路跟踪，所以还不能仅凭它严格区分服务端和网络。

3.2 原有播放器收到首包就开始播放

更新前的播放逻辑基本等价于：

if (queue != NULL) {
    received = xQueueReceive(queue, &packet, pdMS_TO_TICKS(20));
}

if (received == pdTRUE) {
    handle_downstream_opus_sync(packet.data, packet.len);
}

首包到达后立即开始播放，没有固定的初始 jitter buffer。

这种策略首字延迟低，但只要后续包出现较大间隔，队列就很容易耗空。

3.3 原有逻辑没有耗空后的重缓冲状态

更新前队列耗空后，一旦下一包到达就立即恢复播放。

如果网络持续不稳定，播放会变成：

收到 1 包 → 播放 1 包 → 再次耗空 → 等待 → 收到 1 包 → 再播放

这会造成反复启停。听感上可能不只是一次干净的停顿，而是连续的高频卡顿或抖动。

3.4 active 响应会抑制原有 idle mute

原有定时器在响应 active 时主要进行诊断并返回：

if (snapshot_downstream_response_active()) {
    log_downstream_active_diagnostics();
    arm_downstream_active_diagnostics(ctx);
    return;
}

如果响应状态一直没有结束，但音频已经停止，输出路径可能长期没有进入正常的 idle mute。

3.5 I2S 原来没有显式启用 DMA 自动清零

原 I2S 初始化只设置 DMA descriptor 和 frame 数量：

i2s_chan_config_t chan_cfg = I2S_CHANNEL_DEFAULT_CONFIG(
        (i2s_port_t)CONFIG_MULTIMODAL_AUDIO_I2S_PORT,
        I2S_ROLE_MASTER);
chan_cfg.dma_desc_num = CONFIG_MULTIMODAL_AUDIO_I2S_DMA_DESC_NUM;
chan_cfg.dma_frame_num = CONFIG_MULTIMODAL_AUDIO_I2S_DMA_FRAME_NUM;

在上层断流或写入停止时，缺少显式的 DMA 自动清零保护，会增加旧采样残留或重复输出的风险。

3.6 旧响应包缺少 generation 标识

原来的下行包只包含长度和数据指针：

typedef struct {
    size_t len;
    uint8_t *data;
} downstream_packet_t;

当响应被打断、超时或切换时，队列中迟到的旧包缺少明确的响应归属信息，存在被下一次播放路径消费的风险。

4. 本次更新后的具体效果

4.1 正常播放开始前保留至少 180 ms 音频库存

配置值为 160 ms：

CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_PREBUFFER_MS=160

当前 Opus 帧长为 60 ms，代码向上取整：

static UBaseType_t get_downstream_prebuffer_packet_count(
        const multimodal_audio_ctx_t *ctx)
{
    uint32_t frame_ms = ctx != NULL && ctx->opus_frame_duration_ms != 0U ?
            ctx->opus_frame_duration_ms : 20U;
    uint32_t packet_count =
            ((uint32_t)CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_PREBUFFER_MS +
             frame_ms - 1U) /
            frame_ms;
    if (packet_count == 0U) {
        packet_count = 1U;
    }
    UBaseType_t queue_len = get_downstream_playback_queue_len();
    return packet_count > (uint32_t)queue_len ?
            queue_len : (UBaseType_t)packet_count;
}

计算结果：

ceil(160 / 60) = 3 包
3 × 60 ms = 180 ms 音频库存

这不是固定增加 180 ms 的墙钟延迟。服务端可能批量到包，现场等待到第 3 包通常只需要 10～40 ms。

4.2 较大到包抖动可以由库存直接吸收

更新后的现场日志出现过：

Downstream diagnostics playback_complete:
response_age_ms=8560
queued=142
played=142
depth_max=30
arrival_gap_ms(min/avg/max)=0/47/560
empty_events=0
enqueue_failures=0
playback_failures=0

说明：

• 音频包之间出现过最大 560 ms 间隔；
• 队列最高累计 30 包，即约 1.8 秒音频；
• 队列没有耗空；
• 142 个包全部正常播放；
• 用户没有听到高频卡顿。

这是已经由现场日志验证的改善。

4.3 队列真正耗空后转为安全静音和重缓冲

空队列检测阈值：

CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_REBUFFER_GAP_MS=120

队列连续为空 120 ms 后：

1. codec 输出音量设置为 0；
2. 不再收到一包就立即播放；
3. 播放状态切换为等待缓存；
4. 达到恢复目标后再统一恢复。

关键实现：

if (received != pdTRUE || packet.data == NULL || packet.len == 0U) {
    if (snapshot_downstream_response_end_received()) {
        maybe_notify_downstream_playback_completed_after_drain("queue_empty");
    } else if (playback_buffer_ready &&
               generation_started &&
               snapshot_downstream_response_active()) {
        TickType_t now = xTaskGetTickCount();
        if (queue_empty_since == 0U) {
            queue_empty_since = now;
            note_downstream_queue_empty();
        }

        uint32_t empty_ms =
                (uint32_t)pdTICKS_TO_MS(now - queue_empty_since);
        if (empty_ms >= get_downstream_rebuffer_gap_ms(ctx)) {
            if (recovery_underrun_count < UINT32_MAX) {
                recovery_underrun_count++;
            }

            UBaseType_t recovery_target =
                    get_downstream_recovery_packet_count(
                            ctx,
                            recovery_underrun_count);

            (void)set_downstream_output_mute_if_needed(
                    ctx,
                    true,
                    "Playback underrun");

            playback_buffer_ready = false;
            underrun_since = queue_empty_since;
            buffer_wait_since = now;
            first_recovery_packet_tick = 0U;
            queue_empty_since = 0U;

            ESP_LOGW(TAG,
                     "Downstream protection engaged: "
                     "empty_ms=%u underrun=%u "
                     "recovery_target=%u packets "
                     "target_ms=%u output_muted=1",
                     (unsigned)empty_ms,
                     (unsigned)recovery_underrun_count,
                     (unsigned)recovery_target,
                     (unsigned)((uint32_t)recovery_target *
                                ctx->opus_frame_duration_ms));
        }
    }

    vTaskDelay(pdMS_TO_TICKS(10));
    continue;
}

4.4 重复断流时自适应提高恢复库存

最大恢复缓存配置：

CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_MAX_REBUFFER_MS=640

实现：

static UBaseType_t get_downstream_recovery_packet_count(
        const multimodal_audio_ctx_t *ctx,
        uint32_t underrun_count)
{
    uint32_t frame_ms =
            ctx != NULL && ctx->opus_frame_duration_ms != 0U ?
            ctx->opus_frame_duration_ms : 20U;

    uint32_t base_ms =
            (uint32_t)CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_PREBUFFER_MS;
    if (base_ms < frame_ms) {
        base_ms = frame_ms;
    }

    uint32_t max_ms =
            (uint32_t)CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_MAX_REBUFFER_MS;
    if (max_ms < base_ms) {
        max_ms = base_ms;
    }

    uint64_t scaled_ms =
            (uint64_t)base_ms * ((uint64_t)underrun_count + 1ULL);
    uint32_t recovery_ms =
            scaled_ms > max_ms ? max_ms : (uint32_t)scaled_ms;

    uint32_t packet_count =
            (recovery_ms + frame_ms - 1U) / frame_ms;
    UBaseType_t queue_len = get_downstream_playback_queue_len();
    return packet_count > (uint32_t)queue_len ?
            queue_len : (UBaseType_t)packet_count;
}

当前 60 ms 帧对应：

本次响应内耗空次数	理论目标	实际包数	实际库存
第 1 次	320 ms	6 包	360 ms
第 2 次	480 ms	8 包	480 ms
第 3 次及以后	640 ms	11 包	660 ms

网络越不稳定，同一次响应后续恢复时越保守，避免反复出现“恢复一下又耗空”。

4.5 I2S DMA 无新数据时自动清零

更新后的 I2S 初始化：

static esp_err_t init_i2s_bus(multimodal_audio_ctx_t *ctx)
{
    if (!ctx) {
        return ESP_ERR_INVALID_ARG;
    }

    i2s_chan_config_t chan_cfg = I2S_CHANNEL_DEFAULT_CONFIG(
            (i2s_port_t)CONFIG_MULTIMODAL_AUDIO_I2S_PORT,
            I2S_ROLE_MASTER);
    chan_cfg.dma_desc_num = CONFIG_MULTIMODAL_AUDIO_I2S_DMA_DESC_NUM;
    chan_cfg.dma_frame_num = CONFIG_MULTIMODAL_AUDIO_I2S_DMA_FRAME_NUM;
    chan_cfg.auto_clear_after_cb = true;

    esp_err_t err = i2s_new_channel(
            &chan_cfg,
            &ctx->tx_handle,
            &ctx->rx_handle);
    if (err != ESP_OK) {
        ESP_LOGE(TAG,
                 "Create I2S channels failed: %s",
                 esp_err_to_name(err));
        return err;
    }

    /* 后续标准 I2S 配置保持不变。 */
    return ESP_OK;
}

作用：

• 上层停止写入时清理 DMA 输出；
• 降低重复旧采样或残留波形的风险；
• 配合 codec 音量门控，将异常断流表现控制为安静暂停。

本次没有新增直接切换 PA GPIO 的逻辑。PA 原有控制方式保持不变，断流保护使用 codec 输出音量归零和 I2S DMA 自动清零。

4.6 3 秒无音频且无新包时终止异常响应

配置：

CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_ACTIVE_STALL_MUTE_MS=3000

上下文增加：

typedef struct {
    /* 其他字段省略。 */
    bool downstream_response_active;
    bool downstream_response_end_received;
    TickType_t downstream_last_audio_tick;
    TickType_t downstream_last_response_activity_tick;
    esp_timer_handle_t downstream_idle_mute_timer;
    /* 其他字段省略。 */
} multimodal_audio_ctx_t;

定时器回调：

static void downstream_idle_mute_timer_cb(void *arg)
{
    multimodal_audio_ctx_t *ctx =
            (multimodal_audio_ctx_t *)arg;
    if (ctx == NULL) {
        return;
    }

    const bool response_active =
            snapshot_downstream_response_active();

    if (response_active) {
        log_downstream_active_diagnostics();

        TickType_t now = xTaskGetTickCount();
        TickType_t last_audio_tick =
                snapshot_downstream_last_audio_tick(ctx);
        uint32_t idle_ms = last_audio_tick != 0U ?
                (uint32_t)pdTICKS_TO_MS(now - last_audio_tick) : 0U;

        uint32_t idle_timeout_ms =
                get_downstream_idle_mute_timeout_ms();
        uint32_t stall_timeout_ms =
                get_downstream_active_stall_mute_timeout_ms();

        if (idle_ms < idle_timeout_ms) {
            restart_downstream_idle_mute_timer(
                    ctx,
                    idle_timeout_ms - idle_ms);
            return;
        }

        if (ctx->initialized && ctx->codec_dev != NULL) {
            (void)set_downstream_output_mute_if_needed(
                    ctx,
                    true,
                    "Active response gap");
        }

        if (idle_ms < stall_timeout_ms) {
            uint32_t remaining_ms = stall_timeout_ms - idle_ms;
#if CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_DIAGNOSTICS_ENABLE
            if (remaining_ms >
                MULTIMODAL_AUDIO_DOWNSTREAM_DIAGNOSTICS_ACTIVE_INTERVAL_MS) {
                remaining_ms =
                        MULTIMODAL_AUDIO_DOWNSTREAM_DIAGNOSTICS_ACTIVE_INTERVAL_MS;
            }
#endif
            restart_downstream_idle_mute_timer(ctx, remaining_ms);
            return;
        }

        TickType_t last_activity_tick =
                snapshot_downstream_last_response_activity_tick(ctx);
        uint32_t response_idle_ms = last_activity_tick != 0U ?
                (uint32_t)pdTICKS_TO_MS(now - last_activity_tick) :
                idle_ms;

        if (response_idle_ms < stall_timeout_ms) {
            restart_downstream_idle_mute_timer(
                    ctx,
                    stall_timeout_ms - response_idle_ms);
            return;
        }

        abort_downstream_response_after_active_stall(ctx, idle_ms);
        return;
    }

    if (ctx->initialized && ctx->codec_dev != NULL) {
        (void)set_downstream_output_mute_if_needed(
                ctx,
                true,
                "Idle mute");
    }

    maybe_notify_downstream_playback_completed_after_drain("idle");
}

终止异常响应：

static void abort_downstream_response_after_active_stall(
        multimodal_audio_ctx_t *ctx,
        uint32_t idle_ms)
{
    ESP_LOGW(TAG,
             "Downstream protection watchdog: "
             "abort stalled response idle_ms=%u",
             (unsigned)idle_ms);

    (void)advance_downstream_playback_generation();
    notify_downstream_playback_stopped();
    update_downstream_response_state(false, false);

    if (audio_get_downstream_playback_task(ctx) != NULL ||
        audio_get_downstream_playback_starting(ctx)) {
        audio_set_downstream_playback_stopping(ctx, true);
        audio_set_downstream_playback_keep_stopping_on_exit(ctx, false);
        audio_set_downstream_playback_stop_requested(ctx, true);
    }

    drain_downstream_playback_queue_now(ctx);
}

判断逻辑不是单纯“3 秒没有播放就终止”，而是同时参考：

• 最后一次成功音频输出时间；
• 最后一次下行音频包活动时间。

如果包仍在到达，只是暂时没有输出，会保持静音并继续等待；只有两者都停滞达到阈值才终止。

4.7 使用 generation 隔离新旧响应

下行包增加 generation：

typedef struct {
    size_t len;
    uint32_t playback_generation;
    uint8_t *data;
} downstream_packet_t;

入队时标记：

downstream_packet_t packet = {
    .len = len,
    .playback_generation =
            snapshot_downstream_playback_generation(),
    .data = (uint8_t *)audio_psram_first_malloc(len),
};

播放前验证：

if (packet.playback_generation !=
    snapshot_downstream_playback_generation()) {
    free_downstream_packet(&packet);
    continue;
}

响应被打断、超时或切换后，旧 generation 的迟到包会被释放，不会继续送入新的解码播放流程。

5. 播放状态机具体实现

播放任务新增以下状态：

downstream_packet_t packet = {0};
uint32_t buffered_generation = UINT32_MAX;
TickType_t buffer_wait_since = 0U;
TickType_t queue_empty_since = 0U;
TickType_t underrun_since = 0U;
TickType_t first_recovery_packet_tick = 0U;
bool playback_buffer_ready = false;
bool generation_started = false;
uint32_t recovery_underrun_count = 0U;

含义：

字段	含义
buffered_generation	当前状态机服务的响应 generation
buffer_wait_since	本次初始或恢复缓存开始时间
queue_empty_since	连续空队列开始时间
underrun_since	本次真正 underrun 起始时间
first_recovery_packet_tick	耗空后第一包重新到达时间
playback_buffer_ready	是否已经达到允许播放的库存
generation_started	当前响应是否已经成功开始播放
recovery_underrun_count	当前响应内累计耗空次数

generation 变化时全部重置：

uint32_t current_generation =
        snapshot_downstream_playback_generation();

if (current_generation != buffered_generation) {
    buffered_generation = current_generation;
    buffer_wait_since = xTaskGetTickCount();
    queue_empty_since = 0U;
    underrun_since = 0U;
    first_recovery_packet_tick = 0U;
    playback_buffer_ready = false;
    generation_started = false;
    recovery_underrun_count = 0U;
}

未达到缓存目标时不出队播放：

if (queue != NULL && !playback_buffer_ready) {
    UBaseType_t queued_packets =
            uxQueueMessagesWaiting(queue);

    UBaseType_t target_packets = generation_started ?
            get_downstream_recovery_packet_count(
                    ctx,
                    recovery_underrun_count) :
            get_downstream_prebuffer_packet_count(ctx);

    TickType_t now = xTaskGetTickCount();

    if (generation_started &&
        queued_packets > 0U &&
        first_recovery_packet_tick == 0U) {
        first_recovery_packet_tick = now;
    }

    bool response_ended =
            snapshot_downstream_response_end_received();

    if (queued_packets >= target_packets ||
        (response_ended && queued_packets > 0U)) {
        playback_buffer_ready = true;
    }
}

只有 ready 后才消费队列：

if (queue != NULL && playback_buffer_ready) {
    received = xQueueReceive(
            queue,
            &packet,
            pdMS_TO_TICKS(20));
}

这就是本次从“数据驱动立即播放”改为“带初始缓冲和恢复缓冲的状态机播放”的核心。

6. 日志更新

6.1 可配置诊断开关

新增 Kconfig：

config MULTIMODAL_AUDIO_DOWNSTREAM_DIAGNOSTICS_ENABLE
    bool "Enable downstream audio diagnostics"
    default n
    help
        Collect and report low-rate downstream audio timing, queue
        depth, queue starvation, enqueue failure, and playback
        failure statistics. Active responses also report a
        once-per-second wait snapshot when no audio advances.
        Disabled by default to avoid diagnostic logging and
        per-packet accounting in production builds.

默认配置：

# CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_DIAGNOSTICS_ENABLE is not set

当前现场测试使用的本地 sdkconfig 已开启该配置，因此能看到完整诊断日志。产品默认仍为关闭。

6.2 诊断统计结构

#if CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_DIAGNOSTICS_ENABLE
typedef struct {
    TickType_t response_begin_tick;
    TickType_t arrival_last_tick;
    TickType_t first_arrival_tick;
    TickType_t first_playback_tick;
    TickType_t last_playback_tick;
    TickType_t queue_empty_since_tick;
    uint32_t arrival_gap_min_ms;
    uint32_t arrival_gap_max_ms;
    uint64_t arrival_gap_total_ms;
    uint32_t arrival_gap_samples;
    UBaseType_t queue_depth_min;
    UBaseType_t queue_depth_max;
    uint32_t queue_empty_events;
    uint32_t queue_empty_max_ms;
    uint32_t enqueue_failures;
    uint32_t playback_failures;
    bool summary_logged;
} downstream_diagnostics_t;

static downstream_diagnostics_t s_downstream_diagnostics;
#endif

关闭诊断后，对应函数使用空内联实现：

static inline void reset_downstream_diagnostics(void) {}
static inline void note_downstream_arrival(UBaseType_t queue_depth)
{
    (void)queue_depth;
}
static inline void note_downstream_playback(void) {}
static inline void note_downstream_queue_empty(void) {}
static inline void note_downstream_queue_recovered(void) {}
static inline void note_downstream_enqueue_failure(void) {}
static inline void note_downstream_playback_failure(void) {}

因此关闭时不会保留逐包诊断统计开销。

6.3 首包日志

Downstream diagnostics first packet:
wait_ms=20 queue_depth=1

含义：

• wait_ms：响应开始到首包入队的时间；
• queue_depth：首包入队后的队列深度。

6.4 首次播放日志

Downstream diagnostics first playback:
wait_ms=80

表示响应开始到第一次成功写入 codec 的时间。

6.5 播放完成汇总日志

Downstream diagnostics playback_complete:
response_age_ms=8560
first_packet=1
first_packet_ms=20
last_packet_age_ms=1820
first_playback=1
first_playback_ms=80
last_playback_age_ms=20
queued=142
played=142
current_depth=0
depth_min=1
depth_max=30
arrival_gap_ms(min/avg/max)=0/47/560
empty_events=0
empty_max_ms=0
enqueue_failures=0
playback_failures=0

关键判断：

字段	判断方法
first_packet=0	响应开始后首包始终没有到
first_packet=1 first_playback=0	包已到，但本地解码/播放没有推进
queued == played	所有成功入队的包都已消费
current_depth	汇总时队列剩余包数
depth_max	本次响应形成过的最大音频库存
arrival_gap_ms(.../max)	最大连续到包间隔
empty_events	播放期间队列实际耗空并恢复次数
enqueue_failures	包分配或入队失败次数
playback_failures	解码或 codec 写入失败次数

6.6 active_wait 日志

响应仍然 active、但音频没有继续推进时输出：

Downstream diagnostics active_wait:
response_age_ms=...
first_packet=...
last_packet_age_ms=...
first_playback=...
last_playback_age_ms=...
queued=...
played=...
pending_estimate=...
enqueue_failures=...
playback_failures=...

判断方式：

• first_packet=0：零首包停滞；
• first_packet=1 first_playback=0：包已到但播放未启动；
• pending_estimate=0 且 last_packet_age_ms 持续增长：下行供包停止；
• pending_estimate>0 且 last_playback_age_ms 持续增长：本地播放器或 I2S 路径阻塞。

6.7 初始缓存证明日志

诊断开启时输出：

Downstream protection evidence:
initial_wait_ms=30
buffered_ms=180
first_audio_jitter_budget_ms=180

证明播放不是从首包立即开始，而是在开始前形成了指定音频库存。

现场还出现过：

Downstream protection evidence:
initial_wait_ms=20
buffered_ms=1200
first_audio_jitter_budget_ms=1200

说明服务端当时批量到包，在播放任务开始消费前已经形成 20 包、约 1.2 秒库存。

6.8 耗空保护日志

队列连续空达到阈值时，无论诊断开关是否开启，都会保留关键运行告警：

Downstream protection engaged:
empty_ms=120
underrun=1
recovery_target=6 packets
target_ms=360
output_muted=1

这条日志说明：

• 队列确实连续空了 120 ms；
• 输出已经静音；
• 播放器已经进入重缓冲；
• 第一次恢复需要 6 包，即约 360 ms 音频。

6.9 恢复证明日志

达到恢复目标时，普通运行日志输出：

Downstream recovery buffer ready:
depth=6
target=6
buffered_ms=360
waited_ms=...
outage_ms=...

诊断开启时额外输出：

Downstream protection evidence:
underrun=1
outage_ms=...
first_packet_wait_ms=...
held_after_first_packet_ms=...
buffered_ms=360
legacy_would_resume_at_first_packet=1

字段含义：

• first_packet_wait_ms：耗空后重新等到第一包的时间；
• held_after_first_packet_ms：第一包到达后，新逻辑继续等待库存的时间；
• buffered_ms：真正恢复时的库存；
• legacy_would_resume_at_first_packet=1：旧逻辑此时会直接恢复。

如果：

held_after_first_packet_ms > 0
buffered_ms >= target_ms

就能从日志证明新逻辑没有“来一包播一包”，而是等待形成连续播放能力后再恢复。

6.10 watchdog 日志

音频输出和下行包活动都停滞达到 3 秒时：

Downstream protection watchdog:
abort stalled response idle_ms=3000

表示异常 generation 已终止、旧队列已清理，输出保持静音。

6.11 WebSocket 日志说明

以下日志不是本次新增，原来已经存在：

WS binary event queued
WS binary worker frame
Downstream binary frame

它们是定期采样日志，可观察：

• WebSocket 原始 event 是否进入队列；
• worker 是否积压；
• 会话回调是否被调用。

现有现场日志中，这三层通常相差 0～10 ms，pending 通常为 0，说明采样时本地 WebSocket 路径没有明显拥塞。

因为它们不是逐异常包记录，所以目前不能用它们严格定位 560 ms 或 720 ms 空洞发生在服务端还是公网传输阶段。

7. 配置更新

Kconfig 新增：

config MULTIMODAL_AUDIO_DOWNSTREAM_ACTIVE_STALL_MUTE_MS
    int "Downstream active response stall timeout (ms)"
    default 3000
    range 500 10000

config MULTIMODAL_AUDIO_DOWNSTREAM_PREBUFFER_MS
    int "Downstream playback prebuffer (ms)"
    default 160
    range 0 1000

config MULTIMODAL_AUDIO_DOWNSTREAM_REBUFFER_GAP_MS
    int "Downstream underrun detection delay (ms)"
    default 120
    range 20 500

config MULTIMODAL_AUDIO_DOWNSTREAM_MAX_REBUFFER_MS
    int "Maximum adaptive downstream recovery buffer (ms)"
    default 640
    range 160 2000

config MULTIMODAL_AUDIO_DOWNSTREAM_DIAGNOSTICS_ENABLE
    bool "Enable downstream audio diagnostics"
    default n

默认配置：

# CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_DIAGNOSTICS_ENABLE is not set
CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_ACTIVE_STALL_MUTE_MS=3000
CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_PREBUFFER_MS=160
CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_REBUFFER_GAP_MS=120
CONFIG_MULTIMODAL_AUDIO_DOWNSTREAM_MAX_REBUFFER_MS=640

保护功能和诊断开关相互独立：

• 关闭诊断不会关闭预缓冲、重缓冲、I2S 清零和 watchdog；
• 关闭诊断只移除逐包统计和详细 evidence 日志；
• 关键运行告警仍会保留。

8. 更新前后行为对比

场景	更新前	更新后
开始播放	首包到达即播放	至少形成 3 包、180 ms 库存
普通小抖动	容易消耗掉全部余量	优先由初始库存吸收
较大到包间隔	可能出现短暂停顿	实际库存足够时完全无感
队列耗空	下一包到达即恢复	空 120 ms 后静音并进入重缓冲
连续耗空	反复来一包播一包	恢复目标逐步增加到约 660 ms
长时间无包	active 状态可能长期保持	音频和包都停滞 3 秒后终止
I2S 无新数据	存在残留输出风险	DMA callback 后自动清零
响应切换	旧包归属不明确	generation 不匹配直接丢弃
问题定位	缺少完整队列时序	可区分供包、入队、播放和耗空

9. 当前现场验证结论

最新日志中：

Downstream response begin                    21 次
Downstream diagnostics playback_complete     16 次
Downstream protection engaged                 0 次
Downstream recovery buffer ready              0 次
Downstream protection watchdog                0 次
active_wait                                   0 次
codec write failed                            0 次
opus decode failed                            0 次

16 次完整播放汇总全部满足：

empty_events=0
enqueue_failures=0
playback_failures=0

最长的一次到包间隔：

arrival_gap_max=560 ms
depth_max=30
queued=142
played=142
empty_events=0

因此可以确认：

1. 高频卡顿没有再次复现；
2. 上游较大的供包抖动实际出现过；
3. 这次 560 ms 抖动被队列库存完全吸收；
4. 初始预缓冲和更充裕的队列余量已经产生实际效果；
5. 尚未现场触发真正耗空后的 360～660 ms 自适应恢复路径；
6. watchdog 保护已实现并通过构建，但尚未由真实 3 秒停滞触发验证。

10. 资源影响

10.1 Flash

构建结果：

诊断开启：0x1e1af0
诊断关闭：0x1e1080

大致影响：

• 保护逻辑约增加 2 KB Flash；
• 开启诊断相对关闭再增加约 2.7 KB Flash。

10.2 RAM 和 PSRAM

• downstream_packet_t 增加一个 uint32_t playback_generation；
• 当前队列长度为 1024，队列存储优先分配在 PSRAM；
• generation 字段约增加 4 KB PSRAM；
• 恢复缓存通常持有 6～11 个 Opus 包，约占 1～3 KB PSRAM；
• 诊断结构体只在诊断开启时存在。

10.3 CPU 和任务

• 没有新增任务；
• 复用现有下行播放任务；
• 复用现有 idle mute 定时器；
• 增加少量队列深度检查和时间戳计算；
• I2S 自动清零由驱动完成，不新增软件任务。

11. 构建验证

已经完成：

诊断开启配置构建通过
诊断关闭配置构建通过
架构边界检查通过
git diff --check 通过

两种配置均无新增编译告警。

12. 最终结论

本次问题的直接触发点是下行 TTS 音频供包出现数百毫秒空洞；设备端原有首包立即播放、缺少耗空重缓冲、active 响应抑制 idle mute、I2S 未启用自动清零等因素，使普通网络抖动可能进一步表现为明显停顿、反复启停或高频残留声。

本次更新将播放器改为带初始预缓冲和自适应恢复缓冲的状态机，并增加 codec 静音、I2S DMA 自动清零、3 秒双进度 watchdog、generation 隔离和可关闭诊断。

当前现场已经证明 560 ms 到包抖动被库存完整吸收，未出现队列耗空或高频卡顿。真正队列耗空后的自适应恢复和 watchdog 路径已经完成实现与构建验证，仍需等待一次更严重的真实下行断流完成现场验证。