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