音效文件播放

getEffectCurrentPosition:

获取音效文件的播放位置。

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

获取指定音效文件的播放位置，单位为毫秒。

信息

请在调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 方法之后调用此方法。

参数

soundId: 音效 ID。每个音效文件的 ID 是唯一的。

返回值

0：方法调用成功，返回指定音效文件的播放位置（单位为毫秒）。
< 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：方法调用成功，返回指定音效文件的总时长（毫秒）。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

AgoraRtcEngineKit

getEffectsVolume

获取音效的音量。

Objective-C
- (int)getEffectsVolume NS_SWIFT_NAME(getEffectsVolume());

音量为整数，范围为 0 到 100。默认值为 100，表示原始音量。

信息

请在调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 方法后调用此方法。

返回值

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

所属接口类

AgoraRtcEngineKit

getVolumeOfEffect:

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

Objective-C
- (int)getVolumeOfEffect:(int)soundId NS_SWIFT_NAME(getVolumeOfEffect(_:));

参数

soundId: 音效文件的 ID。

返回值

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

所属接口类

AgoraRtcEngineKit

pauseAllEffects

暂停所有音效。

Objective-C
- (int)pauseAllEffects NS_SWIFT_NAME(pauseAllEffects());

返回值

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

所属接口类

AgoraRtcEngineKit

pauseEffect:

暂停指定的音效文件。

Objective-C
- (int)pauseEffect:(int)soundId NS_SWIFT_NAME(pauseEffect(_:));

你可以调用该方法暂停指定的音效文件。

参数

soundId: 音效 ID。每个音效文件的 ID 是唯一的。

返回值

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

所属接口类

AgoraRtcEngineKit

playAllEffectsWithLoopCount:pitch:pan:gain:publish:

播放所有音效。

Objective-C
- (int)playAllEffectsWithLoopCount:(NSInteger)loopCount
                         pitch:(double)pitch
                           pan:(double)pan
                          gain:(NSInteger)gain
                       publish:(BOOL)publish NS_SWIFT_NAME(playAllEffects(withLoopCount:pitch:pan:gain:publish:));

在多次调用 preloadEffect:filePath: 预加载多个音效到内存中后，你可以调用此方法为频道内的所有用户播放所有预加载的音效。

参数

loopCount

音效的循环播放次数：

-1：无限循环播放音效，直到调用 stopEffect 或 stopAllEffects 停止播放。
0：播放音效一次。
1：播放音效两次。

pitch

音效的音调。取值范围为 0.5 到 2.0。默认值为 1.0（原始音调）。值越小，音调越低。

pan

音效的空间位置。取值范围为 -1.0 到 1.0：

-1.0：音效定位在左侧。
0.0：音效定位在正前方。
1.0：音效定位在右侧。

gain

音效的音量。取值范围为 0 到 100。默认值为 100（原始音量）。值越小，音效音量越低。

publish

是否将音效发布到远端：

YES：将音效发布到远端。
NO：不将音效发布到远端。

返回值

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

所属接口类

AgoraRtcEngineKit

playEffect:filePath:loopCount:pitch:pan:gain:

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

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

你可以多次调用该方法，并传入不同的 soundId 和 filePath，以同时播放多个音效文件。为获得最佳用户体验，声网建议不要同时播放超过三个音效文件。

信息

如果需要播放在线音效文件，声网建议先将其缓存到本地设备，调用 preloadEffect:filePath: 将其预加载到内存中，再调用本方法播放。否则，可能因加载超时或失败导致播放失败或无声。

调用时机

你可以在加入频道前或加入频道后调用该方法。

参数

soundId

音效 ID。每个音效文件的 ID 必须唯一。注意：如果你已通过调用 preloadEffect:filePath: 将音效预加载到内存中，确保该参数的值与 preloadEffect:filePath: 中的 soundId 相同。

filePath

音效文件路径。支持以 ipod-library:// 开头的路径、URL 以及本地文件的绝对路径。绝对路径需精确到文件名及扩展名。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV 和 3GP。注意：如果你已通过调用 preloadEffect:filePath: 将音效预加载到内存中，确保该参数的值与 preloadEffect:filePath: 中的 filePath 相同。

loopCount

音效循环播放的次数。

≥ 0：播放的次数。例如，1 表示循环播放一次，即总共播放两次。
-1：无限循环播放该音效文件。

pitch

音效的音调。取值范围为 0.5 到 2.0。默认值为 1.0，表示原始音调。值越小，音调越低。

pan

音效的空间位置。取值范围为 -1.0 到 1.0：

-1.0：音效从你左侧播放。
0.0：音效从你正前方播放。
1.0：音效从你右侧播放。

gain

音效的音量。取值范围为 0 到 100。默认值为 100，表示原始音量。值越小，音量越低。

返回值

0：方法调用成功。 < 0：方法调用失败。

所属接口类

AgoraRtcEngineKit

playEffect:filePath:loopCount:pitch:pan:gain:publish:

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

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 NS_SWIFT_NAME(playEffect(_:filePath:loopCount:pitch:pan:gain:publish:));

你可以多次调用该方法并传入不同的 soundId 和 filePath，以同时播放多个音效文件。为获得最佳用户体验，声网建议你不要同时播放超过三个音效文件。你可以在加入频道前或加入频道后调用该方法。

信息

如果你需要播放在线音效文件，声网建议你先将该文件缓存到本地设备，再调用 preloadEffect:filePath: 将其预加载到内存中，然后调用 playEffect:filePath:loopCount:pitch:pan:gain:publish: 播放音效。否则，可能因加载超时或失败导致播放失败或无声。

调用时机

你可以在加入频道前或加入频道后调用该方法。

参数

soundId

音效 ID。每个音效文件的 ID 必须唯一。注意：如果你已通过 preloadEffect:filePath: 将音效预加载到内存中，确保该参数的值与 preloadEffect:filePath: 中的 soundId 相同。

filePath

音效文件路径。支持以 ipod-library:// 开头的路径、URL 以及本地文件的绝对路径。绝对路径需精确到文件名及扩展名。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV 和 3GP。注意：如果你已通过 preloadEffect:filePath: 将音效预加载到内存中，确保该参数的值与 preloadEffect:filePath: 中的 filePath 相同。

loopCount

音效循环播放的次数。

≥ 0：播放的次数。例如，1 表示循环播放一次，即总共播放两次。
-1：无限循环播放该音效文件。

pitch

音效的音调。取值范围为 0.5 到 2.0。默认值为 1.0，表示原始音调。值越小，音调越低。

pan

音效的空间位置。取值范围为 -1.0 到 1.0：

-1.0：音效从你左侧播放。
0.0：音效从你正前方播放。
1.0：音效从你右侧播放。

gain

音效的音量。取值范围为 0 到 100。默认值为 100，表示原始音量。值越小，音量越低。

publish

是否将音效发布给远端用户：

YES：发布音效到远端，远端用户和你都能听到该音效。
NO：不发布音效到远端，只有你能听到该音效。

返回值

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

所属接口类

AgoraRtcEngineKit

playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:

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

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 NS_SWIFT_NAME(playEffect(_:filePath:loopCount:pitch:pan:gain:publish:startPos:));

你可以多次调用该方法并传入不同的 soundId 和 filePath，以同时播放多个音效文件。为获得最佳用户体验，声网建议你不要同时播放超过三个音效文件。

信息

如果你需要播放在线音效文件，声网建议你先将该文件缓存到本地设备，再调用 preloadEffect:filePath: 将其预加载到内存中，然后调用该方法播放音效。否则，可能因加载超时或失败导致播放失败或无声。

调用时机

你可以在加入频道前或加入频道后调用该方法。

参数

soundId

音效 ID。每个音效文件的 ID 必须唯一。如果你已通过调用 preloadEffect:filePath: 将音效预加载到内存中，确保该参数的值与 preloadEffect:filePath: 中的 soundId 相同。

filePath

音效文件路径。支持以 ipod-library:// 开头的路径、URL 以及本地文件的绝对路径。绝对路径需精确到文件名及扩展名。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV 和 3GP。如果你已通过调用 preloadEffect:filePath: 将音效预加载到内存中，确保该参数的值与 preloadEffect:filePath: 中的 filePath 相同。

loopCount

音效循环播放的次数：

≥ 0：播放的次数。例如，1 表示循环播放一次，即总共播放两次。
-1：无限循环播放该音效文件。

pitch

音效的音调。取值范围为 0.5 到 2.0。默认值为 1.0，表示原始音调。值越小，音调越低。

pan

音效的空间位置。取值范围为 -1.0 到 1.0：

-1.0：音效从你左侧播放。
0.0：音效从你正前方播放。
1.0：音效从你右侧播放。

gain

音效的音量。取值范围为 0 到 100。默认值为 100，表示原始音量。值越小，音量越低。

publish

是否将音效发布给远端用户：

YES：将音效发布给远端用户，你和远端用户都能听到该音效。
NO：不将音效发布给远端用户，只有你能听到该音效。

startPos

音效文件的播放起始位置（单位为毫秒）。

返回值

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

所属接口类

AgoraRtcEngineKit

playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:startPos:

在频道中播放指定的音效。

Objective-C
- (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 NS_SWIFT_NAME(playEffectEx(_:soundId:filePath:loopCount:pitch:pan:gain:publish:startPos:));

自从

自 v4.6.0 版本新增。

该方法用于设置是否在频道中发布音效。若需同时播放多个音效文件，只需使用不同的 soundId 和 filePath 多次调用该方法。在调用 preloadEffect:filePath: 预加载音效后，可调用此方法将指定音效播放给频道内所有用户。每次调用该方法只能播放一个音效。若需同时播放多个音效，请多次调用该方法。

信息

声网建议不要同时播放超过三个音效。
此方法中的音效 ID 和文件路径必须与 preloadEffect:filePath: 方法中的保持一致。

适用场景

该方法适用于多频道场景。

参数

connection

连接对象，详见 AgoraRtcConnection。

soundId

音效的 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.0，默认值为 1.0（原始音调）。值越小，音调越低。

pan

音效的空间位置。取值范围为 -1.0 到 1.0：

0.0：音效从你正前方传来。
1.0：音效从你右侧传来。
-1.0：音效从你左侧传来。

gain

音效的音量。取值范围为 0 到 100，默认值为 100。值越小，音量越低。

publish

是否在频道中发布音效：

YES：在频道中发布音效，远端用户可以听到。
NO：不在频道中发布音效。

startPos

音效文件的播放起始位置（单位为毫秒）。

返回值

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

所属接口类

AgoraRtcEngineKit(Ex)

playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:

在频道中播放指定的音效。

Objective-C
- (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 NS_SWIFT_NAME(playEffectEx(_:soundId:filePath:loopCount:pitch:pan:gain:publish:));

自从

自 v4.6.0 版本新增。

信息

声网建议不要同时播放超过三个音效。
本方法中的音效 ID 和文件路径必须与 preloadEffect:filePath: 中的保持一致。

适用场景

该方法适用于多频道场景。

参数

connection

连接对象。详见 AgoraRtcConnection。

soundId

音效的 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.0，默认值为 1.0（原始音调）。值越小，音调越低。

pan

音效的空间位置。取值范围为 -1.0 到 1.0：

0.0：音效从用户正前方传来。
1.0：音效从用户右侧传来。
-1.0：音效从用户左侧传来。

gain

音效的音量。取值范围为 0 到 100，默认值为 100。值越小，音量越低。

publish

是否在频道中发布音效：

YES：在频道中发布音效，远端用户可以听到。
NO：不在频道中发布音效。

返回值

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

所属接口类

AgoraRtcEngineKit(Ex)

playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:startPos:

在频道中播放指定的音效。

Objective-C
- (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 NS_SWIFT_NAME(playEffectEx(_:soundId:filePath:loopCount:pitch:pan:gain:startPos:));

自从

自 v4.6.0 版本新增。

该方法用于设置是否在频道中发布音效。要同时播放多个音效文件，你只需使用不同的 soundId 和 filePath 多次调用该方法。在调用 preloadEffect:filePath: 预加载音效后，可以调用此方法将指定音效播放给频道中的所有用户。每次调用该方法只能播放一个音效。要同时播放多个音效，请多次调用该方法。

信息

声网建议不要同时播放超过三个音效。
此方法中的音效 ID 和文件路径必须与 preloadEffect:filePath: 中的保持一致。

适用场景

该方法适用于多频道场景。

参数

connection

连接对象。详见 AgoraRtcConnection。

soundId

音效的 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.0，默认值为 1.0（原始音调）。值越小，音调越低。

pan

音效的空间位置。取值范围为 -1.0 到 1.0：

0.0：音效从用户正前方传来。
1.0：音效从用户右侧传来。
-1.0：音效从用户左侧传来。

gain

音效的音量。取值范围为 0 到 100，默认值为 100。值越小，音量越低。

startPos

音效文件的播放起始位置，单位为毫秒。

返回值

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

所属接口类

AgoraRtcEngineKit(Ex)

playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:

在频道中播放指定的音效。

Objective-C
- (int)playEffectEx:(AgoraRtcConnection* _Nonnull)connection
            soundId:(int)soundId
           filePath:(NSString* _Nonnull)filePath
          loopCount:(NSInteger)loopCount
              pitch:(double)pitch
                pan:(double)pan
               gain:(NSInteger)gain NS_SWIFT_NAME(playEffectEx(_:soundId:filePath:loopCount:pitch:pan:gain:));

自从

自 v4.6.0 版本新增。

你可以通过该方法设置是否在频道中发布音效。调用 preloadEffect:filePath: 预加载音效后，再调用此方法即可将指定音效播放给频道中的所有用户。每次调用该方法只能播放一个音效，如需同时播放多个音效，请使用不同的 soundId 和 filePath 多次调用该方法。

信息

声网建议不要同时播放超过三个音效。
此方法中的音效 ID 和文件路径必须与 preloadEffect:filePath: 方法中的保持一致。

适用场景

该方法适用于多频道场景。

参数

connection

连接对象。详见 AgoraRtcConnection。

soundId

音效的 ID。每个音效文件的唯一标识。若通过 preloadEffect:filePath: 预加载音效，请确保该参数值与预加载时一致。

filePath

loopCount

设置音效的循环次数：

0：播放一次。
1：播放两次。
-1：无限循环，直到调用 stopEffect: 或 stopAllEffects。

pitch

音效的音调。取值范围为 0.5 到 2.0，默认值为 1.0（原始音调）。值越小，音调越低。

pan

音效的空间位置。取值范围为 -1.0 到 1.0：

0.0：音效从你正前方传来。
1.0：音效从你右侧传来。
-1.0：音效从你左侧传来。

gain

音效的音量。取值范围为 0 到 100，默认值为 100。值越小，音量越低。

返回值

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

所属接口类

AgoraRtcEngineKit(Ex)

preloadEffect:filePath:startPos:

将指定的音效文件预加载到内存中。

Objective-C
- (int)preloadEffect:(int)soundId
            filePath:(NSString* _Nonnull)filePath
            startPos:(int)startPos NS_SWIFT_NAME(preloadEffect(_:filePath:startPos:));

确保所有预加载文件的总大小不超过限制。

信息

如果你在调用 playEffect 之前调用了 preloadEffect，playEffect 执行后不会关闭文件资源。下次调用 playEffect 时会直接从头开始播放。
如果你未在调用 playEffect 之前调用 preloadEffect，playEffect 执行后会销毁资源。下次调用 playEffect 时会尝试重新打开文件并从头开始播放。

调用时机

声网建议你在加入频道前调用该方法。

参数

soundId

音效 ID。每个音效文件的 ID 必须唯一。

filePath

文件路径：

iOS 或 macOS：音效文件的绝对路径或 URL 地址（包括文件名后缀）。例如：/var/mobile/Containers/Data/audio.mp4。

startPos

音效文件的播放起始位置（单位为毫秒）。

返回值

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

所属接口类

AgoraRtcEngineKit

preloadEffect:filePath:

将指定的音效文件预加载到内存中。

Objective-C
- (int)preloadEffect:(int)soundId
            filePath:(NSString* _Nonnull)filePath NS_SWIFT_NAME(preloadEffect(_:filePath:));

确保所有预加载文件的总大小不超过限制。关于该方法支持的音频文件格式，详见声网 RTC SDK 支持哪些音频文件格式。

调用时机

声网建议你在加入频道前调用该方法。

参数

soundId

音效 ID。每个音效文件的 ID 必须唯一。

filePath

文件路径：

iOS 或 macOS：音效文件的绝对路径或 URL 地址（包括文件名后缀）。例如：/var/mobile/Containers/Data/audio.mp4。

返回值

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

所属接口类

AgoraRtcEngineKit

preloadEffectEx:soundId:filePath:startPos:

预加载指定的音效文件到频道中。

Objective-C
- (int)preloadEffectEx:(AgoraRtcConnection* _Nonnull)connection
             soundId:(int)soundId
            filePath:(NSString* _Nonnull)filePath
            startPos:(int)startPos NS_SWIFT_NAME(preloadEffectEx(_:soundId:filePath:startPos:));

自从

自 v4.6.0 版本新增。

每次调用该方法时，只能将一个音效文件预加载到内存中。如果需要预加载多个音效文件，请多次调用该方法。预加载完成后，可以调用 playEffect 播放预加载的音效，或调用 playAllEffects 播放所有预加载的音效。

信息

为确保使用体验流畅，音效文件的大小不应超过限制。
声网建议你在加入频道前调用该方法。

适用场景

该方法适用于多频道场景。

参数

connection: 连接信息。详见 AgoraRtcConnection。
soundId: 音效 ID。
filePath: 本地文件的绝对路径或在线文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。
startPos: 音效文件的播放起始位置（单位为毫秒）。

返回值

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

所属接口类

AgoraRtcEngineKit(Ex)

preloadEffectEx:soundId:filePath:

预加载指定的音效文件到频道中。

Objective-C
- (int)preloadEffectEx:(AgoraRtcConnection* _Nonnull)connection
             soundId:(int)soundId
            filePath:(NSString* _Nonnull)filePath NS_SWIFT_NAME(preloadEffectEx(_:soundId:filePath:));

自从

自 v4.6.0 版本新增。

每次调用该方法只能将一个音效文件预加载到内存中。如果你需要预加载多个音效文件，请多次调用该方法。预加载完成后，你可以调用 playEffect 播放预加载的音效，或调用 playAllEffects 播放所有预加载的音效。

信息

为确保使用体验流畅，音效文件的大小不应超过限制。
声网建议你在加入频道前调用该方法。

适用场景

该方法适用于多频道场景。

参数

connection: 连接对象。详见 AgoraRtcConnection。
soundId: 音效 ID。
filePath: 本地文件的绝对路径或在线文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

返回值

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

所属接口类

AgoraRtcEngineKit(Ex)

resumeAllEffects

恢复播放所有音效文件。

Objective-C
- (int)resumeAllEffects NS_SWIFT_NAME(resumeAllEffects());

调用 pauseAllEffects 后，可以调用该方法恢复播放。

调用时机

请在调用 pauseAllEffects 之后调用该方法。

返回值

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

所属接口类

AgoraRtcEngineKit

resumeEffect:

恢复播放指定的音效。

Objective-C
- (int)resumeEffect:(int)soundId NS_SWIFT_NAME(resumeEffect(_:));

参数

soundId: 音效 ID。每个音效文件的 ID 是唯一的。

返回值

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

所属接口类

AgoraRtcEngineKit

setEffectPosition:pos:

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

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 NS_SWIFT_NAME(setEffectsVolume(_:));

调用时机

在调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 方法之后调用。

参数

volume: 播放音量。取值范围为 [0, 100]。（默认）为 100，表示原始音量。

返回值

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

所属接口类

AgoraRtcEngineKit

setVolumeOfEffect:withVolume:

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

Objective-C
- (int)setVolumeOfEffect:(int)soundId
              withVolume:(int)volume NS_SWIFT_NAME(setVolumeOfEffect(_:withVolume:));

调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 方法后，可调用该方法设置指定音效文件的播放音量。

调用时机

在调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 方法后调用。

参数

soundId: 音效的 ID。每个音效文件的唯一 ID。
volume: 播放音量。取值范围为 [0, 100]。默认值为 100，表示原始音量。

返回值

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

所属接口类

AgoraRtcEngineKit

stopAllEffects

停止播放所有音效。

Objective-C
- (int)stopAllEffects NS_SWIFT_NAME(stopAllEffects());

当你不再需要播放音效时，可以调用此方法停止播放所有音效。如果你只需要暂停播放，请调用 pauseAllEffects 方法。

调用时机

请在调用 playEffect 方法之后调用此方法。

返回值

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

所属接口类

AgoraRtcEngineKit

stopEffect:

停止播放指定的音效。

Objective-C
- (int)stopEffect:(int)soundId NS_SWIFT_NAME(stopEffect(_:));

当你不再需要播放某个音效时，可以调用该方法停止播放。如果你只需要暂停播放，请调用 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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

AgoraRtcEngineKit

unloadEffect:

释放指定的预加载音效文件。

Objective-C
- (int)unloadEffect:(int)soundId NS_SWIFT_NAME(unloadEffect(_:));

调用 preloadEffect:filePath: 方法将音效文件加载到内存后，如需释放该音效文件，可调用 unloadEffect: 方法。

调用时机

你可以在加入频道前或后调用此方法。

参数

soundId: 音效的 ID。每个音效均有唯一的 ID。

返回值

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

所属接口类

AgoraRtcEngineKit

rtcEngineDidAudioEffectFinish:soundId:

本地音效文件播放完成时的回调。

Objective-C
- (void)rtcEngineDidAudioEffectFinish:(AgoraRtcEngineKit * _Nonnull)engine soundId:(int)soundId NS_SWIFT_NAME(rtcEngineDidAudioEffectFinish(_:soundId:));

该回调在本地音效文件播放完成时触发。

触发时机

该回调在本地音效文件播放完成时被触发。

参数

engine: AgoraRtcEngineKit 对象，详见 AgoraRtcEngineKit。
soundId: 音效 ID，每个音效文件的唯一标识。

所属接口类

AgoraRtcEngineDelegate

getEffectCurrentPosition:

参数​

返回值​

getEffectDuration:

参数​

返回值​

getEffectsVolume

返回值​

getVolumeOfEffect:

参数​

返回值​

pauseAllEffects

返回值​

pauseEffect:

参数​

返回值​

playAllEffectsWithLoopCount:pitch:pan:gain:publish:

参数​

返回值​

playEffect:filePath:loopCount:pitch:pan:gain:

调用时机

参数​

返回值​

playEffect:filePath:loopCount:pitch:pan:gain:publish:

调用时机

参数​

返回值​

playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:

调用时机

相关回调

参数​

返回值​

playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:startPos:

适用场景

参数​

返回值​

playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:

适用场景

参数​

返回值​

playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:startPos:

适用场景

参数​

返回值​

playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:

适用场景

参数​

返回值​

preloadEffect:filePath:startPos:

调用时机

参数​

返回值​

preloadEffect:filePath:

调用时机

参数​

返回值​

preloadEffectEx:soundId:filePath:startPos:

适用场景

参数​

返回值​

preloadEffectEx:soundId:filePath:

适用场景

参数​

返回值​

resumeAllEffects

调用时机

返回值​

resumeEffect:

参数​

返回值​

setEffectPosition:pos:

参数​

返回值​

setEffectsVolume:

调用时机

参数​

返回值​

setVolumeOfEffect:withVolume:

调用时机

参数​

参数

返回值

参数

返回值

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数