Kurento Utils JS

概述

Kurento Utils是RTCPeerConnection的包装器对象。 此对象旨在简化基于WebRTC的应用程序的开发。

该项目的源代码可以从GitHub存储库克隆。

怎么使用它

• Minified file - 点击这儿下载.
• NPM - NodeJS 中安装使用.

npm install kurento-utils

var utils = require('kurento-utils');

• Bower - 生成的 bundled 脚本文件

bower install kurento-utils

导入库到您的html页面

<script src="bower_components/kurento-utils/js/kurento-utils.js"></script>

Examples

有几个教程展示了使用Java，Node和JavaScript开发的完整WebRTC应用程序中使用的kurento-utils。 这些教程在GitHub中，您可以随时下载和运行它们。

• Java - https://github.com/Kurento/kurento-tutorial-java

• Node - https://github.com/Kurento/kurento-tutorial-node

• JavaScript -https://github.com/Kurento/kurento-tutorial-js

在下面几行中，我们将演示如何使用库来创建RTCPeerConnection，以及如何协商与另一个对等体的连接。 库提供了一个WebRtcPeer对象，它是浏览器的RTCPeerConnection API的包装器。 对等连接可以是不同类型：单向（仅发送或接收）或双向（发送和接收）。 以下代码显示如何创建后者，以便能够发送和接收媒体（音频和视频）。 代码假设在加载脚本的网页中有两个视频代码。 这些标签将用于显示由您自己的客户端浏览器捕获的视频，以及从其他对等方接收的媒体。 构造函数接收一个属性，该属性包含配置所需的所有信息。

 var videoInput = document.getElementById('videoInput');
 var videoOutput = document.getElementById('videoOutput');

 var constraints = {
     audio: true,
     video: {
       width: 640,
       framerate: 15
     }
 };

 var options = {
   localVideo: videoInput,
   remoteVideo: videoOutput,
   onicecandidate : onIceCandidate,
   mediaConstraints: constraints
 };


var webRtcPeer = kurentoUtils.WebRtcPeer.WebRtcPeerSendrecv(options, function(error) {
      if(error) return onError(error)

      this.generateOffer(onOffer)
});

有了这个小代码，库负责创建RTCPeerConnection，并在浏览器中调用getUserMedia（如果需要）。若constraints属性在调用中使用，在这种情况下，将使用麦克风和网络摄像头。但是，这不会创建连接。这只有在完成对等体之间的SDP协商之后才能实现。这个过程意味着交换SDP提供和回答，并且由于使用了Trickle ICE，描述每个对等体的能力的多个候选者。谈判的工作原理超出了本文件的范围。更多信息可以在这个链接中找到。

在上一段代码中，当webRtcPeer对象被创建时，使用this.generateOffer（onOffer）生成SDP。传递的唯一参数是一个函数，它将在浏览器的对等连接生成该提议时调用。 onOffer回调方法负责通过您的应用程序中设计的任何方法将此提议发送给其他对等方。由于这是每个特定应用程序的信令面和业务逻辑的一部分，因此本文档中将不涉及。

假设SDP提议已经被远程对等体接收到，则它必须已经生成SDP应答，该SDP应答应该被接收。此回答必须由webRtcEndpoint处理，以便完成协商。这可以是onOffer回调函数的实现。我们假设在范围中有一个函数，允许发送SDP到远程对等体。

function onOffer(error, sdpOffer) {
  if (error) return onError(error);

  // We've made this function up sendOfferToRemotePeer(sdpOffer,
  function(sdpAnswer) {
    webRtcPeer.processAnswer(sdpAnswer);
  });
}

正如我们之前所说的，库假设使用Trickle ICE来完成两个对等体之间的连接。 在webRtcPeer的配置中，有一个对onIceCandidate回调函数的引用。 库将使用此函数将ICE候选项发送到远程对等体。 由于这是每个应用程序的特性，我们将只显示签名。

function onIceCandidate(candidate) {
  // Send the candidate to the remote peer
}

反过来，我们的客户端应用程序必须能够从远程对等体接收ICE候选。 假设信令关注接收那些候选，则足以在webRtcPeer中调用以下方法来考虑ICE候选。

webRtcPeer.addIceCandidate(candidate);

按照前面的步骤，我们有：

• 发送SDP，提供给远程对等体
• 从远程对等体接收到SDP应答，并让webRtcPeer进程回答。
• 在对等体之间交换ICE候选者，通过发送在浏览器中生成的ICE候选者，以及处理由远程对等体接收的候选者。

完成协商过程，并且应该让我们在两个对等体之间进行有效的双向WebRTC媒体交换。

使用 data channels

WebRTC数据通道允许您通过活动的WebRTC连接发送文本或二进制数据。 WebRtcPeer对象可以通过使用RTCDataChannel形式的RTCPeerConnection对象来提供对此功能的访问。 这允许您注入和使用管道中的数据。 这些数据可以被不同的每个端点处理。 例如，浏览器中的WebRtcPeer对象将具有与RTCDataChannel相同的行为（您可以在此处查看说明）。 其他端点可以利用该信道来发送信息：检测视频流中的QR码的过滤器可以通过数据信道将检测到的码发送给客户端。 这个特殊的行为应该在过滤器中指定。

通过在选项包中传递dataChannels标志以及所需的选项来指示WebRtcPeer对象中数据通道的使用。

var options = {
     localVideo : videoInput,
     remoteVideo : videoOutput,
     dataChannels : true,
     dataChannelConfig: {
       id : getChannelName(),
       onmessage : onMessage,
       onopen : onOpen,
       onclose : onClosed,
       onbufferedamountlow : onbufferedamountlow,
       onerror : onerror
     },
     onicecandidate : onIceCandidate
 }

 webRtcPeer = new kurentoUtils.WebRtcPeer.WebRtcPeerSendrecv(options, onWebRtcPeerCreated);

dataChannelConfig中的值都是可选的。 一旦webRtcPeer对象被创建，并且在成功协商连接之后，用户可以通过数据通道发送数据。

webRtcPeer.send('your data stream here');

您要发送的数据的格式由应用程序以及您使用的端点的定义决定。

底层RTCDataChannel的生命周期与webRtcPeer的生命周期相关：当调用webRtcPeer.dispose（）方法时，数据通道将被关闭并释放。

文档参考

WebRtcPeer

WebRtcPeer的构造函数是WebRtcPeer(mode，options，callback)其中：

• mode：配置PeerConnection的模式。 有效值为:

  recv：只接收媒体。

  send：只发送媒体。

  sendRecv：发送并接收媒体。

• options：它是一组参数，它们是可选的。 它是一个json对象。

  localVideo：应用程序中本地流的视频标记。

  remoteVideo：应用程序中远程流的视频标记。

  videoStream：提供已经可用的视频流，而不是使用来自本地网络摄像头的媒体流。

  audioStreams：提供已经可用的音频流代替使用来自本地麦克风的媒体流。

  mediaConstraints：定义视频和音频的质量。

  connectionConstraints：根据浏览器定义连接约束，如googIPv6，DtlsSrtpKeyAgreement ...

  peerConnection：使用以前创建的peerConnection

  sendSource：将使用哪个源

    - webcam
  
    - screen
  
    - window
  

  onstreamended：当流结束事件发生时将被调用的方法

  onicecandidate：当冰候选事件发生时将被调用的方法

  oncandidategatheringdone：当所有候选项都已被收集时将调用的方法

  dataChannels：启用数据通道使用的标志。 如果为true，那么将在RTCPeerConnection对象中创建一个数据通道。

  dataChannelConfig：这是一个JSON对象，该配置通过DataChannel传递并创建。 它支持以下键：

    -id：指定数据通道的id。 如果没有指定，将使用WebRtcPeer对象的相同id。
  
    -options：传递给数据通道构造函数的选项对象。
  
    -onopen：在数据通道的onopen事件中调用的函数，当通道打开时触发。
  
    -onclose：在数据通道的onclose事件中调用的函数，当数据通道关闭时触发。
  
    -onmessage：在数据通道的onmessage事件中调用的函数。 每次接收到消息时触发此事件。
  
    -onbufferedamountlow：当接收bufferedamountlow事件时调用事件处理程序。 当RTCDataChannel.bufferedAmount下降到小于或等于RTCDataChannel.bufferedAmountLowThreshold属性指定的量时，将发送此类事件。
  
    -onerror：当数据通道产生错误时，调用回调函数。 如果没有提供，将在浏览器控制台中记录错误跟踪消息。
  

  simulcast：指示是否要使用联播。 值为true | false

  configuration：它是一个JSON对象，ICE服务器定义使用

    -iceServers：此变量的格式如下：
    [{"urls":"turn:turn.example.org","username":"user","credential":"myPassword"}]
    [{"urls":"stun:stun1.example.net"},{"urls":"stun:stun2.example.net"}]
  

• callback：它是一个指示回调函数，判断一切正常与否。

还有3种特定的方法来创建WebRtcPeer对象而不使用mode参数：

-WebRtcPeerRecvonly(options, callback): 创建一个只接收的WebRtcPeer。

-WebRtcPeerSendonly(options, callback): 创建一个只发送的WebRtcPeer。

-WebRtcPeerSendrecv(options, callback): 创建一个发送和接收的WebRtcPeer。

MediaConstraints

MediaConstraints提供了通用的界面控制，允许应用程序为轨道选择适当的源，并且一旦选择，就影响源如何操作。 getUserMedia() 使用MediaConstraints来帮助轨道选择适当的源并配置它。 有关MediaConstraints及其值的详细信息，可以在此处查看。

默认情况下，如果mediaConstraints未定义，当调用getUserMedia时将使用此约束：

{
  audio: true,
  video: {
    width: 640,
    framerate: 15
  }
}

如果mediaConstraints有值，库将使用此值来调用getUserMedia。 这取决于浏览器是否接受这些约束。

在示例部分中，有一个关于使用媒体约束的示例。

Methods

• getPeerConnection

  使用这种方法，用户可以获得peerConnection并直接使用它。

• showLocalVideo

  使用这个方法显示本地视频

• getLocalStream

  使用此方法，用户可以获取本地流。 如果此属性为true，则可以使用muted属性来隐藏音频。

• getRemoteStream

  使用此方法，用户可以获取远程流。

• getCurrentFrame

  使用这种方法，用户可以获得当前帧并获得具有当前帧的图像的画布。

• processAnswer

  收到SDP应答时调用回调函数。 开发人员需要调用此功能才能完成SDP协商。 此方法有两个参数：

  • sdpAnswer: sdpAnswer描述
  • callback: 它是一个具有类似错误函数的参数。 当远程描述已成功设置时调用。

• processOffer

  收到SDP提议时调用回调函数。 开发人员需要调用此功能才能完成SDP协商。 此方法有两个参数：

  -sdpOffer: sdpOffer描述 -callback: 它是一个具有类似错误函数的参数。 当远程描述已成功设置时调用。

• dispose

  此方法释放WebRtcPeer使用的资源。

• addIceCandidate

  在接收ICE候选时调用回调函数。 开发人员需要调用此功能才能完成SDP协商。 此方法有两个参数：

  -iceCandidate: 文本对象与ICE候选描述 -callback: 它是一个具有类似错误函数的参数。 当远程描述已成功设置时调用。

• getLocalSessionDescriptor

  使用这种方法，用户可以获得对等体连接的本地会话描述符。

• getRemoteSessionDescriptor

  使用这种方法，用户可以获得对等连接的远程会话描述符。

• generateOffer

  创建用于查找具有指定配置的远程对等项的请求。

如何做屏幕共享

屏幕窗口共享取决于私有模块kurento-browser-extensions。 要启用它的支持，您需要手动安装包依赖关系或在运行时自己提供getScreenConstraints函数。 在创建WebRtcEndpoint之前，sendSource选项可以是窗口或屏幕。 如果它不可用，当您试图共享屏幕或窗口内容将抛出异常。

Souce code

源代码托管在GitHub

确保在您的系统中安装了Node.js和Bower：

curl -sL https://deb.nodesource.com/setup | sudo bash -
sudo apt-get install -y nodejs
sudo npm install -g bower

安装库，建议从NPM镜像库执行此操作：

npm install kurento-utils

或者，您可以使用Git下载代码，并手动安装其依赖关系：

git clone https://github.com/Kurento/kurento-utils
cd kurento-utils
npm install

Build for browser

下载项目后，要构建浏览器版本的库，您只需要执行grunt任务。 所需的文件将在dist文件夹中生成。 或者，如果您没有全局安装，您可以通过执行以下命令来运行本地副本：

cd kurento-utils
node_modules/.bin/grunt