Android Java API

最近更新时间:2025-09-01 15:27:51

我的收藏

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。
设置临时会话授权,用于连接现场设备临时会话身份验证。
connect
连接现场设备视频流。
getGwList
获取在线现场设备列表(单线程调用,同步阻塞)。
关闭指定视频连接。
关闭所有视频连接。
给现场设备发送控制数据。
发送自定义音频数据,需要配置开启使用外部音频 "audio_external": 1。
audioMute
现场设备音频设置。
向现场设备发出权限请求。
更新现场设备目标视频流编码参数。
开始录制视频。
停止录制视频。
destroy
释放 SDK 资源。
获取 SDK 版本号。

getInstance

获取 SDK 单例:
public static TrroRemote getInstance()

setListener

注册 SDK 事件监听,可获取网关连接状态、媒体信息等,详细参见本文档 TrroRemoteListener 说明。
public void setListener(TrroRemoteListener listener)

initWithOptions

使用 TrroOptions 配置类启动 SDK,接口为同步阻塞模式,等待信令连接成功后返回。返回值:成功 1 失败 <= 0,详细错误码参见 错误码及排查
//基于ApplicationContext和TrroOptions初始化
public int initWithOptions(Context context, TrroOptions trroOptions)
参数
描述
context
Android ApplicationContext
TrroConnectParam
初始化配置,参见本文档 TrroOptions 说明。

initWithJson

使用 JSON 配置启动SDK,接口为同步阻塞模式,等待信令连接成功后返回。返回值:成功 1 失败 <= 0,详细错误码参见 错误码及排查
public int initWithJson(Context context, String jsonStr)
参数
描述
context
Android ApplicationContext
jsonStr
初始化配置 JSON 字符串,详细参见 远端设备配置说明
注意:证书已内置 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
连接参数,参见本文档中 TrroConnectParam 说明。

connect

发起多路视频连接,异步模式,根据 onState 状态回调确认视频连接成功。
public void connect(String gwid, List<TrroConnectParam> connectParamList)
参数
描述
gwid
目标连接的现场设备 ID,需添加 projectid 前缀。
格式:projectid/gwid
例如:ebesyladhdhs8txj/cam_logitech
connectParamList
连接参数列表,配置每一路视频参数。

getGwList

获取在线现场设备设备列表,接口为同步阻塞模式。返回值参见本文档 GateWayList
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 格式字符串,缺省字段将保持当前值不进行更新,下面是更新支持的编码参数示意。
{
"fps": 30,
"encode_width": 1920,
"encode_height": 1080,
"bps": 3000,
"min_fps": 30,
"min_bps": 1800,
"force_min": 0,
"min_width": 1920
}

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.TXCloudVideoView
        android: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();