音效文件播放

getEffectCurrentPosition

获取指定音效文件的播放进度。

Objective-C

- (int)getEffectCurrentPosition:(int)soundId NS_SWIFT_NAME(getEffectCurrentPosition(_:));- (int)getEffectCurrentPosition:(int)soundId;

注意： 该方法需要在 playEffect [3/3] 后调用。

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。

返回值

• 方法调用成功，返回指定音效文件的播放进度（毫秒）。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

getEffectDuration

获取指定音效文件总时长。

Objective-C

- (int)getEffectDuration:(NSString* _Nonnull)filePath NS_SWIFT_NAME(getEffectDuration(_:));

注意： 该方法需要在加入频道后调用。

参数

参数名	描述
filePath	文件路径： iOS 或 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 /var/mobile/Containers/Data/audio.mp4。

返回值

• 方法调用成功，返回指定音效文件时长（毫秒）。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

getEffectsVolume

获取音效文件的播放音量。

Objective-C

- (int)getEffectsVolume;

音量范围为 0~100。100 （默认值）为原始文件音量。

注意： 该方法需要在 playEffect [3/3] 后调用。

返回值

• 音效文件的音量。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

getVolumeOfEffect

获取指定音效文件的播放音量。

Objective-C

- (int)getVolumeOfEffect:(int)soundId;

参数

参数名	描述
soundId	音效文件的 ID。

返回值

• ≥ 0: 方法调用成功，返回播放音量。音量范围为 [0,100]。100 为原始音量。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

pauseAllEffects

暂停所有音效文件播放。

Objective-C

- (int)pauseAllEffects;

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

pauseEffect

暂停音效文件播放。

Objective-C

- (int)pauseEffect:(int)soundId;

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

playEffect [1/3]

播放指定的本地或在线音效文件。

Objective-C

- (int)playEffect:(int)soundId
         filePath:(NSString* _Nonnull)filePath
        loopCount:(NSInteger)loopCount
            pitch:(double)pitch
              pan:(double)pan
             gain:(NSInteger)gain;

注意： 如果你需要通过该方法来播放在线音效文件，建议你先将在线音效文件缓存到本地设备，调用 preloadEffect 将缓存的音效文件预加载到内存中，然后再调用此方法播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。 你可以多次调用该方法，传入不同的 soundID 和 filePath，同时播放多个音效文件。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。音效文件播放结束后，SDK 会触发 rtcEngineDidAudioEffectFinish 回调。

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。 注意： 如果你已通过 preloadEffect 将音效加载至内存，请确保该参数与 preloadEffect 中设置的 soundId 相同。
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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

playEffect [2/3]

播放指定的本地或在线音效文件。

Objective-C

- (int)playEffect:(int)soundId
         filePath:(NSString* _Nonnull)filePath
        loopCount:(NSInteger)loopCount
            pitch:(double)pitch
              pan:(double)pan
             gain:(NSInteger)gain
          publish:(BOOL)publish;

注意： 如果你需要通过该方法来播放在线音效文件，建议你先将在线音效文件缓存到本地设备，调用 preloadEffect 将缓存的音效文件预加载到内存中，然后再调用此方法播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。 你可以多次调用该方法，传入不同的 soundID 和 filePath，同时播放多个音效文件。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。 音效文件播放结束后，SDK 会触发 rtcEngineDidAudioEffectFinish 回调。 注： 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP等。详见 支持的媒体格式。

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。 注意： 如果你已通过 preloadEffect 将音效加载至内存，请确保该参数与 preloadEffect 中设置的 soundId 相同。
filePath	注意： 如果你已通过 preloadEffect 将音效加载至内存，请确保该参数与 preloadEffect 中设置的 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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

playEffect [3/3]

播放指定的本地或在线音效文件。

Objective-C

- (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;

注意： 如果你需要通过该方法来播放在线音效文件，建议你先将在线音效文件缓存到本地设备，调用 preloadEffect 将缓存的音效文件预加载到内存中，然后再调用此方法播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。 你可以多次调用该方法，传入不同的 soundID 和 filePath，同时播放多个音效文件。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。音效文件播放结束后，SDK 会触发 rtcEngineDidAudioEffectFinish 回调。

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。 注意： 如果你已通过 preloadEffect 将音效加载至内存，请确保该参数与 preloadEffect 中设置的 soundId 相同。
filePath	播放文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 /var/mobile/Containers/Data/audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见支持的媒体格式。 注意： 如果你已通过 preloadEffect 将音效加载至内存，请确保该参数与 preloadEffect 中设置的 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: 不将音效发布至远端。只有本地用户能听到音效。
startPos	音效文件的播放位置，单位为毫秒。

返回值

• 0：方法调用成功。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

preloadEffect

将音效文件加载至内存。

Objective-C

- (int)preloadEffect:(int)soundId
            filePath:(NSString* _Nonnull)filePath;

为保证通信畅通，请注意控制预加载音效文件的大小，并在 joinChannelByToken [2/4] 前就使用该方法完成音效预加载。

注意：

• 该方法不支持在线音频文件。

• 该方法支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。
filePath	文件路径： iOS 或 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 /var/mobile/Containers/Data/audio.mp4。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

resumeAllEffects

恢复播放所有音效文件。

Objective-C

- (int)resumeAllEffects;

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

resumeEffect

恢复播放指定音效文件。

Objective-C

- (int)resumeEffect:(int)soundId;

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setEffectPosition

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

Objective-C

- (int)setEffectPosition:(int)soundId pos:(NSInteger)pos NS_SWIFT_NAME(setEffectPosition(_:pos:));

成功设置后，本地音效文件会在指定位置开始播放。

注意： 该方法需要在 playEffect 后调用。

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。
pos	音效文件的播放位置，单位为毫秒。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setEffectsVolume

设置音效文件的播放音量。

Objective-C

- (int)setEffectsVolume:(NSInteger)volume;

注意： 该方法需要在 playEffect [3/3] 后调用。

参数

参数名	描述
volume	播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

setVolumeOfEffect

实时调整音效文件的播放音量。

Objective-C

- (int)setVolumeOfEffect:(int)soundId
              withVolume:(int)volume;

参数

参数名	描述
soundId	指定音效的 ID。每个音效均有唯一的 ID。
volume	播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

stopAllEffects

停止播放所有音效文件。

Objective-C

- (int)stopAllEffects;

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

stopEffect

停止播放指定音效文件。

Objective-C

- (int)stopEffect:(int)soundId;

参数

参数名	描述
soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

unloadEffect

从内存释放某个预加载的音效文件。

Objective-C

- (int)unloadEffect:(int)soundId;

参数

参数名	描述
soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

rtcEngineDidAudioEffectFinish

本地音效文件播放已结束回调。

Objective-C

- (void)rtcEngineDidAudioEffectFinish:(AgoraRtcEngineKit * _Nonnull)engine soundId:(int)soundId;

当播放音效结束后，会触发该回调。

参数

参数名	描述
engine	AgoraRtcEngineKit 对象。
soundId	指定音效的 ID。每个音效均有唯一的 ID。

所属接口类

• AgoraRtcEngineDelegate