OMCS 开发手册之 Web SDK 说明(JavaScript)
(OMCS Web SDK 支持 Windows 和 Linux ,并支持所有类型的浏览器,目前OMCS Web版本提供的功能有:语音、视频、远程桌面、电子白板。)
如果您已经了解了OMCS语音视频框架 PC版本的使用方法,那么上手Web版本的SDK是非常简单的。在本文中,我们将Web SDK中重要的API列出来加以说明,很多重复性的内容就不再一一赘述了。
由于Web 的一些权限问题,我们最终采取服务插件的模式来实现对本地语音视频设备的调用,Web SDK与本地的OMCS视频服务Web插件(以托盘运行)进行通信,OMCS视频服务Web插件则与OMCS Server 服务端交互,这样一来插件就起到了一个桥梁的作用,完成Web 端与 OMCS服务端的互通。
一. 多媒体管理器:MultimediaManager类
多媒体管理器用于管理本地的多媒体设备,包括:摄像头、麦克风、桌面、电子白板。
在Web客户端中以单例模式提供,可以通过MultimediaManagerFactory类的静态方法GetSingleton()获取该单例的引用
function MultimediaManager() { //与OMCS服务器建立连接,并初始化本地多媒体管理器。 this.Initialize = function (userID, password, serverIP, serverPort) { ... } //设置是否记录安全日志(多媒体管理器的在线状态、每次连接他人设备的连接器状态)。默认值为false。 this.SetSecurityLogEnabled = function (value) { ... }
//[从Owner的角度]Owner发送帧数据给Guest时,通道的选择模型。默认值为P2PChannelFirst。必须在初始化前设置才有效。 P2PDisabled:0 ;P2PChannelFirst:1 this.SetChannelMode = function (value) { ... }
//设置是否开启自动重连,默认false 必须Initialize之前设置才有效果 this.SetAutoReconnect = function (value) { ... } //获取连接状态(是否连接成功) this.Connected = function () { ... } //从OMCS服务器退出登录,并断开与OMCS服务器的连接。 this.Dispose = function () { ... }
//刚刚从麦克风或自定义声音采集器采集的音频帧(20ms的PCM数据)。 需客户端注入回调 this.AudioCaptured = null; //当与目标媒体服务器的连接断开时,触发此事件。事件参数:目标多媒体服务器的地址。 需客户端注入回调 this.ConnectionInterrupted = null; //当与目标媒体服务器重连成功时,触发此事件。事件参数:目标多媒体服务器的地址。 需客户端注入回调 this.ConnectionRebuildSucceed = null; }
- 其中最重要的方法 Initialize(userID, password, serverIP, serverPort) 用于与多媒体服务器建立连接,并初始化本地多媒体管理器。
- 与服务器的连接状态通过ConnectionInterrupted、ConnectionRebuildSucceed 回调方法注入到管理器中,可以监听与服务器TCP连接的状态。
1.摄像头
IMultimediaManager接口中与摄像头设置相关的方法如下:
// 要使用的摄像头的索引。默认值为0。如果不想使用摄像头,可以设置为-1。可以在运行时动态修改 this.SetCameraDeviceIndex = function (value) { ... } //设置摄像头采集视频的宽度与高度 this.SetCameraVideoSize = function (width,height) { ... } //摄像头的最大帧频。默认值:10。(必须在调用Initialize方法之前设置才有效。) this.SetMaxCameraFrameRate = function (value) { ... } //摄像头采集的视频的编码质量。取值0~31,默认值10。取值越小,质量越高。可以在运行时动态修改。 经验:建议取值大于5,当小于5时,带宽占用将数倍增加,而图像质量提升并不太明显。 this.SetCameraEncodeQuality = function (value) { ... } //是否将摄像头集到的视频输出给Guest。 默认值为true。(必须在初始化完成之后设置才有效,可动态修改。) 如果为true,表示输出;否则,表示将采集到的视频数据丢弃,不发送给guest。默认值为true。 this.SetOutputVideo = function (value) { ... }
- SetCameraVideoSize方法设置要采集摄像头的分辨率,默认为640*480。
- SetOutputVideo方法用于控制是否将摄像头的图像发送给guest,默认为true。
2.麦克风
//要使用的麦克风的索引。如果设置为-1,则表示使用采集声卡得到的声音(win7及以上系统)。该属性的值可以在运行时动态修改。 this.SetMicrophoneDeviceIndex = function (value) { ... } //是否将话筒采集到的音频输出给Guest。(必须在初始化完成之后设置才有效,可动态修改。) 如果为true,表示输出;否则,表示将采集到的音频数据丢弃,不发送给guest。默认值为true。(比如在视频会议中,只将发言人的OutputAudio设为true,以减少带宽和避免杂音) this.SetOutputAudio = function (value) { ... }
- SetOutputAudio方法用于控制是否将摄像头的图像发送给guest,默认为true。
3.远程桌面
//要使用的桌面屏幕的索引。默认值:0。 this.SetDesktopIndex = function (index) { ... } //输出桌面分辨率的缩小系数。默认值:1。取值范围:大于等于0.1且小于等于1。 this.SetDesktopZoomCoef = function (value) { ... } // 是否将桌面图像输出给Guest。默认值为true。(必须在初始化完成之后设置才有效,可动态修改。) this.SetOutputDesktop = function (value) { ... } //本地桌面的编码质量。取值0~31,默认值10。取值越小,越清晰。可以在运行时动态修改。 this.SetDesktopEncodeQuality = function (value) { ... } //设置要捕捉的屏幕的区域。 默认为null,则表示捕捉整个屏幕。可以在运行时动态修改。【桌面采集器会将长和宽修正为8的整数倍】 this.SetDesktopRegion = function (x, y, width, height) { ... }
- SetDesktopRegion 方法用于控制是采取屏幕的的区域矩形,以屏幕左上角为原点(0,0),默认为全屏
4.群视频
//群聊动态组,加入群聊成功后可以获取该值 this.ChatGroup = null;
//加入群聊 this.JoinChatGroup = function (groupID,callback) { ... } //退出群聊 this.ExitChatGroup = function (groupID) { ... } //当群组有人加入时触发 参数为 memberID 需客户端注入回调 this.ChatGroupSomeoneJoin = null; //当群组有人退出时触发 参数为 memberID 需客户端注入回调 this.ChatGroupSomeoneExit = null;
- JoinChatGroup方法 加入到指定的群聊中,ExitChatGroup 退出群聊。
- ChatGroupSomeoneJoin、ChatGroupSomeoneExit 为群聊组中人员变化时会触发,可以设置回调在客户端具体处理该事件。
二. 多媒体连接器
当自己作为Guest,需要访问Owner的摄像头等设备时,就需要使用多媒体连接器,包括:摄像头连接器、麦克风连接器、桌面连接器、白板连接器。
1.DynamicCameraConnector
function DynamicCameraConnector() { //当接收到来自Owner的新的一帧图像时,触发此事件。base64信息 this.NewFrameReceived = null; //当与目标设备的连接断开时,触发该事件。 this.Disconnected = null; //当连接对方设备的尝试结束时,触发此事件。事件参数说明了连接的结果。 this.ConnectEnded = null; // 在AutoReconnect为true的情况下,当开始自动重连目标多媒体设备时,触发该事件。 this.AutoReconnectStart = null; //在AutoReconnect为true的情况下,当自动重连目标多媒体设备失败时,触发该事件。 this.AutoReconnectFailed = null; //在AutoReconnect为true的情况下,当自动重连目标多媒体设备成功时,触发该事件。 this.AutoReconnectSucceed = null; //获取是否自动重连 this.GetAutoReconnect = function () { ... } //获取视频尺寸宽度 this.GetVideoWidth = function () { ... } //获取视频尺寸高度 this.GetVideoHeight = function () { ... } //Owner是否输出了视频。【对应于Owner端的多媒体管理器的OutputVideo属性】 this.GetOwnerOutput = function () { ... } //与目标设备是否已连接? this.GetConnected = function () { ... } //获取设备主人的UserID。 this.GetOwnerID = function () { ... } //设置界面要显示的控件 this.SetViewer = function (viewer) { ... } //设置是否在视频图像上面打印视频的相关信息(视频尺寸、编码质量、帧频)。默认值:false。 this.SetDisplayVideoParameters = function (value) { ... } //设置是否自动重连,默认false this.SetAutoReconnect = function (value) { ... } // 尝试连接目标多媒体设备。 this.BeginConnect = function (destUserID) { ... } //与目标设备断开连接,并释放通道。 this.Disconnect = function () { ... } }
- 调用BeginConnect 方法,以尝试连接目标用户Owner的设置,框架会将回调ConnectEnded来通知连接的结果。(MicrophoneConnector、DynamicDesktopConnector、DynamicWhiteBoardConnector 都同理)
- 在AutoReconnect 为 true的情况下,AutoReconnectStart 、AutoReconnectFailed 、AutoReconnectSucceed 为自动重连的相关事件,只需注入对应的回调即可。(MicrophoneConnector、DynamicDesktopConnector、DynamicWhiteBoardConnector 都同理)
- SetViewer 方法用于设置要显示的控件,一般为canvas标签控件,它会将收到图像绘制到该控件上。如果想开启GPU解码渲染模式,则需要使用video控件。注:如果连接的对象是自己,则仍然需要使用canvas控件(因为看自己时使用的是原始图像)。
2.MicrophoneConnector
与DynamicCameraConnector相似,就不多赘述了,主要提到以下不同点
//获取是否静音 this.GetMute = function () { ... } //设置是否静音 默认false this.SetMute = function (isMute) { ... }
- 通过SetMute 方法来设置是否静音该连接器
3.DynamicDesktopConnector
同样DynamicCameraConnector相似,但它不仅是可以观看Owner端的屏幕,并可进行操作。(远程桌面、远程协助)
//是否仅仅允许查看远程桌面,但是不能进行操作。 默认值为true。注意:该属性用于guest端控制,前提是Owner端的AllowControl必须为true,才有效;否则,即使WatchingOnly为false,仍然不能操作桌面。 this.SetWatchingOnly = function (value) { ... } //是否在远程桌面上显示Owner的鼠标光标。默认值为true。 this.SetShowMouseCursor = function (value) { ... }
- SetWatchingOnly方法来控制是否可以操作Owner端的桌面。
- SetShowMouseCursor 用于设置是否显示Owner端的鼠标光标,前提是WatchingOnly为true时,该属性设置才有效。
- SetViewer 方法用于设置要显示的控件,一般为canvas标签控件,它会将收到的图像绘制到该控件上。如果想开启GPU解码渲染模式,则需要使用video控件。注:如果连接的对象是自己,则仍然需要使用canvas控件(因为看自己时使用的是原始图像)。
- 对于DynamicDesktopConnector 而言,当使用canvas或video控件进行渲染时,如果没有设置控件的宽高,则将以原始尺寸进行渲染;如果设置了控件的宽高,则当使用canvas控件进行渲染时,将以铺满控件的形式进行渲染,而当使用video控件时,将以等比缩放的形式进行渲染。注:由于使用canvas控件的宽高默认值分别为300和150,所以如果使用canvas控件并且设置canvas的宽高分别为300和150,则仍然会以原始尺寸进行渲染。
4.DynamicWhiteBoardConnector
通过DynamicWhiteBoardConnector连接到电子白板,观看并操作白板上的内容。
//是否仅仅允许查看画板,但是不能进行操作。 默认值为false。 this.SetWatchingOnly = function (value) { ... }
三. 语音消息
通过MultimediaManager提供的下列方法,可以:开始采集语音消息,停止采集(通过回调返回采集的语音消息)、播放语音消息、停止播放语音消息。
//开始采集语音消息 this.StartCaptureAudio = function () { . . . }; //停止采集语音消息。 采集到的AudioMessage将通过backCall回调通知 this.StopCaptureAudio = async function (backCall) { . . . }; //开发播放语音消息 this.PlayAudio = function (audioMessage) { . . . }; //停止播放语音消息 this.StopPlayAudio = function () { . . . };
四. JS与插件之间收发扩展消息
OMCS Web 插件的源码是可以下载并进行二次开发的。
我们可以在JS与本地的OMCS Web插件之间传送自定义的扩展消息。
1. JS 发消息给插件
JS 可以调用 MultimediaManager 的sendMessage 方法发送扩展消息给插件,注意:消息号 messageType 必须要大于 1000 。
this.sendMessage = function (messageType, msg) ...
在插件端,可以通过预定 IOmcsService4Web 的 JsMessageReceived 事件,拿到JS发过来的扩展消息。
/// <summary> /// 当通过WebSocket通道收到来自JS的消息时,触发此事件。消息类型msgType >= 1000 /// </summary> event CbGeneric<int, string> JsMessageReceived;
2. 插件发消息给 JS
在插件端,可以调用 IOmcsService4Web 的 SendMessageToJs 发送扩展消息给 JS。
/// <summary> /// 通过WebSocket通道发送消息给JS。消息类型msgType >= 1000 /// </summary> void SendMessageToJs(int msgType, string msg);
在JS端,若要接收来自插件的扩展消息,则需先调用 MultimediaManager 的 SetAddinMessageReceivedCallback 方法注入回调:
//收到插件发来的扩展消息回调 参数:messageType, msg this.OnReceiveAddinMessageCallback = null; //设置收到插件发来的扩展消息回调 this.SetAddinMessageReceivedCallback = function (callback) { self.OnReceiveAddinMessageCallback = callback; };
如此,当收到插件的扩展消息时,框架就会回调注入的 OnReceiveAddinMessageCallback 。
五. 关于 OMCS Web插件
在网页中运行OMCS Web版的前提是:在当前电脑上已经安装并运行了 OMCS视频服务Web插件,OMCS入门Demo Web版 文末将提供该插件的安装包下载。
OMCS视频服务Web插件运行时,将使用一个TCP端口为OMCS Web SDK提供服务, 默认使用端口 9910。
正如在接下来的demo中演示的那样,当第一次加载网页时,将会尝试启动Web插件,若启动失败,将提示下载并安装Web插件。
当Web插件安装完成并运行起来,再次刷新页面,即可正常使用OMCS Web 版功能了。
注:当安装Web插件时,若提示类似“没有足够的权限写入注册表项 . . .”错误时,一般是被360或电脑管家等安全软件拦截了,关掉此类软件后再重新安装即可。
六. 如何使用OMCS Web SDK
1. 一台电脑只能登录一个 OMCS Web 客户端。
也就是说,一台电脑上只能有一个Web页面正常使用 OMCS Web 端。如果多个页面都登录OMCS Web 客户端,则只有最后那个才有效。
2. 当js调用MultimediaManagerFactory类的静态方法GetSingleton()获取MultimediaManager实例时,其内部会自动WebSocket连接本机的Web插件。
如果连接Web插件失败,则可能有两种原因:Web插件尚未安装,或者是已经安装但是尚未运行。
而在js的层面,并不能确定究竟是哪种情况导致的连接插件失败。所以,web页面可以提示用户去下载插件安装,或者是启动已经安装好的插件。
3. 当连接Web插件成功后,才可以调用 MultimediaManager的 Initialize 方法登录到 OMCS服务器。
登录 OMCS服务器成功后, 就可以正常使用 OMCS Web 端的功能了。
4. 当使用完后,可调用MultimediaManager的 Dispose方法,就会从OMCS服务器退出。
注意:此时,当前页面到本机插件的WebSocket连接还是继续保持的。
如果之后当前页面又要使用MultimediaManager,可以重新调用 Initialize 方法登录到OMCS服务器。
建议:最简易和最安全的做法是,只有在页面加载时调用 Initialize 方法,和页面关闭时才调用Dispose方法,不要在中途调用它们。
5. 当前页面关掉时,之前保持的到本机插件的WebSocket连接就会释放。
6. 如果有个页面正在正常使用OMCS Web 端,只要一个新的页面调用了 MultimediaManager的 Initialize 方法,就会把之前的页面中OMCS Web 端挤掉。
七. Demo及下载
我们为 OMCS入门Demo 增加了Web端,详细介绍以及相关下载请参见:OMCS Demo -- 入门Demo Web 版
上一篇:OMCS 开发手册(11) -- 深入摄像头、麦克风、扬声器
--------------------------------------------------------------------------------------------------------------------
阅读 更多OMCS开发手册系列文章 。
Q Q:168757008
官网: www.oraycn.com