1# native_audiostream_base.h 2 3## Overview 4 5The file declares the basic data structure of OHAudio. 6 7**File to include**: <ohaudio/native_audiostream_base.h> 8 9**Library**: libohaudio.so 10 11**System capability**: SystemCapability.Multimedia.Audio.Core 12 13**Since**: 10 14 15**Related module**: [OHAudio](capi-ohaudio.md) 16 17## Summary 18 19### Structs 20 21| Name| typedef Keyword| Description| 22| -- | -- | -- | 23| [OH_AudioStreamInfo](capi-ohaudio-oh-audiostreaminfo.md) | OH_AudioStreamInfo | Describes the audio stream information, which is used to describe the basic audio format.| 24| [OH_AudioRenderer_Callbacks_Struct](capi-ohaudio-oh-audiorenderer-callbacks-struct.md) | OH_AudioRenderer_Callbacks | Describes a pointer to the callbacks related to an audio renderer.| 25| [OH_AudioCapturer_Callbacks_Struct](capi-ohaudio-oh-audiocapturer-callbacks-struct.md) | OH_AudioCapturer_Callbacks | Describes a pointer to the callbacks related to an audio capturer.| 26| [OH_AudioStreamBuilderStruct](capi-ohaudio-oh-audiostreambuilderstruct.md) | OH_AudioStreamBuilder | Defines a struct for an audio stream builder. An audio stream builder instance is often used to create an audio stream and set its attributes.| 27| [OH_AudioRendererStruct](capi-ohaudio-oh-audiorendererstruct.md) | OH_AudioRenderer | Describes an audio renderer, which is used to render audio data.| 28| [OH_AudioCapturerStruct](capi-ohaudio-oh-audiocapturerstruct.md) | OH_AudioCapturer | Describes an audio capturer, which is used to capture audio data.| 29 30### Enums 31 32| Name| typedef Keyword| Description| 33| -- | -- | -- | 34| [OH_AudioStream_Result](#oh_audiostream_result) | OH_AudioStream_Result | Enumerates the audio operation results.| 35| [OH_AudioStream_Type](#oh_audiostream_type) | OH_AudioStream_Type | Enumerates the audio stream types.| 36| [OH_AudioStream_SampleFormat](#oh_audiostream_sampleformat) | OH_AudioStream_SampleFormat | Enumerates the sampling formats of audio streams.| 37| [OH_AudioStream_EncodingType](#oh_audiostream_encodingtype) | OH_AudioStream_EncodingType | Enumerates the encoding types of audio streams.| 38| [OH_AudioStream_Usage](#oh_audiostream_usage) | OH_AudioStream_Usage | Enumerates the usage scenarios of an audio renderer, that is, usage scenarios of audio output streams.| 39| [OH_AudioStream_LatencyMode](#oh_audiostream_latencymode) | OH_AudioStream_LatencyMode | Enumerates the latency modes of audio streams.| 40| [OH_AudioStream_DirectPlaybackMode](#oh_audiostream_directplaybackmode) | OH_AudioStream_DirectPlaybackMode | Enumerates the direct playback modes of audio streams.| 41| [OH_AudioStream_VolumeMode](#oh_audiostream_volumemode) | OH_AudioStream_VolumeMode | Enumerates the volume modes of audio streams.| 42| [OH_AudioStream_State](#oh_audiostream_state) | OH_AudioStream_State | Enumerates the audio stream states.| 43| [OH_AudioStream_SourceType](#oh_audiostream_sourcetype) | OH_AudioStream_SourceType | Enumerates the usage scenarios of an audio capturer, that is, usage scenarios of audio input streams.| 44| [OH_AudioStream_Event](#oh_audiostream_event) | OH_AudioStream_Event | Enumerates the audio stream events.| 45| [OH_AudioInterrupt_ForceType](#oh_audiointerrupt_forcetype) | OH_AudioInterrupt_ForceType | Enumerates the types of force that causes audio interruption.<br>The force type is obtained when an audio interruption event is received.<br>This type specifies whether the audio interruption operation is forcibly performed by the system. The operation information (such as audio pause or stop) can be obtained through [OH_AudioInterrupt_Hint](#oh_audiointerrupt_hint).| 46| [OH_AudioInterrupt_Hint](#oh_audiointerrupt_hint) | OH_AudioInterrupt_Hint | Enumerates the hints provided along with audio interruption.<br>The hint is obtained when an audio interruption event is received.<br>The hint specifies the operation (such as audio pause or volume adjustment) to be performed on audio streams based on the focus policy.<br>You can determine whether the operation is forcibly performed by the system based on [OH_AudioInterrupt_ForceType](#oh_audiointerrupt_forcetype).| 47| [OH_AudioInterrupt_Mode](#oh_audiointerrupt_mode) | OH_AudioInterrupt_Mode | Enumerates the audio interruption modes.| 48| [OH_AudioStream_AudioEffectMode](#oh_audiostream_audioeffectmode) | OH_AudioStream_AudioEffectMode | Enumerates the audio effect modes.| 49| [OH_AudioStream_FastStatus](#oh_audiostream_faststatus) | OH_AudioStream_FastStatus | Enumerates the low-latency statuses.| 50| [OH_AudioStream_DeviceChangeReason](#oh_audiostream_devicechangereason) | OH_AudioStream_DeviceChangeReason | Enumerates the reasons for audio stream device changes.| 51| [OH_AudioStream_PrivacyType](#oh_audiostream_privacytype) | OH_AudioStream_PrivacyType | Enumerates the privacy types of an audio stream. The privacy type specifies whether the audio stream can be recorded by other applications.| 52| [OH_AudioData_Callback_Result](#oh_audiodata_callback_result) | OH_AudioData_Callback_Result | Enumerates the audio data callback results.| 53 54### Functions 55 56| Name| typedef Keyword| Description| 57| -- | -- | -- | 58| [typedef void (\*OH_AudioRenderer_OutputDeviceChangeCallback)(OH_AudioRenderer* renderer, void* userData,OH_AudioStream_DeviceChangeReason reason)](#oh_audiorenderer_outputdevicechangecallback) | OH_AudioRenderer_OutputDeviceChangeCallback | Defines a pointer to the callback invoked when the audio capturer device changes.| 59| [typedef void (\*OH_AudioRenderer_OnMarkReachedCallback)(OH_AudioRenderer* renderer, uint32_t samplePos, void* userData)](#oh_audiorenderer_onmarkreachedcallback) | OH_AudioRenderer_OnMarkReachedCallback | Defines a pointer to the callback invoked when the mark position is reached.| 60| [typedef int32_t (\*OH_AudioRenderer_WriteDataWithMetadataCallback)(OH_AudioRenderer* renderer,void* userData, void* audioData, int32_t audioDataSize, void* metadata, int32_t metadataSize)](#oh_audiorenderer_writedatawithmetadatacallback) | OH_AudioRenderer_WriteDataWithMetadataCallback | Defines a function pointer to the callback used to write audio data and metadata.| 61| [typedef OH_AudioData_Callback_Result (\*OH_AudioRenderer_OnWriteDataCallback)(OH_AudioRenderer* renderer, void* userData,void* audioData, int32_t audioDataSize)](#oh_audiorenderer_onwritedatacallback) | OH_AudioRenderer_OnWriteDataCallback | Defines a function pointer to the callback used to write audio data.<br>The callback is used only to write audio data. Do not call AudioRenderer APIs in it.<br>The return result indicates whether the data filled in the buffer is valid. If the data is invalid, the data entered by the user will not be played. Once the callback finishes its execution, the audio service queues the data pointed to by **audioData** for playback. Therefore, do not change the data outside the callback. It is crucial to fill **audioData** with the exact length (specified by **audioDataSize**) of data designated for playback; otherwise, noises may occur during playback.| 62| [typedef int32_t (\*OH_AudioRenderer_OnWriteDataCallbackAdvanced)(OH_AudioRenderer* renderer, void* userData,void* audioData, int32_t audioDataSize)](#oh_audiorenderer_onwritedatacallbackadvanced) | 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].<br>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.<br>If the return value is 0, the callback thread sleeps for a period of time.<br>Otherwise, the system may immediately initiates the next callback.| 63 64## Enum Description 65 66### OH_AudioStream_Result 67 68``` 69enum OH_AudioStream_Result 70``` 71 72**Description** 73 74Enumerates the audio operation results. 75 76**Since**: 10 77 78| Enum Item| Description| 79| -- | -- | 80| AUDIOSTREAM_SUCCESS = 0 | Operation successful.| 81| AUDIOSTREAM_ERROR_INVALID_PARAM = 1 | Invalid input parameter.| 82| AUDIOSTREAM_ERROR_ILLEGAL_STATE = 2 | Invalid state.| 83| AUDIOSTREAM_ERROR_SYSTEM = 3 | System error.| 84| AUDIOSTREAM_ERROR_UNSUPPORTED_FORMAT = 4 | Unsupported audio format, such as unsupported encoding type or sampling format.<br>**Since**: 19| 85 86### OH_AudioStream_Type 87 88``` 89enum OH_AudioStream_Type 90``` 91 92**Description** 93 94Enumerates the audio stream types. 95 96**Since**: 10 97 98| Enum Item| Description| 99| -- | -- | 100| AUDIOSTREAM_TYPE_RENDERER = 1 | The audio stream is an output stream.| 101| AUDIOSTREAM_TYPE_CAPTURER = 2 | The audio stream is an input stream.| 102 103### OH_AudioStream_SampleFormat 104 105``` 106enum OH_AudioStream_SampleFormat 107``` 108 109**Description** 110 111Enumerates the sampling formats of audio streams. 112 113**Since**: 10 114 115| Enum Item| Description| 116| -- | -- | 117| AUDIOSTREAM_SAMPLE_U8 = 0 | Unsigned 8-bit.| 118| AUDIOSTREAM_SAMPLE_S16LE = 1 | Short 16-bit little-endian.| 119| AUDIOSTREAM_SAMPLE_S24LE = 2 | Short 24-bit little-endian.| 120| AUDIOSTREAM_SAMPLE_S32LE = 3 | Short 32-bit little-endian.| 121| AUDIOSTREAM_SAMPLE_F32LE = 4 | Float 32-bit little-endian.<br>**Since**: 17| 122 123### OH_AudioStream_EncodingType 124 125``` 126enum OH_AudioStream_EncodingType 127``` 128 129**Description** 130 131Enumerates the encoding types of audio streams. 132 133**Since**: 10 134 135| Enum Item| Description| 136| -- | -- | 137| AUDIOSTREAM_ENCODING_TYPE_RAW = 0 | PCM encoding.| 138| AUDIOSTREAM_ENCODING_TYPE_AUDIOVIVID = 1 | AudioVivid encoding.<br>**Since**: 12| 139| AUDIOSTREAM_ENCODING_TYPE_E_AC3 = 2 | E_AC3 encoding.<br>**Since**: 19| 140 141### OH_AudioStream_Usage 142 143``` 144enum OH_AudioStream_Usage 145``` 146 147**Description** 148 149Enumerates the usage scenarios of an audio renderer, that is, usage scenarios of audio output streams. 150 151**Since**: 10 152 153| Enum Item| Description| 154| -- | -- | 155| AUDIOSTREAM_USAGE_UNKNOWN = 0 | Unknown content.| 156| AUDIOSTREAM_USAGE_MUSIC = 1 | Music.| 157| AUDIOSTREAM_USAGE_COMMUNICATION = 2 | VoIP voice call.| 158| AUDIOSTREAM_USAGE_VOICE_ASSISTANT = 3 | Voice assistant.| 159| AUDIOSTREAM_USAGE_ALARM = 4 | Alarming.| 160| AUDIOSTREAM_USAGE_VOICE_MESSAGE = 5 | Voice message.| 161| AUDIOSTREAM_USAGE_RINGTONE = 6 | Ringtone.| 162| AUDIOSTREAM_USAGE_NOTIFICATION = 7 | Notification.| 163| AUDIOSTREAM_USAGE_ACCESSIBILITY = 8 | Accessibility.| 164| AUDIOSTREAM_USAGE_MOVIE = 10 | Movie or video.| 165| AUDIOSTREAM_USAGE_GAME = 11 | Gaming.| 166| AUDIOSTREAM_USAGE_AUDIOBOOK = 12 | Audiobooks (including crosstalks and storytelling), news radio, and podcasts.| 167| AUDIOSTREAM_USAGE_NAVIGATION = 13 | Navigation.| 168| AUDIOSTREAM_USAGE_VIDEO_COMMUNICATION = 17 | VoIP video call.<br>**Since**: 12| 169 170### OH_AudioStream_LatencyMode 171 172``` 173enum OH_AudioStream_LatencyMode 174``` 175 176**Description** 177 178Enumerates the latency modes of audio streams. 179 180**Since**: 10 181 182| Enum Item| Description| 183| -- | -- | 184| AUDIOSTREAM_LATENCY_MODE_NORMAL = 0 | Normal latency mode.| 185| AUDIOSTREAM_LATENCY_MODE_FAST = 1 | Low latency mode.| 186 187### OH_AudioStream_DirectPlaybackMode 188 189``` 190enum OH_AudioStream_DirectPlaybackMode 191``` 192 193**Description** 194 195Enumerates the direct playback modes of audio streams. 196 197**Since**: 19 198 199| Enum Item| Description| 200| -- | -- | 201| AUDIOSTREAM_DIRECT_PLAYBACK_NOT_SUPPORTED = 0 | Direct playback is not supported.| 202| AUDIOSTREAM_DIRECT_PLAYBACK_BITSTREAM_SUPPORTED = 1 | Direct playback of bit streams (without decoding) is supported.| 203| AUDIOSTREAM_DIRECT_PLAYBACK_PCM_SUPPORTED = 2 | Direct playback of PCM-encoded audio is supported.| 204 205### OH_AudioStream_VolumeMode 206 207``` 208enum OH_AudioStream_VolumeMode 209``` 210 211**Description** 212 213Enumerates the volume modes of audio streams. 214 215**Since**: 18 216 217| Enum Item| Description| 218| -- | -- | 219| AUDIOSTREAM_VOLUMEMODE_SYSTEM_GLOBAL = 0 | System-level volume (default mode).| 220| AUDIOSTREAM_VOLUMEMODE_APP_INDIVIDUAL = 1 | Application-level volume.<br>In this mode, you can set and query the application volume through the provided functions.| 221 222### OH_AudioStream_State 223 224``` 225enum OH_AudioStream_State 226``` 227 228**Description** 229 230Enumerates the audio stream states. 231 232**Since**: 10 233 234| Enum Item| Description| 235| -- | -- | 236| AUDIOSTREAM_STATE_INVALID = -1 | Invalid state.| 237| AUDIOSTREAM_STATE_NEW = 0 | Newly created.| 238| AUDIOSTREAM_STATE_PREPARED = 1 | Prepared.| 239| AUDIOSTREAM_STATE_RUNNING = 2 | Running.| 240| AUDIOSTREAM_STATE_STOPPED = 3 | Stopped.| 241| AUDIOSTREAM_STATE_RELEASED = 4 | Released.| 242| AUDIOSTREAM_STATE_PAUSED = 5 | Paused.| 243 244### OH_AudioStream_SourceType 245 246``` 247enum OH_AudioStream_SourceType 248``` 249 250**Description** 251 252Enumerates the usage scenarios of an audio capturer, that is, usage scenarios of audio input streams. 253 254**Since**: 10 255 256| Enum Item| Description| 257| -- | -- | 258| AUDIOSTREAM_SOURCE_TYPE_INVALID = -1 | Invalid state.| 259| AUDIOSTREAM_SOURCE_TYPE_MIC = 0 | Audio recording.| 260| AUDIOSTREAM_SOURCE_TYPE_VOICE_RECOGNITION = 1 | Voice recognition.| 261| AUDIOSTREAM_SOURCE_TYPE_PLAYBACK_CAPTURE = 2 | Audio playback.| 262| AUDIOSTREAM_SOURCE_TYPE_VOICE_COMMUNICATION = 7 | Voice communication.| 263| AUDIOSTREAM_SOURCE_TYPE_VOICE_MESSAGE = 10 | Voice message.<br>**Since**: 12| 264| AUDIOSTREAM_SOURCE_TYPE_CAMCORDER = 13 | Video recording.<br>**Since**: 13| 265| AUDIOSTREAM_SOURCE_TYPE_UNPROCESSED = 14 | Raw microphone recording, where the system does not perform any algorithm processing.<br>**Since**: 14| 266| AUDIOSTREAM_SOURCE_TYPE_LIVE = 17 | Live.<br>**Since**: 20| 267 268### OH_AudioStream_Event 269 270``` 271enum OH_AudioStream_Event 272``` 273 274**Description** 275 276Enumerates the audio stream events. 277 278**Since**: 10 279 280**Deprecated from**: 20 281 282| Enum Item| Description| 283| -- | -- | 284| AUDIOSTREAM_EVENT_ROUTING_CHANGED = 0 | The audio route has been changed.<br>**Since**: 10<br>**Deprecated from**: 20<br>**Substitute**: [OH_AudioRenderer_OutputDeviceChangeCallback](#oh_audiorenderer_outputdevicechangecallback)| 285 286### OH_AudioInterrupt_ForceType 287 288``` 289enum OH_AudioInterrupt_ForceType 290``` 291 292**Description** 293 294Enumerates the types of force that causes audio interruption. 295 296The force type is obtained when an audio interruption event is received. 297 298This type specifies whether the audio interruption operation is forcibly performed by the system. The operation information (such as audio pause or stop) can be obtained through [OH_AudioInterrupt_Hint](#oh_audiointerrupt_hint). 299 300**Since**: 10 301 302| Enum Item| Description| 303| -- | -- | 304| AUDIOSTREAM_INTERRUPT_FORCE = 0 | The operation is forcibly performed by the system.| 305| AUDIOSTREAM_INTERRUPT_SHAR = 1 | The operation will not be performed by the system. [OH_AudioInterrupt_Hint](#oh_audiointerrupt_hint) is used to provide recommended operations for the application, and the application can determine the next processing mode.| 306 307### OH_AudioInterrupt_Hint 308 309``` 310enum OH_AudioInterrupt_Hint 311``` 312 313**Description** 314 315Enumerates the hints provided along with audio interruption. 316 317The hint is obtained when an audio interruption event is received. 318 319The hint specifies the operation (such as audio pause or volume adjustment) to be performed on audio streams based on the focus policy. 320 321You can determine whether the operation is forcibly performed by the system based on [OH_AudioInterrupt_ForceType](#oh_audiointerrupt_forcetype). 322 323**Since**: 10 324 325| Enum Item| Description| 326| -- | -- | 327| AUDIOSTREAM_INTERRUPT_HINT_NONE = 0 | None.| 328| AUDIOSTREAM_INTERRUPT_HINT_RESUME = 1 | A hint is displayed, indicating that the audio stream is restored. The application can proactively trigger operations related to rendering or recording.<br>This operation cannot be forcibly performed by the system, and the corresponding [OH_AudioInterrupt_ForceType](#oh_audiointerrupt_forcetype) must be **AUDIOSTREAM_INTERRUPT_SHARE**.| 329| AUDIOSTREAM_INTERRUPT_HINT_PAUSE = 2 | A hint is displayed, indicating that the audio stream is paused and the audio focus is lost temporarily.<br>The **AUDIOSTREAM_INTERRUPT_HINT_RESUME** event will be triggered when the focus is gained.| 330| AUDIOSTREAM_INTERRUPT_HINT_STOP = 3 | A hint is displayed, indicating that the audio stream stops and the audio focus is lost.| 331| AUDIOSTREAM_INTERRUPT_HINT_DUCK = 4 | A hint is displayed, indicating that audio ducking starts and the audio is played at a lower volume.| 332| AUDIOSTREAM_INTERRUPT_HINT_UNDUCK = 5 | A hint is displayed, indicating that audio ducking ends and the audio is played at the normal volume.| 333 334### OH_AudioInterrupt_Mode 335 336``` 337enum OH_AudioInterrupt_Mode 338``` 339 340**Description** 341 342Enumerates the audio interruption modes. 343 344**Since**: 12 345 346| Enum Item| Description| 347| -- | -- | 348| AUDIOSTREAM_INTERRUPT_MODE_SHARE = 0 | Shared mode.| 349| AUDIOSTREAM_INTERRUPT_MODE_INDEPENDENT = 1 | Independent mode.| 350 351### OH_AudioStream_AudioEffectMode 352 353``` 354enum OH_AudioStream_AudioEffectMode 355``` 356 357**Description** 358 359Enumerates the audio effect modes. 360 361**Since**: 12 362 363| Enum Item| Description| 364| -- | -- | 365| EFFECT_NONE = 0 | No audio effect used.| 366| EFFECT_DEFAULT = 1 | Default audio effect mode.| 367 368### OH_AudioStream_FastStatus 369 370``` 371enum OH_AudioStream_FastStatus 372``` 373 374**Description** 375 376Enumerates the low-latency statuses. 377 378**Since**: 20 379 380| Enum Item| Description| 381| -- | -- | 382| AUDIOSTREAM_FASTSTATUS_NORMAL = 0 | Normal audio stream status.| 383| AUDIOSTREAM_FASTSTATUS_FAST = 1 | Low-latency audio stream status.| 384 385### OH_AudioStream_DeviceChangeReason 386 387``` 388enum OH_AudioStream_DeviceChangeReason 389``` 390 391**Description** 392 393Enumerates the reasons for audio stream device changes. 394 395**Since**: 11 396 397| Enum Item| Description| 398| -- | -- | 399| REASON_UNKNOWN = 0 | Unknown reason.| 400| REASON_NEW_DEVICE_AVAILABLE = 1 | A new device is available.| 401| REASON_OLD_DEVICE_UNAVAILABLE = 2 | The old device is unavailable. When this reason is reported, the application should consider pausing audio playback.| 402| REASON_OVERRODE = 3 | The user or system forcibly changes the device.| 403 404### OH_AudioStream_PrivacyType 405 406``` 407enum OH_AudioStream_PrivacyType 408``` 409 410**Description** 411 412Enumerates the privacy types of an audio stream. The privacy type specifies whether the audio stream can be recorded by other applications. 413 414**Since**: 12 415 416| Enum Item| Description| 417| -- | -- | 418| AUDIO_STREAM_PRIVACY_TYPE_PUBLIC = 0 | The audio stream can be recorded by other applications.| 419| AUDIO_STREAM_PRIVACY_TYPE_PRIVATE = 1 | The audio stream cannot be recorded by other applications.| 420 421### OH_AudioData_Callback_Result 422 423``` 424enum OH_AudioData_Callback_Result 425``` 426 427**Description** 428 429Enumerates the audio data callback results. 430 431**Since**: 12 432 433| Enum Item| Description| 434| -- | -- | 435| AUDIO_DATA_CALLBACK_RESULT_INVALID = -1 | The audio data callback result is invalid, and the audio data will not be played.| 436| AUDIO_DATA_CALLBACK_RESULT_VALID = 0 | The audio data callback result is valid, and the audio data will be played.| 437 438 439## Function Description 440 441### OH_AudioRenderer_OutputDeviceChangeCallback() 442 443``` 444typedef void (*OH_AudioRenderer_OutputDeviceChangeCallback)(OH_AudioRenderer* renderer, void* userData,OH_AudioStream_DeviceChangeReason reason) 445``` 446 447**Description** 448 449Defines a pointer to the callback invoked when the audio capturer device changes. 450 451**Since**: 11 452 453 454**Parameters** 455 456| Name| Description| 457| -- | -- | 458| [OH_AudioRenderer](capi-ohaudio-oh-audiorendererstruct.md)* renderer | Pointer to an audio renderer instance, which is created by calling [OH_AudioStreamBuilder_GenerateRenderer](capi-native-audiostreambuilder-h.md#oh_audiostreambuilder_generaterenderer).| 459| void* userData | Pointer to the application data passed through the callback.| 460| [OH_AudioStream_DeviceChangeReason](#oh_audiostream_devicechangereason) reason | Reason for the audio stream device change.| 461 462### OH_AudioRenderer_OnMarkReachedCallback() 463 464``` 465typedef void (*OH_AudioRenderer_OnMarkReachedCallback)(OH_AudioRenderer* renderer, uint32_t samplePos, void* userData) 466``` 467 468**Description** 469 470Defines a pointer to the callback invoked when the mark position is reached. 471 472**Since**: 12 473 474 475**Parameters** 476 477| Name| Description| 478| -- | -- | 479| [OH_AudioRenderer](capi-ohaudio-oh-audiorendererstruct.md)* renderer | Pointer to an audio renderer instance, which is created by calling [OH_AudioStreamBuilder_GenerateRenderer](capi-native-audiostreambuilder-h.md#oh_audiostreambuilder_generaterenderer).| 480| uint32_t samplePos | Mark position.| 481| void* userData | Pointer to the application data passed through the callback.| 482 483### OH_AudioRenderer_WriteDataWithMetadataCallback() 484 485``` 486typedef int32_t (*OH_AudioRenderer_WriteDataWithMetadataCallback)(OH_AudioRenderer* renderer,void* userData, void* audioData, int32_t audioDataSize, void* metadata, int32_t metadataSize) 487``` 488 489**Description** 490 491Defines a function pointer to the callback used to write audio data and metadata. 492 493**Since**: 12 494 495 496**Parameters** 497 498| Name| Description| 499| -- | -- | 500| [OH_AudioRenderer](capi-ohaudio-oh-audiorendererstruct.md)* renderer | Pointer to an audio renderer instance, which is created by calling [OH_AudioStreamBuilder_GenerateRenderer](capi-native-audiostreambuilder-h.md#oh_audiostreambuilder_generaterenderer).| 501| void* userData | Pointer to the application data passed through the callback.| 502| void* audioData | Pointer to the audio data written by the user.| 503| int32_t audioDataSize | Length of the audio data, in bytes.| 504| void* metadata | Pointer to the metadata written by the user.| 505| int32_t metadataSize | Length of the metadata, in bytes.| 506 507**Returns** 508 509| Type| Description| 510| -- | -- | 511| int32_t | Error code of the callback.| 512 513### OH_AudioRenderer_OnWriteDataCallback() 514 515``` 516typedef OH_AudioData_Callback_Result (*OH_AudioRenderer_OnWriteDataCallback)(OH_AudioRenderer* renderer, void* userData,void* audioData, int32_t audioDataSize) 517``` 518 519**Description** 520 521Defines a function pointer to the callback used to write audio data. 522 523The callback is used only to write audio data. Do not call AudioRenderer APIs in it. 524 525The return result indicates whether the data filled in the buffer is valid. If the data is invalid, the data entered by the user will not be played. Once the callback finishes its execution, the audio service queues the data pointed to by **audioData** for playback. Therefore, do not change the data outside the callback. It is crucial to fill **audioData** with the exact length (specified by **audioDataSize**) of data designated for playback; otherwise, noises may occur during playback. 526 527The **audioDataSize** parameter can be set by calling [OH_AudioStreamBuilder_SetFrameSizeInCallback](capi-native-audiostreambuilder-h.md#oh_audiostreambuilder_setframesizeincallback). 528 529**Since**: 12 530 531 532**Parameters** 533 534| Name| Description| 535| -- | -- | 536| [OH_AudioRenderer](capi-ohaudio-oh-audiorendererstruct.md)* renderer | Pointer to an audio renderer instance, which is created by calling [OH_AudioStreamBuilder_GenerateRenderer](capi-native-audiostreambuilder-h.md#oh_audiostreambuilder_generaterenderer).| 537| void* userData | Pointer to the application data passed through the callback.| 538| void* audioData | Pointer to the audio data written by the user.| 539| int32_t audioDataSize | Length of the audio data, in bytes.| 540 541**Returns** 542 543| Type| Description| 544| -- | -- | 545| [OH_AudioData_Callback_Result](#oh_audiodata_callback_result) | **AUDIO_DATA_CALLBACK_RESULT_INVALID**: The audio data callback result is invalid, and the audio data will not be played.<br>**AUDIO_DATA_CALLBACK_RESULT_VALID**: The audio data callback result is valid, and the audio data will be played. | 546 547### OH_AudioRenderer_OnWriteDataCallbackAdvanced() 548 549``` 550typedef int32_t (*OH_AudioRenderer_OnWriteDataCallbackAdvanced)(OH_AudioRenderer* renderer, void* userData,void* audioData, int32_t audioDataSize) 551``` 552 553**Description** 554 555Defines 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]. 556 557Here, **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. 558 559If the return value is 0, the callback thread sleeps for a period of time. 560 561Otherwise, the system may immediately initiates the next callback. 562 563**Since**: 20 564 565 566**Parameters** 567 568| Name| Description| 569| -- | -- | 570| [OH_AudioRenderer](capi-ohaudio-oh-audiorendererstruct.md)* renderer | Pointer to the instance for which the callback occurs.| 571| void* userData | Pointer to the application data passed through the callback.| 572| void* audioData | Pointer to the audio data to be filled by the application.| 573| int32_t audioDataSize | Length of the audio data, in bytes.| 574 575**Returns** 576 577| Type| Description| 578| -- | -- | 579| int32_t | Actual length of valid audio data filled by the application. The return value must be in the range of [0, audioDataSize].<br>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**.<br>Note that the return value must be an integer multiple of the size of a single sampling point.<br>For example, for audio data in stereo s16 format, it must be an integer multiple of 4 (216/8).<br>Failure to do so may result in playback noise.| 580