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