需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

音效文件播放

  • macOS

更新时间不可用

getEffectCurrentPosition:

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

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

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

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

参数

参数名描述
soundId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

getEffectDuration:

获取音效文件的时长。

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

注： 请在加入频道后调用该方法。

参数

参数名描述
filePath

文件路径：

  • iOS 或 macOS：音效文件的绝对路径或 URL 地址（包括文件名后缀）。例如：/var/mobile/Containers/Data/audio.mp4。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功，返回指定音效文件的总时长（毫秒）。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

getEffectsVolume

获取音效的音量。

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

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

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

返回值

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

所属接口类

getVolumeOfEffect:

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

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

参数

参数名描述
soundId

音效文件的 ID。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

pauseAllEffects

暂停所有音效。

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

返回值

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

所属接口类

pauseEffect:

暂停指定的音效文件。

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

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

参数

参数名描述
soundId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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: 将其预加载到内存中，然后再调用该方法播放音效。否则，可能因加载超时或失败导致播放失败或无声音。
  • 如果在调用 playEffect 之前调用了 preloadEffect，playEffect 播放后不会关闭文件资源。下次调用 playEffect 时将直接从头开始播放。
  • 如果在调用 playEffect 之前未调用 preloadEffect，playEffect 播放后将销毁资源。下次调用 playEffect 时将尝试重新打开文件并从头开始播放。

调用时机

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

参数

参数名描述
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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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 之前调用了 preloadEffect，则 playEffect 执行后不会关闭文件资源。下次调用 playEffect 时将直接从头开始播放。
  • 如果在调用 playEffect 之前未调用 preloadEffect，则 playEffect 执行后会销毁资源。下次调用 playEffect 时将尝试重新打开文件并从头开始播放。

调用时机

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

相关回调

音效文件播放完成后，SDK 会触发 rtcEngineDidAudioEffectFinish:soundId: 回调。

参数

参数名描述
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：方法调用失败。

所属接口类

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: 将文件预加载到内存中，再调用此方法播放音效。否则，可能因加载超时或失败导致播放失败或无声。
  • 如果在调用 playEffect 之前已调用 preloadEffect，则 playEffect 执行后不会关闭文件资源。下次调用 playEffect 时将直接从头开始播放。
  • 如果在调用 playEffect 之前未调用 preloadEffect，则 playEffect 执行后资源将被销毁。下次调用 playEffect 时将尝试重新打开文件并从头开始播放。

调用时机

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

相关回调

播放音效文件结束后，SDK 会触发 rtcEngineDidAudioEffectFinish:soundId: 回调。

参数

参数名描述
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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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 多次调用该方法。在通过 preloadEffectEx 预加载音效后，可调用此方法将指定音效播放给频道内所有用户。每次调用该方法只能播放一个音效。若需同时播放多个音效，请多次调用该方法。

注：

  • 声网建议不要同时播放超过三个音效。
  • 此方法中的音效 ID 和文件路径必须与 preloadEffectEx 方法中的保持一致。
  • 如果在执行 playEffectEx 之前调用了 preloadEffectEx，则 playEffectEx 执行后不会关闭文件资源。下次执行 playEffectEx 时将直接从头开始播放。
  • 如果在执行 playEffectEx 之前未调用 preloadEffectEx，则 playEffectEx 执行后会销毁资源。下次执行 playEffectEx 时将尝试重新打开文件并从头播放。

适用场景

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

参数

参数名描述
connection

AgoraRtcConnection 对象。详见 AgoraRtcConnection。

soundId

音效的 ID。每个音效文件的唯一标识。如果通过 preloadEffectEx 方法将音效预加载到内存中，请确保该参数值与 preloadEffectEx 方法中的值一致。

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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 版本新增。

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

注：

  • 声网建议不要同时播放超过三个音效。
  • 此方法中的 soundId 和 filePath 必须与 preloadEffectEx:filePath: 方法中的保持一致。
  • 如果在执行 playEffectEx 之前调用了 preloadEffectEx，则 playEffectEx 执行后不会关闭文件资源。下次执行 playEffectEx 时将直接从头开始播放。
  • 如果在执行 playEffectEx 之前未调用 preloadEffectEx，则 playEffectEx 执行后资源将被销毁。下次执行 playEffectEx 时将尝试重新打开文件并从头播放。

适用场景

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

参数

参数名描述
connection

AgoraRtcConnection 对象。详见 AgoraRtcConnection。

soundId

音效的 ID。每个音效文件的唯一 ID。请确保该参数值与 preloadEffectEx:filePath: 方法中的值一致。

filePath

本地音效文件的绝对路径（包括文件扩展名）或在线音效文件的 URL，例如 /var/mobile/Containers/Data/audio.mp4。支持的音频格式包括 mp3、mp4、m4a、aac、3gp、mkv 和 wav。

loopCount

设置音效的循环播放次数：

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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 多次调用该方法。在调用 preloadEffectEx:filePath: 预加载音效后，你可以调用该方法将音效播放给频道内所有用户。每次调用该方法只能播放一个音效，若需同时播放多个音效，请多次调用该方法。

注：

  • 声网建议你不要同时播放超过三个音效。
  • 此方法中的音效 ID 和文件路径必须与 preloadEffectEx:filePath: 方法中的保持一致。
  • 如果在执行 playEffectEx 之前调用了 preloadEffectEx，则 playEffectEx 执行后不会关闭文件资源。下次执行 playEffectEx 时将直接从头开始播放。
  • 如果在执行 playEffectEx 之前未调用 preloadEffectEx，则 playEffectEx 执行后资源将被销毁。下次执行 playEffectEx 时将尝试重新打开文件并从头播放。

适用场景

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

参数

参数名描述
connection

AgoraRtcConnection 对象。详见 AgoraRtcConnection。

soundId

音效的 ID。每个音效文件的唯一标识。请确保该参数值与 preloadEffectEx:filePath: 方法中的值一致。

filePath

本地音效文件的绝对路径（包含文件扩展名）或在线音效文件的 URL，例如 /var/mobile/Containers/Data/audio.mp4。支持的音频格式包括 mp3、mp4、m4a、aac、3gp、mkv 和 wav。

loopCount

设置音效的循环播放次数：

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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 版本新增。

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

注：

  • 声网建议不要同时播放超过三个音效。
  • 此方法中的音效 ID 和文件路径必须与 preloadEffectEx:filePath: 方法中的保持一致。
  • 如果在执行 playEffectEx 之前调用了 preloadEffectEx:filePath:，则 playEffectEx 执行后不会关闭文件资源。下次执行 playEffectEx 时将直接从头开始播放。
  • 如果在执行 playEffectEx 之前未调用 preloadEffectEx:filePath:，则 playEffectEx 执行后会销毁资源。下次执行 playEffectEx 时将尝试重新打开文件并从头播放。

适用场景

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

参数

参数名描述
connection

AgoraRtcConnection 对象。详见 AgoraRtcConnection。

soundId

音效的 ID。每个音效文件的唯一标识。请确保该参数值与 preloadEffectEx:filePath: 方法中的值一致。

filePath

本地音效文件的绝对路径（包含文件扩展名）或在线音效文件的 URL，例如 /var/mobile/Containers/Data/audio.mp4。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

loopCount

设置音效的循环播放次数：

pitch

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

pan

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

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

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

preloadEffect:filePath:startPos:

预加载指定的音效文件。

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

该方法每次调用时仅将一个指定的音效文件预加载到内存中。如需预加载多个音效文件，请多次调用该方法。 你可以调用 playEffect 播放已预加载的音效，或调用 playAllEffectsWithLoopCount:pitch:pan:gain:publish: 播放所有已预加载的音效。

  • 为确保通信顺畅，请限制音效文件的大小。
  • 声网建议你在加入频道前调用此方法。
  • 如果在调用 playEffect 之前调用了 preloadEffect，则 playEffect 执行后不会关闭文件资源。下次调用 playEffect 时将直接从头开始播放。
  • 如果在调用 playEffect 之前未调用 preloadEffect，则 playEffect 执行后会销毁资源。下次调用 playEffect 时会尝试重新打开文件并从头开始播放。

调用时机

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

参数

参数名描述
soundId

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

filePath

本地音效文件的绝对路径或在线音效文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

startPos

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

preloadEffect:filePath:

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

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

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

注：

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

调用时机

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

参数

参数名描述
soundId

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

filePath

文件路径：

  • iOS 或 macOS：音效文件的绝对路径或 URL 地址（包括文件名后缀）。例如：/var/mobile/Containers/Data/audio.mp4。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

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 播放所有预加载的音效。

注：

  • 为确保使用体验流畅，音效文件的大小不应超过限制。
  • 声网建议在加入频道前调用该方法。
  • 如果在调用 playEffectEx 之前调用了 preloadEffectEx，则 playEffectEx 执行后不会关闭文件资源。下次执行 playEffectEx 时会直接从头开始播放。
  • 如果在调用 playEffectEx 之前未调用 preloadEffectEx，则 playEffectEx 执行后会销毁资源。下次执行 playEffectEx 时会尝试重新打开文件并从头开始播放。

适用场景

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

参数

参数名描述
connection

连接信息。详见 AgoraRtcConnection。

soundId

音效 ID。

filePath

本地文件的绝对路径或在线文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

startPos

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

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:filePath:loopCount:pitch:pan:gain:publish:startPos: 播放预加载的音效，或调用 playAllEffects:loopCount:pitch:pan:gain:publish: 播放所有预加载的音效。

注：

  • 为确保使用体验流畅，音效文件的大小不应超过限制。
  • 声网建议你在加入频道前调用该方法。
  • 如果在调用 playEffectEx 之前调用了 preloadEffectEx，则 playEffectEx 执行后不会关闭文件资源。下次执行 playEffectEx 时会直接从头开始播放。
  • 如果在调用 playEffectEx 之前未调用 preloadEffectEx，则 playEffectEx 执行后会销毁资源。下次执行 playEffectEx 时会尝试重新打开文件并从头开始播放。

适用场景

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

参数

参数名描述
connection

连接信息。详见 AgoraRtcConnection。

soundId

音效 ID。

filePath

本地文件的绝对路径或在线文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

resumeAllEffects

恢复播放所有音效文件。

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

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

调用时机

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

返回值

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

所属接口类

resumeEffect:

恢复播放指定的音效。

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

参数

参数名描述
soundId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setEffectPosition:pos:

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

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

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

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

参数

参数名描述
soundId

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

pos

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

stopAllEffects

停止播放所有音效。

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

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

调用时机

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

返回值

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

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

unloadEffect:

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

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

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

调用时机

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

参数

参数名描述
soundId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

rtcEngineDidAudioEffectFinish:soundId:

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

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

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

触发时机

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

参数

参数名描述
engine

AgoraRtcEngineKit 对象，详见 AgoraRtcEngineKit。

soundId

音效 ID，每个音效文件的唯一标识。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利