AgoraRtcEngineKit
Agora RTC SDK 的基础接口类,实现实时音视频的主要功能。
AgoraRtcEngineKit 提供了 app 调用的主要方法。
addVideoWatermark [1/2]
添加本地视频水印。
- (int)addVideoWatermark:(AgoraImage * _Nonnull)watermark
- 弃用:
- 该方法已废弃,请使用 addVideoWatermark [2/2] 作为替代。
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户,旁路推流观众,甚至采集设备都能看到或采集到该水印图片。如果你仅仅希望在旁路直播推流中添加水印,请参考 setLiveTranscoding中描述的用法。
- 在本地直播和旁路推流中,URL 的定义不同。本地直播中,URL 指本地直播视频上图片的本地绝对/相对路径;旁路推流中,URL 指旁路推流视频上图片的地址。
- 待添加图片的源文件格式必须是 PNG。如果待添加的 PNG 图片的尺寸与你该方法中设置的尺寸不一致,SDK 会对 PNG 图片进行裁剪,以与设置相符。
- 声网当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
参数
- watermark
- 待添加在本地直播推流中的水印图片:AgoraImage。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
addVideoWatermark [2/2]
添加本地视频水印。
- (int)addVideoWatermark:(NSURL* _Nonnull)url options:(WatermarkOptions* _Nonnull)options;
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户、旁路直播观众和采集设备都能看到或采集到该水印图片。 Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
- 如果视频编码方向(AgoraVideoOutputOrientationMode)固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向(AgoraVideoOutputOrientationMode)固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸,否则超出部分将被裁剪。
- 你需要在调用 enableVideo 方法之后再调用该方法。
- 如果你只是在旁路推流时添加水印,你可以使用该方法或 setLiveTranscoding 方法设置水印。
- 待添加水印图片必须是 PNG 格式。该方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在该方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview [1/2] 方法开启本地视频预览,那么该方法的
visibleInPreview
可设置水印在预览时是否可见。 - 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,Agora 建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
- url
- 待添加的水印图片的本地路径。该方法支持从本地绝对/相对路径添加水印图片。
- options
- 待添加的水印图片的设置选项,详见 WatermarkOptions 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingPlayoutVolume
调节音乐文件在本地播放的音量。
- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume;
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
参数
- volume
- 音乐文件音量。取值范围为 [0,100],100 (默认值)为原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingPublishVolume
调节音乐文件远端播放音量。
- (int)adjustAudioMixingPublishVolume:(NSInteger)volume;
该方法调节混音音乐文件在远端的播放音量大小。
你需要在调用 startAudioMixing [2/2] 并收到 audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
参数
- volume
- 音乐文件音量。取值范围为 [0,100],100 (默认值)为原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingVolume
调节音乐文件的播放音量。
- (int)adjustAudioMixingVolume:(NSInteger)volume;
该方法调节混音音乐文件在本端和远端的播放音量大小。
- 该方法需要在 startAudioMixing [2/2] 后调用。
- 调用该方法不影响调用 playEffect [3/3] 播放音效文件的音量。
参数
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingPublishVolume
调节音乐文件远端播放音量。
- (int)adjustAudioMixingPublishVolume:(NSInteger)volume;
该方法调节混音音乐文件在远端的播放音量大小。
你需要在调用 startAudioMixing [2/2] 并收到 audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
参数
- volume
- 音乐文件音量。取值范围为 [0,100],100 (默认值)为原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustCustomAudioPublishVolume
调节自定义采集的外部音频源在远端播放的音量。
- (int)adjustCustomAudioPublishVolume:(NSInteger)sourceId volume:(NSInteger)volume;
调用该方法设置音频在远端播放的音量后,如果你想重新调整音量,你可以再次调用该方法。
参数
- sourceId
- 外部音频源的 ID。如果你要发布自定义的外部音频源,则将该参数设置为你想要发布的自定义音频轨道 ID。
- volume
- 自定义采集音频的播放音量,取值范围为 [0,100]。0 表示静音,100 表示原始音量。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
adjustPlaybackSignalVolume
调节本地播放的所有远端用户信号音量。
- (int)adjustPlaybackSignalVolume:(NSInteger)volume;
- 该方法调节的是本地播放的所有远端用户混音后的音量。
- 该方法在加入频道前后都能调用。
参数
- volume
-
音量,取值范围为 [0,400]。
- 0: 静音。
- 100: (默认)原始音量。
- 400: 原始音量的 4 倍,自带溢出保护。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustRecordingSignalVolume
调节音频采集信号音量。
- (int)adjustRecordingSignalVolume:(NSInteger)volume;
该方法在加入频道前后都能调用。
参数
- volume
-
音量,取值范围为 [0,400]。
- 0: 静音。
- 100: (默认)原始音量。
- 400: 原始音量的 4 倍,自带溢出保护。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustUserPlaybackSignalVolume
调节本地播放的指定远端用户信号音量。
- (int)adjustUserPlaybackSignalVolume:(NSUInteger)uid volume:(int)volume;
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
- 该方法需要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
- uid
- 远端用户 ID。
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
clearVideoWatermarks
删除已添加的视频水印。
- (int)clearVideoWatermarks;
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
complain
投诉通话质量。
- (int)complain:(NSString * _Nonnull)callId description:(NSString * _Nullable)description;
该方法允许用户就通话质量进行投诉。需要在离开频道后调用。
参数
- callId
- 通话 ID。你可以通过调用 getCallId 获取该参数。
- description
- (非必选项)通话的描述。长度应小于 800 字节。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2: 参数无效。
- -3:SDK 尚未准备好。可能的原因有:
- AgoraRtcEngineKit 初始化失败。请重新初始化 AgoraRtcEngineKit。
- 调用方法时用户尚未加入频道。请检查方法的调用逻辑。
- 调用 rate 或 complain 方法时用户尚未离开频道。请检查方法的调用逻辑。
- 请检查是否已开启音频模块。请检查程序集完整性。
configRhythmPlayer
配置虚拟节拍器。
- (int)configRhythmPlayer:(AgoraRhythmPlayerConfig * _Nullable)config;
调用 startRhythmPlayer 后,你可以调用该方法重新配置虚拟节拍器。
- 开启虚拟节拍器后,SDK 会从头开始播放指定的音频文件,并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如,将 beatsPerMinute 设为
60
,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。 - 虚拟节拍器的声音默认会发布至远端,如果你不希望远端用户听到虚拟节拍器的声音,你可以将 AgoraRtcChannelMediaOptions 中的 publishRhythmPlayerTrack 设为
NO
。
参数
- config
- 节拍器配置。详见 AgoraRhythmPlayerConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
sharedEngineWithAppId
创建并初始化 AgoraRtcEngineKit。
+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString * _Nonnull)appId delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate;
AgoraRtcEngineKit 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。
- 请确保在调用其他 API 前先调用该方法创建并初始化 AgoraRtcEngineKit。
- 调用该方法和 sharedEngineWithConfig 均能创建 AgoraRtcEngineKit 实例。该方法与 sharedEngineWithConfig 的区别在于,sharedEngineWithConfig 支持在创建 AgoraRtcEngineKit 实例时进行更多配置,如指定访问区域、设置日志文件等。
- SDK 只支持每个 app 创建一个 AgoraRtcEngineKit 实例。
参数
- appId
- Agora 为 app 开发者签发的 App ID。 使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 AgoraRtcEngineKit。如需更换 App ID,必须先调用 destroy 销毁当前 AgoraRtcEngineKit 再重新创建。
- delegate
- AgoraRtcEngineKit 的事件句柄,详见 AgoraRtcEngineDelegate。
返回值
- 方法调用成功,返回一个 AgoraRtcEngineKit 对象。
- 方法调用失败,返回错误码。
sharedEngineWithConfig
创建并初始化 AgoraRtcEngineKit。
+ (instancetype _Nonnull)sharedEngineWithConfig:(AgoraRtcEngineConfig * _Nonnull)config delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate;
AgoraRtcEngineKit 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。
- 请确保在调用其他 API 前先调用该方法创建并初始化 AgoraRtcEngineKit。
- 调用该方法和 sharedEngineWithAppId 均能创建 AgoraRtcEngineKit 实例。该方法与 sharedEngineWithAppId 的 区别在于,该方法支持在创建 AgoraRtcEngineKit 实例时进行更多配置,如指定访问区域、设置日志文件等。
- SDK 只支持每个 app 创建一个 AgoraRtcEngineKit 实例。
参数
- config
-
AgoraRtcEngineKit 实例的配置。详见 AgoraRtcEngineConfig。
- delegate
- AgoraRtcEngineKit 的事件句柄,详见 AgoraRtcEngineDelegate。
返回值
- 方法调用成功,返回一个 AgoraRtcEngineKit 对象。
- < 0: 方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 设置了无效的参数。
- -7: SDK 初始化失败。
- -22: 资源申请失败。当 app 占用资源过多,或系统资源耗尽时,SDK 分配资源失败,会返回该错误。
- -101: App ID 无效。
createDataStream [1/2]
创建数据流。
- (int)createDataStream:(NSInteger * _Nonnull)streamId reliable:(BOOL)reliable ordered:(BOOL)ordered;
在 AgoraRtcEngineKit 生命周期内,每个用户最多只能创建 5 个数据流。
- 该方法需要在加入频道后调用。
- 不可将 reliable 设为
YES
且将 ordered 设为YES
。
参数
- streamId
- 输出参数,数据流 ID。
- reliable
-
该数据流是否可靠:
YES
: 接收方 5 秒内会收到发送方所发送的数据,否则会收到 didOccurStreamMessageErrorFromUid 回调并获得相应报错信息。NO
: 接收方不保证收到,就算数据丢失也不会报错。
- ordered
-
该数据流是否有序:
YES
: 接收方会按照发送方发送的顺序收到数据包。NO
: 接收方不保证按照发送方发送的顺序收到数据包。
返回值
- 0: 创建数据流成功。
- < 0:方法调用失败。
createDataStream [2/2]
创建数据流。
- (int)createDataStream:(NSInteger * _Nonnull)streamId config:(AgoraDataStreamConfig * _Nonnull)config;
该方法用于创建数据流。每个用户在每个频道中最多只能创建 5 个数据流。
相比 createDataStream [1/2],该方法不支持数据可靠。接收方会丢弃超出发送时间 5 秒后的数据包。
参数
- streamId
- 输出参数,数据流 ID。
- config
- 数据流设置。详见 AgoraDataStreamConfig。
返回值
- 0: 创建数据流成功。
- < 0:方法调用失败。
createMediaPlayerWithDelegate
创建 AgoraRtcMediaPlayerProtocol 实例。
- (id<AgoraRtcMediaPlayerProtocol>_Nullable)createMediaPlayerWithDelegate: (id<AgoraRtcMediaPlayerDelegate>_Nullable)delegate;
参数
- delegate
- AgoraRtcEngineKit 的事件句柄,详见 AgoraRtcEngineDelegate。
返回值
- 方法调用成功:返回 AgoraRtcMediaPlayerProtocol 对象。
- 方法调用失败:返回空指针。
返回一个 AgoraRtcMediaPlayerProtocol 实例。
createCustomVideoTrack
创建一个自定义的视频轨道。
- (unsigned int)createCustomVideoTrack;
- 调用该方法创建视频轨道并获得视频轨道 ID。
- 在每个频道的 AgoraRtcChannelMediaOptions 中,将 customVideoTrackId 参数设置为你想要发布的视频轨道 ID,并将 publishCustomVideoTrack 设置为
YES
。 - 调用 pushExternalVideoFrame 将 videoTrackId 指定为你想要发布的自定义视频轨道 ID,即可实现在多个频道中发布对应的自定义视频源。
返回值
- 方法调用成功,返回视频轨道 ID 作为该视频轨道的唯一标识。
- 方法调用失败,返回负值。
destroyCustomVideoTrack
销毁指定的视频轨道。
- (int)destroyCustomVideoTrack:(NSUInteger)videoTrackId;
参数
- position
- 调用 createCustomVideoTrack 方法返回的视频轨道 ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
delegate
设置并获得 AgoraRtcEngineDelegate。
@property(nonatomic, weak) id<AgoraRtcEngineDelegate> _Nullable delegate;
SDK 通过 AgoraRtcEngineDelegate 类向 app 报告 SDK 运行时的各种事件。该类中定义的所有方法都是可选的实现方法。
destroy
销毁 AgoraRtcEngineKit 对象。
+ (void)destroy;
该方法释放 Agora SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信,不需要时则将资源释放出来用于其他操作, 该方法适用于此类情况。
调用该方法后,你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能,你必须依次重新调用 sharedEngineWithConfig 方法创建一个新的 AgoraRtcEngineKit 对象。
disableAudio
关闭音频模块。
- (int)disableAudio;
- 该方法设置内部引擎为禁用状态,在频道内和频道外均可调用。离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制音频模块:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
disableAudioSpectrumMonitor
关闭音频频谱监测。
- (int)disableAudioSpectrumMonitor;
调用 enableAudioSpectrumMonitor 后,如果你想关闭音频频谱监测,请调用该方法。
该方法在加入频道前后均可调用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
disableVideo
关闭视频模块。
- (int)disableVideo;
该方法用于关闭视频模块,可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频模式。 调用 enableVideo 方法可开启视频模式。
成功调用该方法后,远端会触发 didVideoEnabled (NO
) 回调。
- 该方法设置的是内部引擎为禁用状态,在离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制视频模块:
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAudio
启用音频模块。
- (int)enableAudio;
启用音频模块(默认为开启状态)。
- 该方法设置音频模块为启用状态,在频道内和频道外均可调用。在离开频道后仍然有效。
- 该方法开启整个音频模块,响应时间较慢,因此 Agora 建议使用如下方法来控制音频模块:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAudioSpectrumMonitor
开启音频频谱监测。
- (int)enableAudioSpectrumMonitor:(int)intervalInMS;
如果你想获取本地或远端用户的音频频谱数据,请注册音频频谱观测器并开启音频频谱监测。
该方法在加入频道前后均可调用。
参数
- intervalInMS
-
SDK 触发 onLocalAudioSpectrum 和 onRemoteAudioSpectrum 回调的时间间隔(毫秒)。 默认值为 100 毫秒。取值不得少于 10 毫秒,否则该方法会调用失败。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2: 参数设置错误。
enableAudioVolumeIndication
启用用户音量提示。
- (int)enableAudioVolumeIndication:(NSInteger)interval smooth:(NSInteger)smooth reportVad:(BOOL)reportVad;
该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户, SDK 会在加入频道后按设置的时间间隔触发 reportAudioVolumeIndicationOfSpeakers 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒。该参数需要设为 200 的整数倍。如果取值低于 200,SDK 会自动调整为 200。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- reportVad
-
YES
:开启本地人声检测功能。开启后,reportAudioVolumeIndicationOfSpeakers 回调的 vad 参数会报告是否在本地检测到人声。NO
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,reportAudioVolumeIndicationOfSpeakers 回调的 vad 参数不会报告是否在本地检测到人声。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableContentInspect
开启/关闭视频内容审核。
- (int)enableContentInspect:(BOOL)enabled config:(AgoraContentInspectConfig* _Nonnull)config;
开启视频内容审核后,SDK 会根据你在 AgoraContentInspectConfig 中设置的内容审核模块类型和频率对本地用户发送的视频进行截图、审核和上传。审核完成后,Agora 内容审核服务器会以 HTTPS 请求的形式,向你的服务器发送审核结果,并将所有截图发送至你指定的第三方云存储。
如果你将 AgoraContentInspectModule 中的 type 设置为 AgoraContentInspectTypeModeration(视频鉴黄),审核完成后,SDK 会触发 contentInspectResult 回调,报告鉴黄结果。
参数
- enabled
- 设置是否开启视频内容审核:
YES
:开启。NO
:关闭。
- config
- 内容审核配置。详见 AgoraContentInspectConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableDualStreamMode [1/3]
开关双流模式。
- (int)enableDualStreamMode:(BOOL)enabled;
该方法设置单流(默认)或者双流模式。你可以在发流端调用该方法开启或关闭双流模式。
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStream 选择接收视频大流或视频小流。
- 该方法仅对 SDK 通过摄像头采集的视频流生效。如果你使用自采集或 SDK 通过屏幕采集等方式采集视频流,你需要调用 enableDualStreamMode [2/3] 或 enableDualStreamMode [3/3] 开启双流模式。
- 该方法可以在加入频道前后调用。
参数
- enabled
-
是否开启双流模式。
YES
: 开启双流模式。NO
: 关闭双流模式。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableDualStreamMode [2/3]
开关双流模式。
- (int)enableDualStreamMode:(AgoraVideoSourceType)sourceType enabled:(BOOL)enabled;
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStream 选择接收视频大流或视频小流。
该方法可以在加入频道前后调用。
参数
- sourceType
-
视频源的类型。详见 AgoraVideoSourceType。
- enabled
-
是否开启双流模式:
YES
: 开启双流模式。NO
: 关闭双流模式。
返回值
- 0: 方法调用成功
- 0: 方法调用失败
enableDualStreamMode [3/3]
开关双流模式。
- (int)enableDualStreamMode:(AgoraVideoSourceType)sourceType enabled:(BOOL)enabled streamConfig:(AgoraSimulcastStreamConfig* _Nonnull)streamConfig;
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStream 选择接收视频大流或视频小流。
该方法可以在加入频道前后调用。
参数
- sourceType
-
视频源的类型。详见 AgoraVideoSourceType。
- enabled
-
是否开启双流模式:
YES
: 开启双流模式。NO
: 关闭双流模式。
- streamConfig
-
视频小流的配置。详见 AgoraSimulcastStreamConfig
返回值
- 0: 方法调用成功
- 0: 方法调用失败
enableEncryption
开启或关闭内置加密。
- (int)enableEncryption:(bool)enabled encryptionConfig:(AgoraEncryptionConfig * _Nonnull)config;
在安全要求较高的场景下,Agora 建议你在加入频道前,调用本方法开启内置加密。
同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
参数
- enabled
-
是否开启内置加密:
- YES: 开启内置加密。
- NO: 关闭内置加密。
- config
- 配置内置加密模式和密钥。详见 AgoraEncryptionConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -2: 调用了无效的参数。需重新指定参数。
- -4: 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -7: SDK 尚未初始化。需在调用 API 之前已创建 AgoraRtcEngineKit 对象并完成初始化。
enableExtensionWithVendor
启用/禁用插件。
- (int)enableExtensionWithVendor:(NSString * __nonnull)provider extension:(NSString * __nonnull)extension enabled:(BOOL)enabled;
该方法需要在加入频道前调用。
- 如果要开启多个插件,需要多次调用该方法。
- 不同插件在 SDK 中处理数据的顺序由插件的开通顺序决定。即先开启的插件会先处理数据。
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- enabled
-
是否启用插件:
YES
: 启用插件。NO
: 禁用插件。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableFaceDetection
开启/关闭本地人脸检测。
- (int)enableFaceDetection:(bool)enable NS_SWIFT_NAME(enableFaceDetection(_:));
该方法在加入频道前后都能调用。
- 摄像头采集的画面大小
- 人脸在 view 中的位置
- 人脸距设备屏幕的距离
该方法需要在相机启动(如通过调用 startPreview [1/2] 或 joinChannelByToken [2/4] 实现)后调用。
参数
- enable
- 是否开启人脸检测:
YES
:开启人脸检测。NO
:(默认)关闭人脸检测。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableInEarMonitoring [1/2]
开启耳返功能。
- (int)enableInEarMonitoring:(BOOL)enabled;
该方法打开或关闭耳返功能。
- 用户必须使用有线耳机才能听到耳返效果。
- 该方法在加入频道前后都能调用。
参数
- enabled
- 开启/关闭耳返功能:
YES
: 开启耳返功能。NO
: (默认)关闭耳返功能。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableInEarMonitoring [2/2]
开启耳返功能。
- (int)enableInEarMonitoring:(BOOL)enabled includeAudioFilters:(AgoraEarMonitoringFilterType)includeAudioFilters;
该方法打开或关闭耳返功能。
参数
- enabled
- 开启/关闭耳返功能:
YES
: 开启耳返功能。NO
: (默认)关闭耳返功能。
- includeAudioFilters
- 耳返 audio filter 类型。详见 AgoraEarMonitoringFilterType。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableLocalAudio
开关本地音频采集。
- (int)enableLocalAudio:(BOOL)enabled;
当用户加入频道时,音频功能默认是开启的。该方法可以关闭或重新开启本地音频功能,即停止或重新开始本地音频采集。
该方法不影响接收远端音频流,enableLocalAudio(NO)
适用于只听不发的用户场景。
- 该方法与 muteLocalAudioStream 的区别在于:
- enableLocalAudio: 开启或关闭本地音频采集及处理。使用 enableLocalAudio 关闭或开启本地采集后,本地听远端播放会有短暂中断。
- muteLocalAudioStream: 停止或继续发送本地音频流。
- 该方法在加入频道前后均可调用。在加入频道前调用只能设置设备状态,在加入频道后才会立即生效。
参数
- enabled
-
YES
: 重新开启本地音频功能,即开启本地音频采集(默认);NO
: 关闭本地音频功能,即停止本地音频采集。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableLocalVideo
开关本地视频采集。
- (int)enableLocalVideo:(BOOL)enabled;
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
调用 enableVideo 后,本地视频采集即默认开启。你可以调用 enableLocalVideo(NO
) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo(YES
)。
成功禁用或启用本地视频采集后,远端会触发 remoteVideoStateChangedOfUid 回调。
- 该方法在加入频道前后都能调用。
- 该方法设置内部引擎为启用状态,在离开频道后仍然有效。
参数
- enabled
-
是否开启本地视频采集。
YES
:(默认)开启本地视频采集。NO
: 关闭本地视频采集。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为NO
时,该方法不需要本地有摄像头。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableRemoteSuperResolution
开启或关闭远端视频超分辨率。
- (int)enableRemoteSuperResolution:(NSUInteger)uid enable:(BOOL)enable;
该功能可以有效提升本地用户看到的远端视频画面的分辨率,即:将接收到的指定远端用户的视频宽和高(像素)均扩大为 2 倍。
- 如果参数 superResolutionType >0:超分辨率已开启。
- 如果参数 superResolutionType =0:超分辨率未开启。
超分辨率功能会额外耗费系统资源。为平衡视觉体验和系统消耗,只可以对一个远端用户开启超分辨率,并且远端用户视频的原始分辨率在设备上不能超过 640 × 480。
- 调用该方法前,请确保你已经集成相应的动态库:
- iOS: AgoraSuperResolutionExtension.xcframework
- 该方法对用户设备具有一定要求,Agora 推荐你使用如下或更好的设备:
- iOS:
- iPhone XR
- iPhone XS
- iPhone XS Max
- iPhone 11
- iPhone 11 Pro
- iPhone 11 Pro Max
- iPhone 12
- iPhone 12 mini
- iPhone 12 Pro
- iPhone 12 Pro Max
- iPhone 12 SE(第二代)
- iPad Pro 11-inch(第三代)
- iPad Pro 12.9-inch(第三代)
- iPad Air(第三代)
- iPad Air(第四代)
- iOS:
参数
- uid
- 远端用户 ID。
- enable
- 是否对远端视频开启超分辨率:
YES
: 开启。NO
: 关闭。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableSoundPositionIndication
开启/关闭远端用户的语音立体声。
- (int)enableSoundPositionIndication:(BOOL)enabled;
如果想调用 setRemoteVoicePosition 实现听声辨位的功能,请确保在加入频道前调用该方法开启远端用户的语音立体声。
参数
- enabled
- 是否开启远端用户语音立体声:
YES
: 开启语音立体声。NO
: 关闭语音立体声。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableVideo
启用视频模块。
- (int)enableVideo;
该方法可以在加入频道前或者通话中调用,在加入频道前调用则自动开启视频模块;在通话中调用则由音频模式切换为视频模式。调用 disableVideo 方法可关闭视频模式。
成功调用该方法后,远端会触发 remoteVideoStateChangedOfUid 回调。
- 该方法设置的是内部引擎为启用状态,在离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制视频模块:
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableVideoImageSource
设置是否开启垫片推流功能。
- (int) enableVideoImageSource:(BOOL)enable options:(AgoraImageTrackOptions *_Nullable)options;
在发布视频流时,你可以调用该方法使用自定义图片来替代当前发布的视频流画面进行推流。
开启该功能后,你可以通过 AgoraImageTrackOptions 参数自定义垫片图片;在你关闭垫片功能之后,远端用户看到的依旧是当前你发布的视频流画面。
参数
- enable
- 是否开启垫片推流:
YES
:开启垫片推流。NO
:(默认)关闭垫片推流。
- options
- 垫片图片设置,详见 AgoraImageTrackOptions。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableVirtualBackground
开启/关闭虚拟背景。
- (int)enableVirtualBackground:(BOOL)enable backData:(AgoraVirtualBackgroundSource* _Nullable)backData NS_SWIFT_NAME(enableVirtualBackground(_:backData:));
虚拟背景功能支持你使用自定义的背景图替代本地用户原来的背景图或者将背景虚化处理。成功开启虚拟背景功能后,频道内所有用户都能看到自定义的背景。
请在 enableVideo 或 startPreview [1/2] 之后调用该方法。
- 该功能对设备性能要求较高,Agora 推荐你在搭载如下芯片的设备上使用:
- 搭载 A9 及以上芯片的如下设备:
- iPhone 6S 及以上
- iPad Air 第三代及以上
- iPad 第五代及以上
- iPad Pro 第一代及以上
- iPad mini 第五代及以上
- 搭载 A9 及以上芯片的如下设备:
- Agora 建议你在满足如下条件的场景中使用该功能:
- 使用高清摄像设备、摄像环境光照均匀。
- 摄像画面中,物件较少,用户的人像为半身人像且基本无遮挡,背景色较单一且与用户着装颜色不同。
参数
- enable
- 是否开启虚拟背景:
YES
: 开启。NO
: 关闭。
- backData
- 自定义的背景图。详见 AgoraVirtualBackgroundSource。为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配,SDK 会在保证自定义背景图不变形的前提下,对自定义背景图进行缩放和裁剪。
- segData
- 背景图像的处理属性。详见 AgoraSegmentationProperty。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -1:自定义的背景图不存在。请检查 AgoraVirtualBackgroundSource 中 source 的值。
- -2:自定义的背景图颜色格式出错。请检查 AgoraVirtualBackgroundSource 中 color 的值。
- -3:设备不支持使用虚拟背景。
enableWebSdkInteroperability
打开与 Web SDK 的互通(仅在直播场景适用)。
- (int)enableWebSdkInteroperability:(BOOL)enabled;
- 弃用:
- 该方法已废弃,SDK 自动开启与 Web SDK 的互通,无需调用该方法开启。
该方法打开或关闭与 Agora Web SDK 的互通。如果有用户通过 Web SDK 加入频道,请确保调用该方法,否则 Web 端用户看 Native 端的画面会是黑屏。
该方法仅在直播场景下适用,通信场景下默认互通是打开的。
参数
- enabled
- 是否打开与 Agora Web SDK 的互通:
YES
: 打开互通。NO
: (默认) 关闭互通。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getAudioMixingCurrentPosition
获取音乐文件的播放进度。
- (int)getAudioMixingCurrentPosition;
该方法获取当前音乐文件播放进度,单位为毫秒。
- 你需要在调用 startAudioMixing [2/2] 并收到
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。 - 如需多次调用 getAudioMixingCurrentPosition,请确保调用间隔大于 500 ms。
返回值
- ≥ 0: 方法调用成功,返回当前音乐文件播放进度(ms)。0 表示当前音乐文件未开始播放。
- < 0: 方法调用失败。
getAudioMixingDuration
获取音乐文件总时长。
- (int)getAudioMixingDuration;
该方法获取音乐文件总时长,单位为毫秒。
你需要在调用 startAudioMixing [2/2] 并收到 audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
返回值
- ≥ 0: 方法调用成功返回音乐文件时长。
- < 0: 方法调用失败。
getAudioMixingPlayoutVolume
获取音乐文件的本地播放音量。
- (int)getAudioMixingPlayoutVolume;
该方法获取混音的音乐文件本地播放音量,方便排查音量相关问题。
你需要在调用 startAudioMixing [2/2] 并收到 audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
返回值
- ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]。
- < 0: 方法调用失败。
getAudioMixingPublishVolume
获取音乐文件的远端播放音量。
- (int)getAudioMixingPublishVolume;
该接口可以方便开发者排查音量相关问题。
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。返回值
- ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]。
- < 0: 方法调用失败。
getAudioTrackCount
获取当前音乐文件的音轨索引。
- (int)getAudioTrackCount;
- 你需要在调用 startAudioMixing [2/2] 并收到
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。
返回值
- 方法调用成功时,返回当前音乐文件的音轨索引。
- < 0: 方法调用失败。
getCallId
getCameraMaxZoomFactor
获取摄像头支持最大缩放比例。
- (CGFloat)cameraMaxZoomFactor;
- 请在启动摄像头之后调用该方法,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之后。
返回值
设备摄像头支持的最大缩放比例。
getConnectionState
获取当前网络连接状态。
- (AgoraConnectionState)getConnectionState;
该方法在加入频道前后都能调用。
返回值
当前网络连接状态。详见 AgoraConnectionState。
getEffectCurrentPosition
获取指定音效文件的播放进度。
- (int)getEffectCurrentPosition:(int)soundId NS_SWIFT_NAME(getEffectCurrentPosition(_:));
- (int)getEffectCurrentPosition:(int)soundId;
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
- 方法调用成功,返回指定音效文件的播放进度(毫秒)。
- < 0:方法调用失败。
getEffectDuration
获取指定音效文件总时长。
- (int)getEffectDuration:(NSString* _Nonnull)filePath NS_SWIFT_NAME(getEffectDuration(_:));
参数
- filePath
- 文件路径:
- iOS 或 macOS: 音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。
- iOS 或 macOS: 音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
返回值
- 方法调用成功,返回指定音效文件时长(毫秒)。
- < 0:方法调用失败。
getEffectsVolume
获取音效文件的播放音量。
- (int)getEffectsVolume;
音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 音效文件的音量。
- < 0: 方法调用失败
getErrorDescription
获取警告或错误描述。
+ (NSString* _Nonnull)getErrorDescription: (NSInteger)error;
参数
- error
- SDK 报告的错误码或警告码。
返回值
具体的错误或警告描述。
getExtensionProperty [1/2]
获取插件的详细信息。
- (NSString * _Nullable)getExtensionPropertyWithVendor:(NSString * __nonnull)provider extension:(NSString * __nonnull)extension key:(NSString * __nonnull)key;
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- key
- 插件属性的 Key。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
getExtensionProperty [2/2]
获取插件的详细信息。
- (NSString * _Nullable)getExtensionPropertyWithVendor:(NSString * __nonnull)provider extension:(NSString * __nonnull)extension key:(NSString * __nonnull)key sourceType:(AgoraMediaSourceType)sourceType;
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- key
- 插件属性的 Key。
- sourceType
- 插件的媒体源类型。详见 AgoraMediaSourceType。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
createMediaPlayerCacheManager
创建 AgoraRtcMediaPlayerCacheManagerProtocol 实例。
- (id<AgoraRtcMediaPlayerCacheManagerProtocol> _Nullable)createMediaPlayerCacheManager;
请在初始化 AgoraRtcEngineKit 后调用该方法。
返回值
getNativeHandle
获取 Native SDK 的 C++ 句柄。
- (void* _Nullable)getNativeHandle;
该方法获取 Native SDK engine 的 C++ 句柄,用于包括注册音视频帧观测器在内的特殊场景。
返回值
SDK 引擎的 Native 句柄。
getSdkVersion
获取 SDK 版本。
+ (NSString * _Nonnull)getSdkVersion;
参数
返回值
当前的 SDK 版本号。格式为字符串。
getUserInfoWithUserId
通过 UID 获取用户信息。
- (AgoraUserInfo* _Nullable)getUserInfoByUid:(NSUInteger)uid withError:(AgoraErrorCode* _Nullable)error;
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 didUserInfoUpdatedWithUserId 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。
参数
- uid
- 用户 ID。
- error
- 错误码。
返回值
包含用户信息的 AgoraUserInfo 对象。
- 方法调用成功,返回 AgoraUserInfo 对象。
- 方法调用失败,则返回 nil。
getUserInfoWithUserAccount
通过 User Account 获取用户信息。
- (AgoraUserInfo* _Nullable)getUserInfoByUserAccount:(NSString* _Nonnull)userAccount withError:(AgoraErrorCode* _Nullable)error;
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 didUserInfoUpdatedWithUserId 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。
参数
- userAccount
- 用户 User Account。
- error
- 错误码。
返回值
包含用户信息的 AgoraUserInfo 对象。
- 方法调用成功,返回 AgoraUserInfo 对象。
- 方法调用失败,则返回 nil。
getVolumeOfEffect
获取指定音效文件的播放音量。
- (int)getVolumeOfEffect:(int)soundId;
参数
- soundId
- 音效文件的 ID。
返回值
- ≥ 0: 方法调用成功,返回播放音量。音量范围为 [0,100]。100 为原始音量。
- < 0: 方法调用失败。
isCameraAutoExposureFaceModeSupported
检测设备是否支持自动曝光功能。
- (BOOL)isCameraAutoExposureFaceModeSupported;
- 请在启动摄像头之前调用该方法,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之前。
返回值
YES
: 设备支持自动曝光功能。NO
: 设备不支持自动曝光功能。
isCameraAutoFocusFaceModeSupported
检测设备是否支持人脸对焦功能。
- (BOOL)isCameraAutoFocusFaceModeSupported;
- 请在启动摄像头之后调用该方法,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之后。
返回值
YES
: 设备支持人脸对焦功能。NO
: 设备不支持人脸对焦功能。
isCameraExposurePositionSupported
检测设备是否支持手动曝光功能。
- (BOOL)isCameraExposurePositionSupported;
- 请在启动摄像头之后调用该方法,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之后。
返回值
YES
: 设备支持手动曝光功能。NO
: 设备不支持手动曝光功能。
isCameraFocusSupported
检测设备是否支持手动对焦功能。
- (BOOL)isCameraFocusPositionInPreviewSupported;
- 请在启动摄像头之后调用该方法,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之后。
返回值
YES
: 设备支持手动对焦功能。NO
: 设备不支持手动对焦功能。
isCameraTorchSupported
检测设备是否支持闪光灯常开。
- (BOOL)isCameraTorchSupported NS_SWIFT_NAME(isCameraTorchSupported());
- 请在启动摄像头之后调用该方法,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之后。
- 一般情况下,app 默认开启前置摄像头,因此如果你的前置摄像头不支持闪光灯常开,直接使用该方法会返回 NO。如果需要检查后置摄像头是否支持闪光灯常开,需要先使用 switchCamera 切换摄像头,再使用该方法。
- 在系统版本 15 的 iPad 上,即使 isCameraTorchSupported 返回
YES
,也可能因系统问题导致你无法通过 setCameraTorchOn 成功开启闪光灯。
返回值
YES
: 设备支持闪光灯常开。NO
: 设备不支持闪光灯常开。
isCameraZoomSupported
检测设备是否支持摄像头缩放功能。
- (BOOL)isCameraZoomSupported;
- 请在启动摄像头之后调用该方法,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之后。
返回值
YES
: 设备支持相机缩放功能。NO
: 设备不支持相机缩放功能。
isSpeakerphoneEnabled
检查扬声器状态启用状态。
- (BOOL)isSpeakerphoneEnabled;
返回值
YES
: 扬声器已开启,语音会输出到扬声器。NO
: 扬声器未开启,语音会输出到非扬声器(听筒,耳机等)。
joinChannelByToken [1/4]
加入频道。
- (int)joinChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId info:(NSString * _Nullable)info uid:(NSUInteger)uid joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 app 不能互通。
- 本地会触发 didJoinChannel 和 connectionChangedToState 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 didJoinedOfUid 回调。
在网络状况不理想的情况下,客户端可能会与 Agora 服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 didRejoinChannel 回调。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见https://docs.agora.io/cn/live-streaming-premium-4.x/token_server_ios_ng?platform=iOS。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- info
- (非必选项) 预留参数。
- uid
- 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。 建议设置范围:1 到 232-1。如果不指定(即设为 0),SDK 会自动分配一个,并在 didJoinChannel 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,AgoraRtcChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是:调用 startEchoTestWithInterval 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。Agora 推荐通过 connectionChangedToState 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelByToken [2/4]
设置媒体选项并加入频道。
- (int)joinChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId uid:(NSUInteger)uid mediaOptions:(AgoraRtcChannelMediaOptions * _Nonnull)mediaOptions joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 app 不能互通。
- 本地会触发 didJoinChannel 和 connectionChangedToState 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 didJoinedOfUid 回调。
在网络状况不理想的情况下,客户端可能会与 Agora 服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 didRejoinChannel 回调。
相比 joinChannelByToken [1/4],该方法增加了 options 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。
- 该方法允许用户一次加入仅一个频道。
- 请务必确保用于生成 Token 的 App ID 和 sharedEngineWithConfig 方法初始化引擎时用的是同一个 App ID,否则使用 Token 加入频道失败。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见https://docs.agora.io/cn/live-streaming-premium-4.x/token_server_ios_ng?platform=iOS。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- uid
- 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。 建议设置范围:1 到 232-1。如果不指定(即设为 0),SDK 会自动分配一个,并在 didJoinChannel 回调中返回, app 层必须记住该返回值并维护,SDK 不对该返回值进行维护。
- mediaOptions
- 频道媒体设置选项。详见 AgoraRtcChannelMediaOptions。
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,AgoraRtcChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是:调用 startEchoTestWithInterval 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。Agora 推荐通过 connectionChangedToState 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelByToken [3/4]
使用 User Account 和 Token 加入频道。
- (int)joinChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId userAccount:(NSString * _Nonnull)userAccount joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
- 本地:didLocalUserRegisteredWithUserId、didJoinChannel 和 connectionChangedToState 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会依次触发 didJoinedOfUid 和 didUserInfoUpdatedWithUserId 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见https://docs.agora.io/cn/live-streaming-premium-4.x/token_server_ios_ng?platform=iOS。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- userAccount
-
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 nil。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- 2: 参数无效。
- 3: SDK 初始化失败,请尝试重新初始化 SDK。
- 5: 调用被拒绝。
- 17: 加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 AgoraRtcEngineKit 频道,当已经加入 AgoraRtcEngineKit 频道的用户使用有效的频道名再次调用 AgoraRtcEngineKit 类中的加入频道方法时,会返回此错误码。
joinChannelByToken [4/4]
使用 User Account 和 Token 加入频道,并设置是否自动订阅音频或视频流。
- (int)joinChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId userAccount:(NSString * _Nonnull)userAccount mediaOptions:(AgoraRtcChannelMediaOptions * _Nonnull)mediaOptions joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
- 本地:didLocalUserRegisteredWithUserId、didJoinChannel 和 connectionChangedToState 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 didJoinedOfUid 和 didUserInfoUpdatedWithUserId 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
相比 joinChannelByToken [3/4],该方法加了 options 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见https://docs.agora.io/cn/live-streaming-premium-4.x/token_server_ios_ng?platform=iOS。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- userAccount
-
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 nil。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- mediaOptions
- 频道媒体设置选项。详见 AgoraRtcChannelMediaOptions。
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,AgoraRtcChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是:调用 startEchoTestWithInterval 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。Agora 推荐通过 connectionChangedToState 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
leaveChannel [1/2]
离开频道。
- (int)leaveChannel:(void(^ _Nullable)(AgoraChannelStats * _Nonnull stat))leaveChannelBlock;
该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。
成功加入频道后,必须调用本方法或者 leaveChannel [2/2] 结束通话,否则无法开始下一次通话。
- 本地:didLeaveChannelWithStats 回调。
- 远端:通信场景下的用户和直播场景下的主播离开频道后,远端会触发 didOfflineOfUid 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。
参数
- leaveChannelBlock
-
成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats 。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
leaveChannel [2/2]
离开频道。
- (int)leaveChannel:(AgoraLeaveChannelOptions * _Nonnull)options leaveChannelBlock:(void (^ _Nullable)(AgoraChannelStats * _Nonnull))leaveChannelBlock;
离开频道,即挂断或退出通话。
加入频道后,必须调用本方法或 leaveChannel [1/2] 结束通话,才能开始下一次通话。
不管当前是否在通话中,都可以调用该方法,没有副作用。该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 didLeaveChannelWithStats 回调。
成功调用该方法离开频道后,本地会触发didLeaveChannelWithStats 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 didOfflineOfUid 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。
参数
- options
- 离开频道的选项,详见 AgoraLeaveChannelOptions。
- leaveChannelBlock
-
成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats 。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
- (int)muteAllRemoteAudioStreams:(BOOL)mute;
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户音频流,可以在调用 joinChannelByToken [2/4] 加入频道时设置 autoSubscribeAudio 为
NO
。 - 该方法的推荐设置详见设置订阅状态。
参数
- mute
-
是否取消订阅所有远端用户的音频流:
YES
: 取消订阅所有远端用户的音频流。NO
:(默认)订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteAllRemoteVideoStreams
取消或恢复订阅所有远端用户的视频流。
- (int)muteAllRemoteVideoStreams:(BOOL)mute;
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户视频流,可以在调用 joinChannelByToken [2/4] 加入频道时设置 autoSubscribeVideo 为
NO
。
参数
- mute
-
是否取消订阅所有远端用户的视频流。
YES
: 取消订阅所有用户的视频流。NO
:(默认)订阅所有用户的视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteLocalAudioStream
取消或恢复发布本地音频流。
- (int)muteLocalAudioStream:(BOOL)mute;
参数
- mute
-
是否取消发布本地音频流。
YES
: 取消发布。NO
:(默认)发布。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteLocalVideoStream
取消或恢复发布本地视频流。
- (int)muteLocalVideoStream:(BOOL)mute;
成功调用该方法后,远端会触发 didVideoMuted 回调。
- 相比于 enableLocalVideo(
NO
) 用于控制本地视频流发送的方法,该方法响应速度更快。 - 该方法不影响视频采集状态,没有禁用摄像头。
参数
- mute
-
是否取消发送本地视频流。
YES
: 取消发送本地视频流。NO
: (默认)发送本地视频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteAudioStream
取消或恢复订阅指定远端用户的音频流。
- (int)muteRemoteAudioStream:(NSUInteger)uid mute:(BOOL)mute;
- 该方法需要在加入频道后调用。
参数
- uid
- 指定用户的用户 ID。
- mute
-
是否取消订阅指定远端用户的音频流。
YES
: 取消订阅指定用户的音频流。NO
:(默认)订阅指定用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteVideoStream
取消或恢复订阅指定远端用户的视频流。
- (int)muteRemoteVideoStream:(NSUInteger)uid mute:(BOOL)mute;
- 该方法需要在加入频道后调用。
参数
- uid
- 指定用户的用户 ID。
- mute
-
是否取消订阅指定远端用户的视频流。
YES
: 取消订阅指定用户的视频流。NO
: (默认)订阅指定用户的视频流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pauseAllChannelMediaRelay
暂停向所有目标频道转发媒体流。
- (int)pauseAllChannelMediaRelay;
开始跨频道转发媒体流后,如果你需要暂停向所有频道转发媒体流,可以调用该方法;暂停后,如果要恢复跨频道媒体流转发,可以调用 resumeAllChannelMediaRelay 方法。
成功调用该方法后,SDK 会触发 didReceiveChannelMediaRelayEvent 回调,并在回调中报告是否成功暂停媒体流转发。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
pauseAudioMixing
暂停播放音乐文件。
- (int)pauseAudioMixing;
请在加入频道后调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
pauseAllEffects
暂停所有音效文件播放。
- (int)pauseAllEffects;
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
pauseEffect
暂停音效文件播放。
- (int)pauseEffect:(int)soundId;
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
playEffect [1/3]
播放指定的本地或在线音效文件。
- (int)playEffect:(int)soundId filePath:(NSString* _Nonnull)filePath loopCount:(NSInteger)loopCount pitch:(double)pitch pan:(double)pan gain:(NSInteger)gain;
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
-
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见支持的媒体格式。 - loopCount
-
音效循环播放的次数。
- ≥ 0: 循环播放次数。例如,1 表示循环播放 1 次,即总计播放 2 次。
- -1: 无限循环播放。
- pitch
- 音效的音调,取值范围为 [0.5,2.0]。默认值为 1.0,表示原始音调。取值越小,则音调越低。
- pan
-
音效的空间位置。取值范围为 [-1.0,1.0],例如:
- -1.0:音效出现在左边
- 0.0:音效出现在正前方
- 1.0:音效出现在右边
- gain
- 音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0,表示原始音量。取值越小,则音量越低。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
playEffect [2/3]
播放指定的本地或在线音效文件。
- (int)playEffect:(int)soundId filePath:(NSString* _Nonnull)filePath loopCount:(NSInteger)loopCount pitch:(double)pitch pan:(double)pan gain:(NSInteger)gain publish:(BOOL)publish;
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
- loopCount
-
音效循环播放的次数。
- ≥ 0: 循环播放次数。例如,1 表示循环播放 1 次,即总计播放 2 次。
- -1: 无限循环播放。
- pitch
- 音效的音调,取值范围为 [0.5,2.0]。默认值为 1.0,表示原始音调。取值越小,则音调越低。
- pan
-
音效的空间位置。取值范围为 [-1.0,1.0],例如:
- -1.0:音效出现在左边
- 0.0:音效出现在正前方
- 1.0:音效出现在右边
- gain
- 音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0,表示原始音量。取值越小,则音量越低。
- publish
-
是否将音效发布至远端:
YES
: 将音效发布至远端。本地用户和远端用户都能听到音效。NO
: 不将音效发布至远端。只有本地用户能听到音效。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
playEffect [3/3]
播放指定的本地或在线音效文件。
- (int)playEffect:(int)soundId filePath:(NSString* _Nonnull)filePath loopCount:(NSInteger)loopCount pitch:(double)pitch pan:(double)pan gain:(NSInteger)gain publish:(BOOL)publish startPos:(int)startPos;
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
-
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见支持的媒体格式。 - loopCount
-
音效循环播放的次数。
- ≥ 0: 循环播放次数。例如,1 表示循环播放 1 次,即总计播放 2 次。
- -1: 无限循环播放。
- pitch
- 音效的音调,取值范围为 [0.5,2.0]。默认值为 1.0,表示原始音调。取值越小,则音调越低。
- pan
-
音效的空间位置。取值范围为 [-1.0,1.0],例如:
- -1.0:音效出现在左边
- 0.0:音效出现在正前方
- 1.0:音效出现在右边
- gain
- 音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0,表示原始音量。取值越小,则音量越低。
- publish
-
是否将音效发布至远端:
YES
: 将音效发布至远端。本地用户和远端用户都能听到音效。NO
: 不将音效发布至远端。只有本地用户能听到音效。
- startPos
-
音效文件的播放位置,单位为毫秒。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
preloadEffect
将音效文件加载至内存。
- (int)preloadEffect:(int)soundId filePath:(NSString* _Nonnull)filePath;
为保证通信畅通,请注意控制预加载音效文件的大小,并在 joinChannelByToken [2/4] 前就使用该方法完成音效预加载。
- 该方法不支持在线音频文件。
- 该方法支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
- 文件路径:
- iOS 或 macOS: 音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。
- iOS 或 macOS: 音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
pullPlaybackAudioFrameRawData
拉取远端音频数据。
- (BOOL)pullPlaybackAudioFrameRawData:(void * _Nonnull)data lengthInByte:(NSUInteger)lengthInByte;
使用该方法前,你需要调用 enableExternalAudioSink 通知 app 开启并设置外部渲染。
调用该方法后,app 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。
- 该方法仅支持拉取自采集的数据。如果你需要拉取 SDK 采集的数据,请不要调用该方法。
- 该方法需要在加入频道后调用。
- 开启外部音频渲染后,app 将无法从 onPlaybackAudioFrame 回调中获得数据。
- 该方法和 onPlaybackAudioFrame 回调相比,区别在于:
- SDK 通过 onPlaybackAudioFrame 回调将音频数据传输给 app。如果 app 处理延时,可能会导致音频播放抖动。
- 调用该方法后 app 会主动拉取音频数据。通过设置音频数据,SDK 可以调整缓存,帮助 app 处理延时,从而有效避免音频播放抖动。
参数
- data
- 待拉取的远端音频数据,数据类型为
byte[]
。 - lengthInByte
- 音频数据长度,单位为字节。该参数的值由音频数据时长、enableExternalAudioSink 的
sampleRate
和channels
参数确定。lengthInByte
=sampleRate
/1000 × 2 ×channels
× 音频数据时长 (ms)。
返回值
YES
:方法调用成功。NO
:方法调用失败。
pullPlaybackAudioFrameSampleBufferByLengthInByte
拉取 SampleBuffer 格式的远端音频数据。
- (CMSampleBufferRef _Nullable)pullPlaybackAudioFrameSampleBufferByLengthInByte:(NSUInteger)lengthInByte;
使用该方法前,你需要调用 enableExternalAudioSink 通知 app 开启并设置外部渲染。
调用该方法后,app 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。
- 该方法仅支持拉取自采集的数据。如果你需要拉取 SDK 采集的数据,请不要调用该方法。
- 该方法需要在加入频道后调用。
- 开启外部音频渲染后,app 将无法从 onPlaybackAudioFrame 回调中获得数据。
- 该方法和 onPlaybackAudioFrame 回调相比,区别在于:
- SDK 通过 onPlaybackAudioFrame 回调将音频数据传输给 app。如果 app 处理延时,可能会导致音频播放抖动。
- 调用该方法后 app 会主动拉取音频数据。通过设置音频数据,SDK 可以调整缓存,帮助 app 处理延时,从而有效避免音频播放抖动。
参数
- lengthInByte
- 音频数据长度,单位为字节。该参数的值由音频数据时长、enableExternalAudioSink 的
sampleRate
和channels
参数确定。lengthInByte
=sampleRate
/1000 × 2 ×channels
× 音频数据时长 (ms)。
返回值
YES
:方法调用成功。NO
:方法调用失败。
pushExternalAudioFrameRawData
推送外部音频帧。
- (int)pushExternalAudioFrameRawData:(void * _Nonnull)data samples:(NSInteger)samples sourceId:(NSInteger)sourceId timestamp:(NSTimeInterval)timestamp;
参数
- data
- 外部音频数据。
- samples
- 外部音频帧采样数。
- timestamp
- 外部音频帧的时间戳(毫秒)。该参数为必填。你可以使用该时间戳还原音频帧顺序;在有视频的场景中(包含使用外部视频源的场景),该参数可以帮助实现音视频同步。
- sourceId
- 外部音频源的 ID。如果你要发布自定义的外部音频源,则将该参数设置为你想要发布的自定义音频轨道 ID。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushExternalAudioFrameNSData
推送外部音频数据。
- (int)pushExternalAudioFrameNSData:(NSData * _Nonnull)data sourceId:(NSInteger)sourceId timestamp:(NSTimeInterval)timestamp;
调用该方法前,请将 AgoraRtcChannelMediaOptions 中的 publishCustomAudioTrack 设为 YES
。
参数
- data
- 外部音频数据。
- timestamp
- 外部音频帧的时间戳(毫秒)。该参数为必填。你可以使用该时间戳还原音频帧顺序;在有视频的场景中(包含使用外部视频源的场景),该参数可以帮助实现音视频同步。
- sourceId
- 外部音频源的 ID。如果你要发布自定义的外部音频源,则将该参数设置为你想要发布的自定义音频轨道 ID。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushExternalAudioFrameSampleBuffer
推送外部 CMSampleBuffer 音频帧。
- (int)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer;
参数
- sampleBuffer
- 采样缓冲区。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushExternalVideoFrame
推送外部原始视频帧到 SDK。
- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame * _Nonnull)frame;
调用 setExternalVideoSource 方法,设置 enabled 参数为 YES
、encodedFrame 参数为 NO
后,你可以调用本方法将未编码的外部视频帧推送到 SDK。
参数
- frame
-
待推送的视频帧。详见 AgoraVideoFrame。
返回值
YES
:推送成功。NO
:推送失败。
rate
给通话评分。
- (int)rate:(NSString * _Nonnull)callId rating:(NSInteger)rating description:(NSString * _Nullable)description;
参数
- callId
- 通话 ID。你可以通过调用 getCallId 获取该参数。
- rating
- 给通话的评分,最低 1 分,最高 5 分,如超过这个范围,SDK 会返回 -2(
ERR_INVALID_ARGUMENT
) 错误。 - description
- (非必选项)给通话的描述。长度应小于 800 字节。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2(
ERR_INVALID_ARGUMENT
)。 - -3(
ERR_NOT_READY
)。
- -2(
registerAudioEncodedFrameObserver
注册音频编码数据观测器。
- (int)setAudioEncodedFrameDelegate:(id<AgoraAudioEncodedFrameDelegate> _Nonnull)delegate config:(AgoraAudioEncodedFrameDelegateConfig * _Nonnull) config;
- 请在加入频道后调用该方法。
- 由于该方法和 startAudioRecording [2/2] 都会设置音频内容和音质,Agora 不推荐该方法和 startAudioRecording [2/2] 一起使用。否则,只有后调用的方法会生效。
参数
- config
- 编码后音频的观测器设置。详见 AgoraAudioEncodedFrameDelegateConfig。
- delegate
- 编码后音频的观测器。详见 AgoraAudioEncodedFrameDelegate。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioFrameDelegate
注册音频观测器对象。
- (BOOL)setAudioFrameDelegate:(id<AgoraAudioFrameDelegate> _Nullable)delegate;
该方法用于注册音频观测器对象,即注册回调。当需要 SDK 给出 onRecordAudioFrame、onPlaybackAudioFrame 或 onEarMonitoringAudioFrame 回调时,需要使用该方法注册回调。
参数
- delegate
-
接口对象实例。详见 AgoraAudioFrameDelegate。如果传入 nil,则表示取消注册。Agora 建议在收到 didLeaveChannelWithStats 后调用,来释放音频观测器对象。
返回值
YES
:方法调用成功。NO
:方法调用失败。
registerAudioSpectrumDelegate
注册音频频谱观测器。
- (int)registerAudioSpectrumDelegate:(id<AgoraAudioSpectrumDelegate> _Nullable )delegate;
成功注册音频频谱观测器并调用 enableAudioSpectrumMonitor 开启音频频谱监测后,SDK 会按照你设置的时间间隔报告你在 AgoraAudioSpectrumDelegate 类中实现的回调。
参数
- delegate
-
音频频谱观测器。详见 AgoraAudioSpectrumDelegate。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
registerLocalUserAccountWithAppID
注册本地用户 User Account。
- (int)registerLocalUserAccountWithAppID:(NSString * _Nonnull)appID userAccount:(NSString * _Nonnull)userAccount;
该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。
成功注册 User Account 后,本地会触发 didLocalUserRegisteredWithUserId 回调,告知本地用户的 UID 和 User Account。
- 先调用 registerLocalUserAccountWithAppID 方法注册 Account,再调用 joinChannelByToken [4/4] 方法加入频道。
- 直接调用 joinChannelByToken [4/4] 方法加入频道。
两种方式的区别在于,提前调用 registerLocalUserAccountWithAppID,可以缩短使用 joinChannelByToken [4/4] 进入频道的时间。
- userAccount 不能为空,否则该方法不生效。
- 请确保在该方法中设置的 userAccount 在频道中的唯一性。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Agora Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
参数
- appID
- 你的项目在 Agora 控制台注册的 App ID。
- userAccount
-
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。该参数为必填,最大不超过 255 字节,不可填 nil。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setMediaMetadataDelegate
注册媒体 metadata 观测器用于接收或发送 metadata。
- (BOOL)setMediaMetadataDelegate:(id<AgoraMediaMetadataDelegate> _Nullable)metadataDelegate withType:(AgoraMetadataType)type;
你需要自行实现 AgoraMediaMetadataDelegate 类并在本方法中指定 metadata 类型。本方法允许你为视频流添加同步的 metadata,用于多样化的直播互动,如发送购物链接、电子优惠券和在线测试。
调用该方法成功后,SDK 会触发 metadataMaxSize 回调。
参数
- observer
- metadata 观测器。详见 AgoraMediaMetadataDelegate。
- type
-
metadata 类型。目前仅支持 AgoraMetadataTypeVideo。详见 AgoraMetadataType。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
registerVideoEncodedFrameObserver
为编码后的视频图像注册视频帧接收观测器。
- (BOOL)setEncodedVideoFrameDelegate:(id<AgoraEncodedVideoFrameDelegate> _Nullable)delegate;
- 请在加入频道后调用该方法。
- 如果你调用该方法注册了 IVideoEncodedFrameObserver 对象,则不能再注册 AgoraVideoFrameDelegate 对象。
参数
- delegate
- 接口对象实例。详见 IVideoEncodedFrameObserver。如果传入 nil,则表示取消注册。
返回值
YES
: 方法调用成功。NO
: 方法调用失败。
setVideoFrameDelegate
注册视频观测器对象。
- (BOOL)setVideoFrameDelegate:(id<AgoraVideoFrameDelegate> _Nullable)delegate;
你需要在该方法中实现一个 AgoraVideoFrameDelegate 类,并根据场景需要,注册该类的回调。 成功注册视频观测器后,SDK 会在捕捉到每个视频帧时,触发你所注册的上述回调。
- 在处理回调时,你需要考虑视频帧中 width 和 height 参数的变化,因为观测得到的视频帧可能会随以下情况变化:
- 当网络状况差时,分辨率会阶梯式下降。
- 当用户自行调整分辨率时,回调中报告的分辨率也会变化。
- 该方法需要在加入频道前调用。
参数
- delegate
- 接口对象实例。详见 AgoraVideoFrameDelegate。如果传入 nil,则取消注册。
返回值
YES
:方法调用成功。NO
:方法调用失败。
resumeAllChannelMediaRelay
恢复向所有目标频道转发媒体流。
- (int)resumeAllChannelMediaRelay;
调用 pauseAllChannelMediaRelay 方法后,如果你需要恢复向所有目标频道转发媒体流,可以调用该方法。
成功调用该方法后,SDK 会触发 didReceiveChannelMediaRelayEvent 回调,并在回调中报告是否成功恢复媒体流转发。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
resumeAllEffects
恢复播放所有音效文件。
- (int)resumeAllEffects;
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
resumeEffect
恢复播放指定音效文件。
- (int)resumeEffect:(int)soundId;
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEffectsVolume
设置音效文件的播放音量。
- (int)setEffectsVolume:(NSInteger)volume;
参数
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVolumeOfEffect
实时调整音效文件的播放音量。
- (int)setVolumeOfEffect:(int)soundId withVolume:(int)volume;
参数
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopAllEffects
停止播放所有音效文件。
- (int)stopAllEffects;
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopEffect
停止播放指定音效文件。
- (int)stopEffect:(int)soundId;
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
unloadEffect
从内存释放某个预加载的音效文件。
- (int)unloadEffect:(int)soundId;
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
renewToken
更新 Token。
- (int)renewToken:(NSString * _Nonnull)token;
- 发生 tokenPrivilegeWillExpire 回调时。
- connectionChangedToState 回调报告 AgoraConnectionChangedReasonTokenExpired(9) 时。
参数
- token
- 新的 Token。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token。你需要填入有效的参数。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
resumeAudioMixing
恢复播放音乐文件。
- (int)resumeAudioMixing;
该方法恢复混音,继续播放音乐文件。请在频道内调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
selectAudioTrack
指定当前音频文件的播放音轨。
- (int)selectAudioTrack:(int)index;
获取音频文件的音轨索引后,你可以调用该方法指定任一音轨进行播放。例如,如果一个多音轨文件的不同音轨存放了不同语言的歌曲,则你可以调用该方法设置播放语言。
参数
- index
- 音轨的索引值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
sendCustomReportMessage
发送自定义上报消息。
- (int)sendCustomReportMessage:(NSString * _Nullable)messageId category:(NSString * _Nullable)category event:(NSString * _Nullable)event label:(NSString * _Nullable)label value:(NSInteger)value;
声网提供自定义数据上报和分析服务。该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据,每条自定义数据不能超过 256 字节,每个字符串不能超过 100 字节。如需试用该服务,请联系 sales@agora.io 开通并商定自定义数据格式。
sendStreamMessage
发送数据流。
- (int)sendStreamMessage:(NSInteger)streamId data:(NSData * _Nonnull)data;
- 频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 6 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 receiveStreamMessageFromUid 回调,远端用户可以在该回调中获取接收到的流消息; 若调用失败,远端会触发 didOccurStreamMessageErrorFromUid 回调。
- 请确保在调用该方法前,已调用 createDataStream [2/2] 创建了数据通道。
- 直播场景下,该方法仅适用于主播用户。
参数
- streamId
- 数据流 ID。可以通过 createDataStream [2/2] 获取。
- data
- 待发送的数据。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAdvancedAudioOptions
设置音频的高级选项。
- (int)setAdvancedAudioOptions:(AgoraAdvancedAudioOptions * _Nonnull)options;
如果你对音频处理有进阶需求,例如需要采集和发送立体声,可以调用该方法设置音频的高级选项。
- 你需要在 joinChannelByToken [2/4]、enableAudio 和 enableLocalAudio 前调用该方法。
参数
- options
- 音频的高级选项。详见 AgoraAdvancedAudioOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioEffectParameters
设置 SDK 预设人声音效的参数。
- (int)setAudioEffectParameters:(AgoraAudioEffectPreset)preset param1:(int)param1 param2:(int)param2;
- 3D 人声音效:设置 3D 人声音效的环绕周期。
- 电音音效:设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效,Agora 推荐你将基础调式和主音音高配置选项与应用的 UI 元素绑定。
设置后,频道内所有用户都能听到该效果。
- 该方法在加入频道前后都能调用。
- 为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AgoraAudioScenarioGameStreaming(3)。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileSpeechStandard(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setAudioEffectParameters 后,Agora 不推荐调用以下方法,否则 setAudioEffectParameters 设置的效果会被覆盖:
参数
- preset
- SDK 预设的音效,支持以下设置:
- AgoraAudioEffectPresetRoomAcous3DVoice,3D 人声音效。
- 你需要在使用该枚举前将 setAudioProfile [1/2] 的 profile 参数设置 为 AgoraAudioProfileMusicStandardStereo(3) 或 AgoraAudioProfileMusicHighQualityStereo(5),否则该枚举设置无效。
- 启用 3D 人声后,用户需要使用支持双声道的音频播放设备才能听到预期效果。
- AgoraAudioEffectPresetPitchCorrection,电音音效。为获取更好的人声效果,Agora 建议你在使用该枚举前将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileMusicHighQuality(4) 或 AgoraAudioProfileMusicHighQualityStereo(5)。
- AgoraAudioEffectPresetRoomAcous3DVoice,3D 人声音效。
- param1
-
- 如果 preset 设为 AgoraAudioEffectPresetRoomAcous3DVoice ,则 param1 表示 3D 人声音效的环绕周期。取值范围为 [1,60],单位为秒。默认值为 10,表示人声会 10 秒环绕 360 度。
- 如果 preset 设为 AgoraAudioEffectPresetPitchCorrection,则 param1 表示电音音效的基础调式:
1
: (默认)自然大调。2
: 自然小调。3
: 和风小调。
- param2
-
- 如果 preset 设为 AgoraAudioEffectPresetRoomAcous3DVoice,你需要将 param2 设置为
0
。 - 如果 preset 设为 AgoraAudioEffectPresetPitchCorrection,则 param2 表示电音音效的主音音高:
1
: A2
: A#3
: B4
: (Default) C5
: C#6
: D7
: D#8
: E9
: F10
: F#11
: G12
: G#
- 如果 preset 设为 AgoraAudioEffectPresetRoomAcous3DVoice,你需要将 param2 设置为
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioEffectPreset
设置 SDK 预设的人声音效。
- (int)setAudioEffectPreset:(AgoraAudioEffectPreset)preset;
调用该方法可以为本地发流用户设置 SDK 预设的人声音效,且不会改变原声的性别特征。设置音效后,频道内所有用户都能听到该效果。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AgoraAudioScenarioGameStreaming(3)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileSpeechStandard(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 如果调用 setAudioEffectPreset 并设置除 AgoraAudioEffectPresetRoomAcous3DVoice 或 AgoraAudioEffectPresetPitchCorrection 外的枚举,请勿再调用 setAudioEffectParameters,否则 setAudioEffectPreset 设置的效果会被覆盖。
- 调用 setAudioEffectPreset 后,Agora 不推荐调用以下方法,否则 setAudioEffectPreset 设置的效果会被覆盖:
参数
- preset
- 预设的音效选项,详见 AgoraAudioEffectPreset。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingDualMonoMode
设置当前音频文件的声道模式。
- (int)setAudioMixingDualMonoMode:(AgoraAudioMixingDualMonoMode)mode;
在双声道音频文件中,左声道和右声道可以存储不同的音频数据。根据实际需要,你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如,在 KTV 场景中,音频文件的左声道存储了伴奏,右声道存储了原唱的歌声。如果你只需听伴奏,调用该方法设置音频文件的声道模式为左声道模式;如果你需要同时听伴奏和原唱,调用该方法设置声道模式为混合模式。
- 你需要在调用 startAudioMixing [2/2] 并收到
audioMixingStateChanged (AgoraAudioMixingStateTypePlaying)
回调后调用该方法。 - 该方法仅适用于双声道的音频文件。
参数
- mode
- 声道模式。详见 AgoraAudioMixingDualMonoMode。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingPitch
调整本地播放的音乐文件的音调。
- (int)setAudioMixingPitch:(NSInteger)pitch;
本地人声和播放的音乐文件混音时,调用该方法可以仅调节音乐文件的音调。
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。参数
- pitch
- 按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingPosition
设置音乐文件的播放位置。
- (int)setAudioMixingPosition:(NSInteger)pos;
该方法可以设置音频文件的播放位置,这样你可以根据实际情况播放文件,而非从头到尾播放整个文件。
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调后调用该方法。参数
- pos
- 整数。进度条位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioProfile [1/2]
设置音频编码属性和音频场景。
- (int)setAudioProfile:(AgoraAudioProfile)profile scenario:(AgoraAudioScenario)scenario;
- 弃用:
- 此方法已废弃,如需设置音频编码属性,请改用 setAudioProfile [2/2];如需设置音频场景,请改用 setAudioScenario。
- 该方法在加入频道前后均可调用。
- 在有高音质需求的场景(例如音乐教学场景)中,建议将 profile 设置为
AgoraAudioProfileMusicHighQuality(4)
,scenario 设置为AgoraAudioScenarioGameStreaming(3)
。
参数
- profile
-
音频编码属性,包含采样率、码率、编码模式和声道数。详见 AgoraAudioProfile。
- scenario
- 音频场景。详见 AgoraAudioScenario 。不同的音频场景下,设备的音量类型是不同的。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioProfile [2/2]
设置音频编码属性。
- (int)setAudioProfile:(AgoraAudioProfile)profile;
- 该方法在加入频道前后均可调用。
- 在有高音质需求的场景(例如音乐教学场景)中,建议将
profile
设置为AgoraAudioProfileMusicHighQuality (4)
。 - 如果你想设置音频应用场景,请调用 sharedEngineWithConfig 并设置 AgoraRtcEngineConfig 结构体中的 audioScenario。
参数
- profile
-
音频编码属性,包含采样率、码率、编码模式和声道数。详见 AgoraAudioProfile。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioScenario
设置音频场景。
- (int)setAudioScenario:(AgoraAudioScenario)scenario;
参数
- scenario
- 音频场景。详见 AgoraAudioScenario。不同的音频场景下,设备的音量类型是不同的。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAVSyncSource
设置发流端音画同步。
- (int) setAVSyncSource:(NSString* _Nonnull)channelId uid:(NSUInteger)uid;
同一用户可能使用两个设备分别发送音频流和视频流,为保证接收端听到和看到的音频和视频的时间同步性,你可以在视频发送端调用该方法,并传入音频发送端的频道名、用户 ID。 SDK 会以发送的音频流的时间戳为基准进行自动调节发送的视频流,以保证即使在两个发送端的上行网络情况不一致(如分别使用 Wi-Fi 和 4G 网络)的情况下,也能让接收到的音视频具有时间同步性。
参数
- channelId
- 标识音频发送端所在频道的频道名。
- uid
- 音频发送端的用户 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setBeautyEffectOptions
设置美颜效果选项。
- (int)setBeautyEffectOptions:(BOOL)enable options:(AgoraBeautyOptions* _Nullable)options;
开启本地美颜功能,并设置美颜效果选项。
- 请在 enableVideo 或 startPreview [1/2] 之后调用该方法。
参数
- enable
- 是否开启美颜功能:
YES
: 开启。NO
:(默认)关闭。
- options
- 美颜选项,详细定义见 AgoraBeautyOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraAutoFocusFaceModeEnabled
设置是否开启人脸对焦功能。
- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable;
SDK 默认开启人脸自动对焦。如需自行设置人脸自动对焦,请调用该方法。
- 该方法需在摄像头启动后调用,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之后。
参数
- enable
-
是否开启人脸对焦:
YES
: 开启人脸对焦功能。NO
: 关闭人脸对焦功能。
返回值
YES
: 方法调用成功。NO
: 方法调用失败。
setCameraCapturerConfiguration
设置摄像头采集配置。
- (int)setCameraCapturerConfiguration:(AgoraCameraCapturerConfiguration * _Nullable)config;
- 请在启动摄像头之前调用该方法,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之前。
参数
- config
- 摄像头采集配置,详见 AgoraCameraCapturerConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraExposurePosition
设置手动曝光位置。
- (BOOL)setCameraExposurePosition:(CGPoint)positionInView;
该方法需要在相机启动(如通过调用 startPreview [1/2] 或 joinChannelByToken [2/4] 实现)后调用。
成功调用该方法后,本地会触发 cameraExposureDidChangedToRect 回调。
参数
- positionInView
- 触摸点相对于视图的横坐标和纵坐标。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraFocusPositionInPreview
设置手动对焦位置,并触发对焦。
- (BOOL)setCameraFocusPositionInPreview:(CGPoint)position;
该方法需要在相机启动(如通过调用 startPreview [1/2] 或 joinChannelByToken [2/4] 实现)后调用。 成功调用该方法后,本地会触发 cameraFocusDidChangedToRect 回调。
参数
- position
- 触摸点相对于视图的坐标。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraTorchOn
设置是否打开闪光灯。
- (BOOL)setCameraTorchOn:(BOOL)isOn NS_SWIFT_NAME(setCameraTorchOn(_:));
- 请在启动摄像头之前调用该方法,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之前。
参数
- isOn
-
是否打开闪光灯:
YES
: 打开闪光灯。NO
:(默认)关闭闪光灯。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraZoomFactor
设置摄像头缩放比例。
- (CGFloat)setCameraZoomFactor:(CGFloat)zoomFactor;
- 请在启动摄像头之前调用该方法,如 joinChannelByToken [2/4]、enableVideo 或者 enableLocalVideo 之前。
参数
- zoomFactor
- 相机缩放比例,有效范围从 1.0 到最大缩放比例。你可以通过 getCameraMaxZoomFactor 方法获取设备支持的最大缩放比例。
返回值
- 方法调用成功: 返回设置的 factor 值。
- 方法调用失败: 返回值 < 0。
setChannelProfile
设置频道场景。
- (int)setChannelProfile:(AgoraChannelProfile)profile;
SDK 初始化后默认的频道场景为直播场景。你可以调用该方法设置 Agora 频道的使用场景。Agora SDK 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。
- 为保证实时音视频质量,相同频道内的用户必须使用同一种频道场景。
- 该方法必须在 joinChannelByToken [2/4] 前调用和进行设置,进入频道后无法再设置。
- 不同的频道场景下,SDK 的默认音频路由和默认视频编码码率是不同的,详见 setDefaultAudioRouteToSpeakerphone 和 setVideoEncoderConfiguration 中的说明。
参数
- profile
-
频道使用场景。详见 AgoraChannelProfile。
返回值
- 0(ERR_OK) 方法调用成功。
- < 0 方法调用失败。
- -2 (ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
setCloudProxy
设置 Agora 云代理服务。
- (int)setCloudProxy:(AgoraCloudProxyType)proxyType NS_SWIFT_NAME(setCloudProxy(_:));
当用户的网络访问受到防火墙限制时,你需要将 Agora 提供的 IP 和端口号添加到防火墙白名单,然后调用该方法开启云代理,并通过 proxyType 参数设置云代理类型。
成功连接云代理后,SDK 会触发 connectionChangedToState (AgoraConnectionStateConnecting, AgoraConnectionChangedReasonSettingProxyServer) 回调。
如果你想关闭已设置的 Force UDP 或 Force TCP 云代理,请调用 setCloudProxy (AgoraNoneProxyType)
。
如果你想更改已设置的云代理类型,请先调用 setCloudProxy (AgoraNoneProxyType)
,再调用 setCloudProxy 并传入你期望的 proxyType 值。
- Agora 推荐你在频道外调用该方法。
- 如果用户处于内网防火墙环境下,使用 Force UDP 云代理时,旁路推流和跨频道媒体流转发功能不可用。
- 使用 Force UDP 云代理时,调用 startAudioMixing [2/2] 方法时无法播放 HTTP 协议的在线音频文件。旁路推流和跨频道媒体流转发功能会使用 TCP 协议的云代理。
参数
- proxyType
-
云代理类型,详见 AgoraCloudProxyType。
该参数为必填参数,如果你不赋值,SDK 会报错。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2: 传入的参数无效。
- -7: SDK 尚未初始化。
setClientRole [1/2]
设置用户角色。
- (int)setClientRole:(AgoraClientRole)role;
在加入频道前和加入频道后均可调用该方法设置用户角色。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo 方法设置了本地视频属性,则用户加入频道时会自动开启本地视频预览。
- 本地会触发 didClientRoleChanged 回调。
- 远端会触发 didJoinedOfUid 或
didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience)
回调。
在屏幕共享场景下,如果主播下麦后再上麦,则需要在调用该方法将用户角色设置为主播后,再调用 updateScreenCapture 并将 captureAudio 设置为 YES
,否则观众端无法接收主播端发出的音频流。
参数
- role
-
用户角色。详见 AgoraClientRole。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: SDK 尚未初始化。
setClientRole [2/2]
设置直播场景下的用户角色和级别。
- (int)setClientRole:(AgoraClientRole)role options:(AgoraClientRoleOptions * _Nullable)options;
直播场景下,SDK 会默认设置用户角色为观众,你可以调用该方法设置用户角色为主播。
该方法在加入频道前后均可调用。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo 方法设置了本地视频属性,则用户加入频道时会自动开启本地视频预览。
- 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
- 本地触发 didClientRoleChanged 回调。
- 远端触发 didJoinedOfUid 或 didOfflineOfUid 回调。
- 用户角色(role)确定用户在 SDK 层的权限,包含是否可以发送流、是否可以接收流、是否可以旁路推流等。
- 用户级别(level)需要与角色结合使用,确定用户在其权限范围内可以享受到的服务。例如对于观众,选择接收低延时还是超低延时的视频流。不同的级别会影响计费。
参数
- role
- 直播场景中的用户角色。详见 AgoraClientRole。
- options
- 用户具体设置,包含用户级别。详见 AgoraClientRoleOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -5: 调用被拒绝。
- -7: SDK 尚未初始化。
setDefaultAudioRouteToSpeakerphone
设置默认的音频路由。
- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker;
手机设备一般有两个音频路由,一个是位于顶部的听筒,播放声音偏小;一个是位于底部的扬声器,播放声音偏大。设置默认的音频路由,就是在没有外接设备的前提下,设置系统使用听筒还是扬声器播放音频。
- 语音通话:听筒
- 语音直播:扬声器
- 视频通话:扬声器
- 视频直播:扬声器
调用该 API 可以改变上述默认音频路由。成功改变音频路由后,SDK 会触发 didAudioRouteChanged 回调。
当手机插入外接设备,如蓝牙设备或耳机时,系统的音频路由会发生改变。详细的路由变化规律请参考 音频路由。
参数
- defaultToSpeaker
- 是否使用扬声器作为默认的音频路由:
YES
: 设置默认音频路由为扬声器。NO
: 设置默认音频路由为听筒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setDirectCdnStreamingAudioConfiguration
设置主播端直接向 CDN 推流时的音频编码属性。
- (int)setDirectCdnStreamingAudioConfiguration:(AgoraAudioProfile)profile;
该方法仅对麦克风采集或自采集的音频有效,即对在 AgoraDirectCdnStreamingMediaOptions 中设置 publishMicrophoneTrack 或 publishCustomAudioTrack 为 YES
时所采集的音频有效。
参数
- profile
-
音频编码属性,包含采样率、码率、编码模式和声道数。详见 AgoraAudioProfile。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setDirectCdnStreamingVideoConfiguration
设置主播端直接向 CDN 推流时的视频编码属性。
- (int)setDirectCdnStreamingVideoConfiguration:(AgoraVideoEncoderConfiguration * _Nonnull)config;
该方法仅对摄像头采集、屏幕共享或自采集的视频有效。即对在 AgoraDirectCdnStreamingMediaOptions 中设置 publishCameraTrack 或 publishCustomVideoTrack 为 YES
时所采集的视频有效。
参数
- config
- 视频编码参数配置。详见 AgoraVideoEncoderConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEffectPosition
设置指定音效文件的播放位置。
- (int)setEffectPosition:(int)soundId pos:(NSInteger)pos NS_SWIFT_NAME(setEffectPosition(_:pos:));
成功设置后,本地音效文件会在指定位置开始播放。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- pos
- 音效文件的播放位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEarMonitoringAudioFrameParametersWithSampleRate
设置耳返的音频数据格式。
- (int)setEarMonitoringAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel mode:(AgoraAudioRawFrameOperationMode)mode samplesPerCall:(NSInteger)samplesPerCall;
该方法用于设置 onEarMonitoringAudioFrame 回调的耳返音频数据格式。
- 调用该方法前,你需要先调用 enableInEarMonitoring [2/2],将 includeAudioFilters 设置为 AgoraEarMonitoringFilterBuiltInAudioFilters 或 AgoraEarMonitoringFilterNoiseSuppression。
- SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 onEarMonitoringAudioFrame 回调。
参数
- sampleRate
- onEarMonitoringAudioFrame 中报告音频的采样率 (Hz),可设置为 8000、 16000、 32000、44100 或 48000。
- channel
-
onEarMonitoringAudioFrame 中报告音频的声道数,可设置为 1 或 2:
- 1: 单声道。
- 2: 双声道。
- mode
-
音频帧的使用模式,详见 AgoraAudioRawFrameOperationMode。
- samplesPerCall
- onEarMonitoringAudioFrame 中报告的音频的采样点数,如旁路推流应用中通常为 1024。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setEnableSpeakerphone
开启或关闭扬声器播放。
- (int)setEnableSpeakerphone:(BOOL)enableSpeaker;
如果 SDK 默认的音频路由(见音频路由)或 setDefaultAudioRouteToSpeakerphone 的设置无法满足你的需求,你可以调用 setEnableSpeakerphone 切换当前的音频路由。成功改变音频路由后,SDK 会触发 didAudioRouteChanged 回调。
该方法只设置用户在当前频道内使用的音频路由,不会影响 SDK 默认的音频路由。如果用户离开当前频道并加入新的频道,则用户还是会使用 SDK 默认的音频路由。
- 该方法需要在加入频道后调用。
- 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备,则该方法的设置无效,音频只会通过外接设备播放。当有多个外接设备时,音频会通过最后一个接入的设备播放。
参数
- enableSpeaker
-
设置是否开启扬声器播放:
YES
: 开启。音频路由为扬声器。NO
: 关闭。音频路由为听筒。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setEncryptionMode
启用内置的加密方案。
- (int)setEncryptionMode:(NSString * _Nullable)encryptionMode;
- 弃用:
- 请改用 enableEncryption 方法。
Agora Video SDK 支持内置加密方案,默认支持 AES-128-GCM。如需采用其他加密方案,可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别,请参考 AES 加密算法的相关资料。
参数
- encryptionMode
-
加密模式:
- "
aes-128-xts
": 128 位 AES 加密,XTS 模式; - "
aes-128-ecb
": 128 位 AES 加密,ECB 模式; - "
aes-256-xts
": 256 位 AES 加密,XTS 模式; - "
sm4-128-ecb
": 128 位 SM4 加密,ECB 模式; - "
aes-128-gcm
": 128 位 AES 加密,GCM 模式; - "
aes-256-gcm
": 256 位 AES 加密,GCM 模式; - "": 设置为空字符串时,默认使用加密方式 "
aes-128-gcm
"。
- "
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEncryptionSecret
启用内置加密,并设置数据加密密码。
- (int)setEncryptionSecret:(NSString * _Nullable)secret;
- 弃用:
- 请改用 enableEncryption 方法。
在加入频道之前, app 需调用该方法指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。 当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。
- 请不要在旁路推流时调用此方法。
- 为保证最佳传输效果,请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
参数
- secret
- 加密密码。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setExtensionPropertyWithVendor
设置插件的属性。
- (int)setExtensionPropertyWithVendor:(NSString * __nonnull)provider extension:(NSString * __nonnull)extension key:(NSString * __nonnull)key value:(NSString * __nonnull)value;
开启插件后,你可以调用该方法设置插件的属性。
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- key
- 插件属性的 Key。
- value
- 插件属性 Key 对应的值。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setExtensionProviderPropertyWithVendor
设置插件服务商的属性。
- (int) setExtensionProviderPropertyWithVendor:(NSString * __nonnull)provider key:(NSString * __nonnull)key value:(NSString * __nonnull)value;
你可以调用该方法设置插件服务商的属性,并根据服务商的类型初始化相关参数。
该方法需要在 enableExtensionWithVendor 之后、且启用音频(enableAudio/enableLocalAudio)或启用视频(enableVideo/enableLocalVideo)之前调用。
参数
- provider
- 提供插件的服务商名称。
- key
- 插件属性的 Key。
- value
- 插件属性 Key 对应的值。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableExternalAudioSink
设置外部音频渲染。
- (void)enableExternalAudioSink:(BOOL)enabled sampleRate:(NSUInteger)sampleRate channels:(NSUInteger)channels;
该方法适用于需要自行渲染音频的场景。开启外部音频渲染后,你可以调用 pullPlaybackAudioFrameRawData 拉取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染,获取想要的音频效果。
参数
- enabled
-
设置是否开启外部音频渲染:
YES
:开启外部音频渲染。NO
:(默认)关闭外部音频渲染。
- sampleRate
-
外部音频渲染的采样率 (Hz),可设置为 16000,32000,44100 或 48000。
- channels
- 外部音频渲染的声道数,可设置为 1 或 2:
- 1: 单声道
- 2: 双声道
setExternalAudioSource [1/2]
设置外部音频采集参数。
- (int)setExternalAudioSource:(BOOL)enabled sampleRate:(NSInteger)sampleRate channels:(NSInteger)channels;
请在 joinChannelByToken [1/4] 和 startPreview [1/2] 前调用该方法。
参数
- enabled
-
YES
: 开启使用外部音频源的功能。NO
: (默认)关闭使用外部音频源的功能。
- sampleRate
- 外部音频源的采样率 (Hz),可设置为 8000,16000,32000,44100 或 48000。
- channels
-
外部音频源的通道数,可设置为 1 或 2:
- 1: 单声道
- 2: 双声道
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setExternalAudioSource [2/2]
设置外部音频采集参数。
- (int)setExternalAudioSource:(BOOL)enabled sampleRate:(NSInteger)sampleRate channels:(NSInteger)channels sourceNumber:(NSInteger)sourceNumber localPlayback:(BOOL)localPlayback publish:(BOOL)publish;
参数
- enabled
-
是否开启使用外部音频源的功能:
YES
:开启外部音频源。NO
:(默认)关闭外部音频源。
- sampleRate
- 外部音频源的采样率 (Hz),可设置为
8000
,16000
,32000
,44100
或48000
。 - channels
- 外部音频源的声道数,可设置为
1
(单声道)或2
(双声道)。 - sourceNumber
- 外部音频源的数量,取值为正整数。SDK 会根据该参数值创建对应数量的自采集音频轨道,并从 0 开始为音频轨道命名。你可以在 AgoraRtcChannelMediaOptions 中,设置 publishCustomAudioSourceId 为你想要发布的音频轨道 ID。
- localPlayback
-
是否在本地播放外部音频源:
YES
:在本地播放。NO
:(默认)不在本地播放。
- publish
-
是否将音频发布到远端:
YES
:(默认)发布到远端。NO
:不发布到远端。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
setExternalVideoSource
设置外部视频源。
- (void)setExternalVideoSource:(BOOL)enable useTexture:(BOOL)useTexture sourceType:(AgoraExternalVideoSourceType)sourceType;
参数
- enable
- 是否启用外部视频源:
YES
: 启用外部视频源。SDK 准备接收外部视频帧。NO
:(默认)不启用外部视频源。
- useTexture
- 是否使用 texture 格式的外部视频帧:
YES
: 使用 texture 格式的外部视频帧。NO
: 不使用 texture 格式的外部视频帧。
- sourceType
- 是否对外部视频帧编码,详见 AgoraExternalVideoSourceType。
setInEarMonitoringVolume
设置耳返音量。
- (int)setInEarMonitoringVolume:(NSInteger)volume;
- 用户必须使用有线耳机才能听到耳返效果。
- 该方法在加入频道前后都能调用。
参数
- volume
- 设置耳返音量,取值范围在 [0,100]。默认值为 100。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalAccessPoint
配置与声网私有媒体服务器 Native 接入模块的连接。
- (int)setLocalAccessPoint:(AgoraLocalAccessPointConfiguration* _Nonnull)config NS_SWIFT_NAME(setLocalAccessPoint(withConfig:));
成功部署声网私有媒体服务器并在内网终端集成 Agora Native SDK v4.0.0 后,你可以调用该方法指定 Local Access Point,给 SDK 分配 Native 接入模块。
- 该方法仅在部署声网混合云方案后生效。你可以联系 sales@agora.io 了解和部署声网混合云。
- 该方法需要在加入频道前调用。
参数
- config
- Local Access Point 配置。详见 AgoraLocalAccessPointConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalRenderMode [1/2]
设置本地视图显示模式。
- (int)setLocalRenderMode:(NSUInteger)uid mode:(AgoraVideoRenderMode) mode;
- 弃用:
- 该方法已废弃,请使用 setLocalRenderMode [2/2] 作为替代。
该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。
参数
- mode
-
本地视图显示模式。详见 AgoraVideoRenderMode。
- uid
- 用户 ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalRenderMode [2/2]
更新本地视图显示模式。
- (int)setLocalRenderMode:(AgoraVideoRenderMode)mode mirror:(AgoraVideoMirrorMode)mirror;
初始化本地用户视图后,你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面,不影响本地发布视频。
- 请在调用 setupLocalVideo 方法初始化本地视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新本地用户视图的显示模式。
参数
- mode
-
本地视图显示模式。详见 AgoraVideoRenderMode。
- mirror
-
本地视图的镜像模式,详见 AgoraVideoMirrorMode。
注意: 如果你使用前置摄像头,默认启动本地用户视图镜像模式;如果你使用后置摄像头,默认关闭本地视图镜像模式。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalVideoMirrorMode
设置本地视频镜像。
- (int)setLocalVideoMirrorMode:(AgoraVideoMirrorMode)mode;
- 弃用:
- 该方法已废弃。
参数
- mode
-
本地视频镜像模式。详见 AgoraVideoMirrorMode。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalVoiceEqualizationOfBandFrequency
设置本地语音音效均衡。
- (int)setLocalVoiceEqualizationOfBandFrequency:(AgoraAudioEqualizationBandFrequency)bandFrequency withGain:(NSInteger)gain;
参数
- bandFrequency
- 频谱子带索引。取值范围是 [0,9],分别代表音效的 10 个频带。对应的中心频率为 [31,62,125,250,500,1k,2k,4k,8k,16k] Hz。详见 AgoraAudioEqualizationBandFrequency 。
- gain
- 每个 band 的增益,单位是 dB,每一个值的范围是 [-15,15],默认值为 0。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalVoicePitch
设置本地语音音调。
- (int)setLocalVoicePitch:(double)pitch;
参数
- pitch
- 语音频率。可以 [0.5,2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalVoiceReverbOfType
设置本地音效混响。
- (int)setLocalVoiceReverbOfType:(AgoraAudioReverbType)reverbType withValue:(NSInteger)value;
SDK 提供一个使用更为简便的方法 setAudioEffectPreset,直接实现流行、R&B、KTV 等预置的混响效果。
参数
- reverbType
- 混响音效 Key。该方法共有 5 个混响音效 Key,详见 AgoraAudioReverbType。
- value
- 各混响音效 Key 所对应的值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalVoiceReverbPreset
设置本地语音混响(含虚拟立体声效果)。
- (int) setLocalVoiceReverbPreset:(AgoraAudioReverbPreset)reverbPreset;
- 弃用:
- 请改用 setAudioEffectPreset 或 setVoiceBeautifierPreset。
通信场景下的用户或直播场景下的主播均可调用该方法设置本地语音混响。成功设置以后,频道内的所有用户均可听到声音效果。
- 当使用以
AUDIO_REVERB_FX
为前缀的枚举值时,请确保在调用该方法前将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileMusicHighQuality (4) 或 AgoraAudioProfileMusicHighQualityStereo (5) ,否则该方法设置无效。 - 当使用 AUDIO_VIRTUAL_STEREO 时,Agora 推荐在调用该方法前将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileMusicHighQualityStereo (5)。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含人声和音乐的音频数据。
- 该方法在加入频道前后都能调用。
参数
- reverbPreset
本地语音混响选项,默认值为 AgoraAudioReverbPresetOff ,即原声。详见 AgoraAudioReverbPreset 。为达到更好的混响效果,Agora 推荐使用以
AUDIO_REVERB_FX
为前缀的枚举值。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLogFile
设置日志文件
- (int)setLogFile:(NSString * _Nonnull)filePath;
- 弃用:
- 此方法已废弃,请改用 sharedEngineWithConfig 中的
logConfig
参数设置日志文件路径 。
设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。App 必须保证指定的目录存在而且可写。
如需调用本方法,请在调用 sharedEngineWithConfig 方法初始化 AgoraRtcEngineKit 对象后立即调用,否则输出日志可能不完整。
参数
- filePath
- 日志文件的完整路径。该日志文件为 UTF-8 编码。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLogFileSize
设置 SDK 输出的日志文件的大小。
- (int)setLogFileSize:(NSUInteger)fileSizeInKBytes;
- 弃用:
- 该方法已废弃,请改用 sharedEngineWithConfig 中的
logConfig
参数设置日志文件大小。
默认情况下,SDK 会生成 5 个 SDK 日志文件和 5 个 API 调用日志文件,规则如下:
- SDK 日志文件的名称分别为:
agorasdk.log
、agorasdk.1.log
、agorasdk.2.log
、agorasdk.3.log
、agorasdk.4.log
。 - API 调用日志文件的名称分别为:
agoraapi.log
、agoraapi.1.log
、agoraapi.2.log
、agoraapi.3.log
、agoraapi.4.log
。 - 每个 SDK 日志文件的默认大小为 1,024 KB;API 调用日志文件的默认大小为 2,048 KB。日志文件均为 UTF-8 编码。
- 最新的日志永远写在
agorasdk.log
和agoraapi.log
中。 - 当
agorasdk.log
写满后,SDK 会按照以下顺序对日志文件进行操作:- 删除
agorasdk.4.log
文件(如有)。 - 将
agorasdk.3.log
重命名为agorasdk.4.log
。 - 将
agorasdk.2.log
重命名为agorasdk.3.log
。 - 将
agorasdk.1.log
重命名为agorasdk.2.log
。 - 新建
agorasdk.log
文件。
- 删除
agoraapi.log
文件的覆盖规则与agorasdk.log
相同。
该方法仅用于设置 agorasdk.log
文件的大小,对agoraapi.log
不生效。
参数
- fileSizeInKBytes
-
单个
agorasdk.log
日志文件的大小,单位为 KB,取值范围为 [128,20480],默认值为 1,024 KB。 如果你将fileSizeInKByte
设为小于 128 KB,SDK 会自动调整到 128 KB;如果你将fileSizeInKByte
设为大于 20,480 KB,SDK 会自动调整到 20,480 KB。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLogFilter
设置日志输出等级。
- (int)setLogFilter:(NSUInteger)filter;
- 弃用:
- 请改用 sharedEngineWithConfig 中的 logConfig。
该方法设置 Agora SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 AgoraLogFilterOff、AgoraLogFilterCritical、AgoraLogFilterError、AgoraLogFilterWarning、AgoraLogFilterInfo 和 AgoraLogFilterDebug。 选择一个级别,你就可以看到在该级别之前所有级别的日志信息。
例如,你选择 AgoraLogFilterWarning 级别,就可以看到在 AgoraLogFilterCritical、AgoraLogFilterError 和 AgoraLogFilterWarning 级别的日志信息。
参数
- filter
-
日志过滤等级。详见 AgoraLogFilter。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLogLevel
设置 SDK 的日志输出级别。
- (int)setLogLevel:(AgoraLogLevel)level;
- 弃用:
- 该方法已经废弃。请改用 AgoraRtcEngineConfig 设置日志输出级别。
选择一个级别,你就可以看到该级别的日志信息。
参数
- level
- 日志级别: AgoraLogLevel。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setMediaMetadataDataSource
设置 metadata 的 Data source。
- (BOOL)setMediaMetadataDataSource:(id<AgoraMediaMetadataDataSource> _Nullable)metadataDataSource withType:(AgoraMetadataType)type;
你需要在该方法中实现一个 AgoraMediaMetadataDataSource 协议,并指定 metadata 的数据类型。成功调用该方法后,SDK 会触发 metadataMaxSize 回调。
该接口可以与 setMediaMetadataDelegate 接口搭配使用,在直播场景中实现发送商品链接、分发优惠券、发送答题等功能,构建更为丰富的直播互动方式。
参数
- metadataDataSource
- AgoraMediaMetadataDataSource 协议。
- type
-
metadata 类型。目前仅支持 AgoraMetadataTypeVideo。详见 AgoraMetadataType。
返回值
YES
:方法调用成功。NO
:方法调用失败。
setMixedAudioFrameParametersWithSampleRate
设置 onMixedAudioFrame 报告的音频数据格式。
- (int)setMixedAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel samplesPerCall:(NSInteger)samplesPerCall;
参数
- sampleRate
-
音频数据采样率 (Hz),可设置为
8000
、16000
、32000
、44100
或48000
。
- channel
-
音频数据声道数,可设置为
1
(单声道) 或2
(双声道)。
- samplesPerCall
-
音频数据采样点数。旁路推流场景下通常设为
1024
。
SDK 会根据该方法设置的采样间隔(秒)定期触发 onMixedAudioFrame 回调。 采样间隔 = samplesPerCall
/(sampleRate
x channel
)。请确保你的取值能满足采样间隔大于或等于 0.01 秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setPlaybackAudioFrameBeforeMixingParametersWithSampleRate
设置 onPlaybackAudioFrameBeforeMixing 报告的音频数据格式。
- (int)setPlaybackAudioFrameBeforeMixingParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel;
参数
- sampleRate
-
音频数据采样率 (Hz),可设置为
8000
、16000
、32000
、44100
或48000
。
- channel
-
音频数据声道数,可设置为
1
(单声道) 或2
(双声道) 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setPlaybackAudioFrameParametersWithSampleRate
设置播放的音频格式。
- (int)setPlaybackAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel mode:(AgoraAudioRawFrameOperationMode)mode samplesPerCall:(NSInteger)samplesPerCall;
该方法设置 onPlaybackAudioFrame 回调数据的格式。
- 该方法需要在加入频道前调用。
- SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 onPlaybackAudioFrame 回调。
参数
- sampleRate
- onPlaybackAudioFrame 中返回数据的采样率,可设置为 8000、 16000、 32000、44100 或 48000。
- channel
-
onPlaybackAudioFrame 中返回数据的通道数,可设置为 1 或 2:
- 1: 单声道
- 2: 双声道
- mode
-
音频帧的使用模式,详见 AgoraAudioRawFrameOperationMode。
- samplesPerCall
- onPlaybackAudioFrame 中返回数据的采样点数,如旁路推流应用中通常为 1024。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRecordingAudioFrameParametersWithSampleRate
设置采集的原始音频数据格式。
- (int)setRecordingAudioFrameParametersWithSampleRate:(NSInteger)sampleRate channel:(NSInteger)channel mode:(AgoraAudioRawFrameOperationMode)mode samplesPerCall:(NSInteger)samplesPerCall;
该方法设置 onRecordAudioFrame 回调的采集音频格式。
- 该方法需要在加入频道前调用。
- SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 onRecordAudioFrame 回调。
参数
- sampleRate
- onRecordAudioFrame 中返回数据的采样率,可设置为 8000、 16000、 32000、44100 或 48000。
- channel
-
onRecordAudioFrame 中返回数据的通道数,可设置为 1 或 2:
- 1: 单声道。
- 2: 双声道。
- mode
-
音频帧的使用模式,详见 AgoraAudioRawFrameOperationMode。
- samplesPerCall
- onRecordAudioFrame 中返回数据的采样点数,如旁路推流应用中通常为 1024。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRemoteDefaultVideoStreamType
设置默认订阅的视频流类型。
- (int)setRemoteDefaultVideoStreamType:(AgoraVideoStreamType)streamType;
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode [3/3] (NO)
关闭双流模式,接收端可以选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需默认接收所有用户的视频小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
调用本方法的执行结果将在 didApiCallExecute 中返回。
- 该方法只能在加入频道前调用。Agora 不支持你在加入频道后修改默认订阅的视频流类型。
- 如果你既调用了该方法,也调用了 setRemoteVideoStream,则 SDK 以 setRemoteVideoStream 中的设置为准。
参数
- streamType
-
默认订阅的视频流类型: AgoraVideoStreamType。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteRenderMode [1/2]
设置远端视图显示模式。
- (int)setRemoteRenderMode:(NSUInteger)uid mode:(AgoraVideoRenderMode) mode;
- 弃用:
- 该方法已废弃,请使用 setRemoteRenderMode [2/2]。
该方法设置远端视图显示模式。App 可以多次调用此方法更改显示模式。
参数
- userId
- 远端用户 ID。
- renderMode
-
远端用户视图的渲染模式,详见 AgoraVideoRenderMode。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRemoteRenderMode [2/2]
更新远端视图显示模式。
- (int)setRemoteRenderMode:(NSUInteger)uid mode:(AgoraVideoRenderMode)mode mirror:(AgoraVideoMirrorMode)mirror;
初始化远端用户视图后,你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。
- 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
- uid
- 远端用户 ID。
- mode
-
远端用户视图的渲染模式,详见 AgoraVideoRenderMode。
- mirror
-
远端用户视图的镜像模式,详见 AgoraVideoMirrorMode。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRemoteVideoStream
设置订阅的视频流类型。
- (int)setRemoteVideoStream:(NSUInteger)uid type:(AgoraVideoStreamType)streamType;
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode [3/3](NO) 关闭双流模式,接收端可以选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
调用本方法的执行结果将在 didApiCallExecute 中返回。
参数
- uid
- 用户 ID。
- streamType
-
视频流类型: AgoraVideoStreamType 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVoicePosition
设置远端用户声音的 2D 位置,即水平面位置。
- (int)setRemoteVoicePosition:(NSUInteger)uid pan:(double)pan gain:(double)gain;
设置远端用户声音的 2D 位置和音量,方便本地用户听声辨位。
通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。
- 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声。
- 为获得最佳听觉体验,我们建议使用该方法时使用有线耳机。
- 该方法需要在加入频道后调用。
参数
- uid
- 远端用户的 ID
- pan
- 设置远端用户声音的 2D 位置,取值范围为 [-1.0,1.0]:
- (默认)0.0: 声音出现在正前方。
- -1.0: 声音出现在左边。
- 1.0: 声音出现在右边。
- gain
- 设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setSubscribeAudioBlacklist
设置音频订阅黑名单。
- (int)setSubscribeAudioBlacklist:(NSArray <NSNumber *> *_Nonnull)blacklist;
你可以调用该方法指定不订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅黑名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeAudio 影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- blacklist
-
订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeAudioBlacklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeAudioWhitelist
设置音频订阅白名单。
- (int)setSubscribeAudioWhitelist:(NSArray <NSNumber *> *_Nonnull)whitelist;
你可以调用该方法指定想要订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅白名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeAudio 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- whitelist
-
音频订阅白名单的用户 ID 列表。
如果你想指定订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeAudioWhitelist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoBlacklist
设置视频订阅黑名单。
- (int)setSubscribeVideoBlacklist:(NSArray <NSNumber *> *_Nonnull)blacklist;
你可以调用该方法指定不订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅黑名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- blacklist
-
视频订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeVideoBlacklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoWhitelist
设置视频订阅白名单。
- (int)setSubscribeVideoWhitelist:(NSArray <NSNumber *> *_Nonnull)whitelist;
你可以调用该方法指定想要订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅白名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 AgoraRtcChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
-
视频订阅白名单的用户 ID 列表。
如果你想指定仅订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeVideoWhitelist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setupLocalVideo
初始化本地视图。
- (int)setupLocalVideo:(AgoraRtcVideoCanvas * _Nullable)local;
该方法初始化本地视图并设置本地用户视频显示属性,只影响本地用户看到的视频画面,不影响本地发布视频。调用该方法绑定本地视频流的显示视窗(view),并设置本地用户视图的渲染模式和镜像模式。
在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入频道。退出频道后,绑定仍然有效,如果需要解除绑定,可以调用该方法将参数 view 设为 nil。
- 该方法在加入频道前后都能调用。
- 如果你希望在通话中更新本地用户视图的渲染或镜像模式,请使用 setLocalRenderMode [2/2] 方法。
参数
- local
- 本地视频显示属性。详见 AgoraRtcVideoCanvas。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setupRemoteVideo
初始化远端用户视图。
- (int)setupRemoteVideo:(AgoraRtcVideoCanvas * _Nonnull)remote;
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。
调用该方法时需要指定远端视频的用户 ID,一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID,可以在收到 didJoinedOfUid 回调时调用该方法。
如需解除某个远端用户的绑定视图,可以调用该方法并将 view 设置为空。
离开频道后,SDK 会清除远端用户视图的绑定关系。
- 如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 setRemoteRenderMode [2/2] 方法。
- 如果你使用了 Agora 录制服务,录制服务会作为一个哑客户端加入频道,因此也会触发 didJoinedOfUid 回调。由于录制服务不会发送视频流,app 无需为它绑定视图。如果 app 无法识别哑客户端,可以在收到 firstRemoteVideoDecodedOfUid 回调时再绑定远端用户视图。
参数
- remote
-
远端视频显示属性。详见 AgoraRtcVideoCanvas。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setVideoDenoiserOptions
设置视频降噪功能。
- (int)setVideoDenoiserOptions:(BOOL)enable options:(AgoraVideoDenoiserOptions* _Nullable)options NS_SWIFT_NAME(setVideoDenoiserOptions(_:options:));
采光不足的环境和低端视频采集设备会使视频图像含有明显的噪声,影响视频画质。在实时互动场景下,视频噪声还会在编码过程中占用码流资源并降低编码效率。
你可以调用该方法开启视频降噪功能并设置视频降噪的效果。
- 请在 enableVideo 后调用该方法。
- 视频降噪对设备性能有一定要求。开启视频降噪后,如果设备出现严重发烫等问题,Agora 推荐你将视频降噪等级修改为消耗性能较少的等级或关闭视频降噪功能。
- 该方法和 setExtensionPropertyWithVendor 均可开启视频降噪功能:
- 当你使用 SDK 采集视频时,Agora 推荐使用该方法(该方法只可对 SDK 采集的视频起作用)。
- 当你使用外部的视频源实现自定义视频采集,或者将外部视频源发送给 SDK 时,Agora 推荐使用 setExtensionPropertyWithVendor 方法。
参数
- enable
- 是否开启视频降噪功能:
YES
: 开启视频降噪功能。NO
:(默认)关闭视频降噪功能。
- options
- 视频降噪选项,用于设置视频降噪的效果。详见 AgoraVideoDenoiserOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoEncoderConfiguration
设置视频编码属性。
- (int)setVideoEncoderConfiguration:(AgoraVideoEncoderConfiguration * _Nonnull)config;
设置本地视频的编码属性。
参数
- config
- 视频编码参数配置。详见 AgoraVideoEncoderConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoProfile [1/2]
设置视频编码配置。
- (int)setVideoProfile:(AgoraVideoProfile)profile swapWidthAndHeight:(BOOL)swapWidthAndHeight
- 弃用:
- 该方法已废弃。请改用 setVideoEncoderConfiguration 方法。
该方法设置视频的编码属性。 该方法在加入频道前后都能调用。 如果用户加入频道后不需要重新设置视频编码属性,则 Agora 建议在 enableVideo 前调用该方法,可以加快首帧出图的时间。
参数
- profile
-
视频属性。详见 AgoraVideoProfile。
- swapWidthAndHeight
-
SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高:
YES
: 交换宽和高NO
: 不交换宽和高(默认)
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVideoProfile [2/2]
手动设置视频编码配置。
- (int)setVideoResolution:(CGSize)size andFrameRate:(NSInteger)frameRate bitrate:(NSInteger)bitrate;
- 弃用:
- 该方法已废弃。请改用 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 会自动按照合理区间处理码率。
setVideoQualityParameters
设置视频优化选项(仅适用于直播)。
- (int)setVideoQualityParameters:(BOOL)preferFrameRateOverImageQuality;
- 弃用:
- 该方法已废弃。Agora 建议使用 AgoraVideoEncoderConfiguration 类中的 degradationPreference 参数设置视频质量偏好。
参数
- preferFrameRateOverImageQuality
-
画质和流畅度里,是否优先保证流畅度:
YES
:优先保证流畅度。NO
: (默认)优先保证画质。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVoiceBeautifierParameters
设置预设美声效果的参数。
- (int)setVoiceBeautifierParameters:(AgoraVoiceBeautifierPreset)preset param1:(int)param1 param2:(int)param2;
调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后,频道内所有用户都能听到该效果。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AgoraAudioScenarioGameStreaming(3),并将 profile 设为 AgoraAudioProfileMusicHighQuality(4) 或 AgoraAudioProfileMusicHighQualityStereo(5)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileSpeechStandard(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceBeautifierParameters,Agora 不推荐调用以下方法,否则 setVoiceBeautifierParameters 设置的效果会被覆盖:
参数
- preset
- 预设的音效:
SINGING_BEAUTIFIER
: 歌唱美声。
- param1
- 歌声的性别特征:
1
: 男声。2
: 女声。
- param2
- 歌声的混响效果:
1
: 歌声在小房间的混响效果。2
: 歌声在大房间的混响效果。3
: 歌声在大厅的混响效果。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVoiceBeautifierPreset
设置预设的美声效果。
- (int)setVoiceBeautifierPreset:(AgoraVoiceBeautifierPreset)preset;
调用该方法可以为本地发流用户设置预设的人声美化效果。设置美声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的美声效果。各美声效果的适用场景可参考设置人声效果。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AgoraAudioScenarioGameStreaming(3),并将 profile 设为 AgoraAudioProfileMusicHighQuality(4) 或 AgoraAudioProfileMusicHighQualityStereo(5)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileSpeechStandard(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceBeautifierPreset,Agora 不推荐调用以下方法,否则 setVoiceBeautifierPreset 设置的效果会被覆盖:
参数
- preset
-
预设的美声效果选项,详见 AgoraVoiceBeautifierPreset。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVoiceConversionPreset
设置预设的变声效果。
- (int)setVoiceConversionPreset:(AgoraVoiceConversionPreset)preset;
调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的变声效果。各变声效果的适用场景可参考《设置人声效果》。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile [1/2] 的 profile 设为 AgoraAudioProfileMusicHighQuality(4) 或 AgoraAudioProfileMusicHighQualityStereo(5),并将 scenario 设为 AgoraAudioScenarioGameStreaming(3)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 AgoraAudioProfileSpeechStandard(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceConversionPreset 后,Agora 不推荐调用以下方法,否则 setVoiceConversionPreset 设置的效果会被覆盖:
参数
- preset
-
预设的变声效果选项: AgoraVoiceConversionPreset。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
startAudioMixing [1/2]
开始播放音乐文件。
- (int)startAudioMixing:(NSString * _Nonnull)filePath loopback:(BOOL)loopback replace:(BOOL)replace cycle:(NSInteger)cycle;
- 弃用:
- 请改用 startAudioMixing [2/2]。
该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后,本地会触发 audioMixingStateChanged (AgoraAudioMixingStateTypePlaying) 回调。播放结束后,本地会触发 audioMixingStateChanged (AgoraAudioMixingStateTypeStopped) 回调。
- 该方法在加入频道前后均可调用。如需多次调用 startAudioMixing [1/2],请确保调用间隔大于 500 ms。
- 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL,则 SDK 会报告警告码 701。
参数
- filePath
-
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见支持的媒体格式。 - loopback
-
是否只在本地播放音乐文件:
YES
: 只在本地播放音乐文件,只有本地用户能听到音乐。NO
: 将本地播放的音乐文件发布至远端,本地用户和远端用户都能听到音乐。
- cycle
-
音乐文件的播放次数。
- ≥ 0: 播放次数。例如,0 表示不播放;1 表示播放 1 次。
- -1: 无限循环播放。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioMixing [2/2]
开始播放音乐文件。
- (int)startAudioMixing:(NSString* _Nonnull)filePath loopback:(BOOL)loopback cycle:(NSInteger)cycle startPos:(NSInteger)startPos;
该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后,本地会触发 audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
回调。播放结束后,本地会触发 audioMixingStateChanged(AgoraAudioMixingStateTypeStopped)
回调。
- 该方法在加入频道前后均可调用。如需多次调用 startAudioMixing [2/2],请确保调用间隔大于 500 ms。
- 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL,则 SDK 会报告警告码 701。
- 该方法支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。
参数
- filePath
- 文件路径:
- iOS 或 macOS: 音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。
- iOS 或 macOS: 音频文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
- loopback
-
是否只在本地播放音乐文件:
YES
: 只在本地播放音乐文件,只有本地用户能听到音乐。NO
: 将本地播放的音乐文件发布至远端,本地用户和远端用户都能听到音乐。
- cycle
-
音乐文件的播放次数。
- ≥ 0: 播放次数。例如,0 表示不播放;1 表示播放 1 次。
- -1: 无限循环播放。
- startPos
- 音乐文件的播放位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioRecording [1/2]
开始客户端录音。
- (int)startAudioRecording:(NSString * _Nonnull)filePath quality:(AgoraAudioRecordingQuality)quality;
- 弃用:
- 该方法已废弃,其默认录音采样率为 32 kHz,不可修改。请改用新的 startAudioRecording [2/2] 方法。
.wav
: 文件大,音质保真度高;.aac
: 文件小,有一定的音质保真度损失。
请确保 App 里指定的目录存在且可写。该接口需在 joinChannelByToken [1/4] 之后调用。如果调用 leaveChannel [1/2] 时还在录音,录音会自动停止。
参数
- filePath
- 录音文件在本地保存的绝对路径,需精确到文件名及格式。例如:
/var/mobile/Containers/Data/audio.mp4
。注意:请确保你指定的路径存在并且可写。
- quality
- 录音质量。详见 AgoraAudioRecordingQuality 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioRecording [2/2]
开始客户端录音。
- (int)startAudioRecordingWithConfig:(AgoraAudioRecordingConfiguration * _Nonnull)config;
- WAV: 音质保真度较高,文件较大。例如,采样率为 32000 Hz,录音时长为 10 分钟的文件大小约为 73 M。
- AAC: 音质保真度较低,文件较小。例如,采样率为 32000 Hz,录音音质为 AgoraAudioRecordingQualityMedium,录音时长为 10 分钟的文件大小约为 2 M。
用户离开频道后,录音会自动停止。
参数
- config
- 录音配置。详见 AgoraAudioRecordingConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startChannelMediaRelay
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
- (int)startChannelMediaRelay:(AgoraChannelMediaRelayConfiguration * _Nonnull)config;
- 如果 channelMediaRelayStateDidChange 回调报告 AgoraChannelMediaRelayStateRunning (2) 和 AgoraChannelMediaRelayErrorNone (0),且 didReceiveChannelMediaRelayEvent 回调报告 AgoraChannelMediaRelayEventSentToDestinationChannel (4), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 channelMediaRelayStateDidChange 回调报告 AgoraChannelMediaRelayStateFailure (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
- 跨频道媒体流转发功能需要联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- config
- 跨频道媒体流转发参数配置。详见 AgoraChannelMediaRelayConfiguration。
返回值
- 0:方法调用成功
- < 0:方法调用失败
startDirectCdnStreaming
设置主播端开始直接向 CDN 推流。
- (int)startDirectCdnStreaming:(id<AgoraDirectCdnStreamingEventDelegate> _Nonnull)delegate publishUrl:(NSString * _Nonnull)publishUrl mediaOptions:(AgoraDirectCdnStreamingMediaOptions * _Nonnull)options;
Agora 不支持同一时间向同一个 URL 重复推流。
媒体选项说明
Agora 不支持 publishCameraTrack 和 publishCustomVideoTrack 同时为 YES
,也不支持 publishMicrophoneTrack 和 publishCustomAudioTrack 同时为 YES
。你可以根据场景需求设置媒体选项 (AgoraDirectCdnStreamingMediaOptions)。示例如下:
如果你想推送主播端采集的音视频流,请将媒体选项进行如下设置:
- publishCustomAudioTrack 设为
YES
并调用 pushExternalAudioFrameSampleBuffer 或 pushExternalAudioFrameNSData - publishCustomVideoTrack 设为
YES
并调用 pushExternalVideoFrame - 确保 publishCameraTrack 为
NO
(默认值) - 确保 publishMicrophoneTrack 为
NO
(默认值)
参数
- delegate
- 详见 onDirectCdnStreamingStateChanged 及 onDirectCdnStreamingStats。
- publishUrl
- CDN 推流 URL。
- options
- 主播端的媒体选项。详见 AgoraDirectCdnStreamingMediaOptions。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startEchoTest
开始语音通话回路测试。
- (int)startEchoTest:(void(^ _Nullable) (NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))successBlock;
- 弃用:
- 该方法已废弃,请改用 startEchoTestWithInterval。
该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在 10 秒后回放出来。如果 10 秒后用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。
- 请在加入频道前调用该方法。
- 调用 startEchoTest 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
- 直播场景下,该方法仅能由用户角色为主播的用户调用。
参数
- successBlock
- 成功开始语音通话测试回调。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startEchoTestWithInterval
开始语音通话回路测试。
- (int)startEchoTestWithInterval:(NSInteger)interval successBlock:(void(^ _Nullable) (NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))successBlock;
该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在设置的时间间隔(单位为秒)后回放出来。如果用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。
- 请在加入频道前调用该方法。
- 调用 startEchoTestWithInterval 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
- 直播场景下,该方法仅能由用户角色为主播的用户调用。
参数
- interval
- 设置返回语音通话回路测试结果的时间间隔,取值范围为 [2,10],单位为秒,默认为 10 秒。
- successBlock
- 成功开始语音通话测试回调。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startEchoTestWithConfig
开始音视频通话回路测试。
- (int)startEchoTestWithConfig:(AgoraEchoTestConfiguration* _Nonnull)config;
加入频道前,为测试用户本地发流、收流是否正常,你可以调用该方法进行音视频通话回路测试,即测试系统的音视频设备和用户的上下行网络是否正常。
- 请在加入频道前调用该方法。
- 调用该方法后,必须调用 stopEchoTest 结束测试,否则该用户无法进行下一次音视频通话回路测试, 也无法加入频道。
- 直播场景下,该方法仅能由主播调用。
参数
- config
- 音视频通话回路测试的配置。详见 AgoraEchoTestConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startLastmileProbeTest
开始通话前网络质量探测。
- (int)startLastmileProbeTest:(AgoraLastmileProbeConfig *_Nullable)config;
开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
- lastmileQuality,视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- lastmileProbeTestResult,视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。
- 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 调用该方法后,在收到 lastmileQuality 和 lastmileProbeTestResult 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
- 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
参数
- config
- Last mile 网络探测配置,详见 AgoraLastmileProbeConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startPreview [1/2]
开启视频预览。
- (int)startPreview;
- 调用 setupLocalVideo 设置预览窗口及属性。
- 调用 enableVideo 开启视频功能。
- 本地预览默认开启镜像功能。
- 如果调用 leaveChannel [1/2]退出频道,本地预览依然处于开启状态,如需要关闭本地预览,需要调用 stopPreview [1/2]。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
startPreview [2/2]
开启视频预览并指定预览的视频源。
- 调用 setupLocalVideo 设置预览窗口及属性。
- 调用 enableVideo 开启视频功能。
- 本地预览默认开启镜像功能。
- 如果调用 leaveChannel [1/2] 退出频道,本地预览依然处于开启状态,如需要关闭本地预览,需要调用 stopPreview [2/2]。
- 该方法中设置的视频源类型需要跟 setupLocalVideo 中 AgoraRtcVideoCanvas 的视频源类型一致。
参数
- sourceType
- 视频源的类型,详见 AgoraVideoSourceType。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
startRhythmPlayer
开启虚拟节拍器。
- (int)startRhythmPlayer:(NSString * _Nonnull)sound1 sound2:(NSString * _Nonnull)sound2 config:(AgoraRhythmPlayerConfig * _Nullable)config;
在音乐教学、体育教学等场景中,老师通常需要使用节拍器,让学生跟着正确的节拍练习。 节拍由强拍和弱拍组成,每小节的第一拍称为强拍,其余称为弱拍。
你需要在该方法中设置强拍和弱拍的文件路径、每小节的拍数、节拍速度以及是否将节拍器的声音发送至远端。
- 开启虚拟节拍器后,SDK 会从头开始播放指定的音频文件,并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如,将 beatsPerMinute 设为
60
,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。 - 虚拟节拍器的声音默认会发布至远端,如果你不希望远端用户听到虚拟节拍器的声音,你可以将 AgoraRtcChannelMediaOptions 中的 publishRhythmPlayerTrack 设为
NO
。
参数
- sound1
- 强拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。 - sound2
- 弱拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4
。支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。 - config
- 节拍器配置。详见 AgoraRhythmPlayerConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -22: 无法找到音频文件。请填写正确的 sound1 和 sound2。
startScreenCapture
开始屏幕共享。
- (int)startScreenCapture:(AgoraScreenCaptureParameters2* _Nonnull)parameters NS_SWIFT_NAME(startScreenCapture(_:));
- 在加入频道前调用该方法,然后调用 joinChannelByToken [2/4] 加入频道并设置 publishScreenCaptureVideo 为
YES
,即可开始屏幕共享。 - 在加入频道后调用该方法,然后调用 updateChannelWithMediaOptions 设置 publishScreenCaptureVideo 为
YES
,即可开始屏幕共享。
- AgoraLocalVideoStreamErrorExtensionCaptureStarted(13):屏幕共享 Extension 进程开启。
- AgoraLocalVideoStreamErrorExtensionCaptureStoped(14):屏幕共享 Extension 进程结束。
- AgoraLocalVideoStreamErrorExtensionCaptureDisconnected(15):屏幕共享 Extension 进程异常退出。
- 屏幕共享仅适用于 iOS 12.0 及以上。
- 屏幕共享流的计费以 AgoraScreenVideoParameters 中的 dimensions 值为准:当你未传值时,以 1280 × 720 计费;当你传值时,以你传入的值计费。详细的计费规则请参考计费说明。
- 如果你使用音频自采集而非 SDK 采集音频,为避免应用退后台后屏幕共享停止,Agora 建议你对应用添加保活处理逻辑。
- 该功能对设备性能要求较高,Agora 推荐你在 iPhone X 及之后机型上使用。
参数
- parameters
- 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2,073,600 像素。该像素值为计费标准。详见 AgoraScreenCaptureParameters2。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -2: 参数为空。
stopRhythmPlayer
setColorEnhanceOptions
设置色彩增强功能。
- (int)setColorEnhanceOptions:(BOOL)enable options:(AgoraColorEnhanceOptions* _Nullable)options NS_SWIFT_NAME(setColorEnhanceOptions(_:options:));
摄像头采集到的视频画面可能存在色彩失真的现象。色彩增强功能可以通过智能调节饱和度和对比度等视频特性,提升视频色彩丰富度和色彩还原度,最终使视频画面更生动。
你可以调用该方法开启色彩增强功能并设置色彩增强的效果。
- 请在 enableVideo 后调用该方法。
- 色彩增强对设备性能有一定要求。开启色彩增强后,如果设备出现严重发烫等问题,Agora 推荐你将色彩增强等级修改为消耗性能较少的等级或关闭色彩增强功能。
- 该方法和 setExtensionPropertyWithVendor 均可开启色彩增强功能:
- 当你使用 SDK 采集视频时,Agora 推荐使用该方法(该方法只可对 SDK 采集的视频起作用)。
- 当你使用外部的视频源实现自定义视频采集,或者将外部视频源发送给 SDK 时,Agora 推荐使用 setExtensionPropertyWithVendor 方法。
参数
- enable
- 是否开启色彩增强功能:
YES
:开启色彩增强功能。NO
:(默认)关闭色彩增强功能。
- options
- 色彩增强选项,用于设置色彩增强的效果。详见 AgoraColorEnhanceOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLowlightEnhanceOptions
设置暗光增强功能。
- (int)setLowlightEnhanceOptions:(BOOL)enable options:(AgoraLowlightEnhanceOptions* _Nullable)options NS_SWIFT_NAME(setLowlightEnhanceOptions(_:options:));
暗光增强功能可以在光线亮度偏低(如背光、阴天、暗场景)和亮度不均匀的环境下自适应调整视频画面的亮度值,恢复或凸显图像的细节信息,最终提升视频图像的整体视觉效果。
你可以调用该方法开启暗光增强功能并设置暗光增强的效果。
- 请在 enableVideo 后调用该方法。
- 暗光增强对设备性能有一定要求。开启暗光增强后,如果设备出现严重发烫等问题,Agora 推荐你将暗光增强等级修改为消耗性能较少的等级或关闭暗光增强功能。
- 该方法和 setExtensionPropertyWithVendor 均可开启暗光增强功能:
- 当你使用 SDK 采集视频时,Agora 推荐使用该方法(该方法只可对 SDK 采集的视频起作用)。
- 当你使用外部的视频源实现自定义视频采集,或者将外部视频源发送给 SDK 时,Agora 推荐使用 setExtensionPropertyWithVendor 方法。
参数
- enable
- 是否开启暗光增强功能:
YES
: 开启暗光增强功能。NO
:(默认)关闭暗光增强功能。
- options
- 暗光增强选项,用于设置暗光增强的效果。详见 AgoraLowlightEnhanceOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoEncoderConfiguration
设置视频编码属性。
- (int)setVideoEncoderConfiguration:(AgoraVideoEncoderConfiguration * _Nonnull)config;
设置本地视频的编码属性。
参数
- config
- 视频编码参数配置。详见 AgoraVideoEncoderConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startRtmpStreamWithoutTranscoding
开始非转码推流。
- (int)startRtmpStreamWithoutTranscoding:(NSString* _Nonnull)url;
调用该方法,你可以向指定的旁路推流地址推送直播音视频流。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
- 请确保已开通旁路推流服务。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
startRtmpStreamWithTranscoding
开始旁路推流并设置转码属性。
- (int)startRtmpStreamWithTranscoding:(NSString* _Nonnull)url transcoding:(AgoraLiveTranscoding* _Nullable)transcoding;
调用该方法,你可以向指定的旁路推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
- 请确保已开通旁路推流服务。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- transcoding
-
旁路推流的转码属性,详见 AgoraLiveTranscoding 类。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
stopAudioMixing
停止播放音乐文件。
- (int)stopAudioMixing;
该方法停止播放音乐文件。请在频道内调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopAudioRecording
停止客户端录音。
- (int)stopAudioRecording;
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopChannelMediaRelay
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
- (int)stopChannelMediaRelay;
成功调用该方法后,SDK 会触发 channelMediaRelayStateDidChange 回调。如果报告 AgoraChannelMediaRelayStateIdle (0) 和 AgoraChannelMediaRelayErrorNone (0),则表示已停止转发媒体流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
stopDirectCdnStreaming
设置主播端停止直接向 CDN 推流。
- (int)stopDirectCdnStreaming;
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopEchoTest
停止语音通话回路测试。
- (int)stopEchoTest;
返回值
- 0: 方法调用成功。
-
< 0: 方法调用失败。
- -5(ERR_REFUSED): 无法启动测试,可能没有成功初始化。
stopLastmileProbeTest
停止通话前网络质量探测。
- (int)stopLastmileProbeTest;
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopPreview [1/2]
停止视频预览。
- (int)stopPreview;
调用 startPreview [1/2] 开启预览后,如果你想关闭本地视频预览,请调用该方法。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
stopPreview [2/2]
停止视频预览。
调用 startPreview [2/2] 开启预览后,如果你想关闭本地视频预览,请调用该方法。
参数
- sourceType
- 视频源的类型,详见 AgoraVideoSourceType。
stopRtmpStream
结束旁路推流。
- (int)stopRtmpStream:(NSString* _Nonnull)url;
调用该方法,你可以结束指定的旁路推流地址上的直播。该方法每次只能结束一个推流地址上的直播,如果你需要结束多个推流地址的直播,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopScreenCapture
停止屏幕共享。
- (int)stopScreenCapture NS_SWIFT_NAME(stopScreenCapture());
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
switchCamera
切换前置/后置摄像头。
- (int)switchCamera;
该方法需要在相机启动(如通过调用 startPreview [1/2] 或 joinChannelByToken [2/4] 实现)后调用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
takeSnapshot
获取视频截图。
- (NSInteger)takeSnapshot:(NSInteger)uid filePath:(NSString* _Nonnull)filePath;
该方法用于对指定用户的视频流进行截图,生成一张 JPG 格式的图片,并保存至指定的路径。
该方法是异步操作,调用返回时 SDK 并没有真正获取截图。成功调用该方法后,SDK 会触发 snapshotTaken 回调报告截图是否成功和获取截图的详情。
- 该方法需要在加入频道后调用。
- 该方法对 AgoraRtcChannelMediaOptions 中指定发布的视频流进行截图。
- 如果用户的视频经过前处理,例如,添加了水印或美颜,生成的截图会包含前处理效果。
参数
- uid
- 用户 ID。如果要对本地用户的视频截图,则设为 0。
- filePath
-
截图的本地保存路径,需精确到文件名及格式, 例如:
- iOS:
/App Sandbox/Library/Caches/example.jpg
- iOS:
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
unregisterAudioSpectrumDelegate
取消注册音频频谱观测器。
- (int) unregisterAudioSpectrumDelegate:(id<AgoraAudioSpectrumDelegate> _Nullable)delegate;
调用 registerAudioSpectrumDelegate 后,如果你想取消注册音频频谱观测器,请调用该方法。
参数
- delegate
- 音频频谱观测器。详见 AgoraAudioSpectrumDelegate。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
updateChannelWithMediaOptions
加入频道后更新频道媒体选项。
- (int)updateChannelWithMediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions;
参数
- mediaOptions
- 频道媒体选项,详见 AgoraRtcChannelMediaOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:AgoraRtcChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是用户不在频道中。Agora 推荐通过 connectionChangedToState 回调判断用户是否在频道中。如果收到 AgoraConnectionStateDisconnected(1) 或 AgoraConnectionStateFailed(5),则表示用户不在频道中。你需要在调用该方法前调用 joinChannelByToken [2/4] 加入频道。
updateChannelMediaRelay
更新媒体流转发的频道。
- (int)updateChannelMediaRelay:(AgoraChannelMediaRelayConfiguration * _Nonnull)config;
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。
成功调用该方法后,SDK 会触发 didReceiveChannelMediaRelayEvent 回调, 并在回调中报告状态码 AgoraChannelMediaRelayEventUpdateDestinationChannel (7)。
channelMediaRelayStateDidChange(AgoraChannelMediaRelayStateRunning, AgoraChannelMediaRelayErrorNone)
后调用该方法;否则,方法调用会失败。参数
- config
- 跨频道媒体流转发参数配置。详见 AgoraChannelMediaRelayConfiguration 。
返回值
- 0:方法调用成功
- < 0:方法调用失败
updateRtmpTranscoding
更新旁路推流转码属性。
- (int)updateRtmpTranscoding:(AgoraLiveTranscoding* _Nullable)transcoding;
开启转码推流后,你可以根据场景需求,动态更新转码属性。转码属性更新后,SDK 会触发 rtcEngineTranscodingUpdated 回调。
参数
- transcoding
-
旁路推流的转码属性,详见 AgoraLiveTranscoding 类。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateScreenCapture
更新屏幕共享的参数配置。
- (int)updateScreenCapture:(AgoraScreenCaptureParameters2* _Nonnull)parameters NS_SWIFT_NAME(updateScreenCapture(_:));
参数
- parameters
- 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 AgoraScreenCaptureParameters2。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
ERR_INVALID_STATE
:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture 停止当前共享,再重新开始共享屏幕。ERR_INVALID_ARGUMENT
:传入的参数无效。