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