Media Playback

Audio Mixing

adjustAudioMixingPlayoutVolume

Adjusts the local playback volume of the audio mixing.

virtual int adjustAudioMixingPlayoutVolume(int volume) = 0;

Timing

You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

volume
Local playback volume of the audio mixing. Range: 0 to 100. The default value is 100, which represents the original volume.

Return Values

  • 0: Success.
  • < 0: Failure.

adjustAudioMixingPublishVolume

Adjusts the audio mixing volume for publishing.

virtual int adjustAudioMixingPublishVolume(int volume) = 0;

Timing

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

volume
The audio mixing volume for publishing. Range: 0 to 100. The default value is 100, which represents the original volume.

Return Values

  • 0: Success.
  • < 0: Failure.

adjustAudioMixingVolume

Adjusts the local and remote audio mixing volume.

virtual int adjustAudioMixingVolume(int volume) = 0;
Note: The adjustAudioMixingVolume method does not affect the volume of audio files set by the playEffect method.

Timing

Call this method after calling startAudioMixing.

Parameters

volume
Audio mixing volume. Range: 0 to 100. The default value is 100, which represents the original volume.

Return Values

  • 0: Success.
  • < 0: Failure.

getAudioMixingCurrentPosition

Gets the current playback progress (ms) of the audio mixing.

virtual int getAudioMixingCurrentPosition() = 0;
Note:
  • You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.
  • If you need to call getAudioMixingCurrentPosition multiple times, ensure the interval between two calls is greater than 500 ms.

Return Values

  • ≥ 0: Success. Returns the current playback progress (ms) of the audio mixing. A return value of 0 indicates the music file has not started playing yet.
  • < 0: Failure.

getAudioMixingDuration

Gets the total duration (ms) of the audio mixing file.

virtual int getAudioMixingDuration() = 0;

Timing

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Return Values

  • Success. Returns the total duration of the audio mixing file (ms).
  • < 0: Failure.

getAudioMixingPlayoutVolume

Gets the local playback volume of the audio mixing.

virtual int getAudioMixingPlayoutVolume() = 0;

You can call this method to get the local playback volume of the audio mixing file, which helps troubleshoot volume-related issues.

Timing

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Return Values

  • Success. Returns the audio mixing volume. Range: [0, 100].
  • < 0: Failure.

getAudioMixingPublishVolume

Gets the audio mixing volume for publishing.

virtual int getAudioMixingPublishVolume() = 0;
Note: You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Return Values

  • 0: Success. Returns the audio mixing volume. Range: [0,100].
  • < 0: Failure.

getAudioTrackCount

Gets the audio track index of the current music file.

virtual int getAudioTrackCount() = 0;
Note: You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Return Values

  • 0: Success.
  • < 0: Failure.

pauseAudioMixing

Pauses the playback and mixing of the music file.

virtual int pauseAudioMixing() = 0;

After calling startAudioMixing to play a music file, you can call this method to pause playback. To stop playback, call stopAudioMixing.

Timing

Call this method after joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure.

resumeAudioMixing

Resumes the playback and mixing of the music file.

virtual int resumeAudioMixing() = 0;

After calling pauseAudioMixing to pause playback, you can call resumeAudioMixing to resume playback.

Timing

Call this method after joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure.

selectAudioTrack [1/2]

Selects the audio track to use during playback.

virtual int selectAudioTrack(int index) = 0;

After obtaining the audio track index of an audio file, you can call this method to specify any track for playback. For example, if a multi-track file stores songs in different languages on different tracks, you can call this method to set the playback language.

Note:
  • For supported audio file formats, see [Extended audio file formats](https://docs.agora.io/en/help/general-product-inquiry/audio_format#extended-audio-file-formats).
  • You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

index
The specified audio track index. This value should be greater than 0 and less than the value returned by getAudioTrackCount.

Return Values

  • 0: Success.
  • < 0: Failure.

selectMultiAudioTrack

Selects the audio track for local playback and publishing to the channel.

virtual int selectMultiAudioTrack(int playoutTrackIndex, int publishTrackIndex) = 0;

Before calling this method, you need to open the media file using openWithMediaSource and set enableMultiAudioTrack to true in MediaSource.

Scenario

This method is suitable for scenarios such as KTV: the host can choose to play the original vocal track locally while publishing the accompaniment track to the channel.

Parameters

playoutTrackIndex
The index of the audio track for local playback. Can be obtained via getStreamInfo.
publishTrackIndex
The index of the audio track to publish to the channel. Can be obtained via getStreamInfo.

Return Values

  • 0: Success.
  • < 0: Failure.

setAudioMixingDualMonoMode

Sets the channel mode of the current audio file.

virtual int setAudioMixingDualMonoMode(media::AUDIO_MIXING_DUAL_MONO_MODE mode) = 0;

In stereo music files, the left and right channels can store different audio data. You can set the channel mode to original, left, right, or mixed mode as needed.

Note: This method only applies to stereo audio files.

Scenario

In KTV scenarios, the left channel of a music file stores the accompaniment, and the right channel stores the original vocals. You can set it according to your needs:
  • If you only want to hear the accompaniment, call this method and set the channel mode to left channel.
  • If you want to hear both the accompaniment and the original vocals, call this method and set the channel mode to mixed mode.

Timing

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

mode
Channel mode. See AUDIO_MIXING_DUAL_MONO_MODE.

Return Values

  • 0: Success.
  • < 0: Failure.

setAudioMixingPitch

Sets the pitch of the local music file.

virtual int setAudioMixingPitch(int pitch) = 0;

Call this method to adjust the pitch of the local music file independently when mixing it with local vocals.

Timing

You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

pitch
Sets the pitch of the local music file in semitone steps. The default value is 0, which means the original pitch. Range: -12 to 12. The pitch difference between two adjacent values is one semitone. The greater the absolute value, the more obvious the pitch change.

Return Values

  • 0: Success.
  • < 0: Failure.

setAudioMixingPlaybackSpeed

Sets the playback speed of the current audio file.

virtual int setAudioMixingPlaybackSpeed(int speed) = 0;

Make sure to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged callback reporting the state as AUDIO_MIXING_STATE_PLAYING.

Parameters

speed
Playback speed. It is recommended to set a value between 50 and 400, defined as follows:
  • 50: Half the original speed.
  • 100: Original speed.
  • 400: Four times the original speed.

Return Values

  • 0: Success.
  • < 0: Failure.

setAudioMixingPosition

Sets the starting playback position of the audio mixing file.

virtual int setAudioMixingPosition(int pos /*in ms*/) = 0;

Call this method to set the playback position of the music file to the specified start position. By default, playback starts from the beginning.

Timing

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

pos
Playback position in milliseconds.

Return Values

  • 0: Success.
  • < 0: Failure.

startAudioMixing [1/2]

Starts playing a music file.

virtual int startAudioMixing(const char* filePath, bool loopback, int cycle) = 0;
Deprecated
This method is deprecated. Use startAudioMixing(const char* filePath, bool loopback, int cycle, int startPos) instead.

If the local music file does not exist, the SDK does not support the file format, or the music file URL is not accessible, the SDK returns AUDIO_MIXING_REASON_CAN_NOT_OPEN.

Note:
  • If you use this method to play short sound effect files, playback may fail. It is recommended to use playEffect for such files.
  • If you need to call this method multiple times, ensure that the interval between calls is greater than 500 ms.
  • On Android, note the following:
    • Before using this method, make sure the Android device version is v4.2 or higher and the API level is v16 or higher.
    • If you need to play online music files, avoid using redirected URLs. Some Android devices may not be able to open redirected URLs.
    • If you call this method on an emulator, ensure the music file is located in the /sdcard/ directory and is in MP3 format.

Timing

You can call this method before or after joining a channel.

Related Callbacks

After successfully calling this method, the SDK triggers the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback. When the audio mixing file finishes playing, the SDK triggers the onAudioMixingStateChanged (AUDIO_MIXING_STATE_STOPPED) callback on the local client.

Parameters

filePath
File path. Supports both URL and absolute path of local files, including the file name and extension. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP.
Note: If you have preloaded the sound effect file into memory using preloadEffect, make sure this parameter matches the filePath parameter in preloadEffect.
loopback
Whether to play the music file only on the local client:
  • true: Play locally only; only the local user hears the music.
  • false: Publish the music to remote; both remote and local users hear the music.
cycle
Number of times the music file is played:
  • >0: Play the specified number of times. For example, 1 means play once.
  • -1: Loop indefinitely.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -1: General error (no specific reason).
    • -2: Invalid parameter.
    • -3: SDK not ready:
      • Audio module not enabled.
      • Program not completed.
      • IRtcEngine initialization failed. Please reinitialize IRtcEngine.

startAudioMixing [2/2]

Starts playing a music file.

virtual int startAudioMixing(const char* filePath, bool loopback, int cycle, int startPos) = 0;

If the local music file does not exist, the SDK does not support the file format, or the music file URL is not accessible, the SDK returns AUDIO_MIXING_REASON_CAN_NOT_OPEN.

Note:
  • If you use this method to play short sound effect files, playback may fail. Agora recommends using playEffect for such files.
  • If you need to call this method multiple times, ensure the interval between calls is greater than 500 ms.
  • On Android, note the following:
    • Ensure the Android device version is v4.2 or higher and the API level is v16 or higher.
    • If you need to play online music files, Agora does not recommend using redirected URLs. Some Android devices may not be able to open redirected URLs.
    • If you call this method on an emulator, ensure the music file is located in the /sdcard/ directory and is in MP3 format.

Timing

You can call this method before or after joining a channel.

Related Callbacks

After successfully calling this method, the SDK triggers the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback. When the audio mixing file finishes playing, the SDK triggers the onAudioMixingStateChanged (AUDIO_MIXING_STATE_STOPPED) callback on the local client.

Parameters

filePath
File path:
  • Android: The path must include the file name and extension. Supports URL, absolute path, or paths starting with /assets/. Using an absolute path to access local files may cause permission issues. It is recommended to use a URI, for example: content://com.android.providers.media.documents/document/audio%3A14441.
  • Windows: The absolute path or URL of the sound effect file (including the file extension), for example: C:\music\audio.mp4.
loopback
Whether to play the music file only on the local client:
  • true: Play locally only; only the local user hears the music.
  • false: Publish the music to remote; remote users also hear the music.
cycle
Number of times the music file is played:
  • >0: Play the specified number of times. For example, 1 means play once.
  • -1: Loop indefinitely.
startPos
The start position (in milliseconds) to play the music file.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -1: General error (no specific reason).
    • -2: Invalid parameter.
    • -3: SDK not ready:
      • Audio module is disabled.
      • Program not completed.
      • IRtcEngine initialization failed. Please reinitialize IRtcEngine.

stopAudioMixing

Stops playing the music file.

virtual int stopAudioMixing() = 0;

After calling startAudioMixing to play a music file, you can call this method to stop playback. If you only want to pause playback, call pauseAudioMixing.

Timing

Call this method after joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure.

onAudioMixingFinished

Callback triggered when the local music file finishes playing.

virtual void onAudioMixingFinished() __deprecated {}
Deprecated
This method is deprecated. Use onAudioMixingStateChanged instead.

This callback is triggered when the local music file finishes playing after calling startAudioMixing. If the call to startAudioMixing fails, it returns the error code WARN_AUDIO_MIXING_OPEN_ERROR.

Trigger Timing

Triggered when the local music file finishes playing after calling startAudioMixing.

onAudioMixingPositionChanged

Callback that reports the playback progress of the music file.

virtual void onAudioMixingPositionChanged(int64_t position) {}

After calling startAudioMixing to play a music file, the SDK triggers this callback every two seconds to report the playback progress.

Parameters

position
Playback progress in milliseconds.

Return Values

  • 0: Success.
  • < 0: Failure.

onAudioMixingStateChanged

Callback for music file playback state changes.

virtual void onAudioMixingStateChanged(AUDIO_MIXING_STATE_TYPE state, AUDIO_MIXING_REASON_TYPE reason)

This callback is triggered when the playback state of the music file changes and reports the current playback state and error code.

Parameters

state
The playback state of the music file. See AUDIO_MIXING_STATE_TYPE.
reason
The reason or error code for the playback state change. See AUDIO_MIXING_REASON_TYPE.

Audio Effect Files

getEffectCurrentPosition

Gets the playback position of the specified audio effect file.

virtual int getEffectCurrentPosition(int soundId) = 0;
Note: Use this method after calling playEffect.

Parameters

soundId
The audio effect ID.
Note: Each audio effect file has a unique ID.

Return Values

  • If the method call succeeds, returns the playback position (milliseconds) of the specified audio effect file.
  • < 0: Failure.

getEffectDuration

Gets the duration of an audio effect file.

virtual int getEffectDuration(const char* filePath) = 0;
Note: Call this method after joining a channel.

Parameters

filePath
The path to the audio effect file:
  • Android: The path must include the file name and extension. Supports URL, absolute path, or paths starting with /assets/. Using an absolute path to access local files may cause permission issues. It is recommended to use a URI, e.g., content://com.android.providers.media.documents/document/audio%3A14441.
  • Windows: The absolute path or URL to the audio effect file (including the file extension), e.g., C:\music\audio.mp4.
  • iOS or macOS: The absolute path or URL to the audio effect file (including the file extension), e.g., /var/mobile/Containers/Data/audio.mp4.

Return Values

  • If the method call succeeds, returns the total duration of the specified audio effect file (milliseconds).
  • < 0: Failure.

getEffectsVolume

Gets the current volume of sound effects.

virtual int getEffectsVolume() = 0;

Volume is an integer between 0 and 100. The default value is 100, which represents the original volume.

Note: Call this method after calling playEffect.

Return Values

  • 0: Success. Returns the volume of sound effects.
  • < 0: Failure.

getVolumeOfEffect

Gets the volume of the specified audio effect file.

virtual int getVolumeOfEffect(int soundId) = 0;

Parameters

soundId
The ID of the audio effect file.

Return Values

  • If the method call succeeds, returns the volume of the specified audio effect, in the range [0, 100], where 100 is the original volume.
  • < 0: Failure.

pauseAllEffects

Pauses all audio effects.

virtual int pauseAllEffects() = 0;

Return Values

  • 0: Success.
  • < 0: Failure.

pauseEffect

Pauses the playback of the specified audio effect file.

virtual int pauseEffect(int soundId) = 0;

Parameters

soundId
The audio effect ID. Each audio effect file has a unique ID.

Return Values

  • 0: Success.
  • < 0: Failure.

playAllEffects

Plays all audio effect files.

virtual int playAllEffects(int loopCount, double pitch, double pan, int gain, bool publish = false) = 0;

After preloading multiple audio effect files into memory by calling preloadEffect multiple times, you can call this method to play all loaded audio effects for all users in the channel.

Parameters

loopCount
The number of times the audio effect loops:
pitch
The pitch of the audio effect. The range is [0.5, 2.0], and the default is 1.0 (original pitch). The smaller the value, the lower the pitch.
pan
The spatial position of the audio effect. The range is [-1.0, 1.0]:
  • -1.0: The audio effect appears on the left.
  • 0: The audio effect appears in the center.
  • 1.0: The audio effect appears on the right.
gain
The volume of the audio effect. The range is [0, 100], and the default is 100 (original volume). The smaller the value, the lower the volume.
publish
Whether to publish the audio effect to remote users:
  • true: Publishes the audio effect to remote users. Both local and remote users can hear it.
  • false: (Default) Does not publish the audio effect. Only the local user can hear it.

Return Values

  • 0: Success.
  • < 0: Failure.

playEffect

Plays the specified local or online audio effect file.

virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false, int startPos = 0) = 0;

After calling preloadEffect, you can call this method to play the specified audio effect for all users in the channel. Each call to this method can only play one audio effect. To play multiple audio effects simultaneously, call this method multiple times. For the best user experience, Agora recommends not playing more than three audio effect files at the same time.

Note:
  • If you need to play an online audio effect file, Agora recommends caching it to the local device first, preloading it into memory using preloadEffect, and then calling this method to play the effect. Otherwise, playback may fail or be silent due to loading timeout or failure.
  • The audio effect ID and file path in this method must be the same as those in preloadEffect.
  • If you call preloadEffect before playEffect, the file resource will not be closed after playEffect is executed. The next time playEffect is called, it will start playing from the beginning.
  • If you do not call preloadEffect before playEffect, the resource will be destroyed after playEffect is executed. The next time playEffect is called, it will try to reopen the file and play from the beginning.

Timing

You can call this method either before or after joining a channel.

Related Callbacks

After this method is successfully called, the SDK triggers the onAudioEffectFinished callback to report the completion of the audio effect playback.

Parameters

soundId
The audio effect ID. The ID of each audio effect file must be unique. If you have preloaded the audio effect into memory using preloadEffect, ensure that this parameter value is the same as the soundId in preloadEffect.
filePath
The absolute path of the local audio effect file or the URL of the online audio effect file. Supported audio formats include: mp3, mp4, m4a, aac, 3gp, mkv, and wav.
loopCount
The number of times to loop the audio effect:
pitch
The pitch of the audio effect. The range is from 0.5 to 2.0, with the default value being 1.0 (original pitch). The smaller the value, the lower the pitch.
pan
The spatial position of the audio effect. The range is from -1.0 to 1.0:
  • -1.0: Audio effect is positioned to the left.
  • 0.0: Audio effect is centered.
  • 1.0: Audio effect is positioned to the right.
gain
The volume of the audio effect. The range is from 0 to 100, with the default value being 100 (original volume). The smaller the value, the lower the volume.
publish
Whether to publish the audio effect to remote users:
  • true: Publish the audio effect to remote users. Both local and remote users can hear it.
  • false: (Default) Do not publish the audio effect to remote users. Only the local user can hear it.
startPos
The start position for playing the audio effect file, in milliseconds.

Return Values

  • 0: Success.
  • < 0: Failure.

playEffectEx

Plays the specified sound effect in the channel.

virtual int playEffectEx(const RtcConnection& connection, int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false, int startPos = 0) = 0;
Since
Available since v4.6.0.

You can call this method to play a specified sound effect to all users in the channel. Each call to this method can only play one sound effect. To play multiple sound effects simultaneously, use different soundId and filePath values and call this method multiple times. You can also set whether to publish the sound effect in the channel.

Note:
  • Agora recommends not playing more than three sound effects simultaneously.
  • The sound effect ID and file path in this method must match those used in the preloadEffectEx method.
  • If you call preloadEffectEx before calling playEffectEx, the file resource will not be closed after playEffectEx is executed. The next time you call playEffectEx, playback will start from the beginning.
  • If you do not call preloadEffectEx before calling playEffectEx, the resource will be destroyed after playEffectEx is executed. The next time you call playEffectEx, it will attempt to reopen the file and start playback from the beginning.

Scenario

This method applies to multi-channel scenarios.

Parameters

connection
RtcConnection object. See RtcConnection.
soundId
Sound effect ID.
filePath
The absolute path of the local file or the URL of the online file. Supported audio formats include mp3, mp4, m4a, aac, 3gp, mkv, and wav.
loopCount
The number of times the sound effect is played in a loop:
pitch
The pitch of the sound effect. The value range is from 0.5 to 2.0, with the default being 1.0 (original pitch). The smaller the value, the lower the pitch.
pan
The spatial position of the sound effect. The value range is from -1.0 to 1.0:
  • -1.0: The sound effect comes from the user's left.
  • 0.0: The sound effect comes from directly in front of the user.
  • 1.0: The sound effect comes from the user's right.
gain
The volume of the sound effect. The value range is from 0 to 100, with the default being 100 (original volume). The smaller the value, the lower the volume.
publish
Whether to publish the sound effect in the channel:
  • true: Publish the sound effect in the channel.
  • false: (Default) Do not publish the sound effect in the channel.
startPos
The starting position of the sound effect file, in milliseconds.

Return Values

  • 0: Success.
  • < 0: Failure.

preloadEffect

Preloads the specified audio effect file.

virtual int preloadEffect(int soundId, const char* filePath, int startPos = 0) = 0;

Each time you call this method, only one specified audio effect file is preloaded into memory. To preload multiple audio effect files, call this method multiple times. After preloading, you can call playEffect to play the preloaded effect, or call playAllEffects to play all preloaded effects.

Note:
  • To ensure smooth communication, limit the size of the audio effect files.
  • Agora recommends calling this method before joining a channel.
  • If you call preloadEffect before playEffect, the file resource will not be closed after playEffect is executed. The next time you call playEffect, it will start playing from the beginning.
  • If you do not call preloadEffect before playEffect, the resource will be destroyed after playEffect is executed. The next time you call playEffect, it will try to reopen the file and play from the beginning.

Timing

It is recommended to call this method before joining a channel.

Parameters

soundId
The audio effect ID. The ID of each audio effect file must be unique.
filePath
The absolute path of the local audio effect file or the URL of the online audio effect file. Supported audio formats include: mp3, mp4, m4a, aac, 3gp, mkv, and wav.
startPos
The start position for playing the audio effect, in milliseconds. The default value is 0, which means to play from the beginning.

Return Values

  • 0: Success.
  • < 0: Failure.

preloadEffectEx

Preloads the specified sound effect into the channel.

virtual int preloadEffectEx(const RtcConnection& connection, int soundId, const char* filePath, int startPos = 0) = 0;
Since
Available since v4.6.0.

Each time you call this method, you can preload only one sound effect file into memory. To preload multiple sound effect files, call this method multiple times. After preloading is complete, you can call playEffect to play the preloaded sound effect, or call playAllEffects to play all preloaded sound effects.

Note:
  • To ensure a smooth user experience, the size of the sound effect file should not exceed the limit.
  • Agora recommends calling this method before joining a channel.
  • If you call preloadEffectEx before calling playEffectEx, the file resource will not be closed after playEffectEx is executed. The next time you call playEffectEx, playback will start from the beginning.
  • If you do not call preloadEffectEx before calling playEffectEx, the resource will be destroyed after playEffectEx is executed. The next time you call playEffectEx, it will attempt to reopen the file and start playback from the beginning.

Scenario

This method applies to multi-channel scenarios.

Parameters

connection
Connection information. See RtcConnection.
soundId
Sound effect ID.
filePath
The absolute path of the local file or the URL of the online file. Supported audio formats include: mp3, mp4, m4a, aac, 3gp, mkv, and wav.
startPos
The starting position (in milliseconds) for playing the sound effect file.

Return Values

  • 0: Success.
  • < 0: Failure.

resumeAllEffects

Resumes playing all audio effect files.

virtual int resumeAllEffects() = 0;

After pausing playback by calling pauseAllEffects, you can call this method to resume playback.

Timing

Call this method after calling pauseAllEffects.

Return Values

  • 0: Success.
  • < 0: Failure.

resumeEffect

Resumes playback of the specified audio effect.

virtual int resumeEffect(int soundId) = 0;

Parameters

soundId
The audio effect ID. Each audio effect file has a unique ID.

Return Values

  • 0: Success.
  • < 0: Failure.

setEffectPosition

Sets the playback position of the audio effect file.

virtual int setEffectPosition(int soundId, int pos) = 0;

After setting successfully, the audio effect file will play from the specified position.

Note: Call this method after calling playEffect.

Parameters

soundId
The audio effect ID. Each audio effect file has a unique ID.
pos
Playback position of the audio effect file, in milliseconds.

Return Values

  • 0: Success.
  • < 0: Failure.

setEffectsVolume

Sets the playback volume of sound effects.

virtual int setEffectsVolume(int volume) = 0;

Timing

Call this method after calling the playEffect method.

Parameters

volume
Playback volume. Range: [0, 100]. The default value is 100, which represents the original volume.

Return Values

  • 0: Success.
  • < 0: Failure.

setVolumeOfEffect

Sets the playback volume of the specified audio effect file.

virtual int setVolumeOfEffect(int soundId, int volume) = 0;

Timing

Call this method after calling playEffect.

Parameters

soundId
The unique ID of the audio effect file.
volume
Playback volume, in the range [0, 100]. The default is 100, which represents the original volume.

Return Values

  • 0: Success.
  • < 0: Failure.

stopAllEffects

Stops playing all audio effects.

virtual int stopAllEffects() = 0;

Call this method to stop all audio effects. To pause playback instead, call pauseAllEffects.

Timing

Call this method after calling playEffect.

Return Values

  • 0: Success.
  • < 0: Failure.

stopEffect

Stops playing the specified audio effect.

virtual int stopEffect(int soundId) = 0;

Call this method to stop playing the specified audio effect. To pause playback instead, call pauseEffect.

Timing

Call this method after calling playEffect.

Parameters

soundId
The ID of the audio effect. Each audio effect has a unique ID.

Return Values

  • 0: Success.
  • < 0: Failure.

unloadAllEffects

Releases all preloaded audio effects from memory.

virtual int unloadAllEffects() = 0;

Return Values

  • 0: Success.
  • < 0: Failure.

unloadEffect

Releases the specified preloaded audio effect file.

virtual int unloadEffect(int soundId) = 0;

After loading an audio effect file into memory using preloadEffect, you can call this method to release the file.

Timing

You can call this method before or after joining a channel.

Parameters

soundId
The ID of the audio effect.

Return Values

  • 0: Success.
  • < 0: Failure.

onAudioEffectFinished

Callback triggered when the local audio effect file finishes playing.

virtual void onAudioEffectFinished(int soundId) {}

This callback is triggered when the local audio effect file finishes playing. You can use this callback to determine whether the specified audio effect has completed playback.

Parameters

soundId
Audio effect ID, a unique identifier for each audio effect file.