Android VoIP SDK 使用文档

一,概述:

导入“voip_android.aar”aar 包, 下面为“voip_android”下文件:
1、 TYVoipAndroid: 提供所有 Voip 相关方法
2、 TYVoipVideoCapture: 摄像头管理类
3、 TYVoipVideoRender: Voip 客户端视频渲染视图., 渲染在此视图上进行
4、 VoipAudioIO: Voip 音频管理类
5、 VoipImage:表示了一个可以用于渲染的视频帧
转发服务器链接地址: https://gitee.com/tucodec/relay_server
SDK 设计逻辑说明: https://gitee.com/tucodec/relay_server/wikis
注: 需要自己搭建转发服务器
注: 使用提供的 Demo 时, 如果使用默认 IP, userId 不能随便填, 随便填会可能串流。注册时服务器有分配一个 appkey 和 secret, 一个 UserID 填这个 secret, 另一个userId 填的值为 secret+1.这样可以避免串流。 AppKey 和 AppSecret 是开发者在图鸭科技开发者网站(http://www.tucodec.com/)注册账号后获取的 AppKey 和AppSecret


二, 使用介绍


2.1 配置工程环境

2.1.1 导入”voip_android.aar”文件
在“libs”文件夹下添加 aar 包, 在 build 文件夹下添加:
repositories {
flatDir {
dirs 'libs'
}
} 在
dependencies 下添加:
compile(name: 'voip_android', ext: 'aar')
2.1.2 加入权限
加入以下权限:
/>


2.2 主要函数说明

2.2.1 登录
/**
*连接转发服务器
*@param ip @param 端口号@param userId @param sessionId
*@param AppKey @param AppSecret @return !0 即为成功
*/
//登录转发服务器, 注意与 logoutRelayServer 对应, 服务器有网络掉线自动登出处理
// AppKey 和 AppSecret 是开发者
// 在图鸭科技开发者网站(http://www.tucodec.com/)
// 注册账号后获取的 AppKey 和 AppSecret
loginRelayServer(String ip, short port, int userId, int sessionId, int AppKey, int AppSecret)
调用:
mTYVoipAndroid.loginRelayServer(“192.168.1.1”, 12345, 6, 0, 123, 123)
// 登出转发服务器
logoutRelayServer()
调用:
mTYVoipAndroid.logoutRelayServer()
注: 登录转发服务器, 传入自己 userId, 登录失败或不登录的话, 则后续调用函数将会出错.
sessionId 为校验码, 具体参考 2.4
AppKey 和 AppSecret 是开发者在图鸭科技开发者网站(http://www.tucodec.com/)注
册账号后获取的 AppKey 和 AppSecret
2.2.2 初始化变量, 设置音视频回调, 开始音视频传输
/...此处为初始化变量, 设置音视频回调, 具体请参照 2.3
/** @param
userNa 用户名,( 自定义)
@param
userId userId
*/
//通知转发服务器已准备好上传本地视频流以及下拉他人视频流, 注意 userId 需要先登
录 sta
rtVoip(int videoBitRate, int audioBitRate, int userId)
调用:
mTYVoipAndroid.startVoip(512, 16000, 6)
注: 向服务端推送自己的视频数据, 此时视频流已经开始传输, 他人 add 自身 userId 节点,
便可得到自身传输数据,同样他人 remove 节点便可停止;自己也可以 add、 remove 节点
2.2.3 添加、 删除、 清除节点
/**@param userid 需要添加的节点 Id */
mTYVoipAndroid.removeClientNode(userId)
mTYVoipAndroid.addClientNode(userId)
mTYVoipAndroid.clearClientNodeList()
注: addClientNode(userId)接口, 添加一个发送的对端, 接受对方视频流, 如果对方没有
调用 startVoip(int videoBitRate, int audioBitRate,userId)接口, 则不会受到对方视频流;注意:
双皆需要 add 对方 userId, 如果只有一方 add, 则双方都不会收到对方视频流数据
removeClientNode(userId)接口, 移除一个发送的对端, 移除对方视频流;注意: 建议不
要错误移除未登录的节点.
clearClientNodeLiist()接口, 移除自身 add 的所有对端


2.3 快速集成使用步骤

2.3.1 在 XML 里面写入 TYVoipVideoRender
/**
* TYVoipVideoRender 是 VoIP 客户端的视频渲染视图
* 用于 VoipImage 的显示
*/
//此处为 TYVoipVideoRender 视图类展示(具体构造查看相关类)
public class TYVoipVideoRender extends GLSurfaceView
//在 XML 文件中写入
android:id="@+id/member_render"
android:layout_width="match_parent"
android:layout_height="match_parent">

2.3.2 登录(强烈建议将 TYVoipAndroid 类写成单例模式, 一次初始化, 多次调
用, 否则可能因为多次初始化导致出现问题)
/**
*连接转发服务器
*@param ip @param 端口号@param userId @param sessionId
*@param AppKey @param AppSecret @return !0 即为成功
*/
//登录转发服务器, 注意与 logoutRelayServer 对应, 服务器有网络掉线自动登出处理
// AppKey 和 AppSecret 是开发者
// 在图鸭科技开发者网站(http://www.tucodec.com)
// 注册账号后获取的 AppKey 和 AppSecret
mTYVoipAndroid.loginRelayServer(“192.168.1.1”, “12345”, int userId, int sessionId,
int AppKey, int AppSecret);
2.3.3 设置音视频回调
/**
* VoIP 节点, Key: userId, Value: TYVoipVideoRender
*/
//VoipRender 容器, 每个会议室成员 userId 对应一个 VoipRender 渲染视图
mVoIPPeers = SparseArray()
//音频回调
private TYVoipAndroid.AudioCallback mAudioCallback = new
TYVoipAndroid.AudioCallback() {
@Override
public void audioNotification(int i) {
}
};
//视频回调
private TYVoipAndroid.VideoCallback mVideoCallback = new
TYVoipAndroid.VideoCallback() {
@Override
public void renderVoipVideoData(VoipImage voipImage) {
//如果 image 为本地相机返还数据
if (voipImage.isLocal){
//本地预览视频
mMainRender.pushVideoFrame(voipImage);
}else {
mVoIPPeers.get(voipImage.userId).pushVideoFrame(voipImage);
}
}
};
2.3.4 摄像机, 音频初始化、 参数设置
//初始化 TYVoipAndroid 、 TYVoipVideoCapture
mTYVoipAndroid = new TYVoipAndroid(new Handler(), this,null);//建议将此初始化写入
单例中
private TYVoipVideoCapture mVideoCapture;
//Render 视图, 用于渲染视图
private TYVoipVideoRender mMainRender;
initializationAndSettingParameters() {
/**
* @param callback TYVoipAndroid 对象
* @param param 视频捕捉参数
*/
//初始化本地摄像头
mVideoCapture = TYVoipVideoCapture(mTYVoipAndroid ,
TYVoipVideoCapture.CaptureParam(mTYVoipAndroid.config.videoWidth,
mTYVoipAndroid.config.videoHeight))
/**
* 打开本地视频捕捉设备
* @param frontCamera 是否使用前置摄像头
* @param config VoIP 配置信息
* @param parentView 用于包含
* @return error code 0: 成功
* -1: 相机无法启动
* -2: 相机被禁用
* -3: 打开相机失败
* -4: 没有相机权限
*/
mVideoCapture.start(false, mTYVoipAndroid.config, mMainRender.parent
as ViewGroup)
/**
* 注册音视频回调
*/
mTYVoipAndroid.registerVideoCallback(mVideoCallback)
mTYVoipAndroid.registerAudioCallback(mAudioCallback)
/**
* 初始化 VoIP 客户端
* @param videoCapture video capture object used to open/close camera
*/
mTYVoipAndroid.initVoip(mVideoCapture)
/**
* @param videoBitRate 视频码率 512~2048 kb
* @param audioBitRate 音频采样率 16000 固定值
* @param userid userId
*/
//通知转发服务器已准备好上传本地视频流以及下拉他人视频流, 注意 userId 需要先登录
mTYVoipAndroid.startVoip(512, 16000, userId)

 

2.3.5 开始音视频传输
/** @param userName
用户名,( 自定义)
@param
userId userId
*/
//通知转发服务器已准备好上传本地视频流以及下拉他人视频流, 同时开始自身音视频
传输, 注意 userId 需要先登录
mTYVoipAndroid.startVoip(int videoBitRate, int audioBitRate,userId)
2.3.6 结束 Voip
//停止相机视频捕捉
mVideoCapture.stop()
//结束 Voip 通话
mTYVoipAndroid.stopCall()
//同登录对应, 登出转发服务器
mTYVoipAndroid.logoutRelayServer()
//释放资源
mTYVoipAndroid.release()
2.3.7 流程叙述
回顾整体流程:
1、用户登入,调用 loginRelayServer 函数,传入 ip、port、userId、sessionId
2、调用 startVoip 函数,开始上传视频流,准备下拉视频流
3、得到他人的 userId,添加该节点 addClientNode(userId),获取该节点推流,根据
userId 找到对应 VoipRender 进行渲染。注意:双方皆需要 add 对方 userId,如果只
有一方 add,则双方都不会收到对方视频流数据
4、删除节点 removeClientNode(userId)或清除所有节点 clearClientNodeList(),删
除或结束所有节点推流,对应 VoipRender 停止渲染
5、结束会议,释放资源
2.3.8 其他相关操作
/**
* 切换前后摄像头
*/
mVideoCapture.stop()
mUseFrontCam = !mUseFrontCam
mVideoCapture.start(mUseFrontCam, mVoIPClient.config, mMainRender.parent as
ViewGroup)
/**
* 打开关闭摄像头
*/
if (mEnableCam) {
mVideoCapture.pause()
} else {
mVideoCapture.resume()
} /
**
* 打开、 关闭音效
*/
if (!mSilentMode) {
mVoIPClient.unmuteMicrophone()
} else {
mVoIPClient.muteMicrophone()
}m
SilentMode = !mSilentMode
/**
* @param int rotation 视频旋转角度, 默认为 0
* 参数为 0、 1、 2、 3, 传错值认为传 0
* 分别对应 0 度、 90 度、 180 度、 270 度, 用来调节横竖屏
*/
//设置视频旋转角度
mVideoCapture.setRotation(0);
/**
* @param int gain 声音大小 0~100
* 默认为 50, 可调节
* 传错值默认传入 50
*/
mVoIPClient.setSpeakerGain(50);
/**
* @return bool 是否为前置摄像头
*/
mVideoCapture.isFrontCamera()


2.4 相关函数及参数说明

关于 UserID
每个用户在服务器的唯一标识,服务端用会用 map 存下每个连上的客户端的信息,为了更快的查找,所以这个 UserID 是整形的。 由于是唯一标识,所以每个开发者需要有一个统一的服务器来为每一个登录的客户端分配一个唯一的 UserID,能保证这个 UserID 是全局唯一数字即可,这个 UserID 和开发者对应的客户本身注册的 UserID 无关。

关于 SessionID
考虑一个问题,A 开发者获取了 B 开发者的服务器 IP 和 port,然后拿着 SDK 去向 B 开发者的服务器登录并使用怎么办? B 开发者当然需要拒绝 A 开发者的客户端连接。 怎么拒绝?密码。客户端向服务端请求的时候,不只要告诉服务器他是谁,还要告诉服务器他对应的密码。 so,SessionID 就是完成这个功能的。 开发者的逻辑服务器为每个客户端分配UserID 和对应的 SessionID,客户端拿着 UserID 和 SessionID 到 relay_server 登录,relay_server 把 UserID 和 SessionID 传给开发者的逻辑服务器,逻辑服务器如果验证通过,就返回“1”,其他返回值视为验证失败。
login 接口
login 的功能就是客户端告诉服务器,我是谁。

add 接口
add 接口的设计是添加一个发送的对端,表示我后面采集到的数据都要朝这个人发一份(push 的意思,类似)。这个接口目前的设计是基于双向通信设计的,当你 add 了别人的时候,别人也要 add 你,才能互相收到对方数据,一厢情愿的 add 是不通的。

remove 接口
反 add 接口,不想向对方发送自己数据了就调这个。

2.5 自主设计使用步骤

2.5.1 工程结构


2.5.2 调用函数
(1)音视频数据上传
/**
* @param data yuv420 数据
* @param width 图片长
* @param height 图片宽
* @param front 是否前置摄像头
* @param angle 旋转角度
*/
public void putVideoData(byte[] data, int width, int height, boolean front, int angle);
调用:
TYVoipAndroid.putVideoData(byte[] data, int width, int height, boolean
front, int angle);
(2)音视频数据接收回调
注册回调, 接收对应数据(具体参考 2.3.3):
TYVoipAndroid.registerVideoCallback(mVideoCallback);
(3)将得到的 image 视图渲染到对应 view
注: 需要先 add 对方 userID, 视频流才能回调
若运用包内自带 TYVoipVideoRender 类, 具体参考 2.3, 若自主设计, 将数据渲染到对
应视图即可
注: 以上所有操作都建立在调用 loginRelayServer、startVoip、removeClientNode、
addClientNode、clearClientNodeList 等操作之上,否则无法调用,具体参考 2.3.7

三, 其他 API 参考

/**
* 设置 callback 回调
*/
private native long createContextCallback();
/**
* 注销释放
*/
private native void destroyContext(long context);
private native void destroyContextCallback(long callback);
/**
* 构建网络模块
*/
private native long creatClientNetwork(int sessionID);
/**
* 开关声音
*/
private native void setMuteMicrophone(long context, boolean enable);