licode 客户端API （译文）【转】

来自：http://quainty.org/licode-webrtc/9.html

原文地址：http://lynckia.com/licode/client-api.html

概览：

Api在浏览器中使用，作为一种javascript文件提供使用，可以在你的web应用中直接调用。

典型的使用组合：想要连接的房间，使用后端函数，管理本地音视频，客户端事件管理等等。

客户端API类列表

类名	描述
Erizo.Stream	在LicodeRoom提供本地和远程视频流，音频流和数据流
Erizo.Room	描述LicodeRoom，提供连接，本地流发布和远程流订阅
Erizo.Event	一系列不同类型消息，它代表一个通用事件

Erizo.Stream

它处理webRTC的音视频流和数据流，在适当位置绘制。

这些数据流可以是本地或远程。Licode内部提供创建远程流通过Erizo.Room API

它通过stream.getID()识别每个本地和远程流，它通过stream.paly()控制在html中图像绘制(只有他们在音视频流中)；

你需要在Room中使用流之前初始化这些流，通常流的初始化如下：

<code>

var stream = Erizo.Stream({audio:true, video:false, data: true, attributes: {name:’myStream’}});

</code>

如果你想要在room中发布视频，音频和数据，则这些视频、音频和数据变量必须被设定为true。同时attributes变量可以存储额外的与流相关的信息。这些信息可以在客户端和room中共享。

如果你想要使用一个流共享你的屏幕，你应该像这样初始化：

<code>

var stream = Erizo.Stream({screen: true, data: true, attributes: {name:’myStream’}});

</code>

注意，你按上述方法使用一个流，将要共享屏幕的客户端必须是安全连接（https协议）而且使用屏幕共享插件（http://lynckia.com/licode/plugin.html）。

当创建一个流的时候，你也可以指定视频大小限制。为了这样做，你需要包含上videoSize参数，它是一个如下数组[minWidth,minHeight,maxWidth,

maxHeight]，则初始化如下：

<code>

var stream = Erizo.Stream({video: true, audio: true, videoSize: [320, 240, 640, 480]});</code>

你可以创建一个流发布到外部licode会话上。在这点上，RTSP和文件都是支持的，基于codec文件。你可以创建一个外部流通过使用url变量。例如从rtsp源上创建一个流：

<code>

var stream = Erizo.Stream({video: true, audio: false, url:”rtsp://user:pass@the_server_url:port”});

</code>

或者从.mkv文件创建一个流

var stream = Erizo.Stream({video: true, audio: false, url:”file:///path_to_file/movie.mkv”});

你可以得到以下变量在一个流对象中：
showing检测流是否是本地正在播放的音视频
room可以知道连接的room
local可以知道流是本地还是远程的

接下来这张表可以知道stream类的函数：

 

function	描述
hasAudio()	流是否有激活的视频
hasVideo()	流是否有激活的音频
hasData()	流是否有激活的数据
Init()	初始化本地流
Close()	关闭本地流
Play(elementID,option)	在html中显示视频
Stop()	Html中移除视频
sendData(msg)	通过流向订阅的客户端发送数据
getAttributes()	当创建流的时候，得到属性变量并保存
setAttributes()	设定分享到Room的本地流新的属性
getVideoFrame()	从视频中得到位图
getVideoFrameURL()	从视频中得到位图的URL

检测流中是否有激活的视频、音频和数据

你可以通过一下函数检测流中是否有激活的视频、音频和数据。例子如：
stream.hasAudio();
stream.hasVideo();
stream.hasData();

初始化流

初始化流和从本地音视频中检索一个流（以防你激活他们）。

你需要在将流发布到room或者在本地播放之前调用这个方法。

例子：你首先要创建流然后需要初始化它（line1）。然后需要添加一个监听事件区知道何时用户授权使用摄像头和麦克风（line2）。你将会收到

’access-accepted’或’access-denied ’消息。
stream.init();
stream.addEventListener(‘access-accepted’,function(event) {
console.log(“Access to webcam and microphone granted”);
});
stream.addEventListener(‘access-denied’,function(event) {
console.log(“Access to webcam and microphone rejected”);
});

关闭本地流

如果流中有音视频，这个函数也将关闭摄像头和麦克风。

如果流被推送到了room，这个函数也将停止推送。

如果流在div中播放，这个函数也将停止其播放。

例子：你可以关闭一个曾经初始化的本地流，代码如下：
stream.close();

在html中播放本地流

给定elementID就可以开始播放音视频。它自动创建一个音视频的html标签。

例子：只有当已将收到access-accepted消息后，才可以播放音视频。需要通过elementID作为参数。通过option参数可以控制声音滑块的隐藏。
stream.play(elementID,{speaker: false});

例子：默认情况下视频流会自动适应div，但是有时视频会被剪一些。如果你不想视频被剪，你可以做如下设置:
stream.play(elementID,{crop: false});

从html中消除本地视频

例子：你可以在html中停止音视频的播放，代码如下：
stream.stop();

通过流发送数据

通过流发送信息，所有被订阅过的用户将会收到此信息。

例子：客户端可以发送任何json序列化过的消息，这个消息将会通过流的stream-data事件接收到。所有所有的客户端应该被订阅。
stream.sendData({text:’Hello’,timestamp:12321312});

得到属性对象

得到用户存储的或者更新的流的属性对象。

例子：属性变量通常是json对象
varstream = Erizo.Stream({audio:true, video:false, data: true, attributes: {name:’myStream’, type:’public’}});

varattributes = stream.getAttributes();
if(attributes.type ===’public’) {
console.log(attributes.name);
}
stream.addEventListener(“stream-attributes-update”,function(evt) {
varstream = evt.stream;
// Handle stream attribute event.
});

 

得到一帧视频

从视频中得到一帧的图像。

例子：客户端能从视频流中得到原始位图数据。流返回位图数据。你可以把它放在canvas标签中。如果你想要得到定期不停的得到图像可以设置一个时间间隔。
varbitmap;
varcanvas = document.createElement(‘canvas’);
varcontext = canvas.getContext(‘2d’);

canvas.id =”testCanvas”;
document.body.appendChild(canvas);

setInterval(function(){

bitmap =stream.getVideoFrame();

canvas.width =bitmap.width;
canvas.height =bitmap.height;

context.putImageData(bitmap,0, 0);

},100);

Erizo.Room

它提供了一个licodeRoom，它处理连接，本地流推送和远程流订阅。

典型Room初始化如下：
varroom = Erizo.Room({token:’213h8012hwduahd-321ueiwqewq’});

它将会通过这个用户层收到的标记（token）来创建一个room对象。这个标记必须是服务器API返回的，因为这是一个用户的存取标记。但是你需要调用连接函数连接这个Room。

你可以获取以下变量：
localStreams：在Room中检索当前列表中的本地流变量
remoteStreams：返回Room中当前列表里的远程流变量
roomID：房间标识符
state：当前房间状态。如果没有连接状态可以是0，如果正在连接或已经连上则状态是2.

Room的函数：

connect()	建立与Room的连接
publish(stream)	发布流
subscribe(stream)	订阅远端的流
unsubscribe(stream)	取消订阅流
unpublish(stream)	取消发布流
disconnect()	断开与room的连接
startRecording(stream)	开始录制流
stopRecording(recordingId)	通过recordingId停止录制流
getStreamByAttribute(name,value)	返回指定了属性的远端流列表

打开一个到房间的连接

建立到房间的连接。这个函数是异步的，所以需要添加一个事件监听去知道何时连接上了room。它会抛出room-connected事件。

例子：这个room通过有效的标志（token）建立。然后我们连接到这个room（line1），同时添加事件监听，等待连接建立（line2）。请注意，不能对room做任何操作直到接收到这个事件。
room.connect();
room.addEventListener(“room-connected”,function(event) {
console.log(“Connected!”);
});

发布本地流

根据给定的流参数，发布本地流。客户端应该先初始化流再连接room。当调用这个函数时就开始给licode room发送音/视频流。流准备好后这个room的所有用户都将收到stream-add事件，事件中有你的流信息，其他用户可以订阅它。

例子：首先你需要创建并初始化一个流然后连接room。接下来为了发布流你需要把流交给room（line1）。当轮流最终发布到room后抛出stream-add事件，因为流被添加进了room。必须添加事件监听去处理它（line2），然后检查这个流是否是你刚刚发布的（line3）。
room.publish(localStream);
room.addEventListener(“stream-added”,function(event) {
if (localStream.getID() === event.stream.getID()) {
console.log(“Published!!!”);
}
});

Room.publish也允许对本地流设置带宽限制，通过maxVideoBW参数设置，带宽单位为Kbps。注意，服务器端带宽设置config.erizoController.defaultVideoBW的优先级较高。
room.publish(localStream,{maxVideoBW:300});

订阅一个远程流

在room中订阅一个远程流，需要你首先连接room然后知道room中的哪个流是可订阅的。如前文所述我们已经添加了stream-add事件监听。在这里我们收到的事件中将有stream对象参数。

例子：首先连接room，然后收到你想要订阅的流的事件。注意，你可以订阅你发布的流，但是你将会收到会有时延。我们建议你使用streamAPI直接播放你的本地流。
room.addEventListener(“stream-subscribed”,function(streamEvt) {
console.log(“Stream subscribed”);
});
room.subscribe(stream);

例子：你可以通过subscribe参数选择你想要订阅的音频或视频流。这个例子就是只订阅音频。
room.addEventListener(“stream-subscribed”,function(streamEvt) {
console.log(“Stream subscribed”);
});
room.subscribe(stream,{audio: true, video: false});

取消订阅远程流

你可以取消已经订阅的远程流，要求通订阅相似。

例子：你首先必须订阅过流。当你取消订阅时，html上的对应元素将被清空。
room.unsubscribe(stream);

取消订阅本地流

当你连接到room并正在发布本地流时，你可以通过stream取消你的流。要求与订阅流相似。当你的流取消发布时，Room将向所有用户抛出stream-remove事件。

例子：首先你需要发布本地流，然后你任意时间可以取消发布你的流（line1）。当你收到stream-removed事件时，你可以确定你的流没有被发布（line2-3）。
room.unpublish(localStream);
room.addEventListener(“stream-removed”,function(event) {
if(localStream.getID() === event.stream.getID()) {
console.log(“Unpublished!!!”);
}
});

与room断开连接

当你需要的时候可以与room断开连接。Room将会抛出room-disconnected事件。

例子：
room.disconnect();

开始录制

开始在服务端由licode-config.js指定的路径录制流。录制的内容将以.mkv格式并以VP8编解视频以PCMU或OPUS编解音频，这取决于服务器端的设置。录制的文件可以直接播放或者以流的形式在room中播放。Licode将会一直录制直到调用停止录制或者被录制的流退出了房间。

例子：开始录制本地流
room.startRecording(localStream,function(recordingId) {
console.log(“Recording started, the id of the recording is “,recordingId);
});

停止录制

停止某个流的录制，你必须提供录制的id号：recordingId。

例子：停止录制
room.stopRecording(recordingId);

播放录制的流

有两种方式播放录制的流，这两种方式都需要外部流的参与，你可以设置url参数指定录制的路径或使用recordingId。

例子：从url指定的路径中播放录制或者使用recordingId。
varstream = Erizo.Stream({video: true, audio: false, url:”file:///path_to_file/previousRecording.mkv”});
room.publish(stream);
varstream2 = Erizo.Stream({audio:true, video:true, recording: ‘asda2131231′});
room.publish(stream2);

通过属性得到流

你可以通过属性找到流，一个远程流也是一个你曾订阅过的room流。

例子：如果你想通过’public’属性得到流
varstreams = room.getStreamsByAttribute(‘type’, ‘public’);
//streams is an array that contains the stream objects.

 

事件处理

Room继承于EventDispatcher（可以通过event章节得到更多信息），处理RoomEvent和StreamEvent。例如：
事件’room-connected’表明用户成功连接到room；
事件’room-disconnected’表明用户已经与room断开连接；
事件’stream-added’表明room中加入了新的流；
事件’stream-removed’表明之前的某个流离开了room；

当客户端处于连接状态中就可以收到任意事件。

例子：尽管我们已经举了一些关于事件监听的例子，这里强烈建议在room中做任何操作之前，添加事件监听。
varroom = Room({token:”…”});
room.addEventListener(“room-connected”,function(evt){…});
room.addEventListener(“room-disconnected”,function(evt){…});
room.addEventListener(“stream-added”,function(evt){…});
room.addEventListener(“stream-removed”,function(evt){…});
room.connect();

Erizo.Ewents

Licode提供了一系列事件类去处理客户端的连接的状态变化。Room和Stream类抛出不同的licode event（这就是EventDispatcher）并需要为他们添加事件监听。这里介绍licode事件的不同类型。下表有个简要的描述。

类	描述
Licode Event	代表在库中继承于其他类的通用事件
Room Event	代表与room连接相关联的事件
Stream Event	代表与在room中的流相关联的事件

 

 

Licode Event

它处理事件类型非常重要，主要处理添加EventDispather事件监听和分发新事件。

例子：一个licodeEvent可以如下初始化，但它通常被客户端API创建。
varevent = Erizo.LicodeEvent({type: “room-connected”});

Room Event

它代表连接和断开事件。你可以获得连接到一个room中的所有流的列表，通过roomEvent.stream。这是room事件的列表：
room-connected：指出用户已经成功连接到room，这个消息也提供了发布到room中的所有流列表。
room-disconneted：表明用户已经与room断开连接。

他们都是通过room对象发送出去的。

例子：一个RoomEvent初始化如下，但是他通常被Room对象创建。
varroomEvent = Erizo.RoomEvent({type:”room-connected”, streams:[stream1, stream2]});

 

例子：他们都是Room对象发送出去的，所有你需要给他们添加事件监听。
room.addEventListener(“room-connected”,function(evt){…});

Stream Event

它代表stream相关的事件。你可以通过streamEvent.stream获得相关的流。以下是不同类型的stream事件：
access-accepted：表明用户同意使用摄像头和麦克风；
access-denied：表明用户拒绝使用摄像头和麦克风；
stream-added:表明room中有新的流添加进来；
stream-removed: 表明room中有一个流离开；
stream-data:在流中收到新数据
stream-attributes-update:通知流的拥有者这个流的属性被更新了；

他们通过Room对象发送。

例子：StreamEvent如下被初始化，但是它通常被客户端API创建。

var streamEvent = Erizo.StreamEvent({type:”stream-added”, stream:stream1});

例子：stream-added和stream-removed都是Room对象发送的，所有你需要给他们添加事件监听。
room.addEventListener(“stream-removed”,function(evt){…});

例子：access-accepted, stream-data和stream-attributes-update都是Stream对象发送的，所有你需要给这些事件添加监听函数。
stream.addEventListener(“access-accepted”,function(evt){…});

stream.addEventListener(“stream-data”,function(evt){
console.log(‘Received data ‘,evt.msg, ‘from stream ‘, evt.stream.getAttributes().name);
});

room.addEventListener(“stream-attributes-update”,function(evt){…});

例子

这里展示典型用户的一些例子和代码片段，这些代码使用了这个API中几乎所有的部分。

例子：基本的视频会议功能。这里每个客户端连接room将要发布自己的视频和音频，订阅其他所有用户的音频和视频。这个例子使用了唯一的room。
<html>
<head>
<title>Licode Basic Example</title>
<scripttype=”text/javascript” src=”erizo.js”></script>
<scripttype=”text/javascript”>

window.onload =function () {

varlocalStream = Erizo.Stream({audio: true, video: true, data: true});
varroom = Erizo.Room({token: “af54/=gopknosdvmgiufhgadf==”});

localStream.addEventListener(“access-accepted”,function () {
//同意使用摄像头和麦克风
varsubscribeToStreams = function (streams) {
for(var index in streams) {
varstream = streams[index];
if(localStream.getID() !== stream.getID()) {
room.subscribe(stream);
}

}

};

room.addEventListener(“room-connected”,function (roomEvent) {
// 连接到room
room.publish(localStream);//发布本地流
subscribeToStreams(roomEvent.streams);//订阅所有用户
});

room.addEventListener(“stream-subscribed”,function(streamEvent) {
//订阅远程流
varstream = streamEvent.stream;
vardiv = document.createElement(‘div’);
div.setAttribute(“style”,”width: 320px; height: 240px;”);
div.setAttribute(“id”,”test” + stream.getID());

document.body.appendChild(div);
stream.play(“test”+ stream.getID());
});

room.addEventListener(“stream-added”,function (streamEvent) {
//room中有新的流加入
varstreams = [];
streams.push(streamEvent.stream);
subscribeToStreams(streams);
});

room.addEventListener(“stream-removed”,function (streamEvent) {
// Remove stream from DOM
varstream = streamEvent.stream;
if(stream.elementID !== undefined) {
varelement = document.getElementById(stream.elementID);
document.body.removeChild(element);
}
});

room.connect();
localStream.play(“myVideo”);
});

localStream.init();
};
</script>
</head>

<body>
<divid=”myVideo” style=”width:320px; height: 240px;”>
</div>
</body>
</html>

Node.js client

在你的node.js应用中使用这里介绍的API运行erizo客户端。你可以连接room，发布和订阅流，管理事件。你只需要引入erizofc.js，代码如下：
varErizo = require(‘.erizofc’);

现在你可以使用API调用Erizo.Room, Erizo.Stream 和Erizo.Events.注意你可以不订阅或不发布音视频流。

 

 

 

服务器通过Nuve API 创建聊天室，用户则通过Erizo API连接这些聊天室。Erizo Controller 用来管理聊天室，即通过Erizo API管理流文件。