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 Gets the underflow count on this stream. 287 * 288 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 289 * @param count Pointer to a variable to receive the underflow count number. 290 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 291 * @since 12 292 */ 293 OH_AudioStream_Result OH_AudioRenderer_GetUnderflowCount(OH_AudioRenderer* renderer, uint32_t* count); 294 295 /** 296 * @brief Set mark position on current renderer. Calling this function will overwrite the mark postion which has already 297 * set. 298 * 299 * @since 12 300 * 301 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 302 * @param samplePos Mark position in samples. 303 * @param callback Callback used when the samplePos has reached. 304 * @param userData User data which is passed by user. 305 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 306 */ 307 OH_AudioStream_Result OH_AudioRenderer_SetMarkPosition(OH_AudioRenderer* renderer, uint32_t samplePos, 308 OH_AudioRenderer_OnMarkReachedCallback callback, void* userData); 309 310 /** 311 * @brief Cancel mark which has set by {@link #OH_AudioRenderer_SetMarkPosition}. 312 * 313 * @since 12 314 * 315 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 316 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 317 */ 318 OH_AudioStream_Result OH_AudioRenderer_CancelMark(OH_AudioRenderer* renderer); 319 320 /** 321 * Set volume of current renderer. 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 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 327 */ 328 OH_AudioStream_Result OH_AudioRenderer_SetVolume(OH_AudioRenderer* renderer, float volume); 329 330 /** 331 * Changes the volume with ramp for a duration. 332 * 333 * @since 12 334 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 335 * @param volume Volume to set which changes from 0.0 to 1.0. 336 * @param durationMs Duration for volume ramp, in millisecond. 337 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 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 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 346 * @param volume Pointer to a variable to receive the volume. 347 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 348 */ 349 OH_AudioStream_Result OH_AudioRenderer_GetVolume(OH_AudioRenderer* renderer, float* volume); 350 351 /** 352 * @brief Query the channel layout of the renderer client. 353 * 354 * @since 12 355 * 356 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 357 * @param channelLayout Pointer to a variable to receive the channel layout 358 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 359 */ 360 OH_AudioStream_Result OH_AudioRenderer_GetChannelLayout(OH_AudioRenderer* renderer, 361 OH_AudioChannelLayout* channelLayout); 362 363 /** 364 * @brief Query current audio effect mode. 365 * 366 * @since 12 367 * 368 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 369 * @param effectMode Pointer to a variable to receive current audio effect mode 370 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 371 */ 372 OH_AudioStream_Result OH_AudioRenderer_GetEffectMode(OH_AudioRenderer* renderer, 373 OH_AudioStream_AudioEffectMode* effectMode); 374 375 /** 376 * @brief Set current audio effect mode. 377 * 378 * @since 12 379 * 380 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 381 * @param effectMode Audio effect mode that will be set for the stream 382 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 383 */ 384 OH_AudioStream_Result OH_AudioRenderer_SetEffectMode(OH_AudioRenderer* renderer, 385 OH_AudioStream_AudioEffectMode effectMode); 386 387 /** 388 * @brief Query the playback capture privacy of the renderer client. 389 * 390 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 391 * @param privacy The playback capture privacy of the renderer client. 392 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 393 * @since 12 394 */ 395 OH_AudioStream_Result OH_AudioRenderer_GetRendererPrivacy(OH_AudioRenderer* renderer, 396 OH_AudioStream_PrivacyType* privacy); 397 398 /* 399 * Set silent and mix with other stream for this stream. 400 * 401 * @since 12 402 * 403 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 404 * @param on The silent and mix with other stream status. 405 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 406 */ 407 OH_AudioStream_Result OH_AudioRenderer_SetSilentModeAndMixWithOthers( 408 OH_AudioRenderer* renderer, bool on); 409 410 /* 411 * Query silent and mix with other stream status for this stream. 412 * 413 * @since 12 414 * 415 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 416 * @param on Pointer to the silent and mix with other stream status. 417 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 418 */ 419 OH_AudioStream_Result OH_AudioRenderer_GetSilentModeAndMixWithOthers( 420 OH_AudioRenderer* renderer, bool* on); 421 422 /** 423 * @brief Temporarily changes the current audio device 424 * This function applys on audiorenderers whose StreamUsage are 425 * STREAM_USAGE_VOICE_COMMUNICATIN/STREAM_USAGE_VIDEO_COMMUNICATION/STREAM_USAGE_VOICE_MESSAGE. 426 * Setting the device will ony takes effect if no other accessory such as headphoes are in use. 427 * 428 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 429 * @param deviceType The target device. The available deviceTypes are: 430 * EARPIECE: Built-in earpiece 431 * SPEAKER: Built-in speaker 432 * DEFAULT: System default output device 433 * @return result code for this function. 434 * {@link #AUDIOSTREAM_SUCCESS} succeed in setting the default output device 435 * {@link #AUDIOSTREAM_ERROR_INVALID_PARAM}: 436 * 1.The param of renderer is nullptr; 437 * 2.The param of deviceType is not valid 438 * {@link #AUDIOSTREAM_ERROR_ILLEGAL_STATE} This audiorenderer can not reset the output device 439 * {@link #AUDIOSTREAM_ERROR_SYSTEM} system error when calling this function. 440 * @since 12 441 */ 442 OH_AudioStream_Result OH_AudioRenderer_SetDefaultOutputDevice( 443 OH_AudioRenderer* renderer, OH_AudioDevice_Type deviceType); 444 #ifdef __cplusplus 445 } 446 #endif 447 #endif // NATIVE_AUDIORENDERER_H 448