Web SDK音视频API文档

0.1 登录监听

登录监听主要是对初始化sdk的参数进行验，并与服务端建立连接 事件监听，建议在初始化sdk后做监听

0.1.1 登录成功

rtc.on('login_success', function (data) {
    // 登录成功
    console.log(data,'login_success');
});

返回 data 部分数据格式如下

{

     result:"OK",
     data:{

            "desc": "9DC1A878A164F696",   //房间描述

            "talker_bitrate": 200,      //学生推流码率

            "publisher_bitrate": 200,    //老师推流码率

           "live": {
                  "id": 1231,   // 直播id
                  "status": 0,   // 1为开始
                  "last": "2000" // 如果status为1，则last为直播持续时长，单位毫秒
                "startTime":"1503908480000"  //直播开始时间戳
            }

            "max_streams": 6,   //允许最大视频流数

            "name": "ha",      //用户昵称

            "result": "OK",

            "user": {

                 "id": "6e373a456cd04b45b00f7b97986a45fc",   //用户唯一id

                 "name": "123123123",   //用户name

                 "role": "talker",    //'talker'学生   'presenter'老师

                 "roomid": "EC05E15A770D84AC9C33DC5901307461", // 房间id

            },

            "video_mode": 1,   // 视频模式1为音视频模式  ， 2为仅音频模式

            "is_follow": '',  // 默认为空，如果是跟随模式，则为流id

            "max_users": 1, // 最大支持连麦人数

            "allow_chat": true  // 是否允许发言，默认为True, 房间级配置

            "allow_audio": true   // 是否允许麦克风 默认为True, 房间级配置

            "allow_speak": true  // 是否允许上麦，默认为True 房间级配置

            "rtspurl": "" //第三方推流地址
        }
    }

0.1.2 登录失败

初始化sdk验证失败

 rtc.on('login_failed', function (err) {
     // 登录失败
     console.error('登录失败',err);
 });


 err会返回失败原因

0.2 加入流房间监听

加入流房间是准备视频流环境，满足用户推拉流需要

0.2.1 加入房间成功

加入房间成功，标志着视频流服务已准备完成

rtc.on('conference_join', function (streams) {
    // 返回值为房间内已存在的流，sdk中已通知应用层订阅
    console.log('conference_join', streams);
});

0.2.2 加入房间失败

加入房间失败，视频流服务准备出错

rtc.on('conference_join_failed', function (err) {
    // 加入房间失败  err为错误原因
    console.log('加入房间失败',err);
});

1.1 本地流相关方法

1.1.1 创建本地流

rtc.createLocalStream(object);

参数说明：

object:为创建本地流参数对象，包含以下属性
* （必选）streamName 创建本地流名称，数据类型（String），可选参数值为 'main'、'assist'、'picture'
    此参数为区分多条本地流操作，如果本地只创建一条流，就使用'main'

* （可选）showVoice 音量值回调
object.showVoice = function(value){
    // value值范围（0-100）
}

* （可选） createData 选用特定音视频设备创建本地流，数据类型（object），不选该参数，系统自动识别设备
object.createData = {
        video:{
            device: 'camera',         //固定配置，使用摄像头
            resolution: 'hd720p',     //分辨率  'unspecified'、'sif'、'vga'、'hd720p'、'hd1080p'
            deviceId: 'xxxxxxxxxx'    
        }, //如果video：false ，则表示不开启视频
        audio: {
             deviceId: 'xxxxxxxxxx'
        }     //是否创建音频，可直接传入对象，参数为设备ID，也可以直接传入布尔值true/false 表示是否创建音频
    }

* （必选）success 成功回调
object.success = function(stream){
    // 返回值为创建的本地流对象
    stream.show(id);  // 将本地流显示在元素id值为id的盒子中
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.createLocalStream({
    streamName: 'main',
    showVoice: function(value){
        // value值范围（0-100）

    },
    success: function(stream){
        stream.show('id');  // 将本地流显示在元素id值为id的盒子中
    },
    fail: function(str){
        console.log(str);
    }
});

1.1.2 关闭本地流声音

rtc.pauseAudio(object);

参数说明：

object:为对象，包含以下属性
* （必选）streamName 本地流名称，数据类型（String），可选参数值为 'main'、'assist'、'picture'
    此参数为区分多条本地流操作，如果本地只创建一条流，就使用'main'

* （可选）success 成功回调
object.success = function(){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.pauseAudio({
    streamName: 'main',
    success: function(){

    },
    fail: function(str){
        console.log(str);
    }
});

1.1.3 开启本地流声音

rtc.playAudio(object);

参数说明：

object:为对象，包含以下属性
* （必选）streamName 本地流名称，数据类型（String），可选参数值为 'main'、'assist'、'picture'
    此参数为区分多条本地流操作，如果本地只创建一条流，就使用'main'

* （可选）success 成功回调
object.success = function(){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.playAudio({
    streamName: 'main',
    success: function(){

    },
    fail: function(str){
        console.log(str);
    }
});

1.1.4 关闭本地流视频画面

rtc.pauseVideo(object);

参数说明：

object:为对象，包含以下属性
* （必选）streamName 本地流名称，数据类型（String），可选参数值为 'main'、'assist'、'picture'
    此参数为区分多条本地流操作，如果本地只创建一条流，就使用'main'

* （可选）success 成功回调
object.success = function(){

}


* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.pauseVideo({
    streamName: 'main',
    success: function(){

    },
    fail: function(str){
        console.log(str);
    }
});

1.1.5 开启本地流视频画面

rtc.playVideo(object);

参数说明：

object:为对象，包含以下属性
* （必选）streamName 本地流名称，数据类型（String），可选参数值为 'main'、'assist'、'picture'
    此参数为区分多条本地流操作，如果本地只创建一条流，就使用'main'

* （可选）success 成功回调
object.success = function(){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.playVideo({
    streamName: 'main',
    success: function(){

    },
    fail: function(str){
        console.log(str);
    }
});

1.1.6 结束本地流

rtc.closeVideo(object);

参数说明：

object:为对象，包含以下属性
* （必选）streamName 本地流名称，数据类型（String），可选参数值为 'main'、'assist'、'picture'
    此参数为区分多条本地流操作，如果本地只创建一条流，就使用'main'

* （可选）success 成功回调
object.success = function(){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.closeVideo({
    streamName: 'main',
    success: function(){

    },
    fail: function(str){
        console.log(str);
    }
});

1.1.7 推送本地流

rtc.publish(object);

参数说明：

object:包含以下属性
* （必选）streamName 本地流名称，数据类型（String），可选参数值为 'main'、'assist'、'picture'
    此参数为区分多条本地流操作，如果本地只创建一条流，就使用'main'
* （可选）audioRate 音频码率（50 - 200）数据类型（Number）,默认50
* （可选）videoRate 音频码率（50 - 2000）数据类型（Number）,默认200
* （可选）successed 成功回调
object.success = function(stream){
    // 返回值为流对象
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.publish({
    streamName: 'main',
    videoRate: 300,
    audioRate: 50,
    success: function(stream){
        console.log('本地流推送成功', stream.id());
    },
    fail: function(str){
        console.log(str);
    }
});

1.1.8 取消推送本地流

rtc.unPublish(object);

参数说明：

object 包含以下属性
* （必选）streamName 本地流名称，数据类型（String），可选参数值为 'main'、'assist'、'picture'
    此参数为区分多条本地流操作，如果本地只创建一条流，就使用'main'
* （可选）success 成功回调
object.success = function(id){
    // 返回值为流对象id
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.unPublish({
    streamName: 'main',

    success: function(id){
        console.log('取消本地流推送成功',id);
    },
    fail: function(str){
        console.log(str);
    }
});

1.1.8 推送桌面共享

rtc.publishShareStream(object);
使用说明：1.该功能需要https环境  2.需要使用含有域名的插件

参数说明：

object:包含以下属性
* （可选）audioRate 音频码率（50 - 200）数据类型（Number）,默认50
* （可选）videoRate 音频码率（50 - 2000）数据类型（Number）,默认200
* （可选）success 成功回调
object.success = function(stream){
    // 返回值为流对象
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.publishShareStream({
    videoRate: 300,
    audioRate: 50,
    success: function(stream){
        console.log('推送桌面共享成功', stream.id());
    },
    fail: function(str){
        console.log(str);
    }
});

1.1.9 关闭桌面共享

rtc.unPubShareStream();

使用说明：此方法用于关闭已开启的桌面共享

关闭桌面共享目前提供两种方法：

1. 直接关闭浏览器桌面共享控制条
2. 调用关闭桌面api实现关闭

使用例子：

rtc.unPubShareStream();

1.2 远程流方法

1.2.1 订阅远程流

rtc.trySubscribeStream(object);

参数说明：

object:为对象，包含以下属性
*  (必选)tryStream 要订阅的流对象
*  (可选)tryData 要订阅的流参数
object.tryData = {
    video: false,    //是否订阅视频     true  、 false
    audio: true     //是否适用音频     true  、 false  
}
* （可选）success 成功回调
object.success = function(stream){
    // 返回值为已订阅流对象
}

* （可选）showVoice 音量值回调
object.showVoice = function(value){
    // value值范围（0-100）
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.trySubscribeStream({
    tryStream: stream,
    success: function(stream){
        console.log('订阅流成功', stream.id());
    },
    showVoice: function(value){
        // value值范围（0-100）
    },
    fail: function(str){
        console.log(str);
    }
});

1.2.2 取消订阅远程流

rtc.unSubscribeStream(object);

参数说明：

object:对象，包含以下属性
*  (必选)unSubStream 要取消订阅的流对象
* （可选）success 成功回调
object.success = function(stream){
    // 返回值为已取消订阅流对象
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.unSubscribeStream({
    unSubStream: stream,
    success: function(stream){
        console.log('取消订阅流成功', stream.id());
    },

    fail: function(str){
        console.log(str);
    }
});

1.2.3 结束远程流

rtc.closeRemoteStreams();

使用说明：此方法用于关闭已订阅的远程流通道，建议在卸载页面的时候使用

使用例子：

rtc.closeRemoteStreams();

1.3 监听流相关事件

事件监听，建议在初始化sdk后做监听

1.3.1 监听有流可订阅事件

将房间内推出的流订阅到本地显示

rtc.on('allow_sub', function (stream) {
    // 订阅流
    if(stream instanceof Woogeen.RemoteMixedStream){
        console.log('是混合流,不定阅');
    }else{
        // 订阅流
        rtc.trySubscribeStream({
            tryStream: stream,
            success:function(stream){
                // 订阅流成功
                var streamId = stream.id(); // 获取流id
                console.log('订阅流成功', streamId);
                //将视频动态插入盒子中
                stream.show(streamId); // 将流显示到id为streamId的盒子中
            },
            fail: function(err){
                console.log(err);
            }
        });
    }
});

1.3.2 监听需要取消订阅流事件

取消订阅已经移除房间的流

rtc.on('unSub', function(stream){
    rtc.unSubscribeStream({
        unSubStream: stream,
        success:function(id){
            console.log('取消订阅成功', id);
        },
        fail: function(err){
            console.log('取消订阅失败', err);
        }
    });
});

1.3.3 监听通知移除流事件

房间内有流移除会收到此通知

rtc.on('stream_removed', function (stream) {
    // 删除显示该流用的界面dom
    $('#'+ stream.id()).remove();
});

1.4 部分高级功能

1.4.1 推流至cdn平台

直播开启后，讲师端推流成功后，可以调用该方法，将房间内的流推入cdn平台

rtc.addExternalOutput(object);

参数说明：

object:包含以下属性
* （可选）url 推流地址 有该配置项则推到指定地址，没有，则推至默认地址
object.url = 'xxxxxxxxx';

* （可选）streamId 需要推的流id  不传，默认推合流，指定后，推指定的流
object.streamId = 'xxxxxx'
* （可选）success 成功回调
object.success = function(str){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.addExternalOutput({
    success: function(str){
        console.log(str);
    },
    fail: function(str){
        console.log(str);
    }
});

1.4.2 取消推流至cdn平台

讲师端调用推流至cdn平台成功后，如果要取消推送，可以调用该方法

rtc.removeExternal(object);

参数说明：

object:包含以下属性
* （可选）url 推流地址 有该配置项则推到指定地址，没有，则推至默认地址
object.url = 'xxxxxxxxx';

* （可选）success 成功回调
object.success = function(str){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.removeExternal({
    success: function(str){
        console.log(str);
    },
    fail: function(str){
        console.log(str);
    }
});

1.4.3 更新推流平台地址

rtc.updateExternalOutput(object);

参数说明：

object:包含以下属性
* （必选）url 推流地址
object.url = 'xxxxxxxxx';

* （可选）success 成功回调
object.success = function(str){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.updateExternalOutput({
    url: 'xxxxxxxxxxxx',
    success: function(str){
        console.log(str);
    },
    fail: function(str){
        console.log(str);
    }
});

1.4.4 mix 流

此方法只有讲师角色有权限调用，将流合并入混流

rtc.mix(object);

参数说明：

object:包含以下属性
* （必选）stream 要混合的流对象
object.stream = stream;

* （可选）success 成功回调
object.success = function(str){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.mix({
    stream: stream,
    success: function(str){
        console.log(str);
    },
    fail: function(str){
        console.log(str);
    }
});

1.4.5 unMix 流

此方法只有讲师角色有权限调用，将已加入混流的流取消混流

rtc.unMix(object);

参数说明：

object:包含以下属性
* （必选）stream 要取消混合的流对象
object.stream = stream;

* （可选）success 成功回调
object.success = function(str){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.unMix({
    stream: stream,
    success: function(str){
        console.log(str);
    },
    fail: function(str){
        console.log(str);
    }
});

1.4.6 设置混流位置

此方法只有讲师角色有权限调用，为已加入混流的流设置显示区域

rtc.setRegion(object);

参数说明：

object:包含以下属性
* （必选）regionObj  设置混流参数
object.regionObj = {
    id：'xxxxxxxxxxx',   // 需要设置的流id
    region: '1'    //显示区域，默认 '1'
};

* （可选）success 成功回调
object.success = function(str){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.setRegion({
    regionObj: {
        id：'xxxxxxxxxxx',
        region: '1'
    },
    success: function(str){
        console.log(str);
    },
    fail: function(str){
        console.log(str);
    }
});

1.4.7 获取混流位置

此方法只有讲师角色有权限调用，获取已加入混流的流的显示区域

rtc.getRegion(object);

参数说明：

object:包含以下属性
* （必选）regionObj  设置混流参数
object.regionObj = {
    id：'xxxxxxxxxxx'  // 需要获取位置的流id
};

* （可选）success 成功回调
object.success = function(str){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.getRegion({
    regionObj: {
        id：'xxxxxxxxxxx'
    },
    success: function(str){
        console.log(str);
    },
    fail: function(str){
        console.log(str);
    }
});

1.4.8 获取单条流状态

此方法用于获取已经订阅到或已经推出去的流对象的音视频状态

rtc.getConnectionStats(object);

参数说明：

object:包含以下属性
* （必选）regionObj  设置混流参数
object.stream = stream;

* （可选）success 成功回调
object.success = function(data){
    // data 包含音视频详细参数
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.getConnectionStats({
    stream: stream,
    success: function(data){
        console.log(data);
    },
    fail: function(str){
        console.log(str);
    }
});

1.4.9 开启服务端视频录制

此方法由讲师角色推流成功后调用，用于在服务端备份录制房间内视频

rtc.startRecorder(object);

参数说明：

object:包含以下属性
* （可选）success 成功回调
object.success = function(id){
    // 返回录制文件id
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.startRecorder({
    success: function(id){
        console.log(id);
    },
    fail: function(str){
        console.log(str);
    }
});

1.4.10 关闭服务端视频录制

此方法由讲师角色结束直播后调用，用于停止在服务端备份录制房间内视频

rtc.stopRecorder(object);

参数说明：

object:包含以下属性
* （可选）success 成功回调
object.success = function(id){
    // 返回录制文件id
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.stopRecorder({
    success: function(id){
        console.log(id);
    },
    fail: function(str){
        console.log(str);
    }
});

2.1 主动调用事件

2.1.1 开启直播

直播开启接口由老师角色去控制

rtc.startLive(object);

参数说明：

object:包含以下属性
* （可选）success 成功回调
object.success = function(data){
    // 返回值对象，包含直播id
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.startLive({
    success: function(data){
        console.log('开启直播成功', data);
    },
    fail: function(str){
        console.log(str);
    }
});

2.1.2 关闭直播

直播关闭接口由老师角色去控制

rtc.stopLive(object);

参数说明：

object:包含以下属性
* （可选）success 成功回调
object.success = function(){

}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为失败原因，字符串类型
    console.log(str)；
}

使用例子：

rtc.stopLive({
    success: function(){
        console.log('关闭直播成功');
    },
    fail: function(str){
        console.log(str);
    }
});

2.1.3 查询直播是否开启

rtc.getLiveStat(object);

参数说明：

object:包含以下属性
* （可选）success 成功回调
object.success = function(data){
    // data包含直播id
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为字符串类型
    console.log(str)；
}

使用例子：

rtc.getLiveStat({
    success: function(data){
        console.log('直播开启状态');
    },
    fail: function(str){
        console.log('直播关闭状态或查询直播失败', str);
    }
});

2.1.4 获取设备列表

用于获取当前浏览器可用音视频设备

rtc.getDevice(object);

参数说明：

object:包含以下属性
* （可选）success 成功回调
object.success = function(data){
    // 返回可用设备列表
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为字符串类型
    console.log(str)；
}

使用例子：

rtc.getDevice({
    success: function(data){
        console.log('获取成功', data);
    },
    fail: function(str){
        console.log('直播关闭状态或查询直播失败', str);
    }
});

2.1.5 获取历史记录

用于获取当前直播中房间的文档翻页，画笔，聊天的历史记录

rtc.getHistory(object);

参数说明：

object:包含以下属性
* （可选）success 成功回调
object.success = function(data){
    // 返回数据
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为字符串类型
    console.log(str)；
}

使用例子：

rtc.getHistory({
    success: function(data){
        console.log('获取成功', data);
    },
    fail: function(str){
        console.log(str);
    }
});

2.1.6 网络节点选择

2.1.6.1 查询节点

rtc.getNetPoint(object);

参数说明：

object:包含以下属性
* （可选）success 成功回调
object.success = function(data){
    // 返回可用节点
}

// data数据如下：
 [{
       area_code:"DNYX",  //  地区码缩写
    is_abroad:1,  // 是否属于国外
    loc:"新加坡",    // 地区名
    delay: 63    // 延时，（设置回调时间过短可能没有此字段）

 }
 ...
 ]

* （可选）fail 失败回调
object.fail = function(data){
    // 返回错误数据
    console.log(data)；
}

使用例子：

rtc.getNetPoint({
    success: function(data){
        console.log('获取成功', data);
    }
});

2.1.6.2 推拉流使用节点

初始化sdk时传入地区码

new Rtc({
    userid: 'xxxxxxxx',
    sessionid: 'xxxxxxxx',
    areaCode: 'HB'  // 使用节点
});

2.1.6 开启、结束、暂停、恢复录制接口

用于控制直播过程中开启、关闭、暂停、恢复录制

rtc.liveRecord(object);

参数说明：

object:包含以下属性
* （必须） status 表示执行动作

* （可选）success 成功回调
object.success = function(data){
    // 返回数据
}

* （可选）fail 失败回调
object.fail = function(str){
    // 返回值为字符串类型
    console.log(str)；
}

使用例子：

rtc.liveRecord({
    status:'start',
    success: function(data){
        console.log('成功', data);
    },
    fail: function(str){
        console.log(str);
    }
});

2.2 被动监听事件

事件监听，建议在初始化sdk后做监听

2.2.1 监听通知开启直播事件

当老师角色调用开启直播接口后，房间内所有人都会监听到该事件

rtc.on('publish_stream' function(str){
    console.log('直播已开启');
});

2.2.2 监听通知结束直播事件

当老师角色调用关闭直播接口后，房间内所有人都会监听到该事件

rtc.on('end_stream' function(str){
    console.log('直播已关闭');
});

2.2.3 监听通人员列表变更事件

当有人员上下麦或人员进出房间时会收到该事件

rtc.on('online_users' function(data){
    console.log(data);
});

2.2.4 用户加入房间通知其他人员

rtc.on("join_room_user", function(data){
    console.log(data);
});


// data 数据格式如下
{id:  'xxxxxx'，name: 'xxxxx'}

2.2.5 用户退出房间通知其他人员

rtc.on("exit_room_user", function(data){
    console.log(data);
});


// data 数据格式如下
{id:  'xxxxxx'，name: 'xxxxx'}

2.2.3 自定义消息发送、接收

// 发送自定义消息，data 可自定义
rtc.sendPublishMessage(data);

// 接收自定义消息
rtc.on('publish_message', function(data){
    console.log(data);
});

// 此方法发送的数据如需保存记录，需联系我们，告知需要记录的数据格式