亲加视频直播

来自于:亲加立即使用

简介

亲加视频直播SDK是一套完整的视频直播SDK产品,包含了直播、聊天室聊天、观看直播,且每个模块都是独立的,开发者可以根据自己的需求选择相应的模块进行集成。 功能包括: 1、直播 2、聊天室、送礼物等 3、连麦 4、脸萌特效(可体验demo,测试key,2分钟内有效) 5、音效、小视屏等功能 开发者可以快速接入与直播相关大部分功能,从而减少开发工作量和开发时间,提高系统稳定性。 相关Demo参考及源码可以参考:[https://github.com/QPlus/APICloudLiveDemo]

注:如没有特别说明,文档中提及的接口都是iOS和Android通用的

基础模块(gotyeLiveCore)

包含了各个模块所必需的接口实现,在集成其它模块之前都需要先把当前模块集成到项目中

registerApp

初始化函数。如果在config.xml文件中配置了appKey以及accessSecret的信息,那么在模块初始化的时候底层会自动调用此接口,无需再手动调用。

registerApp({params})

params

appKey:

accessSecret:

companyId:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)亲加管理后台中的公司唯一标识。当roomId类型为custom时,此字段为必须

示例代码

var core = api.require('gotyeLiveCore');
core.registerApp({
    appKey: "46712182-****-11e5-8fee-5254009b7711",
    accessSecret: "eaa6da7a9******e8279677470a1eb9f"
});

config.xml配置示例:

<feature name="gotyeLiveCore">
  <param name="appKey" value="46712182-****-11e5-8fee-5254009b7711" />
  <param name="accessSecret" value="eaa6da7a9****e8279677470a1eb9f" />
</feature>

setDebugLogEnabled

设置是否打印debug日志。默认情况下不打印

setDebugLogEnabled({params})

params

enabled:

  • 类型:布尔值
  • 默认值:false
  • 描述:是否打印debug日志

示例代码

core.setDebugLogEnabled({
    enabled: true
});

authRoomSession

验证房间信息。session是对应一个直播房间的,验证通过才能获取直播间的信息

authRoomSession({params}, callback(ret, err))

params

type:

  • 类型:字符串
  • 默认值:default
  • 描述:roomId类型。default为亲加后台系统默认的id,custom为自定义的id

roomId:

  • 类型:字符串
  • 默认值:无
  • 描述:直播间的唯一标识

password:

  • 类型:字符串
  • 默认值:无
  • 描述:直播间的登录密码。不同的登录密码对应不同的用户级别

nickname:

  • 类型:字符串
  • 默认值:无
  • 描述:登录用户的昵称

callback(ret, err)

ret:

  • 类型:JSON对象

内部字段:

{
    accessToken:'',         //认证token
    createTime:1461223473,  //创建时间,本地维护
    expired:false,          //当前token是否过期。false表示没过期,true表示过期
    expiresIn:21600,        //有效时间,单位(秒)
    role:2,                 //当前token的用户级别。1表示后台用户,2表示主播用户,3表示助理用户,4表示普通用户
    userStatus:0           //(可选)当前用户状态
}

err:

  • 类型:JSON对象

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码

var session = {
    roomId: '',
    password: '',
    nickname: ''
};
core.authRoomSession(session, function( ret, err ){
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

destroyRoomSession

清除房间验证信息,销毁session实例。退出直播间时调用

destroyRoomSession({params})

params

authRoomSession的参数一致

示例代码

var session = {
    roomId: '',
    password: '',
    nickname: ''
};
core.destroyRoomSession(session);

getLiveContext

查询直播间详情

getLiveContext({params}, callback(ret, err))

params

authRoomSession的参数一致

callback(ret, err)

ret:

  • 类型:JSON对象

内部字段:

{
    recordingStatus:0,         //当前直播状态。1-录制中 0-停录中
    playUserCount:0,           //当前播放视频人数
}

err:

  • 类型:JSON对象

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码

var session = {
    roomId: '',
    password: '',
    nickname: ''
};
core.getLiveContext(session, function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

getClientUrl

获取客户端的网页播放地址等信息

getClientUrl({params}, callback(ret, err))

params

authRoomSession的参数一致

callback(ret, err)

ret:

  • 类型:JSON对象

内部字段:

{
    educVisitorUrl:'',               //直播观看地址。可用于分享
    modVisitorShareUrl:'',           //课件观看端页面地址
}

err:

  • 类型:JSON对象

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码

var session = {
    roomId: '',
    password: '',
    nickname: ''
};
core.getClientUrl(session, function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

错误码说明

错误码 描述
401 验证失败,或者是没有验证成功的情况下调用了别的接口
-101 JSON解析出错
-102 网络错误
-106 超时
-999 未知错误

聊天室模块(gotyeLiveChat)

实现了聊天室功能,用户可以在聊天室中进行聊天

init

初始化聊天模块。聊天模块是与直播间绑定的,只有验证成功,才能正常使用聊天功能

init({params})

params

authRoomSession的参数一致

示例代码

var session = {
    roomId: '',
    password: '',
    nickname: ''
};
var chat = api.require('gotyeLiveChat');
chat.init(session);

login

登录直播间聊天室

login(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON对象

内部字段:

{
    account:'',            //系统分配的唯一身份标识
    nickname:'',           //登录用户昵称。与authRoomSession时传入的昵称一致
}

err:

  • 类型:JSON对象

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码

chat.login(function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

补充说明

如果登录失败的话,SDK不会自动重连。但是如果在登录成功的情况下因为网络的问题或者其它问题导致的掉线,SDK底层会自动进行重连,直到登录成功或者开发者主动调用了logout

logout

退出聊天室登录,并断开连接,不再接收消息

logout()

示例代码

chat.logout();

sendText

发送文本消息(type为1)

sendText({params}, callback(ret, err))

params

text:

  • 类型:字符串
  • 默认值:无
  • 描述:需要发送的文本内容。如果文本内容为空,此接口不会做任何事情

extra:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)额外信息文本

callback(ret, err)

ret:

  • 描述:总是为空

err:

  • 类型:JSON对象
  • 描述:发送成功时为空,发送失败时不为空

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码

chat.sendText({text: "text", extra: "extra"}, function(ret, err) {
    if( err ){
        alert( JSON.stringify( err ) );
    }else{
        alert( '发送成功' );
    }
});

sendNotify

发送通知消息(type为3)

sendNotify({params}, callback(ret, err))

params

notify:

  • 类型:字符串
  • 默认值:无
  • 描述:需要发送的通知内容。如果通知内容为空,此接口不会做任何事情

extra:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)额外信息文本

callback(ret, err)

ret:

  • 描述:总是为空

err:

  • 类型:JSON对象
  • 描述:发送成功时为空,发送失败时不为空

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码

chat.sendNotify({notify: "notify", extra: "extra"}, function(ret, err) {
    if( err ){
        alert( JSON.stringify( err ) );
    }else{
        alert( '发送成功' );
    }
});

sendMessage

发送自定义内容的消息

sendMessage({params}, callback(ret, err))

params

type:

  • 类型:数字
  • 默认值:0
  • 描述:消息的类型。这个类型服务器不会做任何判断和处理,发送端填什么类型接收端收到的就是什么类型

text:

  • 类型:字符串
  • 默认值:无
  • 描述:需要发送的通知内容。如果通知内容为空,此接口不会做任何事情

extra:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)额外信息文本

callback(ret, err)

ret:

  • 描述:总是为空

err:

  • 类型:JSON对象
  • 描述:发送成功时为空,发送失败时不为空

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码

chat.sendMessage({type: 1, text: "text", extra: "extra"}, function(ret, err) {
    if( err ){
        alert( JSON.stringify( err ) );
    }else{
        alert( '发送成功' );
    }
});

补充说明

SDK目前只支持纯文本内容的发送,但是消息的格式是可以自定义的,换句话说,只要使用合适的格式,开发者是很容易就能够实现红包、点赞诸如此类的功能的。

getRoomMemberCount

获取聊天室当前在线人数

getRoomMemberCount(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON对象

内部字段:

{
    count:0,      //聊天室人数
}

err:

  • 类型:JSON对象

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码

chat.getRoomMemberCount(function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

queryUserList

获取聊天室用户列表

queryUserList(param, callback(ret, err))

params

index:

  • 类型:整数类型
  • 默认值:无
  • 描述:开始查询的位置

totoal:

  • 类型:整数类型
  • 默认值:无
  • 描述:查询的人数

callback(ret, err)

ret:

  • 类型:JSON对象

内部字段:

{
    total:1,      //实际查询到的总人数
    entities:[
    {"account":"publisher_2184",  //账户ID
     "nickname":"445",            //昵称
     "role" : 2}                  //角色; 2:主播,3:助理,4:观看端
    ]
}

err:

  • 类型:JSON对象

内部字段:

{
    code:201,               //错误的状态码
    description:"用户未登录"   //错误描述     
}

示例代码

queryUserList({index:1,total:20},function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

currentLoginUser

获取聊天室当前登录用户的信息

currentLoginUser(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON对象

内部字段:

{
    account:'',            //系统分配的唯一身份标识
    nickname:'',           //登录用户昵称。与authRoomSession时传入的昵称一致
}

err:

  • 类型:JSON对象

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码

chat.currentLoginUser(function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

addEventListener

添加聊天模块事件的监听

addEventListener({params}, callback(ret, err))

params

name:

  • 类型:字符串
  • 默认值:无
  • 描述:sdk事件名称(详见事件

callback(ret, err)

ret:

  • 类型:JSON对象
  • 描述:事件发生时传递的参数,可能为空

示例代码

//监听与服务器断开连接的事件
chat.addEventListener({
    name:'disconnected'
},function(ret,err){
    //operation
});

removeEventListener

移除事件监听

removeEventListener({params})

params

name:

  • 类型:字符串
  • 默认值:无
  • 描述:sdk事件名称(详见事件

示例代码

chat.removeEventListener({
    name: 'disconnected'
});

removeAllEventListeners

移除所有的事件监听

removeAllEventListeners()

示例代码

chat.removeAllEventListeners();

事件

receiveMsg

收到新消息事件

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:返回消息的具体内容,不为空

内部字段:

{
    text:''             //消息的文本内容
    sendId:''           //发送者的账号
    sendName:''         //发送者昵称
    extra:''            //消息的额外内容,可能为空
    type:1              //消息类型。与发送端设置的消息类型一致
    status:0            //消息状态。这个字段是本地维护的,收到的消息status均为0
}

示例代码
//监听与服务器断开连接的事件
chat.addEventListener({
    name:'receiveMsg'
},function(ret,err){
    //operation
});

disconnected

与服务器异常断开事件。用户主动断开连接不会触发此事件

callback()

不能为空

示例代码
//监听与服务器断开连接的事件
chat.addEventListener({
    name:'disconnected'
},function(ret,err){
    //operation
});

reconnecting

异常断开之后,sdk底层自动重连事件

callback()

不能为空

示例代码
//监听与服务器断开连接的事件
chat.addEventListener({
    name:'reconnecting'
},function(ret,err){
    //operation
});

reloginSuccess

sdk自动重连并登录服务器成功事件

callback()

不能为空

示例代码
//监听与服务器断开连接的事件
chat.addEventListener({
    name:'reloginSuccess'
},function(ret,err){
    //operation
});

reloginFailed

sdk尝试重新登录服务器失败事件

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:返回登录失败的错误信息,不为空

内部字段:

{
    code:401             //错误的状态码
    description:''       //错误的具体描述
}

示例代码
//监听与服务器断开连接的事件
chat.addEventListener({
    name:'reloginFailed'
},function(ret,err){
    //operation
});

forceLogout

账号在另外的设备登录,当前设备被强制踢下线事件

callback()

不能为空

示例代码
//监听与服务器断开连接的事件
chat.addEventListener({
    name:'forceLogout'
},function(ret,err){
    //operation
});

补充说明

昵称并不是区分用户的字段,所以昵称相同的普通用户之间并不会互相踢下线。目前只有主播用户和助理用户会相互踢下线

错误码说明

错误码 描述
300 失败
401 验证失败
403 无效角色,只有聊天室role可以登录
500 系统异常
1001 无操作权限
1003 已被禁言
1005 消息内容和附加字段都为空
1007 无效TARGET_ID
1009 已经被禁止登陆
-101 数据解析出错
-102 网络错误
-103 当前没有登录
-104 已经登录
-105 获取服务器地址失败
-106 超时

播放器模块(gotyeLivePlayer)

实现了视频播放功能

init

初始化播放器模块

init({params})

播放器支持两种模式:

模式一

与直播间绑定,支持直播间的状态判断以及人数统计

params

session:

  • 类型:JSON对象
  • 默认值:无
  • 描述:直播间信息,格式与authRoomSession的参数一致

示例代码
var session = {
    roomId: '',
    password: '',
    nickname: ''
};
var player = api.require('gotyeLivePlayer');
player.init({session:session});

模式二

只需要一个播放url就可以进行播放的(目前只支持rtmp流以及flv流的播放),没有直播状态的概念

params

url:

  • 类型:字符串
  • 默认值:无
  • 描述:rtmp或者flv的播放链接,不能为空

示例代码
player.init({
    url:'rtmp://xxxx'
});

补充说明

如果参数中既有session字段又有url字段,那么优先使用session来初始化

play

开始播放

play({params})

params

playView:

  • 类型:字符串
  • 默认值:无
  • 描述:视频显示的窗口名称。视频视图将以子view的方式添加到这个窗口上

rect:

  • 类型:JSON对象
  • 默认值:充满整个父页面
  • 描述:(可选项)frame的位置和大小

内部字段:

{
    x:0,             //左上角x坐标
    y:0,             //左上角y坐标
    w:320,           //宽度
    h:480            //高度
}

fixed:

  • 类型:布尔值
  • 默认值:false
  • 描述:视图是否固定,为false时跟随目标窗口内容滚动而滚动

quality:

  • 类型:字符串
  • 默认值:无
  • 描述:只有在模式一下有效,表示播放视频的清晰度。original表示原始清晰度,high表示高清清晰度,medium表示标清清晰度,low表示流畅清晰度

示例代码

player.play({playView: "frmMine"});

补充说明

  • 使用模式一时,SDK会验证当前roomSession的有效性,如果没有验证成功,播放会失败;如果当前直播间没有直播,播放也会失败,但是SDK会去定时获取直播状态,当检测到直播开始后,会自动开始播放。
  • 使用模式二时,SDK会验证基础模块初始化时传入的App KeyAccess Secret,判断当前账户的状态,如果验证失败,则播放失败。
  • 不管是哪种模式,如果播放失败了或者播放过程中出现了什么问题导致播放中断,SDK都会自动进行重连(直播间结束直播了除外),直到重新播放成功或者调用了stop()为止。
  • 目前SDK的设定是如果当前正在播放,app切换到后台时播放会自动停止,切换回前台后自动开始重连(直播间结束直播了除外)。

stop

结束播放

stop()

示例代码

player.stop();

setMute

打开/关闭视频的声音

setMute({params})

params

mute:

  • 类型:布尔值
  • 默认值:false
  • 描述:声音是否关闭

示例代码

player.setMute({mute:true});

getMuteStatus

判断当前视频声音是否关闭

getMuteStatus(callback(ret))

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:如果当前播放器没有初始化,返回为空。

内部字段:

{
    mute:false               //false表示声音没关闭,true表示声音关闭
}

示例代码

player.getMuteStatus(function(ret) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }
});

getInfo

获取当前播放器的一些状态信息

getInfo(callback(ret))

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:如果当前播放器没有初始化,返回为空。

内部字段:

{
    connectionTime:500,         //播放器连接到服务器所花费的时间,单位毫秒
    bps:700,                     //当前播放器的码流大小,单位kbps
    videoBuffer:50,             //当前流的视频缓冲大小
    audioBuffer:100,            //当前流的音频缓冲大小
    delay:300                    //当前视频延时,单位为毫秒。
}

示例代码

player.getInfo(function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }
});

补充说明

播放器状态中,delay字段的计算方法为,视频开始播放时记录一个本地时间,然后根据本地时钟得到的时长减去视频播放的时长,即为该延时。有可能为负值

setDisplayMode

设置视频的显示模式

setDisplayMode({params})

params

mode:

  • 类型:字符串
  • 默认值:aspectFit
  • 描述:视频视图的拉伸模式。aspectFit表示保持比例居中,视频会按照比例放大直到撑满屏幕某一边为止;aspectFill表示保持比例撑满,视频会按照比例放大直到撑满屏幕为止

示例代码

player.setDisplayMode({mode:'aspectFit'});

switchToQuality

切换视频清晰度。仅模式一有效

switchToQuality({params})

params

quality: 与play()接口中的quality字段一致

示例代码

chat.switchToQuality({quality:'high'});

补充说明

如果切换的清晰度与当前清晰度一样,接口不会做任何事情。如果不一样,播放器会停止当前播放,并尝试播放参数中指定的清晰度,如果当前直播间的配置没有接口希望选择的清晰度,那么会由高到低选择一个最高的清晰度进行播放

getVideoQuality

获取客户端的当前播放视频的清晰度。仅模式一有效

getVideoQuality(callback(ret))

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:如果当前播放器没有初始化,返回为空。

内部字段:

{
    quality:'original'          //视频清晰度。
                                //original表示原始清晰度
                                //high表示高清清晰度
                                //medium表示标清清晰度
                                //low表示流畅清晰度
}

示例代码

player.getVideoQuality(function(ret) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }
});

getAvailableQualities

获取当前直播间的视频清晰度列表。仅模式一有效

getAvailableQualities(callback(ret))

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:如果当前播放器没有初始化,返回为空。

内部字段:

{
    qualities:['original']          //视频清晰度列表
                                    //original表示原始清晰度
                                    //high表示高清清晰度
                                    //medium表示标清清晰度
                                    //low表示流畅清晰度
}

示例代码

player.getAvailableQualities(function(ret) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }
});

补充说明

默认情况下直播间都只有原始清晰度这一配置,若需要配置多清晰度的流,需要在后台中额外设置

addEventListener

添加播放器模块事件的监听

addEventListener({params}, callback(ret, err))

params

name:

  • 类型:字符串
  • 默认值:无
  • 描述:sdk事件名称(详见事件

callback(ret, err)

ret:

  • 类型:JSON对象
  • 描述:事件发生时传递的参数,可能为空

示例代码

//监听与服务器断开连接的事件
player.addEventListener({
    name:'connected'
},function(ret,err){
    //operation
});

removeEventListener

移除事件监听

removeEventListener({params})

params

name:

  • 类型:字符串
  • 默认值:无
  • 描述:sdk事件名称(详见事件

示例代码

player.removeEventListener({
    name: 'connected'
});

removeAllEventListeners

移除所有的事件监听

removeAllEventListeners()

示例代码

player.removeAllEventListeners();

事件

connected

播放器成功连接服务器的事件

callback()

不可为空

示例代码
//监听与服务器断开连接的事件
player.addEventListener({
    name:'connected'
},function(ret,err){
    //operation
});

disconnected

播放器与服务器断开连接的事件

callback()

不可为空

示例代码
//监听与服务器断开连接的事件
player.addEventListener({
    name:'disconnected'
},function(ret,err){
    //operation
});

reconnecting

播放器正在尝试重新连接服务器的事件

callback()

不可为空

示例代码
//监听与服务器断开连接的事件
player.addEventListener({
    name:'reconnecting'
},function(ret,err){
    //operation
});

buffering

播放器正在缓冲的事件

callback()

不可为空

示例代码
//监听与服务器断开连接的事件
player.addEventListener({
    name:'buffering'
},function(ret,err){
    //operation
});

bufferCompleted

播放器缓冲完毕的事件

callback()

不可为空

示例代码
//监听与服务器断开连接的事件
player.addEventListener({
    name:'bufferCompleted'
},function(ret,err){
    //operation
});

statusUpdate

播放器状态信息更新的事件

callback()

不可为空

示例代码
//监听与服务器断开连接的事件
player.addEventListener({
    name:'statusUpdate'
},function(ret,err){
    //operation
});

补充说明

播放器连接成功后,sdk底层每隔1秒会发送此事件,表示状态信息有更新

error

播放器出现错误的事件。详见错误码说明

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:错误的具体信息,不为空

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码
//监听与服务器断开连接的事件
player.addEventListener({
    name:'error'
},function(ret,err){
    //operation
});

liveStop

直播结束的事件。仅模式一有效

callback()

不可为空

示例代码
//监听与服务器断开连接的事件
player.addEventListener({
    name:'liveStop'
},function(ret,err){
    //operation
});

补充说明

这个事件只有在播放过程中才会触发,表示主播已经结束直播

liveStart

直播开始的事件。仅模式一有效

callback()

不可为空

示例代码
//监听与服务器断开连接的事件
player.addEventListener({
    name:'liveStart'
},function(ret,err){
    //operation
});

补充说明

如果之前已经调用过play()并且没有调用stop(),那么收到此事件的同时,sdk底层会自动尝试播放直播间的视频

错误码说明

错误码 描述
401 验证失败
-101 获取直播状态失败
-102 网络错误
-103 获取直播url失败
-104 直播未开始

直播模块(gotyeLivePublisher)

实现了手机直播功能

init

初始化直播模块

init({params})

与播放器一样,推流端也支持两种模式的初始化:

模式一

与直播间绑定,支持直播间主播账号的登录以及直播状态的设置

params

session:

  • 类型:JSON对象
  • 默认值:无
  • 描述:直播间信息,格式与authRoomSession的参数一致

示例代码
var session = {
    roomId: '',
    password: '',
    nickname: ''
};
var publisher = api.require('gotyeLivePublisher');
publisher.init({session:session});

模式二

需要一个推流地址的url即可发布直播(目前只支持rtmp服务器的推流),没有直播状态的概念

params

url:

  • 类型:字符串
  • 默认值:无
  • 描述:rtmp推流地址,不能为空

示例代码
publisher.init({
    url:'rtmp://xxxx'
});

补充说明

如果参数中既有session字段又有url字段,那么优先使用session来初始化

startPreview

在推流之前,需要先打开设备的摄像头

startPreview({params}, callback(ret, err))

params

preview:

  • 类型:字符串
  • 默认值:无
  • 描述:显示预览的窗口名字,预览画面将以子视图的方式添加到窗口上

position:

  • 类型:字符串
  • 默认值:front
  • 描述:打开摄像头的位置。front为前置摄像头,back为后置摄像头

rect:

  • 类型:JSON对象
  • 默认值:充满整个父页面
  • 描述:(可选项)frame的位置和大小

内部字段:

{
    x:0,             //左上角x坐标
    y:0,             //左上角y坐标
    w:320,           //宽度
    h:480            //高度
}

fixed:

  • 类型:布尔值
  • 默认值:false
  • 描述:视图是否固定,为false时跟随目标窗口内容滚动而滚动

callback(ret, err)

ret:

  • 描述:总是为空

err:

  • 类型:JSON对象
  • 描述:打开摄像头成功时为空,失败时不为空

内部字段:

{
    code:-104,               //错误的状态码
    description:"验证失败"    //无法获取摄像头    
}

示例代码

publisher.startPreview({preview: "frmMine"}, function(ret, err) {
    if( err ){
         alert( JSON.stringify( err ) );
    }
});

补充说明

摄像头的方向是与ViewController的方向一致的

publish

开始直播

publish()

示例代码

publisher.publish();

补充说明

  • 如果使用的是模式一,那么在直播之前需要先登录直播间
  • 推流过程中如果出现了中断的情况,那么SDK底层会自动进行重连,直到重连成功或者手动调用了unpublish()或者stop()为止

unpublish

断开主播端与推流服务器的连接,不停止预览

unpublish()

示例代码

publisher.unpublish();

stop

断开主播端与推流服务器的连接并停止预览

stop()

示例代码

publisher.stop();

switchCamera

切换前后摄像头

switchCamera()

示例代码

publisher.switchCamera();

addWatermark

添加水印

addWatermark({params})

params

src:

  • 类型:字符串
  • 默认值:无
  • 描述:水印图片的本地路径。支持相对路径

rect:

  • 类型:JSON对象
  • 默认值:无
  • 描述:水印的位置和大小。这个位置和大小是以视频分辨率为参考坐标系的,也就是说,同样的位置和大小,在不同的视频分辨率上显示效果是不同的

内部字段:

{
    x:0,             //左上角x坐标
    y:0,             //左上角y坐标
    w:100,           //宽度
    h:100            //高度
}

示例代码

publisher.addWatermark({
    src: "../image/api100.png", 
    rect: {x: 10, y: 10, w: 100, h: 37}
});

可用性

仅适用于iOS

clearWatermark

清除当前所有水印,需要在下次直播开始时才生效

clearWatermark()

示例代码

publisher.clearWatermark();

可用性

仅适用于iOS

setTorchOn

打开/关闭闪光灯

setTorchOn({params})

params

on:

  • 类型:布尔值
  • 默认值:false
  • 描述:是否打开闪光灯

示例代码

publisher.setTorchOn({
    on: true
});

getTorchStatus

获取当前闪光灯状态

getTorchStatus(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON对象

内部字段:

{
    on:false              //false表示关闭状态,true表示打开状态
}

示例代码

publisher.getTorchStatus(function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

setMute

打开/关闭麦克风

setTorchOn({params})

params

mute:

  • 类型:布尔值
  • 默认值:false
  • 描述:是否关闭麦克风

示例代码

publisher.setMute({
    mute: true
});

getMuteStatus

获取当前麦克风状态(是否关闭)

getMuteStatus(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON对象
  • 描述:如果当前推流端没有初始化,返回为空。

内部字段:

{
    mute:false              //false表示麦克风没关闭,true表示关闭
}

示例代码

publisher.getMuteStatus(function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

setVideoPreset

设置视频编码参数

setVideoPreset({params})

params

width:

  • 类型:数字
  • 默认值:0
  • 描述:推送视频的像素宽度

height:

  • 类型:数字
  • 默认值:0
  • 描述:推送视频的像素高度

bps:

  • 类型:数字
  • 默认值:0
  • 描述:推送视频的最高码率限制,单位为kbps

fps:

  • 类型:数字
  • 默认值:0
  • 描述:摄像机的视频帧率,如果使用默认值0将会使用摄像机默认的帧率

示例代码

publisher.setVideoPreset({
    width: 360, 
    height: 640, 
    bps: 640, 
    fps: 24
});

补充说明

  • 默认情况下,直播出去的视频分辨率为640x360,码率为480kbps,帧率为20
  • 视频预览的参数是不可修改的,只能根据视图的方向旋转而已。这个接口设置的只是视频编码的参数(iOS)
  • 当视频编码的分辨率与本地预览的分辨率不一致时,最终推送出去的视频将会是预览画面保持比例居中(iOS)
  • 码率的设置是最大值的设置,码率过低容易导致画面模糊,特别是当画面抖动的时候。
  • 需要在预览开始前就设置,如果当前正在直播,那么设置会在下次直播才生效。
  • Android系统上,调用这个接口会改变摄像头的预览分辨率,sdk底层会根据传入的视频宽度和长度自动选择最接近的分辨率

getVideoPreset

获取当前视频编码参数

getVideoPreset(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON对象
  • 描述:如果当前推流端没有初始化,返回为空。

内部字段:

{
    width:360               //推送视频的像素宽度
    height:640              //推送视频的像素高度
    bps:640                 //推送视频的最高码率限制,单位为kbps
    fps:24                  //摄像机的视频帧率
}

示例代码

publisher.getVideoPreset(function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

setFilter

设置滤镜模式

setFilter({params})

params

filter:

  • 类型:字符串
  • 默认值:normal
  • 描述:滤镜模式。normal表示不添加滤镜,smoothSkin表示美白磨皮滤镜

示例代码

publisher.setFilter({filter: 'smoothSkin'})

补充说明

滤镜的设置是实时生效的

getFilter

获取当前滤镜模式

getFilter(callback(ret))

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:如果当前推流端没有初始化,返回为空。

内部字段:

{
    filter:'normal'     //normal表示不添加滤镜,smoothSkin表示美白磨皮滤镜
}

示例代码

publisher.getFilter(function(ret) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }
});

setSmoothSkinFactor

设置美白磨皮滤镜的效果强度

setSmoothSkinFactor({params})

params

factor:

  • 类型:浮点数
  • 默认值:0.5
  • 描述:表示磨皮效果强度的一个因子,该值越大,效果越强。取值范围为0~1

示例代码

publisher.setSmoothSkinFactor({factor: 0.3})

getSmoothSkinFactor

获取当前美白磨皮滤镜的效果强度

getSmoothSkinFactor(callback(ret))

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:如果当前推流端没有初始化,返回为空。

内部字段:

{
    factor:0.5,     //表示磨皮效果强度的一个因子,该值越大,效果越强,取值范围为0~1
}

示例代码

publisher.getSmoothSkinFactor(function(ret) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }
});

getInfo

获取当前推流端的一些状态信息

getInfo(callback(ret))

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:如果当前推流端没有初始化,返回为空。

内部字段:

{
    connectionTime:500,         //推流端连接到服务器所花费的时间,单位毫秒
    bps:700,                     //当前推流端的码流大小,单位kbps
    bufferSize:50,              //当前推流端的本地数据缓存大小,单位byte
}

示例代码

publisher.getInfo(function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }
});

addEventListener

添加直播模块事件的监听

addEventListener({params}, callback(ret, err))

params

name:

  • 类型:字符串
  • 默认值:无
  • 描述:事件名称(详见事件

callback(ret, err)

ret:

  • 类型:JSON对象
  • 描述:事件发生时传递的参数,可能为空

示例代码

//监听与服务器断开连接的事件
publisher.addEventListener({
    name:'disconnected'
},function(ret,err){
    //operation
});

removeEventListener

移除事件监听

removeEventListener({params})

params

name:

  • 类型:字符串
  • 默认值:无
  • 描述:sdk事件名称(详见事件

示例代码

publisher.removeEventListener({
    name: 'disconnected'
});

removeAllEventListeners

移除所有的事件监听

removeAllEventListeners()

示例代码

publisher.removeAllEventListeners();

login

登录直播间的主播账号。仅模式一有效

login({params}, callback(ret, err))

params

force:

  • 类型:布尔值
  • 默认值:false
  • 描述:如果当前已经有主播登录了该直播间,是否强制踢出当前登录的主播

callback(ret, err)

ret:

  • 类型:JSON对象
  • 描述:始终为空

err:

  • 类型:JSON对象
  • 描述:登录成功成功时为空,失败时不为空

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码

publisher.login({force:true}, function(ret, err) {
    if( ret ){
         alert( JSON.stringify( ret ) );
    }else{
         alert( JSON.stringify( err ) );
    }
});

logout

退出主播间直播账号的登录。仅模式一有效

logout()

示例代码

publisher.logout();

beginRecording

将当时时间设为保存录像的起点。仅模式一有效

beginRecording()

示例代码

publisher.beginRecording();

补充说明

如果重复调用,那么会忽略上一次的时间点,将起点重置为当前时间

endRecording

将当前时间设置为保存直播录像的终点。仅模式一有效

endRecording(callback(ret, err))

callback(ret, err)

ret:

  • 描述:总是为空

err:

  • 类型:JSON对象
  • 描述:成功保存录像时为空,失败时不为空

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误的具体描述   
}

示例代码

publisher.endRecording(function(ret, err) {
    if( err ){
         alert( JSON.stringify( err ) );
    }
});

补充说明

  • 如果时长小于两分钟,保存会失败
  • 如果没有调用过beginRecording,回调返回成功但是不会做任何操作
  • 保存成功的录像可以在亲加管理后台中找到

事件

connected

推流端连接服务器成功的事件

callback()

不可为空

示例代码
publisher.addEventListener({
    name:'connected'
},function(){
    //operation
});

disconnected

推流端与服务器断开连接的事件

callback()

不可为空

示例代码
publisher.addEventListener({
    name:'disconnected'
},function(){
    //operation
});

reconnecting

推流端正在尝试重连连接服务器的事件

callback()

不可为空

示例代码
publisher.addEventListener({
    name:'reconnecting'
},function(){
    //operation
});

statusUpdate

推流端状态信息更新的事件

callback()

不可为空

示例代码
publisher.addEventListener({
    name:'statusUpdate'
},function(){
    //operation
});

补充说明

推流成功成功后,sdk底层每隔1秒会发送此事件,表示状态信息有更新

error

推流端出现错误的事件。详见错误码说明

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:错误的具体信息,不为空

内部字段:

{
    code:401,               //错误的状态码
    description:"验证失败"   //错误描述     
}

示例代码
//监听与服务器断开连接的事件
player.addEventListener({
    name:'error'
},function(ret,err){
    //operation
});

forceLogout

主播账号被强制踢下线的事件。仅模式一有效

callback()

不可为空

示例代码
publisher.addEventListener({
    name:'forceLogout'
},function(){
    //operation
});

错误码说明

错误码 描述
401 验证失败,或者是没有验证成功的情况下调用了别的接口
1011 当前账号已经有人登录了
-101 当前已经有人在直播了
-102 网络断开
-103 获取当前直播状态出错
-104 无法获取摄像头,请检查权限
-105 获取直播Url出错
-106 当前状态无效
-107 用户未登录
-108 获取登录url失败
-109 录制时长过短(少于两分钟)

连麦模块(gotyeLiveP2P)

本模块只实现了连麦的基本功能,包括建立连接以及断开连接。建立连接之前的邀请逻辑以及断开连接之前的挂断逻辑,建议可以通过聊天模块发送自定义消息去实现。

joinRoom

加入视频通话房间,加入同一房间的用户可以相互进行通信。

joinRoom({params})

params

roomId:

  • 类型:字符串
  • 默认值:无
  • 描述:视频聊天房间ID,可以为任意字符串。在同一房间的两个用户可以相互通信

localId:

  • 类型:字符串
  • 默认值:无
  • 描述:本机用户在视频房间中的标识符,需要唯一

remoteId:

  • 类型:字符串
  • 默认值:无
  • 描述:对端用户在视频房间中的标识符,需要唯一。如果指定了这个参数的值,本地的用户将与remoteId指定的用户进建立视频通话,如果不指定,将会与第一个进入房间的用户建立视频通话

localView: (ios)

  • 类型:json对象
  • 默认值:无
  • 描述:仅在iOS平台有效,表示本地视频的窗口参数

内部字段:

{
    fixedOn:"frame",  //窗口的名称
    fixed:true        //是否随窗口一起滚动,默认true     
}

remoteView: (ios)

  • 类型:json对象
  • 默认值:无
  • 描述:仅在iOS平台中有效,表示远端视频的窗口参数

内部字段:

{
    fixedOn:"frame",  //窗口的名称
    fixed:true        //是否随窗口一起滚动,默认true     
}

rendererView: (Android)

  • 类型:json对象
  • 默认值:无
  • 描述:仅在Android平台有效,表示本地合成画面的窗口参数

内部字段:

{
    fixedOn:"frame",  //窗口的名称
    fixed:true        //是否随窗口一起滚动,默认true     
}

leaveRoom

退出视频通话房间并释放资源

leaveRoom()

addEventListener

添加事件监听

addEventListener({params})

params

请参考gotyeLive的其它模块

removeEventListener

移除事件监听

removeEventListener({params})

params

请参考gotyeLive的其它模块

removeAllEventListeners

移除所有的事件监听

removeAllEventListeners()

事件

joinedRoom

成功连接视频房间的事件

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:已连接房间的信息,不为空

内部字段:

{
    roomId:''             //房间ID号
}

connected

成功建立视频通话连接的事件

callback(ret)

ret:

  • 类型:JSON对象
  • 描述:当前正在通话的远端用户的信息,不为空

内部字段:

{
    remoteId:''             //远端用户的ID
}

disconnected

视频通话断开连接的事件

callback()

收到此事件后,与视频通话房间的连接也会断开,如需重新建立视频通话,需要重进调用joinRoom

error

发生错误的事件

callback(ret)

收到此事件后,与视频通话房间的连接也会断开,如需重新建立视频通话,需要重进调用joinRoom