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