1 /*
2  * Copyright (c) 2021-2022 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 #ifndef AUDIO_RENDERER_H
17 #define AUDIO_RENDERER_H
18 
19 #include <vector>
20 #include <stddef.h>
21 #include <stdint.h>
22 #include <memory>
23 #include <cstring>
24 #include <timestamp.h>
25 #include <mutex>
26 #include "audio_effect.h"
27 
28 namespace OHOS {
29 namespace AudioStandard {
30 /**
31  * @brief Defines information about audio renderer parameters.
32  * @since 8
33  */
34 
35 struct AudioRendererParams {
36     /** Sample Format */
37     AudioSampleFormat sampleFormat = SAMPLE_S16LE;
38     /** Sampling rate */
39     AudioSamplingRate sampleRate = SAMPLE_RATE_8000;
40     /** Number of channels */
41     AudioChannel channelCount = MONO;
42     /** Encoding Type */
43     AudioEncodingType encodingType = ENCODING_PCM;
44     /** Channel Layout */
45     AudioChannelLayout channelLayout = CH_LAYOUT_UNKNOWN;
46 };
47 
48 class AudioRendererCallback {
49 public:
50     virtual ~AudioRendererCallback() = default;
51 
52     /**
53      * Called when an interrupt is received.
54      *
55      * @param interruptEvent Indicates the InterruptEvent information needed by client.
56      * For details, refer InterruptEvent struct in audio_info.h
57      * @since 8
58      */
59     virtual void OnInterrupt(const InterruptEvent &interruptEvent) = 0;
60 
61     /**
62      * Called when renderer state is updated.
63      *
64      * @param state Indicates updated state of the renderer.
65      * For details, refer RendererState enum.
66      */
67     virtual void OnStateChange(const RendererState state, const StateChangeCmdType cmdType = CMD_FROM_CLIENT) = 0;
68 };
69 
70 class RendererPositionCallback {
71 public:
72     virtual ~RendererPositionCallback() = default;
73 
74     /**
75      * Called when the requested frame number is reached.
76      *
77      * @param framePosition requested frame position.
78      * @since 8
79      */
80     virtual void OnMarkReached(const int64_t &framePosition) = 0;
81 };
82 
83 class RendererPeriodPositionCallback {
84 public:
85     virtual ~RendererPeriodPositionCallback() = default;
86 
87     /**
88      * Called when the requested frame count is written.
89      *
90      * @param frameCount requested frame frame count for callback.
91      * @since 8
92      */
93     virtual void OnPeriodReached(const int64_t &frameNumber) = 0;
94 };
95 
96 class AudioRendererWriteCallback {
97 public:
98     virtual ~AudioRendererWriteCallback() = default;
99 
100     /**
101      * Called when buffer to be enqueued.
102      *
103      * @param length Indicates requested buffer length.
104      * @since 8
105      */
106     virtual void OnWriteData(size_t length) = 0;
107 };
108 
109 class AudioRendererFirstFrameWritingCallback {
110 public:
111     virtual ~AudioRendererFirstFrameWritingCallback() = default;
112     /**
113      * Called when first buffer to be enqueued.
114      */
115     virtual void OnFirstFrameWriting(uint64_t latency) = 0;
116 };
117 
118 class AudioRendererDeviceChangeCallback {
119 public:
120     virtual ~AudioRendererDeviceChangeCallback() = default;
121 
122     /**
123      * Called when renderer device is updated.
124      *
125      * @param state Indicates updated device of the renderer.
126      * since 10
127      */
128     virtual void OnStateChange(const DeviceInfo &deviceInfo) = 0;
129     virtual void RemoveAllCallbacks() = 0;
130 };
131 
132 class AudioRendererOutputDeviceChangeCallback {
133 public:
134     virtual ~AudioRendererOutputDeviceChangeCallback() = default;
135 
136     /**
137      * Called when the output device of an autio renderer changed.
138      *
139      * @param Audio device descriptors after change.
140      * @param Audio stream device change reason.
141      * since 11
142      */
143     virtual void OnOutputDeviceChange(const DeviceInfo &deviceInfo, const AudioStreamDeviceChangeReason reason) = 0;
144 };
145 
146 class AudioRendererErrorCallback {
147 public:
148     virtual ~AudioRendererErrorCallback() = default;
149 
150     /**
151      * Called when an unrecoverable exception occurs in the renderer
152      *
153      * @param errorCode Indicates error code of the exception.
154      * since 10
155      */
156     virtual void OnError(AudioErrors errorCode) = 0;
157 };
158 
159 /**
160  * @brief Provides functions for applications to implement audio rendering.
161  * @since 8
162  */
163 class AudioRenderer {
164 public:
165     static int32_t CheckMaxRendererInstances();
166 
167     /**
168      * @brief create renderer instance.
169      *
170      * @param audioStreamType The audio streamtype to be created.
171      * refer AudioStreamType in audio_info.h.
172      * @return Returns unique pointer to the AudioRenderer object
173      * @since 8
174     */
175     static std::unique_ptr<AudioRenderer> Create(AudioStreamType audioStreamType);
176 
177     /**
178      * @brief create renderer instance.
179      *
180      * @param audioStreamType The audio streamtype to be created.
181      * refer AudioStreamType in audio_info.h.
182      * @param appInfo Originating application's uid and token id can be passed here
183      * @return Returns unique pointer to the AudioRenderer object
184      * @since 9
185     */
186     static std::unique_ptr<AudioRenderer> Create(AudioStreamType audioStreamType, const AppInfo &appInfo);
187 
188     /**
189      * @brief create renderer instance.
190      *
191      * @param rendererOptions The audio renderer configuration to be used while creating renderer instance.
192      * refer AudioRendererOptions in audio_info.h.
193      * @return Returns unique pointer to the AudioRenderer object
194      * @since 8
195     */
196     static std::unique_ptr<AudioRenderer> Create(const AudioRendererOptions &rendererOptions);
197 
198     /**
199      * @brief create renderer instance.
200      *
201      * @param rendererOptions The audio renderer configuration to be used while creating renderer instance.
202      * refer AudioRendererOptions in audio_info.h.
203      * @param appInfo Originating application's uid and token id can be passed here
204      * @return Returns unique pointer to the AudioRenderer object
205      * @since 9
206     */
207     static std::unique_ptr<AudioRenderer> Create(const AudioRendererOptions &options, const AppInfo &appInfo);
208 
209     /**
210      * @brief create renderer instance.
211      *
212      * @param cachePath Application cache path
213      * @param rendererOptions The audio renderer configuration to be used while creating renderer instance.
214      * refer AudioRendererOptions in audio_info.h.
215      * @return Returns unique pointer to the AudioRenderer object
216      * @since 8
217     */
218     static std::unique_ptr<AudioRenderer> Create(const std::string cachePath,
219         const AudioRendererOptions &rendererOptions);
220 
221     /**
222      * @brief create renderer instance.
223      *
224      * @param cachePath Application cache path
225      * @param rendererOptions The audio renderer configuration to be used while creating renderer instance.
226      * refer AudioRendererOptions in audio_info.h.
227      * @param appInfo Originating application's uid and token id can be passed here
228      * @return Returns unique pointer to the AudioRenderer object
229      * @since 9
230     */
231     static std::unique_ptr<AudioRenderer> Create(const std::string cachePath,
232         const AudioRendererOptions &rendererOptions, const AppInfo &appInfo);
233 
234     /**
235      * @brief Sets audio privacy type.
236      *
237      * @param privacyType Indicates information about audio privacy type. For details, see
238      * {@link AudioPrivacyType}.
239      * @since 10
240      */
241     virtual void SetAudioPrivacyType(AudioPrivacyType privacyType) = 0;
242 
243     /**
244      * @brief Get audio privacy type.
245      *
246      * @return Return the render privacy type.
247      * @since 12
248      */
249     virtual AudioPrivacyType GetAudioPrivacyType() = 0;
250 
251     /**
252      * @brief Sets audio renderer parameters.
253      *
254      * @param params Indicates information about audio renderer parameters to set. For details, see
255      * {@link AudioRendererParams}.
256      * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined
257      * in {@link audio_errors.h} otherwise.
258      * @since 8
259      */
260     virtual int32_t SetParams(const AudioRendererParams params) = 0;
261 
262     /**
263      * @brief Registers the renderer callback listener.
264      * (1)If using old SetParams(const AudioCapturerParams params) API,
265      *    this API must be called immediately after SetParams.
266      * (2) Else if using Create(const AudioRendererOptions &rendererOptions),
267      *    this API must be called immediately after Create.
268      *
269      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
270      * defined in {@link audio_errors.h} otherwise.
271      * @since 8
272      */
273     virtual int32_t SetRendererCallback(const std::shared_ptr<AudioRendererCallback> &callback) = 0;
274 
275     /**
276      * @brief Obtains audio renderer parameters.
277      *
278      * This function can be called after {@link SetParams} is successful.
279      *
280      * @param params Indicates information about audio renderer parameters. For details, see
281      * {@link AudioRendererParams}.
282      * @return Returns {@link SUCCESS} if the parameter information is successfully obtained; returns an error code
283      * defined in {@link audio_errors.h} otherwise.
284      * @since 8
285      */
286     virtual int32_t GetParams(AudioRendererParams &params) const = 0;
287 
288     /**
289      * @brief Obtains audio renderer information.
290      *
291      * This function can be called after {@link Create} is successful.
292      *
293      * @param rendererInfo Indicates information about audio renderer. For details, see
294      * {@link AudioRendererInfo}.
295      * @return Returns {@link SUCCESS} if the parameter information is successfully obtained; returns an error code
296      * defined in {@link audio_errors.h} otherwise.
297      * @since 8
298      */
299     virtual int32_t GetRendererInfo(AudioRendererInfo &rendererInfo) const = 0;
300 
301     /**
302      * @brief Obtains renderer stream information.
303      *
304      * This function can be called after {@link Create} is successful.
305      *
306      * @param streamInfo Indicates information about audio renderer. For details, see
307      * {@link AudioStreamInfo}.
308      * @return Returns {@link SUCCESS} if the parameter information is successfully obtained; returns an error code
309      * defined in {@link audio_errors.h} otherwise.
310      * @since 8
311      */
312     virtual int32_t GetStreamInfo(AudioStreamInfo &streamInfo) const = 0;
313 
314     /**
315      * @brief Starts audio rendering.
316      *
317      * @return Returns <b>true</b> if the rendering is successfully started; returns <b>false</b> otherwise.
318      * @since 10
319      */
320     virtual bool Start(StateChangeCmdType cmdType = CMD_FROM_CLIENT) = 0;
321 
322     /**
323      * @brief Writes audio data.
324      * * This API cannot be used if render mode is RENDER_MODE_CALLBACK.
325      *
326      * @param buffer Indicates the pointer to the buffer which contains the audio data to be written.
327      * @param bufferSize Indicates the size of the buffer which contains audio data to be written, in bytes.
328      * @return Returns the size of the audio data written to the device. The value ranges from <b>0</b> to
329      * <b>bufferSize</b>. If the write fails, one of the following error codes is returned.
330      * <b>ERR_INVALID_PARAM</b>: The input parameter is incorrect.
331      * <b>ERR_ILLEGAL_STATE</b>: The <b>AudioRenderer</b> instance is not initialized.
332      * <b>ERR_INVALID_WRITE</b>: The written audio data size is < 0.
333      * <b>ERR_WRITE_FAILED</b>: The audio data write failed .
334      * @since 8
335      */
336     virtual int32_t Write(uint8_t *buffer, size_t bufferSize) = 0;
337 
338     /**
339      * @brief Writes audio PCM data and associated metadata.
340      *
341      * Note: This function is not available when the renderer is set to RENDER_MODE_CALLBACK.
342      * It should be used only with AUDIOVIVID encoding type.
343      *
344      * @param pcmBuffer Pointer to the PCM data buffer to be written.
345      * @param pcmBufferSize Size of the PCM data buffer, in bytes.
346 	 * The buffer must exactly contain 1024 samples, which is the length of one frame.
347      * @param metaBuffer Pointer to the metadata buffer to be written.
348      * @param metaBufferSize Size of the metadata buffer, in bytes.
349 	 * The buffer must exactly contain one metadata, which matches pcm buffer.
350      * @return The number of bytes successfully written, ranging from 0 to pcmBufferSize.
351      * If the operation fails, an error code is returned:
352      * - ERR_INVALID_PARAM: The input parameters are invalid.
353      * - ERR_ILLEGAL_STATE: The AudioRenderer instance has not been initialized.
354      * - ERR_INVALID_WRITE: The size of the audio data to write is negative.
355      * - ERR_WRITE_FAILED: Writing the audio data failed.
356      * @since 11
357      */
358     virtual int32_t Write(uint8_t *pcmBuffer, size_t pcmBufferSize, uint8_t *metaBuffer, size_t metaBufferSize) = 0;
359 
360     /**
361      * @brief Obtains the audio renderer state.
362      *
363      * @return Returns the audio renderer state defined in {@link RendererState}.
364      * @since 8
365      */
366     virtual RendererState GetStatus() const = 0;
367 
368     /**
369      * @brief Obtains the timestamp.
370      *
371      * @param timestamp Indicates a {@link Timestamp} instance reference provided by the caller.
372      * @param base Indicates the time base, which can be {@link Timestamp.Timestampbase#BOOTTIME} or
373      * {@link Timestamp.Timestampbase#MONOTONIC}.
374      * @return Returns <b>true</b> if the timestamp is successfully obtained; returns <b>false</b> otherwise.
375      * @since 8
376      */
377     virtual bool GetAudioTime(Timestamp &timestamp, Timestamp::Timestampbase base) const = 0;
378 
379     /**
380      * @brief Obtains the position info.
381      *
382      * @param timestamp Indicates a {@link Timestamp} instance reference provided by the caller.
383      * @param base Indicates the time base, which can be {@link Timestamp.Timestampbase#BOOTTIME} or
384      * {@link Timestamp.Timestampbase#MONOTONIC}.
385      * @return Returns <b>true</b> if the timestamp is successfully obtained; returns <b>false</b> otherwise.
386      * @since 11
387      */
388     virtual bool GetAudioPosition(Timestamp &timestamp, Timestamp::Timestampbase base) const = 0;
389 
390     /**
391      * @brief Obtains the latency in microseconds.
392      *
393      * @param latency Indicates the reference variable into which latency value will be written.
394      * @return Returns {@link SUCCESS} if latency is successfully obtained, returns an error code
395      * defined in {@link audio_errors.h} otherwise.
396      * @since 8
397      */
398     virtual int32_t GetLatency(uint64_t &latency) const = 0;
399 
400     /**
401      * @brief drain renderer buffer.
402      *
403      * @return Returns <b>true</b> if the buffer is successfully drained; returns <b>false</b> otherwise.
404      * @since 8
405      */
406     virtual bool Drain() const = 0;
407 
408     /**
409      * @brief flush renderer stream.
410      *
411      * @return Returns <b>true</b> if the object is successfully flushed; returns <b>false</b> otherwise.
412      * @since 8
413      */
414     virtual bool Flush() const = 0;
415 
416     /**
417      * @brief Pauses audio rendering transitent.
418      *
419      * @return Returns <b>true</b> if the rendering is successfully Paused; returns <b>false</b> otherwise.
420      * @since 10
421      */
422     virtual bool PauseTransitent(StateChangeCmdType cmdType = CMD_FROM_CLIENT) = 0;
423 
424     /**
425      * @brief Pauses audio rendering.
426      *
427      * @return Returns <b>true</b> if the rendering is successfully Paused; returns <b>false</b> otherwise.
428      * @since 10
429      */
430     virtual bool Pause(StateChangeCmdType cmdType = CMD_FROM_CLIENT) = 0;
431 
432     /**
433      * @brief Stops audio rendering.
434      *
435      * @return Returns <b>true</b> if the rendering is successfully stopped; returns <b>false</b> otherwise.
436      * @since 8
437      */
438     virtual bool Stop() = 0;
439 
440     /**
441      * @brief Releases a local <b>AudioRenderer</b> object.
442      *
443      * @return Returns <b>true</b> if the object is successfully released; returns <b>false</b> otherwise.
444      * @since 8
445      */
446     virtual bool Release() = 0;
447 
448     /**
449      * @brief Obtains a reasonable minimum buffer size for rendering, however, the renderer can
450      *        accept other write sizes as well.
451      *
452      * @param bufferSize Indicates the reference variable into which buffer size value will be written.
453      * @return Returns {@link SUCCESS} if bufferSize is successfully obtained; returns an error code
454      * defined in {@link audio_errors.h} otherwise.
455      * @since 8
456      */
457     virtual int32_t GetBufferSize(size_t &bufferSize) const = 0;
458 
459     /**
460      * @brief Obtains the renderer stream id.
461      *
462      * @param sessionId Indicates the reference variable into which stream id value will be written.
463      * @return Returns {@link SUCCESS} if stream id is successfully obtained; returns an error code
464      * defined in {@link audio_errors.h} otherwise.
465      * @since 10
466      */
467     virtual int32_t GetAudioStreamId(uint32_t &sessionID) const = 0;
468 
469     /**
470      * @brief Obtains the number of frames required in the current condition, in bytes per sample.
471      *
472      * @param frameCount Indicates the reference variable in which framecount will be written
473      * @return Returns {@link SUCCESS} if frameCount is successfully obtained; returns an error code
474      * defined in {@link audio_errors.h} otherwise.
475      * @since 8
476      */
477     virtual int32_t GetFrameCount(uint32_t &frameCount) const = 0;
478 
479     /**
480      * @brief Set audio renderer descriptors
481      *
482      * @param audioRendererDesc Audio renderer descriptor
483      * @return Returns {@link SUCCESS} if attribute is successfully set; returns an error code
484      * defined in {@link audio_errors.h} otherwise.
485      * @since 8
486      */
487     virtual int32_t SetAudioRendererDesc(AudioRendererDesc audioRendererDesc) = 0;
488 
489     /**
490      * @brief Update the stream type
491      *
492      * @param audioStreamType Audio stream type
493      * @return Returns {@link SUCCESS} if volume is successfully set; returns an error code
494      * defined in {@link audio_errors.h} otherwise.
495      * @since 8
496      */
497     virtual int32_t SetStreamType(AudioStreamType audioStreamType) = 0;
498 
499     /**
500      * @brief Set the track volume
501      *
502      * @param volume The volume to be set for the current track.
503      * @return Returns {@link SUCCESS} if volume is successfully set; returns an error code
504      * defined in {@link audio_errors.h} otherwise.
505      * @since 8
506      */
507     virtual int32_t SetVolume(float volume) const = 0;
508 
509     /**
510      * @brief Obtains the current track volume
511      *
512      * @return Returns current track volume
513      * @since 8
514      */
515     virtual float GetVolume() const = 0;
516 
517     /**
518      * @brief Set the render rate
519      *
520      * @param renderRate The rate at which the stream needs to be rendered.
521      * @return Returns {@link SUCCESS} if render rate is successfully set; returns an error code
522      * defined in {@link audio_errors.h} otherwise.
523      * @since 8
524      */
525     virtual int32_t SetRenderRate(AudioRendererRate renderRate) const = 0;
526 
527     /**
528      * @brief Obtains the current render rate
529      *
530      * @return Returns current render rate
531      * @since 8
532      */
533     virtual AudioRendererRate GetRenderRate() const = 0;
534 
535     /**
536      * @brief Set the render sampling rate
537      *
538      * @param sampleRate The sample rate at which the stream needs to be rendered.
539      * @return Returns {@link SUCCESS} if render rate is successfully set; returns an error code
540      * defined in {@link audio_errors.h} otherwise.
541      * @since 10
542      */
543     virtual int32_t SetRendererSamplingRate(uint32_t sampleRate) const = 0;
544 
545     /**
546      * @brief Obtains the current render samplingrate
547      *
548      * @return Returns current render samplingrate
549      * @since 10
550      */
551     virtual uint32_t GetRendererSamplingRate() const = 0;
552 
553     /**
554      * @brief Registers the renderer position callback listener
555      *
556      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
557      * defined in {@link audio_errors.h} otherwise.
558      * @since 8
559      */
560     virtual int32_t SetRendererPositionCallback(int64_t markPosition,
561         const std::shared_ptr<RendererPositionCallback> &callback) = 0;
562 
563     /**
564      * @brief Unregisters the renderer position callback listener
565      * @since 8
566      *
567      */
568     virtual void UnsetRendererPositionCallback() = 0;
569 
570     /**
571      * @brief Registers the renderer period position callback listener
572      *
573      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
574      * defined in {@link audio_errors.h} otherwise.
575      * @since 8
576      */
577     virtual int32_t SetRendererPeriodPositionCallback(int64_t frameNumber,
578         const std::shared_ptr<RendererPeriodPositionCallback> &callback) = 0;
579 
580     /**
581      * @brief Unregisters the renderer period position callback listener
582      *
583      * @since 8
584      */
585     virtual void UnsetRendererPeriodPositionCallback() = 0;
586 
587     /**
588      * @brief set the buffer duration for renderer, minimum buffer duration is 5msec
589      *         maximum is 20msec
590      *
591      * @param bufferDuration  Indicates a buffer duration to be set for renderer
592      * @return Returns {@link SUCCESS} if bufferDuration is successfully set; returns an error code
593      * defined in {@link audio_errors.h} otherwise.
594      * @since 8
595      */
596     virtual int32_t SetBufferDuration(uint64_t bufferDuration) const = 0;
597 
598     /**
599      * @brief Obtains the formats supported by renderer.
600      *
601      * @return Returns vector with supported formats.
602      * @since 8
603      */
604     static std::vector<AudioSampleFormat> GetSupportedFormats();
605 
606     /**
607      * @brief Obtains the SupportedSamplingRates supported by renderer.
608      *
609      * @return Returns vector with supported SupportedSamplingRates.
610      * @since 8
611      */
612     static std::vector<AudioSamplingRate> GetSupportedSamplingRates();
613 
614     /**
615      * @brief Obtains the channels supported by renderer.
616      *
617      * @return Returns vector with supported channels.
618      * @since 8
619      */
620     static std::vector<AudioChannel> GetSupportedChannels();
621 
622     /**
623      * @brief Obtains the encoding types supported by renderer.
624      *
625      * @return Returns vector with supported encoding types.
626      * @since 8
627      */
628     static std::vector<AudioEncodingType> GetSupportedEncodingTypes();
629 
630     /**
631      * @brief Sets the render mode. By default the mode is RENDER_MODE_NORMAL.
632      * This API is needs to be used only if RENDER_MODE_CALLBACK is required.
633      *
634      * * @param renderMode The mode of render.
635      * @return  Returns {@link SUCCESS} if render mode is successfully set; returns an error code
636      * defined in {@link audio_errors.h} otherwise.
637      * @since 8
638      */
639     virtual int32_t SetRenderMode(AudioRenderMode renderMode) = 0;
640 
641     /**
642      * @brief Obtains the render mode.
643      *
644      * @return  Returns current render mode.
645      * @since 8
646      */
647     virtual AudioRenderMode GetRenderMode() const = 0;
648 
649     /**
650      * @brief Registers the renderer write callback listener.
651      * This API should only be used if RENDER_MODE_CALLBACK is needed.
652      *
653      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
654      * defined in {@link audio_errors.h} otherwise.
655      * @since 8
656      */
657     virtual int32_t SetRendererWriteCallback(const std::shared_ptr<AudioRendererWriteCallback> &callback) = 0;
658 
659     virtual int32_t SetRendererFirstFrameWritingCallback(
660         const std::shared_ptr<AudioRendererFirstFrameWritingCallback> &callback) = 0;
661 
662     /**
663      * @brief Gets the BufferDesc to fill the data.
664      * This API should only be used if RENDER_MODE_CALLBACK is needed.
665      *
666      * @param bufDesc Indicates the buffer descriptor in which data will filled.
667      * refer BufferQueueState in audio_info.h.
668      * @return Returns {@link SUCCESS} if bufDesc is successfully obtained; returns an error code
669      * defined in {@link audio_errors.h} otherwise.
670      * @since 8
671      */
672     virtual int32_t GetBufferDesc(BufferDesc &bufDesc) const = 0;
673 
674     /**
675      * @brief Enqueues the buffer to the bufferQueue.
676      * This API should only be used if RENDER_MODE_CALLBACK is needed.
677      *
678      * @param bufDesc Indicates the buffer descriptor in which buffer data will filled.
679      * refer BufferQueueState in audio_info.h.
680      * @return Returns {@link SUCCESS} if bufDesc is successfully enqued; returns an error code
681      * defined in {@link audio_errors.h} otherwise.
682      * @since 8
683      */
684     virtual int32_t Enqueue(const BufferDesc &bufDesc) const = 0;
685 
686     /**
687      * @brief Clears the bufferQueue.
688      * This API should only be used if RENDER_MODE_CALLBACK is needed.
689      *
690      * @return Returns {@link SUCCESS} if successful; returns an error code
691      * defined in {@link audio_errors.h} otherwise.
692      * @since 8
693      */
694     virtual int32_t Clear() const = 0;
695 
696     /**
697      * @brief Obtains the current state of bufferQueue.
698      * This API should only be used if RENDER_MODE_CALLBACK is needed.
699      *
700      * @param bufDesc Indicates the bufState reference in which state will be obtained.
701      * refer BufferQueueState in audio_info.h.
702      * @return Returns {@link SUCCESS} if bufState is successfully obtained; returns an error code
703      * defined in {@link audio_errors.h} otherwise.
704      * @since 8
705      */
706     virtual int32_t GetBufQueueState(BufferQueueState &bufState) const = 0;
707 
708     /**
709      * @brief Set the application cache path to access the application resources
710      *
711      * @param cachePath Indicates application cache path.
712      * @return none
713      * @since 8
714      */
715     virtual void SetApplicationCachePath(const std::string cachePath) = 0;
716 
717     /**
718      * @brief Set interrupt mode.
719      *
720      * @param mode The interrupt mode.
721      * @return none
722      * @since 9
723      */
724     virtual void SetInterruptMode(InterruptMode mode) = 0;
725 
726     /**
727      * @brief Set parallel play flag (only for sound pool)
728      *
729      * @param parallelPlayFlag Indicates whether the audio renderer can play in parallel with other stream.
730      * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined
731      * in {@link audio_errors.h} otherwise.
732      * @since 10
733      */
734     virtual int32_t SetParallelPlayFlag(bool parallelPlayFlag) = 0;
735 
736     /**
737      * @brief Set volume discount factor.
738      *
739      * @param volume Adjustment percentage.
740      * @return Whether the operation is effective
741      * @since 9
742      */
743     virtual int32_t SetLowPowerVolume(float volume) const = 0;
744 
745     /**
746      * @brief Get volume discount factor.
747      *
748      * @param none.
749      * @return volume adjustment percentage.
750      * @since 9
751      */
752     virtual float GetLowPowerVolume() const = 0;
753 
754     /**
755      * @brief Set Stream of Renderer offload allowed.
756      *
757      * @param isAllowed offload allowed.
758      * @return Returns {@link SUCCESS} if setting is successful; returns an error code
759      * defined in {@link audio_errors.h} otherwise.
760      * @since 12
761      */
762     virtual int32_t SetOffloadAllowed(bool isAllowed) = 0;
763 
764     /**
765      * @brief Set Stream of Renderer into specified offload state.
766      *
767      * @param state power state.
768      * @param isAppBack app state.
769      * @return Returns {@link SUCCESS} if setting is successful; returns an error code
770      * defined in {@link audio_errors.h} otherwise.
771      * @since 10
772      */
773     virtual int32_t SetOffloadMode(int32_t state, bool isAppBack) const = 0;
774 
775     /**
776      * @brief Set Stream of Renderer out of offload state.
777      *
778      * @return Returns {@link SUCCESS} if unsetting is successful; returns an error code
779      * defined in {@link audio_errors.h} otherwise.
780      * @since 10
781      */
782     virtual int32_t UnsetOffloadMode() const = 0;
783 
784     /**
785      * @brief Get single stream volume.
786      *
787      * @param none.
788      * @return single stream volume.
789      * @since 9
790      */
791     virtual float GetSingleStreamVolume() const = 0;
792 
793     /**
794      * @brief Gets the min volume this stream can set.
795      *
796      * @param none.
797      * @return min stream volume.
798      * @since 10
799      */
800     virtual float GetMinStreamVolume() const = 0;
801 
802     /**
803      * @brief Gets the max volume this stream can set.
804      *
805      * @param none.
806      * @return max stream volume.
807      * @since 10
808      */
809     virtual float GetMaxStreamVolume() const = 0;
810 
811     /**
812      * @brief Get underflow count.
813      *
814      * @param none.
815      * @return underflow count.
816      * @since 10
817      */
818     virtual uint32_t GetUnderflowCount() const = 0;
819 
820     /**
821      * @brief Get deviceInfo
822      *
823      * @param deviceInfo.
824      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
825      * defined in {@link audio_errors.h} otherwise.
826      * @since 10
827     */
828     virtual int32_t GetCurrentOutputDevices(DeviceInfo &deviceInfo) const = 0;
829 
830     /**
831      * @brief Gets the audio effect mode.
832      *
833      * @return  Returns current audio effect mode.
834      * @since 10
835      */
836     virtual AudioEffectMode GetAudioEffectMode() const = 0;
837 
838     /**
839      * @brief Gets the audio frame size that has been written.
840      *
841      * @return Returns the audio frame size that has been written.
842      */
843     virtual int64_t GetFramesWritten() const = 0;
844 
845     /**
846      * @brief Sets the audio effect mode.
847      *
848      * * @param effectMode The audio effect mode at which the stream needs to be rendered.
849      * @return  Returns {@link SUCCESS} if audio effect mode is successfully set; returns an error code
850      * defined in {@link audio_errors.h} otherwise.
851      * @since 10
852      */
853     virtual int32_t SetAudioEffectMode(AudioEffectMode effectMode) const = 0;
854 
855     /**
856      * @brief Registers the renderer error event callback listener.
857      *
858      * @param errorCallback Error callback pointer
859      * @since 10
860      */
861     virtual void SetAudioRendererErrorCallback(std::shared_ptr<AudioRendererErrorCallback> errorCallback) = 0;
862 
863     virtual int32_t RegisterOutputDeviceChangeWithInfoCallback(
864         const std::shared_ptr<AudioRendererOutputDeviceChangeCallback> &callback) = 0;
865 
866     virtual int32_t UnregisterOutputDeviceChangeWithInfoCallback() = 0;
867 
868     virtual int32_t UnregisterOutputDeviceChangeWithInfoCallback(
869         const std::shared_ptr<AudioRendererOutputDeviceChangeCallback> &callback) = 0;
870 
871     /**
872      * @brief Register audio policy service died callback.
873      *
874      * @param clientPid client PID
875      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
876      * defined in {@link audio_errors.h} otherwise.
877      * @since 10
878      */
879     virtual int32_t RegisterAudioPolicyServerDiedCb(const int32_t clientPid,
880         const std::shared_ptr<AudioRendererPolicyServiceDiedCallback> &callback) = 0;
881 
882     /**
883      * @brief Unregister audio policy service died callback.
884      *
885      * @param clientPid client PID
886      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
887      * defined in {@link audio_errors.h} otherwise.
888      * @since 10
889      */
890     virtual int32_t UnregisterAudioPolicyServerDiedCb(const int32_t clientPid) = 0;
891 
892     /**
893      * @brief Sets channel blend mode for audio stream.
894      *
895      * @param Channel blend mode
896      * @since 11
897      */
898     virtual int32_t SetChannelBlendMode(ChannelBlendMode blendMode) = 0;
899 
900     /**
901      * @brief Changes the volume with ramp for a duration.
902      *
903      * @param Volume to set. The value type is float, form 0.0 to 1.0.
904      * @param Duration for volume ramp.
905      * @since 11
906      */
907     virtual int32_t SetVolumeWithRamp(float volume, int32_t duration) = 0;
908 
909     virtual void SetPreferredFrameSize(int32_t frameSize) = 0;
910     /**
911      * @brief Changes the renderer speed.
912      * @param Speed to set. The value type is float, form 0.25 to 4.0.
913      * @since 11
914      */
915     virtual int32_t SetSpeed(float speed) = 0;
916 
917     /**
918      * @brief Get the renderer speed.
919      * @since 11
920      */
921     virtual float GetSpeed() = 0;
922 
923     virtual bool IsFastRenderer() = 0;
924 
925     virtual ~AudioRenderer();
926 
927     virtual void SetSilentModeAndMixWithOthers(bool on) = 0;
928 
929     virtual bool GetSilentModeAndMixWithOthers() = 0;
930 
931     virtual void EnableVoiceModemCommunicationStartStream(bool enable) = 0;
932 
933     virtual bool IsNoStreamRenderer() const = 0;
934 
935     /**
936      * @brief Temporarily changes the current audio route.
937      * @param deviceType to set. The available deviceTypes are EARPIECE/SPEAKER/DEFAULT.
938      * @since 12
939      */
SetDefaultOutputDevice(DeviceType deviceType)940     virtual int32_t SetDefaultOutputDevice(DeviceType deviceType) { return 0; };
941 
942 private:
943     static void SendRendererCreateError(const StreamUsage &sreamUsage,
944         const int32_t &errorCode);
945     static std::mutex createRendererMutex_;
946 };
947 }  // namespace AudioStandard
948 }  // namespace OHOS
949 #endif  // AUDIO_RENDERER_H
950