开发前准备_实时音视频 SparkRTC_客户端SDK参考_Electron SDK_华为云

(1)

SDK 参考

文档版本 01

发布日期 2022-02-25

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

(3)

1 ^{使用前必读}

1.1 主要功能

1.2 文档基本使用技巧 1.3 常见问题分析解决办法

1.1 主要功能

SparkRTC主要包含基本房间功能和跨房功能，各端主要功能框架，如图1-1所示。

说明：图1-1中仅展示各端的统一功能，独属功能详见各端SDK指导。

图1-1 功能框架

(9)

表1-1 功能说明

类别功能分类功能说明基本

功能

初始化等基础接口

主要功能包括创建/销毁RTC引擎、设置日志保存位置等。

房间功能主要功能包括进入/离开房间操作、设置角色、创建跨房引擎等。

音频管理主要功能包括是否采集/发送本地音频流、是否接收远端音频流、调整录制/播放音量值、设置远端音频模式等。

视频管理主要功能包括创建本地/远端窗口视图和其他参数设置、是否接收远端视频流、镜像、摄像头等。

屏幕共享主要功能包括是否开始/停止订阅辅流、设置辅流渲染模式/角度等。

音效文件

播放管理主要功能包括开始/停止/暂停/恢复播放音频或音效文件、音频/音效音量相关设置。

检测功能主要功能包括启动/关闭入会前网络检测。

自定义音频采集和渲染

主要功能包括是否开启音频自采集、推送外部音频数据。

自定义视频采集和渲染

主要功能包括是否开启视频自采集、推送外部视频数据、是否开启视频流自渲染。

设备管理主要功能包括切换摄像头、声音播放模式等。

跨房功能

跨房间连麦，指主播的媒体流可以同时转发进多个房间频道，实现主播跨频道与其他主播实时互动的场景。房间中的所有主播可以看见彼此，房间中的观众可以看到所有主播。同一时间最多只能同时跨4个房间，每个跨房房间的ID必须互不相同；同一时间只能以一个joiner角色加入某一个房间。

如果本端在其他房间里的角色是joiner，则需要将本端在该房间内的player 角色切换为joiner角色后再以joiner角色跨入其他房间。以player角色跨房后只能收流不能发流，以joiner角色跨房后既能收流也能发流。

1.2 文档基本使用技巧

● 技巧1：基本使用逻辑说明

用时序图展示各端接口使用顺序，单击相应接口可以快速查看相关接口使用方法。

● 技巧2：接口总览说明

包括SparkRTC接口总体功能流程图和接口列表，根据功能分类可以快速查找具体功能单个接口，方便接口对接。

● 技巧3：单个接口使用须知

接口使用时注意使用的时机、参数说明。“注意”是强调每个接口使用的注意事项并带有调用该接口的相关回调，对接时需要仔细阅读。

(10)

1.3 常见问题分析解决办法

● 问题1：调用setVideoEncoderConfig接口时，为什么有些参数直接报参数设置错误？

设置分辨率时请使用华为SDK系统推荐的码表才能设置成功。

● 问题2：有哪些原因会导致跨房不成功？

– 可能原因1：同一时间不同房间最多只有一个Joiner角色才能跨房成功。

– 可能原因2：同一时间最多只能跨4个房间，跨房对应的房间ID必须互不相同。

● 问题3：使用远端音频模式为HRTC_REMOTE_AUDIO_SUBSCRIBED时，如何设置才能默认听不到远端用户的声音？

HRTC_REMOTE_AUDIO_SUBSCRIBED为自主订阅，需要用户手动调用订阅。在加入房间（joinRoom）时调用带有HRTCJoinParam类的方法，创建该类实例后 autoSubscribeAudio属性设置为false进入房间后则听不到远端用户的声音，需要手动调用muteRemoteAudio根据uid单个用户订阅才能听到声音。

● 问题3：为什么onVideoStats、onAudioStatus、

onAuxiliaryStreamStatsNotify回调触发时程序崩溃？

回调函数的入参localStats和remoteStats指针有可能为空，需要先判断不为空再使用，否则可能引发空指针错误。

● 问题4：为什么本端听筒能听到自己的声音？

调用muteRemoteAudio时，参数设置为自己的uid就会发生此类情况。

● 问题5：setExternalAudioCapture（音频自采集）、setExternalVideoCapture

（视频自采集）能在房间内开启吗？

不能，需要在加入房间前调用。

(11)

2 ^{SDK 概述}

华为云实时音视频服务软件开发工具包是对SparkRTC服务提供的REST API进行的封装，以简化用户的开发工作。用户直接调用SparkRTC SDK提供的接口函数即可实现使用SparkRTC服务业务能力的目的。

相关开发包请参见SDK下载获取。

同时，针对不同平台的SDK提供了集成和接口参考。详细介绍了SDK的集成操作、接口参数定义和代码示例。SparkRTC提供了以下主流平台SDK供开发者使用。

客户端集成SDK 接口参考

Android

Android SDK集成 Android SDK接口参考

iOS

iOS SDK集成 iOS SDK接口参考

MAC

MAC SDK集成 MAC SDK接口参考

Windows

Windows SDK集成 Windows SDK接口参考

Web

Web SDK集成 Web SDK接口参考

Electron

Electron SDK集成 Electron SDK接口参考

(12)

3 Android SDK

3.1 开发前准备 3.2 SDK使用 3.3 基本使用逻辑 3.4 接口参考 3.5 常见问题 3.6 修订记录

3.1 开发前准备

环境要求

Android SDK需要集成到APP工程中，建议您在如下推荐环境中进行集成开发。

● 准备Android Studio或者Eclipse集成开发环境，推荐使用Android Studio 3.3.2及以上。

● 准备Android运行环境：API 21、Android 5.0以上设备。

● 支持的终端CPU架构：armeabi-v7a、arm64-v8a。

说明

手机的CPU架构可通过以下方式查询。

手机开启USB调试，连接上电脑，然后打开Windows操作系统中的cmd程序，输入如下命令：

adb shell getprop ro.product.cpu.abi

SDK 集成

步骤1 解压Android SDK包。

步骤2 将Android SDK包中的“hwRtcSdk.aar”等aar文件，导入Android Studio工程的libs文件夹下。

步骤3 在“/app/build.gradle”文件中设置aar存放路径，并设置依赖本地aar。

// aar存放路径 android{

(13)

repositories { flatDir { dirs 'libs' } }}

// 依赖本地aar dependencies {

implementation fileTree(include: ['*.jar'], dir: 'libs') implementation(name: 'hwRtcSdk', ext: 'aar') }

步骤4 将如图3-1所示的包含so库的两个文件夹导入到jniLibs文件夹中。

图3-1 so 库目录

步骤5 在“/app/build.gradle”文件中设置so库的存放路径。

sourceSets { main {

jniLibs.srcDirs = ['src/main/jniLibs']

} }

步骤6 在“app/src/main/res/values/strings.xml”文件中配置appId，其中，appId请提交工单申请。

<string name="setting_appId_title" translatable="false">appId</string>

步骤7 在“/app/src/main/AndroidManifest.xml”文件中配置App权限。

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.RECORD_AUDIO" />

<uses-permission android:name="android.permission.CAMERA" />

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<uses-permission android:name="android.permission.BLUETOOTH" />

步骤8 单击“Sync Project With Gradle Files”，同步项目文件，完成SDK集成。

----结束

3.2 SDK 使用

步骤1 创建引擎。

HRTCEngineConfig config = new HRTCEngineConfig();

config.setAppId(appId); // 测试体验阶段可以使用官方提供的测试AppId config.setCountryCode(countryCode); // 如无特殊需求，请填空字符串，即""

config.setContext(getApplicationContext()); // 上下文，请传入Application Context config.setDomain(webSocketFalvor); // 该字段已废弃，不需要再传值

config.setMuteAudioRoute(isMuteAudioRoute);

config.setLogEnable(true);

config.setLogSize(logSize);

config.setLogLevel(logLevel);

config.setLogPath(logPath); // logPath为目录，非文件

mHwRtcEngine = HRTCEngine.create(config, mHwHandler); // mHwHandler继承自 IHRTCEngineEventHandler，用于监听各种回调事件

步骤2 设置本地窗口。

SurfaceView surface = HRTCEngine.createRenderer(getApplicationContext()); // 不可使用new SurfaceView(context)创建

(14)

mHwRtcEngine.setupLocalView(surface,

HRTCEnums.HRTCVideoDisplayMode.HRTC_VIDEO_DISPLAY_MODE_HIDDEN);

步骤3 加入房间。调测阶段直接使用appId加入，正式商用阶段建议使用签名鉴权。

HRTCJoinParam joinParam = new HRTCJoinParam();

joinParam.setUserId(mUserId); // userId用于标识同一房间的不同用户

joinParam.setUserName(mUserName); // 用户昵称，如无特殊需求，保持和userId一致即可 joinParam.setRole( HRTCJoinParam.HRTCRoleType.HRTC_ROLE_TYPE_JOINER);

joinParam.setRoomId(roomid);

joinParam.setScenario(1);

joinParam.setOptionalInfo(optionInfo);

joinParam.setAuthorization(signature); // 开启鉴权，则必填，否则不填 joinParam.setCtime(ctime); // 开启鉴权，则必填，否则不填

joinParam.setAutoSubscribeVideo(false);

joinParam.setAutoSubscribeAudio(true);

mHwRtcEngine.joinRoom(joinParam );

joinParam：入会参数，包含用户ID、用户名、房间号、认证信息、ctime、是否自动订阅音频和视频、SFU类型、场景和用户角色，具体请参见HRTCJoinParam。

步骤4 监听远端用户加入房间，并设置远端窗口。

@Override

public void onRemoteUserOnline(String roomId, final String userId, String nickname) { if (userId.equals(mUserId)||mRole == HRTC_ROLE_TYPE_JOINER.ordinal()) { return;

}

Log.e(TAG, "onRemoteUserOnline userId: " + userId);

runOnUiThread(new Runnable() { @Override

public void run() {

Toast.makeText(LiveActivity.this, userId + "加入了房间", Toast.LENGTH_SHORT).show();

SurfaceView surface = HRTCEngine.createRenderer(getApplicationContext());

mHwRtcEngine.startRemoteStreamView(userId,surface, HRTCEnums.HRTCStreamType.HRTC_STREAM_TYPE_HD);

mHwRtcEngine.updateRemoteRenderMode(userId,HRTCEnums.HRTCVideoDisplayMode.HRTC_VIDEO_DISPL AY_MODE_Fit);

// 将userId对应surface添加到布局中 }

});

}

步骤5 监听远端用户离开房间，并删除远端窗口。

@Override

public void onRemoteUserOffline(String roomId, final String userId, int reason) {

Log.i(TAG, "HwRtcDemo onRemoteUserOffline roomId:" + roomId + ", userId:" + userId + ", reason:" + reason);

runOnUiThread(new Runnable() { @Override

public void run() {

Log.e(TAG, "HwRtcDemo run removeRemoteUser! ");

Toast.makeText(LiveActivity.this, userId + "离开了房间", Toast.LENGTH_SHORT).show();

mHwRtcEngine.stopRemoteStreamView(userId);

// 将userId对应的surface从布局中移除 }

});

}

步骤6 离开房间。

mHwRtcEngine.leaveRoom();

finish();

步骤7 销毁引擎

HRTCEngine.destroy();

----结束

(15)

3.3 基本使用逻辑

(16)

(17)

1. 创建新的项目工程，导入SDK后，需要先创建引擎。

2. 您可以在入会前进行视频编码、声音播放模式等参数的配置。

3. 设置本地视图。

4. 用户加入房间后，将通过回调的方式通知房间内的其他用户，收到其他用户加入的回调后，可以为其设置远端视图。

5. 在会中，也可以进行切换摄像头等参数的配置。

6. 用户离开房间后，需销毁对应资源。

说明

在时序图中，单击相应接口名称可快速跳转到相应接口位置查看其使用方法。

3.4 接口参考

3.4.1 HRtcEngine

setBackgroundBlur

public abstract int setBackgroundBlur(boolean enable, int radius)

【功能说明】

背景虚化功能开关，默认关闭。

【请求参数】

● enable：是否打开背景虚化功能开关，true表示打开，false表示关闭。

● radius：背景虚化半径，范围0-25。

【返回参数】

● 0：表示调用命令成功。

● > 0：表示调用命令失败。

setBackgroundReplace

public abstract int setBackgroundReplace(boolean enable, String path)

【功能说明】

背景替换功能开关，默认关闭。

【请求参数】

● enable：是否打开背景替换功能开关，true表示打开，false表示关闭。

● path：背景替换的图片路径，图片只支持png，jpeg格式，高宽不可超过5000，

不可小于50。图片路径长度不可超过255字节（包括一个字节的结束符，即实际有效长度254）

【返回参数】

● 0：表示调用命令成功。

● > 0：表示调用命令失败。

(18)

3.4.1.1 接口总览

本章节介绍了Android SDK的HRtcEngine接口详情。

HRtcEngine按照其功能可分类为：初始化等基础接口、房间功能、视频管理、屏幕共享、音频管理、音效文件播放管理、自定义视频采集和渲染、自定义音频采集和渲染、设备管理、检测功能、音频增强管理。

说明

单击下图中相应接口名称，可快速跳转到相应接口位置查看其使用方法。

初始化等基础接口

表3-1 初始化等基础接口

接口描述

create

创建SparkRTC引擎实例

destroy

销毁SparkRTC引擎

logUpload

上传日志

disableRejoinRoom

设置是否禁用房间重连功能。

enableStats

打点功能开关

(19)

接口描述

getVersion

获取当前SDK版本号

setEncryption

设置端到端加密模式

setAccessResourceType

设置接入环境

房间功能

表3-2 房间功能接口

接口描述

joinRoom

加入房间

leaveRoom

离开房间

changeUserRole

设置用户角色

renewAuthorization

更新鉴权签名

changeUserName

更新用户昵称

createConnection

创建跨房（HRTCConnection）对象

音频管理

表3-3 音频管理接口

接口描述

muteLocalAudio

设置是否发送本地音频流

muteRemoteAudio

设置是否接收对应远端用户的音频流

muteAllRemoteAudio

设置是否接收所有远端用户的音频流

enableLocalAudioStream

设置是否开启音频采集

adjustRecordingVolume

调整录制音量

adjustPlaybackVolume

调整播放音量

adjustPlaybackVolume

调整单个用户播放音量

sendAudioSeiMsg

发送音频SEI

setAudioFrameRecordParameters

设置音频采集回调参数

setAudioConfig

设置音频场景

sendCommandData

媒体通道Cmd命令数据包转发

(20)

接口描述

enableCommandMsg

是否开启媒体通道发数据包功能

视频管理

表3-4 视频管理接口

接口描述

createRenderer

创建渲染视图

updateLocalRenderMode

设置本地窗口显示模式，镜像模式

setupLocalView

设置本地窗口

pushLocalVideo

设置是否发送本地视频流

setVideoEncoderConfig

设置视频编码参数

setRemoteVideoAdjustResolution

设置订阅视频流的分辨率自适应

startLocalPreview

开始本地预览

stopLocalPreview

停止本地预览

startRemoteStreamView

开始订阅远端视频流

stopRemoteStreamView

停止订阅远端视频流

setupRemoteView

设置远端窗口视图

updateRemoteRenderMode

设置远端窗口渲染模式，镜像模式

pullRemoteVideo

设置是否接收对应远端用户的视频流

pullAllRemoteVideo

设置是否接收所有远端用户的视频流

setVideoEncoderMirror

设置视频编码镜像模式

enableLocalVideo

设置是否开启摄像头采集视频

enableVideoSuperResolution

设置是否开启视频超分

enableSmallVideoStream

开启并设置小流编码参数

setPriorRemoteVideoStreamType

设置默认订阅的视频流类型（大流还是小流）

setRemoteVideoStreamType

设置当前订阅的视频流类型

startPublishStream

开始旁路推流

updateTransCoding

更新旁路推流

stopPublishStream

停止旁路推流

(21)

屏幕共享

表3-5 屏幕共享接口

接口描述

startScreenShare

开启屏幕共享

stopScreenShare

关闭屏幕共享

辅流管理

表3-6 辅流管理接口

接口描述

setAuxiliaryVideoEncodeSmooth

设置是否开启辅流的流畅度优先。

startRemoteAuxiliaryStreamView

开始订阅辅流

stopRemoteAuxiliaryStreamView

停止订阅辅流

setRemoteAuxiliaryStreamViewRota

tion

设置辅流角度

updateRemoteAuxiliaryStreamRende

rMode

设置辅流渲染模式，镜像模式

setAuxiliaryVideoEncoderConfig

设置辅流编码参数

setAuxExternalVideoCapture

设置是否开启视频辅流外部采集

音效文件播放管理

表3-7 音效文件播放管理接口

接口描述

startAudioFile

开始播放音频文件

stopAudioFile

停止播放音频文件

pauseAudioFile

暂停播放音频文件

resumeAudioFile

恢复播放音频文件

isPlayMixMyself

是否只有本地可以听到混音

isMixWithMicrophone

是否需要替代采集

adjustAudioFileVolume

调整本地和远端音频播放的音量

adjustAudioFilePlayoutVolume

调整本地音频播放的音量

(22)

接口描述

adjustAudioFilePublishVolume

调整远端音频播放的音量

getAudioFileVolume

获取音频播放的音量

getAudioFilePlayoutVolume

获取音频本地播放的音量

getAudioFilePublishVolume

获取音频远端播放的音量

getAudioFileDuration

获取音频文件的时长

getAudioFilePosition

获取音频文件当前播放位置

setAudioFilePosition

设置音频文件播放位置

playAudioClip

开始播放音效文件

stopAudioClip

停止播放音效文件

pauseAudioClip

暂停播放音效文件

resumeAudioClip

恢复播放音效文件

stopAllAudioClips

停止播放所有音效文件

pauseAllAudioClips

暂停播放所有音效文件

resumeAllAudioClips

恢复播放所有音效文件

setAudioClipsVolume

设置音效播放的最大音量

getAudioClipsVolume

获取音效播放的最大音量

setVolumeOfAudioClip

设置指定音效的播放音量

getVolumeOfAudioClip

获取指定音效的播放音量

setAudioClipPosition

设置指定音效文件的播放位置

getAudioClipCurrentPosition

获取指定音效文件当前的播放位置

getAudioClipDuration

获取音效的文件时长

preloadAudioClip

预加载音效文件

unloadAudioClip

删除预加载音效文件

音频增强管理

表3-8 音频增强接口

接口描述

enableUserVolumeNotify

设置音量值上报回调函数

onUserVolumeStatsNotify回调周期

(23)

检测功能

表3-9 检测功能接口

接口描述

startNetworkTest

开启会前网络探测

stopNetworkTest

停止会前网络检测

自定义视频采集和渲染

表3-10 自定义视频采集和渲染接口

接口描述

setExternalVideoFrameOutputEnable

设置视频数据输出使能

setExternalDataFrameOutputEnable

设置共享数据输出使能

setExternalVideoCapture

设置是否开启外部视频采集

pushExternalVideoFrame

输入外部视频数据

自定义音频采集和渲染

表3-11 自定义音频采集和渲染接口

接口描述

setExternalAudioFrameOutputEnabl

e

设置音频数据输出使能

setExternalAudioCapture

设置是否开启外部音频采集

pushExternalAudioFrame

输入外部音频数据

设备管理

表3-12 设备管理接口

接口描述

setCameraConfig

设置摄像头参数

switchCamera

切换摄像头

setSpeakerModel

设置声音播放模式

(24)

接口描述

setDefaultSpeakerModel

设置默认的声音播放模式

setLayoutDirect

设置显示模式，区分横屏还是竖屏，用

于保证摄像头方向与本地界面方向一致

isSpeakerphoneEnabled

查询是否启用扬声器

3.4.1.2 初始化等基础接口 create

public static synchronized HRTCEngine create(HRTCEngineConfig config, IHRTCEngineEventHandler eventHandler)

【功能说明】

创建SparkRTC引擎实例。

【请求参数】

● config：引擎创建相关参数，具体请参见HRTCEngineConfig。

● eventHandler：引擎事件句柄，用于加入房间、离开房间等事件回调，具体请参见IHRTCEngineEventHandler。

【返回参数】

返回引擎实例对象。

destroy

public static synchronized void destroy()

【功能说明】

销毁SparkRTC引擎。

【请求参数】

无

【返回参数】

无

注意

请不要在RTC SDK的接口回调函数中直接调用此方法，请切回业务线程后调用。

logUpload

public abstract int logUpload();

【功能说明】

上传日志。

(25)

【请求参数】

无

【返回参数】

● 0：成功。

● >0：失败。具体请参见客户端错误码。

注意

会触发以下回调：

●

onLogUploadResult：日志上传结果回调。

●

onLogUploadProgress：日志上传进度回调。

disableRejoinRoom

public abstract int disableRejoinRoom(boolean disable);

【功能说明】

设置是否禁用房间重连功能。

【请求参数】

disable：true表示禁用，false表示不禁用。

【返回参数】

● 0：成功。

● > 0：失败。具体请参见客户端错误码。

enableStats

public abstract int enableStats(boolean enabled);

【功能说明】

打点功能开关，在create之后调用。默认开启。

【请求参数】

enabled：是否打开打点功能开关，true表示打开，false表示关闭。

【返回参数】

● 0：成功。

getVersion

public static String getVersion();

【功能说明】

获取SDK版本号。

【返回参数】

(26)

SDK版本号。

setEncryption

public abstract int setEncryption(HRTCEncryptionConfig encryptionParam);

【功能说明】

设置端到端加密方式。需要在加入房间前设置生效。其中sdk加密模式，需要设置16位加密秘钥和加密算法，app加密模式需要先设置回调接口。

【请求参数】

encryptionParam：加密配置，具体请参见HRTCEncryptionConfig。

【返回参数】

● 0：成功。

● <0：失败。具体请参见客户端错误码。

setAccessResourceType

public abstract int setAccessResourceType(int resType);

【功能说明】

设置接入的环境，不支持跨房间场景。

【请求参数】

● resType：环境类型。

● 0：公网sfu资源。

● 1：公司局Sfu。

● 2：MPC。

● 3：LLL

【返回参数】

● 0：成功。

● <0：失败。具体请参见客户端错误码。

3.4.1.3 房间功能 joinRoom

public abstract int joinRoom(HRTCJoinParam joinParam);

【功能说明】

加入房间。

【请求参数】

joinParam：入会参数，具体请参见HRTCJoinParam。

【返回参数】

● 0：成功。

(27)

● 1：失败。具体请参见客户端错误码。

● 2：上下文为空。

注意

该方法将会触发以下回调：

●

onConnectionStateChangedNotify：连接状态发送改变。

●

onJoinRoomSuccess：加入房间成功时回调。

●

onJoinRoomFailure：加入房间失败时回调，失败原因请参见•加入房间失败时，

成功加入房间发送音频流后才能调用，默认为发送本地音频流。

(30)

muteRemoteAudio

public abstract int muteRemoteAudio(String userId, boolean mute);

【功能说明】

设置是否接收对应远端用户的音频流。

【请求参数】

● userId：用户ID。

● mute：true表示取消音频流接收，false表示开启音频流接收，默认为false。

【返回参数】

● 0：成功。

muteAllRemoteAudio

public abstract int muteAllRemoteAudio(boolean mute);

【功能说明】

设置是否接收所有远端用户的音频流。

【请求参数】

mute：true表示取消音频流接收，false表示开启音频流接收。

【返回参数】

● 0：成功。

注意

● 取消所有音频流接收，同时也会取消接收新加入用户的音频流。

● 开启所有音频流接收，同时也会开启接收新加入用户的音频流。

● 默认开启所有音频流接收。

enableLocalAudioStream

public abstract int enableLocalAudioStream(boolean enabled);

【功能说明】

设置是否开启音频采集。

【请求参数】

enabled：true表示采集开启，false表示关闭。

【返回参数】

● 0：成功。

(31)

注意

默认开启，本端调用该接口时，远端用户会触发onRemoteAudioStateChangedNotify 远端音频流状态变化回调。

adjustRecordingVolume

public abstract int adjustRecordingVolume(int volume);

【功能说明】

调整录制音量值。

【请求参数】

volume：音量值，取值范围：[0,100]，默认音量值为10，此接口不会影响系统音量。

【返回参数】

● 0：成功。

public abstract int setAudioFrameRecordParameters(int sampleRate, int channel, HRTCAudioOperateMode mode, int samplesPerCall);

【功能说明】

设置采集回调参数，配合setAudioFrameObserver的onAudioFrameRecord使用。

【请求参数】

● sampleRate：onAudioFrameRecord中返回的采样率，可设置为8000，16000，

32000, 44100， 48000。

● channel：声道，1表示单声道；2表示双声道。

● mode：可读可写模式，具体请参见HRTCAudioOperateMode。

● samplesPerCall：每次回调的单声道样点数（小于(sampleRate/

100)*channel*2*3，大于(sample/300)*channel*3）。

【返回参数】

● 0：成功。

setAudioConfig

public abstract int setAudioConfig(HRTCAudioQualityLevel level, HRTCAudioSceneType scene)

【功能说明】

设置音频使用场景。

【请求参数】

● level：表示档位，暂时只支持16k。具体请参见HRTCAudioQualityLevel。

● scene：表示音频场景模式，具体请参见HRTCAudioSceneType。

【返回参数】

● 0：成功。

(33)

sendCommandData

public abstract int sendCommandData(String remoteUserId, byte[] data, int length)

【功能说明】

媒体通道Cmd命令数据包转发。

【请求参数】

● userId：用户id，空字符表示广播消息。

● data：数据包。

● length：数据包长度。

【返回参数】

● 0：成功。

enableCommandMsg

public abstract int enableCommandMsg(boolean enable)

【功能说明】

是否开启媒体通道发数据包功能，该接口需要在joinRoom前调用。

【请求参数】

enable：true表示开启，false表示关闭。

【返回参数】

public abstract int pushLocalVideo(boolean push);

【功能说明】

设置是否发送本地视频流。

【请求参数】

push：true表示发送，false表示不发送。

【返回参数】

● 0：成功。

setVideoEncoderConfig

public abstract int setVideoEncoderConfig(int totalBitRate, List<HRTCVideoEncParam> encoderParams);

public abstract int setVideoEncoderConfig(HRTCVideoEncParam encoderParam);

【功能说明】

设置视频编码参数。具体请参见全平台setVideoEncoderConfig。

【请求参数】

● totalBitRate：视频最大码率，默认值4096。

● encoderParams：视频编码参数列表，具体请参见HRTCVideoEncParam。

(35)

● encoderParam：视频编码参数，具体请参见HRTCVideoEncParam。

【返回参数】

● 0：成功。

setRemoteVideoAdjustResolution

public abstract int setRemoteVideoAdjustResolution(boolean enable);

【功能说明】

设置是否开启远端流分辨率自适应。默认开启自适应。

【请求参数】

enable：是否开启分辨率自适应。默认开启。

【返回参数】

● 0：成功。

startLocalPreview

public abstract int startLocalPreview();

【功能说明】

开始本地预览。

【请求参数】

无

【返回参数】

● 0：成功。

注意

● 该接口限制在房间外调用，在房间内设置不生效，需要调用stopLocalPreview关闭预览，否则将一直处于预览状态。

● 在房间内预览：可调用setupLocalView设置有效view开启预览，设置为null表示关闭预览，不需要调用stopLocalPreview。

● 在房间外预览：先调用setupLocalView设置有效view，再调用startLocalPreview 开启预览；关闭时，先调用setupLocalView设置为null，再调用stopLocalPreview 关闭预览。

stopLocalPreview

public abstract int stopLocalPreview();

【功能说明】

停止本地预览。

(36)

【请求参数】

无

【返回参数】

● 0：成功。

注意

如果调用了startLocalPreview，需调用stopLocalPreview关闭预览，否则将一直处于预览状态。该接口限制在房间外调用，在房间内设置不生效。

startRemoteStreamView

public abstract int startRemoteStreamView(String userId, SurfaceView view, HRTCStreamType streamType, boolean disableAdjustRes);

【功能说明】

开始订阅远端视频流，并设置远端窗口。

【请求参数】

● view：远端窗口视图。

● streamType：流类型，具体请参见HRTCStreamType。

● disableAdjustRes：禁用分辨率自适应的标志。

【返回参数】

● 0：成功。

stopRemoteStreamView

public abstract int stopRemoteStreamView(String userId);

【功能说明】

停止订阅远端视频流，并关闭远端窗口。

【请求参数】

userId：用户ID。

【返回参数】

● 0：成功。

setupRemoteView

public abstract int setupRemoteView(String userId, SurfaceView view);

【功能说明】

(37)

设置远端流视图，该接口不影响收流。

【请求参数】

● userId：远端用户的唯一标识。

● view：远端窗口视图，view为null时，解除窗口绑定。

【返回参数】

● 0：成功。

updateRemoteRenderMode

public abstract int updateRemoteRenderMode(String userId, HRTCVideoDisplayMode displayMode, HRTCVideoMirrorType mirrorMode);

【功能说明】

设置远端窗口渲染模式。

【请求参数】

● displayMode：渲染模式，具体请参见HRTCVideoDisplayMode。

● mirrorMode：镜像模式，具体请参见HRTCVideoMirrorType 。

【返回参数】

● 0：成功。

pullRemoteVideo

public abstract int pullRemoteVideo(String userId, boolean pull);

【功能说明】

开启、关闭指定远端用户的视频流。

【请求参数】

● userId：远端用户的userId，唯一标识。

● pull：true表示开始接收，false表示关闭接收。

【返回参数】

● 0：成功。

pullAllRemoteVideo

public abstract int pullAllRemoteVideo(boolean pull);

【功能说明】

批量开启、关闭当前所有远端用户的视频流。

【请求参数】

pull：true表示开启接收，false表示关闭接收，默认开启接收。

(38)

【返回参数】

● 0：成功。

注意

开启本地镜像后，本地视频窗口看到的是镜像视图，但不影响远端查看自己的视图。

setVideoEncoderMirror

public abstract int setVideoEncoderMirror(HRTCVideoMirrorType mirrorType);

【功能说明】

设置视频编码镜像模式。

【请求参数】

mirrorType：镜像模式，是否开启镜像，具体请参见HRTCVideoMirrorType，默认值 false。

【返回参数】

● 0：成功。

注意

开启镜像后，仅改变编码发送给远端用户的视图，不影响自己看到的本地视频窗口。

enableLocalVideo

public abstract int enableLocalVideo(boolean enabled);

【功能说明】

设置是否开启摄像头采集视频。

【请求参数】

enabled：true表示开启，false表示关闭。

【返回参数】

● 0：成功。

注意

默认开启，本端调用时，远端用户会触发onRemoteVideoStateChangedNotify远端视频流状态变化回调。

(39)

enableVideoSuperResolution

public abstract int enableVideoSuperResolution(boolean enabled);

【功能说明】

设置是否开启视频超分。

【请求参数】

enabled：true表示开启，false表示关闭。

【返回参数】

● 0：成功。

enableSmallVideoStream

public abstract int enableSmallVideoStream(boolean enable, HRTCVideoEncParam encoderParam);

【功能说明】

大小流模式设置是否开启小流，并设置编码参数。小流选择性开启。

【请求参数】

● enable：是否开启小流。

● encoderParam：视频编码参数。包括流类型、宽、高、码率、帧率等。具体请参见HRTCVideoEncParam。

【返回参数】

● 0：成功。

setPriorRemoteVideoStreamType

public abstract int setPriorRemoteVideoStreamType(HRTCVideoStreamType type);

【功能说明】

大小流模式，设置所有订阅的远端视频流类型。默认订阅大流，优先应用 setRemoteVideoStreamType接口设置的用户流类型。

【请求参数】

type：订阅的视频流类型，分为大流和小流，具体请参见HRTCVideoStreamType。

【返回参数】

● 0：成功。

setRemoteVideoStreamType

public abstract int setRemoteVideoStreamType(String userId, HRTCVideoStreamType type);

【功能说明】

大小流模式，设置指定订阅的远端视频流类型。

【请求参数】

(40)

● userId：远端用户唯一标识。

● type：订阅的视频流类型，分为大流和小流，具体请参见

HRTCVideoStreamType。

startPublishStream

public abstract int startPublishStream(String taskId, List<String> urlList, HRTCTranscodeConfig transcodeConfig);

【功能说明】

开始旁路推流。

【请求参数】

● taskId：任务id，业务自行定义，保证唯一。

● urlList：url数组。参考HRTCRtmpUrlList

● transcodeConfig：用户id数组和其他参数，具体请参见

HRTCTranscodeConfig。

【返回参数】

● 0：成功。

updateTransCoding

public abstract int updateTransCoding(String taskId, HRTCTranscodeConfig transcodeConfig);

【功能说明】

更新旁路推流。

【请求参数】

● taskId：任务id，业务自行定义，保证唯一。

● transcodeConfig：用户id数组和其他参数，具体请参见

HRTCTranscodeConfig。

【返回参数】

● 0：成功。

stopPublishStream

virtual int stopPublishStream(const char* taskId)

【功能说明】

停止旁路推流。

【请求参数】

taskId：任务id，支持自定义，需保证唯一性。

【返回参数】

● 0：成功。

(41)

startAllRemoteView

public abstract int startAllRemoteView(List<HRTCVideoRemoteView> viewInfoList);

【功能说明】

批量设置远端流视图。

【请求参数】

viewInfoList：订阅的视图信息，主要包括该视图的句柄、流类型、用户ID、是否自适应等，具体请参见HRTCVideoRemoteView。

【返回参数】

● 0：成功。

3.4.1.6 屏幕共享 startScreenShare

public abstract int startScreenShare();

【功能说明】

开启屏幕共享。

【返回参数】

● 0：成功。

注意

● Android 5.0及以上版本支持此功能。

● 使用时，在AndroidManifest.xml中需添加如下约束。

<activity

<activity android:name="com.huawei.allplatform.screencapture.HRTCScreenShareAssistantActivity"

android:theme="@style/dialog" />

● targetSdkVersion >= 24时，在AndroidManifest.xml中需添加如下约束，并在开启屏幕共享时弹出自定义悬浮窗，避免被系统强杀掉。

<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

● targetSdkVersion >= 29时，在AndroidManifest.xml中需添加如下约束。

<service android:name="com.huawei.allplatform.screencapture.HRTCScreenShareService"

android:enabled="true"

android:foregroundServiceType="mediaProjection"/>

● 目前可支持多路辅流共享，若需开启多辅流，请提交工单联系华为云技术工程师处理。

● 开启后将触发onScreenShareStarted回调。

● 远端会收到onUserAuxiliaryStreamAvailable通知，可据此发起辅流选看。

(42)

stopScreenShare

public abstract int stopScreenShare();

【功能说明】

停止屏幕共享。

【返回参数】

● 0：成功。

注意

● SDK 1.7.1及以上版本支持。

● 停止后将会触发onScreenShareStopped回调。

3.4.1.7 辅流管理

setAuxiliaryVideoEncodeSmooth

public abstract int setAuxiliaryVideoEncodeSmooth(boolean enabled);

【功能说明】

设置是否开启辅流的流畅度优先。

【请求参数】

enable：true表示辅流分辨率为720p，false表示辅流分辨率为1080p。

【返回参数】

● 0：成功。

注意

● SDK 1.7.1及以上版本支持。

● 开启后，辅流发流分辨率为720p，否则发流分辨率为1080p。默认不开启。

startRemoteAuxiliaryStreamView

public abstract int startRemoteAuxiliaryStreamView(String userId, SurfaceView view);

【功能说明】

开始订阅辅流。

【请求参数】

● view：窗口视图。

(43)

updateRemoteAuxiliaryStreamRenderMode

public abstract int updateRemoteAuxiliaryStreamRenderMode(String userId, HRTCVideoDisplayMode displayMode, HRTCVideoMirrorType mirrorMode);

【功能说明】

设置辅流渲染模式。

(44)

【请求参数】

● displayMode：渲染模式，默认值为HRTC_VIDEO_DISPLAY_MODE_FIT，具体请参见HRTCVideoDisplayMode。

● mirrorMode：镜像模式，默认值为HRTC_VIDEO_MIRROR_TYPE_DISABLE，具体请参见HRTCVideoMirrorType。

【返回参数】

● 0：成功。

setAuxiliaryVideoEncoderConfig

public abstract int setAuxiliaryVideoEncoderConfig(HRTCVideoAuxiliaryEncParam encoderParams);

【功能说明】

设置辅流编码参数。

【请求参数】

encoderParams：需要设置的辅流编码参数，包括宽、高、帧率和码率，具体请参见

HRTCVideoAuxiliaryEncParam。

【返回参数】

● 0：成功。

注意

使用该接口设置辅流编码参数时，由于当前系统策略会根据获取的区域宽高比对设置的宽高进行调整，使用户设置的宽高比与获取的宽高比保持一致，因此用户实际收流的分辨率与设置的分辨率可能存在不同。

3.4.1.8 音效文件播放管理 startAudioFile

public abstract int startAudioFile(String fullFilePath, int publish, int cycle, int replace);

public abstract int startAudioFile(String fullFilePath, int publish, int cycle, int replace, int startPos);

【功能说明】

开始播放音频文件。当前仅支持本端播放。

【请求参数】

● fullFilePath：音频文件的本地全路径，支持播放本地文件或网络文件。

● publish：播放模式，0表示只有本端能听到播放的音频，1表示远端也能听到播放的音频。

● cycle：循环次数，0表示无限循环。

(45)

● replace：是否替代麦克风采集，等于1时用音频文件的声音替换麦克风采集的声音。

● startPos：音频文件开始播放的位置，单位为ms。

【返回参数】

● 0：成功。

注意

会触发onAudioMixStateChangedNotify回调。

stopAudioFile

public abstract int stopAudioFile();

【功能说明】

停止播放音频文件。

【请求参数】

无

【返回参数】

● 0：成功。

● > 0：失败。

注意

pauseAudioFile

public abstract int pauseAudioFile();

【功能说明】

暂停播放音频文件。

【请求参数】

无

【返回参数】

● 0：成功。

● >0：失败。

注意

(46)

resumeAudioFile

public abstract int resumeAudioFile();

【功能说明】

恢复播放音频文件。

【请求参数】

无

【返回参数】

● 0：成功。

● >0：失败。

注意

isPlayMixMyself

public abstract int isPlayMixMyself(boolean myself);

【功能说明】

是否只有本地可以听到混音。

【请求参数】

myself：true表示只有本地可以听到混音， false表示本地和对方都可以听到混音，默认值为false。

【返回参数】

● 0：成功。

isMixWithMicrophone

public abstract int isMixWithMicrophone(boolean withMic);

【功能说明】

是否需要替代采集。

【请求参数】

withMic：true表示替代采集，远端只能听到音乐，false表示不替代，远端可以同时听到音乐和MIC采集的声音，默认值为false。

【返回参数】

● 0：成功。

adjustAudioFileVolume

public abstract int adjustAudioFileVolume(int volume);

(47)

【功能说明】

调整本地和远端音频播放的音量。

【请求参数】

volume：音量大小，范围为0-100，默认值为100。

【返回参数】

● 0：方法调用成功。

● > 0：方法调用失败。具体请参见客户端错误码。

adjustAudioFilePlayoutVolume

public abstract int adjustAudioFilePlayoutVolume(int volume);

【功能说明】

调整本地音频播放的音量。

【请求参数】

volume：音量大小，范围为0-100，默认值为100。

【返回参数】

adjustAudioFilePublishVolume

public abstract int adjustAudioFilePublishVolume(int volume);

【功能说明】

调整远端音频播放的音量。

【请求参数】

volume：音量大小，范围0-100，默认值100。

【返回参数】

getAudioFileVolume

public abstract int getAudioFileVolume();

【功能说明】

获取音频播放的音量。

【请求参数】

无

【返回参数】

● >=0：音量大小，范围为0-100。

(48)

● < 0：方法调用失败。具体请参见客户端错误码。

getAudioFilePlayoutVolume

public abstract int getAudioFilePlayoutVolume();

【功能说明】

获取音频本地播放的音量。

【请求参数】

无

【返回参数】

● >=0：音量大小，范围为0-100。

public abstract int setAudioFilePosition(int position);

【功能说明】

设置音频文件播放位置。

【请求参数】

position：播放位置，单位为ms。

【返回参数】

playAudioClip

public abstract int playAudioClip(int soundId, String filePath, int loop, double pitch, double pan, double gain, int publish, int startPos);

【功能说明】

播放音效文件并启动混音，需要在有joiner加入房间后调用。

【请求参数】

● soundId：音效ID，取值>= 0。

● filePath：音效文件路径，支持本地文件和网络文件。

● loop：音效文件播放次数，0为循环播放。

● pitch：音调大小，当前不支持。

● pan：空间位置，当前不支持。

● gain：音量大小，取值范围0-100。

● publish：1表示将音效文件混音后发送到远端，0为本地播放，不发送到远端。

● startPos：起始播放位置，单位为ms。

【返回参数】

注意

soundId需要开发者自己生成并维护，保证不同的soundId对应不同的音效播放实例。

同时音效播放完毕或者停止播放后，soundId最好主动回收，下一次播放音效的时候，

尽量复用被回收的soundId。

(50)

stopAudioClip

public abstract int stopAudioClip(int soundId);

【功能说明】

停止播放指定的音效文件。

【请求参数】

soundId：音效ID，取值>= 0。

【返回参数】

pauseAudioClip

public abstract int pauseAudioClip(int soundId);

【功能说明】

暂停播放指定的音效文件。

【请求参数】

【返回参数】

resumeAudioClip

public abstract int resumeAudioClip(int soundId);

【功能说明】

恢复播放指定的音效文件。

【请求参数】

【返回参数】

stopAllAudioClips

public abstract int stopAllAudioClips();

【功能说明】

停止播放所有音效文件。

【请求参数】

无

开发前准备_实时音视频 SparkRTC_客户端SDK参考_Electron SDK_华为云

SDK 参考

目 录

1 使用前必读... 1

2 SDK 概述... 4

3 Android SDK...5

4 iOS/macOS SDK... 158

5 All Platform C++ SDK... 312

6 Web SDK...500

7 Electron SDK...584

8 接入鉴权... 698

9 附录... 702

1 使用前必读

1.1 主要功能

1.2 文档基本使用技巧

1.3 常见问题分析解决办法

2 SDK 概述

Android SDK集成 Android SDK接口参考

iOS SDK集成 iOS SDK接口参考

MAC SDK集成 MAC SDK接口参考

Windows SDK集成 Windows SDK接口参考

Web SDK集成 Web SDK接口参考

Electron SDK集成 Electron SDK接口参考

3 Android SDK

3.1 开发前准备

环境要求

SDK 集成

3.2 SDK 使用

3.3 基本使用逻辑

3.4 接口参考

3.4.1 HRtcEngine

setBackgroundBlur

setBackgroundReplace

3.4.1.1 接口总览

初始化等基础接口

create

destroy

logUpload

disableRejoinRoom

enableStats

getVersion

setEncryption

setAccessResourceType

房间功能

joinRoom

leaveRoom

changeUserRole

renewAuthorization

changeUserName

createConnection

音频管理

muteLocalAudio

muteRemoteAudio

muteAllRemoteAudio

enableLocalAudioStream

adjustRecordingVolume

adjustPlaybackVolume

adjustPlaybackVolume

sendAudioSeiMsg

setAudioFrameRecordParameters

setAudioConfig

sendCommandData

enableCommandMsg

视频管理

createRenderer

updateLocalRenderMode

setupLocalView

pushLocalVideo

setVideoEncoderConfig

setRemoteVideoAdjustResolution

startLocalPreview

stopLocalPreview

startRemoteStreamView

stopRemoteStreamView

setupRemoteView

updateRemoteRenderMode

pullRemoteVideo

pullAllRemoteVideo

setVideoEncoderMirror

enableLocalVideo

目录

1 ^{使用前必读}

2 ^{SDK 概述}