基础功能接口

最近更新时间:2019-09-12 11:34:26

初级开发人员可以通过基础功能接口完成实时音视频基础功能接入,即可体验实时音视频主要功能。功能包括检测是否支持 WebRTC、初始化 WebRTC,创建和加入房间,退出房间。详细接口描述如下:

WebRTCAPI.fn.detectRTC

检测是否支持 WebRTC。

语法示例

WebRTCAPI.fn.detectRTC(options, callback)

参数描述

参数 类型 描述
options object 参数

options

参数 类型 是否必须 描述
screenshare boolean 是否进行屏幕分享检测,默认 true
extensionId String 屏幕分享插件 ID(Chrome 的插件唯一 ID)

回调 callback 的 info 字段

字段 含义 备注
isTBS 是否是 TBS (Android 的微信/手机 QQ Webview) 什么是 TBS
TBSversion TBS 版本号 -
isTBSValid TBS 版本号是否支持 WebRTC -
support 是否支持 WebRTC -
h264Support 是否支持 H.264 必须支持 H.264
screenshare 是否支持屏幕分享 必须安装插件

实际示例

WebRTCAPI.fn.detectRTC({
        screenshare : false
    }, function(info){
    if( !info.support ) {
        alert('不支持WebRTC')
    }
});

WebRTCAPI

初始化 WebRTC。

语法示例

var RTC = new WebRTCAPI( options )

参数描述

参数 类型 描述
options object 参数

Options 描述

参数 类型 描述 备注
sdkAppId integer 应用的 sdkAppId(详细请参见 集成 SDK 必填
userId string 用户的唯一标识,也就是我们常说的用户名(如有疑义请看 集成 SDK 必填
userSig string 必要,身份签名,相当于登录密码的作用 (如有疑义请看 集成 SDK 必填
debug object 调试模式(控制台打印日志){ log:true, uploadLog:true, vconsole:true} 非必填
peerAddNotify boolean p2p 的建连通知,在建立 p2p 连接前由业务侧决定是否需要连接。
需要结合[高级事件通知]的[onPeerConnectionAdd]使用
非必填,默认 false
  • 弃用参数 (SDK 3.0以前的版本)
    closeLocalMedia => 新的 SDK 默认不再推流
    audio,video => 不再支持配置是否进行音视频推流

实际示例

    var RTC = new WebRTCAPI( {
        "userId": userId,
        "sdkAppId":  sdkappid,
        "userSig": userSig
    } );

    //调试模式
    var RTC = new WebRTCAPI( {
        "userId": userId,
        "sdkAppId":  sdkappid,
        "userSig": userSig,
        "debug":{
            "log": true, //是否在控制台打印调试日志 ,默认为false
            "vconsole": true, //是否展示 vconsole (方便在移动端查看日志)
            "uploadLog": true //是否上报日志
        }
    } );

WebRTCAPI.getLocalStream

注意:

SDK 2.5以上版本开始支持。

获取本地音频/视频流。

参数 类型 是否必须 描述
opts Object 可以传空对象 {}
succ function 成功回调
fail function 失败回调

opts 的参数定义

参数 类型 是否必须 描述
audio Boolean 是否采集音频,默认 true
video Boolean 是否采集视频,默认 true
screen Boolean 是否采集屏幕分享 ,默认 false
screenSources string 屏幕分享采集的媒介 用半角逗号隔开, 可选选项包括 screen、window、tab 和 audio
attributes Object 推流相关配置的属性
videoDevice Device | Object 指定设备,getVideoDevices 获取的视频设备
也可以通过参数 facingMode 来指定支持区分前置/后置摄像头的设备
audioDevice Device 指定设备,getVideoDevices 获取的音频设备
needRetry Boolean 使用参数配置获取失败时,是否允许降级去掉配置重试 ,默认为 true

attributes 的参数定义

参数 类型 是否必须 描述
width Integer 分辨率宽度
height Integer 分辨率高度
frameRate Integer 帧率

succ 回调 (Object )

参数 类型 描述
stream MediaStream 音视频流 MediaStream

语法示例

    var RTC = new WebRTCAPI({ ... });
    ...

    RTC.getLocalStream({
        video:true,
        audio:true,
        attributes:{
            width:640,
            height:480,
            frameRate:20
        }
    },function( info ){
        // info { stream }
        var stream = info.stream;
        document.getElementById("localVideo").srcObject = stream
    },function ( error ){
        console.error( error )
    });


    // 通过枚举设备,并指定 VideoDevice 来指定设备
    ···
    var devices = [];
    RTC.getVideoDevices( function( ret ){
        devices = ret
    })
    ··· 
    //getVideoDevices是一个异步接口,实际开发中请注意调用 getLocalStream 的时序问题
    RTC.getLocalStream({
        video:true,
        audio:true,
        videoDevice: devices[0]
    },function( info ){
       ...
    },function ( error ){
       ...
    });


    // 通过facingMode参数指定设备
    RTC.getLocalStream({
        video:true,
        audio:true,
        videoDevice: {
            facingMode:{
                ideal:'user'  // 'environment' 表示后置摄像头  | 'user'表示前置摄像头
            }
        }
    },function( info ){
       ...
    },function ( error ){
       ...
    });

代码示例

WebRTCAPI.enterRoom

创建或进入音视频房间。

语法示例

    var RTC = new WebRTCAPI( ... )
    ...
    //注意:这里必须在 WebRTCAPI 的初始化成功的回调中调用
    RTC.enterRoom( options, succ , error );

参数描述

参数 类型 是否必须 描述
options object 参数
succ function 成功回调
error function 失败回调

Options 描述

参数 类型 是否必须 描述
roomid integer 房间 ID,数据类型为 uint32
privateMapKey string 如果业务认为无需限制用户的权限,可以不带,相当于进入指定房间 roomID 的钥匙 (如有疑义请看 集成 SDK
pureAudioPushMod integer 纯音频推流模式,需要旁路直播和录制时需要带上此参数
1表示本次是纯音频推流,不需要录制 MP3 文件
2表示本次是纯音频推流,录制文件为 MP3
recordId integer 自动录制时业务自定义 ID,int32,将在录制完成后通过直播录制回调接口通知业务方(控制台 - 直播录制回调),相关文档:直播录制文件获取事件消息通知
注意:如果小程序与小程序或者小程序与 Web 端互通,且传了 recordId,必须保证 Web 端和小程序传递的值一致
appScene string 应用场景,VideoCall表示实时通话模式,Live表示互动直播模式
role string 角色名 ,角色决定了服务器接收该视频流的码率控制。当设置了 appScene 参数时,role 值可设置为:anchor主播; audience观众; 若 appScene/role 都不设置,默认是实时通话主播角色; 当 appScene 设置为Live且 role 设置为audience,即互动直播模式下的观众角色,只允许接收远端音视频流,不允许发布本地音视频流。
注意:

  • role 告诉了后台当前流的码率范围,请到控制台配置一个合适的码率。
  • role 可以在 enterRoom 的时候带,也可以在 startRTC 的时候带,建议在进房的时候带会更快。
  • privateMapKey 并不影响业务开发,如果暂时不用考虑对用户的权限控制,您可以忽略这部分内容。

实际示例

var RTC = new WebRTCAPI({
    "userId": "username",
    "sdkAppId":  1400012345,
    "userSig": "xxxxxxxxxxxxxxxxxxxxxxxxx",
});

RTC.enterRoom( {
    roomid : 123456,
    role: 'user'
    // privateMapKey: "xxxxxxxxxxxxx" //不必须
}, function(){
    //进房房间成功
} ,  function(data){
    //进入房间失败
} );

WebRTCAPI.startRTC

主动发起推流/拉流。

参数

参数 类型 是否必须 描述
opt object -
succ function 成功回调
fail function 失败回调

opts 的参数定义

参数 类型 是否必须 描述
stream MediaStream 音视频流 MediaStream
role string 角色名 ,角色决定了服务器接收该视频流的码率控制

语法示例

    var RTC = new WebRTCAPI({ ... });
    ...

    RTC.startRTC({
        role: 'user',
        stream: stream
    }, function(){
        //成功
    },function(){
        //失败
    });

WebRTCAPI.stopRTC

停止推流。

参数 类型 描述
opt object 预留字段,传空对象
succ function 成功回调
fail function 失败回调

语法示例

    var RTC = new WebRTCAPI({ ... });
    ...
    RTC.stopRTC({}, function(){
        console.debug('stop succ')
    }, function(){
        console.debug('stop end')
    });

WebRTCAPI.quit

退出音视频房间。

语法示例

    var RTC = new WebRTCAPI( ... )
    ...
    //注意:这里必须在 WebRTCAPI 的初始化成功的回调中调用
    RTC.quit(  succ , error );

参数描述

参数 类型 描述 备注
succ function 成功回调 非必填
error function 失败回调 非必填

实际示例

    var RTC = new WebRTCAPI( ... )
    ...
    //注意:这里必须在 WebRTCAPI 的初始化成功的回调中调用
    RTC.quit(  function(){
        //退出成功
    } , function(){
        //退出失败
    } );