mediasoup v3 API 学习之一

mediasoup 模块的一些属性

mediasoup.types

mediasoup 模块对外 export 出来的所有的 class + TypeScript 语法定义的类型。

var ms = require('mediasoup');
console.log(ms.types);

结果如下：

{
  Worker: [Function: Worker],
  Router: [Function: Router],
  Transport: [Function: Transport],
  WebRtcTransport: [Function: WebRtcTransport],    
  PlainTransport: [Function: PlainTransport],      
  PlainRtpTransport: [Function: PlainRtpTransport],
  PipeTransport: [Function: PipeTransport],        
  DirectTransport: [Function: DirectTransport],
  Producer: [Function: Producer],
  Consumer: [Function: Consumer],
  DataProducer: [Function: DataProducer],
  DataConsumer: [Function: DataConsumer],
  RtpObserver: [Function: RtpObserver],
  AudioLevelObserver: [Function: AudioLevelObserver],
  UnsupportedError: [Function: UnsupportedError],
  InvalidStateError: [Function: InvalidStateError]
}

mediasoup.version

console.log(ms.version);

结果： 3.6.8
最后一位小版本不是很准确，可能未能及时更新。npm install 成功结束时显示 为 3.6.9 。

mediasoup.observer

这是一个 nodejs 中的 event emitter 类型的数据结构。
该 observer 可以监听 mediasoup 的 worker 实例被创建的事件。即 newworker 事件。

ms.observer.on('newworker', (worker) =>
{
    console.log("new worker created, pid is: " + worker.pid);
});

mediasoup 模块的 OPS / 行为 / 操作 / Functions 接口！

创建 worker

var settings = {
    logLevel    : "error",  // 默认 error
    logTags     : [],       // 是个数组，可以多个合并，默认为空
    rtcMinPort  : 10000,    // 默认 10000
    rtcMaxPort  : 59999,    // 默认 59999
    dtlsCertificateFile : "",   // dtls 加密的 cert
    dtlsPrivateKeyFile  : "",   // dtls 加密的 key
    appData     : {}        // 默认 {} 用户可以使用该字段，
                            // 传参 worker 中。即 worker 的 appData 字段。
};
var worker = await mediasoup.createWorker(settings);

logTags 取值主要如下

Value	Description
“info”	用到的软件以及库的一些版本，配置，以及进程信息
“ice”	ICE 相关日志
“dtls”	DTLS 相关日志
“rtp”	RTP
“srtp”	SRTP 加解密的日志
“rtcp”	RTCP
“rtx”	RTP 重传的相关信息, 包括 NACK/PLI/FIR.
“bwe”	网络带宽质量相关信息
“score”	Producers & Consumers 的得分log
“simulcast”	视频 simulcast log
“svc”	视频 SVC log
“sctp”	SCTP (DataChannel) log
“message”	message 日志

说明：

• 在创建 worker 时，指定了一些信息，其实业务上有实际作用的是端口范围参数，这是需要开启防火墙的。
• 在创建 worker 时，并未制定监听的具体端口，也未制定监听的 IP 地址。这些参数，并不是 worker 层面需要做的事情，而是在下一层，即每一个 transport 各自设置各自的 IP 以及 具体端口。
• settings 中指定的 worker 配置，有两个字段是可以动态更新的。即：
  • logLevel
  • logTags

获取 mediasoup 的 rtp 能力

即 mediasoup 内部支持的音视频编解码的方式
mediasoup.getSupportedRtpCapabilities()

• 当前 mediasoup 支持的编解码的在如下文件中给出；
  mediasoup/src/supportedRtpCapabilities.ts
• 该接口返回一个 RtpCapabilities 的对象
  该对象主要包含两个域：
  codecs 域: 支持的 音视频 codec 数组。
  • 对于音频，支持 8K PCMA/PCMU 编码，48K 双声道 opus 编码等等。
  • 对于视频，支持 H264, H265, VP8, VP9 格式的编码等等。
    headerExtensions 域： rtp 协议头的扩展数组。
• 可以用以下代码，查看：

const rtpCapabilities = mediasoup.getSupportedRtpCapabilities();
console.log(rtpCapabilities);

这个能力，是 mediasoup server 端支持的能力，并不需要 client 端也支持。 client 端只需要支持其中之一，即可。

webrtc-svc 模式 字符串解析

mediasoup.parseScalabilityMode(scalabilityMode)
参数 传入一个符合 webrtc-svc 规范的 模式字符串
返回 ScalabilityMode 对象

Worker

Worker 代表一个在单个 CPU 中运行并处理 Router 实例的 mediasoup C++ 语言实现可执行实例。作为 server 的子进程运行。
主要作用就是管理多个 Router 实例。
所以， 可以称 Worker 为 mediasoup 的工作进程。

相关设置参数，略，参见前文 " 创建 worker 的 settings "

Worker 的属性

见文知意，如下：
worker.pid
worker.closed
worker.appData
worker.observer
单独说一下 woker observer 的事件

worker.observer.on("close", function(){})
worker.observer.on("newrouter", function(router){})
// worker 但不是 observer 的事件，这是个 woker 进程异常退出事件
// 比如 pkill -9 mediasoup-worker
worker.on('died', function(error){})

• close 当 worker 被 close 了，就会触发该事件，无论是何种原因，何处 worker 被close，都会触发该事件。
• newrouter Woker 作为多个 router 实例的管理者，每当 worker 中创建一个 router，就会触发一次 newrouter 事件，并且，将创建成功的 router 作为入参传入。

Worker 的相关操作

1. worker.close(); // 该接口会触发一个: “workerclose” 给到所有的当前 worker 管理的 router。
2. worker.getResourceUsage()
3. worker.updateSettings(settings) // 前文已述，即更新 logLevel 以及 LogTag 域。

创建 Router

Worker 作为工作进程工作在 mediasoup server中，其主要作用，就是创建 router。
worker.createRouter(options)
参数 options: RouterOptions 类型
codecs 域: 即 RTP Captacity 中 codecs 域，可以选择一种或者多种。
appdata 域
返回一个 Router.

const mediaCodecs =
[
  {
    kind        : "audio",
    mimeType    : "audio/opus",
    clockRate   : 48000,
    channels    : 2
  },
  {
    kind       : "video",
    mimeType   : "video/H264",
    clockRate  : 90000,
    parameters :
    {
      "packetization-mode"      : 1,
      "profile-level-id"        : "42e01f",
      "level-asymmetry-allowed" : 1
    }
  }
];
const router = await worker.createRouter({ mediaCodecs });

Router

作用：通过内部的 Transport 实例去实现媒体流的 injection, selection, forwarding。

• RouterOptions
• PipeToRouterOptions
• PipeToRouterResult

属性

router. id
router. closed
router. rtpCapabilities
router. appData
router. observer

行为

• router.close()
  • 触发 routerclose 通知其下管理的 transports
  • 触发 routerclose 通知其 observers

创建 Transport

• router.createWebRtcTransport(options)
  • options: WebRtcTransportOptions
• router.createPlainRtpTransport(options) (DEPRECATED)
  • router.createPlainTransport(options) since medisoup version 3.5.0.
  • options: PlainTransportOptions
• router.createPipeTransport(options)
  • options: PipeTransportOptions
• router.createDirectTransport(options)
  • options: DirectTransportOptions

创建其他

• router.pipeToRouter({ producerId, dataProducerId, router, listenIp })
  • 将给定的媒体或数据生产者通过管道传送到同一主机中的另一个 Router。它创建了一个基础的 PipeTransport（如果以前未创建），它将同一个主机中的两个 Router 互连。
  • 通过互连运行在不同 Worker 中的不同 Router ，这对于扩展广播功能（一对多）特别有用。
• router.createAudioLevelObserver(options)
  • options: AudioLevelObserverOptions
• router.canConsume({ producerId, rtpCapabilities })
  • 给定的 producerId 代表的 producer 指定的 rtpCapabilities，能否被该 router 顺利消费（能否被该 router 识别，处理）。

事件

• router.on(‘workerclose’, function(){})
• router.observer.on(‘close’, function(){})
• router.observer.on(‘newtransport’, function(transport){})
• router.observer.on(‘newrtpobserver’, function(rtpObserver){})

Transport

Transport 的作用就是实现并管理 mediasoup server 中的 router 与各类终端的连接。
通过在 Transport 内部创建的 Producer & Consumer 实现媒体数据的双向传输。
Tansport 本身在 mediasoup 内部是一个抽象类，mediasoup 基于 Transport 主要实现了以下4种具体类型：

• WebRtcTransport
• PlainTransport
• PipeTransport
• DirectTransport

数据类型介绍（准备）

• TransportListenIp

  • ip 域：string 类型的 IpV4 或者 IpV6 格式字符串，必须要有，不可缺少。
  • announcedIp 域：string 类型的 IpV4 或者 IpV6 格式字符串，NAT 穿透时需要。

• TransportTuple

  • localIp: 本端 IP
  • localPort: 本端 port
  • remoteIp: 对端 IP
  • remotePort: 对端 port
  • protocol: 通信协议： “tcp” / “udp”
    removeIp 以及 remotePort 是非必须的。可能当前并不知道对端的地址及端口，所以后续根据不同的 transport 类型，有不同的处理方式。

• TransportTraceEventData

  • type
  • timestamp
  • direction
  • info

• enum

  • TransportTraceEventType
    • “probation”
    • “bwe”
  • TransportSctpState
    • new
    • connecting
    • connected
    • failed
    • closed

Transport 的属性

transport. id
transport.closed
transport.appData
transport.observer

Transport 的行为

• transport.close()
• transport.getStats()
  • For more: RTC Statistics
• transport.connect()
• transport.setMaxIncomingBitrate(bitrate)
• transport.produce(options)
• transport.consume(options)
• transport.produceData(options)
• transport.consumeData(options)

To be continued…

Mediasoup on windows

环境 Windows 10

版本 node: 12.18.2 npm: 6.14.5

编译环境必须:

• visual studio >= 2015, 本机 2019
• python 2: python 2.7.16 （本机 64bit）

配置：

系统环境变量:

1. PATH 中添加 vs 的 MSBuild bin (MSBuild.exe) 目录(没有在C盘，在D盘)，(本机 64bit)
2. 系统环境变量
   名： GYP_MSVS_VERSION
   值： 2019
3. 系统环境变量
   PATH 中添加 python.exe 所在的目录 以及 python/scripts 目录。

Start

1. 找个地方新建文件夹,名为: csrtc
2. 进入该文件夹，创建一个空的文件: server.js 作为入口文件
3. 打开 cmd 进入 csrtc 文件夹。
4. 验证一下：
   npm -v
   node -v
   python --version
   MSBuild -version
   如果都没问题，都能显示版本，那么继续往下走。
5. npm init
6. npm install mediasoup@3 --save
7. 等待完成之后，进入 node_modules/mediasoup/worker 目录
   看到下面有个 mediasoup-worker.sln
   用 vs2019 打开即可。
   8.说明：
   用 GYP 生成的跨平台的项目，工程项目中的代码，不仅仅包含文件，而且文件夹都有对应的筛选器，这一点，比很多开源项目做得都更好。