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