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 frame size in callback, it is a fixed length that the stream want to be filled for each callback. 223 * 224 * @since 10 225 * 226 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 227 * @param frameSize Pointer to a variable that will be set for the frame size. 228 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 229 */ 230 OH_AudioStream_Result OH_AudioRenderer_GetFrameSizeInCallback(OH_AudioRenderer* renderer, int32_t* frameSize); 231 232 /* 233 * Query the playback speed of the stream client 234 * 235 * @since 11 236 * 237 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 238 * @param speed Pointer to a variable to receive the playback speed. 239 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 240 */ 241 OH_AudioStream_Result OH_AudioRenderer_GetSpeed(OH_AudioRenderer* renderer, float* speed); 242 243 /* 244 * Set the playback speed of the stream client 245 * 246 * @since 11 247 * 248 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 249 * @param speed The playback speed, form 0.25 to 4.0. 250 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 251 */ 252 OH_AudioStream_Result OH_AudioRenderer_SetSpeed(OH_AudioRenderer* renderer, float speed); 253 254 /** 255 * @brief Gets the underflow count on this stream. 256 * 257 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 258 * @param count Pointer to a variable to receive the underflow count number. 259 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 260 * @since 12 261 */ 262 OH_AudioStream_Result OH_AudioRenderer_GetUnderflowCount(OH_AudioRenderer* renderer, uint32_t* count); 263 264 /** 265 * @brief Set mark position on current renderer. Calling this function will overwrite the mark postion which has already 266 * set. 267 * 268 * @since 12 269 * 270 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 271 * @param samplePos Mark position in samples. 272 * @param callback Callback used when the samplePos has reached. 273 * @param userData User data which is passed by user. 274 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 275 */ 276 OH_AudioStream_Result OH_AudioRenderer_SetMarkPosition(OH_AudioRenderer* renderer, uint32_t samplePos, 277 OH_AudioRenderer_OnMarkReachedCallback callback, void* userData); 278 279 /** 280 * @brief Cancel mark which has set by {@link #OH_AudioRenderer_SetMarkPosition}. 281 * 282 * @since 12 283 * 284 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 285 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 286 */ 287 OH_AudioStream_Result OH_AudioRenderer_CancelMark(OH_AudioRenderer* renderer); 288 289 /** 290 * Set volume of current renderer. 291 * 292 * @since 12 293 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 294 * @param volume Volume to set which changes from 0.0 to 1.0. 295 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 296 */ 297 OH_AudioStream_Result OH_AudioRenderer_SetVolume(OH_AudioRenderer* renderer, float volume); 298 299 /** 300 * Changes the volume with ramp for a duration. 301 * 302 * @since 12 303 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 304 * @param volume Volume to set which changes from 0.0 to 1.0. 305 * @param durationMs Duration for volume ramp, in millisecond. 306 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 307 */ 308 OH_AudioStream_Result OH_AudioRenderer_SetVolumeWithRamp(OH_AudioRenderer* renderer, float volume, int32_t durationMs); 309 310 /** 311 * Get Volume of current renderer. 312 * 313 * @since 12 314 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 315 * @param volume Pointer to a variable to receive the volume. 316 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 317 */ 318 OH_AudioStream_Result OH_AudioRenderer_GetVolume(OH_AudioRenderer* renderer, float* volume); 319 320 /** 321 * @brief Query the channel layout of the renderer client. 322 * 323 * @since 12 324 * 325 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 326 * @param channelLayout Pointer to a variable to receive the channel layout 327 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 328 */ 329 OH_AudioStream_Result OH_AudioRenderer_GetChannelLayout(OH_AudioRenderer* renderer, 330 OH_AudioChannelLayout* channelLayout); 331 332 /** 333 * @brief Query current audio effect mode. 334 * 335 * @since 12 336 * 337 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 338 * @param effectMode Pointer to a variable to receive current audio effect mode 339 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 340 */ 341 OH_AudioStream_Result OH_AudioRenderer_GetEffectMode(OH_AudioRenderer* renderer, 342 OH_AudioStream_AudioEffectMode* effectMode); 343 344 /** 345 * @brief Set current audio effect mode. 346 * 347 * @since 12 348 * 349 * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer() 350 * @param effectMode Audio effect mode that will be set for the stream 351 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 352 */ 353 OH_AudioStream_Result OH_AudioRenderer_SetEffectMode(OH_AudioRenderer* renderer, 354 OH_AudioStream_AudioEffectMode effectMode); 355 356 /** 357 * @brief Query the playback capture privacy of the renderer client. 358 * 359 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 360 * @param privacy The playback capture privacy of the renderer client. 361 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 362 * @since 12 363 */ 364 OH_AudioStream_Result OH_AudioRenderer_GetRendererPrivacy(OH_AudioRenderer* renderer, 365 OH_AudioStream_PrivacyType* privacy); 366 367 /* 368 * Set silent and mix with other stream for this stream. 369 * 370 * @since 12 371 * 372 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 373 * @param on The silent and mix with other stream status. 374 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 375 */ 376 OH_AudioStream_Result OH_AudioRenderer_SetSilentModeAndMixWithOthers( 377 OH_AudioRenderer* renderer, bool on); 378 379 /* 380 * Query silent and mix with other stream status for this stream. 381 * 382 * @since 12 383 * 384 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 385 * @param on Pointer to the silent and mix with other stream status. 386 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 387 */ 388 OH_AudioStream_Result OH_AudioRenderer_GetSilentModeAndMixWithOthers( 389 OH_AudioRenderer* renderer, bool* on); 390 391 /** 392 * @brief Temporarily changes the current audio device 393 * This function applys on audiorenderers whose StreamUsage are 394 * STREAM_USAGE_VOICE_COMMUNICATIN/STREAM_USAGE_VIDEO_COMMUNICATION/STREAM_USAGE_VOICE_MESSAGE. 395 * Setting the device will ony takes effect if no other accessory such as headphoes are in use. 396 * 397 * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer() 398 * @param deviceType The target device. The available deviceTypes are: 399 * EARPIECE: Built-in earpiece 400 * SPEAKER: Built-in speaker 401 * DEFAULT: System default output device 402 * @return result code for this function. 403 * {@link #AUDIOSTREAM_SUCCESS} succeed in setting the default output device 404 * {@link #AUDIOSTREAM_ERROR_INVALID_PARAM}: 405 * 1.The param of renderer is nullptr; 406 * 2.The param of deviceType is not valid 407 * {@link #AUDIOSTREAM_ERROR_ILLEGAL_STATE} This audiorenderer can not reset the output device 408 * {@link #AUDIOSTREAM_ERROR_SYSTEM} system error when calling this function. 409 * @since 12 410 */ 411 OH_AudioStream_Result OH_AudioRenderer_SetDefaultOutputDevice( 412 OH_AudioRenderer* renderer, OH_AudioDevice_Type deviceType); 413 #ifdef __cplusplus 414 } 415 #endif 416 #endif // NATIVE_AUDIORENDERER_H 417