1 /* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup OHAudio 18 * @{ 19 * 20 * @brief Provide the definition of the C interface for the audio module. 21 * 22 * @syscap SystemCapability.Multimedia.Audio.Core 23 * 24 * @since 10 25 * @version 1.0 26 */ 27 28 /** 29 * @file native_audiorenderer.h 30 * 31 * @brief Declare audio stream related interfaces for output type. 32 * 33 * @library libohaudio.so 34 * @syscap SystemCapability.Multimedia.Audio.Core 35 * @kit AudioKit 36 * @since 10 37 * @version 1.0 38 */ 39 40 #ifndef NATIVE_AUDIORENDERER_H 41 #define NATIVE_AUDIORENDERER_H 42 43 #include <stdbool.h> 44 #include <time.h> 45 #include "native_audiostream_base.h" 46 #include "native_audio_device_base.h" 47 #include "multimedia/native_audio_channel_layout.h" 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 /** 52 * Request to release the renderer stream. 53 * 54 * @since 10 55 * 56 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 57 * @return Function result code: 58 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 59 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 60 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 61 */ 62 OH_AudioStream_Result OH_AudioRenderer_Release(OH_AudioRenderer* renderer); 63 64 /** 65 * Request to start the renderer stream. 66 * 67 * @since 10 68 * 69 * @param renderer reference created by OH_AudioStreamBuilder 70 * @return Function result code: 71 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 72 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 73 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 74 */ 75 OH_AudioStream_Result OH_AudioRenderer_Start(OH_AudioRenderer* renderer); 76 77 /** 78 * Request to pause the renderer stream. 79 * 80 * @since 10 81 * 82 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 83 * @return Function result code: 84 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 85 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 86 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 87 */ 88 OH_AudioStream_Result OH_AudioRenderer_Pause(OH_AudioRenderer* renderer); 89 90 /** 91 * Request to stop renderer stream. 92 * 93 * @since 10 94 * 95 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 96 * @return Function result code: 97 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 98 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 99 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 100 */ 101 OH_AudioStream_Result OH_AudioRenderer_Stop(OH_AudioRenderer* renderer); 102 103 /** 104 * Request to flush the renderer stream. 105 * 106 * @since 10 107 * 108 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 109 * @return Function result code: 110 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 111 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 112 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 113 */ 114 OH_AudioStream_Result OH_AudioRenderer_Flush(OH_AudioRenderer* renderer); 115 116 /** 117 * Query the current state of the renderer client. 118 * 119 * This function will return the renderer state without updating the state. 120 * 121 * @since 10 122 * 123 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 124 * @param state Pointer to a variable that will be set for the state value. 125 * @return Function result code: 126 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 127 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 128 */ 129 OH_AudioStream_Result OH_AudioRenderer_GetCurrentState(OH_AudioRenderer* renderer, 130 OH_AudioStream_State* state); 131 132 /** 133 * Query the sample rate value of the renderer client 134 * 135 * This function will return the renderer sample rate value without updating the state. 136 * 137 * @since 10 138 * 139 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 140 * @param rate The state value to be updated 141 * @return Function result code: 142 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 143 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 144 */ 145 OH_AudioStream_Result OH_AudioRenderer_GetSamplingRate(OH_AudioRenderer* renderer, int32_t* rate); 146 147 /** 148 * Query the stream id of the renderer client. 149 * 150 * @since 10 151 * 152 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 153 * @param streamId Pointer to a variable that will be set for the stream id. 154 * @return Function result code: 155 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 156 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 157 */ 158 OH_AudioStream_Result OH_AudioRenderer_GetStreamId(OH_AudioRenderer* renderer, uint32_t* streamId); 159 160 /** 161 * Query the channel count of the renderer client. 162 * 163 * @since 10 164 * 165 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 166 * @param channelCount Pointer to a variable that will be set for the channel count. 167 * @return Function result code: 168 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 169 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 170 */ 171 OH_AudioStream_Result OH_AudioRenderer_GetChannelCount(OH_AudioRenderer* renderer, int32_t* channelCount); 172 173 /** 174 * Query the sample format of the renderer client. 175 * 176 * @since 10 177 * 178 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 179 * @param sampleFormat Pointer to a variable that will be set for the sample format. 180 * @return Function result code: 181 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 182 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 183 */ 184 OH_AudioStream_Result OH_AudioRenderer_GetSampleFormat(OH_AudioRenderer* renderer, 185 OH_AudioStream_SampleFormat* sampleFormat); 186 187 /** 188 * Query the latency mode of the renderer client. 189 * 190 * @since 10 191 * 192 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 193 * @param latencyMode Pointer to a variable that will be set for the latency mode. 194 * @return Function result code: 195 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 196 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 197 */ 198 OH_AudioStream_Result OH_AudioRenderer_GetLatencyMode(OH_AudioRenderer* renderer, 199 OH_AudioStream_LatencyMode* latencyMode); 200 /** 201 * Query the renderer info of the renderer client. 202 * 203 * The rendere info includes {@link OH_AudioStream_Usage} value. 204 * 205 * @since 10 206 * 207 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 208 * @param usage Pointer to a variable that will be set for the stream usage. 209 * @return Function result code: 210 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 211 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 212 */ 213 OH_AudioStream_Result OH_AudioRenderer_GetRendererInfo(OH_AudioRenderer* renderer, 214 OH_AudioStream_Usage* usage); 215 216 /** 217 * Query the encoding type of the renderer client. 218 * 219 * @since 10 220 * 221 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 222 * @param encodingType Pointer to a variable that will be set for the encoding type. 223 * @return Function result code: 224 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 225 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 226 */ 227 OH_AudioStream_Result OH_AudioRenderer_GetEncodingType(OH_AudioRenderer* renderer, 228 OH_AudioStream_EncodingType* encodingType); 229 230 /** 231 * Query the the number of frames that have been written since the stream was created. 232 * 233 * @since 10 234 * 235 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 236 * @param frames Pointer to a variable that will be set for the frame count number. 237 * @return Function result code: 238 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 239 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 240 */ 241 OH_AudioStream_Result OH_AudioRenderer_GetFramesWritten(OH_AudioRenderer* renderer, int64_t* frames); 242 243 /** 244 * Query the the time at which a particular frame was presented. 245 * 246 * It is recommended to use new api {@link OH_AudioRenderer_GetAudioTimestampInfo} 247 * because it adapts to playback speed change, but current api does not. The 248 * increasing speed for position will not change when speed become fast. 249 * 250 * @since 10 251 * 252 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 253 * @param clockId {@link #CLOCK_MONOTONIC} 254 * @param framePosition Pointer to a variable to receive the position 255 * @param timestamp Pointer to a variable to receive the timestamp 256 * @return Function result code: 257 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 258 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 259 * 1.The param of renderer is nullptr; 260 * 2.The param of clockId invalid. 261 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 262 */ 263 OH_AudioStream_Result OH_AudioRenderer_GetTimestamp(OH_AudioRenderer* renderer, 264 clockid_t clockId, int64_t* framePosition, int64_t* timestamp); 265 266 /** 267 * Query the frame size in callback, it is a fixed length that the stream want to be filled for each callback. 268 * 269 * @since 10 270 * 271 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 272 * @param frameSize Pointer to a variable that will be set for the frame size. 273 * @return Function result code: 274 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 275 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 276 */ 277 OH_AudioStream_Result OH_AudioRenderer_GetFrameSizeInCallback(OH_AudioRenderer* renderer, int32_t* frameSize); 278 279 /** 280 * Query the playback speed of the stream client 281 * 282 * @since 11 283 * 284 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 285 * @param speed Pointer to a variable to receive the playback speed. 286 * @return Function result code: 287 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 288 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 289 */ 290 OH_AudioStream_Result OH_AudioRenderer_GetSpeed(OH_AudioRenderer* renderer, float* speed); 291 292 293 /** 294 * Set the playback speed of the stream client 295 * 296 * @since 11 297 * 298 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 299 * @param speed The playback speed, form 0.25 to 4.0. 300 * @return Function result code: 301 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 302 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 303 */ 304 OH_AudioStream_Result OH_AudioRenderer_SetSpeed(OH_AudioRenderer* renderer, float speed); 305 306 /** 307 * Set volume of current renderer. 308 * 309 * @since 12 310 * 311 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 312 * @param volume Volume to set which changes from 0.0 to 1.0. 313 * @return Function result code: 314 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 315 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 316 * 1.The param of renderer is nullptr; 317 * 2.The param of volume invalid. 318 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 319 * {@link AUDIOSTREAM_ERROR_SYSTEM} An system error has occurred. 320 */ 321 OH_AudioStream_Result OH_AudioRenderer_SetVolume(OH_AudioRenderer* renderer, float volume); 322 323 /** 324 * Changes the volume with ramp for a duration. 325 * 326 * @since 12 327 * 328 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 329 * @param volume Volume to set which changes from 0.0 to 1.0. 330 * @param durationMs Duration for volume ramp, in millisecond. 331 * @return Function result code: 332 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 333 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 334 * 1.The param of renderer is nullptr; 335 * 2.The param of volume invalid. 336 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 337 * {@link AUDIOSTREAM_ERROR_SYSTEM} An system error has occurred. 338 */ 339 OH_AudioStream_Result OH_AudioRenderer_SetVolumeWithRamp(OH_AudioRenderer* renderer, float volume, int32_t durationMs); 340 341 /** 342 * Get Volume of current renderer. 343 * 344 * @since 12 345 * 346 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 347 * @param volume Pointer to a variable to receive the volume. 348 * @return Function result code: 349 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 350 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 351 * 1.The param of renderer is nullptr; 352 * 2.The param of volume is nullptr. 353 */ 354 OH_AudioStream_Result OH_AudioRenderer_GetVolume(OH_AudioRenderer* renderer, float* volume); 355 356 /** 357 * @brief Set mark position on current renderer. Calling this function will overwrite the mark postion which has already 358 * set. 359 * 360 * @since 12 361 * 362 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 363 * @param samplePos Mark position in samples. 364 * @param callback Callback used when the samplePos has reached. 365 * @param userData User data which is passed by user. 366 * @return Function result code: 367 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 368 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 369 * 1.The param of renderer is nullptr; 370 * 2.The param of samplePos invalid. 371 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception. 372 * {@link AUDIOSTREAM_ERROR_SYSTEM} An system error has occurred. 373 */ 374 OH_AudioStream_Result OH_AudioRenderer_SetMarkPosition(OH_AudioRenderer* renderer, uint32_t samplePos, 375 OH_AudioRenderer_OnMarkReachedCallback callback, void* userData); 376 377 /** 378 * @brief Cancel mark which has set by {@link #OH_AudioRenderer_SetMarkPosition}. 379 * 380 * @since 12 381 * 382 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 383 * @return Function result code: 384 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 385 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 386 */ 387 OH_AudioStream_Result OH_AudioRenderer_CancelMark(OH_AudioRenderer* renderer); 388 389 /** 390 * @brief Gets the underflow count on this stream. 391 * 392 * @since 12 393 * 394 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 395 * @param count Pointer to a variable to receive the underflow count number. 396 * @return Function result code: 397 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 398 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 399 * 1.The param of renderer is nullptr; 400 * 2.The param of count is nullptr. 401 */ 402 OH_AudioStream_Result OH_AudioRenderer_GetUnderflowCount(OH_AudioRenderer* renderer, uint32_t* count); 403 404 /** 405 * @brief Query the channel layout of the renderer client. 406 * 407 * @since 12 408 * 409 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 410 * @param channelLayout Pointer to a variable to receive the channel layout 411 * @return Function result code: 412 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 413 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 414 */ 415 OH_AudioStream_Result OH_AudioRenderer_GetChannelLayout(OH_AudioRenderer* renderer, 416 OH_AudioChannelLayout* channelLayout); 417 418 /** 419 * @brief Query current audio effect mode. 420 * 421 * @since 12 422 * 423 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 424 * @param effectMode Pointer to a variable to receive current audio effect mode 425 * @return Function result code: 426 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 427 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 428 */ 429 OH_AudioStream_Result OH_AudioRenderer_GetEffectMode(OH_AudioRenderer* renderer, 430 OH_AudioStream_AudioEffectMode* effectMode); 431 432 /** 433 * @brief Set current audio effect mode. 434 * 435 * @since 12 436 * 437 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 438 * @param effectMode Audio effect mode that will be set for the stream 439 * @return Function result code: 440 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 441 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 442 */ 443 OH_AudioStream_Result OH_AudioRenderer_SetEffectMode(OH_AudioRenderer* renderer, 444 OH_AudioStream_AudioEffectMode effectMode); 445 446 /** 447 * @brief Get the privacy of this stream. 448 * 449 * @since 12 450 * 451 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 452 * @param privacy Pointer to a variable which receives the results. 453 * @return Function result code: 454 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 455 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr. 456 */ 457 OH_AudioStream_Result OH_AudioRenderer_GetRendererPrivacy(OH_AudioRenderer* renderer, 458 OH_AudioStream_PrivacyType* privacy); 459 460 /** 461 * @brief Set silent and mix with other streams for this stream. 462 * 463 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 464 * @param on The silent and mix with other streams mode. 465 * true: set the slient mode and mix with other streams. 466 * false: unset the slient mode, current stream will trigger the audio focus internally. 467 * @return result code for this function. 468 * {@link #AUDIOSTREAM_SUCCESS} succeed in setting to the silent and mix with other streams. 469 * {@link #AUDIOSTREAM_ERROR_ILLEGAL_STATE} this stream is not allowed to set/unset the silent mode. 470 * @since 12 471 */ 472 OH_AudioStream_Result OH_AudioRenderer_SetSilentModeAndMixWithOthers( 473 OH_AudioRenderer* renderer, bool on); 474 475 /** 476 * @brief Query silent and mix with other streams status for this stream. 477 * 478 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 479 * @param on Pointer to the silent and mix with other streams status. 480 * @return result code for this function. 481 * {@link #AUDIOSTREAM_SUCCESS} succeed in getting silent and mix with other streams status 482 * {@link #AUDIOSTREAM_ERROR_SYSTEM} system error when calling this function. 483 * @since 12 484 */ 485 OH_AudioStream_Result OH_AudioRenderer_GetSilentModeAndMixWithOthers( 486 OH_AudioRenderer* renderer, bool* on); 487 488 /** 489 * @brief Temporarily changes the current audio device 490 * This function applys on audiorenderers whose StreamUsage are 491 * STREAM_USAGE_VOICE_COMMUNICATIN/STREAM_USAGE_VIDEO_COMMUNICATION/STREAM_USAGE_VOICE_MESSAGE. 492 * Setting the device will only takes effect if no other accessory such as headphones are in use. 493 * 494 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 495 * @param deviceType The target device. The available deviceTypes are: 496 * EARPIECE: Built-in earpiece 497 * SPEAKER: Built-in speaker 498 * DEFAULT: System default output device 499 * @return result code for this function. 500 * {@link #AUDIOSTREAM_SUCCESS} succeed in setting the default output device 501 * {@link #AUDIOSTREAM_ERROR_INVALID_PARAM}: 502 * 1.The param of renderer is nullptr; 503 * 2.The param of deviceType is not valid 504 * {@link #AUDIOSTREAM_ERROR_ILLEGAL_STATE} This audiorenderer can not reset the output device 505 * {@link #AUDIOSTREAM_ERROR_SYSTEM} system error when calling this function. 506 * @since 12 507 */ 508 OH_AudioStream_Result OH_AudioRenderer_SetDefaultOutputDevice( 509 OH_AudioRenderer* renderer, OH_AudioDevice_Type deviceType); 510 511 /** 512 * @brief Query the timestamp at which a particular frame was presented in clock monotonic timebase, 513 * the frame at the returned position was just committed to hardware. This is often used in 514 * video synchronization and recording stream alignment. 515 * 516 * Position is 0 and timestamp is fixed until stream really runs and frame is committed. Position 517 * will also be reset while flush function is called. When a audio route change happens, like in 518 * device or output type change situations, the position may also be reset but timestamp remains 519 * monotonically increasing. 520 * So it is better to use the values until they becomes regularly after the change. 521 * This interface also adapts to playback speed change. For example, the increseing speed for 522 * position will be double for 2x speed playback. 523 * 524 * For video synchronization usage, there is a best practice document for developer to refer 525 * **AV Synchronization**. 526 * 527 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 528 * @param framePosition Pointer to a variable to receive the position 529 * @param timestamp Pointer to a variable to receive the timestamp 530 * @return Function result code: 531 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 532 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 533 * 1.The param of renderer is nullptr; 534 * 2.The param of framePosition or timestamp is nullptr; 535 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE}: 536 * 1.Only running state is legal for getting audio timestamp. 537 * {@link AUDIOSTREAM_ERROR_SYSTEM}: 538 * 1.Crash or blocking occurs in system process. 539 * 2.Other unexpected error from internal system. 540 * @since 15 541 */ 542 OH_AudioStream_Result OH_AudioRenderer_GetAudioTimestampInfo(OH_AudioRenderer* renderer, 543 int64_t* framePosition, int64_t* timestamp); 544 545 /** 546 * @brief Called when an interrupt event occurs in an AudioRenderer instance. 547 * This function is similar to OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnInterruptEvent. 548 * 549 * @param renderer Pointer to the AudioRenderer instance that triggers the callback. 550 * @param userData Pointer to the user data passed when setting the callback via 551 * OH_AudioStreamBuilder_SetRendererInterruptCallback. 552 * @param type Type of force that causes the interrupt event. 553 * @param hint Hint provided along with the interrupt event. 554 * @see OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnInterruptEvent. 555 * @since 20 556 */ 557 typedef void (*OH_AudioRenderer_OnInterruptCallback)(OH_AudioRenderer* renderer, void* userData, 558 OH_AudioInterrupt_ForceType type, OH_AudioInterrupt_Hint hint); 559 560 /** 561 * @brief Called when an error event occurs in an AudioRenderer instance. 562 * This function is similar to OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnError. 563 * 564 * @param renderer Pointer to the AudioRenderer instance that triggers the callback. 565 * @param userData Pointer to the user data passed when setting the callback via 566 * OH_AudioStreamBuilder_SetRendererErrorCallback. 567 * @param error Specific error information. 568 * @see OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnError 569 * @since 20 570 */ 571 typedef void (*OH_AudioRenderer_OnErrorCallback)(OH_AudioRenderer* renderer, void* userData, 572 OH_AudioStream_Result error); 573 574 /** 575 * @brief Gets audio renderer running status, check if it works in fast status. 576 * 577 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer. 578 * @param status Pointer to a variable to receive the status. 579 * @return 580 * {@link AUDIOSTREAM_SUCCESS} if the execution is successful. 581 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} the param of renderer is nullptr. 582 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} function called in invalid state, only available before release state. 583 * @since 20 584 */ 585 OH_AudioStream_Result OH_AudioRenderer_GetFastStatus(OH_AudioRenderer* renderer, 586 OH_AudioStream_FastStatus* status); 587 588 /** 589 * @brief Callback function of fast status change event for audio renderer. 590 * 591 * @param renderer Pointer to an audio renderer instance for which this callback occurs. 592 * @param userData Userdata which is passed by register. 593 * @param status Current fast status. 594 * @since 20 595 */ 596 typedef void (*OH_AudioRenderer_OnFastStatusChange)( 597 OH_AudioRenderer* renderer, 598 void* userData, 599 OH_AudioStream_FastStatus status 600 ); 601 602 /** 603 * @brief Sets the loudness gain of current renderer. 604 * The default loudness gain is 0.0dB. The stream usage of the audio renderer must be 605 * {@link OH_AudioStream_Usage#AUDIOSTREAM_USAGE_MUSIC}, {@link OH_AudioStream_Usage#AUDIOSTREAM_USAGE_MOVIE} 606 * or {@link OH_AudioStream_Usage#AUDIOSTREAM_USAGE_AUDIOBOOK}. 607 * The latency mode of the audio renderer must be {@link OH_AudioStream_LatencyMode#AUDIOSTREAM_LATENCY_MODE_NORMAL}. 608 * If AudioRenderer is played through the high-resolution pipe, this operation is not supported. 609 * 610 * @param renderer AudioRender created by OH_AudioStreamBuilder_GenerateRenderer() 611 * @param loudnessGain Loudness gain to set which changes from -90.0 to 24.0, expressing in dB. 612 * @return Function result code: 613 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 614 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 615 * 1.The param of renderer is nullptr or not supported to set gain; 616 * 2.The param of loudnessGain is invalid. 617 * @since 20 618 */ 619 OH_AudioStream_Result OH_AudioRenderer_SetLoudnessGain(OH_AudioRenderer* renderer, float loudnessGain); 620 621 /** 622 * @brief Get the loudness gain of current renderer. 623 * 624 * @param renderer AudioRender created by OH_AudioStreamBuilder_GenerateRenderer() 625 * @param loudnessGain Pointer to a variable to receive the loudness gain. 626 * @return Function result code: 627 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 628 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 629 * 1.The param of renderer is nullptr; 630 * 2.The param of loudnessGain is nullptr. 631 * @since 20 632 */ 633 OH_AudioStream_Result OH_AudioRenderer_GetLoudnessGain(OH_AudioRenderer* renderer, float* loudnessGain); 634 635 /** 636 * @brief Callback function of write data on Render. 637 * 638 * Different with OH_AudioRenderer_OnWriteDataCallback, this function allows the caller to write partial data which 639 * ranges from 0 to the callback buffer size. If 0 is returned, the callback thread will sleep for a while. Otherwise, 640 * the system may callback again immediately. 641 * 642 * @param renderer AudioRenderer where this callback occurs. 643 * @param userData User data which is passed by user. 644 * @param audioData Audio data pointer, where user should fill in audio data. 645 * @param audioDataSize Size of audio data that user should fill in. 646 * @return Length of the valid data that has written into audioData buffer. The return value must be in range of 647 * [0, audioDataSize]. If the return value is less than 0, the system changes it to 0. And, if the return value is 648 * greater than audioDataSize, the system changes it to audioDataSize. Note that the length of the returned buffer 649 * must be an integer multiple of the length of the single sample data. For example, for 2 channels and S16 format 650 * audio data, it must be an integer multiple of 4(2*16/8). Otherwise, it may cause noise during playback. 651 * @see OH_AudioRenderer_OnWriteDataCallback 652 * @since 20 653 */ 654 typedef int32_t (*OH_AudioRenderer_OnWriteDataCallbackAdvanced)(OH_AudioRenderer* renderer, void* userData, 655 void* audioData, int32_t audioDataSize); 656 657 #ifdef __cplusplus 658 } 659 #endif 660 661 #endif // NATIVE_AUDIORENDERER_H 662 /** @} */