简介CSDN博客专家、《Android系统多媒体进阶实战》作者博主新书推荐《Android系统多媒体进阶实战》Android Audio工程师专栏地址Audio工程师进阶系列【原创干货持续更新中……】Android多媒体专栏地址多媒体系统工程师系列【原创干货持续更新中……】专题一 二AAOS车载系统AOSP14系统攻城狮入门视频实战课专题三Android14 Binder之HIDL与AIDL通信实战课专题四Android15快速自定义与集成音效实战课专题五Android15音频策略实战课专题六Android15音频性能实战课(无声/杂音/断音/爆音实战案例)人生格言人生从来没有捷径只有行动才是治疗恐惧和懒惰的唯一良药.更多原创,欢迎关注Android系统攻城狮文章目录1.前言要点概括2.应用场景与用法函数原型参数说明返回值应用场景3.调用流程剖析3.1核心步骤3.2调用流程图3.3生命周期图4.实战应用案例5.一句话总结1.前言本篇目的Linux PipeWire深度解析之pw_stream_events调用流程与实战。要点概括核心功能描述PipeWireStream生命周期中的事件回调入口。工作机制应用把一组回调函数注册到StreamPipeWire在状态变化、参数变化、Buffer创建、Graph调度和销毁阶段主动回调应用。典型用途监听Stream状态、处理Buffer、响应格式变化、接收process调度、清理Stream资源。pw_stream_events本质上不是普通函数而是PipeWireStream API中的事件回调表。它不直接执行媒体处理也不直接读写音频数据而是告诉PipeWireStream在不同阶段发生事件时应该调用应用侧的哪个函数。它和pw_stream_dequeue_buffer、pw_stream_queue_buffer不同。pw_stream_events解决“什么时候通知应用”的问题pw_stream_dequeue_buffer解决“从哪里取Buffer”的问题pw_stream_queue_buffer解决“处理完成后如何归还Buffer”的问题。它和pw_stream_add_listener关系更近。pw_stream_events描述事件表内容pw_stream_add_listener负责把事件表绑定到指定Stream。使用pw_stream_new_simple时也可以直接传入pw_stream_events由创建接口内部完成事件绑定。2.应用场景与用法pw_stream_events是PipeWireStream API中用于描述Stream事件回调集合的接口结构。它位于PipeWire客户端侧Stream控制路径和数据路径之间。应用创建Stream后需要通过pw_stream_events接收Stream生命周期事件。状态变化、格式参数变化、Buffer创建、process调度、Drain完成和Stream销毁都会通过这组回调通知应用。pw_stream_events用于注册Stream生命周期事件和媒体处理事件回调。函数原型pw_stream_events不是C函数而是C结构体。它的真实接口原型如下#definePW_VERSION_STREAM_EVENTS2structpw_stream_events{uint32_tversion;void(*destroy)(void*data);void(*state_changed)(void*data,enumpw_stream_stateold,enumpw_stream_statestate,constchar*error);void(*control_info)(void*data,uint32_tid,conststructpw_stream_control*control);void(*io_changed)(void*data,uint32_tid,void*area,uint32_tsize);void(*param_changed)(void*data,uint32_tid,conststructspa_pod*param);void(*add_buffer)(void*data,structpw_buffer*buffer);void(*remove_buffer)(void*data,structpw_buffer*buffer);void(*process)(void*data);void(*drained)(void*data);void(*command)(void*data,conststructspa_command*command);void(*trigger_done)(void*data);};实际使用时通常写成staticconststructpw_stream_eventsstream_events{.versionPW_VERSION_STREAM_EVENTS,.state_changedon_state_changed,.param_changedon_param_changed,.add_bufferon_add_buffer,.remove_bufferon_remove_buffer,.processon_process,.destroyon_destroy,};参数说明uint32_tversion;表示事件结构体版本。应用应设置为PW_VERSION_STREAM_EVENTS用于保证应用侧事件表和当前PipeWire库版本匹配。void(*destroy)(void*data);Stream销毁时触发。应用可以在这里清理和Stream绑定的业务资源但不能继续把旧Stream当作有效对象使用。void(*state_changed)(void*data,enumpw_stream_stateold,enumpw_stream_statestate,constchar*error);Stream状态变化时触发。old表示旧状态state表示新状态error用于描述错误状态下的原因。常见状态包括UNCONNECTED、CONNECTING、PAUSED、STREAMING和ERROR。工程调试中这个回调非常关键可以判断Stream是否成功连接、是否进入运行态、是否发生错误。void(*control_info)(void*data,uint32_tid,conststructpw_stream_control*control);控制信息变化时触发。它用于通知Stream控制项相关信息例如音量、静音或其他控制数据具体取决于Stream暴露的控制能力。void(*io_changed)(void*data,uint32_tid,void*area,uint32_tsize);Stream IO区域变化时触发。area表示IO区域地址size表示区域大小。它用于通知应用某类IO数据区发生变化。void(*param_changed)(void*data,uint32_tid,conststructspa_pod*param);Stream参数变化时触发。id表示参数类型param表示参数内容。音频格式、视频格式、枚举能力和运行参数变化时应用可以在这里读取新的参数信息。void(*add_buffer)(void*data,structpw_buffer*buffer);Stream创建新Buffer时触发。应用可以在这里为Buffer绑定私有数据或者记录Buffer对应的内存信息。void(*remove_buffer)(void*data,structpw_buffer*buffer);Stream销毁Buffer时触发。应用应在这里清理add_buffer阶段绑定到Buffer上的私有资源。void(*process)(void*data);媒体处理回调。PipeWire图调度到该Stream时触发。播放流通常在这里取Buffer、填充数据、queue回Stream采集流通常在这里取Buffer、读取数据、queue回Stream。void(*drained)(void*data);Stream排空完成时触发。播放场景中当应用请求Drain后所有已提交数据处理完成会通过该回调通知应用。void(*command)(void*data,conststructspa_command*command);Stream收到命令通知时触发。它用于接收底层SPA命令类事件。void(*trigger_done)(void*data);trigger_process完成后触发。它通常和显式触发处理流程相关用于确认一次触发已经完成。返回值pw_stream_events本身不是函数没有返回值。每个回调函数也通常不返回结果而是通过回调参数把事件上下文交给应用处理。应用侧如果需要改变Stream行为应调用对应的Stream API完成例如pw_stream_connect、pw_stream_dequeue_buffer、pw_stream_queue_buffer、pw_stream_flush、pw_stream_disconnect等。应用场景第一类场景是播放流。应用注册process回调。PipeWire需要播放数据时触发process应用在回调中调用pw_stream_dequeue_buffer取出Buffer填入PCM数据再调用pw_stream_queue_buffer提交。第二类场景是录音流。应用注册process回调。PipeWire采集到数据后触发process应用取出Buffer读取PCM数据然后归还Buffer。第三类场景是监听Stream状态。应用注册state_changed回调。Stream连接失败、进入PAUSED、进入STREAMING、发生ERROR时可以在这里记录日志、更新业务状态或执行恢复动作。第四类场景是格式协商跟踪。应用注册param_changed回调。PipeWire完成格式协商或参数变化后应用可以在这里读取最终音频格式、采样率、通道数、视频尺寸等信息。第五类场景是Buffer资源绑定。应用注册add_buffer和remove_buffer。add_buffer中为Buffer创建私有上下文remove_buffer中释放这些资源避免在process回调中反复分配内存。3.调用流程剖析3.1核心步骤1.应用定义static const struct pw_stream_events事件表。2.应用设置.version为PW_VERSION_STREAM_EVENTS。3.应用根据需要填充state_changed、param_changed、add_buffer、remove_buffer、process、drained、destroy等回调。4.应用创建pw_stream对象。5.如果使用pw_stream_new_simple创建Stream时直接传入pw_stream_events。6.如果使用pw_stream_new应用需要再通过pw_stream_add_listener把pw_stream_events绑定到Stream。7.应用调用pw_stream_connect连接StreamPipeWire开始建立客户端Stream和Graph对象之间的关系。8.Stream连接过程中状态变化会触发state_changed。9.格式和参数协商过程中参数变化会触发param_changedIO区域变化会触发io_changed。10.Buffer创建完成后PipeWire触发add_buffer应用可以记录Buffer私有信息。11.Graph进入运行调度后PipeWire在合适周期触发process。12.应用在process中完成Buffer处理。播放流写Buffer采集流读Buffer。13.Buffer被销毁前PipeWire触发remove_buffer应用释放Buffer相关私有资源。14.Stream排空、显式触发或命令事件发生时触发drained、trigger_done或command。15.Stream销毁时触发destroy整个事件表生命周期结束。3.2调用流程图3.3生命周期图4.实战应用案例下面以“播放Stream事件注册和process处理”为例说明pw_stream_events在真实开发中的用法。这个案例只保留主链路定义事件表、监听状态、监听参数、处理Buffer、清理Buffer资源。#includepipewire/pipewire.h#includespa/param/audio/format-utils.hstructapp_data{structpw_main_loop*loop;structpw_stream*stream;uint32_tframe_size;};staticvoidon_state_changed(void*userdata,enumpw_stream_stateold,enumpw_stream_statestate,constchar*error){structapp_data*appuserdata;(void)app;(void)old;if(statePW_STREAM_STATE_ERROR){/* * Stream进入错误状态。 * error保存错误原因。 * 工程中通常在这里记录日志或触发重连。 */(void)error;return;}if(statePW_STREAM_STATE_PAUSED){/* * Stream已经连接格式和Buffer通常已经准备好。 */return;}if(statePW_STREAM_STATE_STREAMING){/* * Stream已经进入运行态。 * 后续process会被Graph调度触发。 */return;}}staticvoidon_param_changed(void*userdata,uint32_tid,conststructspa_pod*param){structapp_data*appuserdata;(void)app;if(paramNULL)return;if(idSPA_PARAM_Format){/* * 这里可以解析最终协商出来的音频格式。 * 例如采样率、通道数、采样格式。 */return;}}staticvoidon_add_buffer(void*userdata,structpw_buffer*buffer){structapp_data*appuserdata;(void)app;/* * Buffer创建时触发。 * 如果应用需要为每个Buffer绑定私有资源 * 可以在这里初始化。 */buffer-user_dataNULL;}staticvoidon_remove_buffer(void*userdata,structpw_buffer*buffer){structapp_data*appuserdata;(void)app;/* * Buffer销毁前触发。 * 如果add_buffer中绑定了私有资源 * 应在这里释放。 */buffer-user_dataNULL;}staticuint32_tfill_audio(void*dst,uint32_tmax_bytes){/* * 真实工程中数据可能来自解码器、环形缓冲区、 * DSP算法、网络音频流或测试音源。 */(void)dst;(void)max_bytes;return0;}staticvoidon_process(void*userdata){structapp_data*appuserdata;structpw_buffer*b;structspa_buffer*buf;structspa_data*data;uint32_tn_bytes;bpw_stream_dequeue_buffer(app-stream);if(bNULL)return;bufb-buffer;databuf-datas[0];if(data-dataNULL||data-chunkNULL){pw_stream_queue_buffer(app-stream,b);return;}n_bytesfill_audio(data-data,data-maxsize);data-chunk-offset0;data-chunk-sizen_bytes;data-chunk-strideapp-frame_size;pw_stream_queue_buffer(app-stream,b);}staticvoidon_drained(void*userdata){structapp_data*appuserdata;(void)app;/* * 已提交的数据处理完成。 * 播放器停止、切歌、释放资源时可能用到。 */}staticvoidon_destroy(void*userdata){structapp_data*appuserdata;(void)app;/* * Stream对象销毁时触发。 * 不要在这里继续访问已经失效的Stream资源。 */}staticconststructpw_stream_eventsstream_events{.versionPW_VERSION_STREAM_EVENTS,.destroyon_destroy,.state_changedon_state_changed,.param_changedon_param_changed,.add_bufferon_add_buffer,.remove_bufferon_remove_buffer,.processon_process,.drainedon_drained,};这段代码的重点不在创建完整播放器而在说明pw_stream_events如何组织Stream事件。state_changed用于观察Stream状态。它适合做连接成功、运行态进入、错误恢复这类控制逻辑。param_changed用于观察协商结果。它适合确认最终媒体格式避免应用误以为自己提交的格式一定就是最终格式。add_buffer和remove_buffer用于管理Buffer级资源。它们不适合做大量数据处理主要用于初始化和清理。process是媒体数据路径的核心回调。它应该短、快、少阻塞。实时线程场景下process中不要做文件读写、锁等待、复杂内存分配和耗时算法。destroy用于Stream生命周期结束时的收尾。它不是正常处理Buffer的地方也不是重新启动Stream的地方。如果使用pw_stream_new_simple可以在创建Stream时直接传入事件表app.streampw_stream_new_simple(pw_main_loop_get_loop(app.loop),simple-playback,props,stream_events,app);如果使用pw_stream_new则通常需要手动添加listenerstructspa_hookstream_listener;app.streampw_stream_new(core,manual-playback,props);pw_stream_add_listener(app.stream,stream_listener,stream_events,app);两种方式的核心差异是控制粒度不同。pw_stream_new_simple封装度更高适合最小客户端和快速验证。pw_stream_new配合pw_stream_add_listener控制更细适合已经持有pw_core、需要更复杂上下文管理的工程代码。5.一句话总结pw_stream_events是PipeWireStream的事件回调表它不直接传输数据而是把Stream状态变化、参数变化、Buffer创建、process调度和销毁收尾等关键节点交给应用处理。