1# native_audiostream_base.h 2<!--Kit: Audio Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @songshenke--> 5<!--Designer: @caixuejiang; @hao-liangfei; @zhanganxiang--> 6<!--Tester: @Filger--> 7<!--Adviser: @zengyawen--> 8 9## 概述 10 11声明OHAudio基础的数据结构。 12 13**引用文件：** <ohaudio/native_audiostream_base.h> 14 15**库：** libohaudio.so 16 17**系统能力：** SystemCapability.Multimedia.Audio.Core 18 19**起始版本：** 10 20 21**相关模块：** [OHAudio](capi-ohaudio.md) 22 23## 汇总 24 25### 结构体 26 27| 名称 | typedef关键字 | 描述 | 28| -- | -- | -- | 29| [OH_AudioStreamInfo](capi-ohaudio-oh-audiostreaminfo.md) | OH_AudioStreamInfo | 定义音频流信息，用于描述基本音频格式。 | 30| [OH_AudioRenderer_Callbacks_Struct](capi-ohaudio-oh-audiorenderer-callbacks-struct.md) | OH_AudioRenderer_Callbacks | 声明输出音频流的回调函数指针。 | 31| [OH_AudioCapturer_Callbacks_Struct](capi-ohaudio-oh-audiocapturer-callbacks-struct.md) | OH_AudioCapturer_Callbacks | 声明输入音频流的回调函数指针。<br> 为了避免不可预期的行为，在设置音频回调函数时，请确保该结构体的每一个成员变量都被自定义的回调方法或空指针初始化。 | 32| [OH_AudioStreamBuilderStruct](capi-ohaudio-oh-audiostreambuilderstruct.md) | OH_AudioStreamBuilder | 声明音频流的构造器。构造器实例通常被用来设置音频流属性和创建音频流。 | 33| [OH_AudioRendererStruct](capi-ohaudio-oh-audiorendererstruct.md) | OH_AudioRenderer | 声明输出音频流。输出音频流的实例被用来播放音频数据。 | 34| [OH_AudioCapturerStruct](capi-ohaudio-oh-audiocapturerstruct.md) | OH_AudioCapturer | 声明输入音频流。输入音频流的实例被用来获取音频数据。 | 35 36### 枚举 37 38| 名称 | typedef关键字 | 描述 | 39| -- | -- | -- | 40| [OH_AudioStream_Result](#oh_audiostream_result) | OH_AudioStream_Result | 音频错误码。 | 41| [OH_AudioStream_Type](#oh_audiostream_type) | OH_AudioStream_Type | 音频流类型。 | 42| [OH_AudioStream_SampleFormat](#oh_audiostream_sampleformat) | OH_AudioStream_SampleFormat | 定义音频流采样格式。 | 43| [OH_AudioStream_EncodingType](#oh_audiostream_encodingtype) | OH_AudioStream_EncodingType | 定义音频流编码类型。 | 44| [OH_AudioStream_Usage](#oh_audiostream_usage) | OH_AudioStream_Usage | 定义音频流使用场景。<br> 通常用来描述音频输出流的使用场景。 | 45| [OH_AudioStream_LatencyMode](#oh_audiostream_latencymode) | OH_AudioStream_LatencyMode | 定义音频时延模式。 | 46| [OH_AudioStream_DirectPlaybackMode](#oh_audiostream_directplaybackmode) | OH_AudioStream_DirectPlaybackMode | 定义音频流direct通路播放模式。 | 47| [OH_AudioStream_VolumeMode](#oh_audiostream_volumemode) | OH_AudioStream_VolumeMode | 定义音频流音量模式。 | 48| [OH_AudioStream_State](#oh_audiostream_state) | OH_AudioStream_State | 定义音频流的状态。 | 49| [OH_AudioStream_SourceType](#oh_audiostream_sourcetype) | OH_AudioStream_SourceType | 定义音频流使用场景。<br> 通常用来描述音频输入流的使用场景。 | 50| [OH_AudioStream_Event](#oh_audiostream_event) | OH_AudioStream_Event | 定义音频事件。 | 51| [OH_AudioInterrupt_ForceType](#oh_audiointerrupt_forcetype) | OH_AudioInterrupt_ForceType | 定义音频中断类型。<br> 当用户监听到音频中断时，将获取此信息。<br> 此类型表示本次音频打断的操作是否已由系统强制执行，具体操作信息（如音频暂停、停止等）可通过[OH_AudioInterrupt_Hint](#oh_audiointerrupt_hint)获取。 | 52| [OH_AudioInterrupt_Hint](#oh_audiointerrupt_hint) | OH_AudioInterrupt_Hint | 定义音频中断提示类型。<br> 当用户监听到音频中断时，将获取此信息。<br> 此类型表示根据焦点策略，当前需要对音频流的具体操作（如暂停、调整音量等）。<br> 可以结合[OH_AudioInterrupt_ForceType](#oh_audiointerrupt_forcetype)信息，判断该操作是否已由系统强制执行。 | 53| [OH_AudioInterrupt_Mode](#oh_audiointerrupt_mode) | OH_AudioInterrupt_Mode | 定义音频中断模式。 | 54| [OH_AudioStream_AudioEffectMode](#oh_audiostream_audioeffectmode) | OH_AudioStream_AudioEffectMode | 定义音效模式。 | 55| [OH_AudioStream_FastStatus](#oh_audiostream_faststatus) | OH_AudioStream_FastStatus | 定义低时延状态。 | 56| [OH_AudioStream_DeviceChangeReason](#oh_audiostream_devicechangereason) | OH_AudioStream_DeviceChangeReason | 流设备变更原因。 | 57| [OH_AudioStream_PrivacyType](#oh_audiostream_privacytype) | OH_AudioStream_PrivacyType | 用于标识对应播放音频流是否支持被其他应用录制。 | 58| [OH_AudioData_Callback_Result](#oh_audiodata_callback_result) | OH_AudioData_Callback_Result | 定义音频数据回调结果。 | 59 60### 函数 61 62| 名称 | typedef关键字 | 描述 | 63| -- | -- | -- | 64| [typedef void (\*OH_AudioRenderer_OutputDeviceChangeCallback)(OH_AudioRenderer* renderer, void* userData, OH_AudioStream_DeviceChangeReason reason)](#oh_audiorenderer_outputdevicechangecallback) | OH_AudioRenderer_OutputDeviceChangeCallback | 输出音频流设备变更的回调函数。 | 65| [typedef void (\*OH_AudioRenderer_OnMarkReachedCallback)(OH_AudioRenderer* renderer, uint32_t samplePos, void* userData)](#oh_audiorenderer_onmarkreachedcallback) | OH_AudioRenderer_OnMarkReachedCallback | 到达标记位置时回调。 | 66| [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 | 该函数指针将指向用于同时写入音频数据和元数据的回调函数。 | 67| [typedef OH_AudioData_Callback_Result (\*OH_AudioRenderer_OnWriteDataCallback)(OH_AudioRenderer* renderer, void* userData, void* audioData, int32_t audioDataSize)](#oh_audiorenderer_onwritedatacallback) | OH_AudioRenderer_OnWriteDataCallback | 该函数指针将指向用于写入音频数据的回调函数。<br> 回调函数仅用来写入音频数据，请勿在回调函数中调用AudioRenderer相关接口。<br> 该函数的返回结果表示填充到缓冲区的数据是否有效。如果结果无效，用户填写的数据将不被播放。回调函数结束后，音频服务会把audioData指针数据放入队列里等待播放，因此请勿在回调外再次更改audioData指向的数据, 且务必保证往audioData填满audioDataSize长度的待播放数据, 否则会导致音频服务播放杂音。 | 68| [typedef int32_t (\*OH_AudioRenderer_OnWriteDataCallbackAdvanced)(OH_AudioRenderer* renderer, void* userData, void* audioData, int32_t audioDataSize)](#oh_audiorenderer_onwritedatacallbackadvanced) | OH_AudioRenderer_OnWriteDataCallbackAdvanced | 该函数指针将指向用于写入音频数据的回调函数。不同于OH_AudioRenderer_OnWriteDataCallback，此函数允许应用填充[0, audioDataSize]长度的数据。<br> 其中audioDataSize为回调buffer的长度。调用方通过返回值告知系统写入的数据长度。<br> 如果返回0，回调线程将会sleep一段时间。<br> 否则，系统可能会立刻进行下一次回调。 | 69 70## 枚举类型说明 71 72### OH_AudioStream_Result 73 74``` 75enum OH_AudioStream_Result 76``` 77 78**描述** 79 80音频错误码。 81 82**起始版本：** 10 83 84| 枚举项 | 描述 | 85| -- | -- | 86| AUDIOSTREAM_SUCCESS = 0 | 操作成功 | 87| AUDIOSTREAM_ERROR_INVALID_PARAM = 1 | 入参错误。 | 88| AUDIOSTREAM_ERROR_ILLEGAL_STATE = 2 | 非法状态。 | 89| AUDIOSTREAM_ERROR_SYSTEM = 3 | 系统通用错误。 | 90| AUDIOSTREAM_ERROR_UNSUPPORTED_FORMAT = 4 | 不支持的音频格式，如不支持的编码类型、采样格式等。<br>**起始版本：** 19 | 91 92### OH_AudioStream_Type 93 94``` 95enum OH_AudioStream_Type 96``` 97 98**描述** 99 100音频流类型。 101 102**起始版本：** 10 103 104| 枚举项 | 描述 | 105| -- | -- | 106| AUDIOSTREAM_TYPE_RENDERER = 1 | 该类型代表音频流是输出流。 | 107| AUDIOSTREAM_TYPE_CAPTURER = 2 | 该类型代表音频流是输入流。 | 108 109### OH_AudioStream_SampleFormat 110 111``` 112enum OH_AudioStream_SampleFormat 113``` 114 115**描述** 116 117定义音频流采样格式。 118 119**起始版本：** 10 120 121| 枚举项 | 描述 | 122| -- | -- | 123| AUDIOSTREAM_SAMPLE_U8 = 0 | Unsigned 8位。 | 124| AUDIOSTREAM_SAMPLE_S16LE = 1 | Short 16位小端。 | 125| AUDIOSTREAM_SAMPLE_S24LE = 2 | Short 24位小端。 | 126| AUDIOSTREAM_SAMPLE_S32LE = 3 | Short 32位小端。 | 127| AUDIOSTREAM_SAMPLE_F32LE = 4 | Float 32位小端。<br>**起始版本：** 17 | 128 129### OH_AudioStream_EncodingType 130 131``` 132enum OH_AudioStream_EncodingType 133``` 134 135**描述** 136 137定义音频流编码类型。 138 139**起始版本：** 10 140 141| 枚举项 | 描述 | 142| -- | -- | 143| AUDIOSTREAM_ENCODING_TYPE_RAW = 0 | PCM编码。 | 144| AUDIOSTREAM_ENCODING_TYPE_AUDIOVIVID = 1 | Audio Vivid编码。<br>**起始版本：** 12 | 145| AUDIOSTREAM_ENCODING_TYPE_E_AC3 = 2 | E_AC3编码。<br>**起始版本：** 19 | 146 147### OH_AudioStream_Usage 148 149``` 150enum OH_AudioStream_Usage 151``` 152 153**描述** 154 155定义音频流使用场景。<br> 通常用来描述音频输出流的使用场景。 156 157**起始版本：** 10 158 159| 枚举项 | 描述 | 160| -- | -- | 161| AUDIOSTREAM_USAGE_UNKNOWN = 0 | 未知类型。 | 162| AUDIOSTREAM_USAGE_MUSIC = 1 | 音乐。 | 163| AUDIOSTREAM_USAGE_VOICE_COMMUNICATION = 2 | VoIP语音通话。 | 164| AUDIOSTREAM_USAGE_VOICE_ASSISTANT = 3 | 语音播报。 | 165| AUDIOSTREAM_USAGE_ALARM = 4 | 闹钟。 | 166| AUDIOSTREAM_USAGE_VOICE_MESSAGE = 5 | 语音消息。 | 167| AUDIOSTREAM_USAGE_RINGTONE = 6 | 铃声。 | 168| AUDIOSTREAM_USAGE_NOTIFICATION = 7 | 通知。 | 169| AUDIOSTREAM_USAGE_ACCESSIBILITY = 8 | 无障碍。 | 170| AUDIOSTREAM_USAGE_MOVIE = 10 | 电影或视频。 | 171| AUDIOSTREAM_USAGE_GAME = 11 | 游戏。 | 172| AUDIOSTREAM_USAGE_AUDIOBOOK = 12 | 有声读物（包括听书、相声、评书）、听新闻、播客等。 | 173| AUDIOSTREAM_USAGE_NAVIGATION = 13 | 导航。 | 174| AUDIOSTREAM_USAGE_VIDEO_COMMUNICATION = 17 | VoIP视频通话。<br>**起始版本：** 12 | 175 176### OH_AudioStream_LatencyMode 177 178``` 179enum OH_AudioStream_LatencyMode 180``` 181 182**描述** 183 184定义音频时延模式。 185 186**起始版本：** 10 187 188| 枚举项 | 描述 | 189| -- | -- | 190| AUDIOSTREAM_LATENCY_MODE_NORMAL = 0 | 该模式代表一个普通时延的音频流。 | 191| AUDIOSTREAM_LATENCY_MODE_FAST = 1 | 该模式代表一个低时延的音频流。 | 192 193### OH_AudioStream_DirectPlaybackMode 194 195``` 196enum OH_AudioStream_DirectPlaybackMode 197``` 198 199**描述** 200 201定义音频流direct通路播放模式。 202 203**起始版本：** 19 204 205| 枚举项 | 描述 | 206| -- | -- | 207| AUDIOSTREAM_DIRECT_PLAYBACK_NOT_SUPPORTED = 0 | 该模式代表不支持direct通路播放。 | 208| AUDIOSTREAM_DIRECT_PLAYBACK_BITSTREAM_SUPPORTED = 1 | 该模式代表支持不解码的direct通路播放。 | 209| AUDIOSTREAM_DIRECT_PLAYBACK_PCM_SUPPORTED = 2 | 该模式代表支持pcm编码的direct通路播放。 | 210 211### OH_AudioStream_VolumeMode 212 213``` 214enum OH_AudioStream_VolumeMode 215``` 216 217**描述** 218 219定义音频流音量模式。 220 221**起始版本：** 19 222 223| 枚举项 | 描述 | 224| -- | -- | 225| AUDIOSTREAM_VOLUMEMODE_SYSTEM_GLOBAL = 0 | 系统级音量（默认模式）。 | 226| AUDIOSTREAM_VOLUMEMODE_APP_INDIVIDUAL = 1 | 应用级音量。<br> 设置为该模式后可以通过提供的接口设置、查询应用音量。 | 227 228### OH_AudioStream_State 229 230``` 231enum OH_AudioStream_State 232``` 233 234**描述** 235 236定义音频流的状态。 237 238**起始版本：** 10 239 240| 枚举项 | 描述 | 241| -- | -- | 242| AUDIOSTREAM_STATE_INVALID = -1 | 不合法的状态。 | 243| AUDIOSTREAM_STATE_NEW = 0 | 新创建时的状态。 | 244| AUDIOSTREAM_STATE_PREPARED = 1 | 准备状态。 | 245| AUDIOSTREAM_STATE_RUNNING = 2 | 工作状态。 | 246| AUDIOSTREAM_STATE_STOPPED = 3 | 停止状态。 | 247| AUDIOSTREAM_STATE_RELEASED = 4 | 释放状态。 | 248| AUDIOSTREAM_STATE_PAUSED = 5 | 暂停状态。 | 249 250### OH_AudioStream_SourceType 251 252``` 253enum OH_AudioStream_SourceType 254``` 255 256**描述** 257 258定义音频流使用场景。<br> 通常用来描述音频输入流的使用场景。 259 260**起始版本：** 10 261 262| 枚举项 | 描述 | 263| -- | -- | 264| AUDIOSTREAM_SOURCE_TYPE_INVALID = -1 | 不合法状态。 | 265| AUDIOSTREAM_SOURCE_TYPE_MIC = 0 | 录音。 | 266| AUDIOSTREAM_SOURCE_TYPE_VOICE_RECOGNITION = 1 | 语音识别。 | 267| AUDIOSTREAM_SOURCE_TYPE_PLAYBACK_CAPTURE = 2 | 播放录音。 | 268| AUDIOSTREAM_SOURCE_TYPE_VOICE_COMMUNICATION = 7 | 通话。 | 269| AUDIOSTREAM_SOURCE_TYPE_VOICE_MESSAGE = 10 | 语音消息。<br>**起始版本：** 12 | 270| AUDIOSTREAM_SOURCE_TYPE_CAMCORDER = 13 | 录像。<br>**起始版本：** 13 | 271| AUDIOSTREAM_SOURCE_TYPE_UNPROCESSED = 14 | 麦克风纯净录音（系统不做任何算法处理）。<br>**起始版本：** 14 | 272| AUDIOSTREAM_SOURCE_TYPE_LIVE = 17 | 直播。<br>**起始版本：** 20 | 273 274### OH_AudioStream_Event 275 276``` 277enum OH_AudioStream_Event 278``` 279 280**描述** 281 282定义音频事件。 283 284**起始版本：** 10 285 286**废弃版本：** 20 287 288| 枚举项 | 描述 | 289| -- | -- | 290| AUDIOSTREAM_EVENT_ROUTING_CHANGED = 0 | 音频的路由已更改。<br>**起始版本：** 10<br>**废弃版本：** 20<br>**替代接口：** [OH_AudioRenderer_OutputDeviceChangeCallback](#oh_audiorenderer_outputdevicechangecallback) | 291 292### OH_AudioInterrupt_ForceType 293 294``` 295enum OH_AudioInterrupt_ForceType 296``` 297 298**描述** 299 300定义音频中断类型。<br> 当用户监听到音频中断时，将获取此信息。<br> 此类型表示本次音频打断的操作是否已由系统强制执行，具体操作信息（如音频暂停、停止等）可通过[OH_AudioInterrupt_Hint](#oh_audiointerrupt_hint)获取。 301 302**起始版本：** 10 303 304| 枚举项 | 描述 | 305| -- | -- | 306| AUDIOSTREAM_INTERRUPT_FORCE = 0 | 强制打断类型，即具体操作已由系统强制执行。 | 307| AUDIOSTREAM_INTERRUPT_SHARE = 1 | 共享打断类型，即系统不执行具体操作，通过[OH_AudioInterrupt_Hint](#oh_audiointerrupt_hint)提示并建议应用操作，应用可自行决策下一步处理方式。 | 308 309### OH_AudioInterrupt_Hint 310 311``` 312enum OH_AudioInterrupt_Hint 313``` 314 315**描述** 316 317定义音频中断提示类型。<br> 当用户监听到音频中断时，将获取此信息。<br> 此类型表示根据焦点策略，当前需要对音频流的具体操作（如暂停、调整音量等）。<br> 可以结合[OH_AudioInterrupt_ForceType](#oh_audiointerrupt_forcetype)信息，判断该操作是否已由系统强制执行。 318 319**起始版本：** 10 320 321| 枚举项 | 描述 | 322| -- | -- | 323| AUDIOSTREAM_INTERRUPT_HINT_NONE = 0 | 不提示。 | 324| AUDIOSTREAM_INTERRUPT_HINT_RESUME = 1 | 提示音频恢复，应用可主动触发开始渲染或开始采集的相关操作。<br> 此操作无法由系统强制执行，其对应的[OH_AudioInterrupt_ForceType](#oh_audiointerrupt_forcetype)一定为AUDIOSTREAM_INTERRUPT_SHARE类型。 | 325| AUDIOSTREAM_INTERRUPT_HINT_PAUSE = 2 | 提示音频暂停，暂时失去音频焦点。<br> 后续待焦点可用时，会出现AUDIOSTREAM_INTERRUPT_HINT_RESUME事件。 | 326| AUDIOSTREAM_INTERRUPT_HINT_STOP = 3 | 提示音频停止，彻底失去音频焦点。 | 327| AUDIOSTREAM_INTERRUPT_HINT_DUCK = 4 | 提示音频躲避开始，音频降低音量播放，而不会停止。 | 328| AUDIOSTREAM_INTERRUPT_HINT_UNDUCK = 5 | 提示音量躲避结束，音频恢复正常音量。 | 329| AUDIOSTREAM_INTERRUPT_HINT_MUTE = 6 | 提示音频静音。<br>**起始版本：** 20 | 330| AUDIOSTREAM_INTERRUPT_HINT_UNMUTE = 7 | 提示音频解除静音。<br>**起始版本：** 20 | 331 332### OH_AudioInterrupt_Mode 333 334``` 335enum OH_AudioInterrupt_Mode 336``` 337 338**描述** 339 340定义音频中断模式。 341 342**起始版本：** 12 343 344| 枚举项 | 描述 | 345| -- | -- | 346| AUDIOSTREAM_INTERRUPT_MODE_SHARE = 0 | 共享模式。 | 347| AUDIOSTREAM_INTERRUPT_MODE_INDEPENDENT = 1 | 独立模式。 | 348 349### OH_AudioStream_AudioEffectMode 350 351``` 352enum OH_AudioStream_AudioEffectMode 353``` 354 355**描述** 356 357定义音效模式。 358 359**起始版本：** 12 360 361| 枚举项 | 描述 | 362| -- | -- | 363| EFFECT_NONE = 0 | 无音效模式。 | 364| EFFECT_DEFAULT = 1 | 默认音效模式。 | 365 366### OH_AudioStream_FastStatus 367 368``` 369enum OH_AudioStream_FastStatus 370``` 371 372**描述** 373 374定义低时延状态。 375 376**起始版本：** 20 377 378| 枚举项 | 描述 | 379| -- | -- | 380| AUDIOSTREAM_FASTSTATUS_NORMAL = 0 | 普通音频流状态。 | 381| AUDIOSTREAM_FASTSTATUS_FAST = 1 | 低时延音频流状态。 | 382 383### OH_AudioStream_DeviceChangeReason 384 385``` 386enum OH_AudioStream_DeviceChangeReason 387``` 388 389**描述** 390 391流设备变更原因。 392 393**起始版本：** 11 394 395| 枚举项 | 描述 | 396| -- | -- | 397| REASON_UNKNOWN = 0 | 未知原因。 | 398| REASON_NEW_DEVICE_AVAILABLE = 1 | 新设备可用。 | 399| REASON_OLD_DEVICE_UNAVAILABLE = 2 | 旧设备不可用。当报告此原因时，应用程序应考虑暂停音频播放。 | 400| REASON_OVERRODE = 3 | 用户或系统强制选择切换。 | 401| REASON_SESSION_ACTIVATED = 4 | 音频会话激活触发的设备切换。<br>**起始版本：** 20 | 402| REASON_STREAM_PRIORITY_CHANGED = 5 | 更高优先级的音频流出现导致的系统设备切换。<br>**起始版本：** 20 | 403 404### OH_AudioStream_PrivacyType 405 406``` 407enum OH_AudioStream_PrivacyType 408``` 409 410**描述** 411 412用于标识对应播放音频流是否支持被其他应用录制。 413 414**起始版本：** 12 415 416| 枚举项 | 描述 | 417| -- | -- | 418| AUDIO_STREAM_PRIVACY_TYPE_PUBLIC = 0 | 表示音频流可以被其他应用录制。 | 419| AUDIO_STREAM_PRIVACY_TYPE_PRIVATE = 1 | 表示音频流不可以被其他应用录制。 | 420 421### OH_AudioData_Callback_Result 422 423``` 424enum OH_AudioData_Callback_Result 425``` 426 427**描述** 428 429定义音频数据回调结果。 430 431**起始版本：** 12 432 433| 枚举项 | 描述 | 434| -- | -- | 435| AUDIO_DATA_CALLBACK_RESULT_INVALID = -1 | 表示音频数据回调结果无效，且音频数据不播放。 | 436| AUDIO_DATA_CALLBACK_RESULT_VALID = 0 | 表示音频数据回调结果有效，将播放音频数据。 | 437 438 439## 函数说明 440 441### OH_AudioRenderer_OutputDeviceChangeCallback() 442 443``` 444typedef void (*OH_AudioRenderer_OutputDeviceChangeCallback)(OH_AudioRenderer* renderer, void* userData, OH_AudioStream_DeviceChangeReason reason) 445``` 446 447**描述** 448 449输出音频流设备变更的回调函数。 450 451**起始版本：** 11 452 453 454**参数：** 455 456| 参数项 | 描述 | 457| -- | -- | 458| [OH_AudioRenderer](capi-ohaudio-oh-audiorendererstruct.md)* renderer | 指向[OH_AudioStreamBuilder_GenerateRenderer](capi-native-audiostreambuilder-h.md#oh_audiostreambuilder_generaterenderer)创建的音频流实例。 | 459| void* userData | 指向通过回调函数传递的应用数据指针。 | 460| [OH_AudioStream_DeviceChangeReason](#oh_audiostream_devicechangereason) reason | 流设备变更原因。 | 461 462### OH_AudioRenderer_OnMarkReachedCallback() 463 464``` 465typedef void (*OH_AudioRenderer_OnMarkReachedCallback)(OH_AudioRenderer* renderer, uint32_t samplePos, void* userData) 466``` 467 468**描述** 469 470到达标记位置时回调。 471 472**起始版本：** 12 473 474 475**参数：** 476 477| 参数项 | 描述 | 478| -- | -- | 479| [OH_AudioRenderer](capi-ohaudio-oh-audiorendererstruct.md)* renderer | 指向[OH_AudioStreamBuilder_GenerateRenderer](capi-native-audiostreambuilder-h.md#oh_audiostreambuilder_generaterenderer)创建的音频流实例。 | 480| uint32_t samplePos | 设置目标标记位置。 | 481| void* userData | 指向通过回调函数传递的应用数据指针。 | 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**描述** 490 491该函数指针将指向用于同时写入音频数据和元数据的回调函数。 492 493**起始版本：** 12 494 495 496**参数：** 497 498| 参数项 | 描述 | 499| -- | -- | 500| [OH_AudioRenderer](capi-ohaudio-oh-audiorendererstruct.md)* renderer | 指向[OH_AudioStreamBuilder_GenerateRenderer](capi-native-audiostreambuilder-h.md#oh_audiostreambuilder_generaterenderer)创建的音频流实例。 | 501| void* userData | 指向通过回调函数传递的应用数据指针。 | 502| void* audioData | 指向用户写入的音频数据的指针。 | 503| int32_t audioDataSize | 用户写入的音频数据的数据长度，以字节为单位。 | 504| void* metadata | 指向用户写入的元数据的指针。 | 505| int32_t metadataSize | 用户写入的元数据的数据长度，以字节为单位。 | 506 507**返回：** 508 509| 类型 | 说明 | 510| -- | -- | 511| int32_t | 用户返回的回调函数的错误码。 | 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**描述** 520 521该函数指针将指向用于写入音频数据的回调函数。<br> 回调函数仅用来写入音频数据，请勿在回调函数中调用AudioRenderer相关接口。<br> 该函数的返回结果表示填充到缓冲区的数据是否有效。如果结果无效，用户填写的数据将不被播放。回调函数结束后，音频服务会把audioData指针数据放入队列里等待播放，因此请勿在回调外再次更改audioData指向的数据, 且务必保证往audioData填满audioDataSize长度的待播放数据, 否则会导致音频服务播放杂音。<br> 参数audioDataSize可以通过[OH_AudioStreamBuilder_SetFrameSizeInCallback](capi-native-audiostreambuilder-h.md#oh_audiostreambuilder_setframesizeincallback)设置。 522 523**起始版本：** 12 524 525 526**参数：** 527 528| 参数项 | 描述 | 529| -- | -- | 530| [OH_AudioRenderer](capi-ohaudio-oh-audiorendererstruct.md)* renderer | 指向[OH_AudioStreamBuilder_GenerateRenderer](capi-native-audiostreambuilder-h.md#oh_audiostreambuilder_generaterenderer)创建的音频流实例。 | 531| void* userData | 指向通过回调函数传递的应用数据指针。 | 532| void* audioData | 指向用户写入的音频数据的指针。 | 533| int32_t audioDataSize | 用户写入的音频数据的数据长度，以字节为单位。 | 534 535**返回：** 536 537| 类型 | 说明 | 538| -- | -- | 539| [OH_AudioData_Callback_Result](#oh_audiodata_callback_result) | AUDIO_DATA_CALLBACK_RESULT_INVALID：音频数据回调结果无效，且音频数据不播放。<br> AUDIO_DATA_CALLBACK_RESULT_VALID：音频数据回调结果有效，将播放音频数据。 | 540 541### OH_AudioRenderer_OnWriteDataCallbackAdvanced() 542 543``` 544typedef int32_t (*OH_AudioRenderer_OnWriteDataCallbackAdvanced)(OH_AudioRenderer* renderer, void* userData, void* audioData, int32_t audioDataSize) 545``` 546 547**描述** 548 549该函数指针将指向用于写入音频数据的回调函数。不同于OH_AudioRenderer_OnWriteDataCallback，此函数允许应用填充[0, audioDataSize]长度的数据。<br> 其中audioDataSize为回调buffer的长度。调用方通过返回值告知系统写入的数据长度。<br> 如果返回0，回调线程将会sleep一段时间。<br> 否则，系统可能会立刻进行下一次回调。 550 551**起始版本：** 20 552 553 554**参数：** 555 556| 参数项 | 描述 | 557| -- | -- | 558| [OH_AudioRenderer](capi-ohaudio-oh-audiorendererstruct.md)* renderer | 指向发生回调的实例。 | 559| void* userData | 指向通过回调函数传递的应用数据指针。 | 560| void* audioData | 指向让应用填充音频数据的指针。 | 561| int32_t audioDataSize | 应用应写入音频数据的数据长度，以字节为单位。 | 562 563**返回：** 564 565| 类型 | 说明 | 566| -- | -- | 567| int32_t | 应用实际填充有效音频数据的长度。返回值必须在[0, audioDataSize]范围内。<br>如果返回值小于0，系统将调整为0。并且，如果返回值大于audioDataSize，系统将其调整到audioDataSize。<br>注意返回值必须是单个采样点大小的整数倍。<br>比如，双声道s16格式的音频数据，必须是4(216/8)的整数倍。<br>否则，可能造成播放杂音。 | 568 569 570