OMCS 开发手册之 Web SDK 说明（JavaScript）

　　如果您已经了解了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 版