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