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 "plugin/common/plugin_buffer.h" 20 #include "plugin/common/plugin_caps.h" 21 #include "plugin_base.h" 22 #include "plugin_definition.h" 23 24 namespace OHOS { 25 namespace Media { 26 namespace Plugin { 27 /** 28 * @brief Audio Sink Plugin. 29 * 30 * Component that receives media streams. 31 * 32 * @since 1.0 33 * @version 1.0 34 */ 35 struct AudioSinkPlugin : public PluginBase { 36 /// constructor AudioSinkPluginAudioSinkPlugin37 explicit AudioSinkPlugin(std::string name): PluginBase(std::move(name)) {} 38 /** 39 * @brief Get the mute operation set for the audio. 40 * 41 * This function can be called in any state except DESTROYED and INVALID. 42 * 43 * @param mute Indicates the mute operation set for the audio. 44 * Value true means that the audio is muted, and false means the opposite. 45 * @return Execution status return 46 * @retval OK: Plugin GetMute succeeded. 47 */ 48 virtual Status GetMute(bool& mute) = 0; 49 50 /** 51 * @brief Set the mute operation for the audio. 52 * 53 * This function can be called in any state except DESTROYED and INVALID. 54 * 55 * @param mute Indicates the mute operation set for the audio. 56 * Value true means that the audio is muted, and false means the opposite. 57 * @return Execution status return 58 * @retval OK: Plugin SetMute succeeded. 59 */ 60 virtual Status SetMute(bool mute) = 0; 61 62 /** 63 * @brief Get the audio volume. 64 * 65 * This function can be called in any state except DESTROYED and INVALID. 66 * 67 * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0. 68 * @return Execution status return 69 * @retval OK: Plugin GetVolume succeeded. 70 */ 71 virtual Status GetVolume(float& volume) = 0; 72 73 /** 74 * @brief Set the audio volume. 75 * 76 * This function can be called in any state except DESTROYED and INVALID. 77 * 78 * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0. 79 * @return Execution status return 80 * @retval OK: Plugin SetVolume succeeded. 81 * @retval ERROR_INVALID_DATA: The value is not in the valid range. 82 */ 83 virtual Status SetVolume(float volume) = 0; 84 85 /** 86 * @brief Get the current audio rendering speed. 87 * 88 * This function can be called in any state except DESTROYED and INVALID. 89 * 90 * @param speed Indicates the pointer to the current rendering speed to obtain. 91 * @return Execution status return 92 * @retval OK: Plugin GetSpeed succeeded. 93 */ 94 virtual Status GetSpeed(float& speed) = 0; 95 96 /** 97 * @brief Set the audio rendering speed. 98 * 99 * This function can be called in any state except DESTROYED and INVALID. 100 * 101 * @param speed speed Indicates the pointer to the current rendering speed to obtain. 102 * @return Execution status return 103 * @retval OK: Plugin SetSpeed succeeded. 104 * @retval ERROR_INVALID_DATA: The value is not in the valid range. 105 */ 106 virtual Status SetSpeed(float speed) = 0; 107 108 /** 109 * @brief Pauses audio rendering 110 * 111 * The function is valid only in the RUNNING state. If the pause is successful, 112 * the plugin enters the PAUSED state. 113 * 114 * @return Execution status return 115 * @retval OK: Plugin Pause succeeded. 116 */ 117 virtual Status Pause() = 0; 118 119 /** 120 * @brief Resumes audio rendering 121 * 122 * The function is valid only in the PAUSED state. If the resume is successful, 123 * the plugin enters the RUNNING state. 124 * 125 * @return Execution status return 126 * @retval OK: Plugin Resume succeeded. 127 */ 128 virtual Status Resume() = 0; 129 130 /** 131 * @brief Get the estimated latency of the audio device driver. 132 * 133 * The function is valid only in the after PREPARED state. 134 * 135 * @param hstTime latency times based on {@link HST_TIME_BASE}. 136 * @return Execution status return 137 * @retval OK: Plugin GetLatency succeeded. 138 */ 139 virtual Status GetLatency(uint64_t& hstTime) = 0; 140 141 /** 142 * @brief Get the audio frame size, that is, the length (in bytes) of a frame. 143 * 144 * The function is valid only in the RUNNING state. 145 * 146 * @param size size Indicates the pointer to the audio frame size (in bytes). 147 * @return Execution status return 148 * @retval OK: Plugin GetFrameSize succeeded. 149 */ 150 virtual Status GetFrameSize(size_t& size) = 0; 151 152 /** 153 * @brief Get the number of audio frames in the audio buffer. 154 * 155 * The function is valid only in the RUNNING state. 156 * 157 * @param count Indicates the pointer to the number of audio frames in the audio buffer. 158 * @return Execution status return 159 * @retval OK: Plugin GetFrameCount succeeded. 160 */ 161 virtual Status GetFrameCount(uint32_t& count) = 0; 162 163 /** 164 * @brief Writes a frame of output data into the audio driver for rendering. 165 * 166 * The function is valid only in the RUNNING state. 167 * 168 * @param input Indicates the pointer to the frame to write. 169 * @return Execution status return 170 * @retval OK: Plugin Write succeeded. 171 */ 172 virtual Status Write(const std::shared_ptr<Buffer>& input) = 0; 173 174 /** 175 * @brief Flushes data in the audio buffer. 176 * 177 * The function is valid only in after RUNNING state. 178 * 179 * @return Execution status return 180 * @retval OK: Plugin Flush succeeded. 181 */ 182 virtual Status Flush() = 0; 183 184 /** 185 * @brief Drain data to make sure all the data processed. 186 * 187 * The function is valid only in RUNNING state. 188 * 189 * @return Execution status return 190 * @retval OK: Plugin Drain succeeded. 191 */ 192 virtual Status Drain() = 0; 193 }; 194 195 /// Audio sink plugin api major number. 196 #define AUDIO_SINK_API_VERSION_MAJOR (1) 197 198 /// Audio sink plugin api minor number 199 #define AUDIO_SINK_API_VERSION_MINOR (0) 200 201 /// Audio sink plugin version 202 #define AUDIO_SINK_API_VERSION MAKE_VERSION(AUDIO_SINK_API_VERSION_MAJOR, AUDIO_SINK_API_VERSION_MINOR) 203 204 /** 205 * @brief Describes the audio sink plugin information. 206 * 207 * @since 1.0 208 * @version 1.0 209 */ 210 struct AudioSinkPluginDef : public PluginDefBase { 211 CapabilitySet inCaps {}; ///< Plug-in input capability, For details, @see Capability. 212 PluginCreatorFunc<AudioSinkPlugin> creator {nullptr}; ///< Audio sink plugin create function. AudioSinkPluginDefAudioSinkPluginDef213 AudioSinkPluginDef() 214 { 215 apiVersion = AUDIO_SINK_API_VERSION; ///< Audio sink plugin version. 216 pluginType = PluginType::AUDIO_SINK; ///< Plugin type, MUST be AUDIO_SINK. 217 } 218 }; 219 } // namespace Plugin 220 } // namespace Media 221 } // namespace OHOS 222 #endif // HISTREAMER_PLUGIN_INTF_AUDIO_SINK_PLUGIN_H 223