Custom Audio Capture and Rendering

adjustCustomAudioPlayoutVolume

Adjusts the volume of the custom audio track for local playback.

public abstract int adjustCustomAudioPlayoutVolume(int trackId, int volume);

If you want to change the volume for local playback, you need to call this method again.

Note: Make sure to call createCustomAudioTrack to create a custom audio track before calling this method.

Parameters

trackId

Audio track ID. Set to the custom audio track ID returned by createCustomAudioTrack.

volume

Volume of the audio source, ranging from 0 to 100.

0: Mute.
100: Original volume.

Return Values

0: Success.
< 0: Failure.

adjustCustomAudioPublishVolume

Adjusts the volume of the custom audio track for remote playback.

public abstract int adjustCustomAudioPublishVolume(int trackId, int volume);

If you want to change the volume for remote playback, you need to call this method again.

Note: Make sure to call createCustomAudioTrack to create a custom audio track before calling this method.

Parameters

trackId

Audio track ID. Set to the custom audio track ID returned by createCustomAudioTrack.

volume

Volume of the audio source, ranging from 0 to 100.

0: Mute.
100: Original volume.

Return Values

0: Success.
< 0: Failure.

createCustomAudioTrack

Creates a custom audio track.

public abstract int createCustomAudioTrack(Constants.AudioTrackType trackType, AudioTrackConfig config)

You can publish a custom audio source by following these steps:

Call this method to create a custom audio track and get the track ID.
Call joinChannel to join a channel. In ChannelMediaOptions, set publishCustomAudioTrackId to the track ID obtained in step 1, and set publishCustomAudioTrack to true.
Call pushExternalAudioFrame and set trackId to the track ID from step 2 to publish the corresponding custom audio source in the channel.

Note: You must call this method before joining a channel.

Parameters

trackType: The type of the custom audio track. See AudioTrackType.
Note: If this parameter is set to AUDIO_TRACK_DIRECT, you must set publishMicrophoneTrack in ChannelMediaOptions to false when joining the channel, otherwise the join will fail and return error code -2.
config: Configuration of the custom audio track. See AudioTrackConfig.

Return Values

If the method call succeeds, returns the audio track ID as the unique identifier for the track.
If the method call fails, returns 0xffffffff.

destroyCustomAudioTrack

Destroys the specified audio track.

public abstract int destroyCustomAudioTrack(int trackId);

Parameters

trackId: The custom audio track ID returned by createCustomAudioTrack.

Return Values

0: Success.
< 0: Failure.

enableCustomAudioLocalPlayback

Enables or disables local playback of external audio sources.

public abstract int enableCustomAudioLocalPlayback(int trackId, boolean enabled);

You can call adjustCustomAudioPlayoutVolume to adjust the local playback volume of the custom audio track.

Note: Make sure to call createCustomAudioTrack to create a custom audio track before calling this method.

Parameters

trackId

Audio track ID, should be the custom audio track ID returned by createCustomAudioTrack.

enabled

Whether to play the external audio source:

true: Play the external audio source.
false: (Default) Do not play the external audio source.

Return Values

0: Success.
< 0: Failure.

pullPlaybackAudioFrame [1/2]

Pulls mixed remote audio data for playback.

public abstract int pullPlaybackAudioFrame(byte[] data, int lengthInByte);

Before calling this method, call setExternalAudioSink and set enabled to true to enable external audio rendering.

Note: pullPlaybackAudioFrame and onPlaybackAudioFrame can both be used to obtain mixed remote audio data. After enabling external audio rendering (by calling setExternalAudioSink), you can no longer get data from onPlaybackAudioFrame. Choose pullPlaybackAudioFrame or onPlaybackAudioFrame based on your actual needs. Differences:

pullPlaybackAudioFrame: The app pulls audio data from the SDK. The SDK adjusts the frame buffer to help handle latency and avoid audio jitter.
onPlaybackAudioFrame: The SDK pushes audio data to the app via callback. If there is delay in processing, it may cause jitter.

This method is only for pulling mixed remote audio data. To get data from other stages like capture or playback, use registerAudioFrameObserver to register related callbacks.

Timing

You need to call this method after joining a channel.

Parameters

data: Output parameter. The remote audio data to pull.
lengthInByte: Data length in bytes. This depends on audio duration, and the sampleRate and channels set in setExternalAudioSink. Formula: lengthInByte = sampleRate / 1000 × 2 × channels × duration (ms).

Return Values

0: Success.
< 0: Failure.

pullPlaybackAudioFrame [2/2]

Pulls remote audio data.

public abstract int pullPlaybackAudioFrame(ByteBuffer data, int lengthInByte);

Before calling this method, you need to call setExternalAudioSink and set enabled to true to enable and configure external audio playback. After calling this method successfully, the app pulls decoded and mixed audio data for playback.

Note:

This method must be called after joining a channel.
Differences from onPlaybackAudioFrame:
- onPlaybackAudioFrame: The SDK pushes audio data to the app. Processing delay may cause jitter.
- pullPlaybackAudioFrame: The app pulls remote audio data. The SDK adjusts the frame buffer to avoid jitter in external playback.

Parameters

data: Receives the pulled remote audio data. See ByteBuffer.
lengthInByte: Byte length of the remote audio data. This depends on audio duration, and the sampleRate and channels set in setExternalAudioSink. lengthInByte = sampleRate / 1000 × 2 × channels × duration (ms).

Return Values

0: Success.
< 0: Failure.

pushExternalAudioFrame

Pushes external audio data to the app.

public abstract int pushExternalAudioFrame(byte[] data, long timestamp)

Deprecated: This method is deprecated. Use pushExternalAudioFrame(byte[] data, long timestamp, int sampleRate, int channels, Constants.BytesPerSample bytesPerSample, int trackId) instead.

Parameters

data: Audio data buffer.
timestamp: Timestamp of the audio data.

Return Values

0: Success.
< 0: Failure.

setExternalAudioSink

Sets the external audio renderer.

public abstract int setExternalAudioSink(boolean enabled, int sampleRate, int channels);

After enabling the external audio renderer, you can call pullPlaybackAudioFrame to pull remote audio frames. The app can process the remote audio and apply desired effects for playback.

Note: After enabling the external audio renderer, the app cannot receive any audio data from the onPlaybackAudioFrame callback.

Scenario

Applicable to scenarios where external audio data is used for playback.

Timing

Call this method before joining a channel.

Parameters

enabled

Whether to enable the external audio renderer:

true: Enable.
false: (Default) Disable.

sampleRate

Sample rate (Hz) of the external audio renderer. Supported values:

16000
32000
44100
48000

channels

Number of channels of the external audio renderer:

1: Mono.
2: Stereo.

Return Values

0: Success.
< 0: Failure.

setExternalAudioSource [1/2]

Sets the external audio source.

public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels);

Deprecated: This method is deprecated. Use createCustomAudioTrack instead.

Call this method before joinChannel and startPreview.

Parameters

enabled

Whether to enable the external audio source:

true: Enable.
false: (Default) Disable.

sampleRate

Sample rate (Hz) of the external audio source. Supported values:

8000
16000
32000
44100
48000.

channels

Number of channels of the external audio source:

1: Mono.
2: Stereo.

Return Values

0: Success.
< 0: Failure.

setExternalAudioSource [2/2]

Sets external audio source parameters.

public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels, boolean localPlayback, boolean publish);

Deprecated: This method is deprecated. Use createCustomAudioTrack instead.

Timing

Call this method before joining a channel.

Parameters

enabled

Whether to enable the external audio source:

true: Enable external audio source.
false: (Default) Do not enable external audio source.

sampleRate

Sample rate (Hz) of the external audio source. Available values:

8000
16000
32000
44100
48000.

channels

Number of channels in the external audio source. Available values:

1: Mono.
2: Stereo.

localPlayback

Whether to play the external audio source locally:

true: Play external audio source.
false: (Default) Do not play external audio source.

publish

Whether to publish the audio to remote users:

true: (Default) Publish audio to remote users.
false: Do not publish audio to remote users.

Return Values

0: Success.
< 0: Failure.