mediasoup-client 接收媒体流全攻略：Consumer 使用详解与常见误区

mediasoup-client 接收媒体流全攻略：Consumer 使用详解与常见误区

【免费下载链接】mediasoup-clientmediasoup client side JavaScript library项目地址: https://gitcode.com/gh_mirrors/me/mediasoup-client

mediasoup-client 是 mediasoup SFU 的官方浏览器端 JavaScript 库，而Consumer正是它接收媒体流的核心对象。无论你是刚接触 WebRTC 的新手，还是正在排查收不到画面问题的开发者，理解 Consumer 的创建流程、属性方法和生命周期，都是用好 mediasoup-client 接收音频视频流的关键一步。本文将用最通俗的方式，带你完整掌握 Consumer 使用技巧，并避开新手最常见的几个坑。

一、Consumer 到底是什么？

简单说，Consumer 是服务端某个 Producer（推流端）在本地的“接收端化身”。服务端有用户 A 在推摄像头视频，客户端 B 想看他，B 就要通过 mediasoup-client 创建一个 Consumer，拿到 A 的视频轨道（track）并渲染到页面上。

Consumer 的完整定义位于 src/Consumer.ts，它内部封装了一个MediaStreamTrack（即consumer.track），并附带 RTP 参数、暂停状态等元信息。请注意：Consumer 不能被new出来，它只能通过接收传输（RecvTransport）的consume()方法创建，见 src/Transport.ts。

二、创建 Consumer 的完整流程（信号交互是关键）

第一步：加载 Device

先创建Device并用服务端返回的routerRtpCapabilities调用device.load()。这一步没做，后续所有操作都会报InvalidStateError。

第二步：创建接收传输

通过device.createRecvTransport()创建接收方向的传输对象（方向为recv），实现位于 src/Device.ts。这里需要服务端通过信令下发的iceParameters、iceCandidates、dtlsParameters。

第三步：先信令，后 consume

这是 mediasoup v3 的典型交互模式，顺序千万不能反：

1. 客户端通过信令告诉服务端“我要看某一路流”；
2. 服务端创建好 Consumer 并返回id、producerId、kind、rtpParameters；
3. 客户端拿着这些参数调用recvTransport.consume({ id, producerId, kind, rtpParameters })；
4. consume()内部会自动触发 transport 的connect事件，此时你要像发送端一样，把本地dtlsParameters通过信令回传给服务端完成 DTLS 握手。

💡 提示：consume()返回的是 Promise，一定用await拿到最终的Consumer实例。

三、Consumer 关键属性和方法速查

拿到 Consumer 后，你最常用到的成员有这些：

成员	类型	作用
consumer.track	MediaStreamTrack	远程媒体轨道，可直接塞进<video>或<audio>
consumer.id	string	Consumer 唯一标识
consumer.producerId	string	对应的服务端 Producer id
consumer.kind	'audio' / 'video'	媒体类型
consumer.paused	boolean	是否处于暂停状态
consumer.pause()	方法	暂停接收（会把track.enabled置为 false）
consumer.resume()	方法	恢复接收
consumer.getStats()	方法（异步）	获取 RTC 统计信息，排查卡顿利器
consumer.close()	方法	主动关闭并停止轨道

暂停/恢复的实现非常直观，就是控制track.enabled的开关，代码见 src/Consumer.ts。

四、将媒体流渲染到页面上

拿到consumer.track后，把它挂到媒体元素上即可：

• 视频流：video.srcObject = new MediaStream([consumer.track])；
• 音频流：同理挂到audio元素；
• 多人会议：每个远端用户对应一个 Consumer，各自维护自己的 video 元素。

建议在渲染前判断consumer.kind，音频和视频分别处理，避免把音频轨道塞进视频标签。

五、必学的生命周期事件

Consumer 继承自事件发射器，有两个公开事件必须处理：

• trackended：远端轨道结束（如对方关闭了摄像头），此时应移除对应 UI 元素；
• transportclose：底层传输被关闭，所有 Consumer 随之失效。

此外通过consumer.observer还能监听到pause、resume、close等更细粒度的事件（观察者模式），适合做“静音/暂停”状态角标之类的 UI 联动。

⚠️ 注意：trackended触发后轨道可能已停止，若想再次接收，需要重新走一遍信令 + consume 的流程。

六、新手最常见的 5 个误区

1. 忘加载 Device 就直接建传输：所有操作前必须先device.load()，否则抛InvalidStateError。
2. 用发送传输去 consume：sendTransport.consume()会直接报UnsupportedError，接收媒体流必须用createRecvTransport()创建的 recv 方向传输。
3. 跳过信令、伪造 rtpParameters：rtpParameters必须来自服务端真实返回，consume()内部会用ortc.canReceive()校验，参数不合法会抛UnsupportedError。
4. 不监听transportclose：对端断线或服务端关闭时，Consumer 会静默失效，不监听事件就会出现“画面消失但 UI 没反应”的诡异 Bug。
5. 把pause()当销毁用：pause()只是停流，连接仍在；想要彻底释放资源要用close()（它会自动track.stop()）。

七、小结

掌握mediasoup-client Consumer 使用并不难：记住“先信令后 consume”的时序，管理好track和生命周期事件，就足以支撑绝大多数一对一通话与多人会议场景。如果排查问题需要更深入的数据，getStats()和rtpParameters会是你最好的帮手。希望这份接收媒体流全攻略能帮你少走弯路，快速跑通第一个能“看到人”的 Demo 🚀

【免费下载链接】mediasoup-clientmediasoup client side JavaScript library项目地址: https://gitcode.com/gh_mirrors/me/mediasoup-client