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