native_audiorenderer.h

Overview

The file declares the functions related to an audio renderer.

File to include: <ohaudio/native_audiorenderer.h>

Library: libohaudio.so

System capability: SystemCapability.Multimedia.Audio.Core

Since: 10

Related module: OHAudio

Summary

Functions

Name	typedef Keyword	Description
OH_AudioStream_Result OH_AudioRenderer_Release(OH_AudioRenderer* renderer)	-	Releases an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_Start(OH_AudioRenderer* renderer)	-	Starts an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_Pause(OH_AudioRenderer* renderer)	-	Pauses an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_Stop(OH_AudioRenderer* renderer)	-	Stops an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_Flush(OH_AudioRenderer* renderer)	-	Clears audio data in the buffer.
OH_AudioStream_Result OH_AudioRenderer_GetCurrentState(OH_AudioRenderer* renderer, OH_AudioStream_State* state)	-	Obtains the state of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetSamplingRate(OH_AudioRenderer* renderer, int32_t* rate)	-	Obtains the sampling rate of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetStreamId(OH_AudioRenderer* renderer, uint32_t* streamId)	-	Obtains the stream ID of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetChannelCount(OH_AudioRenderer* renderer, int32_t* channelCount)	-	Obtains the number of channels for an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetSampleFormat(OH_AudioRenderer* renderer, OH_AudioStream_SampleFormat* sampleFormat)	-	Obtains the sampling format of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetLatencyMode(OH_AudioRenderer* renderer, OH_AudioStream_LatencyMode* latencyMode)	-	Obtains the latency mode of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetRendererInfo(OH_AudioRenderer* renderer, OH_AudioStream_Usage* usage)	-	Obtains the usage type of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetEncodingType(OH_AudioRenderer* renderer, OH_AudioStream_EncodingType* encodingType)	-	Obtains the encoding type of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetFramesWritten(OH_AudioRenderer* renderer, int64_t* frames)	-	Obtains the number of frames that have been written since the stream was created.
OH_AudioStream_Result OH_AudioRenderer_GetTimestamp(OH_AudioRenderer* renderer, clockid_t clockId, int64_t* framePosition, int64_t* timestamp)	-	Obtains the timestamp and position information of an output audio stream. This function obtains the actual playback position (specified by framePosition) of the audio channel and the timestamp when playing to that position (specified by timestamp, in nanoseconds). When you switch devices or resume playback after a pause, the playback position and timestamp retrieved via this function will temporarily stay in the state they were in before the switch or pause, since the playback channel requires a moment to stabilize. This API is used to implement audio-video synchronization. Frequent calls may result in power consumption issues. You are advised to call the API at an interval not less than 200 ms, and the API can be called once every minute. Therefore, do not frequently query the timestamp when the audio-video synchronization effect can be ensured.
OH_AudioStream_Result OH_AudioRenderer_GetAudioTimestampInfo(OH_AudioRenderer* renderer, int64_t* framePosition, int64_t* timestamp)	-	Obtains the timestamp and position information of an output audio stream. It adapts to the speed adjustment interface. This information is commonly used for audio and video synchronization.
OH_AudioStream_Result OH_AudioRenderer_GetFrameSizeInCallback(OH_AudioRenderer* renderer, int32_t* frameSize)	-	Obtains the frame size in the callback. The frame size is the fixed length of the buffer returned by each callback.
OH_AudioStream_Result OH_AudioRenderer_GetSpeed(OH_AudioRenderer* renderer, float* speed)	-	Obtains the rate of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_SetSpeed(OH_AudioRenderer* renderer, float speed)	-	Sets the rate for an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_SetMarkPosition(OH_AudioRenderer* renderer, uint32_t samplePos, OH_AudioRenderer_OnMarkReachedCallback callback, void* userData)	-	Sets the mark position for an audio renderer. When this function is called, the mark position that has been set will be overwritten.
OH_AudioStream_Result OH_AudioRenderer_CancelMark(OH_AudioRenderer* renderer)	-	Cancels the mark set by OH_AudioRenderer_SetMarkPosition.
OH_AudioStream_Result OH_AudioRenderer_SetVolume(OH_AudioRenderer* renderer, float volume)	-	Sets the volume for an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_SetVolumeWithRamp(OH_AudioRenderer* renderer, float volume, int32_t durationMs)	-	Sets the volume with a ramp within the specified duration for an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetVolume(OH_AudioRenderer* renderer, float* volume)	-	Obtains the volume of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetUnderflowCount(OH_AudioRenderer* renderer, uint32_t* count)	-	Obtains the number of underloaded audio streams of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetChannelLayout(OH_AudioRenderer* renderer, OH_AudioChannelLayout* channelLayout)	-	Obtains the channel layout of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetEffectMode(OH_AudioRenderer* renderer, OH_AudioStream_AudioEffectMode* effectMode)	-	Obtains the effect mode of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_SetEffectMode(OH_AudioRenderer* renderer, OH_AudioStream_AudioEffectMode effectMode)	-	Sets the effect mode for an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetRendererPrivacy(OH_AudioRenderer* renderer, OH_AudioStream_PrivacyType* privacy)	-	Checks whether the audio stream being played can be recorded by other applications.
OH_AudioStream_Result OH_AudioRenderer_SetSilentModeAndMixWithOthers(OH_AudioRenderer* renderer, bool on)	-	Sets the silent mode in concurrent playback for an audio renderer. If the silent mode in concurrent playback is enabled, the system mutes the audio stream and does not interrupt other audio streams. If the silent mode in concurrent playback is disabled, the audio stream can gain focus based on the system focus strategy.
OH_AudioStream_Result OH_AudioRenderer_GetSilentModeAndMixWithOthers(OH_AudioRenderer* renderer, bool* on)	-	Checks whether the silent mode in concurrent playback is enabled for an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_SetDefaultOutputDevice(OH_AudioRenderer* renderer, OH_AudioDevice_Type deviceType)	-	Sets the default built-in audio output device. This function applies only to the scenario where OH_AudioStream_Usage is set to voice messages, VoIP voice calls, and VoIP video calls and the available device types are the receiver, speaker, and system default device. This function can be called at any time after an AudioRenderer instance is created. The system records the default built-in audio output device set by the application. When the application is started, if an external device such as a Bluetooth or wired headset is connected, the system preferentially uses the external device to play sound. Otherwise, the system uses this default device to play sound.
typedef void (*OH_AudioRenderer_OnInterruptCallback)(OH_AudioRenderer* renderer, void* userData, OH_AudioInterrupt_ForceType type, OH_AudioInterrupt_Hint hint)	OH_AudioRenderer_OnInterruptCallback	Defines the callback for interruption events of an audio renderer.
typedef void (*OH_AudioRenderer_OnErrorCallback)(OH_AudioRenderer* renderer, void* userData, OH_AudioStream_Result error)	OH_AudioRenderer_OnErrorCallback	Defines the callback for error events of an audio renderer.
OH_AudioStream_Result OH_AudioRenderer_GetFastStatus(OH_AudioRenderer* renderer, OH_AudioStream_FastStatus* status)	-	Obtains the running status of an audio renderer to determine whether it is running in low-latency mode.
typedef void (*OH_AudioRenderer_OnFastStatusChange)(OH_AudioRenderer* renderer, void* userData, OH_AudioStream_FastStatus status)	OH_AudioRenderer_OnFastStatusChange	Defines a callback function for low-latency status changes during audio playback.
OH_AudioStream_Result OH_AudioRenderer_SetLoudnessGain(OH_AudioRenderer* renderer, float loudnessGain)	-	Sets the loudness of audio playback. The default loudness value is 0.0 dB. The audio stream playback type must be one of the following: Music: OH_AudioStream_Usage.AUDIOSTREAM_USAGE_MUSIC; movies or videos: OH_AudioStream_Usage.AUDIOSTREAM_USAGE_MOVIE; audiobooks (including books, crosstalk, and storytelling), audio news, podcasts, and others: OH_AudioStream_Usage.AUDIOSTREAM_USAGE_AUDIOBOOK. The latency mode of the audio stream must be OH_AudioStream_LatencyMode.AUDIOSTREAM_LATENCY_MODE_NORMAL. Loudness settings are not supported for high-definition audio channels. Due to the buffer between the audio framework and hardware, there may be a delay in the actual effect of loudness adjustment. The delay duration depends on the buffer length. You are advised to set the loudness before starting playback of different audio streams to achieve the optimal balance effect.
OH_AudioStream_Result OH_AudioRenderer_GetLoudnessGain(OH_AudioRenderer* renderer, float* loudnessGain)	-	Obtains the loudness of audio playback.
typedef int32_t (*OH_AudioRenderer_OnWriteDataCallbackAdvanced)(OH_AudioRenderer* renderer, void* userData, void* audioData, int32_t audioDataSize)	OH_AudioRenderer_OnWriteDataCallbackAdvanced	Defines a function pointer to the callback used to write audio data. Unlike OH_AudioRenderer_OnWriteDataCallback, this function allows the application to fill data of the length ranging [0, audioDataSize]. Here, audioDataSize refers to the length of the callback buffer. The caller notifies the system of the length of the data written through the return value. If the return value is 0, the callback thread sleeps for a period of time. Otherwise, the system may immediately initiate the next callback.
OH_AudioStream_Result OH_AudioRenderer_GetLatency(OH_AudioRenderer* renderer, OH_AudioStream_LatencyType type, int32_t* latencyMs)	-	Obtains the estimated latency of the current audio route, in milliseconds. For audio devices connected in wireless mode, the latency estimation may be inaccurate. The result is for reference only. Since the latency is not counted in the real-time buffer, you are advised to obtain the latency only when audio playback starts. Frequent calls may block this API due to route switching. After audio data is output to the hardware, you are advised to use OH_AudioRenderer_GetAudioTimestampInfo for audio-video synchronization.
OH_AudioStream_Result OH_AudioRenderer_SetIndependentAudioSessionStrategy(OH_AudioRenderer* renderer, const OH_AudioSession_Strategy* strategy, uint32_t behavior)	-	Sets the independent audio session strategy and behavior parameters. If this API is called while an audio renderer is running, you must call the OH_AudioRenderer_Start API again for the settings to take effect.

Function Description

OH_AudioRenderer_Release()

OH_AudioStream_Result OH_AudioRenderer_Release(OH_AudioRenderer* renderer)

Description

Releases an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal.

OH_AudioRenderer_Start()

OH_AudioStream_Result OH_AudioRenderer_Start(OH_AudioRenderer* renderer)

Description

Starts an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal.

OH_AudioRenderer_Pause()

OH_AudioStream_Result OH_AudioRenderer_Pause(OH_AudioRenderer* renderer)

Description

Pauses an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal.

OH_AudioRenderer_Stop()

OH_AudioStream_Result OH_AudioRenderer_Stop(OH_AudioRenderer* renderer)

Description

Stops an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal.

OH_AudioRenderer_Flush()

OH_AudioStream_Result OH_AudioRenderer_Flush(OH_AudioRenderer* renderer)

Description

Clears audio data in the buffer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal.

OH_AudioRenderer_GetCurrentState()

OH_AudioStream_Result OH_AudioRenderer_GetCurrentState(OH_AudioRenderer* renderer, OH_AudioStream_State* state)

Description

Obtains the state of an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioStream_State* state	Pointer to a variable used to receive the state.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetSamplingRate()

OH_AudioStream_Result OH_AudioRenderer_GetSamplingRate(OH_AudioRenderer* renderer, int32_t* rate)

Description

Obtains the sampling rate of an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
int32_t* rate	Pointer to a variable used to receive the sampling rate.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetStreamId()

OH_AudioStream_Result OH_AudioRenderer_GetStreamId(OH_AudioRenderer* renderer, uint32_t* streamId)

Description

Obtains the stream ID of an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
uint32_t* streamId	Pointer to a variable used to receive the stream ID.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetChannelCount()

OH_AudioStream_Result OH_AudioRenderer_GetChannelCount(OH_AudioRenderer* renderer, int32_t* channelCount)

Description

Obtains the number of channels for an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
int32_t* channelCount	Pointer to a variable used to receive the channel count.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetSampleFormat()

OH_AudioStream_Result OH_AudioRenderer_GetSampleFormat(OH_AudioRenderer* renderer, OH_AudioStream_SampleFormat* sampleFormat)

Description

Obtains the sampling format of an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioStream_SampleFormat* sampleFormat	Pointer to a variable used to receive the sampling format.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetLatencyMode()

OH_AudioStream_Result OH_AudioRenderer_GetLatencyMode(OH_AudioRenderer* renderer, OH_AudioStream_LatencyMode* latencyMode)

Description

Obtains the latency mode of an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioStream_LatencyMode* latencyMode	Pointer to a variable used to receive the latency mode.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetRendererInfo()

OH_AudioStream_Result OH_AudioRenderer_GetRendererInfo(OH_AudioRenderer* renderer, OH_AudioStream_Usage* usage)

Description

Obtains the usage type of an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioStream_Usage* usage	Pointer to a variable used to receive the usage type.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetEncodingType()

OH_AudioStream_Result OH_AudioRenderer_GetEncodingType(OH_AudioRenderer* renderer, OH_AudioStream_EncodingType* encodingType)

Description

Obtains the encoding type of an audio renderer.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioStream_EncodingType* encodingType	Pointer to a variable used to receive the encoding type.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetFramesWritten()

OH_AudioStream_Result OH_AudioRenderer_GetFramesWritten(OH_AudioRenderer* renderer, int64_t* frames)

Description

Obtains the number of frames that have been written since the stream was created.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
int64_t* frames	Pointer to a variable used to receive the frame count.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetTimestamp()

OH_AudioStream_Result OH_AudioRenderer_GetTimestamp(OH_AudioRenderer* renderer, clockid_t clockId, int64_t* framePosition, int64_t* timestamp)

Description

Obtains the timestamp and position information of an output audio stream.
This function obtains the actual playback position (specified by framePosition) of the audio channel and the timestamp when playing to that position (specified by timestamp, in nanoseconds).
When you switch devices or resume playback after a pause, the playback position and timestamp retrieved via this function will temporarily stay in the state they were in before the switch or pause, since the playback channel requires a moment to stabilize.
This API is used to implement audio-video synchronization. You are advised to keep the API call frequency within reasonable limits, such as once per minute. The minimal interval between calls should not be less than 200 ms. Frequent calls may increase power consumption. Therefore, do not frequently query the timestamp when the audio-video synchronization effect can be ensured.

NOTE

• When the actual playback position (framePosition) is 0, the timestamp remains fixed until the stream begins playback.
• The playback position is also reset when Flush is called.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
clockid_t clockId	Clock identifier. Use CLOCK_MONOTONIC.
int64_t* framePosition	Pointer to a variable used to receive the position information.
int64_t* timestamp	Pointer to a variable used to receive the timestamp, in nanoseconds.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr. 2. The clockId parameter is set to an invalid value. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal.

OH_AudioRenderer_GetAudioTimestampInfo()

OH_AudioStream_Result OH_AudioRenderer_GetAudioTimestampInfo(OH_AudioRenderer* renderer, int64_t* framePosition, int64_t* timestamp)

Description

Obtains the timestamp and position information of an output audio stream. It adapts to the speed adjustment interface.
This information is commonly used for audio and video synchronization.

NOTE

• When the actual playback position (framePosition) is 0, the timestamp remains fixed until the stream begins playback.
• The playback position is also reset when Flush is called.
• Additionally, changes in the audio stream route, such as switching devices or output types, will reset the playback position, whereas the timestamp keeps increasing. You are advised to call this function to obtain the corresponding value only when the actual playback position and timestamp are stable. This function adapts to the speed adjustment interface. For example, if the playback speed is set to 2x, the rate at which the playback position increases is also twice the normal speed.

Since: 15

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
int64_t* framePosition	Pointer to a variable used to receive the position information.
int64_t* timestamp	Pointer to a variable used to receive the timestamp, in nanoseconds.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr. 2. The framePosition or timestamp parameter is nullptr. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The current stream status is invalid. AUDIOSTREAM_ERROR_SYSTEM: 1. The system process breaks down or is blocked. 2. An internal system error occurs.

OH_AudioRenderer_GetFrameSizeInCallback()

OH_AudioStream_Result OH_AudioRenderer_GetFrameSizeInCallback(OH_AudioRenderer* renderer, int32_t* frameSize)

Description

Obtains the frame size in the callback. The frame size is the fixed length of the buffer returned by each callback.

Since: 10

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
int32_t* frameSize	Pointer to a variable used to receive the frame size.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetSpeed()

OH_AudioStream_Result OH_AudioRenderer_GetSpeed(OH_AudioRenderer* renderer, float* speed)

Description

Obtains the rate of an audio renderer.

Since: 11

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
float* speed	Pointer to the variable that receives the playback rate.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_SetSpeed()

OH_AudioStream_Result OH_AudioRenderer_SetSpeed(OH_AudioRenderer* renderer, float speed)

Description

Sets the rate for an audio renderer.

Since: 11

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
float speed	Playback rate, which ranges from 0.25 to 4.0.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_SetMarkPosition()

OH_AudioStream_Result OH_AudioRenderer_SetMarkPosition(OH_AudioRenderer* renderer, uint32_t samplePos, OH_AudioRenderer_OnMarkReachedCallback callback, void* userData)

Description

Sets the mark position for an audio renderer. When this function is called, the mark position that has been set will be overwritten.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
uint32_t samplePos	Mark position.
OH_AudioRenderer_OnMarkReachedCallback callback	Callback invoked when the target mark position is reached.
void* userData	Pointer to the application data passed through the callbacks.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr. 2. The samplePos parameter is set to an invalid value. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal. AUDIOSTREAM_ERROR_SYSTEM: A system error occurs.

OH_AudioRenderer_CancelMark()

OH_AudioStream_Result OH_AudioRenderer_CancelMark(OH_AudioRenderer* renderer)

Description

Cancels the mark set by OH_AudioRenderer_SetMarkPosition.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_SetVolume()

OH_AudioStream_Result OH_AudioRenderer_SetVolume(OH_AudioRenderer* renderer, float volume)

Description

Sets the volume for an audio renderer.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
float volume	Target volume, in the range of [0.0, 1.0].

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr. 2. The volume parameter is set to an invalid value. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal. AUDIOSTREAM_ERROR_SYSTEM: A system error occurs.

OH_AudioRenderer_SetVolumeWithRamp()

OH_AudioStream_Result OH_AudioRenderer_SetVolumeWithRamp(OH_AudioRenderer* renderer, float volume, int32_t durationMs)

Description

Sets the volume with a ramp within the specified duration for an audio renderer.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
float volume	Target volume, in the range of [0.0, 1.0].
int32_t durationMs	Duration, in milliseconds.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr. 2. The volume parameter is set to an invalid value. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal. AUDIOSTREAM_ERROR_SYSTEM: A system error occurs.

OH_AudioRenderer_GetVolume()

OH_AudioStream_Result OH_AudioRenderer_GetVolume(OH_AudioRenderer* renderer, float* volume)

Description

Obtains the volume of an audio renderer.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
float* volume	Pointer to the audio volume, in the range of [0.0, 1.0].

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr. 2. The volume parameter is nullptr.

OH_AudioRenderer_GetUnderflowCount()

OH_AudioStream_Result OH_AudioRenderer_GetUnderflowCount(OH_AudioRenderer* renderer, uint32_t* count)

Description

Obtains the number of underloaded audio streams of an audio renderer.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
uint32_t* count	Pointer to a variable used to receive the number of underloaded audio streams.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr. 2. The count parameter is nullptr.

OH_AudioRenderer_GetChannelLayout()

OH_AudioStream_Result OH_AudioRenderer_GetChannelLayout(OH_AudioRenderer* renderer, OH_AudioChannelLayout* channelLayout)

Description

Obtains the channel layout of an audio renderer.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioChannelLayout* channelLayout	Pointer to a variable used to receive the channel layout.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetEffectMode()

OH_AudioStream_Result OH_AudioRenderer_GetEffectMode(OH_AudioRenderer* renderer, OH_AudioStream_AudioEffectMode* effectMode)

Description

Obtains the effect mode of an audio renderer.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioStream_AudioEffectMode* effectMode	Pointer to a variable used to receive the effect mode.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_SetEffectMode()

OH_AudioStream_Result OH_AudioRenderer_SetEffectMode(OH_AudioRenderer* renderer, OH_AudioStream_AudioEffectMode effectMode)

Description

Sets the effect mode for an audio renderer.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioStream_AudioEffectMode effectMode	Effect mode to set.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetRendererPrivacy()

OH_AudioStream_Result OH_AudioRenderer_GetRendererPrivacy(OH_AudioRenderer* renderer, OH_AudioStream_PrivacyType* privacy)

Description

Checks whether the audio stream being played can be recorded by other applications.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioStream_PrivacyType* privacy	Pointer to the privacy type, which specifies whether the audio stream being played can be recorded by other applications.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_SetSilentModeAndMixWithOthers()

OH_AudioStream_Result OH_AudioRenderer_SetSilentModeAndMixWithOthers(OH_AudioRenderer* renderer, bool on)

Description

Sets the silent mode in concurrent playback for an audio renderer.
If the silent mode in concurrent playback is enabled, the system mutes the audio stream and does not interrupt other audio streams. If the silent mode in concurrent playback is disabled, the audio stream can gain focus based on the system focus strategy.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
bool on	Status of the silent mode in concurrent playback. The value true means that the audio stream being played is muted and the playback of other audio streams is not interrupted. The value false means that the audio stream being played is unmuted and can gain focus based on the system focus strategy.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_GetSilentModeAndMixWithOthers()

OH_AudioStream_Result OH_AudioRenderer_GetSilentModeAndMixWithOthers(OH_AudioRenderer* renderer, bool* on)

Description

Checks whether the silent mode in concurrent playback is enabled for an audio renderer.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
bool* on	Whether the silent mode in concurrent playback is enabled. true if enabled, false otherwise.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr.

OH_AudioRenderer_SetDefaultOutputDevice()

OH_AudioStream_Result OH_AudioRenderer_SetDefaultOutputDevice(OH_AudioRenderer* renderer, OH_AudioDevice_Type deviceType)

Description

Sets the default built-in audio output device.
This function applies only to the scenario where OH_AudioStream_Usage is set to voice messages, VoIP voice calls, and VoIP video calls and the available device types are the receiver, speaker, and system default device.
This function can be called at any time after an AudioRenderer instance is created. The system records the default built-in audio output device set by the application. When the application is started, if an external device such as a Bluetooth or wired headset is connected, the system preferentially uses the external device to play sound. Otherwise, the system uses this default device to play sound.

Device behavior difference: If the default audio output device is set to earpiece on a device without an earpiece, the speaker will still be used for audio output.

Since: 12

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioDevice_Type deviceType	Device type. For details about the available options, see OH_AudioDevice_Type. The device types that can be set are as follows: AUDIO_DEVICE_TYPE_EARPIECE: receiver. AUDIO_DEVICE_TYPE_SPEAKER: speaker. AUDIO_DEVICE_TYPE_DEFAULT: system default device.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr. 2. The deviceType parameter is set to an invalid value. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal. AUDIOSTREAM_ERROR_SYSTEM: A system error occurs.

OH_AudioRenderer_OnInterruptCallback()

typedef void (*OH_AudioRenderer_OnInterruptCallback)(OH_AudioRenderer* renderer, void* userData, OH_AudioInterrupt_ForceType type, OH_AudioInterrupt_Hint hint)

Description

Defines the callback for interruption events of an audio renderer.

Since: 20

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
void* userData	Pointer to the data storage area customized by the application.
OH_AudioInterrupt_ForceType type	Type of force that causes audio interruption.
OH_AudioInterrupt_Hint hint	Hint provided along with audio interruption.

OH_AudioRenderer_OnErrorCallback()

typedef void (*OH_AudioRenderer_OnErrorCallback)(OH_AudioRenderer* renderer, void* userData, OH_AudioStream_Result error)

Description

Defines the callback for error events of an audio renderer.

Since: 20

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
void* userData	Pointer to the data storage area customized by the application.
OH_AudioStream_Result error	Audio renderer error.

OH_AudioRenderer_GetFastStatus()

OH_AudioStream_Result OH_AudioRenderer_GetFastStatus(OH_AudioRenderer* renderer, OH_AudioStream_FastStatus* status)

Description

Obtains the running status of an audio renderer to determine whether it is running in low-latency mode.

Since: 20

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioStream_FastStatus* status	Pointer to the running status.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The renderer parameter is nullptr. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The function is called in an incorrect state.

OH_AudioRenderer_OnFastStatusChange()

typedef void (*OH_AudioRenderer_OnFastStatusChange)(OH_AudioRenderer* renderer, void* userData, OH_AudioStream_FastStatus status
)

Description

Defines a callback function for low-latency status changes during audio playback.

Since: 20

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
void* userData	Pointer to the data storage area customized by the application.
OH_AudioStream_FastStatus status	Low-latency status.

OH_AudioRenderer_SetLoudnessGain()

OH_AudioStream_Result OH_AudioRenderer_SetLoudnessGain(OH_AudioRenderer* renderer, float loudnessGain)

Description

Sets the loudness of audio playback. The default loudness value is 0.0 dB. The audio stream playback type must be one of the following: Music: OH_AudioStream_Usage.AUDIOSTREAM_USAGE_MUSIC;
movies or videos: OH_AudioStream_Usage.AUDIOSTREAM_USAGE_MOVIE;
audiobooks (including books, crosstalk, and storytelling), audio news, podcasts, and others: OH_AudioStream_Usage.AUDIOSTREAM_USAGE_AUDIOBOOK.
The latency mode of the audio stream must be OH_AudioStream_LatencyMode.AUDIOSTREAM_LATENCY_MODE_NORMAL.
Loudness settings are not supported for high-definition audio channels.
Due to the buffer between the audio framework and hardware, there may be a delay in the actual effect of loudness adjustment. The delay duration depends on the buffer length.
You are advised to set the loudness before starting playback of different audio streams to achieve the optimal balance effect.

Since: 20

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
float loudnessGain	Loudness, in the range [-90.0, 24.0], in dB.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr, or audio streams do not support setting the loudness. 2. The loudnessGain parameter is not within the allowed range.

OH_AudioRenderer_GetLoudnessGain()

OH_AudioStream_Result OH_AudioRenderer_GetLoudnessGain(OH_AudioRenderer* renderer, float* loudnessGain)

Description

Obtains the loudness of audio playback.

Since: 20

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
float* loudnessGain	Pointer to a variable that receives the playback loudness, in decibels.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr. 2. The loudnessGain parameter is nullptr.

OH_AudioRenderer_OnWriteDataCallbackAdvanced()

typedef int32_t (*OH_AudioRenderer_OnWriteDataCallbackAdvanced)(OH_AudioRenderer* renderer, void* userData, void* audioData, int32_t audioDataSize)

Description

Defines a function pointer to the callback used to write audio data. Unlike OH_AudioRenderer_OnWriteDataCallback, this function allows the application to fill data of the length ranging [0, audioDataSize].
Here, audioDataSize refers to the length of the callback buffer. The caller notifies the system of the length of the data written through the return value.
If the return value is 0, the callback thread sleeps for a period of time.
Otherwise, the system may immediately initiate the next callback.

Since: 20

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to the instance for which the callback occurs.
void* userData	Pointer to the application data passed through the callbacks.
void* audioData	Pointer to the audio data to be filled by the application.
int32_t audioDataSize	Length of the audio data, in bytes.

Returns

Type

Description

int32_t

Actual length of valid audio data filled by the application. The return value must be in the range of [0, audioDataSize]. If the return value is less than 0, the system adjusts it to 0. If the return value is greater than audioDataSize, the system adjusts it to audioDataSize. Note that the return value must be an integer multiple of the size of a single sampling point. For example, for audio data in stereo s16 format, it must be an integer multiple of 4 (2 * 16 / 8). Failure to do so may result in playback noise.

OH_AudioRenderer_GetLatency()

OH_AudioStream_Result OH_AudioRenderer_GetLatency(OH_AudioRenderer* renderer, OH_AudioStream_LatencyType type, int32_t* latencyMs)

Description

Obtains the estimated latency of the current audio route, in milliseconds. For audio devices connected in wireless mode, the latency estimation may be inaccurate. The result is for reference only.
Since the latency is not counted in the real-time buffer, you are advised to obtain the latency only when audio playback starts. Frequent calls may block this API due to route switching.
After audio data is output to the hardware, you are advised to use OH_AudioRenderer_GetAudioTimestampInfo for audio-video synchronization.

Since: 23

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
OH_AudioStream_LatencyType type	Latency type to be obtained.
int32_t* latencyMs	Pointer to the variable used to receive the latency, in milliseconds.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: 1. The renderer parameter is nullptr. 2. The latencyMs parameter is nullptr. 3. The type parameter is invalid. AUDIOSTREAM_ERROR_SYSTEM: Internal system error, for example, abnormal audio service.

OH_AudioRenderer_SetIndependentAudioSessionStrategy()

OH_AudioStream_Result OH_AudioRenderer_SetIndependentAudioSessionStrategy(OH_AudioRenderer* renderer, const OH_AudioSession_Strategy* strategy, uint32_t behavior)

Description

Sets the independent audio session strategy and behavior parameters. If this API is called while an audio renderer is running, you must call the OH_AudioRenderer_Start API again for the settings to take effect.

Since: 24

Parameters

Name	Description
OH_AudioRenderer* renderer	Pointer to an audio renderer instance, which is created by calling OH_AudioStreamBuilder_GenerateRenderer.
const OH_AudioSession_Strategy* strategy	Pointer to the independent audio session policy.
uint32_t behavior	Audio session behavior flag. This can be a single flag or a bitwise OR combination of multiple flags. For details about the supported audio session behaviors, see OH_AudioSession_BehaviorFlags.

Returns

Type	Description
OH_AudioStream_Result	AUDIOSTREAM_SUCCESS: The function is executed successfully. AUDIOSTREAM_ERROR_INVALID_PARAM: The parameter value is a null pointer or out of range. AUDIOSTREAM_ERROR_ILLEGAL_STATE: The execution status is abnormal.

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 capi-native-audiostreambuilder-h

openharmony 鸿蒙 capi-ohaudiosuite

openharmony 鸿蒙 js-apis-inner-multimedia-systemSoundPlayer

openharmony 鸿蒙 arkts-apis-audio-i

openharmony 鸿蒙 capi-ohaudio

openharmony 鸿蒙 capi-ohmidi

openharmony 鸿蒙 arkts-apis-audio-AudioManager

openharmony 鸿蒙 capi-ohaudiosuite-oh-audiosuite-spacerenderpositionparams

openharmony 鸿蒙 capi-ohaudio-oh-audiostreaminfo

openharmony 鸿蒙 errorcode-ringtone