Audio Mixing

adjustAudioMixingPlayoutVolume

Adjusts the local playback volume of the audio mixing.

public abstract int adjustAudioMixingPlayoutVolume(int volume);

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

Timing

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

Parameters

volume

The local playback volume of the audio mixing. The value range is [0, 100]. (Default is 100)

0: Mute.
100: Original volume.

Return Values

0: Success.
< 0: Failure.

adjustAudioMixingPublishVolume

Adjusts the audio mixing volume for publishing.

public abstract int adjustAudioMixingPublishVolume(int volume);

This method adjusts the audio mixing volume sent to other users.

Timing

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

Parameters

volume: The audio mixing volume for publishing. The value range is [0, 100], with a default of 100, which means the original volume.

Return Values

0: Success.
< 0: Failure.

adjustAudioMixingVolume

Adjusts the volume during audio mixing.

public abstract int adjustAudioMixingVolume(int volume);

This method adjusts the audio mixing volume on both the local and remote clients.

Note: adjustAudioMixingVolume does not affect the volume of sound effects set by the playEffect method.

Timing

Call this method after calling startAudioMixing.

Parameters

volume: The audio mixing volume. The value range is [0, 100]. (Default is 100, which means the original volume.)

Return Values

0: Success.
< 0: Failure.

getAudioMixingCurrentPosition

Gets the current playback position of the audio mixing (milliseconds).

public abstract int getAudioMixingCurrentPosition();

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 calls is greater than 500 milliseconds.

Return Values

On success, returns the current playback position of the audio mixing (milliseconds). 0 means the music file has not started playing.
< 0: Failure.

getAudioMixingDuration

Gets the duration of the audio mixing file (milliseconds).

public abstract int getAudioMixingDuration();

Timing

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

Return Values

On success, returns the duration of the audio mixing (milliseconds).
< 0: Failure.

getAudioMixingPlayoutVolume

Gets the local playback volume of the audio mixing.

public abstract int getAudioMixingPlayoutVolume();

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

On success, returns the audio mixing volume in the range [0, 100].
On failure, returns an error code less than 0.

getAudioMixingPublishVolume

Gets the audio mixing volume for publishing.

public abstract int getAudioMixingPublishVolume();

This method helps troubleshoot audio volume-related issues.

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 in the range [0, 100].
< 0: Failure.

getAudioTrackCount

Gets the audio track index of the current music file.

public abstract int getAudioTrackCount();

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

Return Values

On success, returns the audio track index.
< 0: Failure.

pauseAudioMixing

Pauses the playback and audio mixing of the music file.

public abstract int pauseAudioMixing();

After calling startAudioMixing to play a music file, you can call this method to pause the 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 audio mixing of the music file.

public abstract int resumeAudioMixing();

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

Timing

Call this method after joining a channel.

Return Values

0: Success.
< 0: Failure.

selectAudioTrack

Selects the audio track to use during playback.

public abstract int selectAudioTrack(int audioIndex);

After getting the audio track index of the file, you can call this method to specify any track for playback. For example, if different tracks of a multi-track file store songs in different languages, you can use this method to select the playback language.

Note:

For supported audio file formats, see [What audio file formats are supported by Agora RTC SDK](https://doc.shengwang.cn/faq/general-product-inquiry/audio-format).
You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

audioIndex: The index of the audio track you want to specify. This value must be greater than 0 and less than the value returned by getAudioTrackCount.

Return Values

0: Success.
< 0: Failure.

selectMultiAudioTrack

Selects the audio tracks to play locally and to publish to the channel.

int selectMultiAudioTrack(int playoutTrackIndex, int publishTrackIndex);

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

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. You can obtain this index via getStreamInfo.
publishTrackIndex: The index of the audio track to publish to the channel. You can obtain this index via getStreamInfo.

Return Values

0: The method call succeeds.
< 0: The method call fails.

setAudioMixingDualMonoMode

Sets the channel mode of the current audio file.

public abstract int setAudioMixingDualMonoMode(Constants.AudioMixingDualMonoMode mode);

You can set the channel mode of the audio file to original, left, right, or mixed mode as needed. For example, in a KTV scenario, the left channel stores accompaniment and the right channel stores the original vocals. You can set it based on your needs:

To hear only the accompaniment, set the channel mode to left.
To hear both accompaniment and vocals, set the channel mode to mixed.

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 AudioMixingDualMonoMode.

Return Values

0: Success.
< 0: Failure.

setAudioMixingPitch

Sets the pitch of the local music file.

public abstract int setAudioMixingPitch(int pitch);

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

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 semitones (default is 0). The value range is [-12, 12], where each increment or decrement represents one semitone. The greater the absolute value, the more noticeable the pitch change.

Return Values

0: Success.
< 0: Failure.

setAudioMixingPlaybackSpeed

Sets the playback speed of the current audio file.

public abstract int setAudioMixingPlaybackSpeed(int speed);

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

Parameters

speed

Playback speed. Recommended values are between 50 and 400, defined as:

50: Half the original speed.
100: Original speed.
400: Four times the original speed.

Return Values

0: Success.
< 0: Failure.

setAudioMixingPosition

Sets the playback position of the audio mixing.

public abstract int setAudioMixingPosition(int pos);

Timing

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

Parameters

pos: The playback position in milliseconds.

Return Values

0: Success.
< 0: Failure.

startAudioMixing [1/2]

Starts playing a music file.

public abstract int startAudioMixing(String filePath, boolean loopback, int cycle);

Deprecated: This method is deprecated. Use startAudioMixing [2/2] instead.

This method supports playing URI files that start with content://. For supported audio file formats, see the formats supported by the Agora RTC SDK. If the local music file does not exist, the SDK does not support the file format, or the music file URL is inaccessible, the SDK reports 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 each call is greater than 500 ms.
On Android, note the following:
- The Android device must be version v4.2 or later, and the API version must be v16 or later.
- If you need to play online music files, it is not recommended to use redirected URLs. Some Android devices may not be able to open redirected URLs.
- If you call this method on an emulator, ensure that 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 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback is triggered. When the audio mixing file finishes playing, the SDK triggers the onAudioMixingStateChanged (AUDIO_MIXING_STATE_STOPPED) callback on the local client.

Parameters

filePath

Note: If you have preloaded the sound effect into memory using preloadEffect, make sure the value of this parameter is the same as the filePath parameter in preloadEffect.

The file path. Supports the following types:

URI addresses that start with content://
Paths that start with /assets/
URLs
Absolute path of local files, including the file name and extension

Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP.

loopback

Whether to play the music file only on the local client:

true: Local playback only. Only the local user can hear the music.
false: Publish to remote. Remote users can also hear the music.

cycle

The number of times the music file is played:

> 0: Play the specified number of times. For example, 1 means play once.
-1: Play in an infinite loop.

Return Values

0: Success.
< 0: Failure.
- -1: A general error occurs (no specific reason).
- -2: Invalid parameter.
- -3: SDK not ready:
  - The audio module is not enabled.
  - The process is not completed.
  - RtcEngine initialization failed. Please reinitialize RtcEngine.

startAudioMixing [2/2]

Starts playing a music file.

public abstract int startAudioMixing(String filePath, boolean loopback, int cycle, int startPos);

This method supports playing URI files starting with content://. If the local music file does not exist, the SDK does not support the file format, or the music file URL is inaccessible, the SDK returns AUDIO_MIXING_REASON_CAN_NOT_OPEN.

Note:

If you call this method to play a short sound effect file, it may fail. Agora recommends using the playEffect method to play 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:
- The device must run Android v4.2 or later and API level v16 or higher.
- When playing online music files, Agora does not recommend using redirected URLs, as some Android devices may not support them.
- If calling this method on an emulator, ensure that 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

Successfully calling this method 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 locally.

Parameters

filePath

The file path. The path must include the file name and extension. Supports URL, absolute path, or paths starting with /assets/. Accessing local files using absolute paths may cause permission issues. Agora recommends using URI, for example: content://com.android.providers.media.documents/document/audio%3A14441.

loopback

Whether to play the music file only locally:

true: Play locally only. Only the local user hears the music.
false: Publish the music to remote users as well.

cycle

Number of times to play the music file:

> 0: Play the specified number of times. For example, 1 means play once.
-1: Loop indefinitely.

startPos

The starting position (in milliseconds) for playing the music file.

Return Values

0: Success.
< 0: Failure.
- -1: General error (unspecified reason).
- -2: Invalid parameter.
- -3: SDK not ready:
  - Audio module not enabled.
  - Incomplete setup.
  - RtcEngine initialization failed. Please reinitialize RtcEngine.

stopAudioMixing

Stops playing the music file.

public abstract int stopAudioMixing();

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 instead.

Timing

Call this method after joining a channel.

Return Values

0: Success.
< 0: Failure.

onAudioMixingFinished

Callback for when local music file playback ends.

public void onAudioMixingFinished()

Deprecated: This method is deprecated. Use onAudioMixingStateChanged instead.

After calling startAudioMixing to play a local music file, this callback is triggered when playback ends. If startAudioMixing fails, it returns the error code WARN_AUDIO_MIXING_OPEN_ERROR.

Trigger Timing

This callback is triggered when the local music file playback ends.

onAudioMixingPositionChanged

Callback for music file playback progress.

public void onAudioMixingPositionChanged(long position)

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

Trigger Timing

This callback is triggered every two seconds after calling startAudioMixing to play the music file.

Parameters

position: Playback progress in milliseconds.

onAudioMixingStateChanged

Callback for changes in music file playback state.

public void onAudioMixingStateChanged(int state, int reason)

This callback reports the current playback state and error code of the music file.

Trigger Timing

This callback is triggered when the playback state of the music file changes.

Parameters

state

The playback state of the music file:

AUDIO_MIXING_STATE_PLAYING (710): The music file is playing.
AUDIO_MIXING_STATE_PAUSED (711): The music file is paused.
AUDIO_MIXING_STATE_STOPPED (713): The music file is stopped.
AUDIO_MIXING_STATE_FAILED (714): An error occurred while playing the music file. The SDK returns the specific reason via the reason parameter.

reason

Error code:

AUDIO_MIXING_REASON_OK (0): No error.
AUDIO_MIXING_REASON_CAN_NOT_OPEN (701): The SDK cannot open the music file.
AUDIO_MIXING_REASON_TOO_FREQUENT_CALL (702): The SDK is opening the music file too frequently.
AUDIO_MIXING_REASON_INTERRUPTED_EOF (703): The music file playback is interrupted.
AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED (721): One loop of the music file playback is completed.
AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED (723): All loops of the music file playback are completed.
AUDIO_MIXING_REASON_STOPPED_BY_USER (724): The music file playback is stopped by calling stopAudioMixing.