Provides the methods to manage the audio effects.
int io.agora.rtc.IAudioEffectManager.playEffect |
( |
int |
soundId, |
|
|
String |
filePath, |
|
|
int |
loopCount, |
|
|
double |
pitch, |
|
|
double |
pan, |
|
|
double |
gain, |
|
|
boolean |
publish |
|
) |
| |
Plays a specified local or online audio effect file.
- Deprecated:
- Deprecated from v3.4.0. Use
playEffect
[3/3] instead.
With this method, you can set the loop count, pitch, pan, and gain of the audio effect file and whether the remote user can hear the audio effect.
Ensure that you call this method after joining a channel. To play multiple audio effect files simultaneously, call this method multiple times with different soundId
and filePath
. We recommend playing no more than three audio effect files at the same time.
When the audio effect file playback is finished, the SDK triggers the onAudioEffectFinished
callback.
- Note
- For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
- To play an online file for which the URL address starts with
http
, you need to add android:usesCleartextTraffic="true"
to the /app/Manifests/AndroidManifest.xml
file.
- To use
playEffect
to play an online audio effect file, Agora recommends that you cache the online audio effect file to your local device, call preloadEffect
, to preload the cached audio effect file into memory, and then call playEffect
to play the audio effect. Otherwise, you can experience playback failures and silence due to online audio effect file loading timeouts or loading failures.
- Parameters
-
soundId | ID of the specified audio effect. Each audio effect has a unique ID. If the audio effect is preloaded into the memory through the preloadEffect method, ensure that the soundID value is set to the same value as in the preloadEffect method. |
filePath | The file path, including the filename extensions. To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/. Note: You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: "content://com.android.providers.media.documents/document/audio%3A14441". If you preloaded an audio effect into memory by calling preloadEffect , ensure that this parameter is set to the same value as in preloadEffect . |
loopCount | The number of times the audio effect loops:
-
≥ 0: The number of loops. For example,
1 means loop one time, which means play the audio effect two times in total.
-
-1: Play the audio effect in an indefinite loop.
|
pitch | The pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch. |
pan | The spatial position of the audio effect. The value ranges between -1.0 and 1.0.
-
0.0: The audio effect displays ahead.
-
1.0: The audio effect displays to the right.
-
-1.0: The audio effect displays to the left.
|
gain | Sets the volume of the audio effect. The value ranges between 0.0 and 100,0. The default value is 100.0. The lower the value, the lower the volume of the audio effect. |
publish | Sets whether to publish the specified audio effect to the remote stream:
-
true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it.
-
false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it.
|
- Returns
-
0: Success.
-
< 0: Failure.
int io.agora.rtc.IAudioEffectManager.playEffect |
( |
int |
soundId, |
|
|
String |
filePath, |
|
|
int |
loopCount, |
|
|
double |
pitch, |
|
|
double |
pan, |
|
|
double |
gain, |
|
|
boolean |
publish, |
|
|
int |
startPos |
|
) |
| |
Plays a specified local or online audio effect file.
- Since
- v3.4.0
To play multiple audio effect files at the same time, call this method multiple times with different soundId
and filePath
values. For the best user experience, Agora recommends playing no more than three audio effect files at the same time.
After completing playing an audio effect file, the SDK triggers the onAudioEffectFinished
callback.
- Note
- Call this method after joining a channel.
- For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
- To play an online file for which the URL address starts with
http
, you need to add android:usesCleartextTraffic="true"
to the /app/Manifests/AndroidManifest.xml
file.
- To use
playEffect
to play an online audio effect file, Agora recommends that you cache the online audio effect file to your local device, call preloadEffect
, to preload the cached audio effect file into memory, and then call playEffect
to play the audio effect. Otherwise, you can experience playback failures and silence due to online audio effect file loading timeouts or loading failures.
- Parameters
-
soundId | Audio effect ID. The ID of each audio effect file is unique. If you preloaded an audio effect into memory by calling preloadEffect , ensure that this parameter is set to the same value as in preloadEffect . |
filePath | The file path, including the filename extensions. To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/. Note: You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: "content://com.android.providers.media.documents/document/audio%3A14441". If you preloaded an audio effect into memory by calling preloadEffect , ensure that this parameter is set to the same value as in preloadEffect . |
loopCount | The number of times the audio effect loops:
-
≥ 0: The number of loops. For example,
1 means loop one time, which means play the audio effect two times in total.
-
-1: Play the audio effect in an indefinite loop.
|
pitch | The pitch of the audio effect. The range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch. |
pan | The spatial position of the audio effect. The range is -1.0 to 1.0. For example:
-
-1.0: The audio effect occurs on the left.
-
0.0: The audio effect occurs in the front.
-
1.0: The audio effect occurs on the right.
|
gain | The volume of the audio effect. The range is 0.0 to 100.0. The default value is 100.0, which means the original volume. The smaller the value, the less the gain. |
publish | Whether to publish the audio effect to the remote users:
-
true: Publish. Both the local user and remote users can hear the audio effect.
-
false: Do not publish. Only the local user can hear the audio effect.
|
startPos | The playback position (ms) of the audio effect file. |
- Returns
-
0: Success.
-
< 0: Failure.
int io.agora.rtc.IAudioEffectManager.startRhythmPlayer |
( |
String |
sound1, |
|
|
String |
sound2, |
|
|
AgoraRhythmPlayerConfig |
config |
|
) |
| |
Enables the virtual metronome.
- Since
- v3.4.0
In music education, physical education, and other scenarios, teachers often need to use a metronome so that students can practice at the correct tempo. A meter is composed of a downbeat and some number of upbeats (including zero). The first beat of each measure is called the downbeat, and the rest are called the upbeats. In this method, you need to set the paths of the upbeat and downbeat files, the number of beats per measure, the tempo, and whether to send the sound of the metronome to remote users.
- Note
- After enabling the virtual metronome, the SDK plays the specified files from the beginning and controls the beat duration according to the value you set in
beatsPerMinute
. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration.
- For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.
- Parameters
-
sound1 | The absolute path (including the filename extensions) of the file for the downbeat. For example: /sdcard/emulated/0/audio.mp4 . |
sound2 | The absolute path (including the filename extensions) of the file for the upbeats. For example: /sdcard/emulated/0/audio.mp4 . |
config | The metronome configuration. See AgoraRhythmPlayerConfig . |
- Returns
- 0: Success.
- < 0: Failure.