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

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

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

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

🌻1. 前言

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

要点概括

• 核心功能：根据 Sink Index 动态调整指定输出设备音量。
• 工作机制：客户端通过 Native Protocol 向 PulseAudio Daemon 发送音量设置请求，由服务端修改对应 Sink 的音量并同步到所有关联 Stream。

🌻2. 用法与应用场景

pa_context_set_sink_volume_by_index
是 PulseAudio 音量控制体系中最常用的接口之一。

在 PulseAudio 中：

• Speaker
• Headphone
• HDMI
• Bluetooth

最终都会对应：

一个 pa_sink 对象。

而该接口用于：

根据 Sink Index 修改指定设备音量。

函数原型

pa_operation* pa_context_set_sink_volume_by_index(
        pa_context *c,
        uint32_t idx,
        const pa_cvolume *volume,
        pa_context_success_cb_t cb,
        void *userdata);

参数说明

c:
PulseAudio Context

idx:
目标 Sink Index

volume:
目标音量

cb:
操作完成回调

userdata:
用户私有数据

返回值

返回 pa_operation 对象

用于：

• 查询操作状态
• 生命周期管理
• 等待服务端 ACK

---

应用场景

1. 调整扬声器音量

pa_context_set_sink_volume_by_index(...)

用于：

• 音量加
• 音量减
• 静音前调节

---

2. 蓝牙耳机音量同步

例如：

A2DP Headset

通过 Sink Index 定位：

bluez_sink

对应设备。

---

3. HDMI 输出音量控制

例如：

HDMI Monitor

独立调整：

• HDMI
• Speaker

音量。

---

🌻3. 调用流程剖析

🌻3.1 核心步骤

1. 应用层发起请求

pa_context_set_sink_volume_by_index(
        context,
        sink_index,
        &volume,
        success_cb,
        userdata);

---

2. libpulse 创建 operation

内部创建：

pa_operation

用于表示：

当前音量设置操作。

---

3. 封装协议数据

构造：

SET_SINK_VOLUME

请求包。

其中包含：

Sink Index
目标音量

---

4. 发送到 PulseAudio Server

通过：

Native Protocol

发送至 Daemon。

---

5. 服务端查找 Sink

Daemon 内部：

core->sinks

查找：

index == sink_index

对应设备。

---

6. 更新 Sink Volume

执行：

pa_sink_set_volume()

修改：

real_volume
reference_volume

等信息。

---

7. 同步所有 Stream

随后：

sink-input

重新计算音量。

因此：

所有正在播放的音频立即生效。

---

8. 返回 ACK

Daemon 返回：

success

客户端：

触发 success callback

---

🌻3.2 调用流程图

🌻3.3 Sink 音量控制生命周期图

🌻4. 实战应用案例

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

static void success_cb(
        pa_context *c,
        int success,
        void *userdata) {

    if (success) {

        printf("set volume success\n");

    } else {

        printf("set volume failed\n");
    }
}

void set_sink_volume(
        pa_context *context,
        uint32_t sink_index) {

    pa_cvolume volume;

    pa_operation *op;

    /*
     * 设置双声道 50%
     */
    pa_cvolume_set(
            &volume,
            2,
            PA_VOLUME_NORM / 2);

    op =
        pa_context_set_sink_volume_by_index(
                context,
                sink_index,
                &volume,
                success_cb,
                NULL);

    if (!op) {

        printf("set sink volume failed\n");
        return;
    }

    pa_operation_unref(op);
}

int main() {

    pa_context *context;

    /*
     * 假设 context 已连接成功
     */

    set_sink_volume(
            context,
            0);

    return 0;
}

🌻5. 源码层核心原理

pa_context_set_sink_volume_by_index

属于：

PulseAudio 音量控制接口。

内部核心流程：

pa_context_set_sink_volume_by_index()
        ↓
pa_pstream_send_tagstruct()
        ↓
PA_COMMAND_SET_SINK_VOLUME
        ↓
Daemon 查找 Sink
        ↓
pa_sink_set_volume()
        ↓
更新 Sink Input
        ↓
ACK

服务端最终执行：

pa_sink_set_volume()

核心对象：

pa_sink

内部保存：

real_volume
reference_volume
soft_volume

修改完成后：

所有关联 Stream
立即更新音量

因此：

pa_context_set_sink_volume_by_index

本质属于：

“设备级音量控制接口”。

🌻6. 一句话总结

pa_context_set_sink_volume_by_index

本质上是：

“根据 Sink Index 修改指定输出设备音量”。

它负责：

• 扬声器音量控制
• 蓝牙耳机音量控制
• HDMI 音量控制
• 所有播放流同步更新

是 PulseAudio 音量管理体系中的核心基础接口之一。