IAudioEffectManager
该类提供音效管理方法。
getEffectsVolume
获取音效文件的播放音量。
public double getEffectsVolume();
音量范围为 0~100。100 (默认值)为原始文件音量。
注意: 该方法需要在 playEffect [2/2] 后调用。
返回值
- 音效文件的音量。
- < 0: 方法调用失败
getVolumeOfEffect
获取指定音效文件的播放音量。
public abstract int getVolumeOfEffect(int soundId);
参数
- soundId
- 音效文件的 ID。
返回值
- ≥ 0: 方法调用成功,返回播放音量。音量范围为 [0,100]。100 为原始音量。
- < 0: 方法调用失败。
pauseAllEffects
暂停所有音效文件播放。
public abstract int pauseAllEffects();
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
pauseEffect
暂停音效文件播放。
public abstract int pauseEffect(int soundId);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
playEffect [1/2]
播放指定的本地或在线音效文件。
public abstract int playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish);
注意: 如果你需要通过该方法来播放在线音效文件,Agora 建议你先将在线音效文件缓存到本地设备,调用 preloadEffect 将缓存的音效文件预加载到内存中,然后再调用此方法播放音效。否则,可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。
你可以多次调用该方法,传入不同的 soundID 和 filePath,同时播放多个音效文件。为获得最佳用户体验,Agora 推荐同时播放的音效文件不超过 3 个。 音效文件播放结束后,SDK 会触发 onAudioEffectFinished 回调。
注: 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP等。详见 支持的媒体格式。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
-
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。通过绝对路径访问本地文件可能会遇到权限问题,Agora 推荐使用 URL 地址访问本地文件。例如
content://com.android.providers.media.documents/document/audio%203A14441
。 - 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
-
是否将音效发布至远端:
true
: 将音效发布至远端。本地用户和远端用户都能听到音效。false
: 不将音效发布至远端。只有本地用户能听到音效。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
playEffect [2/2]
播放指定的本地或在线音效文件。
public int playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish, int startPos);
注意: 如果你需要通过该方法来播放在线音效文件,Agora 建议你先将在线音效文件缓存到本地设备,调用 preloadEffect 将缓存的音效文件预加载到内存中,然后再调用此方法播放音效。否则,可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。
你可以多次调用该方法,传入不同的 soundID 和 filePath,同时播放多个音效文件。为获得最佳用户体验,Agora 推荐同时播放的音效文件不超过 3 个。音效文件播放结束后,SDK 会触发 onAudioEffectFinished 回调。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
-
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
content://com.android.providers.media.documents/document/audio%203A14441
。支持的音频格式包括 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
-
是否将音效发布至远端:
true
: 将音效发布至远端。本地用户和远端用户都能听到音效。false
: 不将音效发布至远端。只有本地用户能听到音效。
- startPos
-
音效文件的播放位置,单位为毫秒。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
preloadEffect
将音效文件加载至内存。
public int preloadEffect(int soundId, String filePath);
为保证通信畅通,请注意控制预加载音效文件的大小,并在 joinChannel [2/2] 前就使用该方法完成音效预加载。
注意:
- 该方法不支持在线音频文件。
- 该方法支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
- 文件路径:
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
/assets/
开头的路径。 通过绝对路径访问本地文件可能会遇到权限问题,Agora 推荐使用 URI 地址访问本地文件。例如content://com.android.providers.media.documents/document/audio%3A14441
。
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
resumeAllEffects
恢复播放所有音效文件。
public abstract int resumeAllEffects();
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
resumeEffect
恢复播放指定音效文件。
public abstract int resumeEffect(int soundId);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEffectsVolume
设置音效文件的播放音量。
public abstract int setEffectsVolume(double volume);
注意: 该方法需要在 playEffect [2/2] 后调用。
参数
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVolumeOfEffect
实时调整音效文件的播放音量。
public abstract int setVolumeOfEffect(int soundId, double volume);
参数
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopAllEffects
停止播放所有音效文件。
public abstract int stopAllEffects();
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopEffect
停止播放指定音效文件。
public abstract int stopEffect(int soundId);
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
unloadEffect
从内存释放某个预加载的音效文件。
public abstract int unloadEffect(int soundId);
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败