1/* 2 * Copyright (c) 2022-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 HdiAudio 18 * @{ 19 * 20 * @brief Provides unified APIs for audio services to access audio drivers. 21 * 22 * An audio service can obtain an audio driver object or agent and then call APIs provided by this object or agent to 23 * access different types of audio devices based on the audio IDs, thereby obtaining audio information, 24 * subscribing to or unsubscribing from audio data, enabling or disabling an audio, 25 * setting the audio data reporting mode, and setting audio options such as the accuracy and measurement range. 26 * 27 * @since 4.0 28 * @version 1.0 29 */ 30 31package ohos.hdi.audio.v1_0; 32 33import ohos.hdi.audio.v1_0.AudioTypes; 34import ohos.hdi.audio.v1_0.IAudioCallback; 35 36/** 37 * @brief Provides capabilities for audio rendering, including controlling the rendering, setting audio attributes, 38 * scenes, and volume, obtaining hardware latency, and rendering audio frames. 39 * 40 * @since 4.0 41 * @version 1.0 42 */ 43interface IAudioRender { 44 /** 45 * @brief Obtains the estimated latency of the audio device driver. 46 * 47 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 48 * @param ms Indicates the pointer to the latency (in milliseconds) to be obtained. 49 * @return Returns <b>0</b> if the latency is obtained; returns a negative value otherwise. 50 */ 51 GetLatency([out] unsigned int ms); 52 53 /** 54 * @brief Writes a frame of output data (downlink data) into the audio driver for rendering. 55 * 56 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 57 * @param frame Indicates the pointer to the frame to write. 58 * @param requestBytes Indicates the size of the frame, in bytes. 59 * @param replyBytes Indicates the pointer to the actual length (in bytes) of the audio data to write. 60 * @return Returns <b>0</b> if the data is written successfully; returns a negative value otherwise. 61 */ 62 RenderFrame([in] byte[] frame, [out] unsigned long replyBytes); 63 64 /** 65 * @brief Obtains the last number of output audio frames. 66 * 67 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 68 * @param frames Indicates the pointer to the last number of output audio frames. 69 * @param time Indicates the pointer to the timestamp associated with the frame. 70 * @return Returns <b>0</b> if the last number is obtained; returns a negative value otherwise. 71 * @see RenderFrame 72 */ 73 GetRenderPosition([out] unsigned long frames, [out] struct AudioTimeStamp time); 74 75 /** 76 * @brief Sets the audio rendering speed. 77 * 78 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 79 * @param speed Indicates the rendering speed to set. 80 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 81 * @see GetRenderSpeed 82 */ 83 SetRenderSpeed([in] float speed); 84 85 /** 86 * @brief Obtains the current audio rendering speed. 87 * 88 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 89 * @param speed Indicates the pointer to the current rendering speed to obtain. 90 * @return Returns <b>0</b> if the speed is successfully obtained; returns a negative value otherwise. 91 * @see SetRenderSpeed 92 */ 93 GetRenderSpeed([out] float speed); 94 95 /** 96 * @brief Sets the channel mode for audio rendering. 97 * 98 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 99 * @param mode Indicates the channel mode to set. 100 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 101 * @see GetChannelMode 102 */ 103 SetChannelMode([in] enum AudioChannelMode mode); 104 105 /** 106 * @brief Obtains the current channel mode for audio rendering. 107 * 108 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 109 * @param mode Indicates the pointer to the channel mode to obtain. 110 * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise. 111 * @see SetChannelMode 112 */ 113 GetChannelMode([out] enum AudioChannelMode mode); 114 115 /** 116 * @brief Registers an audio callback that will be invoked during playback when buffer data writing or 117 * buffer drain is complete. 118 * 119 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 120 * @param callback Indicates the callback to register. 121 * @param cookie Indicates the pointer to the callback parameters. 122 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 123 * @see RegCallback 124 */ 125 RegCallback([in] IAudioCallback audioCallback, [in] byte cookie); 126 127 /** 128 * @brief Drains the buffer. 129 * 130 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 131 * @param type Indicates the pointer to the execution type of this function. For details, 132 * see {@link AudioDrainNotifyType}. 133 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 134 * @see RegCallback 135 */ 136 DrainBuffer([out] enum AudioDrainNotifyType type); 137 138 /** 139 * @brief query whether the vendor supports draining buffer 140 * 141 * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate. 142 * @param support indicates the state whether the vendor supports draining buffer. Value <b>true</b> means that 143 * the vendor supports, and <b>false</b> means the opposite. 144 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 145 * @see IsSupportsDrain 146 */ 147 IsSupportsDrain([out] boolean support); 148 149 /** 150 * @brief Checks whether the configuration of an audio scene is supported. 151 * 152 * @param handle Indicates the audio handle. 153 * @param scene Indicates the pointer to the descriptor of the audio scene. 154 * @param supported Indicates the pointer to the variable specifying whether the configuration is supported. 155 * Value <b>true</b> means that the configuration is supported, and <b>false</b> means the opposite. 156 * @return Returns <b>0</b> if the result is obtained; returns a negative value otherwise. 157 * @see SelectScene 158 */ 159 CheckSceneCapability([in] struct AudioSceneDescriptor scene, [out] boolean supported); 160 161 /** 162 * @brief Selects an audio scene. 163 * 164 * <ul> 165 * <li>To select a specific audio scene, you need to specify both the application scenario and output device. 166 * For example, to select a scene using a smartphone speaker as the output device, set <b>scene</b> according 167 * to the scenarios where the speaker is used. For example:</li> 168 * <ul> 169 * <li>For media playback, set the value to <b>media_speaker</b>.</li> 170 * <li>For a voice call, set the value to <b>voice_speaker</b>.</li> 171 * </ul> 172 * <li>To select only the application scenario, such as media playback, movie, or gaming, you can set 173 * <b>scene</b> to <b>media</b>, <b>movie</b>, or <b>game</b>, respectively.</li> 174 * <li>To select only the output device, such as media receiver, speaker, or headset, you can set 175 * <b>scene</b> to <b>receiver</b>, <b>speaker</b>, or <b>headset</b>, respectively.</li> 176 * </ul> 177 * @param handle Indicates the audio handle. 178 * @param scene Indicates the pointer to the descriptor of the audio scene to select. 179 * @return Returns <b>0</b> if the scene is selected successfully; returns a negative value otherwise. 180 * @see CheckSceneCapability 181 */ 182 SelectScene([in] struct AudioSceneDescriptor scene); 183 184 /** 185 * @brief Sets the mute operation for the audio. 186 * 187 * @param handle Indicates the audio handle. 188 * @param mute Specifies whether to mute the audio. Value <b>true</b> means to mute the audio, 189 * and <b>false</b> means the opposite. 190 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 191 * @see GetMute 192 */ 193 SetMute([in] boolean mute); 194 195 /** 196 * @brief Obtains the mute operation set for the audio. 197 * 198 * @param handle Indicates the audio handle. 199 * @param mute Indicates the pointer to the mute operation set for the audio. Value <b>true</b> means that 200 * the audio is muted, and <b>false</b> means the opposite. 201 * @return Returns <b>0</b> if the mute operation is obtained; returns a negative value otherwise. 202 * @see SetMute 203 */ 204 GetMute([out] boolean mute); 205 206 /** 207 * @brief Sets the audio volume. 208 * 209 * The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15, 210 * <b>0.0</b> indicates that the audio is muted, and <b>1.0</b> indicates the maximum volume level (15). 211 * 212 * @param handle Indicates the audio handle. 213 * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0. 214 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 215 * @see GetVolume 216 */ 217 SetVolume([in] float volume); 218 219 /** 220 * @brief Obtains the audio volume. 221 * 222 * @param handle Indicates the audio handle. 223 * @param volume Indicates the pointer to the volume to obtain. The value ranges from 0.0 to 1.0. 224 * @return Returns <b>0</b> if the volume is obtained; returns a negative value otherwise. 225 * @see SetVolume 226 */ 227 GetVolume([out] float volume); 228 229 /** 230 * @brief Obtains the range of the audio gain. 231 * 232 * The audio gain can be expressed in one of the following two ways (depending on the chip platform), 233 * corresponding to two types of value ranges: 234 * <ul> 235 * <li>Actual audio gain values, for example, ranging from -50 to 6 dB</li> 236 * <li>Float numbers ranging from 0.0 to 1.0, where <b>0.0</b> means to mute the audio, 237 * and <b>1.0</b> means the maximum gain value, for example, 6 dB</li> 238 * </ul> 239 * @param handle Indicates the audio handle. 240 * @param min Indicates the pointer to the minimum value of the range. 241 * @param max Indicates the pointer to the maximum value of the range. 242 * @return Returns <b>0</b> if the range is obtained; returns a negative value otherwise. 243 * @see GetGain 244 * @see SetGain 245 */ 246 GetGainThreshold([out] float min, [out] float max); 247 248 /** 249 * @brief Obtains the audio gain. 250 * 251 * @param handle Indicates the audio handle. 252 * @param gain Indicates the pointer to the audio gain. 253 * @return Returns <b>0</b> if the audio gain is obtained; returns a negative value otherwise. 254 * @see GetGainThreshold 255 * @see SetGain 256 */ 257 GetGain([out] float gain); 258 259 /** 260 * @brief Sets the audio gain. 261 * 262 * @param handle Indicates the audio handle. 263 * @param gain Indicates the audio gain to set. 264 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 265 * @see GetGainThreshold 266 * @see GetGain 267 */ 268 SetGain([in] float gain); 269 270 /** 271 * @brief Obtains the audio frame size, that is, the length (in bytes) of a frame. 272 * 273 * @param handle Indicates the audio handle. 274 * @param size Indicates the pointer to the audio frame size (in bytes). 275 * @return Returns <b>0</b> if the audio frame size is obtained; returns a negative value otherwise. 276 */ 277 GetFrameSize([out] unsigned long size); 278 279 /** 280 * @brief Obtains the number of audio frames in the audio buffer. 281 * 282 * @param handle Indicates the audio handle. 283 * @param count Indicates the pointer to the number of audio frames in the audio buffer. 284 * @return Returns <b>0</b> if the number of audio frames is obtained; returns a negative value otherwise. 285 */ 286 GetFrameCount([out] unsigned long count); 287 288 /** 289 * @brief Sets audio sampling attributes. 290 * 291 * @param handle Indicates the audio handle. 292 * @param attrs Indicates the pointer to the audio sampling attributes to set, such as the sampling rate, 293 * sampling precision, and channel. 294 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 295 * @see GetSampleAttributes 296 */ 297 SetSampleAttributes([in] struct AudioSampleAttributes attrs); 298 299 /** 300 * @brief Obtains audio sampling attributes. 301 * 302 * @param handle Indicates the audio handle. 303 * @param attrs Indicates the pointer to the audio sampling attributes, such as the sampling rate, 304 * sampling precision, and channel. 305 * @return Returns <b>0</b> if audio sampling attributes are obtained; returns a negative value otherwise. 306 * @see SetSampleAttributes 307 */ 308 GetSampleAttributes([out] struct AudioSampleAttributes attrs); 309 310 /** 311 * @brief Obtains the data channel ID of the audio. 312 * 313 * @param handle Indicates the audio handle. 314 * @param channelId Indicates the pointer to the data channel ID. 315 * @return Returns <b>0</b> if the data channel ID is obtained; returns a negative value otherwise. 316 */ 317 GetCurrentChannelId([out] unsigned int channelId); 318 319 /** 320 * @brief Sets extra audio parameters. 321 * 322 * @param handle Indicates the audio handle. 323 * @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters. 324 * The format is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 325 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 326 */ 327 SetExtraParams([in] String keyValueList); 328 329 /** 330 * @brief Obtains extra audio parameters. 331 * 332 * @param handle Indicates the audio handle. 333 * @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters. 334 * The format is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;). 335 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 336 */ 337 GetExtraParams([out] String keyValueList); 338 339 /** 340 * @brief Requests a mmap buffer. 341 * 342 * @param handle Indicates the audio handle. 343 * @param reqSize Indicates the size of the request mmap buffer. 344 * @param desc Indicates the pointer to the mmap buffer descriptor. 345 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 346 */ 347 ReqMmapBuffer([in] int reqSize, [out] struct AudioMmapBufferDescriptor desc); 348 349 /** 350 * @brief Obtains the read/write position of the current mmap buffer. 351 * 352 * @param handle Indicates the audio handle. 353 * @param frames Indicates the pointer to the frame where the read/write starts. 354 * @param time Indicates the pointer to the timestamp associated with the frame where the read/write starts. 355 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 356 */ 357 GetMmapPosition([out] unsigned long frames, [out] struct AudioTimeStamp time); 358 359 /** 360 * @brief Add the audio effect which the effectid indicated. 361 * 362 * @param handle Indicates the audio handle. 363 * @param effectid Indicates the audio effect instance identifier which is going to be added. 364 * @return Returns <b>0</b> if the audio effect were added succesffully; returns a negative value otherwise. 365 */ 366 AddAudioEffect([in] unsigned long effectid); 367 368 /** 369 * @brief Remove the audio effect which the effectid indicated. 370 * 371 * @param handle Indicates the audio handle. 372 * @param effectid Indicates the audio effect which is going to be removed. 373 * @return Returns <b>0</b> if the audio effect were removed succesffully; returns a negative value otherwise. 374 */ 375 RemoveAudioEffect([in] unsigned long effectid); 376 377 /** 378 * @brief Get the buffer size of render or capturer 379 * 380 * @param handle Indicates the audio handle. 381 * @param bufferSize Indicates the buffer size (in bytes) queried from the vendor 382 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 383 */ 384 GetFrameBufferSize([out] unsigned long bufferSize); 385 386 /** 387 * @brief Starts audio rendering or capturing. 388 * 389 * @param handle Indicates the audio handle. 390 * @return Returns <b>0</b> if the rendering or capturing is successfully started; 391 * returns a negative value otherwise. 392 * @see Stop 393 */ 394 Start(); 395 396 /** 397 * @brief Stops audio rendering or capturing. 398 * 399 * @param handle Indicates the audio handle. 400 * @return Returns <b>0</b> if the rendering or capturing is successfully stopped; 401 * returns a negative value otherwise. 402 * @see Start 403 */ 404 Stop(); 405 406 /** 407 * @brief Pauses audio rendering or capturing. 408 * 409 * @param handle Indicates the audio handle. 410 * @return Returns <b>0</b> if the rendering or capturing is successfully paused; 411 * returns a negative value otherwise. 412 * @see Resume 413 */ 414 Pause(); 415 416 /** 417 * @brief Resumes audio rendering or capturing. 418 * 419 * @param handle Indicates the audio handle. 420 * @return Returns <b>0</b> if the rendering or capturing is successfully resumed; 421 * returns a negative value otherwise. 422 * @see Pause 423 */ 424 Resume(); 425 426 /** 427 * @brief Flushes data in the audio buffer. 428 * 429 * @param handle Indicates the audio handle. 430 * @return Returns <b>0</b> if the flush is successful; returns a negative value otherwise. 431 */ 432 Flush(); 433 434 /** 435 * @brief Sets or cancels the standby mode of the audio device. 436 * 437 * @param handle Indicates the audio handle. 438 * @return Returns <b>0</b> if the device is set to standby mode; returns a positive value if the standby mode is 439 * canceled; returns a negative value if the setting fails. 440 */ 441 TurnStandbyMode(); 442 443 /** 444 * @brief Dumps information about the audio device. 445 * 446 * @param handle Indicates the audio handle. 447 * @param range Indicates the range of the device information to dump, which can be brief or full information. 448 * @param fd Indicates the file to which the device information will be dumped. 449 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 450 */ 451 AudioDevDump([in] int range, [in] int fd); 452 453 /** 454 * @brief Query whether the vendor support pause and resume. 455 * 456 * @param handle Indicates the audio handle. 457 * @param supportPause Indicates the state whether the vendor supports pausing. Value <b>true</b> means that 458 * the vendor supports, and <b>false</b> means the opposite. 459 * @param supportResume Indicates the state whether the vendor supports resuming. Value <b>true</b> means that 460 * the vendor supports, and <b>false</b> means the opposite. 461 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 462 * @see IsSupportsPauseAndResume 463 */ 464 IsSupportsPauseAndResume([out] boolean supportPause, [out] boolean supportResume); 465} 466