音效文件播放
getEffectCurrentPosition:
getEffectDuration:
getEffectsVolume
getVolumeOfEffect:
pauseAllEffects
pauseEffect:
playEffect:filePath:loopCount:pitch:pan:gain:
播放指定的本地或在线音效文件。
- (int)playEffect:(int)soundId
filePath:(NSString* _Nonnull)filePath
loopCount:(NSInteger)loopCount
pitch:(double)pitch
pan:(double)pan
gain:(NSInteger)gain;
你可以多次调用该方法，传入不同的 soundID 和 filePath，同时播放多个音效文件。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。
调用时机
该方法在加入频道前后均可调用。
调用限制
如果你需要播放在线音效文件，声网建议先将在线音效文件缓存到本地设备，调用 preloadEffect:filePath: 将缓存的音效文件预加载到内存中，然后再调用此方法播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。
相关回调
音效文件播放结束后，SDK 会触发 rtcEngineDidAudioEffectFinish:soundId: 回调。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。注意
- filePath
播放文件的地址，支持以
ipod-library//开头的文件路径、在线文件的 URL 地址、文件的绝对路径，需精确到文件名及后缀。支持的音频格式包括 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:filePath:loopCount:pitch:pan:gain:publish:
播放指定的本地或在线音效文件。
- (int)playEffect:(int)soundId
filePath:(NSString* _Nonnull)filePath
loopCount:(NSInteger)loopCount
pitch:(double)pitch
pan:(double)pan
gain:(NSInteger)gain
publish:(BOOL)publish;
你可以多次调用该方法，传入不同的 soundID 和 filePath，同时播放多个音效文件。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。
调用时机
该方法在加入频道前后均可调用。
调用限制
如果你需要播放在线音效文件，声网建议先将在线音效文件缓存到本地设备，调用 preloadEffect:filePath: 将缓存的音效文件预加载到内存中，然后再调用此方法播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。
相关回调
音效文件播放结束后，SDK 会触发 rtcEngineDidAudioEffectFinish:soundId: 回调。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。注意
- filePath
播放文件的地址，支持以
ipod-library//开头的文件路径、在线文件的 URL 地址、文件的绝对路径，需精确到文件名及后缀。支持的音频格式包括 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: 不将音效发布至远端。只有本地用户能听到音效。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:
播放指定的本地或在线音效文件。
- (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 和 filePath，同时播放多个音效文件。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。
调用时机
该方法在加入频道前后均可调用。
调用限制
如果你需要播放在线音效文件，声网建议先将在线音效文件缓存到本地设备，调用 preloadEffect:filePath: 将缓存的音效文件预加载到内存中，然后再调用此方法播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。
相关回调
音效文件播放结束后，SDK 会触发 rtcEngineDidAudioEffectFinish:soundId: 回调。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。注意
- filePath
播放文件的地址，支持以
ipod-library//开头的文件路径、在线文件的 URL 地址、文件的绝对路径，需精确到文件名及后缀。支持的音频格式包括 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：方法调用失败。详见错误码了解详情和解决建议。
playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:startPos:
播放指定音效到指定频道。
- (int)playEffectEx:(AgoraRtcConnection* _Nonnull)connection
soundId:(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 和 filePath 多次调用该方法。
- 声网建议同时播放的音效不超过三个。
- 此方法中的音效 ID 和文件路径必须与 preloadEffect:filePath: 方法中的一致。
适用场景
该方法适用于多频道场景。
调用限制
无。
参数
- connection
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。如果通过 preloadEffect:filePath: 方法将音效预加载到内存中，确保该参数值与 preloadEffect:filePath: 方法中的值一致。
- filePath
- 本地音效文件的绝对路径（包括文件名后缀）或在线音效文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。
- loopCount
- 设置音效的循环次数：
- 0：音效播放一次。
- 1：音效播放两次。
- -1：无限循环播放音效，直到你调用 stopEffect: 或 stopAllEffects 方法。
- pitch
- 设置音效的音调。取值范围为 0.5 到 2，默认值为 1（不改变音调）。值越小，音调越低。
- pan
- 设置音效的空间位置。取值范围为 -1.0 到 1.0。
- 0.0：音效位于正前方。
- 1.0：音效位于右侧。
- -1.0：音效位于左侧。
- gain
- 设置音效的音量。取值范围为 0 到 100（默认）。值越小，音效音量越低。
- publish
- 设置是否在频道中发布指定音效：
YES：在频道中发布音效，远端用户可以听到。NO：不在频道中发布音效。
- startPos
- 音效文件的播放起始位置（单位为毫秒）。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。
playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:
播放指定音效到指定频道。
- (int)playEffectEx:(AgoraRtcConnection* _Nonnull)connection
soundId:(int)soundId
filePath:(NSString* _Nonnull)filePath
loopCount:(NSInteger)loopCount
pitch:(double)pitch
pan:(double)pan
gain:(NSInteger)gain
publish:(BOOL)publish;
该方法允许你设置是否在频道中发布音效。要同时播放多个音效文件，请使用不同的 soundId 和 filePath 多次调用该方法。调用 preloadEffect:filePath: 预加载音效后，可以调用该方法将指定音效播放给频道内的所有用户。每次调用该方法只能播放一个音效。如需同时播放多个音效，请多次调用该方法。
- 声网建议同时播放的音效不超过三个。
- 此方法中的音效 ID 和文件路径必须与 preloadEffect:filePath: 方法中的一致。
适用场景
该方法适用于多频道场景。
调用限制
无。
参数
- connection
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。如果通过 preloadEffect:filePath: 方法将音效预加载到内存中，确保该参数值与 preloadEffect:filePath: 方法中的值一致。
- filePath
- 本地音效文件的绝对路径（包括文件名后缀）或在线音效文件的 URL，例如 /var/mobile/Containers/Data/audio.mp4。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。
- loopCount
- 设置音效的循环次数：
- 0：音效播放一次。
- 1：音效播放两次。
- -1：无限循环播放音效，直到调用 stopEffect: 或 stopAllEffects 方法。
- pitch
- 设置音效的音调。取值范围为 0.5 到 2，默认值为 1（不改变音调）。值越小，音调越低。
- pan
- 设置音效的空间位置。取值范围为 -1.0 到 1.0。
- 0.0：音效位于正前方。
- 1.0：音效位于右侧。
- -1.0：音效位于左侧。
- gain
- 设置音效的音量。取值范围为 0 到 100，默认值为 100。值越小，音效音量越低。
- publish
- 设置是否在频道中发布指定音效：
YES：在频道中发布音效，远端用户可以听到。NO：不在频道中发布音效。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。
playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:startPos:
播放指定音效到指定频道。
- (int)playEffectEx:(AgoraRtcConnection* _Nonnull)connection
soundId:(int)soundId
filePath:(NSString* _Nonnull)filePath
loopCount:(NSInteger)loopCount
pitch:(double)pitch
pan:(double)pan
gain:(NSInteger)gain
startPos:(int)startPos;
该方法允许你设置是否在频道中发布音效。要同时播放多个音效文件，请使用不同的 soundId 和 filePath 多次调用该方法。调用 preloadEffect:filePath: 预加载音效后，可以调用该方法将指定音效播放给频道内的所有用户。每次调用该方法只能播放一个音效。如需同时播放多个音效，请多次调用该方法。
- 声网建议同时播放的音效不超过三个。
- 此方法中的音效 ID 和文件路径必须与 preloadEffect:filePath: 方法中的一致。
适用场景
该方法适用于多频道场景。
调用限制
无。
参数
- connection
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。如果通过 preloadEffect:filePath: 方法将音效预加载到内存中，确保该参数值与 preloadEffect:filePath: 方法中的值一致。
- filePath
- 本地音效文件的绝对路径（包括文件名后缀）或在线音效文件的 URL，例如 /var/mobile/Containers/Data/audio.mp4。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。
- loopCount
- 设置音效的循环次数：
- 0：音效播放一次。
- 1：音效播放两次。
- -1：无限循环播放音效，直到调用 stopEffect: 或 stopAllEffects 方法。
- pitch
- 设置音效的音调。取值范围为 0.5 到 2，默认值为 1（不改变音调）。值越小，音调越低。
- pan
- 设置音效的空间位置。取值范围为 -1.0 到 1.0。
- 0.0：音效位于正前方。
- 1.0：音效位于右侧。
- -1.0：音效位于左侧。
- gain
- 设置音效的音量。取值范围为 0 到 100，默认值为 100。值越小，音效音量越低。
- startPos
- 音效文件的播放起始位置（单位为毫秒）。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。
playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:
播放指定音效到指定频道。
- (int)playEffectEx:(AgoraRtcConnection* _Nonnull)connection
soundId:(int)soundId
filePath:(NSString* _Nonnull)filePath
loopCount:(NSInteger)loopCount
pitch:(double)pitch
pan:(double)pan
gain:(NSInteger)gain;
该方法允许你设置是否在频道中发布音效。要同时播放多个音效文件，请使用不同的 soundId 和 filePath 多次调用该方法。调用 preloadEffect:filePath: 预加载音效后，可以调用该方法将指定音效播放给频道内的所有用户。每次调用该方法只能播放一个音效。如需同时播放多个音效，请多次调用该方法。
- 声网建议同时播放的音效不超过三个。
- 此方法中的音效 ID 和文件路径必须与 preloadEffect:filePath: 方法中的一致。
适用场景
该方法适用于多频道场景。
调用限制
无。
参数
- connection
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。如果通过 preloadEffect:filePath: 方法将音效预加载到内存中，确保该参数值与 preloadEffect:filePath: 方法中的值一致。
- filePath
- 本地音效文件的绝对路径（包括文件名后缀）或在线音效文件的 URL，例如 /var/mobile/Containers/Data/audio.mp4。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。
- loopCount
- 设置音效的循环次数：
- 0：音效播放一次。
- 1：音效播放两次。
- -1：无限循环播放音效，直到调用 stopEffect: 或 stopAllEffects 方法。
- pitch
- 设置音效的音调。取值范围为 0.5 到 2，默认值为 1（不改变音调）。值越小，音调越低。
- pan
- 设置音效的空间位置。取值范围为 -1.0 到 1.0。
- 0.0：音效位于正前方。
- 1.0：音效位于右侧。
- -1.0：音效位于左侧。
- gain
- 设置音效的音量。取值范围为 0 到 100，默认值为 100。值越小，音效音量越低。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。
preloadEffect:filePath:
将音效文件加载至内存。
- (int)preloadEffect:(int)soundId
filePath:(NSString* _Nonnull)filePath;
为保证通信畅通，请注意控制预加载音效文件的大小。
该方法支持的预加载音频文件的格式见 RTC SDK 支持播放哪些格式的音频文件。
调用时机
声网建议在加入频道前调用该方法。
调用限制
无。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
- 文件路径：
- iOS 或 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如
/var/mobile/Containers/Data/audio.mp4。
- iOS 或 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
preloadEffectEx
预加载指定音效到指定频道。
- (int)preloadEffectEx:(AgoraRtcConnection* _Nonnull)connection
soundId:(int)soundId
filePath:(NSString* _Nonnull)filePath
startPos:(int)startPos NS_SWIFT_NAME(preloadEffectEx(_:soundId:filePath:startPos:));
每次调用该方法时，仅将一个指定的音效文件预加载到内存中。若需预加载多个音效文件，请多次调用该方法。预加载完成后，你可以调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 播放指定音效，或调用 playAllEffects:loopCount:pitch:pan:gain:publish: 播放所有已预加载的音效。
- 为确保通信顺畅，请限制音效文件的大小。
- 声网建议你在加入频道前调用该方法。
适用场景
该方法适用于多频道场景。
调用限制
无。
参数
- connection
- 连接对象。详见 AgoraRtcConnection。
- soundId
- 音效的 ID。
- filePath
- 本地音效文件的绝对路径或在线音效文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。
- startPos
- 音效文件的播放起始位置（单位为毫秒）。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。
preloadEffectEx
预加载指定音效到指定频道。
- (int)preloadEffectEx:(AgoraRtcConnection* _Nonnull)connection
soundId:(int)soundId
filePath:(NSString* _Nonnull)filePath NS_SWIFT_NAME(preloadEffectEx(_:soundId:filePath:));
每次调用该方法时，你只能将一个指定的音效文件预加载到内存中。若需预加载多个音效文件，请多次调用该方法。 预加载完成后，你可以调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 播放已预加载的音效，或调用 playAllEffects:loopCount:pitch:pan:gain:publish: 播放所有已预加载的音效。
- 为确保通信顺畅，请限制音效文件的大小。
- 声网建议你在加入频道前调用该方法。
适用场景
该方法适用于多频道场景。
调用限制
无。
参数
- connection
- 连接对象。详见 AgoraRtcConnection。
- soundId
- 音效的 ID。
- filePath
- 本地音效文件的绝对路径或在线音效文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。
resumeAllEffects
恢复播放所有音效文件。
- (int)resumeAllEffects;
当你调用 pauseAllEffects 暂停播放所有音效文件后，如需恢复播放，可以调用该方法。
调用时机
该方法需要在 pauseAllEffects 后调用。
调用限制
无。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
resumeEffect:
setEffectPosition:pos:
setEffectsVolume:
设置音效文件的播放音量。
- (int)setEffectsVolume:(NSInteger)volume;
调用时机
该方法需要在 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 后调用。
调用限制
无。
参数
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
setVolumeOfEffect:withVolume:
设置指定音效文件的播放音量。
- (int)setVolumeOfEffect:(int)soundId
withVolume:(int)volume;
调用时机
该方法需要在 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 后调用。
调用限制
无。
参数
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
stopAllEffects
停止播放所有音效文件。
- (int)stopAllEffects;
当你不需要再播放音效文件时，可以调用该方法停止播放。如果你仅需暂停播放，请调用 pauseAllEffects。
调用时机
该方法需要在 playEffect:filePath:loopCount:pitch:pan:gain:、playEffect:filePath:loopCount:pitch:pan:gain:publish: 或 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 之后调用。
调用限制
无。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
stopEffect:
停止播放指定音效文件。
- (int)stopEffect:(int)soundId;
当你不需要再播放某一音效文件时，可以调用该方法停止播放。如果你仅需暂停播放，请调用 pauseEffect:。
调用时机
该方法需要在 playEffect:filePath:loopCount:pitch:pan:gain:、playEffect:filePath:loopCount:pitch:pan:gain:publish: 或 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 之后调用。
调用限制
无。
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
unloadEffect:
从内存释放某个预加载的音效文件。
- (int)unloadEffect:(int)soundId;
调用 preloadEffect:filePath: 将音效文件加载至内存后，如需释放该音效文件，请调用该方法。
调用时机
该方法在加入频道前后均可调用。
调用限制
无。
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。