1/*
2 * Copyright (c) 2021-2021 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 HISTREAMER_PLUGIN_INTF_AUDIO_SINK_PLUGIN_H
17#define HISTREAMER_PLUGIN_INTF_AUDIO_SINK_PLUGIN_H
18
19#include "buffer/avbuffer.h"
20#include "filter/filter.h"
21#include "plugin/plugin_caps.h"
22#include "plugin/plugin_base.h"
23#include "plugin/plugin_definition.h"
24
25namespace OHOS {
26namespace Media {
27namespace Plugins {
28/**
29 * @brief Audio Sink Plugin.
30 *
31 * Component that receives media streams.
32 *
33 * @since 1.0
34 * @version 1.0
35 */
36struct AudioSinkPlugin : public Plugins::PluginBase {
37    /// constructor
38    explicit AudioSinkPlugin(std::string name): PluginBase(std::move(name)) {}
39    /**
40     * @brief Get the mute operation set for the audio.
41     *
42     * This function can be called in any state except DESTROYED and INVALID.
43     *
44     * @param mute  Indicates the mute operation set for the audio.
45     *              Value true means that the audio is muted, and false means the opposite.
46     * @return   Execution status return
47     * @retval OK: Plugin GetMute succeeded.
48     */
49    virtual Status GetMute(bool& mute) = 0;
50
51    /**
52     * @brief Set the mute operation for the audio.
53     *
54     * This function can be called in any state except DESTROYED and INVALID.
55     *
56     * @param mute  Indicates the mute operation set for the audio.
57     *              Value true means that the audio is muted, and false means the opposite.
58     * @return  Execution status return
59     * @retval OK: Plugin SetMute succeeded.
60     */
61    virtual Status SetMute(bool mute) = 0;
62
63    /**
64     * @brief Get the audio volume.
65     *
66     * This function can be called in any state except DESTROYED and INVALID.
67     *
68     * @param volume    Indicates the volume to set. The value ranges from 0.0 to 1.0.
69     * @return  Execution status return
70     * @retval OK: Plugin GetVolume succeeded.
71     */
72    virtual Status GetVolume(float& volume) = 0;
73
74    /**
75     * @brief Set the audio volume.
76     *
77     * This function can be called in any state except DESTROYED and INVALID.
78     *
79     * @param volume    Indicates the volume to set. The value ranges from 0.0 to 1.0.
80     * @return  Execution status return
81     * @retval OK: Plugin SetVolume succeeded.
82     * @retval ERROR_INVALID_DATA: The value is not in the valid range.
83     */
84    virtual Status SetVolume(float volume) = 0;
85
86    /**
87     * @brief Get the current audio rendering speed.
88     *
89     * This function can be called in any state except DESTROYED and INVALID.
90     *
91     * @param speed Indicates the pointer to the current rendering speed to obtain.
92     * @return  Execution status return
93     * @retval OK: Plugin GetSpeed succeeded.
94     */
95    virtual Status GetSpeed(float& speed) = 0;
96
97    /**
98     * @brief Set the audio rendering speed.
99     *
100     * This function can be called in any state except DESTROYED and INVALID.
101     *
102     * @param speed speed Indicates the pointer to the current rendering speed to obtain.
103     * @return  Execution status return
104     * @retval OK: Plugin SetSpeed succeeded.
105     * @retval ERROR_INVALID_DATA: The value is not in the valid range.
106     */
107    virtual Status SetSpeed(float speed) = 0;
108
109    /**
110     * @brief Get the audioeffect mode.
111     *
112     * This function can be called in any state except DESTROYED and INVALID.
113     *
114     * @param effectMode speed Indicates the pointer to the current audioeffect mode to obtain.
115     * @return  Execution status return
116     * @retval OK: Plugin GetAudioEffectMode succeeded.
117     * @retval ERROR_INVALID_DATA: The value is not in the valid range.
118     */
119    virtual Status GetAudioEffectMode(int32_t &effectMode) = 0;
120
121    /**
122     * @brief Set the audio audioeffect mode.
123     *
124     * This function can be called in any state except DESTROYED and INVALID.
125     *
126     * @param effectMode speed Indicates the pointer to the current audioeffect mode to obtain.
127     * @return  Execution status return
128     * @retval OK: Plugin SetAudioEffectMode succeeded.
129     * @retval ERROR_INVALID_DATA: The value is not in the valid range.
130     */
131    virtual Status SetAudioEffectMode(int32_t effectMode) = 0;
132
133    /**
134     * @brief Pauses audio rendering
135     *
136     * The function is valid only in the RUNNING state. If the pause is successful,
137     * the plugin enters the PAUSED state.
138     *
139     * @return  Execution status return
140     * @retval OK: Plugin Pause succeeded.
141     */
142    virtual Status Pause() = 0;
143
144    /**
145     * @brief Pauses audio rendering without clear device lists
146     *
147     * The function is valid only in the RUNNING state. If the pause is successful,
148     * the plugin enters the PAUSED state.
149     *
150     * @return  Execution status return
151     * @retval OK: Plugin Pause succeeded.
152     */
153    virtual Status PauseTransitent() = 0;
154
155    /**
156     * @brief Resumes audio rendering
157     *
158     * The function is valid only in the PAUSED state. If the resume is successful,
159     * the plugin enters the RUNNING state.
160     *
161     * @return  Execution status return
162     * @retval OK: Plugin Resume succeeded.
163     */
164    virtual Status Resume() = 0;
165
166    /**
167     * @brief Get the estimated latency of the audio device driver.
168     *
169     * The function is valid only in the after PREPARED state.
170     *
171     * @param hstTime  latency times based on {@link HST_TIME_BASE}.
172     * @return  Execution status return
173     * @retval OK: Plugin GetLatency succeeded.
174     */
175    virtual Status GetLatency(uint64_t& hstTime) = 0;
176
177    /**
178     * @brief Get the audio frame size, that is, the length (in bytes) of a frame.
179     *
180     * The function is valid only in the RUNNING state.
181     *
182     * @param size  size Indicates the pointer to the audio frame size (in bytes).
183     * @return  Execution status return
184     * @retval OK: Plugin GetFrameSize succeeded.
185     */
186    virtual Status GetFrameSize(size_t& size) = 0;
187
188    /**
189     * @brief Get the number of audio frames in the audio buffer.
190     *
191     * The function is valid only in the RUNNING state.
192     *
193     * @param count Indicates the pointer to the number of audio frames in the audio buffer.
194     * @return  Execution status return
195     * @retval OK: Plugin GetFrameCount succeeded.
196     */
197    virtual Status GetFrameCount(uint32_t& count) = 0;
198
199    /**
200     * @brief Writes a frame of output data into the audio driver for rendering.
201     *
202     * The function is valid only in the RUNNING state.
203     *
204     * @param input Indicates the pointer to the frame to write.
205     * @return  Execution status return
206     * @retval OK: Plugin Write succeeded.
207     */
208    virtual Status Write(const std::shared_ptr<AVBuffer>& input) = 0;
209
210    /**
211     * @brief Flushes data in the audio buffer.
212     *
213     * The function is valid only in after RUNNING state.
214     *
215     * @return  Execution status return
216     * @retval OK: Plugin Flush succeeded.
217     */
218    virtual Status Flush() = 0;
219
220    /**
221     * @brief Drain data to make sure all the data processed.
222     *
223     * The function is valid only in RUNNING state.
224     *
225     * @return  Execution status return
226     * @retval OK: Plugin Drain succeeded.
227     */
228    virtual Status Drain() = 0;
229
230    virtual int64_t GetPlayedOutDurationUs(int64_t nowUs) = 0;
231
232    virtual Status GetFramePosition(int32_t &framePosition) = 0;
233
234    virtual void SetEventReceiver(const std::shared_ptr<Pipeline::EventReceiver>& receiver) = 0;
235
236    virtual int32_t SetVolumeWithRamp(float targetVolume, int32_t duration) = 0;
237
238    virtual Status SetMuted(bool isMuted) = 0;
239    virtual AudioSampleFormat GetSampleFormat()
240    {
241        return INVALID_WIDTH;
242    }
243};
244
245/// Audio sink plugin api major number.
246#define AUDIO_SINK_API_VERSION_MAJOR (1)
247
248/// Audio sink plugin api minor number
249#define AUDIO_SINK_API_VERSION_MINOR (0)
250
251/// Audio sink plugin version
252#define AUDIO_SINK_API_VERSION MAKE_VERSION(AUDIO_SINK_API_VERSION_MAJOR, AUDIO_SINK_API_VERSION_MINOR)
253
254/**
255 * @brief Describes the audio sink plugin information.
256 *
257 * @since 1.0
258 * @version 1.0
259 */
260struct AudioSinkPluginDef : public Plugins::PluginDefBase {
261    AudioSinkPluginDef()
262    {
263        apiVersion = AUDIO_SINK_API_VERSION; ///< Audio sink plugin version.
264        pluginType = Plugins::PluginType::AUDIO_SINK; ///< Plugin type, MUST be AUDIO_SINK.
265    }
266};
267} // namespace Plugin
268} // namespace Media
269} // namespace OHOS
270#endif // HISTREAMER_PLUGIN_INTF_AUDIO_SINK_PLUGIN_H
271