mediasoup-client API 参考速查手册：Device、Transport、Producer、Consumer 一文掌握

mediasoup-client API 参考速查手册Device、Transport、Producer、Consumer 一文掌握【免费下载链接】mediasoup-clientmediasoup client side JavaScript library项目地址: https://gitcode.com/gh_mirrors/me/mediasoup-client想要快速上手 WebRTC SFU 架构的实时音视频应用这份mediasoup-client API 参考速查手册就是为你准备的。mediasoup-client 是 mediasoup 官方出品的 TypeScript 客户端库负责在浏览器端连接 mediasoup 服务器完成音视频推流、拉流和数据通道通信。本文将从Device、Transport、Producer、Consumer四大核心类出发用最精炼的方式带你一文掌握全部常用 API无论是新手入门还是日常开发查漏补缺这份速查手册都能帮你节省大量翻文档的时间。一、上手前的准备工作安装与基础概念安装 mediasoup-client 的快速方法在项目里执行一行命令即可完成安装npm install mediasoup-client安装后从包中引入核心类import { Device, detectDevice } from mediasoup-client;理解四大核心对象的分工在动手写代码前先搞清这几个对象各自的职责整个 mediasoup-client API 都围绕它们运转对象职责一句话概括Device设备与 RTP 能力管理连接服务器前的入口负责加载 Router 能力Transport媒体传输通道分发送send与接收recv两种方向Producer推流端把本地音视频轨发送给服务器Consumer拉流端从服务器接收远端音视频轨 模块路径提示四大核心类分别定义在src/Device.ts、src/Transport.ts、src/Producer.ts、src/Consumer.ts入口统一由src/index.ts导出。二、Device一切从设备创建开始创建并加载 Device 的标准流程Device 是所有操作的起点。创建后必须调用load()加载服务器 Router 的 RTP 能力之后才能创建 Transportconst device new Device(); // 从信令服务器获取 Router RTP capabilities const routerRtpCapabilities await signaling.request(getRouterCapabilities); // 加载能力每个 Device 只能 load 一次 await device.load({ routerRtpCapabilities }); // 检查当前设备是否支持推流 if (!device.canProduce(video)) { console.warn(当前浏览器不支持视频推流); }Device 常用属性与事件速查device.loaded是否已完成加载未加载前调用大部分方法都会抛出InvalidStateError。device.rtpCapabilities本机接收媒体的 RTP 能力是创建 Transport 时的必备参数。device.sctpCapabilitiesSCTP数据通道能力需要传数据时需要用到。device.handlerName当前自动检测到的浏览器处理程序名称如Chrome111、Firefox120、Safari12。device.observer可监听newtransport事件实时感知新 Transport 的创建。 浏览器兼容性检测由detectDevice()/detectDeviceAsync()完成实现逻辑详见src/Device.ts中的detectDeviceImpl函数支持 Chrome、Firefox、Safari 以及 React Native 环境。三、Transport搭建推拉流的双向通道创建发送与接收 Transport 的方法Device 加载完成后需要结合信令服务器返回的参数创建 Transport。发送推流和接收拉流必须分开创建// 创建发送 Transport推流用 const sendTransport device.createSendTransport({ id, iceParameters, iceCandidates, dtlsParameters, sctpParameters, }); // 创建接收 Transport拉流用 const recvTransport device.createRecvTransport({ id, iceParameters, iceCandidates, dtlsParameters, sctpParameters, });⚠️重要提醒这两个方法所需的id、iceParameters、iceCandidates、dtlsParameters全部来自服务器端创建 Transport 后的返回值需要通过你的信令机制如 WebSocket获取。Transport 三大必知事件发送 Transport 在使用前必须先注册以下几个关键事件的监听否则调用produce()会直接报错connect事件DTLS 连接建立时触发需把本地dtlsParameters通过信令发给服务器。produce事件推流时触发需把kind和rtpParameters发给服务器换取 Producer 的id。producedata事件发送数据通道时触发需把sctpStreamParameters发给服务器。 事件类型定义详见src/Transport.ts中的TransportEvents每个事件的回调签名都经过强类型约束配合 TypeScript 使用体验极佳。Transport 其他实用方法方法用途transport.close()关闭 Transport会连带关闭其下所有 Producer / Consumertransport.restartIce()ICE 重启网络切换时使用transport.getStats()获取 RTCPeerConnection 统计信息transport.updateIceServers()动态更新 ICE 服务器列表四、Producer把本地媒体推给服务器推流的核心调用方式Producer 代表一个本地推流单元通过发送 Transport 的produce()方法创建参数是浏览器采集到的MediaStreamTrack// 采集摄像头画面 const stream await navigator.mediaDevices.getUserMedia({ video: true }); const videoTrack stream.getVideoTracks()[0]; // 推流会触发上面注册的 produce 事件与信令服务器交互 const producer await sendTransport.produce({ track: videoTrack }); // 推流成功Producer 已建立 console.log(Producer id:, producer.id);Producer 常用方法暂停、恢复与换轨producer.pause()/producer.resume()暂停/恢复推流默认会同步禁用/启用本地 track。producer.replaceTrack({ track })动态更换推流轨道切换摄像头时非常好用。producer.setMaxSpatialLayer(layer)设置视频最大空间层配合 Simulcast 使用。producer.getStats()获取发送端统计信息。Producer 事件一览trackended本地轨道结束如摄像头被拔出。transportclose所属 Transport 被关闭。closeProducer 被关闭。 Producer 的完整选项如encodings、codecOptions、stopTracks等定义在src/Producer.ts的ProducerOptions中支持 Simulcast、Opus 参数调节等高级能力。五、Consumer接收并播放远端媒体拉流的标准调用方式Consumer 代表一个远端拉流单元通过接收 Transport 的consume()方法创建。参数同样来自服务器服务器在用户加入房间后会通过信令通知你可以消费某个 Producer 了并返回id、producerId、kind、rtpParameters等数据// 服务器通知可以消费远端视频 const consumer await recvTransport.consume({ id, // 服务器返回的 Consumer id producerId, // 对应的 Producer id kind: video, rtpParameters, // 服务器返回的 RTP 参数 }); // 把接收到的轨道挂到 video 元素上播放 const videoEl document.getElementById(remote-video); videoEl.srcObject new MediaStream([consumer.track]); await videoEl.play();Consumer 实用方法与事件Consumer 与 Producer 的 API 高度对称上手成本极低consumer.pause()/consumer.resume()暂停/恢复播放远端画面。consumer.getStats()获取接收端统计信息用于监控卡顿、丢包。consumer.track远端媒体轨道可直接挂载到MediaStream播放。事件包括trackended、transportclose、close语义与 Producer 一致。consume()在调用前会通过 ORTC 能力检查确认当前设备能否解码该流若无法消费会抛出UnsupportedError相关逻辑在src/Transport.ts的consume()中通过ortc.canReceive()实现。六、数据通道DataProducer 与 DataConsumer 补充除了音视频mediasoup-client 还支持基于 SCTP 的数据通道相当于 WebRTC DataChannel适合传输聊天消息、文件等数据// 发送数据 const dataProducer await sendTransport.produceData({ ordered: true, label: chat, }); dataProducer.send(hello mediasoup!); // 接收数据 const dataConsumer await recvTransport.consumeData({ id, dataProducerId, sctpStreamParameters, }); dataConsumer.on(message, (data) { console.log(收到消息:, data); });两个类的 API 定义分别在src/DataProducer.ts和src/DataConsumer.ts常用属性包括readyState、label、bufferedAmount等。七、常见问题与避坑指南常见报错与解决方案UnsupportedError: device not supported当前浏览器版本过旧升级浏览器或显式指定handlerName。InvalidStateError: not loaded忘了调用device.load()或调用顺序有误。no produce listener set使用produce()前未注册produce事件监听。cannot consume this Producer设备不支持该编码格式检查rtpParameters与设备能力是否匹配。新手最容易踩的三个坑Device 只能 load 一次重复调用会抛出InvalidStateError: already loaded。Transport 有方向限制produce()只能在发送 Transport 上调用consume()只能在接收 Transport 上调用。事件回调必须配合信令connect、produce等事件里的回调callback/errback必须在你完成服务器交互后显式调用否则流程会卡死。八、总结与学习资源至此你已经掌握了 mediasoup-client 的完整 API 脉络Device 负责初始化、Transport 负责建通道、Producer 负责推流、Consumer 负责拉流、DataProducer/DataConsumer 负责数据通道。整套 API 设计风格统一、类型完备掌握这几个核心类之后无论是开发视频会议、直播连麦还是在线教育应用都能游刃有余。如果需要查看完整源码与类型定义可以克隆 mediasoup-client 仓库深入学习git clone https://gitcode.com/gh_mirrors/me/mediasoup-client建议按src/Device.ts→src/Transport.ts→src/Producer.ts→src/Consumer.ts的顺序阅读源码结合本文的 API 速查手册相信你很快就能成为 mediasoup-client 的熟练使用者。祝编码愉快【免费下载链接】mediasoup-clientmediasoup client side JavaScript library项目地址: https://gitcode.com/gh_mirrors/me/mediasoup-client创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考