Android (Java)
本文以实现视频通话为例,结合 SDK API 和示例代码,介绍如何快速接入。
如需查看完整 SDK API 列表,请点击左侧导航 SDK API 部分。
导入SDK
- 请到 下载中心 下载 Android SDK压缩包。
- 将其解压,获取 Android 目录下的 panortc.aar,将 panortc.aar 放到你的项目中。
- 在 Module 的 build.gradle - dependencies 中,添加:
implementation fileTree(dir: 'sdk_path', include: ['*.aar'])
请将其中 sdk_path 替换为可以定位到 panortc.aar 的实际路径。
配置权限
请在 AndroidManifest.xml 文件的 manifest
标签内添加必要的权限:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />
防止混淆
如果你的项目需要混淆,请在 proguard-rules.pro 文件中配置以下内容防止混淆 Pano SDK。
-keep class com.pano.**{\*;}
-keep class video.pano.**{\*;}
注册通知
通过实现 RtcEngineCallback
接口的回调方法来处理 Pano SDK 返回的通知。
public class MyPanoEngineCallback implements RtcEngineCallback {
public void onChannelJoinConfirm(Constants.QResult qResult) {
// 处理 加入频道 的结果
}
public void onChannelLeaveIndication(Constants.QResult qResult) {
// 处理 离开频道 的结果
}
......
}
- 完整的回调方法介绍,请查看 RtcEngineCallback接口。
- 为结合介绍 SDK 接口,本文会提供部分 示例代码 中的片段,请开发者注意根据实际情况调整。
初始化
通过 RtcEngine
的 create
方法初始化实例。
public static final String APPID = ""; // 替换为你的应用ID
public static final String PANO_SERVER = "api.pano.video";
private RtcEngine mRtcEngine;
// PanoEngineCallback 为"注册通知"章节中创建的 RtcEngineCallback 接口的子类
private PanoEngineCallback mRtcCallback = new PanoEngineCallback();
protected Constants.AudioAecType mAudioAecType = Constants.AudioAecType.Default;
protected boolean mHwAcceleration = false;
RtcEngineConfig engineConfig = new RtcEngineConfig();
engineConfig.appId = APPID; // 应用ID
engineConfig.server = PANO_SERVER; // PANO服务器地址
engineConfig.context = getApplicationContext();
engineConfig.callback = mRtcCallback; // RtcEngineCallback回调对象
engineConfig.audioAecType = mAudioAecType; // 回音消除算法
engineConfig.videoCodecHwAcceleration = mHwAcceleration; // 硬件加速
mRtcEngine = RtcEngine.create(engineConfig);
- 请登录 Pano控制台,点击左侧导航 应用管理 ,查看应用ID(即
appId
)。- 建议在 app 的
Application
的onCreate
中进行初始化。只有当初始化完成后,才可以使用RtcView
显示视频画面。如果尚未初始化就开始在 UI 中使用RtcView
将出现报错。
本地预览
通过 RtcEngine
实例的 setLocalVideoRender
方法设置显示自己画面的视频画布,startPreview
方法开启本地摄像头预览。
// 通常前置摄像头需要开启镜像;mLocalView 类型为 com.pano.rtc.api.RtcView
// 除 setMirror 外,RtcView 还支持 setScalingType 设置视频缩放类型,等
mLocalView.setMirror(mFrontCamera);
mRtcEngine.setLocalVideoRender(mLocalView);
mRtcEngine.startPreview(Constants.VideoProfileType.HD720P, true);
如果设置的分辨率高于摄像头支持的最大分辨率,则自动降低为摄像头支持的最大分辨率。
切换摄像头
通过 RtcEngine
实例的 switchCamera
方法切换摄像头。
mRtcEngine.switchCamera(); // 此方法会同时影响本地预览和发送出去的视频画面
加入频道
加入频道
通过 RtcEngine
实例的 joinChannel
方法加入频道。
RtcChannelConfig config = new RtcChannelConfig();
config.userName = ""; // 用户名,可选参数,可为空,建议配置以区分不同用户
config.mode_1v1 = false; // 一对一模式/会议模式
// serviceFlags 频道标志:音视频 | 白板 (按位或)
// config.serviceFlags = Constants.kChannelServiceMedia | Constants.kChannelServiceWhiteboard;
config.serviceFlags = Constants.kChannelServiceMedia; // 只使用音视频
config.subscribeAudioAll = true; // 自动订阅音频
Constants.QResult ret = mRtcEngine.joinChannel(mAppToken, mChannelId, mUserId, config);
if (ret != Constants.QResult.OK) {
// 加入失败,请根据 QResult 进行处理
}
自己加入频道的通知
调用 joinChannel
方法后,将触发 onChannelJoinConfirm
通知。
public void onChannelJoinConfirm(Constants.QResult qResult) {
// qResult 表示自己加入频道的结果
}
joinChannel
(加入频道) 接口返回的QResult
仅表示调用该接口的结果,而onChannelJoinConfirm
(自己加入频道的通知) 返回的QResult
表示和服务器交互后的结果。
也就是说当onChannelJoinConfirm
返回OK
才表示加入频道成功。
其他用户加入频道的通知
其他用户加入频道后,将触发 onUserJoinIndication
通知。
public void onUserJoinIndication(long userId, String userName) {
// 其他用户加入频道的通知。userId 和 userName 都是该用户在 joinChannel 时传入的
// 此时可以将其加入到与会者列表中
}
倒计时通知
加入频道后,如果存在倒计时限制,将触发 onChannelCountDown
通知。
public void onChannelCountDown(long remain) {
// 频道倒计时通知,单位:秒;请保存用于展示倒计时,此回调仅在加入频道后回调一次
}
- 已实名认证,并且使用正式token,Pano不限制频道时长
- 未实名认证,或者使用临时token,最大频道时长为 30 分钟
操作视频
发送本地视频
通过 RtcEngine
实例的 startVideo
方法发送本地视频。
// 调用此方法后,其他用户才能看到你的画面;请在 onChannelJoinConfirm 回调加入频道成功后再调用
mRtcEngine.startVideo(Constants.VideoProfileType.HD720P, true);
startPreview
(开启本地摄像头预览) 和startVideo
(发送本地视频) 可以设置不同的摄像头(frontCamera
参数),但是通常都应设置相同的摄像头,因为一般都是预览发送出去的画面。startVideo
设置的分辨率表示期望的发送分辨率,实际过程中可能会因硬件支持情况、网络情况和订阅情况触发 SDK 自动调整而降低(后文会介绍订阅)。
停止发送本地视频
通过 RtcEngine
实例的 stopVideo
方法停止发送本地视频。
mRtcEngine.stopVideo(); // 调用此方法后,其他用户将看不到你的画面;本地预览不会被停止
- 当
startPreview
和startVideo
接口设置不同的profileType
参数时,预览分辨率会自动调整为和和实际的发送分辨率一致。当stopVideo
后,预览的分辨率会恢复为startPreview
设置的分辨率。- 当然,前提条件仍然是摄像头支持相应的分辨率,否则会降低为摄像头支持的最大分辨率。
后文同理不再重复介绍。
其他用户开启视频的通知
当其他用户发送视频时,将触发 onUserVideoStart
通知。
public void onUserVideoStart(long userId, Constants.VideoProfileType maxProfile) {
// maxProfile 表示该用户的最大可发送分辨率
// 取决于 摄像头支持的最大分辨率 和 设置的发送分辨率 这两个值中的较小值。
// 即:maxProfile = min{摄像头支持的最大分辨率, 设置的发送分辨率}
// 可以订阅低于 maxProfile 的 VideoProfileType ,以节省性能、带宽、流量和费用
// 例如,当应用场景需要同时展示多个远端小画面时,可以向远端订阅一个较低的分辨率
}
订阅其他用户的视频
通过 RtcEngine
实例的 subscribeVideo
方法订阅其他用户的视频,通过 setRemoteVideoRender
方法设置显示其他用户画面的视频画布。
// 请在收到其他用户的 onUserVideoStart 通知后,再调用订阅;返回 OK 表示接口调用成功,否则表示失败
Constants.QResult ret = mRtcEngine.subscribeVideo(userId, profileType);
mRtcEngine.setRemoteVideoRender(userId, render);
- Pano采用订阅模式来接收视频,参与者之间需要相互订阅,才可以看到彼此的视频画面。
- 默认 正式token 最多可以订阅 6 路视频,临时token 最多可以订阅 3 路视频。
- 使用
RtcVideoStreamManager
的开发者,请换用RtcVideoStreamManager.subscribeVideo
方法来订阅其他用户的视频流。
订阅视频结果通知
当订阅其他用户的视频后,会触发 onUserVideoSubscribe
通知。
public void onUserVideoSubscribe(long userId, Constants.MediaSubscribeResult result) {
// 处理订阅视频结果通知,Success 表示成功
}
subscribeVideo
接口返回的QResult
仅表示调用该接口的结果,而onUserVideoSubscribe
返回的MediaSubscribeResult
表示和服务器交互后的结果。
也就是说,onUserVideoSubscribe
返回Success
才表示订阅成功。- 如果重复调用 订阅其他用户的视频 接口,只会在第一次调用时触发 订阅视频结果通知。如果取消订阅再重新订阅,视为第一次调用,可正常触发一次 订阅视频结果通知。
收到其他用户视频的通知
当收到其他用户的视频时,将触发 onFirstVideoDataReceived
通知。
public void onFirstVideoDataReceived(long userId) {
// 收到其他用户的首个视频数据包
}
取消订阅其他用户的视频
通过 RtcEngine
实例的 unsubscribeVideo
方法取消订阅其他用户的视频。
mRtcEngine.unsubscribeVideo(userId); // 调用此方法后,你将看不到该用户的画面
- 当其他用户停止视频或者离开频道的时候,将被自动取消订阅。
- 取消订阅后重新订阅的情况,如果使用同一
render
,无须重新调用setRemoteVideoRender
方法。- 使用
RtcVideoStreamManager
的开发者,请换用RtcVideoStreamManager.unsubscribeVideo
方法来取消订阅。
操作声音
发送本地声音
通过 RtcEngine
实例的 startAudio
方法发送本地声音。
mRtcEngine.startAudio(); // 调用此方法后,其他用户才能听到你的声音;请在加入频道成功后再调用
停止发送本地声音
通过 RtcEngine
实例的 stopAudio
方法停止发送本地声音。
// 调用此方法后,其他用户将听不到你的声音
// 不影响你接收其他用户的声音
// 可以调用 startAudio 重新发送
mRtcEngine.stopAudio();
有三种方式将自己静音(不让其他用户听到你的声音):1 停止发送本地声音,2 静音本地麦克风,3 静音本地麦克风(系统层操作)
它们的区别在于:
1 "停止发送本地声音"会断开音频通道连接(同时停止发送麦克风和伴音的声音,会取消其他用户订阅你的声音,如需重建连接需要消耗时间)
2 "静音本地麦克风"会发送静音包(不影响伴音发送,不影响订阅关系,临时静音建议使用此方式,取消静音能够迅速恢复发送声音)
3 "静音本地麦克风(系统层操作)"会调用系统接口设置底层硬件状态,一般情况不建议使用,因此本文不介绍该接口
静音
通过 RtcEngine
实例的 muteAudio
方法静音本地麦克风。
mRtcEngine.muteAudio(); // 调用此方法后,其他用户将听不到你的声音;可以调用 unmuteAudio 取消静音
取消静音
通过 RtcEngine
实例的 unmuteAudio
方法取消静音本地麦克风。
mRtcEngine.unmuteAudio(); // 静音后,需要取消静音,其他用户才能听到你的声音
其他用户开启声音的通知
当其他用户发送声音时,将触发 onUserAudioStart
通知。
public void onUserAudioStart(long userId) {
...
}
订阅其他用户的声音
如果在 joinChannel
(加入频道)时,配置了自动订阅音频(例如:config.subscribeAudioAll = true
),则开发者无需再主动订阅其他用户的声音。否则,需要通过 RtcEngine
实例的 subscribeAudio
方法订阅其他用户的声音。
// 如果 加入频道 时配置了自动订阅音频,则无需调用此接口
// 请在收到其他用户的 onUserAudioStart 通知后,再调用订阅
mRtcEngine.subscribeAudio(userId);
- 如果希望在通话过程中,不收听某位与会者,或者不收听所有其他与会者,请在加入频道时,设置不自动订阅音频;随后按需订阅或取消订阅某位或所有其他与会者。
订阅声音结果通知
当主动订阅其他用户的声音后,会触发 onUserAudioSubscribe
通知。
public void onUserAudioSubscribe(long userId, Constants.MediaSubscribeResult result) {
// 处理订阅声音结果通知,Success 表示成功
}
subscribeAudio
接口返回的QResult
仅表示调用该接口的结果,而onUserAudioSubscribe
返回的MediaSubscribeResult
表示和服务器交互后的结果。
也就是说,onUserAudioSubscribe
返回Success
才表示订阅成功。- 如果配置了自动订阅音频,则不会触发此通知。
收到其他用户声音的通知
当收到其他用户的声音时,将触发 onFirstAudioDataReceived
通知。
public void onFirstAudioDataReceived(long userId) {
// 收到其他用户的首个声音数据包
}
取消订阅其他用户的声音
通过 RtcEngine
实例的 unsubscribeAudio
方法取消订阅其他用户的声音。
mRtcEngine.unsubscribeAudio(userId); // 调用此方法后,你将听不到该用户的声音
当其他用户停止声音或者离开频道的时候,将被自动取消订阅。
离开频道
离开频道
通过 RtcEngine
实例的 leaveChannel
方法离开频道。
mRtcEngine.leaveChannel();
其他用户离开频道的通知
其他用户离开频道后,将触发 onUserLeaveIndication
通知。
onUserLeaveIndication(long userId, Constants.UserLeaveReason reason) {
// 可将其从与会者列表中移除
};
至此,Android 快速接入已介绍完毕。
SDK API 指南
本文仅介绍接入Pano Android SDK实现视频通话的基本流程和接口。
实际场景需要结合使用更多接口,请 点此查看 API 列表。
示例代码
为方便开发者了解丰富的接口使用方式,我们还提供示例代码,请 体验参考。