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

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

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

🌻1.前言

本篇目的：

Linux PipeWire深度解析之pw_stream_flush调用流程与实战。

要点概括

• 核心功能：清理PipeWireStream内部仍在排队的数据，必要时等待已提交数据完成播放或采集。

• 工作机制：根据drain参数决定是立即Flush队列，还是进入Drain流程，等待已提交数据处理完成后触发drained回调。

• 典型用途：暂停后清队列、切歌、Seek、停止播放前排空、设备切换前清理残留数据、低延迟链路恢复。

pw_stream_flush的本质不是“销毁Stream”，也不是“归还单个Buffer”，而是对整个Stream的数据队列进行清理或排空控制。它处理的是Stream级别的数据状态，而不是单个pw_buffer对象。

它和pw_stream_queue_buffer不同。pw_stream_queue_buffer用于把应用已经处理完的Buffer交还给PipeWire；pw_stream_flush用于清理Stream中已经排队或正在转换的数据。

它和pw_stream_set_active也不同。pw_stream_set_active用于激活或停止Stream参与图调度；pw_stream_flush用于处理队列残留。暂停Stream后，如果不清理残留数据，恢复时可能继续播放旧数据或产生延迟感。

它和pw_stream_disconnect也不同。disconnect是断开Stream连接，flush是保持Stream对象存在的情况下处理数据队列。工程上，flush常用于“继续复用Stream”的场景，而不是彻底释放资源。

🌻2.应用场景与用法

pw_stream_flush

是PipeWireStream API中用于清理或排空Stream内部队列数据的接口。

它位于PipeWire客户端Stream控制路径中，通常和播放暂停、停止、切歌、Seek、设备切换、低延迟恢复等动作配合使用。应用在Stream仍然有效的情况下调用该接口，让PipeWire处理已经排队的数据和转换器中的残留数据。

pw_stream_flush用于清理Stream队列，或在drain模式下等待已提交数据完成后通知应用。

函数原型

intpw_stream_flush(structpw_stream*stream,bool drain);

参数说明

structpw_stream*stream;

stream表示需要Flush的PipeWireStream对象。

该对象必须已经创建，并且处于可操作状态。它可以是播放流，也可以是采集流。对于播放流，flush主要影响已经提交到PipeWire侧但尚未完全播放的数据；对于采集流，flush主要影响已经排队但应用尚未处理的数据。

bool drain;

drain用于决定Flush语义。

当drain为false时，表示立即清理队列和转换器中的残留数据。这个模式更适合暂停后清理、Seek后丢弃旧数据、切歌时快速移除旧音频。

当drain为true时，表示进入Drain流程。PipeWire会等待已经提交的数据完成播放或采集，完成后通过Stream事件中的drained回调通知应用。这个模式更适合“停止前完整播放剩余数据”的场景。

返回值

成功时返回0。

失败时返回负数错误码。

工程上应根据返回值判断Flush请求是否成功提交。返回成功不代表所有数据已经立刻播放完成。特别是drain=true时，真正完成点应以后续drained回调为准。

应用场景

第一类场景是播放器切歌。

上一首歌曲可能已经向PipeWire提交了一部分PCM数据。如果不Flush，切到下一首时可能先听到一小段旧数据。此时通常使用drain=false，快速丢弃旧队列。

第二类场景是Seek跳转。

用户从歌曲30秒跳到2分钟位置时，旧位置的数据已经没有意义。此时应暂停或停止数据提交，然后调用pw_stream_flush(stream,false)清除旧数据，再从新位置继续填充Buffer。

第三类场景是停止播放前完整播完尾部数据。

如果应用已经提交最后一批音频，希望声卡实际播放完再关闭流，可以使用drain=true。drained回调到达后，再执行停止、断开或状态切换。

第四类场景是设备切换。

当默认Sink变化、蓝牙耳机切换、有线耳机插拔、车载音频Zone变化时，旧链路中可能还有排队数据。Flush可以减少切换后的残留声、延迟和状态混乱。

第五类场景是低延迟链路恢复。

实时音频处理中，如果发生暂停、XRUN、重配参数或数据源跳变，继续使用旧队列可能造成明显延迟。此时可以通过Flush重新压低链路缓存，让后续数据从新的时间点开始。

🌻3.调用流程剖析

🌻3.1核心步骤

1.应用创建pw_stream对象，并完成事件回调注册。

2.应用连接Stream，完成格式协商、参数协商和Buffer协商。

3.Stream进入运行状态后，应用通过process回调持续dequeue和queueBuffer。

4.业务侧发生状态变化，例如暂停、停止、切歌、Seek或设备切换。

5.应用停止继续提交新的旧数据，避免Flush过程中又产生新的队列残留。

6.应用调用pw_stream_flush(stream,drain)。

7.如果drain=false，PipeWire清理Stream队列和转换器中的残留数据。

8.如果drain=true，PipeWire等待已提交数据完成播放或采集。

9.Drain完成后，PipeWire通过drained事件通知应用。

10.应用根据业务状态决定重新激活Stream、继续填充新数据、断开Stream或销毁Stream。

🌻3.2调用流程图

🌻3.3生命周期图

🌻4.实战应用案例

下面以播放器“暂停、切歌、停止前Drain”三个动作说明pw_stream_flush的工程用法。

播放器通常有三类不同的队列处理需求：

暂停时，希望停止继续播放，并清掉残留数据。

切歌时，希望丢弃旧歌曲队列，避免旧音频串到新歌曲。

停止前，如果希望最后一段已经提交的数据完整播放完，可以Drain后再关闭。

#include<pipewire/pipewire.h>structplayer{structpw_stream*stream;bool draining;bool stopped;};staticvoidon_stream_drained(void*userdata){structplayer*p=userdata;p->draining=false;p->stopped=true;pw_stream_set_active(p->stream,false);}staticvoidon_stream_process(void*userdata){structplayer*p=userdata;structpw_buffer*b;structspa_buffer*buf;structspa_data*data;if(p->stopped||p->draining)return;b=pw_stream_dequeue_buffer(p->stream);if(b==NULL)return;buf=b->buffer;data=&buf->datas[0];if(data->data==NULL||data->chunk==NULL){pw_stream_queue_buffer(p->stream,b);return;}/* * 播放器在这里向data->data填充PCM数据。 * 数据可能来自解码器、环形缓冲区或音频处理模块。 */data->chunk->offset=0;data->chunk->size=0;data->chunk->stride=0;pw_stream_queue_buffer(p->stream,b);}staticconststructpw_stream_eventsstream_events={PW_VERSION_STREAM_EVENTS,.process=on_stream_process,.drained=on_stream_drained,};

暂停场景通常不需要等待旧数据播完，而是希望尽快停止并清理残留队列。

staticintplayer_pause(structplayer*p){intret;pw_stream_set_active(p->stream,false);ret=pw_stream_flush(p->stream,false);if(ret<0)returnret;p->stopped=true;return0;}

这里的关键点是：暂停不是销毁Stream，而是让Stream暂时退出活跃处理状态。随后使用drain=false快速清理队列，避免恢复播放时继续处理旧数据。

切歌场景和暂停类似，但切歌后通常还会继续复用同一个Stream。

staticintplayer_switch_track(structplayer*p){intret;pw_stream_set_active(p->stream,false);ret=pw_stream_flush(p->stream,false);if(ret<0)returnret;/* * 这里重置解码器、环形缓冲区、播放位置和业务状态。 * 后续process回调会从新歌曲重新填充数据。 */p->stopped=false;pw_stream_set_active(p->stream,true);return0;}

这个流程适合播放器Seek、切歌、重新打开音频源等场景。核心目标是让旧数据彻底退出Stream队列，新数据从新的业务时间点开始进入PipeWire图。

停止前Drain适合另一类场景：应用已经提交了最后一批数据，希望PipeWire实际处理完成后再停掉Stream。

staticintplayer_stop_after_drain(structplayer*p){intret;p->draining=true;ret=pw_stream_flush(p->stream,true);if(ret<0){p->draining=false;returnret;}return0;}

这里调用pw_stream_flush(p->stream,true)后，不应立即认为播放已经完成。Drain的完成点在drained回调中。drained回调触发后，再停止Stream、释放业务资源或切换状态，语义更清晰。

工程上使用pw_stream_flush要注意四个边界。

第一，drain=false偏向“丢弃残留数据”，适合快速恢复、切歌和Seek。

第二，drain=true偏向“等待数据完成”，适合优雅停止和尾部播放完整性要求高的场景。

第三，Flush不是线程模型修复工具。如果process回调阻塞、Buffer不归还、数据源锁等待，flush只能处理队列状态，不能替代实时线程设计。

第四，Flush不等于Disconnect。仍然要复用Stream时优先考虑Flush；不再使用Stream时再进入disconnect或destroy流程。

🌻5.一句话总结

pw_stream_flush是PipeWireStream级别的队列清理接口：drain=false用于快速丢弃残留数据，drain=true用于等待已提交数据完成并触发drained回调，适合暂停、切歌、Seek、停止播放和设备切换等工程场景。