简介： CSDN博客专家、《Android系统多媒体进阶实战》作者

博主新书推荐：《Android系统多媒体进阶实战》🚀
Android Audio工程师专栏地址： Audio工程师进阶系列【原创干货持续更新中……】🚀
Android多媒体专栏地址： 多媒体系统工程师系列【原创干货持续更新中……】🚀
专题一 二：AAOS车载系统+AOSP14系统攻城狮入门视频实战课 🚀
专题三：Android14 Binder之HIDL与AIDL通信实战课 🚀
专题四：Android15快速自定义与集成音效实战课 🚀
专题五：Android15音频策略实战课 🚀
专题六：Android15音频性能实战课(无声/杂音/断音/爆音实战案例) 🚀

人生格言： 人生从来没有捷径，只有行动才是治疗恐惧和懒惰的唯一良药.

更多原创,欢迎关注：Android系统攻城狮

🌻1. 前言

本篇目的：Linux PulseAudio 深度解析之 pa_stream_set_underflow_callback 调用流程与实战。

要点概括

• 核心功能：注册 Stream Underflow（欠载）事件回调函数。
• 工作机制：当 PulseAudio 检测到播放缓冲区数据不足时，由 libpulse 内部异步触发 underflow 回调。

🌻2. 用法与应用场景

pa_stream_set_underflow_callback
是 PulseAudio 中用于监听：

“播放缓冲区欠载（Underflow）”

的重要接口。

所谓：

Underflow

本质上是：

声卡播放速度 > 应用写入速度

导致：

• 缓冲区被播放空
• PCM 数据断流
• 出现爆音、卡顿、静音

因此：

Underflow 是音频播放最重要的异常状态之一。

函数原型

void pa_stream_set_underflow_callback(
        pa_stream *p,
        pa_stream_notify_cb_t cb,
        void *userdata);

参数说明

p:
目标 pa_stream

cb:
underflow 回调函数

userdata:
用户私有数据

回调函数原型

typedef void (*pa_stream_notify_cb_t)(
        pa_stream *p,
        void *userdata);

---

应用场景

1. 检测音频卡顿

underflow callback

通常意味着：

• 数据写入不及时
• CPU 忙
• 解码太慢
• IO 阻塞

---

2. 动态调整 Buffer

例如：

• 增大 latency
• 增大 tlength
• 增大 prebuf

减少：

underflow

发生概率。

---

3. 音频性能调优

播放器通常会统计：

underflow 次数

用于：

• 性能分析
• 延迟优化
• Buffer 调优

---

🌻3. 调用流程剖析

🌻3.1 核心步骤

1. 应用层注册回调

pa_stream_set_underflow_callback(
        stream,
        underflow_cb,
        userdata);

---

2. libpulse 保存回调函数

内部本质执行：

stream->underflow_callback = cb;
stream->underflow_userdata = userdata;

---

3. Stream 播放发生 Underflow

例如：

• 应用 write 太慢
• PCM 数据断流
• 缓冲区被播放空

都会导致：

underflow

事件。

---

4. 服务端检测欠载

PulseAudio Server 检测：

buffer empty

随后通过 native protocol 通知客户端。

---

5. libpulse 触发回调

客户端收到事件后：

libpulse 自动执行：

stream->underflow_callback(
        stream,
        userdata);

---

🌻3.2 调用流程图

🌻3.3 Underflow 生命周期图

🌻4. 实战应用案例

#include <pulse/pulseaudio.h>
#include <stdio.h>

static int underflow_count = 0;

/*
 * Underflow 回调
 */
void underflow_cb(
        pa_stream *s,
        void *userdata) {

    underflow_count++;

    printf("Underflow detected!\n");

    printf("underflow count = %d\n",
           underflow_count);
}

void setup_underflow_callback(
        pa_stream *stream) {

    /*
     * 注册 underflow callback
     */
    pa_stream_set_underflow_callback(
            stream,
            underflow_cb,
            NULL);
}

void write_audio_slowly(
        pa_stream *stream,
        const void *data,
        size_t len) {

    /*
     * 模拟 write 不及时
     */
    usleep(500000);

    pa_stream_write(
            stream,
            data,
            len,
            NULL,
            0,
            PA_SEEK_RELATIVE);
}

int main() {

    pa_stream *stream;

    /*
     * 假设 stream 已 connect 成功
     */

    setup_underflow_callback(stream);

    return 0;
}

🌻5. 源码层核心原理

pa_stream_set_underflow_callback
在 libpulse 中本质非常简单。

内部逻辑类似：

void pa_stream_set_underflow_callback(
        pa_stream *p,
        pa_stream_notify_cb_t cb,
        void *userdata) {

    pa_assert(p);

    p->underflow_callback = cb;
    p->underflow_userdata = userdata;
}

你会发现：

它本质只是保存函数指针。

真正触发 callback 的位置：

通常发生在：

underflow event packet

到达客户端时。

随后：

libpulse 自动调用：

p->underflow_callback(
        p,
        userdata);

因此：

它属于：

PulseAudio 异步事件通知体系的一部分。

底层涉及：

• native protocol
• playback buffer
• sink latency
• memblockq
• IO thread

等核心机制。

🌻6. 一句话总结

pa_stream_set_underflow_callback
本质上是：

“给 PulseAudio 播放缓冲区安装欠载报警器”。

它负责：

• 检测 Buffer 被播放空
• 检测音频卡顿
• 统计 Underflow 次数
• 支撑播放器性能调优

是 PulseAudio 播放稳定性分析中的核心基础接口之一。