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.CmConnector

摄像头麦克风连接器CmConnector,用于连接目标用户的摄像头和麦克风,当连接成功后,就可以在video控件(上述的SetViewer方法传入)上显示视频图像,并从扬声器播放对方麦克风的声音。

function CmConnector() {
    //获取视频尺寸宽度
    this.GetVideoWidth = function () {
        ...
    }
    //获取视频尺寸高度
    this.GetVideoHeight = function () {
        ...
    }
   //获取是否静音
    this.GetMute = function () {
       ...
    }
    //设置是否静音 默认false
    this.SetMute = function (isMute) {
      ...
    } 
}
  • 通过SetMute 方法来设置是否静音该连接器

3.DynamicDesktopConnector 

桌面/屏幕连接器 DynamicDesktopConnector ,同CmConnector相似,这里就不多赘述了。

四.  收发自定义消息

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

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方法,不要在中途调用它们。 

六. 部署 H5Media

1. 部署步骤

(1)启动服务端

         将 H5Media.Server 的生成目录,拷贝到服务器上,双击运行目录下的 H5Media.Server.exe 即可。

(2)启动中继服务器

         将 Coturn_RelayServer_x64.rar 拷贝到服务器上解压,修改配置文件 turnserver.conf:

          

(3)部署并运行网站

         将您开发好的网站在IIS或Nginx中部署,不过要特别注意,网站必须要配置为https的。 

2. 需要使用https和wss

      由于浏览器要求只有 https 的网站才能调用摄像头和麦克风等本地设备,所以,在服务器上部署基于H5Media开发的网站时,需要使用https(SSL证书)。

      另外,H5Media 的客户端和服务端之间是基于 WebSocket 通信的,而在https网页中,要求必须使用加密的 WebSocket ,即 wss。

      那么,如何让 H5Media 的服务端支持 wss 了?可以借助Nginx。首先以普通方式运行 H5Media 的服务端(9800端口),然后,再使用Nginx来为它加上SSL。

      Nginx 的配置类似这样: 

     #H5Media服务反向代理
      server {
         listen       9801 ssl;
         server_name  localhost;

         ssl_certificate      cert.pem;
         ssl_certificate_key  cert.key;
       
         ssl_session_cache    shared:SSL:1m;
         ssl_session_timeout  5m;

         ssl_ciphers  HIGH:!aNULL:!MD5;
         ssl_prefer_server_ciphers  on;

         location / {
           proxy_pass http://127.0.0.1:9800;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection upgrade;
           proxy_read_timeout    86400s;
           proxy_send_timeout    86400s;
         }
       } 

3. 如果服务器在内网,该如何部署服务端?

      如果是在内网,可以参考:局域网https自签名教程  ,制作得到SSL证书,可以使用 在线的SSL证书格式转换工具 ,将其转换成我们需要的格式。

      然后将SSL证书应用到网站和Nginx,这样服务器部署就OK了。

      接下来还有最后一步,就是在客户端电脑或手机上,需要增加 host 解析,比如将 test.com 解析到服务器的IP地址(如192.168.0.100)。

      比如,Windows系统,打开 C:\Windows\System32\drivers\etc 目录下的名为 hosts 的文件,在最后面加上如下语句:

      192.168.0.100  test.com 

      再保存文件即可。     

 

七. Demo及下载

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

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

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

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

 

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

Q Q:168757008

官网: www.oraycn.com

导航

首页

官方网站

联系我们

站内搜索

OrayTalk 企业即时通讯系统

傲瑞通官网

详细说明

客户端下载

OrayMeeting 视频会议系统

详细说明

客户端下载

ESFramework 通信框架

详细说明

SDK与Demo下载

ESFramework FAQ

版本变更记录

OMCS 语音视频框架

详细说明

SDK与Demo下载

OMCS FAQ

版本变更记录

OVCS 视频会议Demo

详细说明

源码下载

傲瑞实用组件

SDK下载

H5Media 纯网页音视频交互

NPusher 推流组件

MCapture 语音视频采集组件

MFile 语音视频录制组件

MPlayer 语音视频播放组件

OAUS 自动升级系统

StriveEngine 轻量级的通信引擎

傲瑞组件 FAQ

授权

授权流程

产品选购指南

授权方案说明

授权SDK使用说明

其它

支持信创国产化

SDK使用技巧

联系我们