API 描述
Android 平台提供 Native C API (C/C++ 远端设备 SDK API) 和 Java API。本文档为 Java API, 适用于 Android 系统,使用时请先引用 Android SDK aar 包。
SDK 集成说明
开发环境要求
Android Studio 2.0+。
Android 5.0(SDK API 21)及以上系统。
SDK 引用及依赖配置
1. 将 AAR 文件复制到工程目录下(例如:app/libs)
2. 在 gradle 文件中增加依赖配置:
dependencies {implementation fileTree(dir: 'libs', include: ['*.aar']) //添加 SDK 依赖implementation 'com.google.code.gson:gson:2.8.9' //添加gson依赖}
权限配置
<uses-permission android:name="android.permission.INTERNET" />
混淆配置
-keep class com.tencent.trro.**{*;}
API 概览
TRRORemote
SDK 主入口。
API 方法 | 描述 |
获取 SDK 单例。 | |
注册 SDK 事件监听。 | |
使用 TrroOptions 配置类启动 SDK。 | |
使用 JSON 字符串配置启动 SDK。 | |
设置临时会话授权,用于连接现场设备临时会话身份验证。 | |
连接现场设备视频流。 | |
获取在线现场设备列表(单线程调用,同步阻塞)。 | |
关闭指定视频连接。 | |
关闭所有视频连接。 | |
给现场设备发送控制数据。 | |
发送自定义音频数据,需要配置开启使用外部音频 "audio_external": 1。 | |
现场设备音频设置。 | |
向现场设备发出权限请求。 | |
更新现场设备目标视频流编码参数。 | |
开始录制视频。 | |
停止录制视频。 | |
释放 SDK 资源。 | |
获取 SDK 版本号。 |
getInstance
获取 SDK 单例:
public static TrroRemote getInstance()
setListener
public void setListener(TrroRemoteListener listener)
initWithOptions
//基于ApplicationContext和TrroOptions初始化public int initWithOptions(Context context, TrroOptions trroOptions)
参数 | 描述 |
context | Android ApplicationContext |
TrroConnectParam |
initWithJson
public int initWithJson(Context context, String jsonStr)
参数 | 描述 |
context | Android ApplicationContext |
jsonStr | 注意:证书已内置 SDK 中,不需要再配置 certificate 字段。 |
setSessionPermissionToken
设置临时会话授权,用于连接现场设备时的临时会话身份验证。返回值:成功1 失败<=0。
public int setSessionPermissionToken(String gwid, String signature)
参数 | 描述 |
gwid | 目标会话现场设备 ID。 |
signature | 基于项目共享密钥签发的临时会话授权签名。 |
connect
发起单路视频连接,可多次调用连接不同流。异步模式,根据 onState 状态回调确认视频连接成功,连接多路视频流也可以用下面多路视频流连接接口。
public void connect(String gwid, TrroConnectParam connectParam)
参数 | 描述 |
gwid | 现场设备 ID(要拉取视频流的推流设备 ID),公有云格式为 projectId/deviceId,私有云格式为 deviceId。 |
TrroConnectParam |
connect
发起多路视频连接,异步模式,根据 onState 状态回调确认视频连接成功。
public void connect(String gwid, List<TrroConnectParam> connectParamList)
参数 | 描述 |
gwid | 目标连接的现场设备 ID,需添加 projectid 前缀。 格式:projectid/gwid 例如:ebesyladhdhs8txj/cam_logitech |
connectParamList | 连接参数列表,配置每一路视频参数。 |
getGwList
public GateWayList getGwList()
getGwInfo
获取网关详细信息,接口为同步阻塞模式。返回值网关详细信息对象。
public GwInfo getGwInfo(String gwid)
disconnect
关闭指定视频连接, 返回值:成功 1 失败 <= 0。
public int disconnect(int connFd)
参数 | 描述 |
connFd | 要关闭视频连接对应的接收句柄。 |
disconnectAll
关闭所有视频连接,返回值:成功 1 失败 <= 0。
public int disconnectAll()
sendControlData
给现场设备发送控制数据。消息限制为每条大小1KB, 每秒<100条,每秒总大小<100KB。
public int sendControlData(String gwid, byte[] msg, int qos)
参数 | 描述 |
gwid | 目标连接的现场设备 ID。 |
msg | 消息内容,二进制透传。 |
qos | 消息传输 qos 。 0 超低延迟高频传输, 适合高频远控消息,消息大小<1KB。 1 可靠传输,网络不好时可能产生消息堆积,适合低频重要消息,消息大小<10KB。 |
externalAudioData
外部输入音频数据,需要配置"audio_enable": 1 并开启外部音频输入"audio_external": 1,此时SDK音频采集会关闭并使用外部输入的音频数据。
public int externalAudioData(String gwid, byte[] data, int channel, int sampleRate)
参数 | 描述 |
gwid | 目标连接的现场设备 ID。 |
data | 音频 PCM 数据,16bit采样,10ms长度。 |
channel | 音频声道数。 |
sampleRate | 音频采样率。 |
audioMute
现场设备音频设置, 返回值:成功 1 失败 <= 0。
public int audioMute(String gwid, boolean mute)
参数 | 描述 |
gwid | 目标连接的现场设备 ID。 |
mute | true:静音。 false:取消静音。 |
requestPermission
向网关发出权限请求,返回值:成功 1 失败 <= 0
public int requestPermission(String gwid, int permission)
参数 | 描述 |
gwid | 目标连接的现场设备 ID。 |
permission | 0 guest,只有观看权。 1 master, 完全控制权限。 |
fieldDeviceEncodeConfig
更新现场设备目标视频流编码参数, 返回值:成功 1 失败 <= 0
public int fieldDeviceEncodeConfig(String gwid, int streamId, String encodeConfig)
参数 | 描述 |
gwid | 目标连接的现场设备 ID。 |
streamId | 目标视频流编号。 |
encodeConfig | 待更新的编码参数 ,JSON 格式字符串,缺省字段将保持当前值不进行更新,下面是更新支持的编码参数示意。
|
startRecord
开始录制视频。
参数 | 描述 |
connFd | 视频接收句柄。 |
filePath | 视频储存路径。 |
stopRecord
停止录制视频。
参数 | 描述 |
connFd | 视频接收句柄 |
destroy
释放SDK资源,在程序退出时可以主动释放 SDK 资源,并退出用户登录。
public void destroy()
getSDKVersion
获取 SDK 版本号信息。
public static String getSDKVersion()
TrroRemoteListener
SDK 事件监听回调接口。
回调API | 描述 |
onSignalState | 信令连接状态回调(与登录状态相关)。 |
onState | 视频流连接状态回调。 |
onMediaState | 视频流传输状态回调。 |
onAllLatencyCallback | 时延回调。 |
onReportData | 接收来自现场设备信息回调。 |
onFieldSideMediaState | 现场设备视频流传输网络状态回调。 |
onRemoteFrameData | 解码后视频图像回调(仅开启实验性参数使用强制软解时)。 |
onRemoteEncodedFrame | 编码帧回调。 |
onError | 错误信息回调。 |
onOperationPermissionState | 回调现场设备操控权限状态通知。 |
onRemoteMixAudioFrame | 接收的音频混流数据回调。 |
onSignalState
信令连接状态回调
void onSignalState(int signalState)
参数 | 描述 |
signalState | 信令连接状态。 0 连接建立成功 (初始化首次连接成功)。 1 连接断开,内部会进行自动重连。 2 自动重连成功 。 3 被踢下线 (已有相同用户登录)。 4 用户名或者密码错误。 |
onState
视频流连接状态回调。
void onState(String gwid, int streamId, int connFd, int state)
参数 | 描述 |
gwid | 现场设备 ID。 |
streamId | 现场设备视频流 ID。 |
connFd | 视频接收句柄。 |
state | 视频流连接状态。 0:未连接 1:连接中 2:已连接 3:正在断开连接 |
onMediaState
视频流传输状态回调
void onMediaState(int connFd, int fps, int bps, int rtt, long decd, int jitter, long packetsLost, long packetsReceived, int stun)
参数 | 描述 |
connFd | 连接 FD。 |
fps | 每秒帧数。 |
bps | 每秒数据量。 |
rtt | ping 网络往返时间。 |
decd | 解码耗时,单位:毫秒。 |
jitter | 接收抖动值。 |
packetsLost | 丢包, 丢包率 = packetsLost / 255.0 * 100%。 |
packetsReceived | 总接收包数。 |
stun | 穿网模式。 0:host 1:srflx 2:prflx 3:relay |
onAllLatencyCallback
时延回调
void onAllLatencyCallback(String gwid, int connFd, long latency1, long latency2, long videotime, int rcct)
参数 | 描述 |
gwid | 现场设备 ID。 |
connFd | 视频接收句柄。 |
latency1 | SDK 估计的视频传输时延 ms。 |
latency2 | 视频传输 + 消息下发时延 ms,可认为是远程操控相对本地操控的时延。 |
videotime | 当前视频帧的现场设备采集时间戳。 |
rcct | 消息往返时延ms。 |
onReportData
接收来自现场设备消息回调
void onReportData(String gwid, byte[] msg, int len)
参数 | 描述 |
gwid | 现场设备 ID。 |
msg | 消息内容,二进制透传。 |
qos | 消息来源传输 qos。 0:低延迟高频传输。 1:可靠传输。 |
onFieldSideMediaState
现场设备视频流传输状态回调。
void onFieldSideMediaState(String gwid, int streamId, int fps, int bps, int rtt, int jitter,int lost);
参数 | 描述 |
gwid | 现场设备 ID。 |
streamId | 视频流 ID。 |
fps | 每秒帧数。 |
bps | 每秒数据量,单位 kbps。 |
rtt | 网络往返时间 ms。 |
jitter | 网络延迟抖动值。 |
lost | 丢包, 丢包率 = packetsLost / 255.0 * 100%。 |
onRemoteFrameData
原始视频图像回调,可获取视频 YUV 数据(CPU 内存),用于自定义渲染或者图像处理等场景(仅在开启强制软解时生效)。考虑 Android 平台性能加速优化,一般优先推荐通过 connect 接口的视频输出纹理(GPU内存)来获取原始视频数据。
void onRemoteFrameData(String gwid, int streamId, int connFd, ByteBuffer data, int width,int height, long videoTime);//需要开启强制软解,connect时不使用视频输出纹理ExperimentOptions experimentOptions = new ExperimentOptions.Builder().enableSoftwareDecoder(true).printDecodeTime(false).build();TrroRemote.getInstance().callExperimentApi(experimentOptions);
参数 | 描述 |
gwid | 现场设备 ID。 |
streamId | 现场设备流 ID。 |
connFd | 视频接收句柄。 |
data | 视频帧数据,YUV I420格式。 |
width | 视频帧宽。 |
height | 视频帧高。 |
videoTime | 当前视频帧时间戳。 |
onRemoteEncodedFrame
视频编码数据帧回调。
void onRemoteEncodedFrame(String gwid, int streamId, int connFd, byte[] data, int len,int trroCodec, boolean isKeyFrame, int width, int height, long videoTime);
参数 | 描述 |
gwid | 现场设备 ID。 |
streamId | 现场设备流 ID。 |
connFd | 视频接收句柄。 |
data | 编码的视频图像帧数据。 |
len | 编码的视频图像帧的长度。 |
trroCodec | 编码的 codec 类型。 0:H264 1:H265 |
isKeyFrame | 是否是关键帧。 |
width | 视频帧宽(硬解有效)。 |
height | 视频帧高(硬解有效)。 |
videoTime | 当前视频帧时间戳。 |
onError
错误信息回调。
void onError(int errorCode, String errorMsg)
参数 | 描述 |
errorCode | 错误码。 |
errorMsg | 错误信息描述。 |
onOperationPermissionState
回调现场设备操控权限状态通知,只有拥有 master 权限时才能发送消息给对应现场设备。
void onOperationPermissionState(String fieldDevId, int selfPermission, String masterDevId)
参数 | 描述 |
fieldDevId | 来源现场设备 ID。 |
selfPermission | 本设备当前的操控权限 0 是 guest,只有观看权限。 1是 master,拥有完全控制权限。 |
masterDevId | 拥有 master 权限的远端设备 ID。 |
onRemoteMixAudioFrame
接收的音频混流后 PCM 数据回调, 需要配置开启音频接收"audio_receive": 1 并使用外部音频播放(SDK 不播放音频)"audio_play": "outside"。
void onRemoteMixAudioFrame(byte[] data, int length, int channel, int sampleRate)
参数 | 描述 |
data | PCM 音频数据,16bit采样,10ms长度。 |
length | 音频数据长度。 |
channel | 音频声道数。 |
sampleRate | 音频采样率。 |
TrroOptions
TrroConnectParam
视频流连接配置参数。
属性 | 描述 |
streamId | 现场设备视频流的 ID 数组, 现场设备视频流 ID 从0开始, 最大值为现场设备支持的 device_streams 数量 -1。 |
connFd | 接收视频流的句柄标识,自行编号,取值从0开始。 |
videoView | 视频流输出到视频流显示控件。 |
previewTexture | 视频流输出到 SurfaceTexture,可用于离屏渲染,优先建议使用 Surface。 |
surface | 视频流输出到 Android Surface 实例,可用于自定义渲染等。 |
注意:
videoView、previewTexture 和 surface 同时只能设置一个。如果都不设置则 SDK 只回调对应视频流的视频帧数据,不会进行渲染(含离屏渲染)。
TXCloudVideoView
视频流显示控件,可设置隐藏或展示。
API | 描述 |
setFillMode | 设置视频画面填充模式。 0:填充(画面可能会被拉伸裁剪) 1:适应(显示完整画面,可能会有黑边) 默认值:1 |
useTextureView | 设置视频显示使用 TextureView 或 SurfaceView。 true:使用 TextureView false:使用 SurfaceView 默认值:false |
GateWayList
现场设备列表。
属性 | 描述 |
ret | 0 获取成功。 |
msg | 获取结果描述。 |
count | 在线设备总数。 |
gateways | 在线设备列表,GateWay 数组。 |
GateWay
现场设备。
属性 | 描述 |
name | 设备名称。 |
type | 设备类型。 |
status | 设备状态,ready 在线等待 / connected 会话中。 |
streams | 视频流数量。 |
timestamp | 时间戳。 |
version | 设备 SDK 版本。 |
示例代码
SDK 初始化
//采用trroOptions初始化,也可采用json接口初始化(注意android平台不需要certificate和output_path配置)TrroOptions trroOptions = new TrroOptions.Builder().deviceId(mDeviceId).projectid(mProjectId).password(mPassword)//日志级别,0:关闭,1,输出部分运行日志,2:输出详细运行日志.logEnable(2).cloudMode("public").deviceName(mDeviceName).setMaxStreams(8).build();//启动SDK,阻塞接口,建议在工作线程中调用TrroRemote.getInstance().initWithOptions(getApplicationContext(), trroOptions);
连接视频流
//在layout文件中,配置视频流显示控制<com.tencent.trro.rtmp.ui.TXCloudVideoViewandroid:id="@+id/txcvv_1"android:layout_width="match_parent"android:layout_height="match_parent"/>//第1路视频连接信息配置TrroConnectParam connectParam1 = new TrroConnectParam.Builder().connFd(0) //connFd,分配一个唯一ID,建议从0开始.streamId(0) //现场设备视频流的ID数组, 现场设备视频流ID从0开始.videoView(txCloudVideoView1) //视频流显示控件.build();//第2路视频连接信息配置TrroConnectParam connectParam2 = new TrroConnectParam.Builder().connFd(1).streamId(1).videoView(txCloudVideoView2).build();List<TrroConnectParam> trroConnectParamList = new ArrayList<>();trroConnectParamList.add(connectParam1);trroConnectParamList.add(connectParam2);//调用connect方法连接现场设备视频流TrroRemote.getInstance().connect(mGateWayId, trroConnectParamList);
事件回调监听
//在Activity生命周期函数中设置监听器,比如onStart方法设置监听,在onStop方法取消监听TrroRemote.getInstance().setListener(this);
资源释放
//在退出时释放资源,比如Activity的onDestroy方法中调用TrroRemote.getInstance().destroy();