互动直播 API

新版开发者中心已经发布!如需访问最新版本,请点击  这里

售前咨询QQ群 276282334
售前咨询电话 400 632 6626

互动直播 API

java 接口类 描述
主要方法 (RtcEngine) RtcEngine 接口类包含应用程序调用的主要方法
音效管理方法 (IAudioEffectManager) IAudioEffectManager 类提供管理音效的方法
推流方法 (PublisherConfiguration) PublisherConfiguration 类提供方法创建旁路直播场景的推流配置
主回调事件 (IRtcEngineEventHandler) RtcEngineEventHandler 接口类用于向应用程序发送回调通知
裸数据回调事件 (IAudioFrameObserver) IAudioFrameObserver 接口的回调事件

主要方法 (RtcEngine)

RtcEngine 类包含应用程序调用的主要方法,调用 RtcEngine 的接口最好在同一个线程进行,不建议在不同的线程同时调用。

创建 RtcEngine 对象 (create)

public static synchronized RtcEngine create(Context context,
                                             String appId,
                                             IRtcEngineEventHandler handler);

本方法创建 RtcEngine 对象。

目前 Agora Native SDK 只支持一个 RtcEngine 实例,每个应用程序仅创建一个 RtcEngine 对象 。 RtcEngine 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。所有返回值为 int 型的 API,如无特殊说明,返回值 0 为调用成功,返回值小于 0 为调用失败。

名称 描述
context 安卓活动 (Android Activity) 的上下文
appId Agora 为应用程序开发者签发的 App ID,详见 获取 App ID
handler IRtcEngineEventHandler 是一个提供了缺省实现的抽象类,SDK 通过该抽象类向应用程序报告 SDK 运行时的各种事件
返回值 RtcEngine 对象

实现语音直播

../_images/android_audio_api_live.png

设置频道属性 (setChannelProfile)

public abstract int setChannelProfile(int profile);

该方法用于设置频道模式 (Profile)。Agora RtcEngine 需知道应用程序的使用场景(例如通信模式或直播模式), 从而使用不同的优化手段。

目前 Agora Native SDK 支持以下几种模式:

模式 描述
通信 通信为默认模式,用于常见的一对一或群聊,频道中的任何用户可以自由说话
直播 直播模式有主播和观众两种用户角色,可以通过调用 setClientRole 设置。主播可收发语音和视频,但观众只能收,不能发
游戏语音 频道内任何用户可自由发言。该模式下默认使用低功耗低码率的编解码器

Note

  • 同一频道内只能同时设置一种模式。如果想要切换模式,则需要先调用 destroy 销毁当前引擎,然后在 创建 RtcEngine 对象 (create) 方法中传入 不同 的 App ID 重新创建引擎,再调用该方法切换频道模式。
  • 不同的频道模式必须使用不同的 App ID。
  • 该方法必须在加入频道前调用和进行设置,进入频道后无法再设置。
名称 描述
profile

频道模式:

  • CHANNEL_PROFILE_COMMUNICATION = 0: 通信模式 (默认)
  • CHANNEL_PROFILE_LIVE_BROADCASTING = 1: 直播模式
  • CHANNEL_PROFILE_GAME = 2: 游戏语音模式
返回值
  • 0:方法调用成功
  • < 0:方法调用不成功

设置用户角色 (setClientRole)

public abstract int setClientRole(int role);

在加入频道前,用户需要通过本方法设置观众(默认)或主播模式。在加入频道后,用户可以通过本方法切换用户模式。

名称 描述
role

直播场景里的用户角色

  • CLIENT_ROLE_BROADCASTER = 1; 主播
  • CLIENT_ROLE_AUDIENCE = 2; 观众(默认)
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

打开音频 (enableAudio)

public abstract int enableAudio();

打开音频(默认为开启状态)。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

Note

该方法设置内部引擎为启用状态,在 leaveChannel 后仍然有效。

禁用或重新开启本地语音功能 (enableLocalAudio)

public abstract int enableLocalAudio(boolean enabled);

当 App 加入频道时,它的语音功能是默认开启的。该方法可以关闭或重新开启本地语音功能,停止或重新开始本地音频采集及处理。

该方法不影响接收或播放远端音频流,适用于只听不发的用户场景。

语音功能关闭或重新开启后,会收到 onMicrophoneEnabled 回调。

Note

  • 该方法需要在 joinChannel 之后调用才能生效。
  • 该方法与 muteLocalAudioStreammuteRecordingSignal 的区别在于:
    • enableLocalAudio:开启或关闭本地语音采集及处理
    • muteLocalAudioStream:停止或继续发送本地音频流
    • muteRecordingSignal:静音/不静音麦克风采集到的声音
名称 描述
enabled
  • true:重新启用本地语音功能,即启动本地语音采集或处理
  • false:关闭本地语音功能,即停止本地语音采集或处理
返回值
  • 0:方法调用成功
  • < 0:方法调用失败

关闭音频 (disableAudio)

public abstract int disableAudio();

关闭音频。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

Note

该方法设置内部引擎为禁用状态,在 leaveChannel 后仍然有效。

设置音频属性 (setAudioProfile)

public abstract int setAudioProfile(int profile, int scenario);

该方法用于设置音频参数和应用场景。返回值:

  • 0: 方法调用成功
  • < 0: 方法调用失败
名称 描述
profile

设置采样率,码率,编码模式和声道数:

  • AUDIO_PROFILE_DEFAULT = 0: 默认设置。通信模式下为 1,直播模式下为 2
  • AUDIO_PROFILE_SPEECH_STANDARD = 1: 指定 32 KHz采样率,语音编码, 单声道,编码码率约 18 kbps
  • AUDIO_PROFILE_MUSIC_STANDARD = 2: 指定 48 KHz采样率,音乐编码, 单声道,编码码率约 48 kbps
  • AUDIO_PROFILE_MUSIC_STANDARD_STEREO = 3: 指定 48 KHz采样率,音乐编码, 双声道,编码码率约 56 kbps
  • AUDIO_PROFILE_MUSIC_HIGH_QUALITY = 4: 指定 48 KHz 采样率,音乐编码, 单声道,编码码率约 128 kbps
  • AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO = 5: 指定 48 KHz采样率,音乐编码, 双声道,编码码率约 192 kbps
scenario

设置音频应用场景:

  • AUDIO_SCENARIO_DEFAULT = 0: 默认设置
  • AUDIO_SCENARIO_CHATROOM_ENTERTAINMENT = 1: 娱乐应用,需要频繁上下麦的场景
  • AUDIO_SCENARIO_EDUCATION = 2: 教育应用,流畅度和稳定性优先
  • AUDIO_SCENARIO_GAME_STREAMING = 3: 游戏直播应用,需要外放游戏音效也直播出去的场景
  • AUDIO_SCENARIO_SHOWROOM = 4: 秀场应用,音质优先和更好的专业外设支持
  • AUDIO_SCENARIO_CHATROOM_GAMING = 5: 游戏开黑

Note

  • 该方法需要在 joinChannel 之前设置好,joinChannel 之后设置不生效
  • 通信模式下,该方法设置 profile 生效,设置 scenario 不生效
  • 通信和直播模式下,音质(码率)会有网络自适应的调整,通过该方法设置的是一个最高码率
  • 音乐教学场景下,建议将 profile 设置为 MUSIC_HIGH_QUALITY(4),scenario 设置为 GAME_STREAMING(3)
  • scenario 中的 CHATROOM_ENTERTAINMENT(1)和 CHATROOM_GAMING(5)为游戏开黑场景,建议仅在纯音频的场景下使用

设置音频高音质选项 (setHighQualityAudioParameters)

public abstract int setHighQualityAudioParameters(boolean fullband, boolean stereo, boolean fullBitrate);

该方法设置音频高音质选项。请在加入频道前调用本方法并一次性设置好三个模式。切勿在加入频道后再次调用本方法。

名称 描述
fullband

全频带编解码器(48 kHz 采样率), 不兼容 1.7.4 以前版本

  • true: 启用全频带编解码器
  • false: 禁用全频带编解码器
stereo

立体声编解码器,不兼容 1.7.4 以前版本

  • true: 启用立体声编解码器
  • false: 禁用立体声编解码器
fullBitrate

高码率模式,建议仅在纯音频模式下使用

  • true: 启用高码率模式
  • false: 禁用高码率模式
返回值
  • 0:方法调用成功
  • < 0:方法调用不成功

Note

该接口为废弃接口,Agora 不推荐继续使用。如果需要设置音质,可以使用 设置音频属性 (setAudioProfile) 进行设置。

加入频道 (joinChannel)

public abstract int joinChannel(String token,
                                String channelName,
                                String optionalInfo,
                                int optionalUid);

该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的应用程序是不能互通的。如果已在通话中,用户必须调用 leaveChannel() 退出当前通话,才能进入下一个频道。

Note

同一个频道里不能出现两个相同的 UID。如果你的 App 支持多设备同时登录,即同一个用户账号可以在不同的设备上同时登录(例如微信支持在 PC 端和移动端同时登录),请保证传入的 UID 不相同。 例如你之前都是用同一个用户标识作为 UID, 建议从现在开始加上设备 ID, 以保证传入的 UID 不相同 。如果你的 App 不支持多设备同时登录,例如在电脑上登录时,手机上会自动退出,这种情况下就不需要在 UID 上添加设备 ID。

名称 描述
token
  • 安全要求不高: 将值设为 null
  • 安全要求高: 将值设置为 Token 值。 如果你已经启用了 App Certificate, 请务必使用 Token。 关于如何获取 Token,详见 密钥说明
channelName 标识通话的频道名称,长度在64字节以内的字符串。以下为支持的字符集范围(共89个字符): a-z,A-Z,0-9,space,! #$%&,()+, -,:;<=.#$%&,()+,-,:;<=.,>?@[],^_,{|},~
optionalInfo (非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串,或频道相关信息。该信息不会传递给频道内的其他用户
optionalUid

(非必选项) 用户ID,32位无符号整数。建议设置范围:1到 (2^32-1),并保证唯一性。如果不指定(即设为0),SDK 会自动分配一个,并在 onJoinChannelSuccess 回调方法中返回,App 层必须记住该返回值并维护,SDK不对该返回值进行维护

uid 在 SDK 内部用 32 位无符号整数表示,由于 java 不支持无符号整数,uid 被当成 32 位有符号整数处理,对于过大的整数,java 会表示为负数,如有需要可以用(uid&0xffffffffL)转换成 64 位整数

返回值
  • 0:方法调用成功
  • < 0:方法调用失败
  • ERR_INVALID_ARGUMENT (-2):传递的参数无效
  • ERR_NOT_READY (-3):没有成功初始化

离开频道 (leaveChannel)

public abstract int leaveChannel();

离开频道,即挂断或退出通话。

当调用 joinChannel() API 方法后,必须调用 leaveChannel() 结束通话,否则无法开始下一次通话。 不管当前是否在通话中,都可以调用 leaveChannel(),没有副作用。该方法会把会话相关的所有资源释放掉。该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 onLeaveChannel 回调。

Note

如果你调用了 leaveChannel 后立即调用 destroy(),SDK 将无法触发 onLeaveChannel 回调。

名称 描述
返回值
  • 0:方法调用成功
  • < 0:方法调用不成功

设置音效

设置本地语音音调 (setLocalVoicePitch)

public abstract int setLocalVoicePitch(double pitch);

该方法改变本地说话人声音的音调。

名称 描述
pitch 语音频率可以 [0.5, 2.0] 范围内设置。默认值为 1.0
返回值
  • 0: 方法调用成功
  • < 0: 方法调用失败

设置本地语音音效均衡 (setLocalVoiceEqualization)

public abstract int setLocalVoiceEqualization(int bandFrequency, int bandGain);

该方法设置本地语音音效均衡。

名称 描述
bandFrequency 取值范围是 [0-9],分别代表音效的 10 个 band 的中心频率 [31,62,125,250,500,1k,2k,4k,8k,16k]Hz
bandGain 每个 band 的增益,单位是 dB,每一个值的范围是 [-15,15]

设置本地音效混响 (setLocalVoiceReverb)

public abstract int setLocalVoiceReverb(int reverbKey, int value);

该方法设置本地音效混响。

名称 描述
reverbKey 混响音效 Key。该方法共有 5 个混响音效 Key,分别如 value 栏列出
value

各混响音效 Key 所对应的值:

  • AUDIO_REVERB_DRY_LEVEL = 0:(dB, [-20,10]),原始声音效果,即所谓的 dry signal
  • AUDIO_REVERB_WET_LEVEL = 1:(dB, [-20,10]),早期反射信号效果,即所谓的 wet signal
  • AUDIO_REVERB_ROOM_SIZE = 2:([0,100]), 所需混响效果的房间尺寸
  • AUDIO_REVERB_WET_DELAY = 3:(ms, [0, 200]),wet signal 的初始延迟长度,以毫秒为单位
  • AUDIO_REVERB_STRENGTH = 4:([0,100]),后期混响长度

实现视频直播

../_images/android_video_api_live.png

创建渲染视图 (createRendererView)

public static SurfaceView createRendererView (Context context);

该方法创建视频渲染视图,返回 SurfaceView 的类型。view 的操作和布局由 App 管理, Agora SDK 在 App 提供的 view 上进行渲染。显示视频视图必须调用该方法,而不是直接调用 SurfaceView。

名称 描述
context 安卓活动 (Android Activity) 的上下文

打开视频模式 (enableVideo)

public abstract int enableVideo();

该方法用于打开视频模式。可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启视频模式,在通话中调用则由音频模式切换为视频模式。 调用 disableVideo() 方法可关闭视频模式。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

Note

该方法设置内部引擎为启用状态,在 leaveChannel 后仍然有效。

关闭视频模式 (disableVideo)

public abstract int disableVideo();

该方法用于关闭视频。可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频模式。 调用 enableVideo() 方法可开启视频模式。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

Note

该方法设置内部引擎为禁用状态,在 leaveChannel 后仍然有效。

启用本地视频 (enableLocalVideo)

public abstract int enableLocalVideo(boolean enabled);

禁用/启用本地视频功能。该方法用于只看不发的视频场景。

请在 enableVideo 后调用该方法,否则该方法可能无法正常使用。 调用 enableVideo 后,本地视频即默认开启。使用该方法可以开启或关闭本地视频,且不影响接收远端视频。

名称 描述
enabled

是否启用本地视频:

  • true:开启本地视频采集和渲染(默认)
  • false:关闭使用本地摄像头设备。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为 false 时,该方法不需要本地有摄像头。
返回值
  • 0:方法调用成功
  • < 0:方法调用失败

Note

该方法设置内部引擎为启用/禁用状态,在 leaveChannel 后仍然有效。

设置视频编码属性 (setVideoEncoderConfiguration)

public abstract int setVideoEncoderConfiguration(VideoEncoderConfiguration config);

该方法设置视频编码属性。每个属性对应一套视频参数,如分辨率、帧率、码率、视频方向等。 所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时,会取最接近最大值的那个值。

如果用户加入频道后不需要重新设置视频编码属性,则 Agora 建议在 enableVideo 前调用该方法,可以加快首帧出图的时间。

名称 描述
config 视频编码属性。详细的 VideoEncoderConfiguration 定义见下文
返回值
  • 0:方法调用成功
  • < 0:方法调用不成功

VideoEncoderConfiguration 定义

public VideoEncoderConfiguration(
        VideoDimensions dimensions, FRAME_RATE frameRate, int bitrate, ORIENTATION_MODE orientationMode);

其中 VideoDimensions 定义如下:

static public class VideoDimensions {
    public int width;
    public int height;

    public VideoDimensions(int width, int height) {
        this.width = width;
        this.height = height;
    }

    public VideoDimensions() {
        this.width = 0;
        this.height = 0;
    }
}
名称 描述
dimensions

视频编码的分辨率,由宽 x 高组成,用户可以自行对宽和高设值,也可以根据下面的枚举来设置:

  • VD_120x120:视频分辨率为 120x120
  • VD_160x120:视频分辨率为 160x120
  • VD_180x180:视频分辨率为 180x180
  • VD_240x180:视频分辨率为 240x180
  • VD_320x180:视频分辨率为 320x180
  • VD_240x240:视频分辨率为 240x240
  • VD_320x240:视频分辨率为 320x240
  • VD_424x240:视频分辨率为 424x240
  • VD_360x360:视频分辨率为 360x360
  • VD_480x360:视频分辨率为 480x360
  • VD_640x360:视频分辨率为 640x360
  • VD_480x480:视频分辨率为 480x480
  • VD_640x480:视频分辨率为 640x480
  • VD_840x480:视频分辨率为 840x480
  • VD_960x720:视频分辨率为 960x720 [1]
  • VD_1280x720:视频分辨率为 1280x720 [1]
frameRate

视频编码的帧率。具体可设置如下帧率:

  • FRAME_RATE_FPS_1(1):每秒钟 1 帧
  • FRAME_RATE_FPS_7(7):每秒钟 7 帧
  • FRAME_RATE_FPS_10(10):每秒钟 10 帧
  • FRAME_RATE_FPS_15(15):每秒钟 15 帧
  • FRAME_RATE_FPS_24(24):每秒钟 24 帧
  • FRAME_RATE_FPS_30(30):每秒钟 30 帧
bitrate

视频编码的码率。你可以参考 基准码率参考表 ,手动设置你想要的码率。若设置的视频码率超出合理范围,SDK 会自动按照合理区间处理码率。如果觉得手动设置比较繁琐,也可以直接选择:

  • STANDARD_BITRATE(0):(推荐)标准模式。该模式下,视频在通信和直播模式下的码率有所不同:
    • 通信模式下,码率与基准码率一致
    • 直播模式下,码率对照基准码率翻倍
  • COMPATIBLE_BITRATE(-1):适配模式。该模式下,视频在通信和直播模式下的码率均与基准码率一致。直播模式下如果选择该模式,可能会导致帧率值低于 基准码率参考表 中列的值

Agora 在通信和直播模式下采用不同的编码方式,以提升不同场景下的用户体验。通信场景保证流畅,而直播场景则更注重画面质量,因此直播模式对码率的需求大于通信模式。所以 Agora 推荐将该参数设置为 STANDARD_BITRATE。

orientationMode

视频编码的方向模式:

  • ORIENTATION_MODE_ADAPTIVE(0):(默认)该模式下 SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景
    • 如果采集的视频是横屏模式,则输出的视频也是横屏模式
    • 如果采集的视频是竖屏模式,则输出的视频也是竖屏模式
  • ORIENTATION_MODE_FIXED_LANDSCAPE(1):该模式下 SDK 固定输出风景(横屏)模式的视频。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该模式适用于当接收端无法调整视频方向时,如使用 CDN 推流场景下
  • ORIENTATION_MODE_FIXED_PORTRAIT(2):该模式下 SDK 固定输出人像(竖屏)模式的视频,如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该模式适用于当接收端无法调整视频方向时,如使用 CDN 推流场景下

对于有视频旋转的场景,Agora 提供 入门:视频采集旋转 文档,指导用户如何设置该参数以获取想要的视频。

脚注

[1](1, 2) 视频能否达到 720P 的分辨率取决于设备的性能,在性能配备较低的设备上有可能无法实现。如果采用 720P 分辨率而设备性能跟不上,则有可能出现帧率过低的情况。如设备有特别需求,请联系 support@agora.io
基准码率参考表

Note

该表中的基准码率适用于通信场景。

直播场景下通常需要较大码率来提升视频质量。Agora 推荐通过设置 STANDARD_BITRATE 模式来实现。你也可以直接将码率值设为基准码率值 x 2。

视频属性 分辨率(宽x高) 帧率(fps) 基准码率 (Kbps)
120P 160x120 15 65
120P_3 120x120 15 50
180P 320x180 15 140
180P_3 180x180 15 100
180P_4 240x180 15 120
240P 320x240 15 200
240P_3 240x240 15 140
240P_4 424x240 15 220
360P 640x360 15 400
360P_3 360x360 15 260
360P_4 640x360 30 600
360P_6 360x360 30 400
360P_7 480x360 15 320
360P_8 480x360 30 490
480P 640x480 15 500
480P_3 480x480 15 400
480P_4 640x480 30 750
480P_6 480x480 30 600
480P_8 848x480 15 610
480P_9 848x480 30 930
480P_10 640x480 10 400
720P 1280x720 15 1130
720P_3 1280x720 30 1710
720P_5 960x720 15 910
720P_6 960x720 30 1380

如下码率适用于直播模式。直播场景下,无论选择 STANDARD_BITRATE 还是 COMPATIBLE_BITRATE 模式,码率值不变。

视频属性 分辨率(宽x高) 帧率(fps) 码率 (Kbps)
360P_9 640x360 15 800
360P_10 640x360 24 800
360P_11 640x360 24 1000
设置视频属性 (setVideoProfile)

Note

该接口已废弃。如果需要设置视频编码属性,Agora 推荐使用 设置视频编码属性 (setVideoEncoderConfiguration)

public abstract int setVideoProfile(int profile, boolean swapWidthAndHeight);

该方法设置视频的编码属性。如果用户加入频道后不需要重新设置视频编码属性,则 Agora 建议在 enableVideo 前调用该方法,可以加快首帧出图的时间。

名称 描述
profile 视频属性 (profile),详见 视频分辨率、帧率、码率对照表 中的定义
swapWidthAndHeight

SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高:

  • true:交换宽和高,交换后视频为 Portrait(竖屏)布局,即宽 < 高
  • false:(默认)不交换宽和高,视频为 Landscape(横屏)布局,即宽 > 高
返回值
  • 0:方法调用成功
  • < 0:方法调用失败
手动设置视频属性(setVideoProfile)

Note

该接口已废弃。如果需要设置视频编码属性,Agora 推荐使用 设置视频编码属性 (setVideoEncoderConfiguration)

public abstract int setVideoProfile(int width, int height, int frameRate, int bitrate);

如果上表中的 Profile 和你需求的不一致,也可以使用该接口手动设置视频的宽、高、帧率和码率。如果用户加入频道后不需要重新设置视频编码属性,则 Agora 建议在 enableVideo 前调用该方法,可以加快首帧出图的时间。

名称 描述
width 你想要设置的视频宽度,最高值不超过 1280
height 你想要设置的视频高度,最高值不超过 720
frameRate 你想要设置的视频帧率,最高值不超过 30,如: 5、10、15、24、30 等
bitrate

你想要设置的视频码率,需要开发者根据想要设置的视频的宽、高和帧率,并结合上表,手动推算出合适值。宽和高固定的情况下,码率随帧率的变化而变化

  • 若选取的帧率为 5 FPS,则推算码率为上表推荐码率除以 2
  • 若选取的帧率为 15 FPS,则推算码率为上表推荐码率
  • 若选取的帧率为 30 FPS,则推算码率为上表码率乘以 1.5
  • 若选取其余帧率,等比例推算即可

若设置的视频码率超出合理范围,SDK 会自动按照合理区间处理码率

设置本地视频显示属性 (setupLocalVideo)

public abstract int setupLocalVideo(VideoCanvas local);

该方法设置本地视频显示信息。应用程序通过调用此接口绑定本地视频流的显示视窗(view),并设置视频显示模式。 在应用程序开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入频道。退出频道后,绑定仍然有效,如果需要解除绑定,可以指定空(NULL)View 调用 setupLocalVideo()

名称 描述
local

设置视频属性。Class VideoCanvas:

  • view:视频显示视窗
  • renderMode:视频显示模式
    • RENDER_MODE_HIDDEN (1):视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
    • RENDER_MODE_FIT (2):视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
  • 返回值:本地用户 ID,与 joinChannel 中的 uid 保持一致
返回值
  • 0:方法调用成功
  • < 0:方法调用失败

设置远端视频显示属性 (setupRemoteVideo)

public abstract int setupRemoteVideo(VideoCanvas remote);

该方法绑定远程用户和显示视图,即设定 uid 指定的用户用哪个视图显示。调用该接口时需要指定远程视频的 uid,一般可以在进频道前提前设置好。

如果应用程序不能事先知道对方的 uid,可以在 APP 收到 onUserJoined 事件时设置。如果启用了视频录制功能,视频录制服务会做为一个哑客户端加入频道,因此其他客户端也会收到它的 onUserJoined 事件,APP 不应给它绑定视图(因为它不会发送视频流),如果 APP 不能识别哑客户端,可以在 onFirstRemoteVideoDecoded 事件时再绑定视图。解除某个用户的绑定视图可以把 view 设置为空。退出频道后,SDK 会把远程用户的绑定关系清除掉。

名称 描述
remote

设置视频属性。Class VideoCanvas:

  • view:视频显示视窗
  • renderMode:视频显示模式
    • RENDER_MODE_HIDDEN (1):视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
    • RENDER_MODE_FIT (2):视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
返回值
  • 0:方法调用成功
  • < 0:方法调用失败

用双流/单流模式 (enableDualStreamMode)

public abstract int enableDualStreamMode(boolean enabled);

使用该方法设置单流(默认)或者双流模式。发送端开启双流模式后,接收端可以选择接收大流还是小流。 其中,大流指高分辨率、高码率的视频流,小流指低分辨率、低码率的视频流。

名称 描述
enabled

指定双流或者单流模式:

  • true: 双流
  • false: 单流(默认)
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

设置视频大小流 (setRemoteVideoStreamType)

public abstract int setRemoteVideoStreamType(int uid, int streamType);

当远端用户发送了双流 (视频大流和小流) 时,使用该方法本地用户可以选择接收远端用户的视频大流还是小流。 该方法可以根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。 本方法调用状态将在下文的 onApiCallExecuted 中返回。Agora SDK 默认收到视频大流。如需使用视频小流,调用本方法进行切换。

名称 描述
uid 用户 ID
streamType

设置视频流大小。视频流类型如下:

  • VIDEO_STREAM_HIGH = 0:视频大流
  • VIDEO_STREAM_LOW = 1:视频小流
返回值
  • 0:方法调用成功
  • < 0:方法调用失败

视频大流的分辨率有三种配置分别为1:1, 4:3, 16:9。视频小流默认和大流的宽高比一致。根据当前大流的宽高比,系统自动配置小流分辨率如下:

分辨率 帧率 关键帧间隔 码率(kbps)
160*160 5 5 45
160*120 5 5 32
160*90 5 5 28

设置远端视频的默认视频流类型 (setRemoteDefaultVideoStreamType)

public abstract int setRemoteDefaultVideoStreamType(int streamType);

该方法设置远端视频默认为大流或小流。

名称 描述
streamType

设置视频流类型。视频流类型如下:

  • VIDEO_STREAM_HIGH = 0:视频大流
  • VIDEO_STREAM_LOW = 1:视频小流
返回值
  • 0:方法调用成功
  • < 0:方法调用失败

设置视频优化选项 (setVideoQualityParameters)

public abstract int setVideoQualityParameters(boolean preferFrameRateOverImageQuality);

该方法允许用户设置视频的优化选项。

名称 描述
preferFrameRateOverImageQuality

支持两种优化选项:

  • true:画质和流畅度里,优先保证流畅度
  • false:画质和流畅度里,优先保证画质 (默认)
返回值
  • 0:方法调用成功
  • < 0:方法调用失败

开启视频预览 (startPreview)

public abstract int startPreview();

该方法用于在进入频道前启动本地视频预览。调用该 API 前,必须:

  • 调用 setupLocalVideo 设置预览窗口及属性
  • 调用 enableVideo() 开启视频功能。

Note

使用该方法开启本地视频预览后,如果直接调用 leaveChannel 退出频道,并不会关闭视频预览。如需关闭预览,请调用 stopPreview

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

停止视频预览 (stopPreview)

public abstract int stopPreview();

该方法用于停止本地视频预览。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

设置画中画布局 (setVideoCompositingLayout)

Note

该接口已废弃,Agora 不推荐使用。如果希望设置 CDN 推流合图布局,可以调用 setLiveTranscoding 方法实现。

public abstract int setVideoCompositingLayout(const VideoCompositingLayout layout);

使用该方法设置直播场景里的画中画布局。该方法仅适用于在 Agora 服务器端推流的场景。当您在服务器端进行推流时:

  1. 定义一个画布(canvas): 画布的宽和高(即视频的分辨率), 背景颜色,和您想在屏幕上显示的视频总数。
  2. 在画布上定义每个视频的位置和尺寸(无论画布定义的宽和高有多大,每个视频用 0 到 1 的相对位置和尺寸进行定义),图片所在的图层,图片的透明度,视频是经过裁减的还是缩放到合适大小等等。

服务端推流程序在生成 H.264 视频流并通过 RTMP 协议推送给 CDN 服务商时,会将自定义布局的详细信息格式化为 JSON 字符串,打包到在每个关键帧的 SEI 信息中,SEI 的类型为 100 。

下表包含各参数的详细解释,建议您阅读 调整合图布局, 通过不同场景示例,进一步了解如何使用该方法动态、灵活地设置画中画布局。

Note

  • 请确保在频道内调用该方法。
  • 应用程序需保证同一频道内仅有一人调用该方法,如果同一频道内有多人调用该方法,其他调用了该方法的用户需调用 clearVideoCompositingLayout 取消已设置的画中画布局,仅留一人保留布局设置。
名称 描述
canvasWidth 整个屏幕(画布)的宽度
canvasHeight 整个屏幕(画布)的高度
backgroundColor 用以定义屏幕(画布)的背景颜色,可根据 RGB 填写所需颜色对应的 6 位 符号
regions AgoraRtcVideoCompositingRegion 的主播用户列表。频道内每位主播在屏幕上均可以有一个区域显示自己的头像或视频,包括:
enabled
  • uid: 待显示在该区域的主播用户 uid
  • x[0.0,1.0]: 屏幕里该区域的横坐标
  • y[0.0,1.0]: 屏幕里该区域的纵坐标
  • width[0.0, 1.0]:该区域的实际宽度
  • height[0.0, 1.0]:该区域的实际高度
  • zOrder[0, 100]: 用于定义图层。 0 表示该区域图像位于最下层,而 100 表示该区域图像位于最上层
  • alpha[0.0, 1.0]: 用于定义图像的透明度。 0 表示图像为透明的, 1 表示图像为完全不透明的
  • renderMode: * AgoraVideoRenderModeHidden(1): 经过裁减的 * AgoraVideoRenderModeFit(2): 缩放到合适大小
appData 应用程序自定义的数据

下面的例子用来描述主播图像的位置和尺寸:

../_images/sei_overview.png

清除画中画布局 (clearVideoCompositingLayout)

Note

该接口已废弃,Agora 不推荐使用。

public abstract int clearVideoCompositingLayout();

该方法删除使用 setVideoCompositingLayout 方法进行的设置。

设置本地视频显示模式 (setLocalRenderMode)

public abstract int setLocalRenderMode(int mode);

该方法设置本地视频显示模式。应用程序可以多次调用此方法更改显示模式。

名称 描述
mode

设置视频显示模式:

  • RENDER_MODE_HIDDEN (1):如果视频尺寸与显示视窗尺寸不一致,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗
  • RENDER_MODE_FIT (2):如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边
返回值
  • 0:方法调用成功
  • 1:方法调用失败

设置远端视频显示模式 (setRemoteRenderMode)

public abstract int setRemoteRenderMode(int uid, int mode);

该方法设置远端视频显示模式。应用程序可以多次调用此方法更改显示模式。

名称 描述
uid 远端用户 UID
mode

设置视频显示模式:

  • RENDER_MODE_HIDDEN (1):如果视频尺寸与显示视窗尺寸不一致,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗
  • RENDER_MODE_FIT (2):如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边
  • RENDER_MODE_ADAPTIVE (3):该模式已废弃,不推荐使用
返回值
  • 0:方法调用成功
  • 1:方法调用失败

设置本地推流回退选项 (setLocalPublishFallbackOption)

public abstract int setLocalPublishFallbackOption(int option);

网络不理想的环境下,直播音视频的质量都会下降。使用该接口并将 option 设置为 2 后,SDK 会在上行弱网且音视频质量严重受影响时,自动关断视频流,从而保证或提高音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。 当本地推流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发 本地发布的媒体流已回退为音频流 (onLocalPublishFallbackToAudioOnly) 回调。

Note

CDN 推流场景下,设置本地推流回退为 Audio Only 可能会导致远端的 CDN 用户听到声音的时间有所延迟。因此在有 CDN 推流的场景下,Agora 建议不开启该功能。

名称 描述
option

本地推流回退处理选项:

  • STREAM_FALLBACK_OPTION_DISABLED = 0:(默认)上行网络较弱时,不对音视频流作回退处理,但不能保证音视频流的质量
  • STREAM_FALLBACK_OPTION_AUDIO_ONLY = 2:上行网络较弱时只发布音频流
返回值
  • 0:方法调用成功
  • < 0:方法调用不成功

设置远端订阅流回退选项 (setRemoteSubscribeFallbackOption)

public abstract int setRemoteSubscribeFallbackOption(int option);

网络不理想的环境下,直播音视频的质量都会下降。使用该接口并将 option 设置为 1 或者 2 后,SDK 会在下行弱网且音视频质量严重受影响时,将视频流切换为小流,或关断视频流,从而保证或提高音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。 当远端订阅流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发 远端订阅流已回退为音频流 (onRemoteSubscribeFallbackToAudioOnly) 回调。

名称 描述
option

远端订阅流回退处理选项:

  • STREAM_FALLBACK_OPTION_DISABLED = 0:下行网络较弱时,不对音视频流作回退处理,但不能保证音视频流的质量
  • STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW = 1:(默认)下行网络较弱时只接收视频小流。该选项只对该方法有效,对 setLocalPublishFallbackOption 方法无效
  • STREAM_FALLBACK_OPTION_AUDIO_ONLY = 2:下行网络较弱时,先尝试只接收视频小流;如果网络环境无法显示视频,则再回退到只接收远端订阅的音频流
返回值
  • 0:方法调用成功
  • < 0:方法调用不成功

添加本地视频水印 (addVideoWatermark)

public abstract int addVideoWatermark(AgoraImage watermark);

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的观众,旁路直播观众,甚至录制设备都能看到或采集到该水印图片。 如果你仅仅希望在旁路直播推流中添加水印,请参考 设置直播转码 (setLiveTranscoding) 中描述的用法。

AgoraImage 定义
public class AgoraImage {
    public String url;
    public int x;
    public int y;
    public int width;
    public int height;

    public AgoraImage() {
    }
}
名称 描述
url 直播视频上图片的 url 地址
x 图片左上角在视频帧上的横轴坐标
y 图片左上角在视频帧上的纵轴坐标
width 图片在视频帧上的宽度
height 图片在视频帧上的高度

Note

  • 在本地直播和旁路直播中,url 的定义不同。本地直播中,url 指本地直播视频上图片的本地绝对路径;旁路直播中,url 指旁路直播视频上图片的 Url 地址
  • 待添加图片的源文件格式必须是 PNG。如果待添加的 PNG 图片的尺寸与你该方法中设置的尺寸不一致,SDK 会对 PNG 图片进行裁剪,以与设置相符
  • Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印
  • 如果你在 设置视频编码属性 (setVideoEncoderConfiguration) 方法中将 orientationMode 设置为 ADAPTIVE 模式,则如果视频帧在播放端发生旋转,水印也会以其左上角为坐标原点,跟着视频帧旋转。

删除已添加的视频水印 (clearVideoWatermarks)

public abstract int clearVideoWatermarks();

该方法删除视频上添加的水印。

设置本地视频镜像 (setLocalVideoMirrorMode)

public abstract int setLocalVideoMirrorMode(int mode);

该方法设置本地视频镜像,须在开启本地预览前设置。如果在开启预览后设置,需要重新开启预览才能生效。

名称 描述
mode

设置本地视频镜像模式

  • 0:默认镜像模式,即由 SDK 决定镜像模式
  • 1:启用镜像模式
  • 2:关闭镜像模式
返回值
  • 0:该方法调用成功
  • < 0:该方法调用失败

管理摄像头

切换前置/后置摄像头 (switchCamera)

public abstract int switchCamera();

该方法用于在前置/后置摄像头间切换。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

检测设备是否支持相机缩放功能 (isCameraZoomSupported)

public abstract boolean isCameraZoomSupported();

返回值:

  • true: 设备支持相机缩放功能
  • false: 设备不支持相机缩放功能

检测设备是否支持闪光灯常开 (isCameraTorchSupported)

public abstract boolean isCameraTorchSupported();

返回值:

  • true: 设备支持闪光灯常开
  • false: 设备不支持闪光灯常开

Note

一般情况下,App 默认开启前置摄像头,因此如果你的前置摄像头不支持闪光灯常开,直接使用该方法会返回 false。如果需要检查后置摄像头是否支持闪光灯常开,需要先使用 switchCamera 切换摄像头,再使用该方法。

检测设备是否支持手动对焦功能 (isCameraFocusSupported)

public abstract boolean isCameraFocusSupported();

返回值:

  • true: 设备支持手动对焦功能
  • false: 设备不支持手动对焦功能

检测设备是否支持人脸对焦功能 (isCameraAutoFocusFaceModeSupported)

public abstract boolean isCameraAutoFocusFaceModeSupported();

返回值:

  • true: 设备支持人脸对焦功能;
  • false: 设备不支持人脸对焦功能;

设置相机缩放比例 (setCameraZoomFactor)

public abstract int setCameraZoomFactor(float factor);

该方法设置相机的缩放比例。

名称 描述
factor 相机缩放比例,有效范围从 1.0 到最大缩放

获取相机支持最大缩放比例 (getCameraMaxZoomFactor)

public abstract float getCameraMaxZoomFactor();

返回值: 该相机支持的最大缩放比例。

设置手动对焦位置,并触发对焦 (setCameraFocusPositionInPreview)

public abstract int setCameraFocusPositionInPreview(float positionX, float positionY);
名称 描述
positionX 触摸点相对于视图的横坐标
positionY 触摸点相对于视图的纵坐标

设置是否打开闪光灯 (setCameraTorchOn)

public abstract int setCameraTorchOn(boolean isOn);
名称 描述
isOn

是否打开闪光灯:

  • true: 打开
  • false: 关闭

设置是否开启人脸对焦功能 (setCameraAutoFocusFaceModeEnabled)

public abstract int setCameraAutoFocusFaceModeEnabled(boolean enabled);
名称 描述
enabled

是否开启人脸对焦功能:

  • true: 打开
  • false: 关闭

打开与 Web SDK 的互通 (enableWebSdkInteroperability)

public abstract int enableWebSdkInteroperability(boolean enabled);

该方法打开或关闭与 Agora Web SDK 的互通。

名称 描述
enabled

是否已打开与 Agora Web SDK 的互通:

  • true:打开互通
  • false:关闭互通
返回值
  • 0:方法调用成功
  • < 0:方法调用失败

设置语音路由

修改默认的语音路由 (setDefaultAudioRouteToSpeakerphone)

public abstract int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeaker);

Note

  1. 该方法只在纯音频模式下工作,在有视频的模式下不工作。
  2. 该方法需要在 joinChannel 前设置,否则不生效。

如有必要,调用该方法修改默认的语音路由。默认的语音路由如下:

频道模式 默认语音路由
通信
  • 语音通话: 听筒
  • 视频通话: 外放
  • 视频通话中关闭视频 [2] : 听筒
直播 外放
游戏语音 外放

脚注

[2]已调用 disableVideo 或 已调用 muteLocalVideoStream/muteAllRemoteVideoStreams

如有需要, 根据下表修改上述默认的语音路由:

名称 描述
defaultToSpeaker
  • true: 默认路由改为外放(扬声器)
  • false: 默认路由改为听筒

无论语音是从外放还是听筒出声,如果插上耳机或连接蓝牙,语音路由会发生相应改变。拔出耳机或断开蓝牙后语音路由将恢复成默认路由。

返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

打开扬声器 (setEnableSpeakerphone)

public abstract int setEnableSpeakerphone(boolean enabled);

该方法将语音路由强制设置为扬声器(外放)。调用该方法后,SDK 将返回 onAudioRouteChanged 回调提示状态已更改。

Note

在调用该方法前,请先阅读 修改默认的语音路由 (setDefaultAudioRouteToSpeakerphone) 里关于默认语音路由的说明,确认是否需要调用该方法。

名称 描述
enabled
  • true:

    • 如果用户已在频道内,无论之前语音是路由到耳机,蓝牙,还是听筒,调用该 API 后均会默认切换到从外放(扬声器)出声。
    • 如果用户尚未加入频道,调用该API后,无论用户是否有耳机或蓝牙设备,在加入频道时均会默认从外放(扬声器)出声。
  • false: 语音会根据默认路由出声,详见 修改默认的语音路由 (setDefaultAudioRouteToSpeakerphone)

返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

是否是扬声器状态 (isSpeakerphoneEnabled)

public abstract boolean isSpeakerphoneEnabled();

该方法检查扬声器是否已开启。

名称 描述
返回值
  • true: 表明输出到扬声器
  • false: 表明输出到非扬声器(听筒,耳机等)

启用耳返监听 (enableInEarMonitoring)

public abstract int enableInEarMonitoring(boolean enabled);

该方法打开或关闭耳返监听功能。

名称 描述
enabled
  • true: 启用耳返监听功能
  • false: 禁用耳返监听功能(默认)
返回值
  • 0: 方法调用成功
  • < 0:方法调用失败

设置音量

启用说话者音量提示 (enableAudioVolumeIndication)

public abstract int enableAudioVolumeIndication(int interval, int smooth);

该方法允许 SDK 定期向应用程序反馈当前谁在说话以及说话者的音量。启用该方法后,无论频道内是否有人说话,都会在 说话声音音量提示回调 (onAudioVolumeIndication) 回调中按设置的间隔时间返回音量提示。

名称 描述
interval

指定音量提示的时间间隔:

  • <= 0:禁用音量提示功能
  • > 0:返回音量提示的间隔,单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒,否则会收不到 onAudioVolumeIndication 回调
smooth 平滑系数,指定音量提示的灵敏度。取值范围为 [0-10],建议值为 3,数字越大,波动越灵敏;数字越小,波动越平滑。
返回值
  • 0:方法调用成功
  • < 0:方法调用失败

设置耳返音量 (setInEarMonitoringVolume)

public abstract int setInEarMonitoringVolume(int volume);

该方法设置耳返的音量。

名称 描述
volume 设置耳返音量,取值范围在 0 到 100 间,默认值为 100

自定义视频源和渲染器

设置视频源 (setVideoSource)

public abstract int setVideoSource(IVideoSource source);

实时通讯过程中,Agora SDK 通常会启动默认的视频输入设备,即内置的摄像头,进行视频推流。当需要自定义视频设备时,App 可以先通过 IVideoSource 接口 自定义视频源,然后调用该方法将自定义的视频源加入到 SDK 中。

名称 描述
source 自定义的视频源。详细的 IVideoSource 定义见 IVideoSource 接口 中的描述

设置本地视频渲染器 (setLocalVideoRenderer)

public abstract int setLocalVideoRenderer(IVideoSink render);

该方法设置本地视频渲染器。实时通讯过程中,Agora SDK 通常会启动默认的视频渲染器进行视频渲染。当需要自定义视频渲染设备时,App 可以先通过 IVideoSink 接口 自定义渲染器,然后调用该方法将视频渲染器加入到 SDK 中。

名称 描述
render 自定义的本地视频渲染器。详细的 IVideoRenderer 定义见 IVideoSink 接口 中的描述

设置远端视频渲染器 (setRemoteVideoRenderer)

public abstract int setRemoteVideoRenderer(int uid, IVideoSink render);

该方法设置远端视频渲染器。实时通讯过程中,Agora SDK 通常会启动默认的视频渲染器进行视频渲染。当需要自定义视频设备时,App 可以先通过 IVideoSink 接口 自定义渲染器,然后调用该方法将视频渲染器加入到 SDK 中。

名称 描述
uid 远端用户的 UID
render 自定义的远端视频渲染器。详细的 IVideoRenderer 定义见 IVideoSink 接口 中的描述

自定义设备 API

该组接口允许开发者创建自定义的视频源和渲染器,传输给底层的媒体引擎,以替代默认的视频源。该组 API 计划会在未来取代下面的 自采集 API裸数据 API

自定义设备 API 包含如下两组接口:

IVideoSource 接口 IVideoSource 接口定义了一套协议,开发者通过实现该接口,来创建自定义的视频源,并设置给 Agora 底层的 Media Engine
IVideoSink 接口 IVideoSink 接口定义了一套协议,开发者通过实现该接口,来创建自定义的视频渲染器,并设置给 Agora 底层的 Media Engine

Note

  • 目前自定义设备 API 仅支持自定义视频设备。Agora 会在将来添加自定义音频设备的 API。如果想要使用自采集的音频设备,可以使用 自采集 API 实现。
  • 这两组接口中定义的方法都是回调方法,Media Engine 内部维护着状态机,并使用这些方法将自定义视频源及渲染器的状态传给 Media Engine。因此请避免直接在 App 中直接调用这些接口。

IVideoSource 接口

public interface IVideoSource {
  boolean onInitialize(IVideoFrameConsumer consumer);
  boolean onStart();
  void onStop()
  void onDispose();
  int getBufferType();
}

实时通讯过程中,Agora SDK 通常会启动默认的视频输入设备,即内置的摄像头,进行视频推流。 使用 IVideoSource 接口可以自定义视频源。通过调用 设置视频源 (setVideoSource) 接口,可以改变并控制默认的视频输入设备,再将自定义的视频源发送给 Agora Media Engine,让 Media Engine 进行其它视频处理,如过滤视频、将视频发布到 RTC 链接等。

初始化视频源 (onInitialize)
boolean onInitialize(IVideoFrameConsumer consumer);

Media Engine 在初始化视频源的时候会回调此方法。开发者可以在这个方法中做一些准备工作,例如打开 Camera,或者初始化视频源,并通过返回值告诉 Media Engine,自定义的视频源是否已经准备好。

名称 描述
consumer Media Engine 传递给开发者的一个 IVideoFrameConsumer 对象。开发者需要保存该对象,并在视频源启动后,通过这个对象把视频帧输入给 Media Engine。详细定义见下文
返回值

开发者需要手动输入返回值,以告诉 Media Engine 自定义视频源是否已准备好:

  • true:自定义的视频源已经完成了初始化工作
  • false:自定义的视频源设备没准备好或者初始化失败,Media Engine 会停下来并上报错误

Note

自定义视频源时,开发者需要通过 获取 Buffer 类型 (getBufferType) 来指定一种 Buffer 类型,并在自定义视频源中只使用与其对应的方法来传递视频帧数据。

IVideoFrameConsumer 定义

public interface IVideoFrameConsumer {
  void consumeByteBufferFrame(ByteBuffer buffer, int format, int width, int height, int rotation, long timestamp);
  void consumeByteArrayFrame(byte[] data, int format, int width, int height, int rotation, long timestamp);
  void consumeTextureFrame(int textureId, int format, int width, int height, int rotation, long timestamp, float[] matrix);
 }

IVideoFrameConsumer 支持接收三种 Buffer 类型的视频帧数据:ByteBuffe、ByteArray 和 Texture 类型,各类型包含的视频帧信息如下:

ByteBuffer 类型

参数 描述
buffer ByteBuffer 型的 Buffer
format

像素格式:

  • I420(1):YUV420p
  • NV21(3):YUV420sp
  • RGBA(4):RGBA8888
  • TEXTURE_2D(10):GL_TEXTURE_2D 格式
  • TEXTURE_OES(11):GL_TEXTURE_OES 格式
width 视频帧的宽度
height 视频帧的高度
rotation 视频帧顺时针旋转的角度。如果设置了旋转角度,媒体引擎会对图像进行旋转。你可以根据需要将角度值设为 0 度、90 度、180 度和 270 度,如果设置为其他数字,系统会自动忽略
timestamp 传入的视频帧的时间戳,以毫秒为单位。开发者必须为每一个视频帧设置一个时间戳

ByteArray 类型

参数 描述
data Byte 数据
format

像素格式:

  • I420(1):YUV420p
  • NV21(3):YUV420sp
  • RGBA(4):RGBA8888
  • TEXTURE_2D(10):GL_TEXTURE_2D 格式
  • TEXTURE_OES(11):GL_TEXTURE_OES 格式
width 视频帧的宽度
height 视频帧的高度
rotation 视频帧顺时针旋转的角度。如果设置了旋转角度,媒体引擎会对图像进行旋转。你可以根据需要将角度值设为 0 度、90 度、180 度和 270 度,如果设置为其他数字,系统会自动忽略
timestamp 传入的视频帧的时间戳,以毫秒为单位。开发者必须为每一个视频帧设置一个时间戳

Texture 类型

参数 描述
textureId texture 的 ID
format

像素格式:

  • I420(1):YUV420p
  • NV21(3):YUV420sp
  • RGBA(4):RGBA8888
  • TEXTURE_2D(10):GL_TEXTURE_2D 格式
  • TEXTURE_OES(11):GL_TEXTURE_OES 格式
width 视频帧的宽度
height 视频帧的高度
rotation 视频帧顺时针旋转的角度。如果设置了旋转角度,媒体引擎会对图像进行旋转。你可以根据需要将角度值设为 0 度、90 度、180 度和 270 度,如果设置为其他数字,系统会自动忽略
timestamp 传入的视频帧的时间戳,以毫秒为单位。开发者必须为每一个视频帧设置一个时间戳
matrix texture 的纹理坐标。浮点数 float 一般介于 0~1 之间,如 0.1,0.2 等

Note

当直接把 Texture 作为视频帧传给 Media Engine 进行编码的时候,必须在 GL 环境下调用 consumeTextureFrame() 方法,并且是创建 textureId 的 GL 环境。

关于 YUV 图像格式的定义,请参考如下链接:

http://www.fourcc.org/yuv.php

https://msdn.microsoft.com/en-us/library/windows/desktop/dd206750(v=vs.85).aspx

启动视频源 (onStart)
boolean OnStart();

Media Engine 在启动视频源时会回调这个方法。开发者可以在该方法中启动视频帧捕捉。开发者需要通过返回值告诉告知 Media Engine 自定义的视频源是否开启成功。

名称 描述
返回值

开发者需要手动输入返回值,以告诉 Media Engine 自定义视频源是否开启:

  • true:自定义的视频源已成功开启,接下来会打开 IVideoFrameConsumer 的开关,接收开发者传输的视频帧
  • false:自定义的视频源设备启动失败,Media Engine 会停下来并上报错误
停止视频源 (onStop)
void OnStop();

Media Engine 在停止视频源的时候会回调这个方法。开发者可以在这个方法中停止视频的采集。Media Engine 通过这个回调通知开发者,VideoFrameConsumer 的帧输入开关即将关闭,之后输入的视频帧都会被丢弃。

释放视频源 (onDispose)
void OnDispose();

Media Engine 通知开发者视频源即将失效,开发者可以在这个方法中关闭视频源设备。引擎会销毁 IVideoFrameConsumer 对象,开发者需要确保在此回调之后不再使用它。

获取 Buffer 类型 (getBufferType)
int getBufferType();

Media Engine 在初始化的时候,会调用这个方法来查询该视频源所使用的 Buffer 类型。开发者必须指定且只能指定一种 Buffer 类型并通过返回值告诉 Media Engine

参数 描述
返回值
开发者在返回值中指定一种 Buffer 类型并告知 Media Engine
  • BYTE_BUFFER(1):使用 ByteBuffer 作为 Buffer 容器
  • BYTE_ARRAY(2):使用 ByteArray 作为 Buffer 容器
  • TEXTURE(3):使用 Texture 作为 Buffer 容器

IVideoSink 接口

public interface IVideoSink extends IVideoFrameConsumer {
    boolean onInitialize();
    boolean onStart();
    void onStop();
    void onDispose();
    int getBufferType();
    int getPixelFormat();
}

实时通讯过程中,Agora SDK 通常会启动默认的视频渲染器进行视频渲染。 IVideoSink 接口可以自定义视频渲染器,再通过调用 设置本地视频渲染器 (setLocalVideoRenderer)设置远端视频渲染器 (setRemoteVideoRenderer) 接口,改变并控制默认的视频渲染器。 该接口中的 IVideoFrameConsumer 提供视频帧数据的传递的接口,Media Engine 通过它把视频帧数据送给渲染器。详细的 IVideoFrameConsumer 定义请见上文 初始化视频源 (onInitialize) 中的描述。

初始化渲染器 (onInitialize)
boolean onInitialize();

Media Engine 初始化渲染器的时候调用这个方法。开发者可以在这个方法中做渲染器的初始化工作。如果是耗时操作,也可以提前初始化好,然后在这个方法中通过返回值告知 Media Engine 自定义渲染器已初始化好。

该方法需要开发者输入返回值,告知 Media Engine 自定义渲染器的状态:

  • true:Media Engine 会认为自定义的渲染器已经初始化好
  • false:Media Engine 会认为自定义的渲染器初始化失败,不继续往下运行
启动渲染器 (onStart)
boolean onStart();

Media Engine 在开启渲染功能的时候会回调这个方法。开发者可以在这个方法中启动渲染器。

该方法需要开发者输入返回值,Media Engine 会根据返回值做对应的动作:

  • true:Media Engine 继续进行渲染
  • false:Media Engine 认为出错而停止渲染器的功能
停止渲染器 (onStop)
void onStop();

Media Engine 在停止渲染功能的时候会回调这个方法。开发者可以在这个方法中停止渲染。

释放渲染器 (onDispose)
void onDispose();

Media Engine 通知开发者渲染器即将被废弃。在 onDispose() 返回之后,开发者就可以释放掉资源了。

获取 EGLContextHandle (getEGLContextHandle)
public long getEGLContextHandle();

Media Engine 在需要创建 EGLContext 的时候,首先会从自定义的渲染器中查询,是都已经创建了 EGLContext。如果自定义渲染器中已经创建了并管理 EGL 环境,这个方法就会返回 EGLContext 的 Native Handle 并共享给 Media Engine。如果自定义渲染器中没有创建 EGLContext,会返回 0。

获取 Buffer 类型 (getBufferType)
void getBufferType();

用于在自定义渲染器的时候,需要指定 Buffer 类型,通过返回值告知引擎。Media Engine 会调用这个方法并检查返回值类型。有三种 Buffer 类型:

参数 描述
返回值
开发者在返回值中指定一种 Buffer 类型并告知 Media Engine:
  • BYTE_BUFFER(1):使用 ByteBuffer 作为 Buffer 容器
  • BYTE_ARRAY(2):使用 ByteArray 作为 Buffer 容器
  • TEXTURE(3):使用 Texture 作为 Buffer 容器
获取像素格式 (getPixelFormat)
void getPixelFormat();

用于自定义渲染器的时候,还需要指定视频数据的像素格式。当自定义渲染器希望得到 ByteArray 或者 ByteBuffer 类型的视频数据时,可以选择 YUV(YUV20P)或 RGBA 格式;当自定义渲染器希望直接得到 Texture 时,也可以选择 Texture。

format

像素格式:

  • I420(1):YUV420p
  • NV21(3):YUV420sp
  • RGBA(4):RGBA8888
  • TEXTURE_2D(10):GL_TEXTURE_2D 格式
  • TEXTURE_OES(11):GL_TEXTURE_OES 格式

自采集 API

音频自采集

Note

  • 如果客户没有特殊需求,不建议使用自采集;
  • 如果客户有特殊需求,如使用 IoT 设备,而选择使用自采集时,请注意:Agora SDK 不提供自采集音频信号处理机制,如回声抑制,自动增益,啸叫抑制等,客户需要自己处理。
设置外部音频采集参数 (setExternalAudioSource)
public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels);
名称 描述
enable 是否开启外部音频源
sampleRate 外部音频源的采样率
channels 外部音频源的通道数(最多支持两个声道)
推送外部音频帧 (pushExternalAudioFrame)
public abstract int pushExternalAudioFrame(byte[] data, long timestamp);
名称 描述
data 外部音频数据
timestamp 外部音频帧的时间戳,用于和外部视频源同步

视频自采集

本章向有自采集需求的用户介绍如何配置外部视频源。它将原来 libvideoprp 里支持的外部视频源功能和 texture 编码接口功能合并了。 同时它将 yuv/rgba/texture 图片发送到 Agora SDK 进行编码。

Note

建议新开发的 App 使用该方法,用户体验更好。

检查是否支持 Texture 编码 (isTextureEncodeSupported)
public abstract boolean isTextureEncodeSupported();

该方法检查该设备是否支持 Texture 编码。

配置外部视频源 (setExternalVideoSource)
public abstract void setExternalVideoSource(boolean enable, boolean useTexture, boolean pushMode);

该方法设置是否使用外部视频源:

  • 如果是,是否使用 texture 作为输入;
  • 如果不是,是否将视频帧主动推送到 Agora SDK 进行编码;
名称 描述
enable [3]

是否使用外部视频源:

  • true:使用外部视频源
  • false:不适用外部视频源
useTexture

是否使用 Texture 作为输入:

  • true:使用 texture 作为输入
  • false:不使用 texture 作为输入
pushMode

是否外部视频源需要调用 pushExternalVideoFrame 将视频帧主动推送给 Agora SDK:

  • true:使用推送 (push) 模式
  • false:使用拉取 (pull) 模式(暂不支持)

脚注

[3]目前 Agora SDK 不支持频道内动态切换视频源。如果您启用了外部视频源,且已经在频道内,如果想切换成外部视频源,须先退出频道,调用本方法将参数 enable 设为 false 后,再重新加入频道。
推送外部视频帧 (pushExternalVideoFrame)
public abstract boolean pushExternalVideoFrame(AgoraVideoFrame frame);

该方法主动将视频帧数据用 AgoraVideoFrame 类封装后传递给 SDK 。 请确保在你调用本方法前已调用 setExternalVideoSource, 并将参数 pushMode 设为 true ,不然调用本方法后会一直报错。

Note

视频通话过程中,该接口目前不支持推送 Texture 格式的视频帧。

名称 描述
frame 该视频帧包含待 Agora SDK 编码的视频数据。
返回值
  • true:该帧推送成功
  • false:该帧推送不成功

AgoraVideoFrame 类定义如下:

public AgoraVideoFrame() {

  //mandatory
    public int format;
    public long timeStamp;
    public int stride;
    public int height;

    // Texture related
    public javax.microedition.khronos.egl.EGLContext eglContext11;
    public android.opengl.EGLContext eglContext14;
    public int textureID;
    public boolean syncMode;
    public float[] transform;

    // Raw data related
    public byte[] buf;
    public int cropLeft;
    public int cropTop;
    public int cropRight;
    public int cropBottom;
    public int rotation;
}

其中各个字段的解释,详见下表:

字段 描述
format

[必要]传入的视频帧的格式。必须指定为下面的某一个值:

  • AgoraVideoFrame.FORMAT_TEXTURE_2D
  • AgoraVideoFrame.FORMAT_TEXTURE_OES
  • AgoraVideoFrame.FORMAT_I420
  • AgoraVideoFrame.FORMAT_NV21
  • AgoraVideoFrame.FORMAT_RGBA
timestamp [必要]传入的视频帧的时间戳,以毫秒为单位。不正确的时间戳会导致丢帧或者音视频不同步
stride [必要]传入视频帧的行间距,单位为像素而不是字节。对于 Texture,该值指的是 Texture 的宽度
height [必要]传入视频帧的高度
eglContext11 [Texture 相关的字段]当使用 khronos 定义的 OpenGL 接口 (javax.microedition.khronos.egl.*)时,需要将 EGLContext 设置给这个字段
eglContext14 [Texture 相关的字段]当使用 Android 定义的 OpenGL 接口 (android.opengl.*)时,需要将 EGLContext 设置给这个字段
textureID [Texture 相关的字段]视频帧所使用的 Texture ID
transform [Texture 相关的字段]传入一个 4x4 的变换矩阵,典型值是传入一个单位矩阵
syncMode

[Texture 相关的字段]设置是否等待前一帧编码完成:

  • true:等待
  • false:不等待
buf [原始数据相关字段]传入视频帧的内容数据
cropLeft, cropTop, cropRight, cropBottom [原始数据相关字段]指定各方向裁剪掉的像素数量。默认为 0
rotation [原始数据相关字段]指定是否对传入的视频组做顺时针旋转操作,可选值为 0, 90, 180, 270。默认为 0

代码示例:

当传入的格式为 TEXTURE_2D 时,且是 khronos 定义的 EGLContext 时:

import io.agora.rtc.video.AgoraVideoFrame;

private final static float[] UNIQUE_MAT = {
    1.0f, 0.0f, 0.0f, 0.0f,
    0.0f, 1.0f, 0.0f, 0.0f,
    0.0f, 0.0f, 1.0f, 0.0f,
    0.0f, 0.0f, 0.0f, 1.0f
};

AgoraVideoFrame vf = new AgoraVideoFrame();
vf.format = AgoraVideoFrame.FORMAT_TEXTURE_2D;
vf.timeStamp = System.currentTimeMillis();
vf.stride = 352;
vf.height = 640;
vf.textureID = textureId;
vf.eglContext11 = eglContext;
vf.transform = UNIQUE_MAT;
mMeida Engine.pushExternalVideoFrame(vf);

当传入的格式为 NV21 的YUV图像时:

AgoraVideoFrame vf = new AgoraVideoFrame();
vf.format = AgoraVideoFrame.FORMAT_NV21;
vf.timeStamp = System.currentTimeMillis();
vf.stride = 640;
vf.height = 480;
vf.rotation = rotation;
vf.buf = data;
mMeida Engine.pushExternalVideoFrame(vf);

裸数据 API

设置录制的声音格式 (setRecordingAudioFrameParameters)

public abstract int setRecordingAudioFrameParameters(int sampleRate,
                                                     int channel,
                                                     int mode,
                                                     int samplesPerCall);

该方法设置 onRecordFrame 回调数据的格式。

名称 描述
sampleRate 指定 onRecordFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000。
channel

指定 onRecordFrame 中返回数据的通道数,可设置为 1 或 2:

  • 1:单声道
  • 2:双声道
mode

指定onRecordFrame的使用模式:

  • RAW_AUDIO_FRAME_OP_MODE_READ_ONLY = 0:只读模式,用户仅从 AudioFrame 获取原始数据。例如:若用户通过 Agora SDK 采集数据,自己进行 RTMP 推流,则可以选择该模式。
  • RAW_AUDIO_FRAME_OP_MODE_WRITE_ONLY = 1:只写模式,用户替换 AudioFrame 中的数据以供 Agora SDK 编码传输。例如:若用户自行采集数据,可选择该模式。
  • RAW_AUDIO_FRAME_OP_MODE_READ_WRITE = 2:读写模式,用户从 AudioFrame 获取并修改数据,并返回给 Aogra SDK 进行编码传输。例如:若用户自己有音效处理模块,且想要根据实际需要对数据进行前处理 (例如变声),则可以选择该模式。
samplesPerCall 指定 onRecordFrame 中返回数据的采样点数,如 RTMP 推流应用中通常为 1024

设置播放的声音格式 (setPlaybackAudioFrameParameters)

该方法设置 onPlaybackAudioFrame 回调数据的格式。

public abstract int setPlaybackAudioFrameParameters(int sampleRate,
                                                    int channel,
                                                    int mode,
                                                    int samplesPerCall);
名称 描述
sampleRate 指定 onPlaybackAudioFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000
channel

指定 onPlaybackAudioFrame 中返回数据的通道数,可设置为 1 或 2:

  • 1:单声道
  • 2:双声道
mode

指定 onPlaybackAudioFrame 的使用模式:

  • RAW_AUDIO_FRAME_OP_MODE_READ_ONLY = 0:只读模式,用户仅从 AudioFrame 获取原始数据,不作任何修改。例如:若用户通过 Agora SDK 采集数据,自己进行 RTMP 推流,则可以选择该模式。
  • RAW_AUDIO_FRAME_OP_MODE_WRITE_ONLY = 1:只写模式,用户替换 AudioFrame 中的数据。例如:若用户自行采集数据,可选择该模式。
  • RAW_AUDIO_FRAME_OP_MODE_READ_WRITE = 2:读写模式,用户从 AudioFrame 获取数据、修改。例如:若用户自己有音效处理模块,且想要根据实际需要对数据进行后处理 (例如变声),则可以选择该模式。
samplesPerCall 指定 onPlaybackAudioFrame 中返回数据的采样点数,如RTMP推流应用中通常为 1024

设置录制和播放声音混音后的数据格式 (setMixedAudioFrameParameters)

该方法设置 onMixedAudioFrame 回调数据的格式。

public abstract int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall);
名称 描述
sampleRate 指定 onMixedAudioFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000
samplesPerCall 指定 onMixedAudioFrame 中返回数据的采样点数,如 RTMP 推流应用中通常为 1024

注册语音观测器对象 (registerAudioFrameObserver)

public abstract int registerAudioFrameObserver(IAudioFrameObserver observer);

该方法用于注册语音观测器对象,即注册回调。当需要引擎给出 onRecordFrame 或 onPlaybackFrame 回调时,需要使用该方法注册回调。

名称 描述
observer IAudioFrameObserver 接口对象实例。如果传入 null,则取消注册。

IAudioFrameObserver 定义

public interface IAudioFrameObserver {
    public abstract  boolean onRecordFrame(byte[] samples, int numOfSamples, int bytesPerSample, int channels, int samplesPerSec);
    public abstract  boolean onPlaybackFrame(byte[] samples, int numOfSamples, int bytesPerSample, int channels, int samplesPerSec);
}

详细定义见下文中 onRecordFrame 或 onPlaybackFrame 的描述。

Note

除了 Java 语言的裸数据接口,Android 平台还通过插件提供更精简的 C++ 裸数据接口,Agora 推荐你使用。通过 C++ 的接口,你可以注册更多音频及视频相关回调,包括:

  • onRecordAudioFrame
  • onPlaybackAudioFrame
  • onPlaybackAudioFrameBeforeMixing
  • onMixedAudioFram
  • onCaptureVideoFrame
  • onRenderVideoFrame

你需要在 Android 上使用 SDK 库的 JNI 和插件管理器以使用 C++ 裸数据接口。具体使用方法详见 进阶:修改裸数据

暂停发送音视频流

将自己静音 (muteLocalAudioStream)

public abstract int muteLocalAudioStream(boolean muted);

静音/取消静音。该方法用于允许/禁止往网络发送本地音频流。

Note

该方法不影响录音状态,并没有禁用麦克风。

名称 描述
muted
  • true: 麦克风静音
  • false: 取消静音
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

静音所有远端音频 (muteAllRemoteAudioStreams)

public abstract int muteAllRemoteAudioStreams(boolean muted);

该方法用于允许/禁止接收和播放远端用户的音频流,即对所有远端用户进行静音与否。

名称 描述
muted
  • true: 停止接收和播放所有远端音频流
  • false: 允许接收和播放所有远端音频流
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

静音指定用户音频 (muteRemoteAudioStream)

public abstract int muteRemoteAudioStream(int uid, boolean muted);

静音指定远端用户/对指定远端用户取消静音。

Note

如果之前有调用过 muteAllRemoteAudioStreams (true) 对所有远端音频进行静音,在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams (false) 。 muteAllRemoteAudioStreams 是全局控制,muteRemoteAudioStream 是精细控制。

名称 描述
uid 指定用户 ID
muted
  • true: 停止接收和播放指定音频流
  • false: 允许接收和播放指定音频流
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

暂停本地视频流 (muteLocalVideoStream)

public abstract int muteLocalVideoStream(boolean muted);

该方法暂停发送本地视频流。

Note

调用该方法时,SDK 不再发送本地视频流,但摄像头仍然处于工作状态。相比于 enableLocalVideo (false) 用于控制本地视频流发送的方法,该方法响应速度更快。该方法不影响本地视频流获取,没有禁用摄像头。

名称 描述
mute
  • true: 不发送本地视频流
  • false: 发送本地视频流
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

暂停所有远端视频流 (muteAllRemoteVideoStreams)

public abstract int muteAllRemoteVideoStreams(boolean muted);

该方法用于允许/禁止接收和播放所有人的视频流。

名称 描述
muted
  • true: 停止接收和播放所有远端视频流
  • false: 允许接收和播放所有远端视频流
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

暂停指定远端视频流 (muteRemoteVideoStream)

public abstract int muteRemoteVideoStream(int uid, boolean muted);

该方法用于允许/禁止接收指定的远端视频流。

Note

如果之前有调用过 muteAllRemoteVideoStreams (true) 暂停播放所有远端视频流,在调用本 API 之前请确保你已调用 muteAllRemoteVideoStreams (false) 。 muteAllRemoteVideoStreams 是全局控制,muteRemoteVideoStream 是精细控制。

名称 描述
uid 指定用户的 uid
muted
  • true: 停止接收和播放指定用户的视频流
  • false: 允许接收和播放指定用户的视频流
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

播放伴奏

开始播放伴奏 (startAudioMixing)

public abstract int startAudioMixing(String filePath,
                                     boolean loopback,
                                     boolean replace,
                                     int cycle);

指定本地音频文件来和麦克风采集的音频流进行混音和替换(用音频文件替换麦克风采集的音频流), 可以通过参数选择是否让对方听到本地播放的音频和指定循环播放的次数。该 API 也支持播放在线音乐。

Note

  • 如需调用该方法,请确保使用 Android 4.2 或以上设备,且 API Level>=16。
  • 请在频道内调用该方法,如果在频道外调用该方法可能会出现问题。
  • 如果在模拟器上使用该 API,暂时只支持存放在 /sdcard/ 中的 mp3 文件。
名称 描述
filePath

指定需要混音的本地音频文件名和文件路径名:

  • 如果用户提供的目录以 /assets/ 开头,则去 assets 里面查找该文件
  • 如果用户提供的目录不是以 /assets/ 开头,一律认为是在绝对路径里查找该文件

支持以下音频格式: mp3,aac,m4a, 3gp, wav, flac

loopback
  • true: 只有本地可以听到混音或替换后的音频流
  • false: 本地和对方都可以听到混音或替换后的音频流
replace
  • true: 音频文件内容将会替换本地录音的音频流
  • false: 音频文件内容将会和麦克风采集的音频流进行混音
cycle

指定音频文件循环播放的次数:

  • 正整数: 循环的次数
  • -1:无限循环
返回值
  • 0:方法调用成功
  • <0: 方法调用失败

停止播放伴奏 (stopAudioMixing)

public abstract int stopAudioMixing();

该方法停止播放伴奏。请在频道内调用该方法。

名称 描述
返回值
  • 0:方法调用成功
  • <0: 方法调用失败

暂停播放伴奏 (pauseAudioMixing)

public abstract int pauseAudioMixing();

该方法暂停播放伴奏。请在频道内调用该方法。

名称 描述
返回值
  • 0:方法调用成功
  • <0: 方法调用失败

恢复播放伴奏 (resumeAudioMixing)

public abstract int resumeAudioMixing();

该方法恢复混音,继续播放伴奏。请在频道内调用该方法。

名称 描述
返回值
  • 0:方法调用成功
  • <0: 方法调用失败

调节伴奏音量 (adjustAudioMixingVolume)

public abstract int adjustAudioMixingVolume(int volume);

该方法调节混音里伴奏的音量大小。请在频道内调用该方法。

名称 描述
volume 伴奏音量范围为 0~100。默认 100 为原始文件音量
返回值
  • 0:方法调用成功
  • <0: 方法调用失败

获取伴奏时长 (getAudioMixingDuration)

public abstract int getAudioMixingDuration();

该方法获取伴奏时长,单位为毫秒。请在频道内调用该方法。如果返回值 <0,表明调用失败。

获取伴奏播放进度 (getAudioMixingCurrentPosition)

public abstract int getAudioMixingCurrentPosition();

该方法获取当前伴奏播放进度,单位为毫秒。请在频道内调用该方法。

拖动语音进度条 (setAudioMixingPosition)

public abstract int setAudioMixingPosition(int pos);

该方法可以拖动播放音频文件的进度条,这样你可以根据实际情况播放文件,而不是非得从头到尾播放一个文件。

名称 描述
pos 整数。进度条位置,单位为毫秒

录制

开始客户端录音 (startAudioRecording)

public abstract int startAudioRecording(String filePath, int quality);

Agora SDK 支持通话过程中在客户端进行录音。该方法录制频道内所有用户的音频,并生成一个包含所有用户声音的录音文件,录音文件格式可以为:

  • wav : 文件大,音质保真度高
  • aac : 文件小,有一定的音质保真度损失

请确保应用程序里指定的目录存在且可写。该接口需在加入频道之后调用。如果调用 leaveChannel() 时还在录音,录音会自动停止。

名称 描述
filePath 录音文件的本地保存路径,由用户自行指定,需精确到文件名及格式,例如:/dir1/dir2/dir3/audio.aac
quality

录音音质:

  • AUDIO_RECORDING_QUALITY_LOW = 0: 低音质。录制 10 分钟的文件大小为 1.2 M 左右
  • AUDIO_RECORDING_QUALITY_MEDIUM = 1: 中音质。录制 10 分钟的文件大小为 2 M 左右
  • AUDIO_RECORDING_QUALITY_HIGH = 2: 高音质。录制 10 分钟的文件大小为 3.75 M 左右
返回值
  • 0:方法调用成功
  • < 0:方法调用失败

停止客户端录音 (stopAudioRecording)

public abstract int stopAudioRecording();

停止录音。该接口需要在 leaveChannel() 之前调用,不然会在调用 leaveChannel() 时自动停止。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

调节录音信号音量 (adjustRecordingSignalVolume)

public abstract int adjustRecordingSignalVolume(int volume);

该方法调节录音信号音量。

名称 描述
volume

录音信号音量可在 0~400 范围内进行调节:

  • 0: 静音
  • 100: 原始音量
  • 400: 最大可为原始音量的 4 倍(自带溢出保护)
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

调节播放信号音量 (adjustPlaybackSignalVolume)

public abstract int adjustPlaybackSignalVolume(int volume);

该方法调节播放信号音量。

名称 描述
volume

播放信号音量可在 0~400 范围内进行调节:

  • 0: 静音
  • 100: 原始音量
  • 400: 最大可为原始音量的 4 倍(自带溢出保护)
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

加密

启用内置加密,并设置数据加密密码 (setEncryptionSecret)

public abstract int setEncryptionSecret(String secret);

在加入频道之前,应用程序需调用 setEncryptionSecret() 指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。 当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。

名称 描述
secret 加密密码
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

设置内置的加密方案 (setEncryptionMode)

public abstract int setEncryptionMode(String encryptionMode);

Agora Native SDK 支持内置加密功能,默认使用 AES-128-XTS 加密方式。如需使用其他加密方式,可以调用该 API 设置。

同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别,请参考 AES 加密算法的相关资料。

Note

在调用本方法前,请先调用 setEncryptionSecret() 启用内置加密功能。

名称 描述
encryptionMode

加密方式。目前支持以下几种:

  • “aes-128-xts”: 128 位 AES 加密, XTS 模式
  • “aes-128-ecb”: 128 位 AES 加密, ECB 模式
  • “aes-256-xts”: 256 位 AES 加密,XTS 模式
  • “”: 设置为空字符串时,使用默认加密方式 “aes-128-xts”
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

建立数据通道

创建数据流 (createDataStream)

public abstract int createDataStream(boolean reliable, boolean ordered);

该方法用于创建数据流。频道内每人最多只能创建 5 个数据流。频道内数据通道最多允许数据延迟 5 秒,若超过 5 秒接收方尚未收到数据流,则数据通道会向应用程序报错。

Note

请将 reliableordered 同时设置为 true 或 false, 暂不支持交叉设置。

名称 描述
reliable
  • true:接收方会在 5 秒内收到发送方所发送的数据,否则会收到 onStreamMessageError 回调获得相应报错信息。
  • false:接收方不保证收到,就算数据丢失也不会报错。
ordered
  • true:接收方 5 秒内会按照发送方发送的顺序收到数据包。
  • false:接收方不保证按照发送方发送的顺序收到数据包。
返回值
  • < 0: 创建数据流失败的错误码 [4]
  • > 0: 数据流 ID

脚注

[4]返回的错误码是负数,对应错误代码和警告代码里的正整数。例如返回的错误码为-2,则对应错误代码和警告代码里的 2: ERR_INVALID_ARGUMENT 。

发送数据流 (sendStreamMessage)

public abstract int sendStreamMessage(int streamId, byte[] message);

该方法发送数据流消息到频道内所有用户。频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。 API 须对数据通道的传送速率进行控制: 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。

名称 描述
streamId 数据流 ID,createDataStream() 的返回值。
message 待发送的数据
返回值
  • 0: 发送成功
  • < 0: 发送失败,返回错误码:
    • ERR_SIZE_TOO_LARGE (114)
    • ERR_TOO_OFTEN (12)
    • ERR_BITRATE_LIMIT (115)
    • ERR_INVALID_ARGUMENT (2)

网络与设备监测

开始语音通话测试 (startEchoTest)

public abstract int startEchoTest();

该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。 在测试过程中,用户先说一段话,在 10 秒后,声音会回放出来。如果 10 秒后用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。

Note

  • 调用 startEchoTest 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,或者调用 joinChannel() 进行通话。
  • 直播模式下,只有主播用户才能调用。如果用户由通信模式切换到直播模式,请务必调用 setClientRole() 方法将用户角色设置为主播后再调用该方法。
名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败
  • ERR_REFUSED (-5):无法启动测试,可能没有成功初始化

停止语音通话测试 (stopEchoTest)

public abstract int stopEchoTest();

该方法停止语音通话测试。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败
  • ERR_REFUSED (-5):不能启动测试,可能语音通话测试没有成功启动

启动网络测试 (enableLastmileTest)

public abstract int enableLastmileTest();

该方法启用网络连接质量测试,用于检测用户网络接入质量。默认该功能为关闭状态。该方法主要用于以下场景:

用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。启用该方法会消耗一定的网络流量,影响通话质量。在收到 onLastmileQuality 回调后须调用 disableLastmileTest() 停止测试,再加入频道。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

禁用网络测试 (disableLastmileTest)

public abstract int disableLastmileTest();

该方法禁用网络测试。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

用户反馈

获取通话 ID (getCallId)

public abstract String getCallId();

获取当前的通话 ID。

客户端在每次 joinChannel() 后会生成一个对应的 CallId,标识该客户端的此次通话。有些方法如rate, complain需要在通话结束后调用,向SDK提交反馈,这些方法必须指定CallId参数。使用这些反馈方法,需要在通话过程中调用getCallId方法获取CallId,在通话结束后在反馈方法中作为参数传入。

名称 描述
返回值 通话 ID

给通话评分 (rate)

public abstract int rate(String callId,
                         int rating,
                         String description);

该方法能够让用户为通话评分,一般在通话结束后调用。

名称 描述
callId 通话 getCallId 函数获取的通话 ID
rating 给通话的评分,最低 1 分,最高 10 分
description (非必选项) 给通话的描述,可选,长度应小于 800 字节
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败
  • ERR_INVALID_ARGUMENT(-2): 传入的参数无效,例如 callId 无效
  • ERR_NOT_READY(-3):SDK 不在正确的状态,可能是因为没有成功初始化

投诉通话质量 (complain)

public abstract int complain(String callId,
                             String description);

该方法让用户就通话质量进行投诉。一般在通话结束后调用。

名称 描述
callId 通话 getCallId 函数获取的通话 ID
description (非必选项) 给通话的描述,可选,长度应小于 800 字节
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败
  • ERR_INVALID_ARGUMENT(-2): 传入的参数无效,例如 callId 无效
  • ERR_NOT_READY(-3):SDK 不在正确的状态,可能是因为没有成功初始化

其他

更新 Token (renewToken)

public abstract int renewToken(String token);

该方法用于更新 Token。如果启用了 Token 机制,过一段时间后使用的 Token 会失效。

当:

  • 发生 onTokenPrivilegeWillExpire 回调时,
  • onError 回调报告 ERR_TOKEN_EXPIRED(109) 时,
  • onRequestToken 回调报告 ERR_TOKEN_EXPIRED(109) 时,

应用程序应重新获取 Token,然后调用该 API 更新 Token,否则 SDK 无法和服务器建立连接。

名称 描述
token 指定要更新的 Token
返回值
  • 0:方法调用成功
  • < 0:方法调用不成功

设置日志文件 (setLogFile)

public abstract int setLogFile(String filePath);

设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。应用程序必须保证指定的目录存在而且可写。

名称 描述
filePath 日志文件的完整路径。该日志文件为 UTF-8 编码。
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

Note

Android 平台下日志文件的默认地址为:sdcard/<appname>/agorasdk.log。appname 为应用名称。

设置日志过滤器 (setLogFilter)

public abstract int setLogFilter(int filter);

设置 SDK 的输出日志过滤等级。不同的过滤等级可以单独或组合使用。

日志级别顺序依次为 OFFCRITICALERRORWARNINGINFODEBUG。选择一个级别,你就可以看到在该级别之前所有级别的日志信息。

例如,你选择 WARNING 级别,就可以看到在 CRITICALERRORWARNING 级别上的所有日志信息。

名称 描述
filter

设置过滤器等级:

  • LOG_FILTER_OFF = 0:不输出日志信息
  • LOG_FILTER_DEBUG = 0x80f:输出所有 API 日志信息
  • LOG_FILTER_INFO = 0x0f:输出 CRITICAL、ERROR、WARNING 和 INFO 级别的日志信息
  • LOG_FILTER_WARNING = 0x0e:输出 CRITICAL、ERROR 和 WARNING 级别的日志信息
  • LOG_FILTER_ERROR = 0x0c:输出 CRITICAL 和 ERROR 级别的日志信息
  • LOG_FILTER_CRITICAL = 0x08:输出 CRITICAL 级别的日志信息
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

销毁引擎实例 (destroy)

public static synchronized void destroy();

该方法释放 Agora SDK 使用的所有资源。有些应用程序只在用户需要时才进行语音通话,不需要时则将资源释放出来用于其他操作,该方法对这类程序可能比较有用。 只要调用了 destroy(), 用户将无法再使用和回调该 SDK 内的其它方法。如需再次使用通信功能,必须重新初始化 sharedEngineWithappId 来新建一个 AgoraRtcEngineKit 实例(instance)。

Note

  • 该方法需要在子线程中操作。
  • 该方法为同步调用。在等待 IRtcEngine 对象资源释放后再返回。APP 不应该在 SDK 产生的回调中调用该接口,否则由于 SDK 要等待回调返回才能回收相关的对象资源,会造成死锁。

查询 SDK 版本号 (getSdkVersion)

public static String getSdkVersion();

该方法返回 SDK 版本号字符串。

音效管理方法 (IAudioEffectManager)

获取音效音量 (getEffectsVolume)

public double getEffectsVolume();

该方法获取音效的音量,范围为 [0.0, 100.0]。

设置音效音量 (setEffectsVolume)

public int setEffectsVolume(double volume);

该方法设置音效的音量。

名称 描述
volume 取值范围为 [0.0, 100.0]。 100.0 为默认值
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

实时调整音效音量 (setVolumeOfEffect)

public int setVolumeOfEffect(int soundId, double volume);

该方法实时调整指定音效的音量。

名称 描述
soundId 指定音效的 ID。每个音效均有唯一的 ID
volume 取值范围为 [0.0, 100.0]。 100.0 为默认值
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

播放指定音效 (playEffect)

public int playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish);

该方法播放指定音效。

名称 描述
soundId 指定音效的 ID。每个音效均有唯一的 ID [5]
filepath 音效文件的绝对路径
loopCount

设置音效循环播放的次数:

  • 0:播放音效一次
  • 1:播放音效两次
  • -1:无限循环播放音效,直至调用 stopEffectstopAllEffects 后停止
pitch 设置音效的音调 取值范围为 [0.5, 2.0]。默认值为 1.0,表示不需要修改音调。取值越小,则音调越低
pan

设置是否改变本地听到的音效的空间位置。取值范围为 [-1.0, 1.0]:

  • 0.0:音效出现在正前方
  • -1.0:音效出现在左边
  • 1.0:音效出现在右边
gain 设置是否改变单个音效的音量。取值范围为 [0.0, 100.0]。默认值为 100.0。取值越小,则音效的音量越低
publish

设置是否将音效传到远端:

  • true:音效在本地播放的同时,会发布到 Agora 云上,因此远端用户也能听到该音效
  • false:音效不会发布到 Agora 云上,因此只能在本地听到该音效
返回值
  • 0:该方法调用成功
  • < 0:该方法调用不成功

脚注

[5]如果你已通过 preloadEffect 将音效加载至内存,确保这里设置的 soundIdpreloadEffect 设置的 soundId 相同。

Note

该接口在 v2.1.x 及之前的版本中如下所示,不推荐使用。

public int playEffect(int soundId, String filePath, boolean loop, double pitch, double pan, double gain);

停止播放指定音效 (stopEffect)

public int stopEffect(int soundId);

该方法停止播放指定音效。

名称 描述
soundId 指定音效的 ID。每个音效均有唯一的 ID
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

停止播放所有音效 (stopAllEffects)

public int stopAllEffects();

该方法停止播放所有音效。

预加载音效 (preloadEffect)

public int preloadEffect(int soundId, String filePath);

该方法将指定音效文件(压缩的语音文件)预加载至内存。

Note

为保证通信畅通,请注意预加载音效文件的大小,并在 joinChannel 前就使用该方法完成音效预加载。

名称 描述
soundId 指定音效的 ID。每个音效均有唯一的 ID
filePath 音效文件的绝对路径
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

释放音效 (unloadEffect)

public int unloadEffect(int soundId);

该方法将指定预加载的音效从内存里释放出来。

名称 描述
soundId 指定音效的 ID。每个音效均有唯一的 ID
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

暂停音效播放 (pauseEffect)

public int pauseEffect(int soundId);

该方法暂停播放指定音效。

名称 描述
soundId 指定音效的 ID。每个音效均有唯一的 ID
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

暂停所有音效播放 (pauseAllEffects)

public int pauseAllEffects();

该方法暂停播放所有音效。

名称 描述
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

恢复播放指定音效 (resumeEffect)

public int resumeEffect(int soundId);

该方法恢复播放指定音效。

名称 描述
soundId 指定音效的 ID。每个音效均有唯一的 ID
返回值
  • 0: 方法调用成功
  • <0: 方法调用失败

恢复播放所有音效 (resumeAllEffects)

public int resumeAllEffects();

该方法恢复播放所有音效。

推流方法 (PublisherConfiguration)

在你调用本章 API 之前:

设置直播转码 (setLiveTranscoding)

public abstract int setLiveTranscoding(LiveTranscoding transcoding);

该方法用于 CDN 推流的视图布局及音频设置等。

参数 描述
transcoding 直播转码的相关配置。

LiveTranscoding 定义

public int width;
public int height;
public int videoBitrate;
public int videoFramerate;
public boolean lowLatency;
public int videoGop;
public AgoraImage watermark;
public AgoraImage backgroundImage;
public AudioSampleRateType audioSampleRate;
public int audioBitrate;
public int audioChannels;
public VideoCodecProfileType videoCodecProfile;
public String userConfigExtraInfo;
public String metadata;
public int backgroundColor;
public static class TranscodingUser {
    public int uid;
    public int x;
    public int y;
    public int width;
    public int height;
    public int zOrder;
    public float alpha;
    public int audioChannel;

    public TranscodingUser() {
        alpha = 1;
    }
}

public LiveTranscoding() {
    width = 360;
    height = 640;
    videoBitrate = 400;
    videoCodecProfile = VideoCodecProfileType.HIGH;
    videoGop = 30;
    videoFramerate = 15;
    watermark = new AgoraImage();
    backgroundImage = new AgoraImage();

    lowLatency = false;
    audioSampleRate = AudioSampleRateType.TYPE_44100;
    audioBitrate = 48;
    audioChannels = 1;
    backgroundColor = 0xFF000000;
    userConfigExtraInfo = null;
    metadata = null;
}
参数 描述
width 用于旁路直播的输出视频的总宽度。360 为默认值
height 用于旁路直播的输出视频的总高度。640 为默认值
videoBitrate 用于旁路直播的输出视频的码率。单位为 Kbps。400 Kbps 为默认值
videoCodecProfile

用于旁路直播的输出视频的编解码类型:

  • VIDEO_CODEC_PROFILE_TYPE_BASELINE = 66, 最低视频编码率
  • VIDEO_CODEC_PROFILE_TYPE_MAIN = 77
  • VIDEO_CODEC_PROFILE_TYPE_HIGH = 100, 默认值,最高视频编码率
videoGop 用于旁路直播的输出视频的 GOP。单位为帧
videoFramerate 用于旁路直播的输出视频的帧率。单位为帧每秒。15 fps 为默认值。
watermark 用于旁路直播的输出视频上水印图片的 Url 地址。添加后所有旁路直播的观众都可以看到水印。水印图片的定义详见 AgoraImage 定义 中的描述
backgroundImage 用于旁路直播的输出视频上背景图片的 Url 地址。添加后所有旁路直播的观众都可以看到背景图片。背景图片的定义详见 AgoraImage 定义 中的描述
lowLatency

低延时模式

  • true: 低延时,不保证画质。
  • false: (默认值)高延时,保证画质。
audioSampleRate

用于旁路直播的输出音频的采样率:

  • AUDIO_SAMPLE_RATE_TYPE_32000
  • AUDIO_SAMPLE_RATE_TYPE_44100 (默认值)
  • AUDIO_SAMPLE_RATE_TYPE_48000
audioBitrate 用于旁路直播的输出音频的码率。单位为 Kbps,默认值为 48,最大值为 128。
audioChannels

用于旁路直播的输出音频的声道数,默认值为 1。取值范围为 [1,5] 中的整型,建议取 1 或 2, 3、4、5需要特殊播放器支持:

  • 1:单声道
  • 2:双声道
  • 3:三声道
  • 4:四声道
  • 5:五声道
backgroundColor 用于设置旁路直播的输出视频的背景色。backgroundColor 作为 sRGB color space,定义为 int color = (A & 0xff) << 24 | (R & 0xff) << 16 | (G & 0xff) << 8 | (B & 0xff);用户可以直接用 ARGB ColorInt 给 backgroundColor 赋值
userConfigExtraInfo 推流输出的视频中嵌入 SEI 中的信息

添加推流地址 (addPublishStreamUrl)

public abstract int addPublishStreamUrl(String url, boolean transcodingEnabled);

该方法用于CDN推流,用于添加推流地址。

参数 描述
url 推流地址
transcodingEnabled

是否转码

  • true: 转码
  • false: 不转码

Note

  • 请确保在成功加入房间后才能调用该接口。
  • 该方法每次只能增加一路 CDN 推流地址。若需推送多路流,则需多次调用该方法。
  • url 不支持中文等特殊字符。

删除推流地址 (removePublishStreamUrl)

public abstract int removePublishStreamUrl(String url);

该方法用于 CDN 推流,用于删除推流地址。

参数 描述
url 推流地址

Note

  • 该方法每次只能删除一路 CDN 推流地址。若需删除多路流,则需多次调用该方法。
  • url 不支持中文等特殊字符。

添加一个用户 (addUser)

public int addUser(TranscodingUser user);

该方法用于添加一个用户到已有用户中。

Parameter Description
user 参与合图的用户,定义详见 transcodingUser 定义 中的描述。

transcodingUser 定义

public static class TranscodingUser {
    public int uid;
    public int x;
    public int y;
    public int width;
    public int height;
    public int zOrder;
    public float alpha;
    public int audioChannel;

    public TranscodingUser() {
        alpha = 1;
    }
}
参数 描述
uid CDN 主播的 user ID
x 屏幕里该区域的横坐标绝对值。取值范围为转码配置参数定义中设置的 [0, width]
y 屏幕里该区域的纵坐标绝对值。取值范围为转码配置参数定义中设置的 [0, height]
width 视频帧宽度
height 视频帧高度
zOrder 视频帧图层编号。取值范围为 [1,100] 中的整型。1 表示该区域图像位于最下层,而 100 表示该区域图像位于最上层
alpha 视频帧的透明度。取值范围为 [0,1] 。0 表示该区域图像完全透明,而1表示该区域图像完全不透明。默认值为 1
audioChannel

音频所在声道。取值范围为 [0, 5],默认值为 0:

  • 0: (推荐) 默认混音设置,最多支持双声道,与主播端上行音频相关
  • 1: 对应主播的音频,推流中位于 FL 声道。如果主播上行为双声道,则仅取左声道用于推流
  • 2: 对应主播的音频,推流中位于 FC 声道。如果主播上行为双声道,则仅取左声道用于推流
  • 3: 对应主播的音频,推流中位于 FR 声道。如果主播上行为双声道,则仅取左声道用于推流
  • 4: 对应主播的音频,推流中位于 BL 声道。如果主播上行为双声道,则仅取左声道用于推流
  • 5: 对应主播的音频,推流中位于 BR 声道。如果主播上行为双声道,则仅取左声道用于推流

选项不为 0 时,需要特殊的播放器支持

批量获取用户 (getUsers)

public final ArrayList<TranscodingUser> getUsers();

该方法用于获取参与合图的全部用户。该方法返回的用户列表为只读,开发者不应该修改该数据。

Parameter Description
users 所有参与合图的用户,定义详见 transcodingUser 定义 中的描述。

批量设置用户 (setUsers)

public void setUsers(ArrayList<TranscodingUser> users);

该方法用于设置参与合图的全部用户。该方法会使用新的 User 数据替换原有的数据。

Parameter Description
users 所有参与合图的用户,定义详见 transcodingUser 定义 中的描述。

批量设置用户 (setUsers)

public void setUsers(Map<Integer, TranscodingUser> users);

该方法用于设置参与合图的全部用户。该方法会使用新的 User 数据替换原有的数据。

Parameter Description
users 所有参与合图的用户,定义详见 transcodingUser 定义 中的描述。

移除转码合图用户 (removeUser)

public int removeUser(int uid);

该方法移除参与合图的用户。

Parameter Description
uid 待删除的用户 UID

获取转码合图用户人数 (getUserCount)

public int getUserCount();

该方法获取参数合图的用户人数。

获取背景颜色 (getBackgroundColor)

public int getBackgroundColor;

该方法获取合图的背景颜色。

设置背景色 (setBackgroundColor)

public void setBackgroundColor(int color);

该方法用于设置背景色。

参数 描述
color 背景色

设置背景色 RGB (setBackgroundColor)

public void setBackgroundColor(int red, int green, int blue);

该方法用于设置背景色。

参数 描述
red
green 绿
blue

获取背景红色分量 (getRed)

Note

该方法已弃用。Agora 推荐使用 获取背景颜色 (getBackgroundColor) 方法获取背景颜色。

public int getRed();

该方法用于获取背景色中的红色主色信息。

获取背景绿色分量 (getGreen)

Note

该方法已弃用。Agora 推荐使用 获取背景颜色 (getBackgroundColor) 方法获取背景颜色。

public int getGreen();

该方法用于获取背景色中的绿色主色信息。

获取背景蓝色分量 (getBlue)

Note

该方法已弃用。Agora 推荐使用 获取背景颜色 (getBackgroundColor) 方法获取背景颜色。

public int getBlue();

该方法用于获取背景色中的蓝色主色信息。

设置背景红色分量 (setRed)

Note

该方法已弃用。Agora 推荐使用 设置背景色 RGB (setBackgroundColor) 方法设置背景颜色。

public void setRed(int red);

该方法用于设置背景的红色主色而保持其他两个主色不变。

设置背景绿色分量 (setGreen)

Note

该方法已弃用。Agora 推荐使用 设置背景色 RGB (setBackgroundColor) 方法设置背景颜色。

public void setGreen(int green);

该方法用于设置背景的绿色主色而保持其他两个主色不变。

设置背景蓝色分量 (setBlue)

Note

该方法已弃用。Agora 推荐使用 设置背景色 RGB (setBackgroundColor) 方法设置背景颜色。

public void setBlue(int blue);

该方法用于设置背景的蓝色主色而保持其他两个主色不变。

配置旁路直播推流 (configPublisher)

Note

该方法已弃用。你仍然可以使用该方法推流到 CDN。但是声网推荐你使用以下方法推流:

  • addPublishStreamUrl()
  • removePublishStreamUrl()
  • setLiveTranscoding()

声网将在这三个接口的基础上对 CDN 推流做更多优化。

public abstract int configPublisher(PublisherConfiguration config);

该方法用于在加入频道前为引擎创建一份推流设置。我们提供一个 Builder 类方便配置旁路直播推流,例如:

PublisherConfiguration config = New PublisherConfiguration.Builder()
  .owner(true)
  .size(360, 640)
  .framerate(15)
  .bitrate(500)
  .defaultLayout(1)
  .lifecycle(STREAM_LIFE_CYCLE_BIND2CHANNEL)
  .rawStreamUrl(rtmpUrl)
  .publisherUrl(rtmpUrl)
  .build();

mRtcEngine.configPublisher(config);

Note

  • 关于如何调用 Builder 类里的各方法,配置推流设置,详见 Builder 类
  • 请确保设置的分辨率、码率和帧率与主播上行设置一致,以免视频质量下降。

Builder 类

Note

该类接口已废弃。如果需要对推流设置,Agora 推荐直接在 设置直播转码 (setLiveTranscoding) 方法中实现。

设置 RTMP 流主人 (owner)

public Builder owner(boolean isRoomOwner)

在 Builder 类,该方法决定是否将当前主播设为该 RTMP 流的主人。

名称 描述
isRoomOwner
  • true: 将当前主播设为指定 RTMP 流的主人(默认) 。 当设置为 true 时,推流配置才能生效
  • false: 不将当前主播设为指定 RTMP 流的主人,推流配置无法生效

设置流分辨率 (size)

public Builder size(int width, int height)

在 Builder 类里,该方法设置旁路直播的分辨率。

名称 描述
width 旁路直播输出码流的宽度。默认值为 360
height 旁路直播输出码流的高度。默认值为 640

设置流帧率 (frameRate)

public Builder frameRate(int framerate)

设置旁路直播的输出码率帧率。默认值为 15 fps

名称 描述
framerate 旁路直播输出码流的帧率。默认值为 15 fps

设置流码率 (Kbps)

public Builder biteRate(int bitrate)

在 Builder 类,设置旁路直播输出码流的码率。默认值为 500 Kbps。

名称 描述
bitrate 设置旁路直播输出码流的码率。默认设置为 500 Kbps

设置默认合图布局 (defaultLayout)

public Builder defaultLayout(int layoutStyle)

在 Builder 类,如果你不使用 自由调整布局 ,调用该方法设置 自由调整布局

名称 描述
layoutStyle
  • 0: 横向平铺视窗
  • 1: 层叠视窗
  • 2: 纵向平铺视窗

设置合图推流地址 (publishUrl)

public Builder publishUrl(String url)

在 Builder 类,该方法设置合图推流地址。

名称 描述
url 配置推流合图的推流地址,默认为 null

设置单流地址 (rawStreamUrl)

public Builder rawStreamUrl(String url)

在 Builder 类里,该方法用于设置不需要做合图的原始流的推流地址。

名称 描述
url 不需要做合图的原始流的推流地址,默认为 null

添加其他信息 (extraInfo)

public Builder extraInfo(String optionalInfo)
名称 描述
optionalInfo 保留字段,默认值为 null

导入外部视频源

导入外部视频流 Url (addInjectStreamUrl)

public int addInjectStreamUrl(String url, LiveInjectStreamConfig config)

该方法将正在播放的音视频作为音视频源导入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。

如果导入成功,该音视频流会出现在频道中,其 uid 为 666。

参数 描述
url 添加到直播中的视频流 url 地址, 支持 RTMP, HLS, FLV 协议传输
config 所添加的视频流属性定义,详见下表

LiveInjectStreamConfig 属性定义如下:

public int width;
public int height;
public int videoGop;
public int videoFramerate;
public int videoBitrate;
public AudioSampleRateType audioSampleRate;
public int audioBitrate;
public int audioChannels;

public LiveInjectStreamConfig() {
    width = 0;
    height = 0;
    videoGop = 30;
    videoFramerate = 15;
    videoBitrate = 400;
    audioSampleRate = AudioSampleRateType.TYPE_44100;
    audioBitrate = 48;
    audioChannels = 1;
}
名称 描述
width 添加进入直播的外部视频源宽度。默认值为 0,即保留视频源原始宽度
height 添加进入直播的外部视频源高度。默认值为 0,即保留视频源原始高度
videoGop 添加进入直播的外部视频源 GOP。默认值为 30
videoFramerate 添加进入直播的外部视频源帧率。默认值为 15 fps
videoBitrate 添加进入直播的外部视频源码率。默认设置为 400 Kbps
audioSampleRate 添加进入直播的外部音频采样率。默认值为 44100
audioBitrate 添加进入直播的外部音频码率。默认值为 48
audioChannels 添加进入直播的外部音频频道。默认值为 1

删除外部视频流 Url (removeInjectStreamUrl)

public int removeInjectStreamUrl(String url)

该方法删除已导入的外部视频流 url。

名称 描述
url 已导入、待删除的外部视频流 url 地址

主回调事件 (IRtcEngineEventHandler)

软件包: io.agora.rtc

IRtcEngineEventHandler 接口类用于SDK向应用程序发送回调事件通知,应用程序通过继承该接口类的方法获取 SDK 的事件通知。

接口类的所有方法都有缺省(空)实现,应用程序可以根据需要只继承关心的事件。在回调方法中,应用程序不应该做耗时或者调用可能会引起阻塞的 API(如 SendMessage),否则可能影响 SDK 的运行。

加入频道回调 (onJoinChannelSuccess)

public void onJoinChannelSuccess(String channel,
                                 int uid,
                                 int elapsed);

表示客户端已经登入服务器,且分配了频道 ID 和用户 ID。频道 ID 的分配是根据 join() API 中指定的频道名称。如果调用 join() 时并未指定用户 ID,服务器就会分配一个。

名称 描述
channel 频道名
uid 用户 ID 。如果 joinChannel() 中指定了 uid,则此处返回该 ID;否则使用 Agora 服务器自动分配的 ID
elapsed joinChannel() 开始到该事件产生的延迟(毫秒)

重新加入频道回调 (onRejoinChannelSuccess)

public void onRejoinChannelSuccess(String channel,
                                   int uid,
                                   int elapsed);

有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。

名称 描述
channel 频道名
uid 用户 ID 。如果 joinChannel() 中指定了 uid,则此处返回该 ID;否则使用 Agora 服务器自动分配的 ID
elapsed joinChannel() 开始到该事件产生的延迟(毫秒)

发生警告回调 (onWarning)

public void onWarning(int warn);

该回调方法表示 SDK 运行时出现了(网络或媒体相关的)警告。通常情况下,SDK 上报的警告信息应用程序可以忽略,SDK 会自动恢复。 例如和服务器失去连接时,SDK 可能会上报 ERR_OPEN_CHANNEL_TIMEOUT 警告,同时自动尝试重连。

名称 描述
warn 警告代码,详见 错误代码和警告代码

Note

部分 Warning Code 在上报给客户之前,会经过映射,映射后的 Warning Code 与原来的 Warning Code 意义相同,但错误类别更清晰,方便客户判断。详细的错误代码及映射表,见 错误代码及映射

发生错误回调 (onError)

public void onError(int err);

表示 SDK 运行时出现了(网络或媒体相关的)错误。 通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 APP 干预或提示用户。 例如启动通话失败时,SDK 会上报 ERR_START_CALL 错误。APP 可以提示用户启动通话失败,并调用 leaveChannel() 退出频道。

名称 描述
err 错误代码,详见 错误代码和警告代码

Note

部分 Error Code 在上报给客户之前,会经过映射,映射后的 Error Code 与原来的 Error Code 意义相同,但错误类别更清晰,方便客户判断。详细的错误代码及映射表,见 错误代码及映射

API 已执行回调 (onApiCallExecuted)

public void onApiCallExecuted(int error, String api, String result)

当 SDK 执行相应的 API 后,会触发该回调。

名称 描述
error 错误码。如果方法调用失败,会返回错误码;如果返回 0,则表示方法调用成功
api SDK 所调用的 API
result SDK 调用 API 的调用结果

离开频道回调 (onLeaveChannel)

public void onLeaveChannel(RtcStats stats);

应用程序调用 leaveChannel() 方法时,SDK 提示应用程序离开频道成功。在该回调方法中,应用程序可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。

RtcStats 类定义

public static class RtcStats {
    public int totalDuration; // in seconds
    public int txBytes;
    public int rxBytes;
    public int txKBitRate;
    public int rxKBitRate;
    public int txAudioKBitRate;
    public int rxAudioKBitRate;
    public int txVideoKBitRate;
    public int rxVideoKBitRate;
    public int lastmileDelay;
    public int users;
    public double cpuTotalUsage;
    public double cpuAppUsage;
}
名称 描述
stats

通话相关的统计信息:

  • totalDuration:通话时长,单位为秒,累计值
  • txBytes:发送字节数 (bytes),累计值
  • rxBytes:接收字节数 (bytes),累计值
  • txKBitRate:发送码率 (kbps),瞬时值
  • rxKBitRate:接收码率 (kbps),瞬时值
  • txAudioKBitRate:音频发送码率 (kbps),瞬时值
  • rxAudioKBitRate:音频接收码率 (kbps),瞬时值
  • txVideoKBitRate:视频发送码率 (kbps),瞬时值
  • rxVideoKBitRate:视频接收码率 (kbps),瞬时值
  • lastmileDelay:客户端到 vos 服务器的延迟(毫秒)
  • users:用户离开频道时频道内的瞬时人数
  • cpuTotalUsage:当前系统的 CPU 使用率 (%)
  • cpuAppUsage:当前应用程序的 CPU 使用率 (%)

语音路由已变更回调 (onAudioRouteChanged)

public void onAudioRouteChanged(int routing);

当调用 setEnableSpeakerphone 成功时, SDK 会通过该回调通知 App 语音路由状态已发生变化。该回调返回当前的语音路由已切换至听筒,外放(扬声器),耳机或蓝牙。 其中 routing 定义如下:

public static final int AUDIO_ROUTE_DEFAULT = -1;
public static final int AUDIO_ROUTE_HEADSET = 0;
public static final int AUDIO_ROUTE_EARPIECE = 1;
public static final int AUDIO_ROUTE_HEADSETNOMIC = 2;
public static final int AUDIO_ROUTE_SPEAKERPHONE = 3;
public static final int AUDIO_ROUTE_LOUDSPEAKER = 4;
public static final int AUDIO_ROUTE_HEADSETBLUETOOTH = 5;
routing

设置语音路由:

  • -1:使用默认的语音路由
  • 0:使用耳机为语音路由
  • 1:使用听筒为语音路由
  • 2:使用不带麦的耳机为语音路由
  • 3:使用手机的扬声器为语音路由
  • 4:使用外接的扬声器为语音路由
  • 5:使用蓝牙耳机为语音路由

远端音频传输状态回调 (onRemoteAudioTransportStats)

public void onRemoteAudioTransportStats(int uid,
                                        int delay,
                                        int lost,
                                        int rxKBitRate);

在通话中,当收到远端用户发送的音频数据包后,会周期性地发生该回调上报。回调频率约为 2 秒 1 次。

名称 描述
uid 发送音频数据包的远端用户 UID
delay 远端到本地客户端的延迟,单位为毫秒
lost 丢包率
rxKBitRate 音频包的接收码率(Kbps)

远端视频传输状态回调 (onRemoteVideoTransportStats)

public void onRemoteVideoTransportStats(int uid,
                                        int delay,
                                        int lost,
                                        int rxKBitRate);

在通话中,当收到远端用户发送的视频数据包后,会周期性地发生该回调上报。回调频率约为 2 秒 1 次。

名称 描述
uid 发送视频数据包的远端用户 UID
delay 远端到本地客户端的延迟,单位为毫秒
lost 丢包率
rxKBitRate 视频包的接收码率(Kbps)

音频质量回调 (onAudioQuality)

public void onAudioQuality(int uid,
                           int quality,
                           short delay,
                           short lost);

在通话中,该回调方法每两秒触发一次,报告当前通话的音频质量(嘴到耳)。默认启用。

名称 描述
uid 用户 ID
quality

语音质量:

  • QUALITY_UNKNOWN(0):网络质量未知
  • QUALITY_EXCELLENT(1):网络质量极好
  • QUALITY_GOOD(2):用户主观感觉和 excellent 差不多,但码率可能略低于 excellent
  • QUALITY_POOR(3):用户主观感受有瑕疵但不影响沟通
  • QUALITY_BAD(4):勉强能沟通但不顺畅
  • QUALITY_VBAD(5):网络质量非常差,基本不能沟通
  • QUALITY_DOWN(6):完全无法沟通
delay 延迟,单位为毫秒
lost 丢包率,单位为百分比

说话声音音量提示回调 (onAudioVolumeIndication)

public void onAudioVolumeIndication(AudioVolumeInfo[] speakers, int totalVolume);

该回调提示频道内谁在说话以及说话者的音量。默认禁用。可以通过 启用说话者音量提示 (enableAudioVolumeIndication) 方法开启;开启后,无论频道内是否有人说话,都会按方法中设置的时间间隔返回提示音量。

名称 描述
speakers

说话者(数组)。每个 speaker() 包括:

  • uid:说话者的用户 ID。如果返回的 uid 为 0,则默认为本地用户
  • volume:说话者的音量(0~255)
totalVolume (混音后的)总音量(0~255)

在返回的 speakers 数组中:

  • 如果返回的 uid 为 0,即当频道内的说话者为本地用户时,说话者的音量 volumetotalVolume,即频道内的总音量。
  • 如果返回的 uid 不是 0,且 volume 为 0,则默认该 uid 对应的远端用户没有说话。
  • 如果有 uid 出现在上次返回的数组中,但不在本次返回的数组中,则默认该 uid 对应的远端用户没有说话。

主播加入频道回调 (onUserJoined)

public void onUserJoined(int uid, int elapsed);

该回调提示有主播加入了频道,并返回该主播的 ID。如果在加入之前,已经有主播在频道中了,新加入的用户也会收到已有主播加入频道的回调。Agora 建议连麦主播不超过 17 人。

Note

直播场景下:

  • 主播间能相互收到新主播加入频道的回调,并能获得该主播的 uid
  • 观众也能收到新主播加入频道的回调,并能获得该主播的 uid
  • 当 Web 端加入直播频道时,只要 Web 端有推流,SDK 会默认该 Web 端为主播,并触发该回调
名称 描述
uid 主播 ID
elapsed 从调用 joinChannel() 到触发该回调的延迟(毫秒)

主播离开频道回调 (onUserOffline)

public void onUserOffline(int uid, int reason);

提示有主播离开了频道(或掉线)。SDK 判断用户离开频道(或掉线)的依据是超时:在一定时间内(15 秒)没有收到对方的任何数据包,判定为对方掉线。在网络较差的情况下,可能会有误报。建议可靠的掉线检测应该由信令来做。

名称 描述
uid 主播 ID
reason

离线原因:

  • USER_OFFLINE_QUIT(0): 用户主动离开
  • USER_OFFLINE_DROPPED(1): 因过长时间收不到对方数据包,超时掉线。注意:由于 SDK 使用的是不可靠通道,也有可能对方主动离开本方没收到对方离开消息而误判为超时掉线
  • USER_OFFLINE_BECOME_AUDIENCE(2): 用户身份从主播切换为观众时触发

麦克风状态改变回调 (onMicrophoneEnabled)

public void onMicrophoneEnabled(boolean enabled);

该回调向应用程序报告麦克风的状态已改变。

名称 描述
enabled
  • true:麦克风已启用
  • false:麦克风已禁用

用户静音回调 (onUserMuteAudio)

public void onUserMuteAudio(int uid, boolean muted);

提示有其他用户将他的音频流静音/取消静音。

名称 描述
uid 用户 ID
muted
  • true: 该用户已静音音频
  • false: 该用户已取消音频静音

Rtc Engine统计数据回调 (onRtcStats)

public void onRtcStats(RtcStats stats);

该回调定期上报 Rtc Engine 的运行时的状态,每两秒触发一次。

名称 描述
stats RtcEngine 数据,详见 离开频道回调 (onLeaveChannel) 中的描述

网络质量报告回调 (onLastmileQuality)

public void onLastmileQuality(int quality);

报告本地用户的网络质量。当你调用 enableLastmileTest 之后,该回调函数每 2 秒触发一次。

名称 描述
quality

网络质量:

  • QUALITY_UNKNOWN(0):网络质量未知
  • QUALITY_EXCELLENT(1):网络质量极好
  • QUALITY_GOOD(2):用户主观感觉和 excellent 差不多,但码率可能略低于 excellent
  • QUALITY_POOR(3):用户主观感受有瑕疵但不影响沟通
  • QUALITY_BAD(4):勉强能沟通但不顺畅
  • QUALITY_VBAD(5):网络质量非常差,基本不能沟通
  • QUALITY_DOWN(6):完全无法沟通

频道内网络质量报告回调 (onNetworkQuality)

public void onNetworkQuality(int uid, int txQuality, int rxQuality);

该回调每 2 秒触发,向 APP 报告频道内所有用户当前的上行、下行网络质量。

名称 描述
uid 用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。当 uid 为 0 时,返回的是本地用户的网络质量
txQuality

该用户的上行网络质量:

  • QUALITY_UNKNOWN(0):网络质量未知
  • QUALITY_EXCELLENT(1):网络质量极好
  • QUALITY_GOOD(2):用户主观感觉和 excellent 差不多,但码率可能略低于 excellent
  • QUALITY_POOR(3):用户主观感受有瑕疵但不影响沟通
  • QUALITY_BAD(4):勉强能沟通但不顺畅
  • QUALITY_VBAD(5):网络质量非常差,基本不能沟通
  • QUALITY_DOWN(6):完全无法沟通
rxQuality

该用户的下行网络质量:

  • QUALITY_UNKNOWN(0):网络质量未知
  • QUALITY_EXCELLENT(1):网络质量极好
  • QUALITY_GOOD(2):用户主观感觉和 excellent 差不多,但码率可能略低于 excellent
  • QUALITY_POOR(3):用户主观感受有瑕疵但不影响沟通
  • QUALITY_BAD(4):勉强能沟通但不顺畅
  • QUALITY_VBAD(5):网络质量非常差,基本不能沟通
  • QUALITY_DOWN(6):完全无法沟通

远端视频流状态发生改变回调 (onRemoteVideoStateChanged)

public void onRemoteVideoStateChanged(int uid, int state);

该回调方法表示远端的视频流状态发生了改变。

名称 描述
uid 发生视频流状态改变的远端用户的 ID
state

远端视频流状态:

  • 1:远端视频正常
  • 2:远端视频卡住

连接中断回调 (onConnectionInterrupted)

public void onConnectionInterrupted();

该回调方法表示 SDK 和服务器失去了网络连接。

与 onConnectionLost 回调的区别是: onConnectionInterrupted 回调在 SDK 刚失去和服务器连接时触发,onConnectionLost 在失去连接且尝试自动重连失败后才触发。 失去连接后,除非 APP 主动调用 leaveChannel(),不然 SDK 会一直自动重连。

连接丢失回调 (onConnectionLost)

public void onConnectionLost();

在 SDK 和服务器失去了网络连接后,会触发 onConnectionInterrupted 回调,并自动重连。如果重连一段时间(默认 10 秒)后仍未连上,会触发该回调。 如果 SDK 在调用 joinChannel 后 10 秒内没有成功加入频道,也会触发该回调。 该回调触发后,SDK 仍然会尝试重连,重连成功后会触发 onRejoinChannelSuccess 回调。

连接已被禁止回调 (onConnectionBanned)

public void onConnectionBanned();

当你被服务端禁掉连接的权限时,会触发该回调。

本地视频显示回调 (onFirstLocalVideoFrame)

public void onFirstLocalVideoFrame(int width, int height, int elapsed);

提示第一帧本地视频画面已经显示在屏幕上。

名称 描述
width 视频流宽(像素)
height 视频流高(像素)
elapsed 加入频道开始到该回调触发的延迟(毫秒)

收到远端音频回调 (onFirstRemoteAudioFrame)

public void onFirstRemoteAudioFrame(int uid, int elapsed)

当接收到远端音频第一帧时,触发此回调。

名称 描述
uid 用户 UID,表示收到的是哪个用户的音频流
elapsed 加入频道开始到该回调触发的延迟(毫秒)

远端视频显示回调 (onFirstRemoteVideoFrame)

public void onFirstRemoteVideoFrame(int uid, int width, int height, int elapsed);

第一帧远程视频显示在视图上时,触发此调用。应用程序可在此调用中获知出图时间(elapsed)。

名称 描述
uid 用户 ID,指定是哪个用户的视频流
width 视频流宽(像素)
height 视频流高(像素)
elapsed 加入频道开始到该回调触发的延迟(毫秒)

远端视频接收解码回调 (onFirstRemoteVideoDecoded)

public void onFirstRemoteVideoDecoded(int uid, int width, int height, int elapsed);

收到第一帧远程视频流并解码成功时,触发此调用。应用程序可以在此回调中设置该用户的视图。

名称 描述
uid 用户 ID,指定是哪个用户的视频流
width 视频流宽(像素)
height 视频流高(像素)
elapsed 加入频道开始到该回调触发的延迟(毫秒)

其他用户已停发/已重发视频流回调 (onUserMuteVideo)

public void onUserMuteVideo(int uid, boolean muted);

提示有其他用户暂停/恢复了视频流的发送。

名称 描述
uid 用户 ID,提示是哪个用户的视频流
muted
  • true:该用户已暂停发送视频流
  • false:该用户已恢复发送视频流

其他用户启用/关闭视频 (onUserEnableVideo)

public void onUserEnableVideo(int uid, boolean enabled);

提示有其他用户启用/关闭了视频功能。关闭视频功能是指该用户只能进行语音通话,不能显示、发送自己的视频,也不能接收、显示别人的视频。

名称 描述
uid 用户 ID,提示是哪个用户的视频流
enabled
  • true:该用户已启用视频功能。启用后,该用户可以进行视频通话或直播
  • false:该用户已关闭视频功能。关闭后,该用户只能进行语音通话或直播,不能显示、发送自己的视频,也不能接收、显示别人的视频

其他用户启用/关闭本地视频 (onUserEnableLocalVideo)

public void onUserEnableLocalVideo(int uid, boolean enabled)

提示有其他用户启用/关闭了本地视频功能。

名称 描述
uid 用户 ID,提示是哪个用户的视频流
enabled
  • true:该用户已启用本地视频功能。启用后,其他用户可以接收到该用户的视频流
  • false:该用户已关闭视频功能。关闭后,该用户仍然可以接收其他用户的视频流,但其他用户接收不到该用户的视频流

本地发布的媒体流已回退为音频流 (onLocalPublishFallbackToAudioOnly)

public void onLocalPublishFallbackToAudioOnly(boolean isFallbackOrRecover);

如果你调用了 设置本地推流回退选项 (setLocalPublishFallbackOption) 接口并将 option 设置为 2,当上行网络环境不理想、本地发布的媒体流回退为音频流时,或当上行网络改善、媒体流恢复为音视频流时,会触发该回调。 如果本地推流已回退为音频流,远端的 App 上会收到 onUserMuteVideo 的回调事件。

名称 描述
isFallbackOrRecover

本地推流已回退或恢复:

  • true: 由于网络环境不理想,本地发布的媒体流已回退为音频流
  • false: 由于网络环境改善,发布的音频流已恢复为音视频流

远端订阅流已回退为音频流 (onRemoteSubscribeFallbackToAudioOnly)

public void onRemoteSubscribeFallbackToAudioOnly(int uid, boolean isFallbackOrRecove);

如果你调用了 设置远端订阅流回退选项 (setRemoteSubscribeFallbackOption) 接口并将 option 设置为 2,当下行网络环境不理想、仅接收远端音频流时,或当下行网络改善、恢复订阅音视频流时,会触发该回调。

Note

远端订阅流因弱网环境不能同时满足音视频而回退为小流时,你可以使用 remoteVideoStats 方法来监控远端视频大小流的切换。

名称 描述
uid 远端用户的 UID
isFallbackOrRecover

远端订阅流已回退或恢复:

  • true: 由于网络环境不理想,远端订阅流已回退为音频流
  • false: 由于网络环境改善,订阅的音频流已恢复为音视频流

导入外部视频流状态回调 (onStreamInjectedStatus)

public void onStreamInjectedStatus(String url, int uid, int status)

该回调表明向直播导入的外部视频流的状态。

名称 描述
url 导入进直播的外部视频源 url 地址
uid 用户 uid
status

导入的外部视频源状态:

  • public final static int INJECT_STREAM_STATUS_START_SUCCESS = 0:外部视频流导入成功
  • public final static int INJECT_STREAM_STATUS_START_ALREADY_EXIST = 1:外部视频流已存在
  • public final static int INJECT_STREAM_STATUS_START_UNAUTHORIZED = 2:外部视频流导入未经授权
  • public final static int INJECT_STREAM_STATUS_START_TIMEDOUT = 3:导入外部视频流超时
  • public final static int INJECT_STREAM_STATUS_START_FAILED = 4:外部视频流导入失败
  • public final static int INJECT_STREAM_STATUS_STOP_SUCCESS = 5:外部视频流停止导入成功
  • public final static int INJECT_STREAM_STATUS_STOP_NOT_FOUND = 6:未找到要停止导入的外部视频流
  • public final static int INJECT_STREAM_STATUS_STOP_UNAUTHORIZED = 7:要停止导入的外部视频流未经授权
  • public final static int INJECT_STREAM_STATUS_STOP_TIMEDOUT = 8:停止导入外部视频流超时
  • public final static int INJECT_STREAM_STATUS_STOP_FAILED = 9:停止导入外部视频流失败
  • public final static int INJECT_STREAM_STATUS_BROKEN = 10:外部视频流被破坏

本地视频统计回调 (onLocalVideoStats)

public void onLocalVideoStats(LocalVideoStats stats) {
};

报告更新本地视频统计信息,该回调函数每两秒触发一次。LocalVideoStats 定义如下:

public static class LocalVideoStats {
    public int sentBitrate;
    public int sentFrameRate;
}
名称 描述
stats

本地视频相关的统计信息,包含:

  • sentBitrate:(上次统计后)发送的码率(kbps)
  • sentFrameRate:(上次统计后)发送的帧率(fps)

远端视频统计回调 (onRemoteVideoStats)

public void onRemoteVideoStats(RemoteVideoStats stats) {
};

SDK 定期向应用程序报告远程视频流的统计信息。该回调函数针对每个远端主播每 2 秒触发一次。如果远端同时存在多个主播,该回调每 2 秒会被触发多次。

public static class RemoteVideoStats {
       public int uid;
       public int delay;
       public int width;
       public int height;
       public int receivedBitrate;
       public int receivedFrameRate;
       public int rxStreamType;
 }
名称 描述
stats

远端视频相关的统计信息,包含:

  • uid: 用户ID,指定是哪个用户的视频流
  • delay: 延迟(毫秒)
  • width: 远端视频流宽度
  • height: 远端视频流高度
  • receivedBitrate: 接收码率(kbps)
  • receivedFrameRate: 接收帧率(fps)
  • rxStreamType: 视频流类型,大流或小流

摄像头启用回调 (onCameraReady)

public void onCameraReady();

提示已成功打开摄像头,可以开始捕获视频。如果摄像头打开失败,可在 onError() 中处理相应错误。

视频功能停止回调 (onVideoStopped)

public void onVideoStopped();

提示视频功能已停止。应用程序如需在停止视频后对 view 做其他处理(例如显示其他画面),可以在这个回调中进行。

接收到对方数据流消息的回调 (onStreamMessage)

public void onStreamMessage(int uid, int streamId, byte[] data);

该回调表示已在 5 秒内按照顺序收到了对方发送的数据包。

名称 描述
uid 用户 ID
streamId 数据流 ID
data 接收到的数据

接收对方数据流消息错误的回调 (onStreamMessageError)

public void onStreamMessageError(int uid, int streamId, int error, int missed, int cached);

该回调表示没有在 5 秒内收到对方发送的数据包。

名称 描述
uid 用户 ID
streamId 数据流 ID
error
  • ERR_OK = 0, 没有错误
  • ERR_NOT_IN_CHANNEL=113,用户不在频道内

更多错误码描述,详见 错误代码和警告代码

missed 丢失的消息数量
cached 数据流中断时,后面缓存的消息数量

Token 服务即将过期回调 (onTokenPrivilegeWillExpire)

public void onTokenPrivilegeWillExpire(String token);

在调用 joinChannel() 时如果指定了 Token,由于 Token 具有一定的时效,在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发该回调,提醒应用程序更新 Token。 当收到该回调时,用户需要重新在服务端生成新的 Token,然后调用 renewToken() 将新生成的 Token 传给 SDK。

名称 描述
token 即将服务失效的 Token
返回值
  • 0:方法调用成功
  • < 0:方法调用不成功

监测到活跃用户回调 (onActiveSpeaker)

public void onActiveSpeaker(int uid);

如果用户开启了 enableAudioVolumeIndication 功能,则当音量检测模块监测到频道内有新的活跃用户说话时,会通过本回调返回该用户的 uid。

名称 描述
uid 当前时间段声音最大的用户的 uid。如果返回的 uid 为 0,则默认为本地用户

Note

  • 你需要开启 enableAudioVolumeIndication 方法才能收到该回调。
  • uid 返回的是当前时间段内声音最大的用户 uid,而不是瞬时声音最大的用户 uid。

Token 已过期回调 (onRequestToken)

public void onRequestToken();

在调用 joinChannel() 时如果指定了 Token,由于 Token 具有一定的时效,在通话过程中 SDK 可能由于网络原因和服务器失去连接,重连时可能需要新的 Token。该回调通知 APP 需要生成新的 Token,并需调用 renewToken() 为 SDK 指定新的 Token。 之前的处理方法是在 onError() 回调报告 ERR_TOKEN_EXPIRED(109)、ERR_INVALID_TOKEN(110) 时,APP 需要生成新的 Token。在新版本中,原来的处理仍然有效,但建议把相关逻辑放进该回调里。

伴奏播放已结束回调 (onAudioMixingFinished)

public void onAudioMixingFinished();

当调用 startAudioMixing() 播放伴奏音乐结束后,会触发该回调。 如果调用 startAudioMixing() 失败,会在 onError 回调里,返回错误码 WARN_AUDIO_MIXING_OPEN_ERROR

音效播放已结束回调 (onAudioEffectFinished)

public void onAudioEffectFinished(int soundId)

当指定的音效播放结束后,会触发该回调。

名称 描述
soundId 指定音效的 ID。每个音效均有唯一的 ID

上下麦回调 (onClientRoleChanged)

public void onClientRoleChanged(int oldRole, int newRole);

直播场景下,当用户上下麦时会触发此回调,即主播切换为观众时,或观众切换为主播时。

名称 描述
oldRole 切换前的角色
newRole 切换后的角色

相机对焦区域已改变回调 (onCameraFocusAreaChanged)

public void onCameraFocusAreaChanged (Rect rect){};

该回调表示相机的对焦区域发生了改变。

名称 描述
rect 镜头内表示对焦区域的长方形

视频大小改变回调 (onVideoSizeChanged)

public void onVideoSizeChanged(int uid, int width, int height, int rotation)

该回调用于通知:视频帧的大小已经改变。

参数 描述
uid User ID 。
width 视频帧的宽度 (像素) 。
height 视频帧的高度 (像素) 。
rotation 视频新的旋转角度。它的值包括: 0, 90, 180, or 270 。默认为 0。

推流成功回调 (onStreamPublished)

public void onStreamPublished(String url)

该回调用于通知主播推流成功。

参数 描述
url 主播推流的 URL 地址。

停止推流回调 (onStreamUrlUnpublished)

public void onStreamUrlUnpublished(String url)

该回调用于通知主播停止推流成功。

参数 描述
url 主播推流的 URL 地址。

主播转码更新回调 (onTranscodingUpdated)

public void TranscodingUpdated()

该回调用于通知主播 CDN 转码已成功更新。

裸数据回调事件 (IAudioFrameObserver)

获得录制的声音 (onRecordFrame)

该方法获取录制的声音。

public abstract  boolean onRecordFrame(byte[] samples, int numOfSamples, int bytesPerSample, int channels, int samplesPerSec);
名称 描述
samples 该帧的样本数量
numOfSamples 采样数
bytesPerSample 每个样本的字节数:PCM(16位)含两个字节
channels 频道数量(如果是立体声,数据是交叉的)
samplesPerSec 采样率

获得播放的声音 (onPlaybackFrame)

该方法获得播放的所有声音。参数解释同 onRecordFrame。

public abstract  boolean onPlaybackFrame(byte[] samples, int numOfSamples, int bytesPerSample, int channels, int samplesPerSec);

错误代码和警告代码 - Agora Native SDK

详见 错误代码和警告代码

以上内容是否对您有帮助?