1 /* 2 * Copyright (c) 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 17 /** 18 * @addtogroup LowPowerAudioSink 19 * @{ 20 * 21 * @brief The LowPowerAudioSink sub module provides variables, properties, and functions 22 * for lowpower audio sink. 23 * 24 * @since 20 25 */ 26 27 /** 28 * @file lowpower_audio_sink.h 29 * 30 * @brief Declare the Native API used for lowpower audio sink. 31 * 32 * @library liblowpower_avsink.so 33 * @kit MediaKit 34 * @syscap SystemCapability.Multimedia.Media.LowPowerAVSink 35 * @since 20 36 */ 37 38 #ifndef NATIVE_LOWPOWER_AUDIO_SINK_H 39 #define NATIVE_LOWPOWER_AUDIO_SINK_H 40 41 #include <stdint.h> 42 #include <stdio.h> 43 #include "native_averrors.h" 44 #include "native_avformat.h" 45 #include "lowpower_audio_sink_base.h" 46 #include "native_audiostream_base.h" 47 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 /** 54 * @brief Creates a lowpower audio sink instance from the mime type, which is recommended in most cases. 55 * 56 * @param {const char*} mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} 57 * @return Returns a Pointer to an LowPowerAudioSink instance. 58 * Return nullptr if memory ran out or the mime type is not supported. 59 * @since 20 60 */ 61 OH_LowPowerAudioSink* OH_LowPowerAudioSink_CreateByMime(const char* mime); 62 63 /** 64 * @brief To configure the lowpower audio sink, typically, you need to configure the description information of the 65 * decoded audio track, which can be extracted from the OH_AVSource. This interface must be called before Prepare 66 * is called. 67 * 68 * @param {LowPowerAudioSink*} sink Pointer to an LowPowerAudioSink instance 69 * @param {OH_AVFormat*} format A pointer to an OH_AVFormat to give the description of the audio track to be decoded 70 * @return Returns AV_ERR_OK if the execution is successful, 71 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 72 * {@link AV_ERR_INVALID_VAL}, the sink or format is nullptr or invalid. Invalid param in format. 73 * {@link AV_ERR_UNKNOWN}, unknown error. 74 * {@link AV_ERR_SERVICE_DIED}, media service is died. 75 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. 76 * {@link AV_ERR_UNSUPPORTED_FORMAT}, unsupported format. 77 * @since 20 78 */ 79 OH_AVErrCode OH_LowPowerAudioSink_Configure(OH_LowPowerAudioSink* sink, const OH_AVFormat* format); 80 81 /** 82 * @brief Set dynamic parameters to the lowpower audio sink. 83 * Note: This interface can only be called after the decoder is started. 84 * At the same time, incorrect parameter settings may cause audio sink failure. 85 * 86 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 87 * @param {OH_AVFormat*} format pointer to an OH_AVFormat instance 88 * @return Returns AV_ERR_OK if the execution is successful, 89 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 90 * {@link AV_ERR_INVALID_VAL}, the sink or format is nullptr or invalid. Invalid param in format. 91 * {@link AV_ERR_UNKNOWN}, unknown error. 92 * {@link AV_ERR_SERVICE_DIED}, media service is died. 93 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 94 * {@link AV_ERR_UNSUPPORTED_FORMAT}, unsupported format. 95 * @since 20 96 */ 97 OH_AVErrCode OH_LowPowerAudioSink_SetParameter(OH_LowPowerAudioSink* sink, const OH_AVFormat* format); 98 99 /** 100 * @brief Get parameter of current lowpower audio sink. 101 * 102 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 103 * @param {OH_AVFormat*} format pointer to an OH_AVFormat instance 104 * @return Returns AV_ERR_OK if the execution is successful, 105 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 106 * {@link AV_ERR_INVALID_VAL}, the streamer or format is nullptr or invalid. Invalid param in format. 107 * {@link AV_ERR_UNKNOWN}, unknown error. 108 * {@link AV_ERR_SERVICE_DIED}, media service is died. 109 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 110 * {@link AV_ERR_UNSUPPORTED_FORMAT}, unsupported format. 111 * @since 20 112 */ 113 OH_AVErrCode OH_LowPowerAudioSink_GetParameter(OH_LowPowerAudioSink* sink, OH_AVFormat* format); 114 115 /** 116 * @brief To prepare the internal resources of the lowpower audio sink, the Configure interface must be called before 117 * calling this interface. 118 * 119 * @param {OH_LowPowerAudioSink*} streamer Pointer to an OH_LowPowerAudioSink instance 120 * @return Returns AV_ERR_OK if the execution is successful, 121 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 122 * {@link AV_ERR_INVALID_VAL}, the streamer is nullptr or invalid. 123 * {@link AV_ERR_UNKNOWN}, unknown error. 124 * {@link AV_ERR_SERVICE_DIED}, media service is died. 125 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 126 * @since 20 127 */ 128 OH_AVErrCode OH_LowPowerAudioSink_Prepare(OH_LowPowerAudioSink* sink); 129 130 /** 131 * @brief Start the lowpower audio sink, this interface must be called after the Prepare is successful. 132 * After being successfully started, the lowpower audio sink will start reporting DataNeeded events. 133 * 134 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 135 * @return Returns AV_ERR_OK if the execution is successful, 136 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 137 * {@link AV_ERR_INVALID_VAL}, the streamer is nullptr or invalid. 138 * {@link AV_ERR_UNKNOWN}, unknown error. 139 * {@link AV_ERR_SERVICE_DIED}, media service is died. 140 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 141 * @since 20 142 */ 143 OH_AVErrCode OH_LowPowerAudioSink_Start(OH_LowPowerAudioSink* sink); 144 145 /** 146 * @brief Pause the lowpower audio sink, this interface must be called after the Start or Resume is successful. 147 * After being successfully paused, the lowpower audio sink will pause reporting DataNeeded events.. 148 * 149 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 150 * @return Returns AV_ERR_OK if the execution is successful, 151 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 152 * {@link AV_ERR_INVALID_VAL}, the streamer is nullptr or invalid. 153 * {@link AV_ERR_UNKNOWN}, unknown error. 154 * {@link AV_ERR_SERVICE_DIED}, media service is died. 155 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 156 * @since 20 157 */ 158 OH_AVErrCode OH_LowPowerAudioSink_Pause(OH_LowPowerAudioSink* sink); 159 160 /** 161 * @brief Resume the lowpower audio sink, this interface must be called after the Pause is successful. 162 * After being successfully resumed, the lowpower audio sink will resume reporting DataNeeded events. 163 * 164 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 165 * @return Returns AV_ERR_OK if the execution is successful, 166 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 167 * {@link AV_ERR_INVALID_VAL}, the streamer is nullptr or invalid. 168 * {@link AV_ERR_UNKNOWN}, unknown error. 169 * {@link AV_ERR_SERVICE_DIED}, media service is died. 170 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 171 * @since 20 172 */ 173 OH_AVErrCode OH_LowPowerAudioSink_Resume(OH_LowPowerAudioSink* sink); 174 175 /** 176 * @brief Clear cache data in the lowpower audio sink, this interface is suggested to not be called after the Start 177 * or Resume. It should be noted that need to re-enter if the codec has been input before Codec-Specific-Data. 178 * 179 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 180 * @return Returns AV_ERR_OK if the execution is successful, 181 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 182 * {@link AV_ERR_INVALID_VAL}, the streamer is nullptr or invalid. 183 * {@link AV_ERR_UNKNOWN}, unknown error. 184 * {@link AV_ERR_SERVICE_DIED}, media service is died. 185 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 186 * @since 20 187 */ 188 OH_AVErrCode OH_LowPowerAudioSink_Flush(OH_LowPowerAudioSink* sink); 189 190 /** 191 * @brief Stop the lowpower audio sink. 192 * 193 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 194 * @return Returns AV_ERR_OK if the execution is successful, 195 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 196 * {@link AV_ERR_INVALID_VAL}, the streamer is nullptr or invalid. 197 * {@link AV_ERR_UNKNOWN}, unknown error. 198 * {@link AV_ERR_SERVICE_DIED}, media service is died. 199 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 200 * @since 20 201 */ 202 OH_AVErrCode OH_LowPowerAudioSink_Stop(OH_LowPowerAudioSink* sink); 203 204 /** 205 * @brief Reset the lowpower audio sink. Too reuse this instance, you need to call the Configure. 206 * 207 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 208 * @return Returns AV_ERR_OK if the execution is successful, 209 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 210 * {@link AV_ERR_INVALID_VAL}, the streamer is nullptr or invalid. 211 * {@link AV_ERR_UNKNOWN}, unknown error. 212 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 213 * @since 20 214 */ 215 OH_AVErrCode OH_LowPowerAudioSink_Reset(OH_LowPowerAudioSink* sink); 216 217 /** 218 * @brief Clear the internal resources of the lowpower audio sink and destroy the lowpower audio sink instance. 219 * 220 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 221 * @return Returns AV_ERR_OK if the execution is successful, 222 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 223 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 224 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 225 * @since 20 226 */ 227 OH_AVErrCode OH_LowPowerAudioSink_Destroy(OH_LowPowerAudioSink* sink); 228 229 /** 230 * @brief Set volume of current lowpower audio sink. 231 * 232 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 233 * @param {const float} volume Volume to set which changes from 0.0 to 1.0 234 * @return Returns AV_ERR_OK if the execution is successful, 235 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 236 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 237 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 238 * @since 20 239 */ 240 OH_AVErrCode OH_LowPowerAudioSink_SetVolume(OH_LowPowerAudioSink* sink, const float volume); 241 242 /** 243 * @brief Set playback speed for the lowpower audio sink. 244 * 245 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 246 * @param {const float} speed The playback speed value needs to be specified, the valid value is 0.1-4.0 247 * @return Returns AV_ERR_OK if the execution is successful, 248 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 249 * {@link AV_ERR_INVALID_VAL}, the streamer is nullptr or invalid. 250 * {@link AV_ERR_UNKNOWN}, unknown error. 251 * {@link AV_ERR_SERVICE_DIED}, media service is died. 252 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 253 * @since 20 254 */ 255 OH_AVErrCode OH_LowPowerAudioSink_SetPlaybackSpeed(OH_LowPowerAudioSink* sink, const float speed); 256 257 /** 258 * @brief Return frame packet buffer to lowpower audio sink. 259 * 260 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 261 * @param {OH_AVSamplesBuffer*} samples Pointer to an OH_AVSamplesBuffer instance 262 * @return Returns AV_ERR_OK if the execution is successful, 263 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 264 * {@link AV_ERR_INVALID_VAL}, the streamer is nullptr or invalid. 265 * {@link AV_ERR_UNKNOWN}, unknown error. 266 * {@link AV_ERR_SERVICE_DIED}, media service is died. 267 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 268 * @since 20 269 */ 270 OH_AVErrCode OH_LowPowerAudioSink_ReturnSamples(OH_LowPowerAudioSink* sink, OH_AVSamplesBuffer* samples); 271 272 /** 273 * @brief Regsister callback instance for lowpower audio sink. 274 * 275 * @param {OH_LowPowerAudioSink*} sink Pointer to an OH_LowPowerAudioSink instance 276 * @param {OH_LowPowerAudioSinkCallback*} callback Pointer to an OH_LowPowerAudioSinkCallback instance 277 * @return Returns AV_ERR_OK if the execution is successful, 278 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 279 * {@link AV_ERR_INVALID_VAL}, the streamer is nullptr or invalid. 280 * {@link AV_ERR_UNKNOWN}, unknown error. 281 * {@link AV_ERR_SERVICE_DIED}, media service is died. 282 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 283 * @since 20 284 */ 285 OH_AVErrCode OH_LowPowerAudioSink_RegisterCallback(OH_LowPowerAudioSink* sink, OH_LowPowerAudioSinkCallback* callback); 286 287 /** 288 * @brief Creates a lowpower audio sink callback instance. 289 * 290 * @return Returns a Pointer to an OH_LowPowerAudioSinkCallback instance. 291 * Return nullptr if memory ran out. 292 * @since 20 293 */ 294 OH_LowPowerAudioSinkCallback* OH_LowPowerAudioSinkCallback_Create(void); 295 296 /** 297 * @brief Destroy the lowpower audio sink callback instance. 298 * 299 * @param {OH_LowPowerAudioSinkCallback*} callback Pointer to an OH_LowPowerAudioSinkCallback instance 300 * @return Returns AV_ERR_OK if the execution is successful, 301 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 302 * {@link AV_ERR_INVALID_VAL}, the callback is nullptr or invalid. 303 * @since 20 304 */ 305 OH_AVErrCode OH_LowPowerAudioSinkCallback_Destroy(OH_LowPowerAudioSinkCallback* callback); 306 307 /** 308 * @brief Add onPositionUpdated listener to the lowpower audio sink callback instance. 309 * 310 * @param {OH_LowPowerAudioSinkCallback*} callback Pointer to an OH_LowPowerAudioSinkCallback instance 311 * @param {OH_LowPowerAudioSink_OnPositionUpdated} onPositionUpdated OH_LowPowerAudioSink_OnPositionUpdated function, 312 * refer to {@link OH_LowPowerAudioSink_OnPositionUpdated} 313 * @param userData User specific data 314 * @return Returns AV_ERR_OK if the execution is successful, 315 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 316 * {@link AV_ERR_INVALID_VAL}, the callback is nullptr or invalid. 317 * @since 20 318 */ 319 OH_AVErrCode OH_LowPowerAudioSinkCallback_SetPositionUpdateListener( 320 OH_LowPowerAudioSinkCallback* callback, 321 OH_LowPowerAudioSink_OnPositionUpdated onPositionUpdated, 322 void* userData); 323 324 /** 325 * @brief Add onDataNeeded listener to the lowpower audio sink callback instance. 326 * 327 * @param {OH_LowPowerAudioSinkCallback*} callback Pointer to an OH_LowPowerAudioSinkCallback instance 328 * @param {OH_LowPowerAudioSink_OnDataNeeded} onDataNeeded OH_LowPowerAudioSink_OnDataNeeded function, 329 * refer to {@link OH_LowPowerAudioSink_OnDataNeeded} 330 * @param {void*} userData User specific data 331 * @return Returns AV_ERR_OK if the execution is successful, 332 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 333 * {@link AV_ERR_INVALID_VAL}, the callback is nullptr or invalid. 334 * @since 20 335 */ 336 OH_AVErrCode OH_LowPowerAudioSinkCallback_SetDataNeededListener( 337 OH_LowPowerAudioSinkCallback* callback, 338 OH_LowPowerAudioSink_OnDataNeeded onDataNeeded, 339 void* userData); 340 341 /** 342 * @brief Add onError listener to the lowpower audio sink callback instance. 343 * 344 * @param {OH_LowPowerAudioSinkCallback*} callback Pointer to an OH_LowPowerAudioSinkCallback instance 345 * @param {OH_LowPowerAudioSink_OnError} onError OH_LowPowerAudioSink_OnError function, 346 * refer to {@link OH_LowPowerAudioSink_OnError} 347 * @param {void*} userData User specific data 348 * @return Returns AV_ERR_OK if the execution is successful, 349 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 350 * {@link AV_ERR_INVALID_VAL}, the callback is nullptr or invalid. 351 * @since 20 352 */ 353 OH_AVErrCode OH_LowPowerAudioSinkCallback_SetErrorListener( 354 OH_LowPowerAudioSinkCallback* callback, 355 OH_LowPowerAudioSink_OnError onError, 356 void* userData); 357 358 /** 359 * @brief Add onInterrupted listener to the lowpower audio sink callback instance. 360 * 361 * @param {OH_LowPowerAudioSinkCallback*} callback Pointer to an OH_LowPowerAudioSinkCallback instance 362 * @param {OH_LowPowerAudioSink_OnInterrupted} onInterrupted OH_LowPowerAudioSink_OnInterrupted function, 363 * refer to {@link OH_LowPowerAudioSink_OnInterrupted} 364 * @param {void*} userData User specific data 365 * @return Returns AV_ERR_OK if the execution is successful, 366 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 367 * {@link AV_ERR_INVALID_VAL}, the callback is nullptr or invalid. 368 * @since 20 369 */ 370 OH_AVErrCode OH_LowPowerAudioSinkCallback_SetInterruptListener( 371 OH_LowPowerAudioSinkCallback* callback, 372 OH_LowPowerAudioSink_OnInterrupted onInterrupted, 373 void* userData); 374 375 /** 376 * @brief Add onDeviceChanged listener to the lowpower audio sink callback instance. 377 * 378 * @param {OH_LowPowerAudioSinkCallback*} callback Pointer to an OH_LowPowerAudioSink Callback instance 379 * @param {OH_LowPowerAudioSink_OnDeviceChanged} onInterrupted OH_LowPowerAudioSink_OnDeviceChanged function, 380 * refer to {@link OH_LowPowerAudioSink_OnInterrupted} 381 * @param {void*} userData User specific data 382 * @return Returns AV_ERR_OK if the execution is successful, 383 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 384 * {@link AV_ERR_INVALID_VAL}, the callback is nullptr or invalid. 385 * @since 20 386 */ 387 OH_AVErrCode OH_LowPowerAudioSinkCallback_SetDeviceChangeListener( 388 OH_LowPowerAudioSinkCallback* callback, 389 OH_LowPowerAudioSink_OnDeviceChanged onDeviceChanged, 390 void* userData); 391 392 /** 393 * @brief Add onEos listener to the lowpower audio sink callback instance. 394 * 395 * @param {OH_LowPowerAudioSinkCallback*} callback Pointer to an OH_LowPowerAudioSinkCallback instance 396 * @param {OH_LowPowerAudioSink_OnEos} onInterrupted OH_LowPowerAudioSink_OnEos function, 397 * refer to {@link OH_LowPowerAudioSink_OnEos} 398 * @param {void*} userData User specific data 399 * @return Returns AV_ERR_OK if the execution is successful, 400 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 401 * {@link AV_ERR_INVALID_VAL}, the callback is nullptr or invalid. 402 * @since 20 403 */ 404 OH_AVErrCode OH_LowPowerAudioSinkCallback_SetEosListener( 405 OH_LowPowerAudioSinkCallback *callback, 406 OH_LowPowerAudioSink_OnEos onEos, 407 void* userData); 408 409 #ifdef __cplusplus 410 } 411 #endif 412 413 #endif // NATIVE_LOWPOWER_AUDIO_SINK_H 414 415 /** @} */