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

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

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

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

🌻1. 前言

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

要点概括

• 核心功能：注册 Stream 延迟（Latency）更新通知回调。
• 工作机制：当 PulseAudio Server 检测到 Stream 延迟发生变化时，异步通知客户端执行回调函数。

🌻2. 用法与应用场景

pa_stream_set_latency_update_callback

是 PulseAudio 延迟监控体系中的核心接口之一。

在 PulseAudio 中：

• 播放延迟会变化
• 录音延迟会变化
• 网络音频延迟会变化
• 蓝牙设备延迟会变化

因此：

应用层需要实时感知 Latency 的变化。

函数原型

void pa_stream_set_latency_update_callback(
        pa_stream *s,
        pa_stream_notify_cb_t cb,
        void *userdata);

参数说明

s:
目标 pa_stream

cb:
Latency 更新回调函数

userdata:
用户私有数据

回调函数原型

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

---

应用场景

1. 实时显示播放延迟

例如播放器：

当前播放延迟：35ms

需要实时刷新。

---

2. 音视频同步

例如：

• 视频播放器
• WebRTC
• 视频会议

需要根据延迟动态调整：

Audio Sync
Video Sync

---

3. 网络音频监控

例如：

• RTP
• RAOP(AirPlay)
• 蓝牙 A2DP

延迟会动态变化。

需要实时获取：

Latency Update

用于优化缓冲区。

---

🌻3. 调用流程剖析

🌻3.1 核心步骤

1. 应用层注册回调

pa_stream_set_latency_update_callback(
        stream,
        latency_update_cb,
        userdata);

---

2. libpulse 保存回调函数

内部类似：

stream->latency_update_callback = cb;

stream->latency_update_userdata =
        userdata;

---

3. 服务端检测延迟变化

例如：

• Buffer 增长
• Buffer 缩短
• Sink 切换
• 网络波动

都会导致：

Latency Change

---

4. PulseAudio Server 发送通知

通过 native protocol：

LATENCY_UPDATE

通知客户端。

---

5. libpulse 触发回调

内部自动执行：

stream->latency_update_callback(
        stream,
        userdata);

---

6. 应用层读取最新延迟

通常：

pa_stream_get_latency(...)

获取最新值。

---

🌻3.2 调用流程图

🌻3.3 Latency Update 生命周期图

🌻4. 实战应用案例

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

void latency_update_cb(
        pa_stream *s,
        void *userdata) {

    pa_usec_t latency;

    int negative;

    if (pa_stream_get_latency(
                s,
                &latency,
                &negative) < 0) {

        printf("get latency failed\n");
        return;
    }

    printf("Current Latency = %.2f ms\n",
           latency / 1000.0);
}

int main() {

    pa_stream *stream;

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

    pa_stream_set_latency_update_callback(
            stream,
            latency_update_cb,
            NULL);

    return 0;
}

🌻5. 源码层核心原理

pa_stream_set_latency_update_callback

在 libpulse 中本质非常简单。

内部逻辑类似：

void pa_stream_set_latency_update_callback(
        pa_stream *s,
        pa_stream_notify_cb_t cb,
        void *userdata) {

    pa_assert(s);

    s->latency_update_callback = cb;

    s->latency_update_userdata =
            userdata;
}

你会发现：

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

真正触发的位置：

通常发生在：

PA_COMMAND_REQUEST_LATENCY

或：

PA_COMMAND_STARTED

等协议事件处理过程中。

当：

Latency Changed

发生后：

libpulse 自动执行：

s->latency_update_callback(
        s,
        userdata);

因此：

它是整个 PulseAudio 延迟监控体系中的核心基础设施之一。

🌻6. 一句话总结

pa_stream_set_latency_update_callback

本质上是：

“给 Stream 延迟变化安装监听器”。

它负责：

• 感知 Latency 更新
• 获取最新延迟
• 驱动音视频同步
• 支撑网络音频监控

是 PulseAudio Latency 管理体系中的核心回调接口之一。