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