H5Media 开发手册

H5Media 是一套基于H5的跨平台实时音视频SDK，基于H5Media开发的应用，同一套代码便可运行在所有平台及浏览器上，并支持嵌入到手机原生APP和PC桌面应用中。

H5Media SDK 支持 Windows，Linux，Android，iOS ，以及国产OS上所有主流的浏览器，支持H5。目前H5Media 提供的功能有：语音、视频、远程桌面。

H5Media 包含了服务端 API（C#）和客户端 API（JavaScript）。

关于H5Media的Demo及功能演示请参见：H5Media 入门Demo -- 语音、视频、桌面基础功能演示

一. H5Media 服务端

调用 H5Media.Server.MultimediaServerFactory 类的 CreateMultimediaServer 方法，就可以创建 H5Media 服务器实例。

        /// <summary>
        /// 创建H5Media服务器实例。
        /// </summary>
        /// <param name="port">监听的端口。</param>
        /// <param name="userVerifier">用户帐密验证器。</param>  
        /// <param name="wssOption">如果需要使用WSS，则可以通过该参数传入SSL证书信息</param>
        /// <returns>H5Media服务器</returns>        
        public static IMultimediaServer CreateMultimediaServer(int port, IUserVerifier userVerifier, WssOption wssOption = null)

H5Media 服务器实例创建成功后，服务端即开始正常运行。我们已经提供了一个默认的服务端可执行程序，其运行界面如下所示：

通过返回的 IMultimediaServer 接口，我们可以与 H5Media 服务器实例进行交互。以下是 IMultimediaServer 接口的定义：

     /// <summary>
    /// H5Media服务器。
    /// </summary> 
    public interface IMultimediaServer
    {
        /// <summary>
        /// 关闭H5Media多媒体服务器。
        /// </summary>
        void Close();

        /// <summary>
        /// 获取在线用户的ID列表。
        /// </summary>     
        List<string> GetOnlineUserList();

        /// <summary>
        /// 目标用户是否在线。
        /// </summary>   
        bool IsUserOnLine(string userID);
        
        /// <summary>
        /// 当前服务器所监听的端口。
        /// </summary>
        int Port { get; }

        /// <summary>
        /// 当前在线用户的数量。
        /// </summary>
        int UserCount { get; }         

        /// <summary>
        /// 客户端连接到服务器时，将触发此事件。
        /// </summary>
        event CbGeneric<string> UserConnected;        

        /// <summary>
        /// 客户端连接断开时，将触发此事件。
        /// </summary>
        event CbGeneric<string> UserDisconnected;          

        /// <summary>
        /// 当某人加入聊天组时，触发此事件。参数：ChatType - UserID - GroupID
        /// </summary>
        event CbGeneric<string, string> SomeoneJoinChatGroup;

        /// <summary>
        /// 当某人离开聊天组时，触发此事件。参数：ChatType - UserID - GroupID
        /// </summary>
        event CbGeneric<string, string> SomeoneQuitChatGroup;      

        /// <summary>
        /// 当收到来自客户端的自定义消息时，触发此事件。参数：string srcUserID, int msgType, byte[] msg, string tag。       
        /// </summary>
        event CbGeneric<string, int, byte[], string> CustomizedMessageReceived;

        /// <summary>
        /// 向在线用户发送自定义消息。
        /// </summary>          
        void SendCustomizedMessage(string targetUserID, int msgType, byte[] msg, string tag);       

        /// <summary>
        /// 获取多人语音/视频组的成员。注意：返回的集合不可被修改。
        /// </summary>        
        List<string> GetMultiChatMembers(string groupID);       
    }

在H5Media服务端，通过 IMultimediaServer 接口，我们可以得到用户的上下线通知，以及加入、退出音视频群组的通知。

并且，在服务端可以通过SendCustomizedMessage 方法主动给某个在线的用户发送自定义消息。而当收到来自某个客户端的自定义消息时，将触发CustomizedMessageReceived 事件。

H5Media 的服务端相当简单，接下来我们看看 H5Media 的客户端相关的内容。

二. 多媒体管理器：MultimediaManager类

多媒体管理器是 H5Media 客户端的核心，用于管理本地的多媒体设备，包括：摄像头、麦克风、桌面。

　　在Web客户端中以单例模式提供，可以通过MultimediaManagerFactory类的静态方法GetSingleton()获取该单例的引用

function MultimediaManager() {

　　 //与多媒体服务器建立连接，并初始化本地多媒体管理器。 
    this.Initialize = function (userID, password, serverIP, serverPort, iceServers, _loginResultCallBack) {
        ...
    }

　　 //设置是否开启自动重连,默认false  必须Initialize之前设置才有效果
    this.SetAutoReconnect = function (value) {
        ...
    }
    
    //获取连接状态（是否连接成功）
    this.Connected = function () {
        ...
    }
    
    //从多媒体服务器退出登录，并断开与多媒体服务器的连接。 
    this.Dispose = function () {
        ...
    }    

    //当与目标媒体服务器的连接断开时，触发此事件。事件参数：目标多媒体服务器的地址。 需客户端注入回调
    this.ConnectionInterrupted = null;

    //当与目标媒体服务器重连成功时，触发此事件。事件参数：目标多媒体服务器的地址。 需客户端注入回调
    this.ConnectionRebuildSucceed = null;

}

其中最重要的方法 Initialize(userID, password, serverIP, serverPort, iceServers, _loginResultCallBack) 用于与多媒体服务器建立连接，并初始化本地多媒体管理器。
与服务器的连接状态通过ConnectionInterrupted、ConnectionRebuildSucceed 回调方法注入到管理器中，可以监听与服务器TCP连接的状态。

1.摄像头

IMultimediaManager接口中与摄像头设置相关的方法如下：

    // 要使用的摄像头的索引。默认值为0。
    this.SetCameraDeviceIndex = function (value) {
        ...
    }
    
    //设置摄像头采集视频的宽度与高度 
    this.SetCameraVideoSize = function (width,height) {
        ...
    }
    
    //摄像头的最大帧频。默认值：15。（必须在调用Initialize方法之前设置才有效。）
    this.SetMaxCameraFrameRate = function (value) {
        ...
    }
    //摄像头采集的视频的编码质量。取值0~31，默认值18。取值越小，质量越高。经验：建议取值大于5，当小于5时，带宽占用将数倍增加，而图像质量提升并不太明显。
    this.SetCameraEncodeQuality = function (value) {
        ...
    }
    
    //是否将摄像头集到的视频输出给Guest。 默认值为true。（必须在初始化完成之后设置才有效，可动态修改）。
    this.SetOutputVideo = function (value) {
        ...
    }

SetCameraVideoSize方法设置要采集摄像头的分辨率，默认为640*480。
SetOutputVideo方法用于控制是否将摄像头的图像发送给guest，默认为true。

2.麦克风　

    //要使用的麦克风的索引。默认值为0。
    this.SetMicrophoneDeviceIndex = function (value) {
        ...
    }
    
    //是否将话筒采集到的音频输出给Guest。必须在初始化完成之后设置才有效，可动态修改。（比如在视频会议中，只将发言人的OutputAudio设为true，以减少带宽和避免杂音）
    this.SetOutputAudio = function (value) {
        ...
    }

SetOutputAudio方法用于控制是否将摄像头的图像发送给guest，默认为true。

3.远程桌面


    // 是否将桌面图像输出给Guest。默认值为true。（必须在初始化完成之后设置才有效，可动态修改。）
    this.SetOutputDesktop = function (value) {
        ...
    }
    
    //本地桌面的编码质量。取值0~31，默认值18。取值越小，越清晰。
    this.SetDesktopEncodeQuality = function (value) {
        ...
    }

4.群视频　

    //群聊动态组（只需要同时存在一个）
    this.ChatGroupEntrance = null;   
   
　　//加入群聊
    this.JoinChatGroup = function (groupID,chatType,callback) {
        ...
    }

    //退出群聊
    this.ExitChatGroup = function (groupID,chatType) {
        ...
    }

JoinChatGroup方法加入到指定的群聊中，ExitChatGroup 退出群聊。

三. 多媒体连接器

在客户端，当自己作为Guest，需要访问某个Owner的摄像头等设备时，就需要使用多媒体连接器，连接器分为：摄像头连接器、麦克风连接器、桌面连接器。

当Guest使用连接器连接Owner的设备成功后，就可以通过该连接器看到/听到Owner了。

比如，当A使用摄像头连接器连接B的摄像头成功后，摄像头连接器就会渲染出B的视频图像了。如果，B也需要看到A的视频，那么B也使用一个摄像头连接器去连接A即可。

所有的连接器都是从 MultimediaConnector 继承。

1.MultimediaConnector

function MultimediaConnector() {

    //当与目标设备的连接断开时，触发该事件。
    this.Disconnected = null;

    //当连接对方设备的尝试结束时，触发此事件。事件参数说明了连接的结果。
    this.ConnectEnded = null;
    
    //Owner是否输出。
    this.GetOwnerOutput = function () {
        ...
    }
    
    //与目标设备是否已连接？
    this.GetConnected = function () {
        ...
    }
    
    //获取设备主人的UserID。
    this.GetOwnerID = function () {
        ...
    }    
    
    //设置界面要显示的控件
    this.SetViewer = function (viewer) {
        ...
    }
    
    // 尝试连接目标多媒体设备。
    this.BeginConnect = function (destUserID) {
        ...
    }
    
    //与目标设备断开连接，并释放通道。
    this.Disconnect = function () {
        ...
    }
 
}

调用BeginConnect 方法，以尝试连接目标用户Owner的设置，框架会将回调ConnectEnded来通知连接的结果。
SetViewer 方法用于设置要显示的控件，必须为video标签控件。

2.DynamicCameraConnector

function DynamicCameraConnector() {

    //获取视频尺寸宽度
    this.GetVideoWidth = function () {
        ...
    }
    //获取视频尺寸高度
    this.GetVideoHeight = function () {
        ...
    } 
}

3.MicrophoneConnector

    //获取是否静音 
    this.GetMute = function () {
        ...
    }
    
    //设置是否静音 默认false
    this.SetMute = function (isMute) {
　　　　...
    }

通过SetMute 方法来设置是否静音该连接器

4.DynamicDesktopConnector

　　同样DynamicCameraConnector相似，这里就不多赘述了。

四. 收发自定义消息

在客户端，我们可以发送自定义消息给服务器或其它在线用户。

1. JS 发自定义消息给其他用户或服务端

JS 可以调用 MultimediaManager 的sendCustomMessage 方法发送自定义消息给其他用户或服务端。

        this.sendCustomMessage = function (targetUserID, messageType, msg, tag)  ...

2. 收到其他用户或服务端发来的自定义消息

若要接收来自其他用户或服务端的自定义消息，则需先调用 MultimediaManager 的 SetCustomMessageReceivedCallback 方法注入回调：

    //收到其他用户或服务端发来的自定义消息回调    参数: targetUserID: null表示向服务端发送，msgType：消息类型, msg：二进制的消息体, tag：字符串类型的附加信息  
    this.OnReceiveCustomMessageCallback = null; 

    //设置收到其他用户或服务端发来的自定义消息回调
    this.SetCustomMessageReceivedCallback = function (callback) {
        self.OnReceiveCustomMessageCallback = callback;
    };

如此，当收到其他用户或服务端的自定义消息时，框架就会回调注入的 OnReceiveCustomMessageCallback 。

五. 如何使用 H5Media SDK

1. 一台电脑可以登录一个或多个 H5Media 客户端。

2. 通过调用MultimediaManagerFactory类的静态方法GetSingleton()获取到MultimediaManager实例后，调用 MultimediaManager的 Initialize 方法登录到服务器。

登录服务器成功后，就可以正常使用 H5Media 客户端的功能了。

3. 当使用完后，可调用MultimediaManager的 Dispose方法，就会从H5Media 服务器退出。

建议：最简易和最安全的做法是，只有在页面加载时调用 Initialize 方法，和页面关闭时才调用Dispose方法，不要在中途调用它们。

六. Demo及下载

关于H5Media的Demo介绍请参见：H5Media 入门Demo -- 语音、视频、桌面基础功能演示

我们已经部署好了测试服务器，以方便测试。

PC Web 测试网址： https://h5rtc.oraycn.com:544

手机 Web 测试网址： https://h5rtc.oraycn.com:543

--------------------------------------------------------------------------------------------------------------------

Q Q：168757008

官网： www.oraycn.com