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 * @syscap SystemCapability.Multimedia.Audio.Core 34 * @since 10 35 * @version 1.0 36 */ 37 38 #ifndef NATIVE_AUDIORENDERER_H 39 #define NATIVE_AUDIORENDERER_H 40 41 #include <time.h> 42 #include "native_audiostream_base.h" 43 #include "native_audio_device_base.h" 44 #include "multimedia/native_audio_channel_layout.h" 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 /* 49 * Request to release the renderer stream. 50 * 51 * @since 10 52 * 53 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 54 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 55 */ 56 OH_AudioStream_Result OH_AudioRenderer_Release(OH_AudioRenderer* renderer); 57 58 /* 59 * Request to start the renderer stream. 60 * 61 * @since 10 62 * 63 * @param renderer reference created by OH_AudioStreamBuilder 64 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 65 */ 66 OH_AudioStream_Result OH_AudioRenderer_Start(OH_AudioRenderer* renderer); 67 68 /* 69 * Request to pause the renderer stream. 70 * 71 * @since 10 72 * 73 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 74 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 75 */ 76 OH_AudioStream_Result OH_AudioRenderer_Pause(OH_AudioRenderer* renderer); 77 78 /* 79 * Request to stop renderer stream. 80 * 81 * @since 10 82 * 83 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 84 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 85 */ 86 OH_AudioStream_Result OH_AudioRenderer_Stop(OH_AudioRenderer* renderer); 87 88 /* 89 * Request to flush the renderer stream. 90 * 91 * @since 10 92 * 93 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 94 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 95 */ 96 OH_AudioStream_Result OH_AudioRenderer_Flush(OH_AudioRenderer* renderer); 97 98 /* 99 * Query the current state of the renderer client. 100 * 101 * This function will return the renderer state without updating the state. 102 * 103 * @since 10 104 * 105 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 106 * @param state Pointer to a variable that will be set for the state value. 107 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 108 */ 109 OH_AudioStream_Result OH_AudioRenderer_GetCurrentState(OH_AudioRenderer* renderer, 110 OH_AudioStream_State* state); 111 112 /* 113 * Query the sample rate value of the renderer client 114 * 115 * This function will return the renderer sample rate value without updating the state. 116 * 117 * @since 10 118 * 119 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 120 * @param rate The state value to be updated 121 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 122 */ 123 OH_AudioStream_Result OH_AudioRenderer_GetSamplingRate(OH_AudioRenderer* renderer, int32_t* rate); 124 125 /* 126 * Query the stream id of the renderer client. 127 * 128 * @since 10 129 * 130 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 131 * @param stramId Pointer to a variable that will be set for the stream id. 132 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 133 */ 134 OH_AudioStream_Result OH_AudioRenderer_GetStreamId(OH_AudioRenderer* renderer, uint32_t* streamId); 135 136 /* 137 * Query the channel count of the renderer client. 138 * 139 * @since 10 140 * 141 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 142 * @param channelCount Pointer to a variable that will be set for the channel count. 143 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 144 */ 145 OH_AudioStream_Result OH_AudioRenderer_GetChannelCount(OH_AudioRenderer* renderer, int32_t* channelCount); 146 147 /* 148 * Query the sample format of the renderer client. 149 * 150 * @since 10 151 * 152 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 153 * @param sampleFormat Pointer to a variable that will be set for the sample format. 154 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 155 */ 156 OH_AudioStream_Result OH_AudioRenderer_GetSampleFormat(OH_AudioRenderer* renderer, 157 OH_AudioStream_SampleFormat* sampleFormat); 158 159 /* 160 * Query the latency mode of the renderer client. 161 * 162 * @since 10 163 * 164 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 165 * @param latencyMode Pointer to a variable that will be set for the latency mode. 166 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 167 */ 168 OH_AudioStream_Result OH_AudioRenderer_GetLatencyMode(OH_AudioRenderer* renderer, 169 OH_AudioStream_LatencyMode* latencyMode); 170 /* 171 * Query the renderer info of the renderer client. 172 * 173 * The rendere info includes {@link OH_AudioStream_Usage} value. 174 * 175 * @since 10 176 * 177 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 178 * @param usage Pointer to a variable that will be set for the stream usage. 179 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 180 */ 181 OH_AudioStream_Result OH_AudioRenderer_GetRendererInfo(OH_AudioRenderer* renderer, 182 OH_AudioStream_Usage* usage); 183 184 /* 185 * Query the encoding type of the renderer client. 186 * 187 * @since 10 188 * 189 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 190 * @param encodingType Pointer to a variable that will be set for the encoding type. 191 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 192 */ 193 OH_AudioStream_Result OH_AudioRenderer_GetEncodingType(OH_AudioRenderer* renderer, 194 OH_AudioStream_EncodingType* encodingType); 195 196 /* 197 * Query the the number of frames that have been written since the stream was created. 198 * 199 * @since 10 200 * 201 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 202 * @param frames Pointer to a variable that will be set for the frame count number. 203 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 204 */ 205 OH_AudioStream_Result OH_AudioRenderer_GetFramesWritten(OH_AudioRenderer* renderer, int64_t* frames); 206 207 /* 208 * Query the the time at which a particular frame was presented. 209 * 210 * @since 10 211 * 212 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 213 * @param clockId {@link #CLOCK_MONOTONIC} 214 * @param framePosition Pointer to a variable to receive the position 215 * @param timestamp Pointer to a variable to receive the timestamp 216 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 217 */ 218 OH_AudioStream_Result OH_AudioRenderer_GetTimestamp(OH_AudioRenderer* renderer, 219 clockid_t clockId, int64_t* framePosition, int64_t* timestamp); 220 221 /* 222 * Query the timestamp at which a particular frame was presented in clock monotonic timebase, the frame at 223 * the returned position was just committed to hardware. This is often used in video synchronization and 224 * recording stream alignment. 225 * 226 * Position is 0 and timestamp is fixed until stream really runs and frame is committed. Position will 227 * also be reset while flush function is called. When a audio route change happens, like in device or output 228 * type change situations, the position may also be reset but timestamp remains monotonically increasing. 229 * So it is better to use the values until they becomes regularly after the change. 230 * This interface also adapts to playback speed change. For example, the increseing speed for position 231 * will be double for 2x speed playback. 232 * 233 * @since 15 234 * 235 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 236 * @param framePosition Pointer to a variable to receive the position 237 * @param timestamp Pointer to a variable to receive the timestamp 238 * @return Function result code: 239 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 240 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 241 * 1.The param of renderer is nullptr; 242 * 2.The param of framePosition or timestamp is nullptr; 243 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE}: 244 * 1.Stopped state is illegal for getting audio timestamp. 245 * {@link AUDIOSTREAM_ERROR_SYSTEM}: 246 * 1.Crash or blocking occurs in system process. 247 * 2.Other unexpected error from internal system. 248 */ 249 OH_AudioStream_Result OH_AudioRenderer_GetAudioTimestampInfo(OH_AudioRenderer* renderer, 250 int64_t* framePosition, int64_t* timestamp); 251 252 /* 253 * Query the frame size in callback, it is a fixed length that the stream want to be filled for each callback. 254 * 255 * @since 10 256 * 257 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 258 * @param frameSize Pointer to a variable that will be set for the frame size. 259 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 260 */ 261 OH_AudioStream_Result OH_AudioRenderer_GetFrameSizeInCallback(OH_AudioRenderer* renderer, int32_t* frameSize); 262 263 /* 264 * Query the playback speed of the stream client 265 * 266 * @since 11 267 * 268 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 269 * @param speed Pointer to a variable to receive the playback speed. 270 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 271 */ 272 OH_AudioStream_Result OH_AudioRenderer_GetSpeed(OH_AudioRenderer* renderer, float* speed); 273 274 /* 275 * Set the playback speed of the stream client 276 * 277 * @since 11 278 * 279 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 280 * @param speed The playback speed, form 0.25 to 4.0. 281 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 282 */ 283 OH_AudioStream_Result OH_AudioRenderer_SetSpeed(OH_AudioRenderer* renderer, float speed); 284 285 /** 286 * @brief Set mark position on current renderer. Calling this function will overwrite the mark postion which has already 287 * set. 288 * 289 * @since 12 290 * 291 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 292 * @param samplePos Mark position in samples. 293 * @param callback Callback used when the samplePos has reached. 294 * @param userData User data which is passed by user. 295 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 296 */ 297 OH_AudioStream_Result OH_AudioRenderer_SetMarkPosition(OH_AudioRenderer* renderer, uint32_t samplePos, 298 OH_AudioRenderer_OnMarkReachedCallback callback, void* userData); 299 300 /** 301 * @brief Cancel mark which has set by {@link #OH_AudioRenderer_SetMarkPosition}. 302 * 303 * @since 12 304 * 305 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 306 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 307 */ 308 OH_AudioStream_Result OH_AudioRenderer_CancelMark(OH_AudioRenderer* renderer); 309 310 /** 311 * Set volume of current renderer. 312 * 313 * @since 12 314 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 315 * @param volume Volume to set which changes from 0.0 to 1.0. 316 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 317 */ 318 OH_AudioStream_Result OH_AudioRenderer_SetVolume(OH_AudioRenderer* renderer, float volume); 319 320 /** 321 * Changes the volume with ramp for a duration. 322 * 323 * @since 12 324 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 325 * @param volume Volume to set which changes from 0.0 to 1.0. 326 * @param durationMs Duration for volume ramp, in millisecond. 327 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 328 */ 329 OH_AudioStream_Result OH_AudioRenderer_SetVolumeWithRamp(OH_AudioRenderer* renderer, float volume, int32_t durationMs); 330 331 /** 332 * @brief Sets the loudness gain of current renderer. 333 * The default loudness gain is 0.0dB. The stream usage of the audio renderer must be 334 * {@link OH_AudioStream_Usage#AUDIOSTREAM_USAGE_MUSIC}, {@link OH_AudioStream_Usage#AUDIOSTREAM_USAGE_MOVIE} 335 * or {@link OH_AudioStream_Usage#AUDIOSTREAM_USAGE_AUDIOBOOK}. 336 * The latency mode of the audio renderer must be {@link OH_AudioStream_LatencyMode#AUDIOSTREAM_LATENCY_MODE_NORMAL}. 337 * If AudioRenderer is played through the high-resolution pipe, this operation is not supported. 338 * 339 * @param renderer AudioRender created by OH_AudioStreamBuilder_GenerateRenderer() 340 * @param loudnessGain Loudness gain to set which changes from -90.0 to 24.0, expressing in dB. 341 * @return Function result code: 342 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 343 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 344 * 1.The param of renderer is nullptr or not supported to set gain; 345 * 2.The param of loudnessGain is invalid. 346 * @since 20 347 */ 348 OH_AudioStream_Result OH_AudioRenderer_SetLoudnessGain(OH_AudioRenderer* renderer, float loudnessGain); 349 350 /** 351 * @brief Get the loudness gain of current renderer. 352 * 353 * @param renderer AudioRender created by OH_AudioStreamBuilder_GenerateRenderer() 354 * @param loudnessGain Pointer to a variable to receive the loudness gain. 355 * @return Function result code: 356 * {@link AUDIOSTREAM_SUCCESS} If the execution is successful. 357 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM}: 358 * 1.The param of renderer is nullptr; 359 * 2.The param of loudnessGain is nullptr. 360 * @since 20 361 */ 362 OH_AudioStream_Result OH_AudioRenderer_GetLoudnessGain(OH_AudioRenderer* renderer, float* loudnessGain); 363 364 /** 365 * Get Volume of current renderer. 366 * 367 * @since 12 368 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 369 * @param volume Pointer to a variable to receive the volume. 370 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 371 */ 372 OH_AudioStream_Result OH_AudioRenderer_GetVolume(OH_AudioRenderer* renderer, float* volume); 373 374 /** 375 * @brief Gets the underflow count on this stream. 376 * 377 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 378 * @param count Pointer to a variable to receive the underflow count number. 379 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 380 * @since 12 381 */ 382 OH_AudioStream_Result OH_AudioRenderer_GetUnderflowCount(OH_AudioRenderer* renderer, uint32_t* count); 383 384 /** 385 * @brief Query the channel layout of the renderer client. 386 * 387 * @since 12 388 * 389 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 390 * @param channelLayout Pointer to a variable to receive the channel layout 391 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 392 */ 393 OH_AudioStream_Result OH_AudioRenderer_GetChannelLayout(OH_AudioRenderer* renderer, 394 OH_AudioChannelLayout* channelLayout); 395 396 /** 397 * @brief Query current audio effect mode. 398 * 399 * @since 12 400 * 401 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 402 * @param effectMode Pointer to a variable to receive current audio effect mode 403 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 404 */ 405 OH_AudioStream_Result OH_AudioRenderer_GetEffectMode(OH_AudioRenderer* renderer, 406 OH_AudioStream_AudioEffectMode* effectMode); 407 408 /** 409 * @brief Set current audio effect mode. 410 * 411 * @since 12 412 * 413 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 414 * @param effectMode Audio effect mode that will be set for the stream 415 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 416 */ 417 OH_AudioStream_Result OH_AudioRenderer_SetEffectMode(OH_AudioRenderer* renderer, 418 OH_AudioStream_AudioEffectMode effectMode); 419 420 /** 421 * @brief Query the playback capture privacy of the renderer client. 422 * 423 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 424 * @param privacy The playback capture privacy of the renderer client. 425 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 426 * @since 12 427 */ 428 OH_AudioStream_Result OH_AudioRenderer_GetRendererPrivacy(OH_AudioRenderer* renderer, 429 OH_AudioStream_PrivacyType* privacy); 430 431 /* 432 * Set silent and mix with other stream for this stream. 433 * 434 * @since 12 435 * 436 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 437 * @param on The silent and mix with other stream status. 438 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 439 */ 440 OH_AudioStream_Result OH_AudioRenderer_SetSilentModeAndMixWithOthers( 441 OH_AudioRenderer* renderer, bool on); 442 443 /* 444 * Query silent and mix with other stream status for this stream. 445 * 446 * @since 12 447 * 448 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 449 * @param on Pointer to the silent and mix with other stream status. 450 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 451 */ 452 OH_AudioStream_Result OH_AudioRenderer_GetSilentModeAndMixWithOthers( 453 OH_AudioRenderer* renderer, bool* on); 454 455 /** 456 * @brief Temporarily changes the current audio device 457 * This function applys on audiorenderers whose StreamUsage are 458 * STREAM_USAGE_VOICE_COMMUNICATIN/STREAM_USAGE_VIDEO_COMMUNICATION/STREAM_USAGE_VOICE_MESSAGE. 459 * Setting the device will ony takes effect if no other accessory such as headphoes are in use. 460 * 461 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 462 * @param deviceType The target device. The available deviceTypes are: 463 * EARPIECE: Built-in earpiece 464 * SPEAKER: Built-in speaker 465 * DEFAULT: System default output device 466 * @return result code for this function. 467 * {@link #AUDIOSTREAM_SUCCESS} succeed in setting the default output device 468 * {@link #AUDIOSTREAM_ERROR_INVALID_PARAM}: 469 * 1.The param of renderer is nullptr; 470 * 2.The param of deviceType is not valid 471 * {@link #AUDIOSTREAM_ERROR_ILLEGAL_STATE} This audiorenderer can not reset the output device 472 * {@link #AUDIOSTREAM_ERROR_SYSTEM} system error when calling this function. 473 * @since 12 474 */ 475 OH_AudioStream_Result OH_AudioRenderer_SetDefaultOutputDevice( 476 OH_AudioRenderer* renderer, OH_AudioDevice_Type deviceType); 477 478 /** 479 * @brief Callback function of interrupt event on AudioRenderer. 480 * 481 * This function is similar with OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnInterruptEvent. 482 * 483 * @param renderer AudioRenderer where this callback occurs. 484 * @param userData User data which is passed by user. 485 * @param type Force type of this interrupt event. 486 * @param hint Hint of this interrupt event. 487 * @see OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnInterruptEvent. 488 * @since 18 489 */ 490 typedef void (*OH_AudioRenderer_OnInterruptCallback)(OH_AudioRenderer* renderer, void* userData, 491 OH_AudioInterrupt_ForceType type, OH_AudioInterrupt_Hint hint); 492 493 /** 494 * @brief Callback function of error on AudioRenderer. 495 * 496 * This function is similar with OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnError. 497 * 498 * @param renderer AudioRenderer where this callback occurs. 499 * @param userData User data which is passed by user. 500 * @param error Error while using AudioRenderer. 501 * @see OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnError 502 * @since 18 503 */ 504 typedef void (*OH_AudioRenderer_OnErrorCallback)(OH_AudioRenderer* renderer, void* userData, 505 OH_AudioStream_Result error); 506 507 /** 508 * @brief Gets audio renderer running status, check if it works in fast status. 509 * 510 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer. 511 * @param status Pointer to a variable to receive the status. 512 * @return 513 * {@link AUDIOSTREAM_SUCCESS} if the execution is successful. 514 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} the param of renderer is nullptr. 515 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} function called in invalid state, only available before release state. 516 * @since 20 517 */ 518 OH_AudioStream_Result OH_AudioRenderer_GetFastStatus(OH_AudioRenderer* renderer, 519 OH_AudioStream_FastStatus* status); 520 521 /** 522 * @brief Callback function of fast status change event for audio renderer. 523 * 524 * @param renderer Pointer to an audio renderer instance for which this callback occurs. 525 * @param userData Userdata which is passed by register. 526 * @param status Current fast status. 527 * @since 20 528 */ 529 typedef void (*OH_AudioRenderer_OnFastStatusChange)( 530 OH_AudioRenderer* renderer, 531 void* userData, 532 OH_AudioStream_FastStatus status 533 ); 534 535 #ifdef __cplusplus 536 } 537 #endif 538 #endif // NATIVE_AUDIORENDERER_H 539