Public 成员函数

abstract int setChannelProfile (int profile)
 
abstract int setClientRole (int role)
 
abstract int sendCustomReportMessage (String id, String category, String event, String label, int value)
 
abstract int joinChannel (String token, String channelName, String optionalInfo, int optionalUid)
 
abstract int switchChannel (String token, String channelName)
 
abstract int leaveChannel ()
 
abstract int renewToken (String token)
 
abstract int registerLocalUserAccount (String appId, String userAccount)
 
abstract int joinChannelWithUserAccount (String token, String channelName, String userAccount)
 
abstract int getUserInfoByUserAccount (String userAccount, UserInfo userInfo)
 
abstract int getUserInfoByUid (int uid, UserInfo userInfo)
 
abstract int enableWebSdkInteroperability (boolean enabled)
 
abstract int getConnectionState ()
 
abstract int enableAudio ()
 
abstract int disableAudio ()
 
abstract int pauseAudio ()
 
abstract int resumeAudio ()
 
abstract int setAudioProfile (int profile, int scenario)
 
abstract int setHighQualityAudioParameters (boolean fullband, boolean stereo, boolean fullBitrate)
 
abstract int adjustRecordingSignalVolume (int volume)
 
abstract int adjustPlaybackSignalVolume (int volume)
 
abstract int adjustUserPlaybackSignalVolume (int uid, int volume)
 
abstract int enableAudioVolumeIndication (int interval, int smooth, boolean report_vad)
 
abstract int enableAudioQualityIndication (boolean enabled)
 
abstract int enableLocalAudio (boolean enabled)
 
abstract int muteLocalAudioStream (boolean muted)
 
abstract int muteRemoteAudioStream (int uid, boolean muted)
 
abstract int muteAllRemoteAudioStreams (boolean muted)
 
abstract int setDefaultMuteAllRemoteAudioStreams (boolean muted)
 
abstract int enableVideo ()
 
abstract int disableVideo ()
 
abstract int setVideoProfile (int profile, boolean swapWidthAndHeight)
 
abstract int setVideoProfile (int width, int height, int frameRate, int bitrate)
 
abstract int setVideoEncoderConfiguration (VideoEncoderConfiguration config)
 
abstract int setCameraCapturerConfiguration (CameraCapturerConfiguration config)
 
abstract int setupLocalVideo (VideoCanvas local)
 
abstract int setupRemoteVideo (VideoCanvas remote)
 
abstract int setLocalRenderMode (int mode)
 
abstract int setLocalRenderMode (int renderMode, int mirrorMode)
 
abstract int setRemoteRenderMode (int uid, int mode)
 
abstract int setRemoteRenderMode (int uid, int renderMode, int mirrorMode)
 
abstract int startPreview ()
 
abstract int stopPreview ()
 
abstract int enableLocalVideo (boolean enabled)
 
abstract int muteLocalVideoStream (boolean muted)
 
abstract int muteRemoteVideoStream (int uid, boolean muted)
 
abstract int muteAllRemoteVideoStreams (boolean muted)
 
abstract int setDefaultMuteAllRemoteVideoStreams (boolean muted)
 
abstract int setBeautyEffectOptions (boolean enabled, BeautyOptions options)
 
abstract int setDefaultAudioRoutetoSpeakerphone (boolean defaultToSpeaker)
 
abstract int setEnableSpeakerphone (boolean enabled)
 
abstract boolean isSpeakerphoneEnabled ()
 
abstract int enableInEarMonitoring (boolean enabled)
 
abstract int setInEarMonitoringVolume (int volume)
 
abstract int useExternalAudioDevice ()
 
abstract int setLocalVoicePitch (double pitch)
 
abstract int setLocalVoiceEqualization (int bandFrequency, int bandGain)
 
abstract int setLocalVoiceReverb (int reverbKey, int value)
 
abstract int setLocalVoiceChanger (int voiceChanger)
 
abstract int setLocalVoiceReverbPreset (int preset)
 
abstract int enableSoundPositionIndication (boolean enabled)
 
abstract int setRemoteVoicePosition (int uid, double pan, double gain)
 
abstract int startAudioMixing (String filePath, boolean loopback, boolean replace, int cycle)
 
abstract int stopAudioMixing ()
 
abstract int pauseAudioMixing ()
 
abstract int resumeAudioMixing ()
 
abstract int adjustAudioMixingVolume (int volume)
 
abstract int adjustAudioMixingPlayoutVolume (int volume)
 
abstract int adjustAudioMixingPublishVolume (int volume)
 
abstract int getAudioMixingPlayoutVolume ()
 
abstract int getAudioMixingPublishVolume ()
 
abstract int getAudioMixingDuration ()
 
abstract int getAudioMixingCurrentPosition ()
 
abstract int setAudioMixingPosition (int pos)
 
abstract int setAudioMixingPitch (int pitch)
 
abstract IAudioEffectManager getAudioEffectManager ()
 
abstract int startAudioRecording (String filePath, int quality)
 
abstract int startAudioRecording (String filePath, int sampleRate, int quality)
 
abstract int stopAudioRecording ()
 
abstract int startEchoTest ()
 
abstract int startEchoTest (int intervalInSeconds)
 
abstract int stopEchoTest ()
 
abstract int enableLastmileTest ()
 
abstract int disableLastmileTest ()
 
abstract int startLastmileProbeTest (LastmileProbeConfig config)
 
abstract int stopLastmileProbeTest ()
 
abstract int setVideoSource (IVideoSource source)
 
abstract int setLocalVideoRenderer (IVideoSink render)
 
abstract int setRemoteVideoRenderer (int uid, IVideoSink render)
 
abstract int setExternalAudioSink (boolean enabled, int sampleRate, int channels)
 
abstract int pullPlaybackAudioFrame (byte[] data, int lengthInByte)
 
abstract int setExternalAudioSource (boolean enabled, int sampleRate, int channels)
 
abstract int pushExternalAudioFrame (byte[] data, long timestamp)
 
abstract void setExternalVideoSource (boolean enable, boolean useTexture, boolean pushMode)
 
abstract boolean pushExternalVideoFrame (AgoraVideoFrame frame)
 
abstract boolean isTextureEncodeSupported ()
 
abstract int registerAudioFrameObserver (IAudioFrameObserver observer)
 
abstract int setRecordingAudioFrameParameters (int sampleRate, int channel, int mode, int samplesPerCall)
 
abstract int setPlaybackAudioFrameParameters (int sampleRate, int channel, int mode, int samplesPerCall)
 
abstract int setMixedAudioFrameParameters (int sampleRate, int samplesPerCall)
 
abstract int addVideoWatermark (AgoraImage watermark)
 
abstract int addVideoWatermark (String watermarkUrl, WatermarkOptions options)
 
abstract int clearVideoWatermarks ()
 
abstract int setRemoteUserPriority (int uid, int userPriority)
 
abstract int setLocalPublishFallbackOption (int option)
 
abstract int setRemoteSubscribeFallbackOption (int option)
 
abstract int enableDualStreamMode (boolean enabled)
 
abstract int setRemoteVideoStreamType (int uid, int streamType)
 
abstract int setRemoteDefaultVideoStreamType (int streamType)
 
abstract int setEncryptionSecret (String secret)
 
abstract int setEncryptionMode (String encryptionMode)
 
abstract int enableEncryption (boolean enabled, EncryptionConfig config)
 
abstract int addInjectStreamUrl (String url, LiveInjectStreamConfig config)
 
abstract int removeInjectStreamUrl (String url)
 
abstract int addPublishStreamUrl (String url, boolean transcodingEnabled)
 
abstract int removePublishStreamUrl (String url)
 
abstract int setLiveTranscoding (LiveTranscoding transcoding)
 
abstract int createDataStream (boolean reliable, boolean ordered)
 
abstract int sendStreamMessage (int streamId, byte[] message)
 
abstract int setVideoQualityParameters (boolean preferFrameRateOverImageQuality)
 
abstract int setLocalVideoMirrorMode (int mode)
 
abstract int switchCamera ()
 
abstract boolean isCameraZoomSupported ()
 
abstract boolean isCameraTorchSupported ()
 
abstract boolean isCameraFocusSupported ()
 
abstract boolean isCameraExposurePositionSupported ()
 
abstract boolean isCameraAutoFocusFaceModeSupported ()
 
abstract int setCameraZoomFactor (float factor)
 
abstract float getCameraMaxZoomFactor ()
 
abstract int setCameraFocusPositionInPreview (float positionX, float positionY)
 
abstract int setCameraExposurePosition (float positionXinView, float positionYinView)
 
abstract int enableFaceDetection (boolean enable)
 
abstract int setCameraTorchOn (boolean isOn)
 
abstract int setCameraAutoFocusFaceModeEnabled (boolean enabled)
 
abstract String getCallId ()
 
abstract int rate (String callId, int rating, String description)
 
abstract int complain (String callId, String description)
 
abstract int setLogFile (String filePath)
 
abstract int setLogFilter (int filter)
 
abstract int setLogFileSize (int fileSizeInKBytes)
 
abstract long getNativeHandle ()
 
void addHandler (IRtcEngineEventHandler handler)
 
void removeHandler (IRtcEngineEventHandler handler)
 
abstract boolean enableHighPerfWifiMode (boolean enable)
 
abstract void monitorHeadsetEvent (boolean monitor)
 
abstract void monitorBluetoothHeadsetEvent (boolean monitor)
 
abstract void setPreferHeadset (boolean enabled)
 
abstract int setParameters (String parameters)
 
abstract String getParameter (String parameter, String args)
 
abstract int registerMediaMetadataObserver (IMetadataObserver observer, int type)
 
abstract int startChannelMediaRelay (ChannelMediaRelayConfiguration channelMediaRelayConfiguration)
 
abstract int stopChannelMediaRelay ()
 
abstract int updateChannelMediaRelay (ChannelMediaRelayConfiguration channelMediaRelayConfiguration)
 
abstract RtcChannel createRtcChannel (String channelId)
 

静态 Public 成员函数

static synchronized RtcEngine create (Context context, String appId, IRtcEngineEventHandler handler) throws Exception
 
static synchronized RtcEngine create (RtcEngineConfig config) throws Exception
 
static synchronized void destroy ()
 
static SurfaceView CreateRendererView (Context context)
 
static TextureView CreateTextureView (Context context)
 
static int getRecommendedEncoderType ()
 
static String getSdkVersion ()
 
static String getMediaEngineVersion ()
 
static String getErrorDescription (int error)
 

详细描述

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

成员函数说明

◆ create() [1/2]

static synchronized RtcEngine io.agora.rtc.RtcEngine.create ( Context  context,
String  appId,
IRtcEngineEventHandler  handler 
) throws Exception
static

创建 RtcEngine 实例。

RtcEngine 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。

注解
  • 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine
  • 调用该方法和 create2 均能创建 RtcEngine 实例。该方法与 create2 的区别在于,create2 支持在创建 RtcEngine 实例时指定访问区域。
  • 目前 Agora RTC Native SDK 只支持每个 app 创建一个 RtcEngine 实例。
参数
context安卓活动 (Android Activity) 的上下文。
appIdAgora 为 app 开发者签发的 App ID,详见获取 App ID。使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 RtcEngine。如需更换 App ID,必须先调用 destroy 销毁当前 RtcEngine,并在 destroy 成功返回后,再调用 create 重新创建 RtcEngine
handlerio.agora.rtc.IRtcEngineEventHandler 是一个提供了缺省实现的抽象类,SDK 通过该抽象类向 app 报告 SDK 运行时的各种事件
返回
  • 方法调用成功,则返回一个 RtcEngine 对象。
  • 方法调用失败,则返回错误码。
    • ERR_INVALID_APP_ID(-101):不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。
异常
Exception调用该方法时可能会发生的异常说明。

◆ create() [2/2]

static synchronized RtcEngine io.agora.rtc.RtcEngine.create ( RtcEngineConfig  config) throws Exception
static

创建 RtcEngine 实例。

自从
3.0.0.2

RtcEngine 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。

注解
  • 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine
  • 调用该方法和 create1 均能创建 RtcEngine 实例。该方法与 create1 的区别在于,该方法支持在创建 RtcEngine 实例时指定访问区域,详见 RtcEngineConfig 中的 mAreaCode 参数。
  • 目前 Agora RTC Native SDK 只支持每个 app 创建一个 RtcEngine 实例。
参数
configRtcEngine 实例的配置,详见 RtcEngineConfig
返回
  • 方法调用成功,返回一个 RtcEngine 对象。
  • 方法调用失败,返回错误码。
    • ERR_INVALID_APP_ID(-101): App ID 无效。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。
异常
Exception调用该方法时可能会发生的异常说明。

◆ destroy()

static synchronized void io.agora.rtc.RtcEngine.destroy ( )
static

销毁 RtcEngine 实例。

该方法释放 Agora SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信,不需要时则将资源释放出来用于其他操作,该方法适用于此类情况。调用 destroy 方法后,你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能,你必须重新调用 create 方法创建一个新的 RtcEngine 实例。

注解
  • 该方法为同步调用,需要等待 RtcEngine 实例资源释放后才能执行其他操作,所以我们建议在子线程中调用该方法,避免主线程阻塞。此外,我们不建议在 SDK 的回调中调用 destroy,否则由于 SDK 要等待回调返回才能回收相关的对象资源,会造成死锁。
  • 如需在销毁后再次创建 RtcEngine 实例,需要等待 destroy 方法执行结束后再创建实例。

◆ setChannelProfile()

abstract int io.agora.rtc.RtcEngine.setChannelProfile ( int  profile)
abstract

设置频道场景。

该方法用于设置 Agora 频道的使用场景。Agora SDK 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。

注解
  • 为保证实时音视频质量,我们建议相同频道内的用户必须使用同一种频道场景。
  • 该方法必须在加入频道前调用,进入频道后无法再设置频道模式。
  • 不同的频道场景下,SDK 的默认音频路由和默认视频编码码率是不同的,详见 setDefaultAudioRoutetoSpeakerphonesetVideoEncoderConfiguration 中的说明。
参数
profile频道使用场景:
  • CHANNEL_PROFILE_COMMUNICATION(0):(默认)通信场景。该场景下,频道内所有用户都可以发布和接收音、视频流。适用于语音通话、视频群聊等应用场景。
  • CHANNEL_PROFILE_LIVE_BROADCASTING(1): 直播场景。该场景有主播和观众两种用户角色,可以通过 setClientRole 设置。主播可以发布和接收音视频流,观众直接接收流。适用于语聊房、视频直播、互动大班课等应用场景。
  • CHANNEL_PROFILE_GAME(2): 游戏场景。该场景默认使用低功耗低码率的编解码器,且频道内任何用户都可以自由发言,适用于游戏场景。
返回
  • 0(ERR_OK): 方法调用成功。
  • < 0: 方法调用失败。
    • -2(ERR_INVALID_ARGUMENT): 参数无效。
    • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

◆ setClientRole()

abstract int io.agora.rtc.RtcEngine.setClientRole ( int  role)
abstract

设置直播场景下的用户角色。

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

直播场景下,如果你在加入频道后调用该方法切换用户角色,调用成功后,本地会触发 onClientRoleChanged 回调;远端会触发 onUserJoined/onUserOffline(USER_OFFLINE_BECOME_AUDIENCE) 回调。

参数
role用户角色:
  • CLIENT_ROLE_BROADCASTER(1): 直播频道中的主播,可以发布和接收音视频流。
  • CLIENT_ROLE_AUDIENCE(2): 直播频道中的观众,只可以接收音视频流。
返回
  • 0(ERR_OK): 方法调用成功。
  • < 0: 方法调用失败。
    • -1(ERR_FAILED): 一般性的错误(未明确归类)。
    • -2(ERR_INALID_ARGUMENT): 参数无效。
    • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

◆ sendCustomReportMessage()

abstract int io.agora.rtc.RtcEngine.sendCustomReportMessage ( String  id,
String  category,
String  event,
String  label,
int  value 
)
abstract

声网提供自定义数据上报和分析服务。

自从
v3.1.0

该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据,每条自定义数据不能超过 256 字节,每个字符串不能超过 100 字节。如需试用该服务,请联系 sales.nosp@m.@ago.nosp@m.ra.io 开通并商定自定义数据格式。

◆ joinChannel()

abstract int io.agora.rtc.RtcEngine.joinChannel ( String  token,
String  channelName,
String  optionalInfo,
int  optionalUid 
)
abstract

加入频道。

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

成功调用该方加入频道后,本地会触发 onJoinChannelSuccess 回调;通信场景下的用户和直播场景下的主播加入频道后,远端会触发 onUserJoined 回调。

在网络状况不理想的情况下,客户端可能会与 Agora 的服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 onRejoinChannelSuccess 回调。

警告
  • 频道内每个用户的 UID 必须是唯一的。如果将 uid 设为 0,系统将自动分配一个 UID。如果想要从不同的设备同时接入同一个频道,请确保每个设备上使用的 UID 是不同的。
  • 请确保用于生成 Token 的 App ID 和 create 方法创建 RtcEngine 对象时用的 App ID 一致。
参数
token在 App 服务器端生成的用于鉴权的 Token:
channelName标识通话的频道名称,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
optionalInfo(非必选项)开发者需加入的任何附加信息。一般可设置为空字符串,或频道相关信息。该信息不会传递给频道内的其他用户。
optionalUid(非必选项)用户 ID,32 位无符号整数。建议设置范围:1 到 (2^32-1),并保证唯一性。如果不指定(即设为 0),SDK 会自动分配一个,并在 onJoinChannelSuccess 回调方法中返回,App 层必须记住该返回值并维护,SDK 不对该返回值进行维护。uid 在 SDK 内部用 32 位无符号整数表示,由于 Java 不支持无符号整数,uid 被当成 32 位有符号整数处理,对于过大的整数,Java 会表示为负数,如有需要可以用 (uid&0xffffffffL) 转换成 64 位整数。
返回
  • 0(ERR_OK): 方法调用成功。
  • < 0: 方法调用失败。
    • -2(ERR_INALID_ARGUMENT): 参数无效。
    • -3(ERR_NOT_READY): SDK 初始化失败,请尝试重新初始化 SDK。
    • -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因:
      • 已经创建了一个同名的 RtcChannel 频道。
      • 已经通过 RtcChannel 加入了一个频道,并在该 RtcChannel 频道中发布了音视频流。

◆ switchChannel()

abstract int io.agora.rtc.RtcEngine.switchChannel ( String  token,
String  channelName 
)
abstract

快速切换直播频道。

自从
v2.9.0。

当直播频道中的观众想从一个频道切换到另一个频道时,可以调用该方法,实现快速切换。

成功调用该方切换频道后,本地会先收到离开原频道的回调 onLeaveChannel,再收到成功加入新频道的回调 onJoinChannelSuccess

注解
该方法仅适用直播频道中的观众用户。
参数
token在服务器端生成的用于鉴权的 Token:
channelName标识频道的频道名,最大不超过 64 字节。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
返回
  • 0(ERR_OK): 方法调用成功。
  • < 0: 方法调用失败。
    • -1(ERR_FAILED): 一般性的错误(未明确归类)。
    • -2(ERR_INALID_ARGUMENT): 参数无效。
    • -5(ERR_REFUSED): 调用被拒绝。可能因为用户角色不是观众。
    • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
    • -102(ERR_INVALID_CHANNEL_NAME): 频道名无效。请更换有效的频道名。
    • -113(ERR_NOT_IN_CHANNEL): 用户不在频道内。

◆ leaveChannel()

abstract int io.agora.rtc.RtcEngine.leaveChannel ( )
abstract

离开频道。

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

调用 joinChannel 后,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。

不管当前是否在通话中,都可以调用 leaveChannel,没有副作用。

该方法会把会话相关的所有资源释放掉。该方法是异步操作,调用返回时并没有真正退出频道。

成功调用该方法离开频道后,本地会触发 onLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserOffline 回调。

注解
  • 如果你调用了 leaveChannel 后立即调用 destroy 方法,SDK 将无法触发 onLeaveChannel 回调。
  • 如果你在旁路推流过程中调用了 leaveChannel 方法, SDK 将自动调用 removeInjectStreamUrl 方法。
返回
  • 0(ERR_OK): 方法调用成功。
  • < 0: 方法调用失败。
    • -1(ERR_FAILED): 一般性的错误(未明确归类)。
    • -2(ERR_INALID_ARGUMENT: 参数无效。
    • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

◆ renewToken()

abstract int io.agora.rtc.RtcEngine.renewToken ( String  token)
abstract

更新 Token。

该方法用于更新 Token。如果启用了 Token 机制,过一段时间后使用的 Token 会失效。以下两种情况下,app 应重新获取 Token,然后调用 renewToken 更新 Token,否则 SDK 无法和服务器建立连接:

参数
token新的 Token。
返回
  • 0(ERR_OK): 方法调用成功。
  • < 0: 方法调用失败。
    • -1(ERR_FAILED): 一般性的错误(未明确归类)。
    • -2(ERR_INALID_ARGUMENT): 参数无效。
    • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

◆ registerLocalUserAccount()

abstract int io.agora.rtc.RtcEngine.registerLocalUserAccount ( String  appId,
String  userAccount 
)
abstract

注册本地用户 User Account。

自从
v2.8.0。

该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。

成功注册 User Account 后,本地会触发 onLocalUserRegistered 回调,告知本地用户的 UID 和 User Account。

该方法为可选。如果你希望用户使用 User Account 加入频道,可以选用以下两种方式:

两种方式的区别在于,提前调用 registerLocalUserAccount,可以缩短使用 joinChannelWithUserAccount 进入频道的时间。

注解
  • userAccount 不能为空,否则该方法不生效。
  • 请确保在该方法中设置的 userAccount 在频道中的唯一性。
  • 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Agora Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
参数
appId你的项目在 Agora 控制台注册的 App ID
userAccount用户 User Account。该参数为必填,最大不超过 255 字节,不可填 null。请确保注册的 User Account 的唯一性。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ joinChannelWithUserAccount()

abstract int io.agora.rtc.RtcEngine.joinChannelWithUserAccount ( String  token,
String  channelName,
String  userAccount 
)
abstract

使用 User Account 加入频道。

自从
v2.8.0。

该方法允许本地用户使用 User Account 加入频道。成功加入频道后,会触发以下回调:

注解
为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Agora Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
参数
token在服务器端生成的用于鉴权的 Token。
channelName标识频道的频道名,最大不超过 64 字节。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
userAccount用户 User Account。该参数为必需,最大不超过 255 字节,不可为 null。请确保加入频道的 User Account 的唯一性。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
返回

◆ getUserInfoByUserAccount()

abstract int io.agora.rtc.RtcEngine.getUserInfoByUserAccount ( String  userAccount,
UserInfo  userInfo 
)
abstract

通过 User Account 获取用户信息。

自从
v2.8.0。

远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表, 并在本地触发 onUserInfoUpdated 回调。收到这个回调后,你可以调用该方法,通过传入 User Account 获取包含了指定用户 UID 的 UserInfo 对象。

参数
userAccount用户 User Account。该参数为必填。
userInfo[in/out] 标识用户信息的 UserInfo 对象,详见 UserInfo
  • 输入值:一个 UserInfo 对象
  • 输出值:一个包含了用户 User Account 和 UID 的 UserInfo 对象
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ getUserInfoByUid()

abstract int io.agora.rtc.RtcEngine.getUserInfoByUid ( int  uid,
UserInfo  userInfo 
)
abstract

通过 UID 获取用户信息。

自从
v2.8.0。

远端用户加入频道后, SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 onUserInfoUpdated 回调。 收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。

参数
uid用户 ID。该参数为必填。
userInfo[in/out] 标识用户信息的 UserInfo 对象,详见 UserInfo
  • 输入值:一个 UserInfo 对象
  • 输出值:一个包含了用户 User Account 和 UID 的 UserInfo 对象
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ enableWebSdkInteroperability()

abstract int io.agora.rtc.RtcEngine.enableWebSdkInteroperability ( boolean  enabled)
abstract

打开与 Web SDK 的互通(仅在直播下适用)。

弃用:
v3.0.0。自 Native SDK 3.0.0 及之后,SDK 自动开启与 Web SDK 的互通,无需调用该方法开启。

该方法打开或关闭与 Agora Web SDK 的互通。如果有用户通过 Web SDK 加入频道,请确保调用该方法,否则 Web 端用户看 Native 端的画面会是黑屏。

该方法仅在直播场景下适用,通信场景下默认互通是打开的。

参数
enabled是否打开与 Agora Web SDK 的互通:
  • true: 打开互通。
  • false: (默认)关闭互通。
返回
  • 0:方法调用成功。
  • <0:方法调用失败。

◆ getConnectionState()

abstract int io.agora.rtc.RtcEngine.getConnectionState ( )
abstract

获取当前网络连接状态。

自从
v2.3.2。
返回
当前的网络连接状态:

◆ enableAudio()

abstract int io.agora.rtc.RtcEngine.enableAudio ( )
abstract

启用音频模块(默认为开启状态)。

注解
  • 该方法设置的是内部引擎为开启状态,在频道内和频道外均可调用,且在 leaveChannel 后仍然有效。
  • 该方法重置整个引擎,响应速度较慢,因此我们建议使用如下方法来控制音频模块:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ disableAudio()

abstract int io.agora.rtc.RtcEngine.disableAudio ( )
abstract

关闭音频模块。

注解
  • 该方法设置的是内部引擎为禁用状态,在频道内和频道外均可调用,且在 leaveChannel 后仍然有效。
  • 该方法重置整个引擎,响应速度较慢,因此 Agora 建议使用如下方法来控制音频模块:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ pauseAudio()

abstract int io.agora.rtc.RtcEngine.pauseAudio ( )
abstract

禁用频道中的音频功能。

弃用:
该方法已废弃。声网不建议你使用。如果你想禁用频道中的音频功能,请改用 disableAudio 方法。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ resumeAudio()

abstract int io.agora.rtc.RtcEngine.resumeAudio ( )
abstract

启用频道中的音频功能。

弃用:
该方法已废弃。声网不建议你使用。如果你想启用频道中的音频功能,请改用 enableAudio 方法。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setAudioProfile()

abstract int io.agora.rtc.RtcEngine.setAudioProfile ( int  profile,
int  scenario 
)
abstract

设置音频编码配置。

注解
  • 该方法需要在 joinChannel 之前设置好,joinChannel 后设置不生效。
  • 通信和直播场景下,音质(码率)会有网络自适应的调整,通过该方法设置的是一个最高码率。
  • 在有高音质需求的场景(例如音乐教学场景)中,建议将 profile 设置为 MUSIC_HIGH_QUALITY (4),Scenario 设置为 GAME_STREAMING (3)
参数
profile设置采样率,码率,编码模式和声道数,详见 AudioProfile
scenario设置音频应用场景,详见 AudioScenario。不同的音频场景下,设备的系统音量是不同的。详见如何区分媒体音量和通话音量

◆ setHighQualityAudioParameters()

abstract int io.agora.rtc.RtcEngine.setHighQualityAudioParameters ( boolean  fullband,
boolean  stereo,
boolean  fullBitrate 
)
abstract

设置音频高音质选项。

弃用:
该方法已废弃。声网不建议你使用。如果你希望设置音频高音质选项,请改用 setAudioProfile 方法。

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

参数
fullband全频带编解码器(48 kHz 采样率), 不兼容 1.7.4 以前版本
  • true: 启用全频带编解码器
  • false: 禁用全频带编解码器
stereo立体声编解码器,不兼容 1.7.4 以前版本
  • true: 启用立体声编解码器
  • false: 禁用立体声编解码器
fullBitrate高码率模式,建议仅在纯音频模式下使用
  • true: 启用高码率模式
  • false: 禁用高码率模式
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ adjustRecordingSignalVolume()

abstract int io.agora.rtc.RtcEngine.adjustRecordingSignalVolume ( int  volume)
abstract

调节录音音量。

参数
volume录音信号音量,可在 0~400 范围内进行调节:
  • 0:静音
  • 100:原始音量
  • 400:最大可为原始音量的 4 倍(自带溢出保护)。为避免回声并提升通话质量,Agora 建议将 volume 值设为 [0,100]。如果 volume 值需超过 100,联系技术支持
返回
  • 0: 方法调用成功。
  • <0: 方法调用失败。

◆ adjustPlaybackSignalVolume()

abstract int io.agora.rtc.RtcEngine.adjustPlaybackSignalVolume ( int  volume)
abstract

调节本地播放的所有远端用户音量。

注解
  • 该方法调节的是本地播放的所有远端用户混音后的音量。
  • 从 v2.3.2 开始,静音本地音频需同时调用该方法和 adjustAudioMixingPlayoutVolume 方法,并将 volume 参数设置为 0。
参数
volume播放音量,取值范围为 [0, 400]:
  • 0:静音
  • 100:原始音量
  • 400:最大可为原始音量的 4 倍(自带溢出保护)。为避免回声并提升通话质量,Agora 建议将 volume 值设为 [0,100]。如果 volume 值需超过 100,联系技术支持
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ adjustUserPlaybackSignalVolume()

abstract int io.agora.rtc.RtcEngine.adjustUserPlaybackSignalVolume ( int  uid,
int  volume 
)
abstract

调节本地播放的指定远端用户音量。

自从
v3.0.0。

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。

注解
  • 该方法要在加入频道后调用。
  • 该方法调节的是本地播放的指定远端用户混音后的音量。
  • 该方法每次只能调整一位远端用户在本地播放的音量。如需调整多位远端用户在本地播放的音量,则需多次调用该方法。
参数
uid远端用户的 ID。
volume播放音量,取值范围为 [0,100]。
  • 0:静音。
  • 100:原始音量。
返回
  • 0:方法调用成功。
  • < 0:方法调用失败。

◆ enableAudioVolumeIndication()

abstract int io.agora.rtc.RtcEngine.enableAudioVolumeIndication ( int  interval,
int  smooth,
boolean  report_vad 
)
abstract

启用说话者音量提示。

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

参数
interval指定音量提示的时间间隔:
  • ≤ 0:禁用音量提示功能。
  • > 0:返回音量提示的间隔,单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒,否则会收不到 onAudioVolumeIndication 回调。
smooth平滑系数,指定音量提示的灵敏度。取值范围为 [0, 10],建议值为 3,数字越大,波动越灵敏;数字越小,波动越平滑。
report_vad是否开启人声检测
  • true: 开启本地人声检测功能。开启后,onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。
  • false: (默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ enableAudioQualityIndication()

abstract int io.agora.rtc.RtcEngine.enableAudioQualityIndication ( boolean  enabled)
abstract

启用音频质量通知回调。

弃用:
从 v2.4.1 起废弃。

该方法启用音频质量通知回调。一旦启用,onAudioQuality 将被定期触发。

参数
enabled是否启用音频质量通知回调
  • true: 启用
  • false: 禁用(默认)
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ enableLocalAudio()

abstract int io.agora.rtc.RtcEngine.enableLocalAudio ( boolean  enabled)
abstract

开启/关闭本地音频采集。

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

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

语音功能关闭或重新开启后,会收到回调 onLocalAudioStateChanged ,并报告 LOCAL_AUDIO_STREAM_STATE_STOPPED(0) 或 LOCAL_AUDIO_STREAM_STATE_RECORDING(1)`。

注解
  • 调用 enableLocalAudio(false) 关闭本地采集后,系统会走媒体音量;调用 enableLocalAudio(true) 重新打开本地采集后,系统会恢复为通话音量。
  • 该方法与 muteLocalAudioStream 的区别在于:
    • enableLocalAudio 开启或关闭本地语音采集及处理。使用 enableLocalAudio 关闭或开启本地采集后,本地听远端播放会有短暂中断。
    • muteLocalAudioStream 停止或继续发送本地音频流。
参数
enabled是否开启本地语音。
  • true:(默认)重新开启本地语音,即开启本地语音采集。
  • false: 关闭本地语音,即停止本地语音采集。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ muteLocalAudioStream()

abstract int io.agora.rtc.RtcEngine.muteLocalAudioStream ( boolean  muted)
abstract

停止/恢复发送本地音频流。

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

成功调用该方法后,远端会触发 onUserMuteAudio 回调。

注解
  • 该方法不影响录音状态,并没有禁用麦克风。
  • 如果你在该方法后调用 setChannelProfile 方法,SDK 会根据你设置的频道模式以及用户角色,重新设置是否停止发送本地音频。因此我们建议在 setChannelProfile 后调用该方法。
参数
muted是否停止发送本地音频流。
  • true: 停止发送本地音频流
  • false:(默认)继续发送本地音频流
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ muteRemoteAudioStream()

abstract int io.agora.rtc.RtcEngine.muteRemoteAudioStream ( int  uid,
boolean  muted 
)
abstract

停止/恢复接收指定音频流。

参数
uid指定的用户 ID
muted
  • true:停止接收指定用户的音频流
  • false:继续接收指定用户的音频流(默认)
注解
如果之前有调用过 muteAllRemoteAudioStreams (true) 停止接收所有远端音频流,在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams (false)。muteAllRemoteAudioStreams 是全局控制,muteRemoteAudioStream 是精细控制。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ muteAllRemoteAudioStreams()

abstract int io.agora.rtc.RtcEngine.muteAllRemoteAudioStreams ( boolean  muted)
abstract

停止/恢复接收所有音频流。

参数
muted
  • true:停止接收所有远端音频流
  • false:继续接收所有远端音频流(默认)
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setDefaultMuteAllRemoteAudioStreams()

abstract int io.agora.rtc.RtcEngine.setDefaultMuteAllRemoteAudioStreams ( boolean  muted)
abstract

设置是否默认接收音频流。

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteAudioStreams(true), 会接收不到后面加入频道的用户的音频流。

注解
停止接收音频流后,如果想要恢复接收,请调用 muteRemoteAudioStream(false),并指定你想要接收的远端用户的 ID。 如果想恢复接收多个用户的音频流,则需要多次调用 muteRemoteAudioStreamsetDefaultMuteAllRemoteAudioStreams(false) 只能恢复接收设置后加入频道的用户的音频流。
参数
muted是否默认不接收所有远端音频:
  • true:默认不接收所有远端音频流
  • false:默认接收所有远端音频流(默认)
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ enableVideo()

abstract int io.agora.rtc.RtcEngine.enableVideo ( )
abstract

启用视频模块。

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

成功调用该方法后,远端会触发 onUserEnableVideo(true) 回调。

注解
  • 该方法设置的是内部引擎为开启状态,在频道内和频道外均可调用,且在 leaveChannel 后仍然有效。
  • 该方法重置整个引擎,响应速度较慢,因此 Agora 建议使用如下方法来控制视频模块:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ disableVideo()

abstract int io.agora.rtc.RtcEngine.disableVideo ( )
abstract

关闭视频模块。

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

成功调用该方法后,远端会触发 onUserEnableVideo(false) 回调。

注解
  • 该方法设置的是内部引擎为禁用状态,在频道内和频道外均可调用,且在 leaveChannel 后仍然有效。
  • 该方法重置整个引擎,响应速度较慢,因此 Agora 建议使用如下方法来控制视频模块:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setVideoProfile() [1/2]

abstract int io.agora.rtc.RtcEngine.setVideoProfile ( int  profile,
boolean  swapWidthAndHeight 
)
abstract

设置视频属性。

弃用:
从 v2.3.2 起废弃。声网不建议你使用。如果你希望设置视频编码属性,请改用 setVideoEncoderConfiguration 方法。

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

参数
profile视频属性,详细定义见 Video Profile
swapWidthAndHeightSDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高:
  • true:交换宽和高,交换后视频为 Portrait(竖屏)布局,即宽 < 高
  • false:(默认)不交换宽和高,视频为 Landscape(横屏)布局,即宽 > 高
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setVideoProfile() [2/2]

abstract int io.agora.rtc.RtcEngine.setVideoProfile ( int  width,
int  height,
int  frameRate,
int  bitrate 
)
abstract

手动设置视频属性。

弃用:
从 v2.3.2 起废弃。声网不建议你使用。如果你希望设置视频编码属性,请改用 setVideoEncoderConfiguration 方法。

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

参数
width你想要设置的视频宽度,宽 × 高的最大值不超过 1280 × 720。
height你想要设置的视频高度,宽 × 高的最大值不超过 1280 × 720。
frameRate你想要设置的视频帧率,最高值不超过 30,如: 5、10、15、24、30 等。
bitrate你想要设置的视频码率,需要开发者根据想要设置的视频的宽、高和帧率,根据 Bitrate 中的码率参考表,手动推算出合适值。宽和高固定的情况下,码率随帧率的变化而变化:
  • 如选取的帧率为 5 FPS,则推算码率为上表推荐码率除以 2。
  • 如选取的帧率为 15 FPS,则推算码率为上表推荐码率。
  • 如选取的帧率为 30 FPS,则推算码率为上表码率乘以 1.5。
  • 如选取其余帧率,等比例推算即可。
  • 如设置的视频码率超出合理范围,SDK 会自动按照合理区间处理码率。

◆ setVideoEncoderConfiguration()

abstract int io.agora.rtc.RtcEngine.setVideoEncoderConfiguration ( VideoEncoderConfiguration  config)
abstract

设置视频编码属性。

自从
v2.3.0。用于替换 setVideoProfile 方法。

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

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

参数
config视频编码属性,详细定义见 VideoEncoderConfiguration
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setCameraCapturerConfiguration()

abstract int io.agora.rtc.RtcEngine.setCameraCapturerConfiguration ( CameraCapturerConfiguration  config)
abstract

设置摄像头的采集偏好。

自从
v2.4.0。

一般的视频通话或直播中,默认由 SDK 自动控制摄像头的输出参数。在如下特殊场景中,默认的参数通常无法满足需求,或可能引起设备性能问题,我们推荐调用该接口设置摄像头的采集偏好:

  • 使用裸数据自采集接口时,如果 SDK 输出的分辨率和帧率高于 setVideoEncoderConfiguration 中指定的参数,在后续处理视频帧的时候,比如美颜功能时, 会需要更高的 CPU 及内存,容易导致性能问题。在这种情况下,我们推荐将摄像头采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1),避免性能问题
  • 如果没有本地预览功能或者对预览质量没有要求,我们推荐将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1),以优化 CPU 和内存的资源分配
  • 如果用户希望本地预览视频比实际编码发送的视频清晰,可以将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PREVIEW(2)
注解
请在启动摄像头之前调用该方法,如 joinChannelenableVideo 或者 enableLocalVideo
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。
参数
config摄像头采集偏好,详细定义见 CameraCapturerConfiguration

◆ setupLocalVideo()

abstract int io.agora.rtc.RtcEngine.setupLocalVideo ( VideoCanvas  local)
abstract

初始化本地视图。

该方法初始化本地视图并设置本地用户视频显示信息,只影响本地用户看到的视频画面,不影响本地发布视频。 调用该方法绑定本地视频流的显示视窗(View),并设置本地用户视图的渲染模式和镜像模式。

注解
  • 请在主线程调用该方法。
  • 如果你希望在通话中更新本地用户视图的渲染或镜像模式,请使用 setLocalRenderMode 方法。
参数
local本地视频显示属性,详细定义见 Video Canvas
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setupRemoteVideo()

abstract int io.agora.rtc.RtcEngine.setupRemoteVideo ( VideoCanvas  remote)
abstract

初始化远端用户视图。

该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。

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

注解
  • 请在主线程调用该方法。
  • 如果你希望在通话中更新远端用户的渲染或镜像模式,请使用 setRemoteRenderMode 方法。
参数
remote远端视图属性,详细定义见 Video Canvas
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setLocalRenderMode() [1/2]

abstract int io.agora.rtc.RtcEngine.setLocalRenderMode ( int  mode)
abstract

设置本地视频显示模式。

弃用:
v3.0.0。该方法已废弃,请改用 setLocalRenderMode2 方法。

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

参数
mode视频显示模式:
  • RENDER_MODE_HIDDEN(1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
  • RENDER_MODE_FIT(2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
  • RENDER_MODE_ADAPTIVE(3):已废弃,不再推荐使用。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setLocalRenderMode() [2/2]

abstract int io.agora.rtc.RtcEngine.setLocalRenderMode ( int  renderMode,
int  mirrorMode 
)
abstract

更新本地视图显示模式。

自从
v3.0.0。

初始化本地用户视图后,你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面,不影响本地发布视频。

注解
  • 请在调用 setupLocalVideo 方法初始化本地视图后,调用该方法。
  • 你可以在通话中多次调用该方法,多次更新本地用户视图的显示模式。
参数
renderMode本地视图的渲染模式。
  • RENDER_MODE_HIDDEN(1): 优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
  • RENDER_MODE_FIT(2): 优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
  • RENDER_MODE_ADAPTIVE(3): 已废弃,不再推荐使用。
  • RENDER_MODE_FILL(4): 视频尺寸进行缩放和拉伸以充满显示视窗。
mirrorMode本地视图的镜像模式。
  • VIDEO_MIRROR_AUTO(0): 默认的镜像模式(SDK 决定镜像模式)。如果你使用前置摄像头,默认启动本地视图镜像模式;如果你启用后置摄像头,默认关闭本地视图镜像模式。
  • VIDEO_MIRROR_MODE_ENABLED(1): 开启镜像模式。
  • VIDEO_MIRROR_MODE_DISABLED(2): 关闭镜像模式。
返回
  • 0:方法调用成功。
  • < 0:方法调用失败。

◆ setRemoteRenderMode() [1/2]

abstract int io.agora.rtc.RtcEngine.setRemoteRenderMode ( int  uid,
int  mode 
)
abstract

设置远端视频显示模式。

弃用:
v3.0.0. 该方法已废弃,请改用 setRemoteRenderMode2。

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

参数
uid远端用户 ID
mode视频显示模式:
  • RENDER_MODE_HIDDEN(1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
  • RENDER_MODE_FIT(2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
  • RENDER_MODE_ADAPTIVE(3):已废弃,不再推荐使用。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setRemoteRenderMode() [2/2]

abstract int io.agora.rtc.RtcEngine.setRemoteRenderMode ( int  uid,
int  renderMode,
int  mirrorMode 
)
abstract

更新远端视图显示模式。

自从
v3.0.0。

初始化远端用户视图后,你可以调用该方法更新远端用户在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

注解
  • 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
  • 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
uid远端用户的 ID。
renderMode远端用户视图的渲染模式。
  • RENDER_MODE_HIDDEN(1): 优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
  • RENDER_MODE_FIT(2): 优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
  • RENDER_MODE_ADAPTIVE(3): 已废弃,不再推荐使用。
  • RENDER_MODE_FILL(4): 视频尺寸进行缩放和拉伸以充满显示视窗。
mirrorMode远端用户视图的镜像模式。
  • VIDEO_MIRROR_AUTO(0): 默认的镜像模式(SDK 决定镜像模式)。SDK 默认关闭远端用户视图的镜像模式。
  • VIDEO_MIRROR_MODE_ENABLED(1): 开启镜像模式。
  • VIDEO_MIRROR_MODE_DISABLED(2): 关闭镜像模式。
返回
  • 0:方法调用成功。
  • < 0:方法调用失败。

◆ CreateRendererView()

static SurfaceView io.agora.rtc.RtcEngine.CreateRendererView ( Context  context)
static

创建 RendererView。

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

如果你需要使用 SurfaceView,请调用本方法;如果你需要使用 TextureView,请调用 CreateTextureView 方法。详见 TextureView 和 SurfaceView 的区别选择 SurfaceView 或 TextureView

注解
请在主线程调用该方法。
参数
context安卓活动 (Android Activity) 的上下文。
返回
SurfaceView

◆ CreateTextureView()

static TextureView io.agora.rtc.RtcEngine.CreateTextureView ( Context  context)
static

创建 TextureView。

自从
v3.1.0。

该方法创建 TextureView,适用于需要对视频画面进行缩放、旋转和平移的场景,如屏幕共享。View 的操作和布局由 app 管理,SDK 仅在 app 提供的 View 上进行渲染。

如果你需要使用 TextureView,请调用本方法。如果你需要使用 SurfaceView,请调用 CreateRendererView 方法。详见 TextureView 和 SurfaceView 的区别选择 SurfaceView 或 TextureView

Agora 推荐你在视频通话和直播场景使用 SurfaceView,在需要对视频画面进行缩放、旋转和平移的场景(如屏幕共享场景)使用 TextureView。

注解
请在主线程调用该方法。
参数
context安卓活动 (Android Activity) 的上下文。
返回
TextureView

◆ startPreview()

abstract int io.agora.rtc.RtcEngine.startPreview ( )
abstract

开启视频预览。

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

注解
  • 本地预览默认开启镜像功能。
  • 使用该方法启用了本地视频预览后,如果直接调用 leaveChannel 退出频道,并不会关闭预览。如需关闭预览,请调用 stopPreview
返回
  • 0:方法调用成功。
  • < 0:方法调用失败。

◆ stopPreview()

abstract int io.agora.rtc.RtcEngine.stopPreview ( )
abstract

停止视频预览。

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

◆ enableLocalVideo()

abstract int io.agora.rtc.RtcEngine.enableLocalVideo ( boolean  enabled)
abstract

开启/关闭本地视频采集。

该方法禁用或重新启用本地视频采集。不影响接收远端视频。

调用 enableVideo 后,本地视频即默认开启。 你可以调用 enableLocalVideo(false) 关闭本地视频采集。关闭后如果想重新开启,则可调用 enableLocalVideo(true)。

成功禁用或启用本地视频采集后,远端会触发 onUserEnableLocalVideo 回调。

注解
该方法设置的是内部引擎为启用或禁用状态,在 leaveChannel 后仍然有效。
参数
enabled是否启用本地视频:
  • true: 开启本地视频采集和渲染(默认)
  • false: 关闭使用本地摄像头设备。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为 false 时,该方法不需要本地有摄像头。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ muteLocalVideoStream()

abstract int io.agora.rtc.RtcEngine.muteLocalVideoStream ( boolean  muted)
abstract

停止/恢复发送本地视频流。

成功调用该方法后,远端会触发 onUserMuteVideo 回调。

注解
  • 调用该方法时,SDK 不再发送本地视频流,但摄像头仍然处于工作状态。相比于 enableLocalVideo (false) 用于控制本地视频流发送的方法,该方法响应速度更快。
  • 该方法不影响本地视频流获取,没有禁用摄像头。
  • 如果你在该方法后调用 setChannelProfile 方法,SDK 会根据你设置的频道模式以及用户角色,重新设置是否停止发送本地视频。因此我们建议在 setChannelProfile 后调用该方法。
参数
muted发送本地视频流
  • true: 不发送本地视频流。
  • false: (默认)发送本地视频流。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ muteRemoteVideoStream()

abstract int io.agora.rtc.RtcEngine.muteRemoteVideoStream ( int  uid,
boolean  muted 
)
abstract

停止/恢复接收指定视频流。

注解
如果之前有调用过 muteAllRemoteVideoStreams(true) 停止接收所有远端视频流,在调用本 API 之前请确保你已调用 muteAllRemoteVideoStreams(false)。 muteAllRemoteVideoStreams 是全局控制,muteRemoteVideoStream 是精细控制。
参数
uid指定的用户 ID。
muted是否停止接收指定用户的视频流:
  • true: 停止接收指定用户的视频流。
  • false: (默认)继续接收指定用户的视频流。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ muteAllRemoteVideoStreams()

abstract int io.agora.rtc.RtcEngine.muteAllRemoteVideoStreams ( boolean  muted)
abstract

停止/恢复接收所有视频流。

参数
muted是否停止接收所有远端视频流:
  • true: 停止接收所有远端视频流。
  • false: (默认)继续接收所有远端视频流。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setDefaultMuteAllRemoteVideoStreams()

abstract int io.agora.rtc.RtcEngine.setDefaultMuteAllRemoteVideoStreams ( boolean  muted)
abstract

设置是否默认接收视频流。

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteVideoStreams(true), 会接收不到后面加入频道的用户的音频流。

注解
停止接收视频流后,如果想要恢复接收,请调用 muteRemoteVideoStream(false),并指定你想要接收的远端用户的 ID。 如果想恢复接收多个用户的视频流,则需要多次调用 muteRemoteVideoStreamsetDefaultMuteAllRemoteVideoStreams(false) 只能恢复接收设置后加入频道的用户的视频流。
参数
muted是否默认不接收所有远端视频流:
  • true:默认不接收所有远端视频流
  • false:默认继续接收所有远端视频流(默认)
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ setBeautyEffectOptions()

abstract int io.agora.rtc.RtcEngine.setBeautyEffectOptions ( boolean  enabled,
BeautyOptions  options 
)
abstract

开启本地美颜功能,并设置美颜效果选项。

自从
v2.4.0。
注解
  • 该方法需要在 enableVideo 之后调用。
  • 该方法仅适用于 Android 4.4 及以上版本。
参数
enabled是否开启美颜功能:
  • true:开启
  • false:(默认)关闭
options美颜选项,详细定义见 BeautyOptions
返回
  • 0:方法调用成功
  • < 0:方法调用失败
    • ERR_NOT_SUPPORTED(4):当前设备版本低于 Android 4.4,不支持该操作。

◆ setDefaultAudioRoutetoSpeakerphone()

abstract int io.agora.rtc.RtcEngine.setDefaultAudioRoutetoSpeakerphone ( boolean  defaultToSpeaker)
abstract

设置默认的音频播放路由。

该方法设置接收到的语音从听筒或扬声器出声。如果用户不调用本方法,则语音默认从听筒出声。 如果你想要在加入频道后修改语音路由,可以使用 setEnableSpeakerphone.

各场景下默认的语音路由:

  • 通信场景:
    • 语音通话,默认从听筒出声。
    • 视频通话,默认从扬声器出声。如果有用户在频道中使用 disableVideomuteLocalVideoStreammuteAllRemoteVideoStreams 关闭视频,则语音路由会自动切换回听筒。
  • 直播场景:扬声器。
注解
  • 该方法仅适用于通信场景。
  • 该方法需要在加入频道前设置,否则不生效。
参数
defaultToSpeaker
  • true:默认从外放(扬声器)出声。如果设备连接了耳机或蓝牙,则无法切换到外放。
  • false:(默认)默认从听筒出声。如果设备连接了耳机,则语音路由走耳机。
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ setEnableSpeakerphone()

abstract int io.agora.rtc.RtcEngine.setEnableSpeakerphone ( boolean  enabled)
abstract

启用/关闭扬声器播放。

该方法设置是否将语音路由设到扬声器(外放)。调用该方法后,SDK 将触发 onAudioRouteChanged 回调提示状态已更改。

注解
  • 请确保在调用此方法前已调用过 joinChannel 方法。
  • setAudioProfilescenariosetChannelProfile 的设置会影响 setEnableSpeakerphone 的行为。setEnableSpeakerphone 不生效的情况如下:
    • scenarioAUDIO_SCENARIO_GAME_STREAMING 时,所有用户都无法切换音频播放路由。
    • scenarioAUDIO_SCENARIO_DEFAULTAUDIO_SCENARIO_SHOWROOM 时,直播场景中的观众无法切换音频播放路由,且当频道中只有一个主播时,该主播也无法切换音频播放路由。
    • scenarioAUDIO_SCENARIO_EDUCATION 时,直播场景中的观众无法切换音频播放路由。
参数
enabled是否将音频路由到外放:
  • true: 切换到外放。
  • false: 切换到听筒。如果设备连接了耳机,则语音路由走耳机。
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ isSpeakerphoneEnabled()

abstract boolean io.agora.rtc.RtcEngine.isSpeakerphoneEnabled ( )
abstract

检查扬声器状态启用状态。

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

返回
  • true:扬声器已开启,语音会输出到扬声器
  • false:扬声器未开启,语音会输出到非扬声器(听筒,耳机等)

◆ enableInEarMonitoring()

abstract int io.agora.rtc.RtcEngine.enableInEarMonitoring ( boolean  enabled)
abstract

开启耳返功能。

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

注解
用户必须使用有线耳机才能听到耳返效果。
参数
enabled
  • true: 开启耳返功能
  • false: (默认)关闭耳返功能
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ setInEarMonitoringVolume()

abstract int io.agora.rtc.RtcEngine.setInEarMonitoringVolume ( int  volume)
abstract

设置耳返音量。

注解
用户必须使用有线耳机才能听到耳返效果。
参数
volume设置耳返音量,取值范围在 0 到 100 间。默认值为 100。
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ useExternalAudioDevice()

abstract int io.agora.rtc.RtcEngine.useExternalAudioDevice ( )
abstract

使用外部音频设备。

弃用:
该方法已废弃。声网不建议你使用。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setLocalVoicePitch()

abstract int io.agora.rtc.RtcEngine.setLocalVoicePitch ( double  pitch)
abstract

设置本地语音音调。

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

参数
pitch语音频率。可以在 [0.5, 2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调。
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ setLocalVoiceEqualization()

abstract int io.agora.rtc.RtcEngine.setLocalVoiceEqualization ( int  bandFrequency,
int  bandGain 
)
abstract

设置本地语音音效均衡。

参数
bandFrequency频谱子带索引,取值范围是 [0-9],分别代表 10 个频带,对应的中心频率是 [31,62,125,250,500,1k,2k,4k,8k,16k] Hz
bandGain每个 band 的增益,单位是 dB,每一个值的范围是 [-15,15],默认值为 0
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ setLocalVoiceReverb()

abstract int io.agora.rtc.RtcEngine.setLocalVoiceReverb ( int  reverbKey,
int  value 
)
abstract

设置本地音效混响。

注解
Agora SDK 在 v2.4.0 版本中提供一个使用更为简便的接口 setLocalVoiceReverbPreset,该 方法通过一系列内置参数的调整,直接实现流行、R&B、摇滚、嘻哈等预置的混响效果。详见 setLocalVoiceReverbPreset
参数
reverbKey混响音效 Key。该方法共有 5 个混响音效 Key,分别如 value 栏列出。
value各混响音效 Key 所对应的值:
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ setLocalVoiceChanger()

abstract int io.agora.rtc.RtcEngine.setLocalVoiceChanger ( int  voiceChanger)
abstract

设置本地语音变声、美音或语聊美声效果。

自从
v2.4.0。

通信场景下的用户或直播场景下的主播均可调用该方法为本地语音设置以下效果。成功设置以后,频道内的所有用户均可听到声音效果。

  • 变声效果:枚举值以 VOICE_CHANGER 为前缀。效果包括老男孩、小男孩、小女孩、猪八戒、空灵和绿巨人,通常用于语聊场景。
  • 美音效果:枚举值以 VOICE_BEAUTY 为前缀。效果包括浑厚、低沉、圆润、假音、饱满、清澈、高亢、嘹亮和空旷,通常用于语聊和唱歌场景。
  • 语聊美声效果:枚举值以 GENERAL_BEAUTY_VOICE 为前缀。效果包括磁性(男)、清新(女)和活力(女),通常用于语聊场景。该功能主要细化了男声和女声各自的特点。
注解
  • 为达到更好的声音效果,Agora 推荐在调用该方法前将 setAudioProfileprofile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)
  • 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含人声和音乐的音频数据。
  • 该方法不能与 setLocalVoiceReverbPreset 方法一同使用,否则先调的方法会不生效。更多注意事项,详见《变声与混响》。
参数
voiceChanger本地语音的变声、美音或语聊美声效果选项:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setLocalVoiceReverbPreset()

abstract int io.agora.rtc.RtcEngine.setLocalVoiceReverbPreset ( int  preset)
abstract

设置本地语音混响(含虚拟立体声效果)。

自从
v2.4.0。

通信场景下的用户或直播场景下的主播均可调用该方法设置本地语音混响。成功设置以后,频道内的所有用户均可听到声音效果。

注解
  • 当使用以 AUDIO_REVERB_FX 为前缀的枚举值时,请确保在调用该方法前将 setAudioProfileprofile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5),否则该方法设置无效。
  • 当使用 AUDIO_VIRTUAL_STEREO 时,Agora 推荐在调用该方法前将 setAudioProfileprofile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)
  • 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含人声和音乐的音频数据。
  • 该方法不能与 setLocalVoiceChanger 方法一同使用,否则先调的方法会不生效。更多注意事项,详见《变声与混响》。
参数
preset本地语音混响选项。为达到更好的混响效果,Agora 推荐使用以 AUDIO_REVERB_FX 为前缀的枚举值。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ enableSoundPositionIndication()

abstract int io.agora.rtc.RtcEngine.enableSoundPositionIndication ( boolean  enabled)
abstract

开启/关闭远端用户的语音立体声。

自从
v2.4.0。

如果想调用 setRemoteVoicePosition 实现听声辨位的功能,请确保在调用 joinChannel 方法前调用该方法。

参数
enabled是否开启远端用户语音立体声:
  • true:开启
  • false:(默认)关闭
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ setRemoteVoicePosition()

abstract int io.agora.rtc.RtcEngine.setRemoteVoicePosition ( int  uid,
double  pan,
double  gain 
)
abstract

设置远端用户声音的空间位置和音量,方便本地用户听声辨位。

自从
v2.4.0。

用户通过调用该接口,设置远端用户声音出现的位置,左右声道的声音差异会让用户产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。

注解
  • 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声
  • 为获得最佳听觉体验,我们建议用户佩戴耳机
参数
uid远端用户的 ID
pan设置远端用户声音出现的位置,取值范围为 [-1.0, 1.0]:
  • 0.0:(默认)声音出现在正前方
  • -1.0:声音出现在左边
  • 1.0:声音出现在右边
gain设置远端用户声音的音量,取值范围为 [0.0, 100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ startAudioMixing()

abstract int io.agora.rtc.RtcEngine.startAudioMixing ( String  filePath,
boolean  loopback,
boolean  replace,
int  cycle 
)
abstract

开始播放音乐文件及混音。

该方法指定本地或在线音频文件来和麦克风采集的音频流进行混音或替换。替换是指用音频文件替换麦克风采集的音频流。该方法可以选择是否让对方听到本地播放的音频,并指定循环播放的次数。 成功调用该方法后,本地会触发 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY) 回调。播放结束后,会收到 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_STOPPED) 回调。

注解
  • 如需调用该方法,请确保使用 Android 4.2 或以上设备,且 API Level ≥ 16
  • 请在频道内调用该方法,如果在频道外调用该方法可能会出现问题
  • 如果播放的是在线音乐文件,请确保重复调用该 API 的间隔超过 100 ms,否则 SDK 会返回 AUDIO_FILE_OPEN_TOO_FREQUENT = 702 警告码,表示音乐文件打开过于频繁
  • 如果播放的是在线音乐文件,Agora 建议不要使用重定向地址。重定向地址在某些机型上可能会出现无法打开的情况
  • 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 WARN_AUDIO_MIXING_OPEN_ERROR(701)
  • 如果在模拟器上使用该 API,暂时只支持存放在 /sdcard/ 中的 mp3 文件。
参数
filePath指定需要混音的本地或在线音频文件的绝对路径(包含文件名后缀),如 /sdcard/emulated/0/audio.mp4。支持的音频格式包括:mp3、mp4、m4a、aac、3gp、mkv 及 wav。
  • 如果用户提供的目录以 /assets/ 开头,则去 assets 里面查找该文件。
  • 如果用户提供的目录不是以 /assets/ 开头,一律认为是在绝对路径里查找该文件。
loopback
  • true:只有本地可以听到混音或替换后的音频流
  • false:本地和对方都可以听到混音或替换后的音频流
replace
  • true:只推动设置的本地音频文件或者线上音频文件,不传输麦克风收录的音频
  • false:音频文件内容将会和麦克风采集的音频流进行混音
cycle音频文件循环播放的次数:
  • 正整数:循环的次数。
  • -1:无限循环。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。
    • WARN_AUDIO_MIXING_OPEN_ERROR (701): 如果指定播放的音频文件不存在,或打开在线文件流后 5 秒内未收到网络流的数据包,则 SDK 会认为媒体文件不可访问,并返回该警告。

◆ stopAudioMixing()

abstract int io.agora.rtc.RtcEngine.stopAudioMixing ( )
abstract

停止播放音乐文件及混音。

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

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

◆ pauseAudioMixing()

abstract int io.agora.rtc.RtcEngine.pauseAudioMixing ( )
abstract

暂停播放音乐文件及混音。

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

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

◆ resumeAudioMixing()

abstract int io.agora.rtc.RtcEngine.resumeAudioMixing ( )
abstract

恢复播放音乐文件及混音。

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

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

◆ adjustAudioMixingVolume()

abstract int io.agora.rtc.RtcEngine.adjustAudioMixingVolume ( int  volume)
abstract

调节音乐文件的播放音量。

该方法调节混音里伴奏在本端和远端播放的音量大小。请在频道内调用该方法。

注解
调用该方法不影响调用 playEffect 播放音效文件的音量。
参数
volume伴奏音量范围为 0~100。默认 100 为原始文件音量。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ adjustAudioMixingPlayoutVolume()

abstract int io.agora.rtc.RtcEngine.adjustAudioMixingPlayoutVolume ( int  volume)
abstract

调节音乐文件的本地播放音量。

自从
v2.3.2。

该方法调节混音里音乐文件在本端播放的音量大小。请在频道内调用该方法。

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

◆ adjustAudioMixingPublishVolume()

abstract int io.agora.rtc.RtcEngine.adjustAudioMixingPublishVolume ( int  volume)
abstract

调节音乐文件的远端播放音量。

自从
v2.3.2。

该方法调节混音里音乐文件在远端播放的音量大小。请在频道内调用该方法。

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

◆ getAudioMixingPlayoutVolume()

abstract int io.agora.rtc.RtcEngine.getAudioMixingPlayoutVolume ( )
abstract

获取音乐文件的本地播放音量。

自从
v2.4.1。

该方法获取音乐文件的本地播放音量。该接口可以方便开发者排查音量相关问题。

返回
  • 方法调用成功则返回音量值,范围为 [0, 100]。
  • < 0:方法调用失败。

◆ getAudioMixingPublishVolume()

abstract int io.agora.rtc.RtcEngine.getAudioMixingPublishVolume ( )
abstract

获取音乐文件的远端播放音量。

自从
v2.4.1。

该方法获取音乐文件的远端播放音量。该接口可以方便开发者排查音量相关问题。

返回
  • 方法调用成功则返回音量值,范围为 [0, 100]。
  • < 0:方法调用失败。

◆ getAudioMixingDuration()

abstract int io.agora.rtc.RtcEngine.getAudioMixingDuration ( )
abstract

获取音乐文件的时长。

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

返回
  • 方法调用成功,并返回伴奏时长。
  • < 0:方法调用失败。

◆ getAudioMixingCurrentPosition()

abstract int io.agora.rtc.RtcEngine.getAudioMixingCurrentPosition ( )
abstract

获取音乐文件的播放进度。

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

返回
  • 方法调用成功并返回伴奏播放进度。
  • < 0:方法调用失败。

◆ setAudioMixingPosition()

abstract int io.agora.rtc.RtcEngine.setAudioMixingPosition ( int  pos)
abstract

设置音乐文件的播放位置。

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

参数
pos整数。进度条位置,单位为毫秒。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setAudioMixingPitch()

abstract int io.agora.rtc.RtcEngine.setAudioMixingPitch ( int  pitch)
abstract

调整本地播放的音乐文件的音调。

自从
3.0.1

本地人声和播放的音乐文件混音时,调用该方法可以仅调节音乐文件的音调。

注解
该方法需在 startAudioMixing 后调用。
参数
pitch按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ getAudioEffectManager()

abstract IAudioEffectManager io.agora.rtc.RtcEngine.getAudioEffectManager ( )
abstract

获取 IAudioEffectManager 类,以管理音效文件。

返回
IAudioEffectManager

◆ startAudioRecording() [1/2]

abstract int io.agora.rtc.RtcEngine.startAudioRecording ( String  filePath,
int  quality 
)
abstract

开始客户端录音。

弃用:
从 v2.9.1 起废弃。请改用 startAudioRecording2。

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

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

该方法的录制采样率固定为 32 kHz。

该接口需在加入频道之后调用。如果调用 leaveChannel 时还在录音,录音会自动停止。

参数
filePath录音文件的本地保存路径,由用户自行指定,需精确到文件名及格式,例如:/sdcard/emulated/0/audio.aac。请确保目录存在且可写。
quality录音音质:
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ startAudioRecording() [2/2]

abstract int io.agora.rtc.RtcEngine.startAudioRecording ( String  filePath,
int  sampleRate,
int  quality 
)
abstract

开始客户端录音。

自从
v2.9.1。

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

  • .wav:文件大,音质保真度较高。
  • .aac:文件小,音质保真度较低。
注解
  • 请确保你在该方法中指定的路径存在并且可写。
  • 该接口需要在 joinChannel 之后调用。如果调用 leaveChannel 时还在录音,录音会自动停止。
  • 为保证录音效果,当 sampleRate 设为 44.1 kHz 或 48 kHz 时,建议将 quality 设为 AUDIO_RECORDING_QUALITY_MEDIUM 或 AUDIO_RECORDING_QUALITY_HIGH。
参数
filePath录音文件在本地保存的绝对路径,由用户自行制定,需精确到文件名及格式,例如:/dir1/dir2/dir3/audio.aac。
sampleRate录音采样率 (Hz),可以设置为以下值:
  • 16000
  • (默认)32000
  • 44100
  • 48000
quality录音音质:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ stopAudioRecording()

abstract int io.agora.rtc.RtcEngine.stopAudioRecording ( )
abstract

停止客户端录音。

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

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

◆ startEchoTest() [1/2]

abstract int io.agora.rtc.RtcEngine.startEchoTest ( )
abstract

开始语音通话回路测试。

弃用:
从 v2.4.0 起废弃。声网建议使用 startEchoTest 方法开始语音回路测试。 该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,在 10 秒后,声音会回放出来。如果 10 秒后用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。
注解
  • 调用 startEchoTest 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,或者调用 joinchannel 进行通话。
  • 直播场景下,该方法仅能由用户角色为主播的用户调用。如果用户由通信场景切换到直播场景,请务必调用 setClientRole 方法将用户角色设置为主播后再调用该方法。
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ startEchoTest() [2/2]

abstract int io.agora.rtc.RtcEngine.startEchoTest ( int  intervalInSeconds)
abstract

开始语音通话回路测试。

自从
v2.4.0。

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

注解
  • 请在加入频道前调用该方法。
  • 调用 startEchoTest 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法调用 joinchannel 加入频道。
  • 直播场景下,该方法仅能由用户角色为主播的用户调用。
参数
intervalInSeconds设置返回语音通话回路测试结果的时间间隔,取值范围为 [2, 10],单位为秒,默认为 10 秒。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ stopEchoTest()

abstract int io.agora.rtc.RtcEngine.stopEchoTest ( )
abstract

停止语音通话回路测试。

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

◆ enableLastmileTest()

abstract int io.agora.rtc.RtcEngine.enableLastmileTest ( )
abstract

启用网络测试。

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

  • 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
  • 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。 无论哪种场景,启用该方法会消耗一定的网络流量,影响通话质量。在收到 onLastmileQuality 回调后须调用 disableLastmileTest 停止测试,再加入频道或切换用户角色。
注解
  • 该方法请勿与 startLastmileProbeTest 同时使用。
    • 调用该方法后,在收到 onLastmileQuality 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此回调无法执行。
    • 直播场景下,主播在加入频道后,请勿调用该方法。
    • 加入频道前调用该方法检测网络质量后,SDK 会占用一路视频的带宽,码率与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后,无论是否调用了 disableLastmileTest,SDK 均会自动停止带宽占用。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ disableLastmileTest()

abstract int io.agora.rtc.RtcEngine.disableLastmileTest ( )
abstract

关闭网络测试。

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

◆ startLastmileProbeTest()

abstract int io.agora.rtc.RtcEngine.startLastmileProbeTest ( LastmileProbeConfig  config)
abstract

开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。

自从
v2.4.0。

启用该方法后,SDK 会依次返回如下 2 个回调:

  • onLastmileQuality:视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
  • onLastmileProbeResult:视网络情况约 30 秒内返回。该回调通过客观数据反馈上下行网络质量,因此更客观。

该方法主要用于以下两种场景:

  • 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
  • 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
注解
  • 该方法会消耗一定的网络流量,影响通话质量,因此我们建议不要同时使用该方法和 enableLastmileTest
  • 调用该方法后,在收到 onLastmileQualityonLastmileProbeResult 回调之前请不用调用其他方法, 否则可能会由于 API 操作过于频繁导致此方法无法执行。
  • 直播场景下,如果本地用户为主播,请勿在加入频道后调用该方法。
参数
configLast-mile 网络探测配置,详细定义见 LastmileProbeConfig
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ stopLastmileProbeTest()

abstract int io.agora.rtc.RtcEngine.stopLastmileProbeTest ( )
abstract

停止通话前网络质量探测。

自从
v2.4.0。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setVideoSource()

abstract int io.agora.rtc.RtcEngine.setVideoSource ( IVideoSource  source)
abstract

设置自定义的视频源。

实时通信过程中,Agora SDK 会启动默认的视频输入设备,即内置的摄像头,采集视频。但是,如果你需要自定义视频输入设备,你可以先通过 IVideoSource 类自定义视频源,再调用该方法将自定义的视频源加入到 SDK 中。

参数
source自定义的视频源。详细定义见 IVideoSource

◆ setLocalVideoRenderer()

abstract int io.agora.rtc.RtcEngine.setLocalVideoRenderer ( IVideoSink  render)
abstract

自定义本地视频渲染器。

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

参数
render自定义的本地视频渲染器。详细定义见 IVideoSink

◆ setRemoteVideoRenderer()

abstract int io.agora.rtc.RtcEngine.setRemoteVideoRenderer ( int  uid,
IVideoSink  render 
)
abstract

自定义远端视频渲染器。

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

参数
uid远端用户 ID
render自定义的远端视频渲染器。详细定义见 IVideoSink

◆ setExternalAudioSink()

abstract int io.agora.rtc.RtcEngine.setExternalAudioSink ( boolean  enabled,
int  sampleRate,
int  channels 
)
abstract

设置外部音频渲染。

自从
v2.9.0。

该方法适用于需要自行渲染音频的场景。开启外部音频渲染后,你可以通过调用 pullPlaybackAudioFrame 方法拉取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染,获取想要的音频效果。

注解
开启外部音频渲染后,App 会无法从 c 回调中获得数据。
参数
enabled设置是否开启外部音频渲染:
  • true:开启外部音频渲染
  • false:(默认)关闭外部音频渲染
sampleRate外部音频渲染的采样率 (Hz),可设置为 16000,32000,44100 或 48000。
channels外部音频渲染的声道数,可设置为 1 或 2:
  • 1:单声道
  • 2:双声道
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ pullPlaybackAudioFrame()

abstract int io.agora.rtc.RtcEngine.pullPlaybackAudioFrame ( byte []  data,
int  lengthInByte 
)
abstract

拉取外部音频数据。

自从
v2.9.0。

使用该方法前,你需要调用 setExternalAudioSink(enabled: true) 方法通知 App 开启并设置外部渲染。

调用该方法后,app 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。

注解
  • 使用该方法后,app 会无法从 onPlaybackFrame 回调中获得数据。
  • 该方法和 onPlaybackFrame 回调相比,区别在于:
    • onPlaybackFrame:SDK 通过该回调将音频数据传输给 app。如果 app 处理延时,可能会导致音频播放抖动。
    • pullPlaybackAudioFrame:app 主动拉取音频数据。通过设置音频数据,SDK 可以调整缓存,帮助 app 处理延时,从而有效避免音频播放抖动。
参数
data需要拉取的音频数据,格式为 byte[]。
lengthInByte待拉取音频数据的字节数,单位为 byte。该参数的取值与音频数据的时长、你在 setExternalAudioSink 中设置的 sampleRatechannels 参数相关。Agora 建议音频数据的时长至少为 10 毫秒。计算公式为:
lengthInByte = sampleRate/1000 × 2 × channels × 音频数据时长(毫秒)。
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ setExternalAudioSource()

abstract int io.agora.rtc.RtcEngine.setExternalAudioSource ( boolean  enabled,
int  sampleRate,
int  channels 
)
abstract

设置外部音频采集参数。

注解
请在 joinChannel 前调用该方法。
参数
enabled是否开启外部音频采集。
  • true: 开启外部音频采集。
  • false: (默认)关闭外部音频采集。
sampleRate外部音频源的采样率(Hz),可设置为 8000,16000,32000,44100 或 48000。
channels外部音频源的通道数,可设置为:
  • 1: 单声道。
  • 2: 双声道。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ pushExternalAudioFrame()

abstract int io.agora.rtc.RtcEngine.pushExternalAudioFrame ( byte []  data,
long  timestamp 
)
abstract

推送外部音频帧。

参数
data外部音频数据
timestamp外部音频帧的时间戳。该参数为必填。你可以使用该时间戳还原音频帧顺序;在有视频的场景中(包含使用外部视频源的场景),该参数可以帮助音视频同步
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setExternalVideoSource()

abstract void io.agora.rtc.RtcEngine.setExternalVideoSource ( boolean  enable,
boolean  useTexture,
boolean  pushMode 
)
abstract

配置外部视频源。

参数
enable是否使用外部视频源:
  • true:使用外部视频源
  • false:不使用外部视频源(默认)
useTexture是否使用 Texture 作为输入:
  • true:使用 texture 作为输入
  • false:不使用 texture 作为输入
pushMode是否外部视频源需要调用 PushExternalVideoFrame 将视频帧主动推送给 Agora SDK:
  • true:使用推送(push)模式
  • false:使用拉取(pull)模式(暂不支持)

◆ pushExternalVideoFrame()

abstract boolean io.agora.rtc.RtcEngine.pushExternalVideoFrame ( AgoraVideoFrame  frame)
abstract

推送外部视频帧。

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

参数
frame视频帧的数据信息。详细定义见 Agora Video Frame
返回
  • true:该帧推送成功
  • false:该帧推送不成功

◆ isTextureEncodeSupported()

abstract boolean io.agora.rtc.RtcEngine.isTextureEncodeSupported ( )
abstract

检查视频是否支持 Texture 编码。

返回
  • true:支持 Texture 编码
  • false:不支持 Texture 编码

◆ registerAudioFrameObserver()

abstract int io.agora.rtc.RtcEngine.registerAudioFrameObserver ( IAudioFrameObserver  observer)
abstract

注册语音观测器对象。

该方法用于注册语音观测器对象,即注册回调。当需要 SDK 给出 onRecordFrameonPlaybackFrame 回调时,需要使用该方法注册回调。

参数
observer接口对象实例:IAudioFrameObserver。传入 null 表示取消注册。我们建议在收到 onLeaveChannel 后调用,来释放语音观测器对象。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setRecordingAudioFrameParameters()

abstract int io.agora.rtc.RtcEngine.setRecordingAudioFrameParameters ( int  sampleRate,
int  channel,
int  mode,
int  samplesPerCall 
)
abstract

设置录制的声音格式。

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

注解
SDK 会通过该方法中的 samplesPerCallsampleRatechannel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。 请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 onRecordFrame 回调。
参数
sampleRateonRecordFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000。
channelonRecordFrame 中返回数据的通道数,可设置为:
  • 1: 单声道。
  • 2: 双声道。
modeonRecordFrame 的使用模式:
  • 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 进行编码传输。例如,如用户自己有音效处理模块,且想要根据实际需要对数据进行前处理 (例如变声),则可以选择该模式。
samplesPerCallonRecordFrame 中返回数据的采样点数,如 RTMP 推流应用中通常为 1024。
返回
  • 0:方法调用成功。
  • < 0:方法调用失败。

◆ setPlaybackAudioFrameParameters()

abstract int io.agora.rtc.RtcEngine.setPlaybackAudioFrameParameters ( int  sampleRate,
int  channel,
int  mode,
int  samplesPerCall 
)
abstract

设置播放的声音格式。

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

注解
SDK 会通过该方法中的 samplesPerCallsampleRatechannel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。 请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 onPlaybackFrame 回调。
参数
sampleRateonPlaybackFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000。
channelonPlaybackFrame 中返回数据的通道数,可设置为:
  • 1: 单声道。
  • 2: 双声道。
modeonPlaybackFrame 的使用模式:
  • 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 获取数据、修改。例如,如果用户自己有音效处理模块,且想要根据实际需要对数据进行后处理 (例如变声),则可以选择该模式。
samplesPerCallonPlaybackFrame 中返回数据的采样点数,如 RTMP 推流应用中通常为 1024。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setMixedAudioFrameParameters()

abstract int io.agora.rtc.RtcEngine.setMixedAudioFrameParameters ( int  sampleRate,
int  samplesPerCall 
)
abstract

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

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

注解
SDK 会通过该方法中的 samplesPerCallsampleRate 和 AudioFrame 中的 channels 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channels)。 请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发onMixedAudioFrame 回调。
参数
sampleRate指定 onMixedAudioFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000
samplesPerCall指定 onMixedAudioFrame 中返回数据的采样点数,如 RTMP 推流应用中通常为 1024。
返回
  • 0:方法调用成功。
  • < 0:方法调用失败。

◆ addVideoWatermark() [1/2]

abstract int io.agora.rtc.RtcEngine.addVideoWatermark ( AgoraImage  watermark)
abstract

添加本地视频水印。

弃用:
从 v2.9.1 废弃。请改用 addVideoWatermark2。

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

注解
  • 在本地直播和旁路直播中,URL 的定义不同。本地直播中,URL 指本地直播视频上图片的本地绝对路径;旁路直播中,URL 指旁路直播视频上图片的地址。
  • 待添加图片的源文件格式必须是 PNG。如果待添加的 PNG 图片的尺寸与你该方法中设置的尺寸不一致,SDK 会对 PNG 图片进行裁剪,以与设置相符。
  • Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
  • 如果你在 setVideoEncoderConfiguratio 方法中将 orientationMode 设置为 ADAPTIVE 模式,则如果视频帧在播放端发生旋转,水印也会以其左上角为坐标原点,跟着视频帧旋转。
参数
watermark待添加在本地直播推流中的水印图片,详细定义见 Agora Image
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ addVideoWatermark() [2/2]

abstract int io.agora.rtc.RtcEngine.addVideoWatermark ( String  watermarkUrl,
WatermarkOptions  options 
)
abstract

添加本地视频水印。

自从
v2.9.1。

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的观众、旁路直播观众和录制设备都能看到或采集到该水印图片。 Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。

水印坐标和 setVideoEncoderConfiguration 方法中的设置有依赖关系:

  • 如果视频编码方向/ORIENTATION_MODE 固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
  • 如果视频编码方向/ORIENTATION_MODE 固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
  • 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸,否则超出部分将被裁剪。
注解
  • 你需要在调用 enableVideo 方法之后再调用本方法。
  • 如果你只是在旁路直播(推流到CDN)中添加水印,你可以使用本方法或 setLiveTranscoding 方法设置水印。
  • 待添加图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
  • 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
  • 如果你已经使用 startPreview 方法开启本地视频预览,那么本方法的 visibleInPreview 可设置水印在预览时是否可见。
  • 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,Agora 建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
watermarkUrl待添加的水印图片的本地路径。本方法支持从本地路径和 assets 路径添加水印图片。如果使用 assets 路径,需要以 /assets/ 开头。
options待添加的水印图片的设置选项。详见 Watermark Options
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ clearVideoWatermarks()

abstract int io.agora.rtc.RtcEngine.clearVideoWatermarks ( )
abstract

删除本地视频水印。 该方法删除使用 addVideoWatermark 方法添加的本地视频水印。

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

◆ setRemoteUserPriority()

abstract int io.agora.rtc.RtcEngine.setRemoteUserPriority ( int  uid,
int  userPriority 
)
abstract

设置用户媒体流优先级。

自从
v2.4.0。

如果将某个用户的优先级设为高,那么发给这个用户的音视频流的优先级就会高于其他用户。 弱网下 SDK 会优先保证高优先级用户收到的流的质量。

注解
目前 Agora SDK 仅允许将一名远端用户设为高优先级。
参数
uid远端用户的 ID
userPriority远端用户的优先级:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setLocalPublishFallbackOption()

abstract int io.agora.rtc.RtcEngine.setLocalPublishFallbackOption ( int  option)
abstract

设置弱网条件下发布的音视频流回退选项。

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

参数
option本地推流回退处理选项:
注解
旁路推流场景下,设置本地推流回退为 Audio-only 可能会导致远端的 CDN 用户听到声音的时间有所延迟。因此在有旁路推流的场景下,Agora 建议不开启该功能。
返回
  • 0:方法调用成功
  • <0:方法调用失败

◆ setRemoteSubscribeFallbackOption()

abstract int io.agora.rtc.RtcEngine.setRemoteSubscribeFallbackOption ( int  option)
abstract

设置弱网条件下订阅的音视频流回退选项。

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

参数
option远端订阅流回退处理选项:
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ enableDualStreamMode()

abstract int io.agora.rtc.RtcEngine.enableDualStreamMode ( boolean  enabled)
abstract

开/关视频双流模式。

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

参数
enabled指定双流或者单流模式:
  • true: 双流。
  • false: (默认)单流。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setRemoteVideoStreamType()

abstract int io.agora.rtc.RtcEngine.setRemoteVideoStreamType ( int  uid,
int  streamType 
)
abstract

设置订阅的视频流类型。

在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode(false) 关闭双流模式,接收端可以选择接收大流还是小流。其中,大流可以接为高分辨率高码率的视频流, 小流则是低分辨率低码率的视频流。

正常情况下,用户默认接收大流。如需节约带宽和计算资源,则可以调用该方法动态调整对应远端视频流的大小。 SDK 会根据该方法中的设置,切换大小流。

视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 onApiCallExecuted 中返回。

参数
uid用户 ID
streamType视频流类型:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setRemoteDefaultVideoStreamType()

abstract int io.agora.rtc.RtcEngine.setRemoteDefaultVideoStreamType ( int  streamType)
abstract

设置默认订阅的视频流类型。

参数
streamType视频流类型:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setEncryptionSecret()

abstract int io.agora.rtc.RtcEngine.setEncryptionSecret ( String  secret)
abstract

启用内置加密,并设置数据加密密码。

弃用:
自 v3.1.0 起废弃。请改用 enableEncryption

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

注解
  • 为保证最佳传输效果,请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
  • 请勿在转码推流场景中使用该方法。
参数
secret加密密码。
返回
  • 0:方法调用成功。
  • < 0:方法调用失败。

◆ setEncryptionMode()

abstract int io.agora.rtc.RtcEngine.setEncryptionMode ( String  encryptionMode)
abstract

设置内置的加密方案。

弃用:
自 v3.1.0 起废弃。请改用 enableEncryption

Agora SDK 支持内置加密功能,默认使用 AES-128-XTS 加密方式。如需使用其他加密方式,可以调用该 API 设置。 同一频道内的所有用户必须设置相同的加密方式和密码才能进行通话。关于这几种加密方式的区别,请参考 AES 加密算法的相关资料。

注解
在调用本方法前,请先调用 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: 方法调用失败。

◆ enableEncryption()

abstract int io.agora.rtc.RtcEngine.enableEncryption ( boolean  enabled,
EncryptionConfig  config 
)
abstract

开启或关闭内置加密。

自从
v3.1.0。

在安全要求较高的场景下,Agora 建议你在加入频道前,调用 enableEncryption 方法开启内置加密。

同一频道内所有用户必须使用相同的加密模式和密钥。一旦所有用户都离开频道,该频道的加密密钥会自动清除。

注解
  • 如果开启了内置加密,则不能使用 RTMP 推流功能。
  • Agora 支持 4 种加密模式。除 SM4_128_ECB 模式外,其他加密模式都需要在集成 SDK 时,额外添加加密库文件。详见《媒体流加密》。
参数
enabled是否开启内置加密:
  • true: 开启内置加密。
  • false: 关闭内置加密。
config配置内置加密模式和密钥。详见 EncryptionConfig
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。
    • -2(ERR_INVALID_ARGUMENT): 调用了无效的参数。需重新指定参数。
    • -7(ERR_NOT_INITIALIZED: SDK 尚未初始化。需在调用 API 之前已创建 IRtcEngine 对象并完成初始化。
    • -4(ERR_NOT_SUPPORTED): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。

◆ addInjectStreamUrl()

abstract int io.agora.rtc.RtcEngine.addInjectStreamUrl ( String  url,
LiveInjectStreamConfig  config 
)
abstract

输入在线媒体流。 该方法通过在服务端拉取视频流并发送到频道中,将正在播出的视频输入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。

调用该方法后,SDK 会在本地触发 onStreamInjectedStatus 回调,报告输入在线媒体流的状态; 成功输入媒体流后,该音视频流会出现在频道中,频道内所有用户都会收到 onUserJoined 回调,其中 uid 为 666。

注解
  • 调用该方法前,请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
  • 该方法仅适用于直播场景中的主播用户。
  • 频道内同一时间只允许输入一个在线媒体流。
参数
url添加到直播中的视频流 URL 地址,支持 RTMP,HLS,HTTP-FLV 协议传输。
  • 支持的音频编码格式:AAC
  • 支持的视频编码格式:H264 (AVC)
config外部输入的音视频流的配置,详细定义见 Live Inject Stream Configuration
返回

◆ removeInjectStreamUrl()

abstract int io.agora.rtc.RtcEngine.removeInjectStreamUrl ( String  url)
abstract

删除输入的在线媒体流。

成功删除后,会触发 onUserOffline 回调,其中 uid 为 666。

参数
url已输入、待删除的外部视频流 URL 地址,格式为 HTTP 或 HTTPS
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ addPublishStreamUrl()

abstract int io.agora.rtc.RtcEngine.addPublishStreamUrl ( String  url,
boolean  transcodingEnabled 
)
abstract

增加旁路推流地址。

调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告增加旁路推流地址的状态。

参数
urlCDN 推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。url 不支持中文等特殊字符。
transcodingEnabled是否转码。如果设为 true,则需要在该方法前先调用 setLiveTranscoding 方法。
  • true:转码。转码是指在旁路推流时对音视频流进行转码处理后,再推送到其他 RTMP 服务器。多适用于频道内有多个主播,需要进行混流、合图的场景。
  • false:不转码。
注解
  • 调用该方法前,请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
  • 该方法仅适用直播场景。
  • 请确保在成功加入频道后才能调用该接口。
  • 该方法每次只能增加一路旁路推流地址。如需推送多路流,则需多次调用该方法。
返回

◆ removePublishStreamUrl()

abstract int io.agora.rtc.RtcEngine.removePublishStreamUrl ( String  url)
abstract

删除旁路推流地址。

调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告删除旁路推流地址的状态。

注解
  • 调用该方法前,请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
  • 该方法只适用于直播场景。
  • 该方法每次只能删除一路旁路推流地址。如需删除多路流,则需多次调用该方法。
参数
url待删除的推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。推流地址不支持中文等特殊字符。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setLiveTranscoding()

abstract int io.agora.rtc.RtcEngine.setLiveTranscoding ( LiveTranscoding  transcoding)
abstract

设置直播转码。

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码参数 LiveTranscoding 时,SDK 会触发 onTranscodingUpdated 回调。 首次调用该方法设置转码参数时,不会触发 onTranscodingUpdated 回调。

注解
  • 请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
  • 该方法仅适用于直播场景下的主播用户。
  • 请确保先调用过该方法,再调用 addPublishStreamUrl
参数
transcoding旁路推流布局相关设置,详细定义见 LiveTranscoding
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ createDataStream()

abstract int io.agora.rtc.RtcEngine.createDataStream ( boolean  reliable,
boolean  ordered 
)
abstract

创建数据流。

该方法用于创建数据流。RtcEngine 生命周期内,每个用户最多只能创建 5 个数据流。频道内数据通道最多允许数据延迟 5 秒,若超过 5 秒接收方尚未收到数据流,则数据通道会向 App 报错。

参数
reliable是否可靠。
  • true: 接收方 5 秒内会收到发送方所发送的数据,否则会收到 onStreamMessageError 回调并获得相应报错信息。
  • false: 接收方不保证收到,就算数据丢失也不会报错。
ordered是否有序。
  • true: 接收方会按照发送方发送的顺序收到数据包。
  • false: 接收方不保证按照发送方发送的顺序收到数据包。
返回
  • 创建数据流成功则返回数据流 ID。
  • < 0:创建数据流失败。如果返回的错误码是负数,对应错误代码和警告代码里的正整数。例如返回的错误码为 -2,则对应错误代码和警告代码里的 2:ERR_INVALID_ARGUMENT(-2)

◆ sendStreamMessage()

abstract int io.agora.rtc.RtcEngine.sendStreamMessage ( int  streamId,
byte []  message 
)
abstract

发送数据流。

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制:频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。

成功调用该方法后,远端会触发 onStreamMessage 回调,远端用户可以在该回调中获取接收到的流消息;若调用失败,远端会触发 onStreamMessageError 回调。

注解
  • 请确保在调用该方法前,已调用 createDataStream 创建了数据通道。
  • 该方法仅适用于通信场景以及直播场景下的主播用户。
参数
streamId数据流 ID,createDataStream 的返回值。
message待发送的数据。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setVideoQualityParameters()

abstract int io.agora.rtc.RtcEngine.setVideoQualityParameters ( boolean  preferFrameRateOverImageQuality)
abstract

设置视频优化选项(仅适用于直播)。

弃用:
从 v2.4.0 起废弃。声网建议使用 VideoEncoderConfiguration 类中的 degradationPrefer 参数设置视频质量偏好。 该方法允许用户设置视频的优化选项。
参数
preferFrameRateOverImageQuality支持两种优化选项:
  • true: 画质和流畅度里,优先保证流畅度。
  • false:(默认)画质和流畅度里,优先保证画质。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ getRecommendedEncoderType()

static int io.agora.rtc.RtcEngine.getRecommendedEncoderType ( )
static

获取推荐的编码器类型。

弃用:
该方法已废弃。我们不建议使用。
返回
编码器类型:

◆ setLocalVideoMirrorMode()

abstract int io.agora.rtc.RtcEngine.setLocalVideoMirrorMode ( int  mode)
abstract

设置本地视频镜像。

弃用:
从 v3.0.0 起废弃。请改用 setupLocalVideosetLocalRenderMode
注解
请在调用 setupLocalVideo 方法初始化本地视图后调用该方法。
参数
mode本地视频镜像模式:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ switchCamera()

abstract int io.agora.rtc.RtcEngine.switchCamera ( )
abstract

切换前置/后置摄像头。

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

◆ isCameraZoomSupported()

abstract boolean io.agora.rtc.RtcEngine.isCameraZoomSupported ( )
abstract

检测设备是否支持摄像头缩放功能。

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

◆ isCameraTorchSupported()

abstract boolean io.agora.rtc.RtcEngine.isCameraTorchSupported ( )
abstract

检测设备是否支持闪光灯常开。

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

◆ isCameraFocusSupported()

abstract boolean io.agora.rtc.RtcEngine.isCameraFocusSupported ( )
abstract

检测设备是否支持手动对焦功能。

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

◆ isCameraExposurePositionSupported()

abstract boolean io.agora.rtc.RtcEngine.isCameraExposurePositionSupported ( )
abstract

检测设备是否支持手动曝光功能。

自从
v2.3.2。
返回
  • true:设置支持手动曝光功能
  • false:设备不支持手动曝光功能

◆ isCameraAutoFocusFaceModeSupported()

abstract boolean io.agora.rtc.RtcEngine.isCameraAutoFocusFaceModeSupported ( )
abstract

检测设备是否支持人脸对焦功能。

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

◆ setCameraZoomFactor()

abstract int io.agora.rtc.RtcEngine.setCameraZoomFactor ( float  factor)
abstract

设置摄像头缩放比例。

参数
factor相机缩放比例,有效范围从 1.0 到最大缩放
返回
  • 方法调用成功:返回设置的 Factor 值
  • 方法调用失败:返回值 < 0

◆ getCameraMaxZoomFactor()

abstract float io.agora.rtc.RtcEngine.getCameraMaxZoomFactor ( )
abstract

获取摄像头支持最大缩放比例。

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

◆ setCameraFocusPositionInPreview()

abstract int io.agora.rtc.RtcEngine.setCameraFocusPositionInPreview ( float  positionX,
float  positionY 
)
abstract

设置手动对焦位置,并触发对焦。

成功调用该方法后,本地会触发 onCameraFocusAreaChanged 回调。

参数
positionX触摸点相对于视图的横坐标
positionY触摸点相对于视图的纵坐标
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ setCameraExposurePosition()

abstract int io.agora.rtc.RtcEngine.setCameraExposurePosition ( float  positionXinView,
float  positionYinView 
)
abstract

设置手动曝光位置。

成功调用该方法后,本地会触发 onCameraExposureAreaChanged 回调。

自从
v2.3.2。
参数
positionXinView触摸点相对于视图的横坐标
positionYinView触摸点相对于视图的纵坐标
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ enableFaceDetection()

abstract int io.agora.rtc.RtcEngine.enableFaceDetection ( boolean  enable)
abstract

开启/关闭本地人脸检测。

自从
3.0.1

开启本地人脸检测后,SDK 会触发 onFacePositionChanged 回调向你报告人脸检测的信息:

  • 摄像头采集的画面大小。
  • 人脸在画面中的位置。
  • 人脸距设备屏幕的距离。
参数
enable是否开启人脸检测:
  • true: 开启人脸检测
  • false: (默认)关闭人脸检测
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ setCameraTorchOn()

abstract int io.agora.rtc.RtcEngine.setCameraTorchOn ( boolean  isOn)
abstract

设置是否打开闪光灯。

参数
isOn是否打开闪光灯
  • true:打开
  • false:关闭
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setCameraAutoFocusFaceModeEnabled()

abstract int io.agora.rtc.RtcEngine.setCameraAutoFocusFaceModeEnabled ( boolean  enabled)
abstract

设置是否开启人脸对焦功能。

参数
enabled是否开启人脸对焦:
  • true: 开启人脸对焦功能。
  • false: (默认)关闭人脸对焦功能。

◆ getCallId()

abstract String io.agora.rtc.RtcEngine.getCallId ( )
abstract

获取通话 ID。

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

返回
通话 ID。

◆ rate()

abstract int io.agora.rtc.RtcEngine.rate ( String  callId,
int  rating,
String  description 
)
abstract

给通话评分。

参数
callId通过 getCallId 函数获取的通话 ID
rating给通话的评分,最低 1 分,最高 5 分,如超过这个范围,SDK 会返回 ERR_INVALID_ARGUMENT(-2) 错误
description(非必选项)给通话的描述,可选,长度应小于 800 字节
返回

◆ complain()

abstract int io.agora.rtc.RtcEngine.complain ( String  callId,
String  description 
)
abstract

投诉通话质量。

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

参数
callId通话 getCallId 函数获取的通话 ID
description(非必选项)给通话的描述,可选,长度应小于 800 字节
返回

◆ getSdkVersion()

static String io.agora.rtc.RtcEngine.getSdkVersion ( )
static

查询 SDK 版本号。

返回
当前的 SDK 版本号,格式为字符串,如 2.3.0。

◆ getMediaEngineVersion()

static String io.agora.rtc.RtcEngine.getMediaEngineVersion ( )
static

返回媒体引擎版本号。

弃用:
该方法已废弃。声网不建议你使用。
返回
char 格式的版本号字符串

◆ setLogFile()

abstract int io.agora.rtc.RtcEngine.setLogFile ( String  filePath)
abstract

设置 Agora SDK 输出的日志文件。

默认情况下,SDK 会生成 agorasdk.log、agorasdk_1.log、agorasdk_2.log、agorasdk_3.log、agorasdk_4.log 这 5 个日志文件。 每个文件的默认大小为 1024 KB。日志文件为 UTF-8 编码。最新的日志永远写在 agorasdk.log 中。agorasdk.log 写满后,SDK 会从 1-4 中删除修改时间最早的一个文件,然后将 agorasdk.log 重命名为该文件,并建立新的 agorasdk.log 写入最新的日志。

注解
如需调用本方法,请在调用 create 方法初始化 RtcEngine 对象后立即调用,否则可能造成输出日志不完整。
参见
setLogFileSize
setLogFilter
参数
filePath日志文件的完整路径。默认路径为 /storage/emulated/0/Android/data/<package name>/files/agorasdk.log。请确保指定的目录存在而且可写。你可通过该参数修改日志文件名。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setLogFilter()

abstract int io.agora.rtc.RtcEngine.setLogFilter ( int  filter)
abstract

设置日志输出等级。

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

日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。选择一个级别,你就可以看到在该级别之前所有级别的日志信息。 例如,你选择 WARNING 级别,就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。

参见
setLogFile
setLogFileSize
参数
filter日志输出等级。按照输出日志最全到最少排列:
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ setLogFileSize()

abstract int io.agora.rtc.RtcEngine.setLogFileSize ( int  fileSizeInKBytes)
abstract

设置日志文件大小。

自从
v2.4.0。

设置 SDK 输出的日志文件大小,单位为 KB。

Agora SDK 设有 2 个日志文件,每个文件默认大小为 512 KB。如果你将 fileSizeInKByte 设置为 1024 KB,SDK 会最多输出 2 M 的日志文件。如果日志文件超出设置值,新的日志会覆盖之前的日志。

参见
setLogFile
setLogFilter
参数
fileSizeInKBytes单个日志文件的大小,单位为 KB。默认值为 1024 KB。如果你将 fileSizeInKByte 设为 1024 KB,SDK 会最多输出 5 MB 的日志文件。如果你将 fileSizeInKByte 设为小于 1024 KB,单个日志文件最大仍为 1024 KB。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败,有可能是因为传入的参数无效。

◆ getNativeHandle()

abstract long io.agora.rtc.RtcEngine.getNativeHandle ( )
abstract

返回 SDK 引擎的 Native 句柄。

该方法用于获取 SDK 引擎的 C++ 句柄并将其应用于包括注册音视频帧观察器的特殊场景。

返回
SDK 引擎的 Native 句柄。

◆ addHandler()

void io.agora.rtc.RtcEngine.addHandler ( IRtcEngineEventHandler  handler)

添加主回调事件。

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

参数
handlerIRtcEngineEventHandler

◆ removeHandler()

void io.agora.rtc.RtcEngine.removeHandler ( IRtcEngineEventHandler  handler)

删除指定的回调句柄。

自从
v2.9.1。

该方法删除指定的回调句柄。对于某些注册的回调句柄,如果你在收到相应回调事件后无需再次接收回调消息,可以调用该方法移除回调句柄。

参数
handler你想要删除的回调句柄。

◆ enableHighPerfWifiMode()

abstract boolean io.agora.rtc.RtcEngine.enableHighPerfWifiMode ( boolean  enable)
abstract

启用/关闭 WiFi 模式。

弃用:
该方法已废弃。声网不建议你使用。
参数
enable
  • true:启用 Wifi 模式
  • false:关闭 Wifi 模式
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ getErrorDescription()

static String io.agora.rtc.RtcEngine.getErrorDescription ( int  error)
static

获取错误码或警告码描述。

参数
errorWarning codeError code 中的详细错误码或警告码描述。
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ monitorHeadsetEvent()

abstract void io.agora.rtc.RtcEngine.monitorHeadsetEvent ( boolean  monitor)
abstract

是否监听外部头戴设备事件。

弃用:
该方法已废弃。声网不建议你使用。
参数
monitor
  • true:监听外部头戴设备事件
  • false:不监听外部头戴设备事件

◆ monitorBluetoothHeadsetEvent()

abstract void io.agora.rtc.RtcEngine.monitorBluetoothHeadsetEvent ( boolean  monitor)
abstract

是否监听蓝牙头戴设备事件。

弃用:
该方法已废弃。声网不建议你使用。
参数
monitor
  • true:监听蓝牙头戴设备事件
  • false:不监听蓝牙头戴设备事件

◆ setPreferHeadset()

abstract void io.agora.rtc.RtcEngine.setPreferHeadset ( boolean  enabled)
abstract

设置是否优先使用听筒。

弃用:
该方法已废弃。声网不建议你使用。
参数
enabled
  • true:优先使用听筒
  • false:不优先使用听筒

◆ setParameters()

abstract int io.agora.rtc.RtcEngine.setParameters ( String  parameters)
abstract

通过 JSON 配置 SDK 提供技术预览或特别定制功能。

JSON 选项默认不公开。声网工程师正在努力寻求以标准化方式公开 JSON 选项。

参数
parametersJSON 字符串形式的参数
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ getParameter()

abstract String io.agora.rtc.RtcEngine.getParameter ( String  parameter,
String  args 
)
abstract

获取 Agora SDK 可供自定义的参数。 该方法暂未公开,请联系声网支持 support@agora.io 获取详情。

◆ registerMediaMetadataObserver()

abstract int io.agora.rtc.RtcEngine.registerMediaMetadataObserver ( IMetadataObserver  observer,
int  type 
)
abstract

注册媒体 Metadata 观测器。

自从
v2.4.1。

你需要在该方法中实现一个 IMetadataObserver 类,并指定 Metadata 的数据类型。成功调用该方法后,SDK 会触发 getMaxMetadataSize 回调。

该接口通过在直播的视频帧中同步添加 Metadata,实现发送商品链接、分发优惠券、发送答题等功能,构建更为丰富的直播互动方式。

注解
  • 请在调用 joinChannel 加入频道前调用该方法。
  • 该方法仅适用于直播场景。
参数
observerIMetadataObserver 类。
typeMetadata 的数据类型,目前 SDK 仅支持视频类的 Metadata,即 VIDEO_METADATA(0)
返回
  • 0: 方法调用成功。
  • < 0: 方法调用失败。

◆ startChannelMediaRelay()

abstract int io.agora.rtc.RtcEngine.startChannelMediaRelay ( ChannelMediaRelayConfiguration  channelMediaRelayConfiguration)
abstract

开始跨频道媒体流转发。

自从
v2.9.0。

该方法可用于实现跨频道媒体流转发。

成功调用该方法后,SDK 会触发 onChannelMediaRelayStateChangedonChannelMediaRelayEvent 回调,并在回调中报告当前的跨频道媒体流转发状态和事件。

  • 如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_RUNNING(2) 和 RELAY_OK(0),且 onChannelMediaRelayEvent 回调报告 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL(4), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
  • 如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_FAILURE(3),则表示跨频道媒体流转发出现异常。
注解
  • 跨频道媒体流转发功能需要提交工单联系技术支持开通。
  • 该功能不支持 String 型 UID。
  • 请在成功加入频道后调用该方法。
  • 该方法仅适用于直播场景下的主播。
  • 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
参数
channelMediaRelayConfiguration跨频道媒体流转发参数配置:ChannelMediaRelayConfiguration
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ stopChannelMediaRelay()

abstract int io.agora.rtc.RtcEngine.stopChannelMediaRelay ( )
abstract

停止跨频道媒体流转发。

自从
v2.9.0。

一旦停止,主播会退出所有目标频道。

成功调用该方法后,SDK 会触发 onChannelMediaRelayStateChanged 回调。如果报告 RELAY_STATE_IDLE(0) 和 RELAY_OK(0),则表示已停止转发媒体流。

注解
如果该方法调用不成功,SDK 会触发 onChannelMediaRelayStateChanged 回调,并报告状态码 RELAY_ERROR_SERVER_NO_RESPONSE(2) 或 RELAY_ERROR_SERVER_CONNECTION_LOST(8)。你可以调用 leaveChannel 方法离开频道,跨频道媒体流转发会自动停止。
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ updateChannelMediaRelay()

abstract int io.agora.rtc.RtcEngine.updateChannelMediaRelay ( ChannelMediaRelayConfiguration  channelMediaRelayConfiguration)
abstract

更新媒体流转发的频道。

自从
v2.9.0。

成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。

成功调用该方法后,SDK 会触发 onChannelMediaRelayEvent 回调,并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL(7)。

注解
  • 请在 startChannelMediaRelay 方法后调用该方法,更新媒体流转发的频道。
  • 跨频道媒体流转发最多支持 4 个目标频道。如果直播间里已经有 4 个频道了,你可以在调用该方法之前,调用 ChannelMediaRelayConfiguration 类中的 removeDestChannelInfo 方法移除不需要的频道。
参数
channelMediaRelayConfiguration跨频道媒体流转发参数配置:ChannelMediaRelayConfiguration
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ createRtcChannel()

abstract RtcChannel io.agora.rtc.RtcEngine.createRtcChannel ( String  channelId)
abstract

创建并获取一个 RtcChannel 对象。

你可以多次调用该方法,创建多个 RtcChannel 对象,再调用各 RtcChannel 对象中的 joinChannel 方法,实现同时加入多频道。

加入多个频道后,你可以同时订阅各个频道的音、视频流;但是同一时间只能在一个频道发布一路音、视频流。

参数
channelId能标识频道的频道名,长度在 64 字节以内的字符。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z;
  • 26 个大写英语字母 A-Z;
  • 10 个数字 0-9;
  • 空格;
  • "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。
注解
  • 该参数没有默认值,请确保对参数设值。
  • 请勿将该参数设为空字符 "",否则 SDK 会返回 ERR_REFUSED(-5) 错误码。
返回
  • 方法调用成功,返回 RtcChannel 对象。
  • 方法调用失败,返回 null。
  • 如果将 channelId 设为空字符 "",则返回错误码 ERR_REFUSED(-5)。