EasyRTC官方tutorial [译文]

neteaseim 2019-06-26

EasyRTC

概览

EasyRTC基于webRTC。WebRTC是W3C/IETF用于浏览器间实时音视频沟通以及数据传输的一个实现方案。WebRTC只需要一个轻量负荷的服务器就可以支持点对点(P2P)间的任何数据传输。

EasyRTC由客户端(浏览器端)的JS库与基于node.js的后端服务器组成。WebRTC已经被各个浏览器(google chrome, firefox, opera, etc)所支持,因此无需额外的浏览器插件。

Google Chrome对WebRTC的API有着最广泛的支持,Opera现在采用与Chrome相同的内核引擎,因此所有API行为与chrome基本一致。Firefox对WebRTC的Data Channel有着十分良好的实现,但仅提供了基础的视频功能。

一旦WebRTC被标准化,它将有着巨大的潜能为音视频会议,多用户游戏,以及许多其他的基于音视频,数据传输的应用提供支持。

如同其他的软件,强大的功能往往伴随着复杂的内部实现。WebRTC有着十分曲折的学习曲线,对开发人员不够友好。为了简化具体的开发流程,我们(Priologic)构建了EasyRTC框架。

构建一个基于WebRTC的应用通常有如下步骤。

  • 将本地摄像头、麦克风获取到的数据输出成media stream对象
  • 与信令服务器建立连接
  • 通过浏览器与目标用户建立p2p通信
  • 将media stream绑定到<video>

通过使用EasyRTC,一些步骤可以被简化到一个简单的通信(call)当中,
能极大地简化开发流程,尤其是当开发人员需要投入更多的精力于多平台支持当中。

此文档是编写基于WebRTC应用的一个基本教程,但并未包含EasyRTC的所有API。

术语

  • callbakck(回调函数)
  • Media Stream 浏览器音视频输出对象
  • Peer Connection 点对点连接
  • Server

安装EasyRTC与获取支持

EasyRTC的安装十分简单,多数平台可在10分钟内完成。我们提供了Windows,Linux,Mac的安装向导。EasyRTC的源码可在[https://github.com/priologic/...]获取。在doc目录下可以获取到客户端与服务端的所有HTML说明文档

视频会议

html 略

页面载入完成(onload)后调用初始化函数(initialization function)。
初始化函数的最主要作用是调用EasyRTC.easyApp方法。该方法有如下参数

  • applicationName - String 应用名,如"Company_Chat_Line"
  • self-video-id - String video标签id
  • array-of-caller-video-ids - Array 包含了其他用户(除当前用户)的video标签id
  • successCallback - 连接成功时回调函数

初始化函数可以使用EasyRTC.setRoomOccupantListener来注册一个回调函数,以用于获取当前已连接到同一房间内的其他用户id,。

示例:

function my_init() {
    easyrtc.setRoomOccupantListener(loggedInListener)
    easyrtc.easyApp("Company_chat_line", "self", ["caller"], id => {
    console.info("My id is " + id)
    })
}

当用户从"Company_chat_line"连接或断开链接时,easyrtc.setRoomOccupantListener将被调用,该方法的回调函数包含两个参数:

  • String room name
  • Array 连接到相同房间名的用户id

在我们的示例程序当中,该方法的回调函数将建立一系列用于“拨打”给当前已连接到房间内的其他用户的按钮。

html 略

多数情况下可以忽略room_name参数,除非你的应用允许用户同时连接到多个房间。

在现实的应用当中,我们不会使用easyrtc的默认id当作按钮的label属性。我们将使用类似姓名,职位等建立起与easyrtc id相关联的内容以用作按钮的label属性。

初始化一个call,我们只需要调用 easyrtc.call 方法,传入目标用户的id,该方法包含三个回调函数:

  • successCallback(id)
  • errorCallback(errorCode, errorText)
  • accepted(wasAccepted, id) 指明该call是否被接受

示例代码:

function performCall(id) {
    easyrtc.call(id, id => {
        console.info("completed call to  " + id)
    }, errorMessage => {
        console.error("err: " + errorMessage)
    }, (accepted, bywho) => {
        console.info(accepted ? "accepted" : "rejected" + " by " + bywho)
    })
}

html 略

视频会议(Advanced)

在上一节,我们大致地描述了构建一个视频会议应用的最简单情形。
在这一节,我们将进一步深入。

除了调用easyrtc.easyApp,你也可以调用easyrtc.initMediaSource来直接获取本地设备的media stream,成功之后可以调用easyrtc.connect方法来连接到信令服务器。这也是easyrtc.easyApp的内部实现。

html略

注意: easyrtc.getLocalStream和easyrtc.setVideoObjectSrc,前者用于当easyrtc.initMediaSource调用完成,从本地摄像头和麦克风获取media stream,后者用于将media stream与video标签绑定。一起使用便可以十分便携地供用户实时观察到他们自己的图像。

我们还需要两个其他函数

  • 一个用于提供远程用户的media stream
easyrtc.setStreamAcceptor((callerId, stream) => {
    let video = document.getElementById("caller")
    easyrtc.setVideoObjectSrc(video, stream)
})
  • 一个用于检测远程用户是否挂起(离线)。该函数用于清除对应的video标签
easyrtc.setOnStreamClosed(callerId => {
        easyrtc.setVideoObjectSrc(document.getElementById("caller"), "")
    })

整个js文件如下

// 设置远程用户的media stream 的关联video标签
easyrtc.setStreamAcceptor((callerId, stream) => {
    let video = document.getElementById("caller")
    // 绑定media stream到video标签对象
    easyrtc.setVideoObjectSrc(video, stream)
})

// 当远程media strem 关闭
easyrtc.setOnStreamClosed(callerId => {
// 清除关联的video标签内容
easyrtc.setVideoObjectSrc(document.getElementById("caller"), "")
})

// 初始化函数
function my_init() {
    // 设置监听器,获取当前在线的用户
    easyrtc.setRoomOccupantListener(loggedInListener)
    // 连接成功处理函数
    let connectSuccess = myId => {
        console.info("My easyrtc id is " + myId)
    }
    // 连接失败 创建本地media stream对象失败时调用函数
    let connectFailure = (errorCode, errText) => {
        console.error(errText)
    }
    // 初始化本地media stream
    easyrtc.initMediaSource(() => {
        let selfVideo = document.getElementById("self")
        // 绑定本地media stream 到video tag
        easyrtc.setVideoObjectSrc(selfVideo, easyrtc.getLocalStream())
        // 连接到服务器
        easyrtc.connect("Company_Chat_line", connectSuccess, connectFailure)
    }, 
    connectFailure)
}

// 当获取到当前房间内在线用户
function loggedInListener(roomName, otherPeers) {
    let otherClientDiv = document.getElementById("otherClients")
    while(otherClientDiv.hasChildNodes()) {
    // 移除最后一个 “text ”
otherClientDiv.removeChild(otherClientDiv.lastChild)
    }
    
    for (let i in otherPeers) {
        let button = document.createElement("button")
        // 为每一个远程用户创建一个按钮监听器
        button.onclick = easyrtcId => {
            // 发起连接
            return (easyrtcId) => performCall(easyrtcId)
        }(i)
        
        let label = document.createTextNode(i)
        button.appendChild(label)
        otherClientDiv.appendChild(button)
    }
}

function performCall(id) {
    easyrtc.call(id, id => {
        console.info("completed call to " + id)
    }, 
    (errorCode, errText) => {
        console.error("err: " + errorText)
    }, 
    (accepted, bywho) => {
        console.info(accepted ? "accepted" : "rejected" + " by " + bywho)
    })
}

使用多个本地media stream源

使用多个media stream的基本思想是,你需要为每个media stream命名。
当你调用initMediaSource,它的第三个参数便是media stream的名字,
如:

easyrtc.initMediaStream(success, failure, yourname)

如果你没有传入第三个参数,则该media stream会得到一个默认的"default"。

使用easyrtc.getLocalMediaIds以获取所有本地media stream的名字

let ids = easyrtc.getLocalMediaIds()
ids.map(id => console.info(id))

当你初始化一个call,可以传入一个stream name的数组作为第五个参数,同样的,当你接受call时,你可以传入一个stream name的数组作为accept回调函数的第二个参数。

easyrtc.call(otherEasyrtcId, successCB, failCB, wasAcceptedCB, ["first_name", "second_name", "etc"])

easyrtc.setAcceptChecker((otherGuy, acceptCallback) => {
    acceptCallback(true, ["first_name", "second_name"])
})

你也可以通过使用easyrtc.addStreamToCall向一个已存在的call添加meida stream。该方法接受三个参数,接受stream的id,stream的名字,以及一个optional的回调处理函数。

注意:EasyApp 框架并不是专门为多media stream而设计的。它的初衷便是假定只有单个本地media stream。
如果你想使用media stream,那么你就必须自己将这些media stream绑定到video标签。

屏幕分享

只使用音频或视频功能

拒绝远程对话(call)

EasyRTC允许注册一个在用户每次收到call时都将被调用的函数。该函数接受远程用户的id,以及一个报告函数(reporting function)作为参数,报告函数接受一个参数,true接受对话,false拒绝对话。

easyrtc.setAcceptChecker( function(easyrtcid, acceptor){
          if( easyrtc.idToName(easyrtcid) === 'Fred' ){
             acceptor(true);
          }
          else if( easyrtc.idToName(easyrtcid) === 'Barney' ){
             setTimeout( function(){
     acceptor(true, ['myOtherCam']); // myOtherCam presumed to a streamName
     }, 10000);
          }
          else{
             acceptor(false);
          }
     });

加入或离开房间

Room是EasyRTC的一个隔离(compartmentalize)功能,目的是为用户建立起一个个“chat rooms”。
房间的行为受服务器安装的EasyRTC Server的配置所影响(详见服务器模块文档)。默认行为如下:

  • 除非用户在连接前指定了所要加入的房间名,否则将会加入默认的“default”房间。
  • 一个用户可以是多个房间的成员
  • 每个用户所加入的任一个房间发生变化时(用户的加入,离开),都会触发roomOccupantListener函数
  • 加入一个不存在的房间将会创建它
  • 加入房间
easyrtc.joinRoom(roomName, roomParameters, successCallback, failureCallback)

其中,roomParameters是Application specific(不详),可以为空。joinRoom可以在任何时候调用任意多次,但successCallback, failureCallback只会在成功与信令服务器建立连接之后才会被调用。

  • 离开房间
easyrtc.leaveRoom(roomName, successCallback, failureCallback)

leaveRoom的性质同joinRoom

监听Error

你可以通过easyrtc.setOnError注册一个error callback用以处理错误。该函数接受一个形如{"errorCode": "errorCode", "errorText": "errorText"}的对象。

easyrtc.setOnError(errEvent => {
    console.error(errEvent.errorText)
})

发送消息

你可以通过调用easyrtc.sendDataWS来使用websocket通信,

easyrtc.sendDataWS(destination, messageType, messageData, ackHandler)

easyrtc.sendDataWS("xkxkxkxkxk9c93", "contactInfo", {firstName: "jack", lastName: "smith"}, ackMsg => {
// ackMsg 为来自服务器的确认信息
    if (ackMsg.msgType === "error") {
        console.error(ackMsg.msgData.errorText)
    }
})

注意: 通过websocket通信意味着你指定信息要通过服务器转发

destination 可以是peer的id,或者是一个指定了一个或多个目标id的js对象,或者房间(详见文档)。
messageType需要自行指定,ackHandler处理来自服务器的确认信息

处理来自其他用户的信息:
easyrtc.setPeerListener((sender_id, msgType, msgData, targeting) => {

if (msgType === "contactInfo") {
    console.info(sender_id + " is named " + msgData.firstName + " " + msgData.lastName)
}

})

其中,当使用WebRTC的data channel发送数据时,targeting为null,否则为{targetEasyrtcid, targetGroup, targetRoom}当中的一个。

你也可以为特定的msgType或sender指定监听器,在这种情况下,每次将只有一个监听器会被调用,指定的监听器将被优先调用。

使用Data Channels

在使用data channel之前,发送者和接收者都必须启用data channels。

easyrtc.enableDataChannels(true)

之后便可监听与特定用户的datachannel的 ready 和 close 事件,

easyrtc.setDataChannelOpenListener(sourceEasyrtcId => 
    console.info("channel is open ")
)

easyrtc.setDataChannelCloseListener(sourceEasyrtcid => 
    console.info("channel is close ")
)

open监听器被调用之后,便可以通过easyrtc.sendDataP2P来发送消息:

easyrtc.sendDataP2P(targetEasyrtcid, "contactInfo", {firstName: "jack", lastName: "smith"})

监听data channels消息与websocket消息一致

获取当前连接数

通过easyrtc.getConnectionCount来获取当前用户的连接数,该函数返回一个number

挂起

通过easyrtc.hangup(peerId)来挂起与特定用户的连接

easyrtc.hangupAll()来挂起与所有用户的连接

与服务器断开链接

easyrtc.disconnect()

相关推荐