include/esplusplayer_capi/esplusplayer_capi.h

   1 /**
   2  * @file           esplusplayer_capi.h
   3  * @brief          EsPlusPlayer api c version
   4  * @interfacetype  Platform
   5  * @privlevel      None-privilege
   6  * @privilege      None
   7  * @product        TV, AV, B2B
   8  * @version        2.0
   9  * @SDK_Support    N
  10  * @remark         This is esplusplayer api header implemented as C style to
  11  *                 avoid binary compatibility issues.
  12  *
  13  * Copyright (c) 2020 Samsung Electronics Co., Ltd All Rights Reserved
  14  * PROPRIETARY/CONFIDENTIAL
  15  * This software is the confidential and proprietary
  16  * information of SAMSUNG ELECTRONICS ("Confidential Information"). You shall
  17  * not disclose such Confidential Information and shall use it only in
  18  * accordance with the terms of the license agreement you entered into with
  19  * SAMSUNG ELECTRONICS. SAMSUNG make no representations or warranties about the
  20  * suitability of the software, either express or implied, including but not
  21  * limited to the implied warranties of merchantability, fitness for a
  22  * particular purpose, or non-infringement. SAMSUNG shall not be liable for any
  23  * damages suffered by licensee as a result of using, modifying or distributing
  24  * this software or its derivatives.
  25  */
  26
  27 #ifndef __ESPLUSPLAYER_ESPLUSPLAYER_CAPI_ESPLUSPLAYER_CAPI_H__
  28 #define __ESPLUSPLAYER_ESPLUSPLAYER_CAPI_ESPLUSPLAYER_CAPI_H__
  29
  30 #include "esplusplayer_capi/buffer.h"
  31 #include "esplusplayer_capi/display.h"
  32 #include "esplusplayer_capi/drm.h"
  33 #include "esplusplayer_capi/error.h"
  34 #include "esplusplayer_capi/espacket.h"
  35 #include "esplusplayer_capi/event.h"
  36 #include "esplusplayer_capi/latency.h"
  37 #include "esplusplayer_capi/state.h"
  38 #include "esplusplayer_capi/stream.h"
  39 #include "esplusplayer_capi/submitdatatype.h"
  40 #include "esplusplayer_capi/submitstatus.h"
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 #include <stdint.h>
  47
  48 typedef void (*esplusplayer_error_cb)(const esplusplayer_error_type, void*);
  49 typedef void (*esplusplayer_buffer_status_cb)(const esplusplayer_stream_type,
  50                                               const esplusplayer_buffer_status,
  51                                               void*);
  52 typedef void (*esplusplayer_buffer_byte_status_cb)(
  53     const esplusplayer_stream_type, const esplusplayer_buffer_status, uint64_t,
  54     void*);
  55 typedef void (*esplusplayer_buffer_time_status_cb)(
  56     const esplusplayer_stream_type, const esplusplayer_buffer_status, uint64_t,
  57     void*);
  58 typedef void (*esplusplayer_resource_conflicted_cb)(void*);
  59 typedef void (*esplusplayer_eos_cb)(void*);
  60 typedef void (*esplusplayer_ready_to_prepare_cb)(const esplusplayer_stream_type,
  61                                                  void*);
  62 typedef void (*esplusplayer_prepare_async_done_cb)(bool, void*);
  63 typedef void (*esplusplayer_seek_done_cb)(void*);
  64 typedef void (*esplusplayer_ready_to_seek_cb)(const esplusplayer_stream_type,
  65                                               const uint64_t, void*);
  66 typedef void (*esplusplayer_media_packet_video_decoded_cb)(
  67     const esplusplayer_decoded_video_packet*, void*);
  68 typedef void (*esplusplayer_closed_caption_cb)(const char* data, const int size,
  69                                                void* userdata);
  70 typedef void (*esplusplayer_flush_done_cb)(void*);
  71 typedef void (*esplusplayer_event_cb)(const esplusplayer_event_type,
  72                                       const esplusplayer_event_msg, void*);
  73 typedef void (*esplusplayer_video_latency_status_cb)(
  74     const esplusplayer_latency_status latency_status, void*);
  75 typedef void (*esplusplayer_audio_latency_status_cb)(
  76     const esplusplayer_latency_status latency_status, void*);
  77 typedef void (*esplusplayer_video_high_latency_cb)(void*);
  78 typedef void (*esplusplayer_audio_high_latency_cb)(void*);
  79 typedef void (*esplusplayer_video_frame_dropped_cb)(const uint64_t count,
  80                                                     void*);
  81 typedef void (*esplusplayer_decoder_buffer_time_cb)(
  82     const esplusplayer_stream_type, const esplusplayer_decoder_buffer_time,
  83     void*);
  84
  85 typedef void* esplusplayer_handle;
  86
  87 /**
  88  * @brief  Enumerations for the Adaptive info type
  89  */
  90 enum esplusplayer_adaptive_info_type {
  91   ESPLUSPLAYER_ADAPT_INFO_TYPE_NONE,
  92   ESPLUSPLAYER_ADAPT_INFO_TYPE_DROPPED_FRAMES,
  93   ESPLUSPLAYER_ADAPT_INFO_TYPE_DROPPED_VIDEO_FRAMES_FOR_CATCHUP,
  94   ESPLUSPLAYER_ADAPT_INFO_TYPE_DROPPED_AUDIO_FRAMES_FOR_CATCHUP,
  95 };
  96
  97 /**
  98  * @brief   Enumerations for low latency mode
  99  * @version 3.2
 100  */
 101 enum esplusplayer_low_latency_mode {
 102   ESPLUSPLAYER_LOW_LATENCY_MODE_NONE = 0x0000,
 103   /**
 104    * @description   to support audio fast decoding/rendering
 105    */
 106   ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO = 0x0001,
 107   /**
 108    * @description   to support video fast decoding/rendering
 109    *                Video stream should be composed only of P and I frames.
 110    *                The mode support seamless resolution change since tizen 6.5
 111    */
 112   ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO = 0x0010,
 113   /**
 114    * @description   to support video fast decoding/rendering and video
 115    *                distortion concealment.
 116    *                Video stream should be composed only of P and I frames.
 117    *                For applications using the UDP protocol, packet loss can
 118    *                occur. when video distortion by video packet loss is
 119    *                detected, it is a function to conceal distortion by showing
 120    *                previous vido frame. It is supported only in h.264 codec &
 121    *                FHD or lower resolution.
 122    */
 123   ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO_DISTORTION_CONCEALMENT =
 124       ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO | 0x0020,
 125   /**
 126    * @description   to disable clock sync and a/v sync when rendering. it
 127    *                includes #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_PREROLL.
 128    */
 129   ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_SYNC = 0x0100,
 130   /**
 131    * @description   to disable preroll which means player doesn't wait for
 132    *                first buffer when state is changed to
 133    *                #ESPLUSPLAYER_STATE_READY from #ESPLUSPLAYER_STATE_IDLE.
 134    *                It changes the state immediately.
 135    *                It's usually used for sparse stream. (e.g. video packet
 136    *                arrives but audio packet does't yet.)
 137    */
 138   ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_PREROLL = 0x0200,
 139   /**
 140    * @deprecated    Deprecated since tizen 6.5
 141    * @description   to set lower video quality
 142    *                If set this value, it can use original game_mode.
 143    *                This value will be deprecated from 2022TV.
 144    *                Please use ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE.
 145    */
 146   ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY = 0x1000,
 147   /**
 148    * @description   to set game mode for minimum latency
 149    *                Video stream should be composed only of P and I frames.
 150    *                It must not be used together with
 151    *                #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY.
 152    *                If use this value, It can expect better latency performance
 153    *                than #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY.
 154    *                The mode support seamless resolution change.
 155    *                The mode use lower video quality.
 156    */
 157   ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE =
 158       ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO |
 159       ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO | 0x2000,
 160   /**
 161    * @description   to set game mode for latency
 162    *                Video stream should be composed only of P and I frames.
 163    *                Video stream must use fixed resolution.
 164    *                It must not be used together with
 165    *                #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY.
 166    *                If use this value, It can expect better latency
 167    *                performance than
 168    *                #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY and
 169    *                #ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE
 170    *                The mode use lower video quality.
 171    */
 172   ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE_WITH_FIXED_RESOLUTION =
 173       ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE | 0x4000,
 174 };
 175
 176 /**
 177  * @brief   Enumerations for esplusplayer audio codec type
 178  */
 179 enum esplusplayer_audio_codec_type {
 180   /**
 181    * @description   hardware codec can only be selected, default type
 182    */
 183   ESPLUSPLAYER_AUDIO_CODEC_TYPE_HW,
 184   /**
 185    * @description   sorfware codec can only be selected
 186    */
 187   ESPLUSPLAYER_AUDIO_CODEC_TYPE_SW
 188 };
 189
 190 /**
 191  * @brief   Enumerations for esplusplayer video codec type
 192  */
 193 enum esplusplayer_video_codec_type {
 194   /**
 195    * @description   hardware codec can only be selected, default type
 196    */
 197   ESPLUSPLAYER_VIDEO_CODEC_TYPE_HW,
 198   /**
 199    * @description   software codec can only be selected
 200    */
 201   ESPLUSPLAYER_VIDEO_CODEC_TYPE_SW,
 202   /**
 203   * @description   hardware codec using n-decoding mode can only be selected.
 204                    It must set display type to mixer type by display setting
 205   api.
 206                    esplusplayer_set_display()
 207   */
 208   ESPLUSPLAYER_VIDEO_CODEC_TYPE_HW_N_DECODING
 209
 210 };
 211 /**
 212  * @brief   Enumerations for esplusplayer audio easing type
 213  * @version 3.0
 214  */
 215 enum esplusplayer_audio_easing_type {
 216   /**
 217    * @description audio easing function type is linear
 218    */
 219   ESPLUSPLAYER_AUDIO_EASING_LINEAR,
 220   /**
 221    * @description audio easing function type is incubic
 222    */
 223   ESPLUSPLAYER_AUDIO_EASING_INCUBIC,
 224   /**
 225    * @description audio easing function type is outcubic
 226    */
 227   ESPLUSPLAYER_AUDIO_EASING_OUTCUBIC,
 228   /**
 229    * @description audio easing function type is none
 230    */
 231   ESPLUSPLAYER_AUDIO_EASING_NONE
 232 };
 233
 234 /**
 235  * @brief   Enumerations for esplusplayer resource type
 236  * @version 3.0
 237  */
 238 enum esplusplayer_rsc_type {
 239   /**
 240    * @description video renderer type
 241    */
 242   ESPLUSPLAYER_RSC_TYPE_VIDEO_RENDERER
 243 };
 244
 245 /**
 246  * @brief   Enumerations for advanced video quality type
 247  * @version 4.0
 248  */
 249 enum esplusplayer_advanced_picture_quality_type {
 250   /**
 251    * @description advanced picture quality for video call
 252    * @version 3.1
 253    */
 254   ESPLUSPLAYER_ADVANCED_PICTURE_QUALITY_VIDEO_CALL,
 255   /**
 256    * @description advanced picture quality for usb camera
 257    * @version 3.1
 258    */
 259   ESPLUSPLAYER_ADVANCED_PICTURE_QUALITY_USB_CAMERA,
 260   /**
 261    * @description advanced picture quality for airplay screen mirroring
 262    * @version 4.0
 263    */
 264   ESPLUSPLAYER_ADVANCED_PICTURE_QUALITY_AIRPLAY_MIRRORING
 265 };
 266
 267 /**
 268  * @brief   Enumerations for audio resource type
 269  * @version 3.8
 270  */
 271 enum esplusplayer_audio_resource_type {
 272   /**
 273    * @description all audio resources(decoder/audio out) to main resources
 274    */
 275   ESPLUSPLAYER_AUDIO_RESOURCE_MAIN,
 276   /**
 277    * @description only audio decoder to sub resource
 278    */
 279   ESPLUSPLAYER_AUDIO_RESOURCE_SUB_DECODER,
 280   /**
 281    * @description only audio out to simple mix out resource
 282    */
 283   ESPLUSPLAYER_AUDIO_RESOURCE_SIMPLE_MIX_OUT
 284 };
 285
 286 /**
 287  * @brief   Enumerations for buffer level of simple mix out
 288  * @version 3.8
 289  */
 290 enum esplusplayer_simple_mix_out_buffer_level {
 291   /**
 292    * @description buffer level is low
 293    */
 294   ESPLUSPLAYER_SIMPLE_MIX_OUT_BUFFER_LOW,
 295   /**
 296    * @description buffer level is middle, default type
 297    */
 298   ESPLUSPLAYER_SIMPLE_MIX_OUT_BUFFER_MID,
 299   /**
 300    * @description buffer level is high
 301    */
 302   ESPLUSPLAYER_SIMPLE_MIX_OUT_BUFFER_HIGH
 303 };
 304
 305 /**
 306  * @brief  ESPlusplayer easing target volume, duration, type information
 307  * @version 3.0
 308  */
 309 typedef struct {
 310   /**
 311    * @description   audio easing target volume (0 ~ 100)
 312    */
 313   unsigned int volume;
 314   /**
 315    * @description   audio easing duration, in millisecond
 316    */
 317   unsigned int duration;
 318   /**
 319    * @description   audio easing function type
 320    */
 321   esplusplayer_audio_easing_type type;
 322 } esplusplayer_target_audio_easing_info;
 323
 324 /**
 325  * @brief  ESPlusplayer app id, version, type information
 326  */
 327 typedef struct {
 328   /**
 329    * @description   App id for controlling resource.
 330    */
 331   char* id;
 332   /**
 333    * @description   When there is playback market issue, KPI logger will
 334    *                send the version.
 335    */
 336   char* version;
 337   /**
 338    * @description   RunningApps.InformationTicker will use this type to show
 339    *                stream information. ex) "MSE", "HTML5", etc..
 340    */
 341   char* type;
 342 } esplusplayer_app_info;
 343
 344 /**
 345  * @brief  ESPlusplayer app id, version, type, runtitle information
 346  * @version 5.0
 347  */
 348 typedef struct {
 349   /**
 350    * @description   App id for controlling resource.
 351    */
 352   char* id;
 353   /**
 354    * @description   When there is playback market issue, KPI logger will
 355    *                send the version.
 356    */
 357   char* version;
 358   /**
 359    * @description   RunningApps.InformationTicker will use this type to show
 360    *                stream information. ex) "MSE", "HTML5", etc..
 361    */
 362   char* type;
 363   /**
 364    * @description   App runtitle.
 365    */
 366   char* runtitle;
 367 } esplusplayer_app_info_ex;
 368
 369 typedef struct {
 370   /**
 371    * @description   the minimum frame number in case of mid latency
 372    */
 373   int mid_latency_threshold;
 374   /**
 375    * @description   the minimum frame number in case of high latency
 376    */
 377   int high_latency_threshold;
 378 } esplusplayer_latency_threshold;
 379
 380 /**
 381  * @brief  rational number numerator/denominator
 382  */
 383 typedef struct {
 384   /**
 385    * @description   the numerator value
 386    */
 387   int num;
 388   /**
 389    * @description   the denominator value
 390    */
 391   int den;
 392 } esplusplayer_rational;
 393
 394 /**
 395  * @brief  resource allocate policy
 396  * @version 3.3
 397  */
 398 enum esplusplayer_rsc_alloc_policy {
 399   /**
 400    * @description exclusive policy, RM will return the requested resources,
 401    * default policy
 402    */
 403   ESPLUSPLAYER_RSC_ALLOC_EXCLUSIVE = 0,
 404   /**
 405    * @description conditional policy, when trying to allocate resources and
 406    * available resources are not left, RM will return fail.
 407    */
 408   ESPLUSPLAYER_RSC_ALLOC_EXCLUSIVE_CONDITIONAL,
 409   /**
 410    * @description exclusive no explicit policy, RM will return available
 411    * resources.
 412    * @version 6.0
 413    */
 414   ESPLUSPLAYER_RSC_ALLOC_EXCLUSIVE_NO_EXPLICIT
 415 };
 416
 417 /**
 418  * @brief Enumerations for the status of getting decoded video frame
 419  * @version 4.0
 420  */
 421 enum esplusplayer_get_decoded_video_frame_status_type {
 422   /** @brief successfully decoded video frame acquired. */
 423   ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_SUCCESS,
 424   /** @brief  it means app has to return the video before getting decoded
 425    * video frame frame.
 426    */
 427   ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_NO_REMAINING_BUFFER,
 428   /**
 429    * @brief  there is no filled video frame yet.
 430    */
 431   ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_NO_FILLED_BUFFER,
 432   /**
 433    * @brief  internal error
 434    */
 435   ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_UNKNOWN
 436 };
 437
 438 /**
 439  * @brief Enumerations for the video scan type
 440  * @version 4.0
 441  */
 442 enum esplusplayer_video_scan_type {
 443   /**
 444    * @description progressive, mfd or dvde will be allocated for H.264 2K in
 445    * normal mode.
 446    */
 447   ESPLUSPLAYER_VIDEO_SCAN_TYPE_PROGRESSIVE,
 448   /**
 449    * @description interlaced, only mfd has been allocated for H.264 2K in normal
 450    * mode.
 451    */
 452   ESPLUSPLAYER_VIDEO_SCAN_TYPE_INTERLACED,
 453 };
 454
 455 /**
 456  * @brief Enumerations for the time unit type
 457  * @version 5.0
 458  */
 459 enum esplusplayer_time_unit_type {
 460   /**
 461    * @description the timeunit will be ms. It is default value.
 462    */
 463   ESPLUSPLAYER_TIME_UNIT_MS,
 464   /**
 465    * @description the timeunit will be us.
 466    */
 467   ESPLUSPLAYER_TIME_UNIT_US,
 468 };
 469
 470 /**
 471  * @brief  Enumerations for the video stream rotation type
 472  * @version 5.2
 473  */
 474 enum esplusplayer_video_stream_rotation_type {
 475   ESPLUSPLAYER_VIDEO_ROTATION_NONE,
 476   ESPLUSPLAYER_VIDEO_ROTATION_90,
 477   ESPLUSPLAYER_VIDEO_ROTATION_180,
 478   ESPLUSPLAYER_VIDEO_ROTATION_270
 479 };
 480
 481 /**
 482  * @brief     Create a esplusplayer handle.
 483  * @param     None
 484  * @return    return esplusplayer handle pointer.
 485  * @code
 486  *            esplusplayer_handle esplayer = esplusplayer_create();
 487  *            // ... your codes ...
 488  *            esplusplayer_destroy(esplayer);
 489  * @endcode
 490  * @pre       None
 491  * @post      The player state will be #ESPLUSPLAYER_STATE_NONE.
 492  * @exception None
 493  */
 494 esplusplayer_handle esplusplayer_create();
 495
 496 /**
 497  * @brief     Open esplusplayer handle.
 498  * @param     [in] handle : esplusplayer handle
 499  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 500  * esplusplayer_error_type
 501  *            values will be returned.
 502  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 503  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 504  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 505  * failed
 506  * @code
 507  *            esplusplayer_handle esplayer = esplusplayer_create();
 508  *            esplusplayer_open(esplayer);
 509  *            // ... your codes ...
 510  *            esplusplayer_close(esplayer);
 511  *            esplusplayer_destroy(esplayer);
 512  * @endcode
 513  * @pre       The player state must be #ESPLUSPLAYER_STATE_NONE.
 514  * @post      The player state will be #ESPLUSPLAYER_STATE_IDLE.
 515  * @exception None
 516  * @see       esplusplayer_close()
 517  */
 518 int esplusplayer_open(esplusplayer_handle handle);
 519
 520 /**
 521  * @brief     Release all the player resources and all setting except callback
 522  *            functions.
 523  * @param     [in] handle : esplusplayer handle.
 524  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 525  * esplusplayer_error_type
 526  *            values will be returned.
 527  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 528  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 529  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 530  * failed
 531  * @pre       The player state must be all of #esplusplayer_state except
 532  *            #ESPLUSPLAYER_STATE_NONE.
 533  * @post      The player state will be #ESPLUSPLAYER_STATE_NONE.
 534  * @exception None
 535  * @see       esplusplayer_open()
 536  */
 537 int esplusplayer_close(esplusplayer_handle handle);
 538
 539 /**
 540  * @brief     Release player handle.
 541  * @param     [in] handle : esplusplayer handle.
 542  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 543  * esplusplayer_error_type
 544  *            values will be returned.
 545  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 546  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 547  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 548  * failed
 549  * @code
 550  *            refer to the sample code of esplusplayer_create()
 551  * @endcode
 552  * @pre       The player state must be #ESPLUSPLAYER_STATE_NONE
 553  * @post      player handle will be removed.
 554  * @exception None
 555  * @see       esplusplayer_create()
 556  */
 557 int esplusplayer_destroy(esplusplayer_handle handle);
 558
 559 /**
 560  * @brief     Not play the specific stream anymore.
 561  * @remark    The submitted es packets will be dropped after deactivated.
 562  *            It recommands to stop feeding the specific stream's packets.
 563  * @param     [in] handle : esplusplayer handle.
 564  * @param     [in] type : stream type which user want to deactivate.
 565  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 566  * esplusplayer_error_type
 567  *            values will be returned.
 568  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 569  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 570  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 571  * failed
 572  * @code
 573  *            refer to the sample code of esplusplayer_activate()
 574  * @endcode
 575  * @pre       The player state must be at least #ESPLUSPLAYER_STATE_READY
 576  * @post      The player state is same as before calling
 577  *            esplusplayer_deactivate(). The buffered data of the deactivated
 578  * stream will be flushed and the resources for decoding and rendering will be
 579  * released.
 580  * @exception None
 581  * @see       esplusplayer_activate
 582  */
 583 int esplusplayer_deactivate(esplusplayer_handle handle,
 584                             esplusplayer_stream_type type);
 585
 586 /**
 587  * @brief     Restart to play the specific stream.
 588  * @remark    If user wants to change the specific stream info, new stream info
 589  * has to be set before activate. User has to submit the specific stream from
 590  * the current playing time for activating. The video stream has to be submitted
 591  * from Iframe.
 592  * @param     [in] handle : esplusplayer handle.
 593  * @param     [in] type : stream type which user want to activate.
 594  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 595  * esplusplayer_error_type
 596  *            values will be returned.
 597  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 598  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 599  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 600  * failed
 601  * @code
 602  *            prepare esplayer done
 603  *            // ... your codes ...
 604  *            esplusplayer_deactivate(esplayer, ESPLUSPLAYER_STREAM_TYPE_VIDEO);
 605  *            esplusplayer_set_video_stream_info* stream;
 606  *            stream->width = 640;
 607  *            stream->height = 352;
 608  *            stream->mime_type = ESPLUSPLAYER_VIDEO_MIME_TYPE_H264;
 609  *            stream->framerate_num = 30;
 610  *            stream->framerate_den = 1;
 611  *            esplusplayer_set_video_stream_info(esplayer, stream);
 612  *            esplusplayer_activate(esplayer, ESPLUSPLAYER_STREAM_TYPE_VIDEO);
 613  *            // ... your codes ...
 614  *            esplusplayer_close(esplayer);
 615  *            esplusplayer_destroy(esplayer);
 616  * @endcode
 617  * @pre       The player state must be at least #ESPLUSPLAYER_STATE_READY
 618  * @post      The player state is same as before calling
 619  *            esplusplayer_activate(). Rebuild pipeline to render the stream.
 620  * @exception None
 621  * @see       esplusplayer_prepare_async()
 622  */
 623 int esplusplayer_activate(esplusplayer_handle handle,
 624                           esplusplayer_stream_type type);
 625
 626 /**
 627  * @brief     Not play the audio stream anymore.
 628  * @remark    User has to keep feeding audio packets like when playing audio.
 629  * @param     [in] handle : esplusplayer handle.
 630  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 631  * esplusplayer_error_type
 632  *            values will be returned.
 633  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 634  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 635  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 636  * failed
 637  * @code
 638  *             refer to the sample code of esplusplayer_activate_audio()
 639  * @endcode
 640  * @pre       The player state must be at least #ESPLUSPLAYER_STATE_IDLE
 641  * @post      The player state is same as before calling
 642  *            esplusplayer_deactivate_audio(). The player will keep buffering
 643  *            the audio packets and consuming it at the rendering time.
 644  *            All audio resources of decoder and renderer will be released.
 645  * @exception None
 646  * @version   6.0
 647  * @see       esplusplayer_activate_audio
 648  */
 649 int esplusplayer_deactivate_audio(esplusplayer_handle handle);
 650
 651 /**
 652  * @brief     Restart to play the audio stream.
 653  * @remark    User can't change the audio stream info before activate.
 654  * @param     [in] handle : esplusplayer handle.
 655  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 656  * esplusplayer_error_type
 657  *            values will be returned.
 658  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 659  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 660  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 661  * failed
 662  * @code
 663  *            // play one esplayer in normal
 664  *            esplusplayer_handle esplayer1 = esplusplayer_create();
 665  *            esplusplayer_open(esplayer1);
 666  *            esplusplayer_audio_stream_info audio_stream_1;
 667  *            audio_stream_1.codec_data = nullptr;
 668  *            audio_stream_1.codec_data_length = 0;
 669  *            esplusplayer_set_audio_stream_info(esplayer1, &audio_stream_1);
 670  *            // ... your codes ...
 671  *            esplusplayer_prepare_async(esplayer1);
 672  *            esplusplayer_start(esplayer1);
 673  *
 674  *            // play one more esplayer started in deactivate
 675  *            esplusplayer_handle esplayer2 = esplusplayer_create();
 676  *            esplusplayer_open(esplayer2);
 677  *            esplusplayer_audio_stream_info audio_stream_2;
 678  *            audio_stream_2.codec_data = nullptr;
 679  *            audio_stream_2.codec_data_length = 0;
 680  *            esplusplayer_set_audio_stream_info(esplayer2, &audio_stream_2);
 681  *            // ... your codes ...
 682  *            esplusplayer_deactivate_audio(esplayer2);
 683  *            esplusplayer_prepare_async(esplayer2);
 684  *            esplusplayer_start(esplayer2);
 685  *
 686  *            // if you want to play esplayer2, deactivate esplayer1 first
 687  *            // and then activate esplayer2
 688  *            esplusplayer_deactivate_audio(esplayer1);
 689  *            esplusplayer_activate_audio(esplayer2);
 690  *            // ... your codes ...
 691  *            esplusplayer_close(esplayer1);
 692  *            esplusplayer_destroy(esplayer1);
 693  *            esplusplayer_close(esplayer2);
 694  *            esplusplayer_destroy(esplayer2);
 695  * @endcode
 696  * @pre       The player state must be at least #ESPLUSPLAYER_STATE_READY
 697  * @post      The player state is same as before calling
 698  *            esplusplayer_activate_audio(). Rebuild audio pipeline to render
 699  *            the audio stream.
 700  * @exception None
 701  * @version   6.0
 702  * @see       esplusplayer_deactivate_audio
 703  */
 704 int esplusplayer_activate_audio(esplusplayer_handle handle);
 705
 706 /**
 707  * @brief     Prepare the player for playback, asynchronously.
 708  * @param     [in] handle : esplusplayer handle.
 709  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 710  * esplusplayer_error_type
 711  *            values will be returned.
 712  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 713  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 714  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 715  * failed
 716  * @code
 717  *            static void OnPrepareDone(bool ret, void* userdata) {
 718  *                //Something you want to do when prepare done, but, we strongly
 719  *                //recommend DO NOT CALL PLAYER APIs in this callbck
 720  *                printf("OnPrepareDone\n");
 721  *            }
 722  *            esplusplayer_handle esplayer = esplusplayer_create();
 723  *            esplusplayer_set_prepare_async_done_cb(esplayer,
 724  * OnPrepareDone,nullptr);
 725  *            esplusplayer_open(esplayer);
 726  *            esplusplayer_prepare_async(esplayer);
 727  *            // ... your codes ...
 728  *            esplusplayer_close(esplayer);
 729  *            esplusplayer_destroy(esplayer);
 730  * @endcode
 731  * @pre       The player state must be #ESPLUSPLAYER_STATE_IDLE. \n
 732  *            Call at least one of esplusplayer_set_video_stream_info() or
 733  *            esplusplayer_set_audio_stream_info(). \n
 734  * @post      It invokes esplusplayer_prepare_async_done_cb() when prepare is
 735  *            finished. \n
 736  *            Prepare result can be succeeded or not at this moment. \n
 737  *            If the result is succeeded, the player state will be
 738  *            #ESPLUSPLAYER_STATE_READY and one frame will be displayed
 739  *            unless esplusplayer_set_display_visible() is set to @c false.
 740  * @exception None
 741  * @remark    esplusplayer_prepare_async_done_cb() can be invoked only when as
 742  *            many es packets as at least one decoded frame is submitted. \n
 743  *            The player can receive es packets after
 744  *            esplusplayer_ready_to_seek_cb() is called.
 745  * @see       esplusplayer_open() \n
 746  *            esplusplayer_stop() \n
 747  *            esplusplayer_submit_packet() \n
 748  *            esplusplayer_ready_to_prepare_cb() \n
 749  *            esplusplayer_close()
 750  */
 751 int esplusplayer_prepare_async(esplusplayer_handle handle);
 752
 753 /**
 754  * @brief     Start playback.
 755  * @param     [in] handle : esplusplayer handle.
 756  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 757  * esplusplayer_error_type
 758  *            values will be returned.
 759  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 760  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 761  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 762  * failed
 763  * @code
 764  *            prepare esplayer done
 765  *            esplusplayer_start(esplayer);
 766  *            // ... your codes ...
 767  *            esplusplayer_stop(esplayer);
 768  * @endcode
 769  * @pre       The player state should be #ESPLUSPLAYER_STATE_READY.
 770  * @post      The player state will be #ESPLUSPLAYER_STATE_PLAYING.
 771  * @exception None
 772  * @see       esplusplayer_open() \n
 773  *            esplusplayer_prepare_async() \n
 774  *            esplusplayer_stop() \n
 775  *            esplusplayer_close()
 776  */
 777 int esplusplayer_start(esplusplayer_handle handle);
 778
 779 /**
 780  * @brief     Stop playing media content.
 781  * @param     [in] handle : esplusplayer handle.
 782  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 783  * esplusplayer_error_type
 784  *            values will be returned.
 785  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 786  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 787  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 788  * failed
 789  * @code
 790  *            prepare esplayer done
 791  *            // ... your codes ...
 792  *            esplusplayer_stop(esplayer);
 793  *             // ... your codes ...
 794  *            esplusplayer_close(esplayer);
 795  * @endcode
 796  * @pre       The player state must be all of #esplusplayer_state except
 797  *            #ESPLUSPLAYER_STATE_NONE.
 798  * @post      The player state will be #ESPLUSPLAYER_STATE_IDLE.
 799  * @exception None
 800  * @remark    esplusplayer_close() must be called once after player is stopped
 801  * @see       esplusplayer_open() \n
 802  *            esplusplayer_prepare_async() \n
 803  *            esplusplayer_start() \n
 804  *            esplusplayer_pause() \n
 805  *            esplusplayer_resume() \n
 806  *            esplusplayer_close()
 807  */
 808 int esplusplayer_stop(esplusplayer_handle handle);
 809
 810 /**
 811  * @brief     Pause playing media content.
 812  * @param     [in] handle : esplusplayer handle.
 813  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 814  * esplusplayer_error_type
 815  *            values will be returned.
 816  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 817  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 818  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 819  * failed
 820  * @code
 821  *            prepare esplayer done
 822  *            // ... your codes ...
 823  *            esplusplayer_pause(esplayer);
 824  *            // ... your codes ...
 825  *            esplusplayer_stop(esplayer);
 826  * @endcode
 827  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY or
 828  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
 829  * @post      The player state will be #ESPLUSPLAYER_STATE_PAUSE.
 830  * @exception None
 831  * @see       esplusplayer_start() \n
 832  *            esplusplayer_resume() \n
 833  *            esplusplayer_prepare_async()
 834  */
 835 int esplusplayer_pause(esplusplayer_handle handle);
 836
 837 /**
 838  * @brief     Resume playing media content.
 839  * @param     [in] handle : esplusplayer handle.
 840  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 841  * esplusplayer_error_type
 842  *            values will be returned.
 843  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 844  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 845  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 846  * failed
 847  * @code
 848  *            prepare esplayer done
 849  *            // ... your codes ...
 850  *            esplusplayer_pause(esplayer);
 851  *            // ... your codes ...
 852  *            esplusplayer_resume(esplayer);
 853  *            // ... your codes ...
 854  *            esplusplayer_stop(esplayer);
 855  * @endcode
 856  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_PAUSED or
 857  *            #ESPLUSPLAYER_STATE_PLAYING.
 858  * @post      The player state will be #ESPLUSPLAYER_STATE_PLAYING.
 859  * @exception None
 860  * @see       esplusplayer_start() \n
 861  *            esplusplayer_pause() \n
 862  *            esplusplayer_prepare_async()
 863  */
 864 int esplusplayer_resume(esplusplayer_handle handle);
 865
 866 /**
 867  * @brief     Set playback rate.
 868  * @param     [in] handle : esplusplayer handle.
 869  * @param     [in] playback_rate :  the playback rate from 0.0 to 2.0.
 870  * @param     [in] audio_mute :  the audio is mute on/off, true: mute on, false:
 871  * mute off.
 872  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 873  * esplusplayer_error_type
 874  *            values will be returned.
 875  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 876  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 877  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 878  * failed
 879  * @code
 880  *            prepare esplayer done
 881  *            // ... your codes ...
 882  *            esplusplayer_set_playback_rate(esplayer,2,true);
 883  *            // ... your codes ...
 884  *            esplusplayer_stop(esplayer);
 885  * @endcode
 886  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY or
 887  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING. \n
 888  *            User has to push the data as fast as playback rate.
 889  * @post      None
 890  * @exception None
 891  * @see       esplusplayer_prepare_async()
 892  */
 893 int esplusplayer_set_playback_rate(esplusplayer_handle handle,
 894                                    const double playback_rate,
 895                                    const bool audio_mute);
 896
 897 /**
 898  * @brief     Seek for playback, asynchronously.
 899  * @param     [in] handle : esplusplayer handle.
 900  * @param     [in] time : seek time default in milliseconds, can be set by
 901  * @esplusplayer_set_timeunit_type
 902  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 903  * esplusplayer_error_type
 904  *            values will be returned.
 905  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 906  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 907  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 908  * failed
 909  * @code
 910  *            prepare esplayer done
 911  *            // ... your codes ...
 912  *            const uint64_t ms_to_seek = 0;
 913  *            esplusplayer_seek(esplayer,ms_to_seek);
 914  *            // ... your codes ...
 915  *            esplusplayer_stop(esplayer);
 916  * @endcode
 917  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY or
 918  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
 919  *            In ESPLUSPLAYER_STATE_IDLE, this api can be called exceptionally
 920  *            between esplusplayer_open() and esplusplayer_prepare_async().
 921  *            the start time of plyabak can be set explicitly when starting
 922  *            first playback. In this case, esplusplayer_set_seek_done_cb is not
 923  *            called.
 924  * @post      None
 925  * @exception None
 926  * @remark    esplusplayer_set_seek_done_cb() will be invoked if seek operation
 927  *            is finished. \n
 928  *            Seek result can be succeeded or not at this moment. \n
 929  *            esplusplayer_set_seek_done_cb() can be invoked only when as many
 930  *            es packets as at least one decoded frame is submitted. \n
 931  *            The player can receive es packets from seek time after
 932  *            esplusplayer_ready_to_seek_cb() is invoked.
 933  * @see       esplusplayer_ready_to_seek_cb() \n
 934  *            esplusplayer_prepare_async()
 935  */
 936 int esplusplayer_seek(esplusplayer_handle handle, uint64_t time);
 937
 938 /**
 939  * @brief     Set App id to esplayer to control resource confliction.
 940  * @param     [in] handle : esplusplayer handle.
 941  * @param     [in] app_info : application id, version, type.
 942  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 943  * esplusplayer_error_type
 944  *            values will be returned.
 945  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 946  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 947  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 948  * failed
 949  * @code
 950  *            esplusplayer_app_info appinfo;
 951  *            appinfo.id = "youtube";
 952  *            appinfo.version = "3.0";
 953  *            appinfo.type = "MSE";
 954  *            esplusplayer_handle esplayer = esplusplayer_create();
 955  *            esplusplayer_open(esplayer);
 956  *            esplusplayer_set_app_info(esplayer,&appinfo);
 957  *            // ... your codes ...
 958  *            esplusplayer_close(esplayer);
 959  * @endcode
 960  * @pre       The player state must be #ESPLUSPLAYER_STATE_IDLE.
 961  * @post      None
 962  * @exception None
 963  * @see       esplusplayer_open()
 964  */
 965 int esplusplayer_set_app_info(esplusplayer_handle handle,
 966                               const esplusplayer_app_info* app_info);
 967
 968 /**
 969  * @brief     Set the video display.
 970  * @param     [in] handle : esplusplayer handle.
 971  * @param     [in] type : display type.
 972  * @param     [in] window : the handle to display window.
 973  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
 974  * esplusplayer_error_type
 975  *            values will be returned.
 976  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 977  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 978  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
 979  * failed
 980  * @code
 981  *            esplusplayer_open(esplayer);
 982  *            esplusplayer_set_display(esplayer,ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY,window);
 983  *            // ... your codes ...
 984  *            esplusplayer_close(esplayer);
 985  * @endcode
 986  * @pre       The player state must be #ESPLUSPLAYER_STATE_IDLE.
 987  * @post      None
 988  * @exception None
 989  * @remark    Esplusplayer is not supporting changing display. \n
 990  *            This API have to be called before calling
 991  *            esplusplayer_prepare_async() to reflect the display type.
 992  * @see       esplusplayer_open() \n
 993  *            esplusplayer_set_display_mode() \n
 994  *            esplusplayer_set_display_roi() \n
 995  *            esplusplayer_set_display_visible()
 996  */
 997 int esplusplayer_set_display(esplusplayer_handle handle,
 998                              esplusplayer_display_type type, void* window);
 999 /**
1000  * @brief     Set the video display.
1001  * @param     [in] handle : esplusplayer handle.
1002  * @param     [in] type : display type.
1003  * @param     [in] subsurface : the ecore wayland subsurface handle.
1004  * @param     [in] x : the x coordinate of subsurface.
1005  * @param     [in] y : the y coordinate of subsurface.
1006  * @param     [in] width : the width of subsurface.
1007  * @param     [in] height : the height of subsurface.
1008  * @return    @c one of esplusplayer_error_type values will be returned.
1009  * @pre       The player state must be #ESPLUSPLAYER_STATE_IDLE.
1010  * @post      None
1011  * @exception   None
1012  * @version   3.1
1013  * @see       esplusplayer_set_display_mode() \n
1014  *            esplusplayer_set_display_roi() \n
1015  *            esplusplayer_set_display_visible()
1016  */
1017 int esplusplayer_set_display_ecore_subsurface(esplusplayer_handle handle,
1018                                               esplusplayer_display_type type,
1019                                               void* subsurface, int x, int y,
1020                                               int width, int height);
1021 /**
1022  * @brief     Set the video display.
1023  * @param     [in] handle : esplusplayer handle.
1024  * @param     [in] type : display type.
1025  * @param     [in] window : the ecore wayland2 window handle.
1026  * @param     [in] x : the x coordinate of window.
1027  * @param     [in] y : the ycoordinate of window.
1028  * @param     [in] width : the width of window.
1029  * @param     [in] height : the height of window.
1030  * @return    @c one of esplusplayer_error_type values will be returned.
1031  * @pre       The player state must be #ESPLUSPLAYER_STATE_IDLE.
1032  * @post      None
1033  * @exception   None
1034  * @version   4.0
1035  * @see       esplusplayer_set_display_mode() \n
1036  *            esplusplayer_set_display_roi() \n
1037  *            esplusplayer_set_display_visible()
1038  */
1039 int esplusplayer_set_ecore_display(esplusplayer_handle handle,
1040                                    esplusplayer_display_type type, void* window,
1041                                    int x, int y, int width, int height);
1042 /**
1043  * @brief     Set the video display mode.
1044  * @param     [in] handle : esplusplayer handle.
1045  * @param     [in] mode : display mode.
1046  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1047  * esplusplayer_error_type
1048  *            values will be returned.
1049  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1050  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1051  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1052  * failed
1053  * @code
1054  *            esplusplayer_open(esplayer);
1055  *            esplusplayer_set_display_mode(esplayer,ESPLUSPLAYER_DISPLAY_MODE_DST_ROI);
1056  *            // ... your codes ...
1057  *            esplusplayer_close(esplayer);
1058  * @endcode
1059  * @pre       The player state can be all of #esplusplayer_state except
1060  *            #ESPLUSPLAYER_STATE_NONE.
1061  * @post      None
1062  * @exception None
1063  * @remark    If no display is set, no operation is performed.
1064  * @see       esplusplayer_open() \n
1065  *            esplusplayer_set_display_mode() \n
1066  *            esplusplayer_set_display_roi() \n
1067  *            esplusplayer_set_display_visible()
1068  */
1069 int esplusplayer_set_display_mode(esplusplayer_handle handle,
1070                                   esplusplayer_display_mode mode);
1071
1072 /**
1073  * @brief     Set the ROI(Region Of Interest) area of display.
1074  * @param     [in] handle : esplusplayer handle.
1075  * @param     [in] x : var startPointX in src video area.
1076  * @param     [in] y : var startPointY in src video area.
1077  * @param     [in] width : width of display in src video area.
1078  * @param     [in] height : height of display in src video area.
1079  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1080  * esplusplayer_error_type
1081  *            values will be returned.
1082  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1083  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1084  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1085  * failed
1086  * @code
1087  *            esplusplayer_open(esplayer);
1088  *            esplusplayer_set_display(esplayer,ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY,window);
1089  *            esplusplayer_set_display_mode(esplayer,ESPLUSPLAYER_DISPLAY_MODE_DST_ROI);
1090  *            esplusplayer_set_display_roi(esplayer,0,0,600,500);
1091  *            // ... your codes ...
1092  *            esplusplayer_close(esplayer);
1093  * @endcode
1094  * @pre       The player state can be all of #esplusplayer_state except
1095  *            #ESPLUSPLAYER_STATE_NONE. \n
1096  *            Before set display ROI, #ESPLUSPLAYER_DISPLAY_MODE_DST_ROI
1097  *            must be set with esplusplayer_set_display_mode().
1098  * @post      None
1099  * @exception None
1100  * @remark    The minimum value of width and height are 1.
1101  * @see       esplusplayer_open() \n
1102  *            esplusplayer_set_display() \n
1103  *            esplusplayer_set_display_mode() \n
1104  *            esplusplayer_set_display_visible()
1105  */
1106 int esplusplayer_set_display_roi(esplusplayer_handle handle, int x, int y,
1107                                  int width, int height);
1108
1109 /**
1110  * @brief     Set the video stretch mode on 21:9 TV.
1111  * @param     [in] handle : esplusplayer handle.
1112  * @param     [in] mode : stretch mode.
1113  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1114  * esplusplayer_error_type
1115  *            values will be returned.
1116  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1117  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1118  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1119  * failed
1120  * @code
1121  *            esplusplayer_open(esplayer);
1122  *            esplusplayer_set_stretch_mode(esplayer,1);
1123  *            // ... your codes ...
1124  *            esplusplayer_close(esplayer);
1125  * @endcode
1126  * @pre       The player state can be all of #esplusplayer_state except
1127  *            #ESPLUSPLAYER_STATE_NONE.
1128  * @post      None
1129  * @exception None
1130  * @version   4.8
1131  * @remark    If no display is set, no operation is performed.
1132  * @see       esplusplayer_open() \n
1133  *            esplusplayer_set_video_roi()
1134  */
1135 int esplusplayer_set_stretch_mode(esplusplayer_handle handle, int mode);
1136
1137 /**
1138  * @brief     Set the Crop Area(Region Of Src ratio) area of display.
1139  * @param     [in] handle : esplusplayer handle.
1140  * @param     [in] scale_x: x label ratio in src video area.
1141  * @param     [in] scale_y: y label ratio in src video area.
1142  * @param     [in] scale_w: width ratio in src video area.
1143  * @param     [in] scale_h: height ratio in src video area.
1144  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1145  * esplusplayer_error_type
1146  *            values will be returned.
1147  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1148  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1149  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1150  * failed
1151  * @code
1152  *            esplusplayer_open(esplayer);
1153  *            esplusplayer_set_display(esplayer,ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY,window);
1154  *            esplusplayer_set_video_roi(esplayer,0,0,0.5,0.5);
1155  *            // ... your codes ...
1156  *            esplusplayer_close(esplayer);
1157  * @endcode
1158  * @pre       The player state can be all of #esplusplayer_state except
1159  *            #ESPLUSPLAYER_STATE_NONE. \n
1160  * @post      None
1161  * @exception None
1162  * @remark    The minimum value of input are 0,maximun value is 1.
1163  * @see       esplusplayer_open() \n
1164  *            esplusplayer_set_display() \n
1165  *            esplusplayer_set_display_visible()
1166  */
1167 int esplusplayer_set_video_roi(esplusplayer_handle handle, double scale_x,
1168                                double scale_y, double scale_w, double scale_h);
1169
1170 /**
1171  * @brief     Resize the render rectangle(the max region that video can be
1172  * displayed).
1173  * @param     [in] handle : esplusplayer handle.
1174  * @param     [in] x: x coordinate of render rectangle.
1175  * @param     [in] y: y coordinate of render rectangle.
1176  * @param     [in] width: width  of render rectangle.
1177  * @param     [in] height: height  of render rectangle.
1178  * @return    @c one of esplusplayer_error_type values will be returned.
1179  * @pre       Should be called after esplusplayer_set_display() \n
1180  *            esplusplayer_set_surface_display() \n
1181  *            esplusplayer_set_ecore_display() \n
1182  *            esplusplayer_set_display_ecore_subsurface
1183  * @post      None
1184  * @exception   None
1185  * @version   3.2
1186  * @remark    The minimum value of width and height are 1.
1187  * @see       esplusplayer_set_display() \n
1188  *            esplusplayer_set_surface_display() \n
1189  *            esplusplayer_set_ecore_display() \n
1190  *            esplusplayer_set_display_ecore_subsurface
1191  */
1192 int esplusplayer_resize_render_rect(esplusplayer_handle handle, int x, int y,
1193                                     int width, int height);
1194
1195 /**
1196  * @brief     Set the visibility of the video display.
1197  * @param     [in] handle : esplusplayer handle.
1198  * @param     [in] visible : the visibility of the display.
1199  *            (@c true = visible, @c false = non-visible)
1200  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1201  * esplusplayer_error_type
1202  *            values will be returned.
1203  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1204  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1205  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1206  * failed
1207  * @code
1208  *            esplusplayer_open(esplayer);
1209  *            esplusplayer_set_display(esplayer,ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY,window);
1210  *            esplusplayer_set_display_visible(esplayer,false);
1211  *            // ... your codes ...
1212  *            esplusplayer_close(esplayer);
1213  * @endcode
1214  * @pre       The player state can be all of #esplusplayer_state except
1215  *            #ESPLUSPLAYER_STATE_NONE.
1216  * @post      None
1217  * @exception   None
1218  * @see       esplusplayer_open() \n
1219  *            esplusplayer_set_display()
1220  */
1221 int esplusplayer_set_display_visible(esplusplayer_handle handle, bool visible);
1222
1223 /**
1224  * @brief     Set the rotate angle of the video display.
1225  * @param     [in] handle : esplusplayer handle.
1226  * @param     [in] rotation : the rotate angle of the display.
1227  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1228  * esplusplayer_error_type
1229  *            values will be returned.
1230  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1231  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1232  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1233  * failed
1234  * @code
1235  *            esplusplayer_open(esplayer);
1236  *            esplusplayer_set_display(esplayer,ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY,window);
1237  *            esplusplayer_set_display_rotation(esplayer_,ESPLUSPLAYER_DISPLAY_ROTATION_TYPE_90);
1238  *            // ... your codes ...
1239  *            esplusplayer_close(esplayer);
1240  * @endcode
1241  * @pre       The player state can be all of #esplusplayer_state except
1242  *            #ESPLUSPLAYER_STATE_NONE.
1243  * @post      this API worked only when video sink created.
1244  * @exception None
1245  * @see       esplusplayer_open() \n
1246  *            esplusplayer_set_display()
1247  */
1248 int esplusplayer_set_display_rotation(
1249     esplusplayer_handle handle, esplusplayer_display_rotation_type rotation);
1250
1251 /**
1252  * @brief     Get the rotate angle of the video display.
1253  * @param     [in] handle : esplusplayer handle.
1254  * @param     [out] rotation : the rotate angle of the display which want to
1255  * get.
1256  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1257  * esplusplayer_error_type
1258  *            values will be returned.
1259  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1260  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1261  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1262  * failed
1263  * @code
1264  *            esplusplayer_open(esplayer);
1265  *            esplusplayer_set_display_rotation(esplayer,ESPLUSPLAYER_DISPLAY_ROTATION_TYPE_90);
1266  *            esplusplayer_display_rotation_type rotation_get =
1267  * ESPLUSPLAYER_DISPLAY_ROTATION_TYPE_NONE;
1268  *            // ... your codes ...
1269  *            esplusplayer_get_display_rotation(esplayer,&rotation_get);
1270  *            // ... your codes ...
1271  *            esplusplayer_close(esplayer);
1272  * @endcode
1273  * @pre       The player state can be all of #esplusplayer_state except
1274  *            #ESPLUSPLAYER_STATE_NONE.
1275  * @post      this API worked only when video sink created.
1276  * @exception None
1277  * @see       esplusplayer_open() \n
1278  *            esplusplayer_set_display_rotation()
1279  */
1280 int esplusplayer_get_display_rotation(
1281     esplusplayer_handle handle, esplusplayer_display_rotation_type* rotation);
1282
1283 /**
1284  * @deprecated Deprecated since API V2.0. Use
1285  *             esplusplayer_set_submit_data_type() instead.
1286  * @brief     Set whether to send decrypted es packets in the trust zone.
1287  * @param     [in] handle : esplusplayer handle.
1288  * @param     [in] using_tz : whether to use trust zone memory.
1289  *            (@c true = if decrypted packets are sent in trust zone, @c false =
1290  *            otherwise @c)
1291  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1292  * esplusplayer_error_type
1293  *            values will be returned.
1294  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1295  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1296  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1297  * failed
1298  * @code
1299  *            esplusplayer_open(esplayer);
1300  *            esplusplayer_set_tz_use(esplayer, true);
1301  *            // ... your codes ...
1302  *            esplusplayer_close(esplayer);
1303  * @endcode
1304  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
1305  * @post      None
1306  * @exception None
1307  * @remark    This API have to be called before calling
1308  *            esplusplayer_prepare_async(). \n If using_tz is set to true, use
1309  *            esplusplayer_submit_trust_zone_packet() to send decrypted packets.
1310  * @see       esplusplayer_open() \n
1311  *            esplusplayer_submit_trust_zone_packet()
1312  */
1313 int esplusplayer_set_tz_use(esplusplayer_handle handle, bool using_tz);
1314
1315 /**
1316  * @brief     Set whether to send decrypted es packets in the trust zone or
1317  *            encrypted es packets.
1318  * @param     [in] handle : esplusplayer handle.
1319  * @param     [in] type : whether to use trust zone memory or encrypted data
1320  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1321  * esplusplayer_error_type
1322  *            values will be returned.
1323  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1324  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1325  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1326  * failed
1327  * @code
1328  *            esplusplayer_open(esplayer);
1329  *            esplusplayer_set_submit_data_type(esplayer,ESPLUSPLAYER_SUBMIT_DATA_TYPE_CLEAN_DATA);
1330  *            // ... your codes ...
1331  *            esplusplayer_close(esplayer);
1332  * @endcode
1333  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
1334  * @post      None
1335  * @exception None
1336  * @remark    This API have to be called before calling
1337  *            esplusplayer_prepare_async(). \n
1338  *            If type is ESPLUSPLAYER_SUBMIT_DATA_TYPE_CLEAN_DATA use
1339  *            esplusplayer_submit_packet() to send clean packets. \n
1340  *            If type is ESPLUSPLAYER_SUBMIT_DATA_TYPE_TRUSTZONE_DATA, use
1341  *            esplusplayer_submit_trust_zone_packet() to send decrypted packets
1342  *            in trust zone \n
1343  *            If type is ESPLUSPLAYER_SUBMIT_DATA_TYPE_ENCRYPTED_DATA, use
1344  *            esplusplayer_submit_encrypted_packet() to send encrypted packets.
1345  * @see       esplusplayer_open() \n
1346  *            esplusplayer_submit_trust_zone_packet() \n
1347  *            esplusplayer_submit_encrypted_packet() \n
1348  *            esplusplayer_submit_data_type
1349  */
1350 int esplusplayer_set_submit_data_type(esplusplayer_handle handle,
1351                                       esplusplayer_submit_data_type type);
1352
1353 /**
1354  * @brief     Set on mute of the audio sound.
1355  * @param     [in] handle : esplusplayer handle.
1356  * @param     [in] mute : on mute of the sound.
1357  *            (@c true = mute, @c false = non-mute)
1358  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success, otherwise @c one of
1359  * esplusplayer_error_type
1360  *            values will be returned.
1361  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1362  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1363  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1364  * failed
1365  * @code
1366  *            esplusplayer_open(esplayer);
1367  *            esplusplayer_set_audio_mute(esplayer, true);
1368  *            // ... your codes ...
1369  *            esplusplayer_close(esplayer);
1370  * @endcode
1371  * @pre       The player state can be all of #esplusplayer_state except
1372  *            #ESPLUSPLAYER_STATE_NONE.
1373  * @post      None
1374  * @exception None
1375  * @see       esplusplayer_open()
1376  */
1377 int esplusplayer_set_audio_mute(esplusplayer_handle handle, bool mute);
1378
1379 /**
1380  * @brief     Get current state of player.
1381  * @param     [in] handle : esplusplayer handle.
1382  * @return    current #esplusplayer_state of player.
1383  * @code
1384  *            esplusplayer_handle esplayer = esplusplayer_create();
1385  *            // ... your codes ...
1386  *            esplusplayer_state ret = esplusplayer_get_state(esplayer);
1387  *            // ... your codes ...
1388  *            esplusplayer_destroy(esplayer);
1389  * @endcode
1390  * @pre       None
1391  * @post      None
1392  * @exception None
1393  */
1394 esplusplayer_state esplusplayer_get_state(esplusplayer_handle handle);
1395
1396 /**
1397  * @brief     Submit es packet to decode audio or video.
1398  * @param     [in] handle : esplusplayer handle.
1399  * @param     [in] packet : es packet pointer.
1400  * @return    @c ESPLUSPLAYER_SUBMIT_STATUS_SUCCESS : succeed to submit es
1401  *            packet,
1402  *            otherwise @c : fail to submit es packet.
1403  * @code
1404  *            static void OnPrepareDone(bool ret, void* userdata) {
1405  *                // ... your codes ...
1406  *                printf ("OnPrepareDone\n");
1407  *            }
1408  *            static void OnReadyToPrepare(const esplusplayer_stream_type
1409  *type,void* userdata) {
1410  *                if (type == ESPLUSPLAYER_STREAM_TYPE_VIDEO) {
1411  *                    //Something you want to do when feed es video stream is
1412  *allowed
1413  *                } else {
1414  *                    //Something you want to do when feed es audio stream is
1415  *allowed
1416  *                }
1417  *                //Something you want to do when OnReadyToPrepare
1418  *                printf ("OnReadyToPrepare\n");
1419  *            }
1420  *            static void OnBufferByteStatus(const esplusplayer_stream_type
1421  *type,
1422  *                                           const esplusplayer_buffer_status
1423  *status,
1424  *                                           uint64_t byte_size, void* userdata)
1425  *{
1426  *                if (type == ESPLUSPLAYER_STREAM_TYPE_VIDEO) {
1427  *                    if (status == ESPLUSPLAYER_BUFFER_STATUS_UNDERRUN) {
1428  *                        //Something you want to do when es video buffer is
1429  *enough
1430  *                    } else {
1431  *                        //Something you want to do when es video buffer is not
1432  *enough
1433  *                    }
1434  *                } else {
1435  *                    if (status == ESPLUSPLAYER_BUFFER_STATUS_UNDERRUN) {
1436  *                        //Something you want to do when es audio buffer is
1437  *enough
1438  *                    } else {
1439  *                        //Something you want to do when es audio buffer is not
1440  *enough
1441  *                    }
1442  *                }
1443  *                //Something you want to do when OnBufferByteStatus
1444  *                printf ("OnBufferByteStatus\n");
1445  *            }
1446  *            static void OnBufferTimeStatus(const esplusplayer_stream_type
1447  *type,
1448  *                                           const esplusplayer_buffer_status
1449  *status,
1450  *                                           uint64_t time_size,void* userdata)
1451  *{
1452  *                if (type == ESPLUSPLAYER_STREAM_TYPE_VIDEO) {
1453  *                    if (status == ESPLUSPLAYER_BUFFER_STATUS_UNDERRUN) {
1454  *                        //Something you want to do when es video buffer is
1455  *enough
1456  *                    } else {
1457  *                        //Something you want to do when es video buffer is not
1458  *enough
1459  *                    }
1460  *                } else {
1461  *                    if (status == ESPLUSPLAYER_BUFFER_STATUS_UNDERRUN) {
1462  *                        //Something you want to do when es audio buffer is
1463  *enough
1464  *                    } else {
1465  *                        //Something you want to do when es audio buffer is not
1466  *enough
1467  *                    }
1468  *                }
1469  *                //Something you want to do when OnBufferTimeStatus
1470  *                printf ("OnBufferTimeStatus\n");
1471  *            }
1472  *            void FeedEsPacket(esplusplayer_handle
1473  *player,esplusplayer_es_packet pkt) {
1474  *               // ... your codes ...
1475  *               if(feed is allowed && buffer is enough) {
1476  *                   esplusplayer_submit_packet(player, &pkt);
1477  *               }
1478  *               // ... your codes ...
1479  *           )
1480  *            esplusplayer_handle esplayer = esplusplayer_create();
1481  *            esplusplayer_set_prepare_async_done_cb(esplayer,OnPrepareDone,&esplayer);
1482  *            esplusplayer_set_ready_to_prepare_cb(esplayer,OnReadyToPrepare,&esplayer);
1483  *            esplusplayer_set_buffer_byte_status_cb(esplayer,OnBufferByteStatus,&esplayer);
1484  *            esplusplayer_set_buffer_time_status_cb(esplayer,OnBufferTimeStatus,&esplayer);
1485  *            esplusplayer_open(esplayer);
1486  *            esplusplayer_prepare_async(esplayer);
1487  *            // ... your codes ...
1488  *            //FeedEsPacket()(call a new thread to do this)
1489  *            // ... your codes ...
1490  *            esplusplayer_close(esplayer);
1491  *            esplusplayer_destroy(esplayer);
1492  * @endcode
1493  * @pre       User can submit es packets after
1494  *            esplusplayer_ready_to_prepare_cb() or
1495  *            esplusplayer_ready_to_seek_cb() is called.
1496  * @post      None
1497  * @exception None
1498  * @remark    Amount of packets for at least one decoded frame must be submitted
1499  *            after calling esplusplayer_prepare_async() or esplusplayer_seek()
1500  *            for invoking esplusplayer_prepare_async_done_cb() or
1501  *            esplusplayer_seek_done_cb() \n
1502  *            This api must be called from a different thread than other apis.
1503  * @see       esplusplayer_set_submit_data_type() \n
1504  *            esplusplayer_es_packet \n
1505  *            esplusplayer_buffer_status_cb() \n
1506  *            esplusplayer_ready_to_prepare_cb() \n
1507  *            esplusplayer_ready_to_seek_cb()
1508  */
1509 esplusplayer_submit_status esplusplayer_submit_packet(
1510     esplusplayer_handle handle, esplusplayer_es_packet* packet);
1511
1512 /**
1513  * @brief     Submit es packet to decode audio or video.
1514  * @param     [in] handle : esplusplayer handle.
1515  * @param     [in] packet : es packet pointer.
1516  * @param     [in] tz_handle : es decrypted tz handle.
1517  * @return    @c ESPLUSPLAYER_SUBMIT_STATUS_SUCCESS : succeed to submit es
1518  *            packet,
1519  *            otherwise @c : fail to submit es packet.
1520  * @code
1521  *            refer to the sample code of esplusplayer_submit_packet();
1522  * @endcode
1523  * @pre       User can submit es packets after
1524  *            esplusplayer_ready_to_prepare_cb() or
1525  *            esplusplayer_ready_to_seek_cb() is called.
1526  * @post      None
1527  * @exception None
1528  * @remark    Amount of packets for at least one decoded frame must be submitted
1529  *            after calling esplusplayer_prepare_async() or esplusplayer_seek()
1530  *            for invoking esplusplayer_prepare_async_done_cb() or
1531  *            esplusplayer_seek_done_cb(). \n
1532  *            To use this api, Must set
1533  * ESPLUSPLAYER_SUBMIT_DATA_TYPE_TRUSTZONE_DATA using
1534  * esplusplayer_set_submit_data_type() \n This api must be called from a
1535  * different thread than other apis.
1536  * @see       esplusplayer_es_packet \n
1537  *            esplusplayer_buffer_status_cb() \n
1538  *            esplusplayer_ready_to_prepare_cb() \n
1539  *            esplusplayer_ready_to_seek_cb()
1540  */
1541 esplusplayer_submit_status esplusplayer_submit_trust_zone_packet(
1542     esplusplayer_handle handle, esplusplayer_es_packet* packet,
1543     uint32_t tz_handle);
1544
1545 /**
1546  * @brief     Submit encrypted es packet to decode and decrypt audio or video.
1547  * @param     [in] handle : esplusplayer handle.
1548  * @param     [in] packet : es packet pointer.
1549  * @param     [in] drm_info : information to decrypt es packet.
1550  *                            esplusplayer doesn't take ownership. user should
1551  *                            free it. if you deliver it as (null), this api
1552  *                            works as esplusplayer_submit_packet().
1553  * @return    @c ESPLUSPLAYER_SUBMIT_STATUS_SUCCESS : succeed to submit es
1554  *            packet,
1555  *            otherwise @c : fail to submit es packet.
1556  * @code
1557  *            refer to the sample code of esplusplayer_submit_packet();
1558  * @endcode
1559  * @pre       User can submit es packets after
1560  *            esplusplayer_ready_to_prepare_cb() or
1561  *            esplusplayer_ready_to_seek_cb() is called.
1562  * @post      None
1563  * @exception None
1564  * @remark    Amount of packets for at least one decoded frame must be submitted
1565  *            after calling esplusplayer_prepare_async() or esplusplayer_seek()
1566  *            for invoking esplusplayer_prepare_async_done_cb() or
1567  *            esplusplayer_seek_done_cb(). \n
1568  *            To use this api, Must set
1569  * ESPLUSPLAYER_SUBMIT_DATA_TYPE_ENCRYPTED_DATA using
1570  * esplusplayer_set_submit_data_type() \n This api must be called from a
1571  * different thread than other apis.
1572  * @see       esplusplayer_es_packet \n
1573  *            esplusplayer_drm_info_64bit \n
1574  *            esplusplayer_buffer_status_cb() \n
1575  *            esplusplayer_ready_to_prepare_cb() \n
1576  *            esplusplayer_ready_to_seek_cb() \n
1577  *            esplusplayer_submit_packet()
1578  *@version 6.0
1579  */
1580 esplusplayer_submit_status esplusplayer_submit_encrypted_packet_64bit(
1581     esplusplayer_handle handle, esplusplayer_es_packet* packet,
1582     esplusplayer_drm_info_64bit* drm_info);
1583
1584 /**
1585  * @brief     Submit encrypted es packet to decode and decrypt audio or video.
1586  * @param     [in] handle : esplusplayer handle.
1587  * @param     [in] packet : es packet pointer.
1588  * @param     [in] drm_info : information to decrypt es packet.
1589  *                            esplusplayer doesn't take ownership. user should
1590  *                            free it. if you deliver it as (null), this api
1591  *                            works as esplusplayer_submit_packet().
1592  * @return    @c ESPLUSPLAYER_SUBMIT_STATUS_SUCCESS : succeed to submit es
1593  *            packet,
1594  *            otherwise @c : fail to submit es packet.
1595  * @code
1596  *            refer to the sample code of esplusplayer_submit_packet();
1597  * @endcode
1598  * @pre       User can submit es packets after
1599  *            esplusplayer_ready_to_prepare_cb() or
1600  *            esplusplayer_ready_to_seek_cb() is called.
1601  * @post      None
1602  * @exception None
1603  * @remark    Amount of packets for at least one decoded frame must be submitted
1604  *            after calling esplusplayer_prepare_async() or esplusplayer_seek()
1605  *            for invoking esplusplayer_prepare_async_done_cb() or
1606  *            esplusplayer_seek_done_cb(). \n
1607  *            To use this api, Must set
1608  * ESPLUSPLAYER_SUBMIT_DATA_TYPE_ENCRYPTED_DATA using
1609  * esplusplayer_set_submit_data_type() \n This api must be called from a
1610  * different thread than other apis.
1611  * @see       esplusplayer_es_packet \n
1612  *            esplusplayer_drm_info \n
1613  *            esplusplayer_buffer_status_cb() \n
1614  *            esplusplayer_ready_to_prepare_cb() \n
1615  *            esplusplayer_ready_to_seek_cb() \n
1616  *            esplusplayer_submit_packet()
1617  */
1618 esplusplayer_submit_status esplusplayer_submit_encrypted_packet(
1619     esplusplayer_handle handle, esplusplayer_es_packet* packet,
1620     esplusplayer_drm_info* drm_info);
1621
1622 /**
1623  * @brief     Generate EOS(End Of Stream) packet explicitly and submit it to the
1624  *            player.
1625  * @param     [in] handle : esplusplayer handle.
1626  * @param     [in] type : stream type which reaches eos.
1627  * @return    @c ESPLUSPLAYER_SUBMIT_STATUS_SUCCESS : succeed to submit EOS
1628  * packet,
1629  *            otherwise @c : fail to submit EOS packet.
1630  * @code
1631  *            esplusplayer_handle esplayer = esplusplayer_create();
1632  *            // ... your codes ...
1633  *            esplusplayer_submit_eos_packet(esplayer,ESPLUSPLAYER_STREAM_TYPE_VIDEO);
1634  *            // ... your codes ...
1635  * @endcode
1636  * @pre       None
1637  * @post      None
1638  * @exception None
1639  */
1640 esplusplayer_submit_status esplusplayer_submit_eos_packet(
1641     esplusplayer_handle handle, esplusplayer_stream_type type);
1642
1643 /**
1644  * @brief     Set audio stream to have contents information.
1645  * @param     [in] handle : esplusplayer handle.
1646  * @param     [in] stream : audio stream pointer.
1647  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1648  * esplusplayer_error_type
1649  *            values will be returned.
1650  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1651  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1652  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1653  * failed
1654  * @code
1655  *            esplusplayer_open(esplayer);
1656  *            esplusplayer_audio_stream_info audio_stream;
1657  *            audio_stream.codec_data = nullptr;
1658  *            audio_stream.codec_data_length = 0;
1659  *            esplusplayer_set_audio_stream_info(esplayer, &audio_stream);
1660  *            // ... your codes ...
1661  *            esplusplayer_close(esplayer);
1662  * @endcode
1663  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE except
1664  *            audio stream is deactivated.
1665  * @post      None
1666  * @exception None
1667  * @remark    This API have to be called before calling the
1668  *            esplusplayer_prepare_async().
1669  * @see       esplusplayer_open() \n
1670  *            esplusplayer_audio_stream_info
1671  */
1672 int esplusplayer_set_audio_stream_info(esplusplayer_handle handle,
1673                                        esplusplayer_audio_stream_info* stream);
1674
1675 /**
1676  * @brief     Set video stream to have contents information.
1677  * @param     [in] handle : esplusplayer handle.
1678  * @param     [in] stream : video stream pointer.
1679  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1680  * esplusplayer_error_type
1681  *            values will be returned.
1682  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1683  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1684  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1685  * failed
1686  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE except
1687  *            video stream is deactivated.
1688  * @post      None
1689  * @exception None
1690  * @remark    This API have to be called before calling the
1691  *            esplusplayer_prepare_async().
1692  * @see       esplusplayer_audio_stream_info
1693  *            esplusplayer_activate
1694  */
1695 int esplusplayer_set_video_stream_info(esplusplayer_handle handle,
1696                                        esplusplayer_video_stream_info* stream);
1697
1698 /**
1699  * @brief     Get the current playing time of the associated media.
1700  * @param     [in] handle : esplusplayer handle.
1701  * @param     [out] cur_time : current playing time default in milliseconds, can
1702  * be set by @esplusplayer_set_timeunit_type
1703  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1704  * esplusplayer_error_type
1705  *            values will be returned.
1706  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1707  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1708  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1709  * failed
1710  * @code
1711  *            prepare esplayer done
1712  *            esplusplayer_start(esplayer);
1713  *            // ... your codes ...
1714  *            uint64_t cur_time = 0;
1715  *            esplusplayer_get_playing_time(esplayer, &cur_time);
1716  *            // ... your codes ...
1717  *            esplusplayer_stop(esplayer);
1718  * @endcode
1719  * @pre       The player must be one of #ESPLUSPLAYER_STATE_PAUSE or
1720  *            #ESPLUSPLAYER_STATE_PLAYING.
1721  * @post      None
1722  * @exception None
1723  * @see       esplusplayer_prepare_async()
1724  */
1725 int esplusplayer_get_playing_time(esplusplayer_handle handle,
1726                                   uint64_t* cur_time);
1727 /**
1728  * @brief     Get dropped frame counts in videosink.
1729  * @param     [in] handle : esplusplayer handle.
1730  * @param     [out] padaptive_info : dropped frame counts.
1731  * @param     [in] adaptive_type : type of adaptive info which APP want to get.
1732  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1733  * esplusplayer_error_type
1734  *            values will be returned.
1735  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1736  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1737  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1738  * failed
1739  * @code
1740  *            prepare esplayer done
1741  *            // ... your codes ...
1742  *            uint64_t count = 0;
1743  *            esplusplayer_get_adaptive_info(esplayer,
1744  *                static_cast<void*>(&count),ESPLUSPLAYER_ADAPT_INFO_TYPE_DROPPED_FRAMES);
1745  *            // ... your codes ...
1746  *            esplusplayer_stop(esplayer);
1747  * @endcode
1748  * @pre       The player must be one of #ESPLUSPLAYER_STATE_READY,
1749  *                    #ESPLUSPLAYER_STATE_PAUSE or #ESPLUSPLAYER_STATE_PLAYING.
1750  * @post      None
1751  * @exception None
1752  * @see       esplusplayer_prepare_async()
1753  */
1754 int esplusplayer_get_adaptive_info(
1755     esplusplayer_handle handle, void* padaptive_info,
1756     esplusplayer_adaptive_info_type adaptive_type);
1757
1758 /**
1759  * @brief     Set volume to player
1760  * @param     [in] handle : esplusplayer handle.
1761  * @param     [in] volume : volume level(0 ~ 100).
1762  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1763  * esplusplayer_error_type
1764  *            values will be returned.
1765  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1766  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1767  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1768  * failed
1769  * @code
1770  *            esplusplayer_open(esplayer);
1771  *            int vol = 80;
1772  *            esplusplayer_set_volume(esplayer, vol)
1773  *            // ... your codes ...
1774  *            esplusplayer_close(esplayer);
1775  * @endcode
1776  * @pre       The player state must be not #ESPLUSPLAYER_STATE_NONE.
1777  * @post      None
1778  * @exception None
1779  * @see       esplusplayer_open()
1780  */
1781 int esplusplayer_set_volume(esplusplayer_handle handle, const int volume);
1782
1783 /**
1784  * @brief     Get volume from player
1785  * @param     [in] handle : esplusplayer handle.
1786  * @param     [out] volume : volume ptr.
1787  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1788  * esplusplayer_error_type
1789  *            values will be returned.
1790  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1791  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1792  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1793  * failed
1794  * @code
1795  *            esplusplayer_open(esplayer);
1796  *            // ... your codes ...
1797  *            int vol = 0;
1798  *            esplusplayer_get_volume(esplayer, &vol)
1799  *            // ... your codes ...
1800  *            esplusplayer_close(esplayer);
1801  * @endcode
1802  * @pre       The player state must be not #ESPLUSPLAYER_STATE_NONE.
1803  * @post      None
1804  * @exception None
1805  * @see       esplusplayer_open()
1806  */
1807 int esplusplayer_get_volume(esplusplayer_handle handle, int* volume);
1808
1809 /**
1810  * @brief     Set decoded video frame buffer type.
1811  * @param     [in] handle : esplusplayer handle.
1812  * @param     [in] type : one of the video decoded buffer type to set .
1813  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1814  esplusplayer_error_type
1815  *            values will be returned.
1816  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1817  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1818  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1819  failed
1820  * @code
1821  *            esplusplayer_open(esplayer);
1822  *            esplusplayer_set_video_frame_buffer_type(esplayer,
1823  *                ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_NONE);
1824  *            // ... your codes ...
1825  *            esplusplayer_close(esplayer);
1826  * @endcode
1827  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE when type
1828               is not equal to be
1829  ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_SCALE
1830               The player state must be not #ESPLUSPLAYER_STATE_NONE when
1831               type is equal to be
1832  ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_SCALE
1833  * @post      None
1834  * @exception None
1835  * @remark    reference can't support sw codec type.
1836  *            esplusplayer_set_media_packet_video_decoded_cb()
1837  *            esplusplayer_set_video_codec_type()
1838  *            when type is SCALE, the target scale resolution can be set by
1839  *            esplusplayer_set_video_frame_buffer_scale_resolution()
1840  * @see       esplusplayer_open()
1841  */
1842 int esplusplayer_set_video_frame_buffer_type(
1843     esplusplayer_handle handle,
1844     esplusplayer_decoded_video_frame_buffer_type type);
1845
1846 /**
1847  * @brief     Set the request frame rate of decoded video
1848  * @param     [in] handle : esplusplayer handle.
1849  * @param     [in] request_framerate : the request frame rate of returned
1850  * decoded video frame
1851  *                 The value of track_framerate(A) and request_framerate(B)
1852  * should be one of the following sets:
1853  *                 track_framerate indicate the frame rate of input video stream
1854  *                 1.A/(A-B) = X ,X means drop 1 frame every X frame
1855  *                 2.Special cases,such as 24000/1000 -> 15000/1000
1856  *                 when request_framerate.num = 0, return none decoded video
1857  * frame
1858  *                 when request_framerate.num/request_framerate.den =
1859  *                   track_framerate.num/track_framerate.den, return all decoded
1860  *                   video frame
1861  *                 when request_framerate.num/request_framerate.den <
1862  *                   track_framerate.num/track_framerate.den, drop some decoded
1863  *                   video frame
1864  * @return    @c one of esplusplayer_error_type values will be returned.
1865  * @pre       The player state must be not #ESPLUSPLAYER_STATE_NONE.
1866  * @post      None
1867  * @exception   None
1868  * @version   3.4
1869  * @remark    only works when decoded video frame buffer type is scale
1870  *            esplusplayer_set_video_frame_buffer_type()
1871  *            esplusplayer_set_media_packet_video_decoded_cb()
1872  */
1873 int esplusplayer_set_decoded_video_frame_rate(
1874     esplusplayer_handle handle, esplusplayer_rational request_framerate);
1875
1876 /**
1877  * @brief     Set the target scale resolution when decoded video frame buffer
1878  * type is scale
1879  * @param     [in] handle : esplusplayer handle.
1880  * @param     [in] target_width : scale target width of video frame buffer.
1881  * @param     [in] target_width : scale target height of video frame buffer.
1882  * @return    @c one of esplusplayer_error_type values will be returned.
1883  * @pre       The player state can be set in all states except
1884  * #ESPLUSPLAYER_STATE_NONE.
1885  * @post      None
1886  * @exception   None
1887  * @version   3.1
1888  * @remark    esplusplayer_set_video_frame_buffer_type()
1889  *            esplusplayer_set_media_packet_video_decoded_cb()
1890  *            If user don't call this api to set target_width and target_height,
1891  * the default
1892  *            target scale resolution is 960x540
1893  */
1894 int esplusplayer_set_video_frame_buffer_scale_resolution(
1895     esplusplayer_handle handle, uint32_t target_width, uint32_t target_height);
1896
1897 /**
1898  * @brief     Flush buffers for a player.
1899  * @param     [in] handle : esplusplayer handle ptr.
1900  * @param     [in] type : choose which stream data need to be
1901  *            flush,audio/video,if need flush all pipeline can call this API
1902  * twice.
1903  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1904  * esplusplayer_error_type
1905  *            values will be returned.
1906  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1907  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1908  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1909  * failed
1910  * @code
1911  *            prepare esplayer done
1912  *            // ... your codes ...
1913  *            esplusplayer_flush(esplayer, ESPLUSPLAYER_STREAM_TYPE_VIDEO);
1914  *            // ... your codes ...
1915  *            esplusplayer_stop(esplayer);
1916  * @endcode
1917  * @pre       The player state should greater than #ESPLUSPLAYER_STATE_IDLE
1918  * @post      None
1919  * @exception None
1920  * @see       esplusplayer_prepare_async()
1921  */
1922 int esplusplayer_flush(esplusplayer_handle handle,
1923                        esplusplayer_stream_type type);
1924
1925 /**
1926  * @brief     Convert the esplusplayer error type to a string.
1927  * @param     [in] type : esplusplayer error type
1928  * @return    @c not nullptr  the converted error string otherwise @c failed to
1929  *            convert the error.
1930  * @code
1931  *            // ... your codes ...
1932  *            const char* error;
1933  *            error =
1934  * esplusplayer_get_error_string(ESPLUSPLAYER_ERROR_TYPE_NOT_SUPPORTED_FILE);
1935  *            // ... your codes ...
1936  * @endcode
1937  * @pre       None
1938  * @post      None
1939  * @exception None
1940  */
1941 const char* esplusplayer_get_error_string(esplusplayer_error_type type);
1942
1943 /**
1944  * @brief     Sets a callback function to be invoked when an error occurs.
1945  * @param     [in] handle : esplusplayer handle.
1946  * @param     [in] error_cb : the error callback function to register.
1947  * @param     [in] userdata : userdata of esplusplayer_error_cb()
1948  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1949  * esplusplayer_error_type
1950  *            values will be returned.
1951  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1952  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1953  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1954  * failed
1955  * @code
1956  *            static void OnError(const esplusplayer_error_type err_code, void*
1957  *                userdata) {
1958  *                //Something you want to do when error occur
1959  *                printf ("OnError\n");
1960  *            }
1961  *            esplusplayer_handle esplayer = esplusplayer_create();
1962  *            esplusplayer_set_error_cb(esplayer, OnError, nullptr);
1963  *            // ... your codes ...
1964  *            esplusplayer_destroy(esplayer);
1965  * @endcode
1966  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1967  *            or #ESPLUSPLAYER_STATE_IDLE.
1968  * @post      esplusplayer_error_cb() will be invoked.
1969  * @exception None
1970  * @remark    esplusplayer_error_cb()
1971  *            if error_cb is set to null, esplusplayer_error_cb() will not be
1972  *            invoked anymore.
1973  */
1974 int esplusplayer_set_error_cb(esplusplayer_handle handle,
1975                               esplusplayer_error_cb error_cb, void* userdata);
1976
1977 /**
1978  * @brief     Set a callback function to be invoked when buffer underrun or
1979  *            overflow is occurred.
1980  * @param     [in] handle : esplusplayer handle.
1981  * @param     [in] buffer_status_cb : the buffer status callback function to
1982  * register.
1983  * @param     [in] userdata : userdata of esplusplayer_buffer_status_cb()
1984  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
1985  * esplusplayer_error_type
1986  *            values will be returned.
1987  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1988  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1989  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
1990  * failed
1991  * @code
1992  *            refer to the sample code of esplusplayer_set_error_cb();
1993  * @endcode
1994  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1995  *            or #ESPLUSPLAYER_STATE_IDLE.
1996  * @post      esplusplayer_buffer_status_cb() will be invoked.
1997  * @exception None
1998  * @remark    esplusplayer_buffer_status_cb()
1999  *            if buffer_status_cb is set to null,
2000  *            esplusplayer_buffer_status_cb() will not be invoked anymore.
2001  */
2002 int esplusplayer_set_buffer_status_cb(
2003     esplusplayer_handle handle, esplusplayer_buffer_status_cb buffer_status_cb,
2004     void* userdata);
2005
2006 /**
2007  * @brief     Set a callback function to be invoked when buffer underrun or
2008  *            overflow is occurred and buffer size in byte will be passed.
2009  * @param     [in] handle : esplusplayer handle.
2010  * @param     [in] buffer_status_cb : the buffer byte status callback function
2011  *            to register.
2012  * @param     [in] userdata : userdata of esplusplayer_buffer_byte_status_cb()
2013  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2014  * esplusplayer_error_type
2015  *            values will be returned.
2016  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2017  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2018  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2019  * failed
2020  * @code
2021  *            refer to the sample code of esplusplayer_submit_packet();
2022  * @endcode
2023  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2024  *            or #ESPLUSPLAYER_STATE_IDLE.
2025  * @post      esplusplayer_buffer_byte_status_cb() will be invoked.
2026  * @exception None
2027  * @remark    esplusplayer_buffer_byte_status_cb()
2028  */
2029 int esplusplayer_set_buffer_byte_status_cb(
2030     esplusplayer_handle handle,
2031     esplusplayer_buffer_byte_status_cb buffer_status_cb, void* userdata);
2032
2033 /**
2034  * @brief     Set a callback function to be invoked when buffer underrun or
2035  *            overflow is occurred and buffer size in time will be passed.
2036  * @param     [in] handle : esplusplayer handle.
2037  * @param     [in] buffer_status_cb : the buffer time status callback function
2038  *            to register.
2039  * @param     [in] userdata : userdata of esplusplayer_buffer_time_status_cb()
2040  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2041  esplusplayer_error_type
2042  *            values will be returned.
2043  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2044  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2045  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2046  failed
2047  * @code
2048               refer to the sample code of esplusplayer_submit_packet();
2049  * @endcode
2050  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2051  *            or #ESPLUSPLAYER_STATE_IDLE.
2052  * @post      esplusplayer_buffer_time_status_cb() will be invoked.
2053  * @exception None
2054  * @remark    esplusplayer_buffer_time_status_cb(),
2055  *            esplusplayer_buffer_time_status_cb() will be invoked only
2056  *            when the duration value of espacket is set.
2057  *            if buffer_status_cb is set to null,
2058  *            esplusplayer_buffer_time_status_cb() will not be invoked anymore.
2059  */
2060 int esplusplayer_set_buffer_time_status_cb(
2061     esplusplayer_handle handle,
2062     esplusplayer_buffer_time_status_cb buffer_status_cb, void* userdata);
2063
2064 /**
2065  * @brief     Set a callback function to be invoked when video latency status
2066  *            is changed.
2067  * @param     [in] handle : esplusplayer handle.
2068  * @param     [in] video_latency_status_cb : the video latency status callback
2069  * function to register.
2070  * @param     [in] userdata : userdata of
2071  *             esplusplayer_set_video_latency_status_cb()
2072  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2073  * esplusplayer_error_type
2074  *            values will be returned.
2075  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2076  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2077  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2078  * failed
2079  * @code
2080  *            refer to the sample code of esplusplayer_set_error_cb();
2081  * @endcode
2082  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2083  *            or #ESPLUSPLAYER_STATE_IDLE.
2084  * @post      esplusplayer_video_latency_status_cb() will be invoked.
2085  * @exception None
2086  * @version   2.7
2087  * @remark    esplusplayer_video_latency_status_cb() will be invoked only
2088  *            when mid / high latency threshold is set.
2089  */
2090 int esplusplayer_set_video_latency_status_cb(
2091     esplusplayer_handle handle,
2092     esplusplayer_video_latency_status_cb video_latency_status_cb,
2093     void* userdata);
2094
2095 /**
2096  * @brief     Set a callback function to be invoked when audio latency status
2097  * is changed.
2098  * @param     [in] handle : esplusplayer handle.
2099  * @param     [in] audio_latency_status_cb : the audio latency status callback
2100  * function to register.
2101  * @param     [in] userdata : userdata of
2102  *            esplusplayer_set_audio_latency_status_cb()
2103  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2104  * esplusplayer_error_type
2105  *            values will be returned.
2106  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2107  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2108  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2109  * failed
2110  * @code
2111  *            refer to the sample code of esplusplayer_set_error_cb();
2112  * @endcode
2113  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2114  *            or #ESPLUSPLAYER_STATE_IDLE.
2115  * @post      esplusplayer_audio_latency_status_cb() will be invoked.
2116  * @exception None
2117  * @version   2.7
2118  * @remark    esplusplayer_audio_latency_status_cb() will be invoked only
2119  *            when mid / high latency threshold is set.
2120  */
2121 int esplusplayer_set_audio_latency_status_cb(
2122     esplusplayer_handle handle,
2123     esplusplayer_audio_latency_status_cb audio_latency_status_cb,
2124     void* userdata);
2125
2126 /**
2127  * @brief     Set buffer size with different option
2128  * @param     [in] handle : esplusplayer handle.
2129  * @param     [in] option : the option of buffer size.
2130  * @param     [in] size : size of selected buffer option.
2131  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2132  * esplusplayer_error_type
2133  *            values will be returned.
2134  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2135  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2136  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2137  * failed
2138  * @code
2139  *            esplusplayer_open(esplayer);
2140  *            esplusplayer_set_buffer_size(esplayer,ESPLUSPLAYER_BUFFER_AUDIO_MAX_BYTE_SIZE,10240)
2141  *            // ... your codes ...
2142  *            esplusplayer_close(esplayer);
2143  * @endcode
2144  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
2145  *            When the stream is deactivated, it can be set in
2146  *            #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PAUSED and
2147  *            #ESPLUSPLAYER_STATE_PLAYING. The changed buffer size will be
2148  *            applied when esplusplayer_activate() is called.
2149  * @post      None
2150  * @exception None
2151  * @remark    esplusplayer_buffer_option
2152  * @see       esplusplayer_open() \n
2153  *            esplusplayer_deactivate() \n
2154  *            esplusplayer_activate()
2155  */
2156 int esplusplayer_set_buffer_size(esplusplayer_handle handle,
2157                                  esplusplayer_buffer_option option,
2158                                  uint64_t size);
2159 /**
2160  * @brief     Set a callback function to be invoked when resource confliction is
2161  * occurred.
2162  * @param     [in] handle : esplusplayer handle.
2163  * @param     [in] resource_conflicted_cb : the resource conflicted callback
2164  *            function to register.
2165  * @param     [in] userdata : userdata of resource_conflicted_cb()
2166  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2167  * esplusplayer_error_type
2168  *            values will be returned.
2169  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2170  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2171  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2172  * failed
2173  * @code
2174  *            refer to the sample code of esplusplayer_set_error_cb();
2175  * @endcode
2176  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2177  *            or #ESPLUSPLAYER_STATE_IDLE.
2178  * @post      esplusplayer_resource_conflicted_cb() will be invoked.
2179  * @exception None
2180  * @remark    esplusplayer_resource_conflicted_cb()
2181  *            if resource_conflicted_cb is set to null,
2182  *            esplusplayer_resource_conflicted_cb() will not be invoked
2183  *            anymore.
2184  */
2185 int esplusplayer_set_resource_conflicted_cb(
2186     esplusplayer_handle handle,
2187     esplusplayer_resource_conflicted_cb resource_conflicted_cb, void* userdata);
2188
2189 /**
2190  * @brief     Set a callback function to be invoked when player has reached the
2191  *            end of stream.
2192  * @param     [in] handle : esplusplayer handle.
2193  * @param     [in] eos_cb : the eos callback function to register.
2194  * @param     [in] userdata : userdata of esplusplayer_eos_cb()
2195  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2196  * esplusplayer_error_type
2197  *            values will be returned.
2198  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2199  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2200  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2201  * failed
2202  * @code
2203  *            refer to the sample code of esplusplayer_set_error_cb();
2204  * @endcode
2205  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2206  *            or #ESPLUSPLAYER_STATE_IDLE.
2207  * @post      esplusplayer_eos_cb() will be invoked.
2208  * @exception None
2209  * @remark    esplusplayer_eos_cb()
2210  *            if eos_cb is set to null, esplusplayer_eos_cb() will not be
2211  *            invoked anymore.
2212  */
2213 int esplusplayer_set_eos_cb(esplusplayer_handle handle,
2214                             esplusplayer_eos_cb eos_cb, void* userdata);
2215
2216 /**
2217  * @brief     Set a callback function to be invoked when player is prepared to
2218  *            receive es packets after calling esplusplayer_prepare_async().
2219  * @param     [in] handle : esplusplayer handle.
2220  * @param     [in] ready_to_prepare_cb : the ready to prepare callback function
2221  *            to register.
2222  * @param     [in] userdata : userdata of ready_to_prepare_cb()
2223  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2224  * esplusplayer_error_type
2225  *            values will be returned.
2226  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2227  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2228  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2229  * failed
2230  * @code
2231  *            refer to the sample code of esplusplayer_submit_packet();
2232  * @endcode
2233  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2234  *            or #ESPLUSPLAYER_STATE_IDLE.
2235  * @post      None
2236  * @exception None
2237  * @remark    esplusplayer_prepare_async()
2238  *            if ready_to_prepare_cb is set to null,
2239  *            esplusplayer_ready_to_prepare_cb() will not be invoked anymore.
2240  */
2241 int esplusplayer_set_ready_to_prepare_cb(
2242     esplusplayer_handle handle,
2243     esplusplayer_ready_to_prepare_cb ready_to_prepare_cb, void* userdata);
2244
2245 /**
2246  * @brief     Set a callback function to be invoked when player is prepared to
2247  *            be started.
2248  * @param     [in] handle : esplusplayer handle.
2249  * @param     [in] prepare_async_done_cb : the repare async done callback
2250  * function to register.
2251  * @param     [in] userdata : userdata of prepare_async_done_cb()
2252  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2253  * esplusplayer_error_type
2254  *            values will be returned.
2255  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2256  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2257  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2258  * failed
2259  * @code
2260  *            refer to the sample code of plusplayer_prepare_async();
2261  * @endcode
2262  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2263  *            or #ESPLUSPLAYER_STATE_IDLE.
2264  * @post      esplusplayer_prepare_async_done_cb() will be invoked.
2265  * @exception It is prohibited to call any player APIs at
2266  *            esplusplayer_prepare_async_done_cb callback.
2267  * @remark    esplusplayer_prepare_async_done_cb()
2268  *            if prepare_async_done_cb is set to null,
2269  *            esplusplayer_prepare_async_done_cb() will not be
2270  *            invoked anymore.
2271  * @see       plusplayer_prepare_async
2272  */
2273 int esplusplayer_set_prepare_async_done_cb(
2274     esplusplayer_handle handle,
2275     esplusplayer_prepare_async_done_cb prepare_async_done_cb, void* userdata);
2276
2277 /**
2278  * @brief     Set a callback function to be invoked when player is prepared to
2279  *            be started.
2280  * @param     [in] handle : esplusplayer handle.
2281  * @param     [in] seek_done_cb : the seek done callback function to register.
2282  * @param     [in] userdata : userdata of esplusplayer_seek_done_cb()
2283  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2284  * esplusplayer_error_type
2285  *            values will be returned.
2286  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2287  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2288  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2289  * failed
2290  * @code
2291  *            refer to the sample code of esplusplayer_set_error_cb();
2292  * @endcode
2293  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2294  *            or #ESPLUSPLAYER_STATE_IDLE.
2295  * @post      esplusplayer_seek_done_cb() will be invoked.
2296  *            if seek_done_cb is set to null, esplusplayer_seek_done_cb() will
2297  *            not be invoked anymore.
2298  * @exception None
2299  */
2300 int esplusplayer_set_seek_done_cb(esplusplayer_handle handle,
2301                                   esplusplayer_seek_done_cb seek_done_cb,
2302                                   void* userdata);
2303
2304 /**
2305  * @brief     Set a callback function to be invoked when player is prepared to
2306  *            receive es packets after flushing all submitted es packets for
2307  *            seek.
2308  * @param     [in] handle : esplusplayer handle.
2309  * @param     [in] ready_to_seek_cb : the ready to seek callback function to
2310  *            register.
2311  * @param     [in] userdata : userdata of esplusplayer_ready_to_seek_cb()
2312  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2313  * esplusplayer_error_type
2314  *            values will be returned.
2315  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2316  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2317  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2318  * failed
2319  * @code
2320  *            refer to the sample code of esplusplayer_set_error_cb();
2321  * @endcode
2322  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2323  *            or #ESPLUSPLAYER_STATE_IDLE.
2324  * @post      None
2325  * @exception None
2326  * @remark    esplusplayer_seek()
2327  *            if ready_to_seek_cb is set to null,
2328  * esplusplayer_ready_to_seek_cb()
2329  *            will not be invoked anymore.
2330  */
2331 int esplusplayer_set_ready_to_seek_cb(
2332     esplusplayer_handle handle, esplusplayer_ready_to_seek_cb ready_to_seek_cb,
2333     void* userdata);
2334
2335 /**
2336  * @brief     Set a callback function to be invoked when player decoded video
2337  *            frame. A video frame can be retrieved using a registered callback.
2338  * @param     [in] handle : esplusplayer handle.
2339  * @param     [in] media_packet_video_decoded_cb : the media packet video
2340  * decoded callback function to register.
2341  * @param     [in] userdata : userdata of
2342  * esplusplayer_set_media_packet_video_decoded_cb()
2343  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2344  * esplusplayer_error_type
2345  *            values will be returned.
2346  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2347  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2348  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2349  * failed
2350  * @code
2351  *            refer to the sample code of esplusplayer_set_error_cb();
2352  * @endcode
2353  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2354  *            or #ESPLUSPLAYER_STATE_IDLE.
2355  * @post      None
2356  * @exception None
2357  * @remark    esplusplayer_set_video_frame_buffer_type()
2358  *            if media_packet_video_decoded_cb is set to null,
2359  *            esplusplayer_error_cb() will not be invoked anymore.
2360  *            media packets have to be released by calling
2361  *            esplusplayer_decoded_buffer_destroy().
2362  * @see       esplusplayer_set_video_frame_buffer_scale_resolution
2363  */
2364 int esplusplayer_set_media_packet_video_decoded_cb(
2365     esplusplayer_handle handle,
2366     esplusplayer_media_packet_video_decoded_cb media_packet_video_decoded_cb,
2367     void* userdata);
2368
2369 /**
2370  * @brief     Set closed caption callback function.
2371  * @description   In this function set closed caption callback to handle the
2372  *            closed caption. If there is closed caption to display,
2373  *            esplusplayer_closed_caption_cb will be called to notify there
2374  *            is closed caption to display.
2375  * @param     [in] handle : esplusplayer handle ptr.
2376  * @param     [in] closed_caption_cb :  the closed caption callback  function to
2377  * register.
2378  * @param     [in] userdata : userdata of esplusplayer_closed_caption_cb
2379  *            callback function.
2380  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2381  * esplusplayer_error_type
2382  *            values will be returned.
2383  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2384  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2385  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2386  * failed
2387  * @code
2388  *            refer to the sample code of esplusplayer_set_error_cb();
2389  * @endcode
2390  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2391  *            or #ESPLUSPLAYER_STATE_IDLE.
2392  * @post      When there is closed caption data, call
2393  *            esplusplayer_closed_caption_cb to nofity that there is closed
2394  *            caption needed to be displayed.
2395  * @exception None
2396  * @remark    esplusplayer_closed_caption_cb \n
2397  *            [in] data : closed caption data \n
2398  *            [in] size : length of closed caption data \n
2399  *            [in] userdata : userdata of esplusplayer_closed_caption_cb
2400  *            callback function.
2401  *            if closed_caption_cb is set to null,
2402  * esplusplayer_closed_caption_cb()
2403  *            will not be invoked anymore.
2404  */
2405 int esplusplayer_set_closed_caption_cb(
2406     esplusplayer_handle handle,
2407     esplusplayer_closed_caption_cb closed_caption_cb, void* userdata);
2408
2409 /**
2410  * @brief     Set a callback function to be invoked when player is flush
2411  *            successed.
2412  * @param     [in] handle : esplusplayer handle.
2413  * @param     [in] flush_done_cb : the flush done callback function to register.
2414  * @param     [in] userdata : userdata of esplusplayer_flush_done_cb()
2415  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2416  * esplusplayer_error_type
2417  *            values will be returned.
2418  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2419  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2420  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2421  * failed
2422  * @code
2423  *            refer to the sample code of esplusplayer_set_error_cb();
2424  * @endcode
2425  * @pre       This api should be called before esplusplayer_flush() is called
2426  * @post      esplusplayer_flush_done_cb() will be invoked.
2427  * @exception None
2428  * @remark    called before esplusplayer_flush().
2429  *            if flush_done_cb is set to null, esplusplayer_error_cb() will
2430  *            not be invoked anymore.
2431  */
2432 int esplusplayer_set_flush_done_cb(esplusplayer_handle handle,
2433                                    esplusplayer_flush_done_cb flush_done_cb,
2434                                    void* userdata);
2435 /**
2436  * @brief     Set a callback function to be invoked when a specific event
2437  *            occurs.
2438  * @param     [in] handle : esplusplayer handle.
2439  * @param     [in] event_cb : the callback function to register.
2440  * @param     [in] userdata : userdata of esplusplayer_event_cb()
2441  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2442  * esplusplayer_error_type
2443  *            values will be returned.
2444  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2445  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2446  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2447  * failed
2448  * @code
2449  *            refer to the sample code of esplusplayer_set_error_cb();
2450  * @endcode
2451  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
2452  *            or #ESPLUSPLAYER_STATE_IDLE.
2453  * @post      esplusplayer_event_cb() will be invoked.
2454  * @exception None
2455  * @remark    esplusplayer_set_event_cb()
2456  *            if event_cb is set to null, esplusplayer_event_cb() will not be
2457  *            invoked anymore.
2458  */
2459 int esplusplayer_set_event_cb(esplusplayer_handle handle,
2460                               esplusplayer_event_cb event_cb, void* userdata);
2461 /**
2462  * @brief     Provided api for destroying decoded buffer.
2463  * @param     [in] handle : esplusplayer handle.
2464  * @param     [in] packet : the decoded buffer.
2465  * @return    @c one of esplusplayer_error_type values will be returned.
2466  * @pre       The player state can be greater than #ESPLUSPLAYER_STATE_IDLE.
2467  * @post      esplusplayer_decoded_buffer_destroy will be invoked for video
2468  *            texturing
2469  * @exception None
2470  * @remark    esplusplayer_decoded_buffer_destroy().
2471  */
2472 int esplusplayer_decoded_buffer_destroy(
2473     esplusplayer_handle handle, esplusplayer_decoded_video_packet* packet);
2474
2475 /**
2476  * @brief     Provided api for setting low latency mode, multiple modes can be
2477  *            set to duplicate.
2478  * @param     [in] handle : esplusplayer handle.
2479  * @param     [in] mode : one of the low latency mode to set.
2480  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2481  * esplusplayer_error_type
2482  *            values will be returned.
2483  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2484  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2485  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2486  * failed
2487  * @code
2488  *            esplusplayer_open(esplayer);
2489  *            esplusplayer_set_low_latency_mode(esplayer,ESPLUSPLAYER_LOW_LATENCY_MODE_NONE);
2490  *            // ... your codes ...
2491  *            esplusplayer_close(esplayer);
2492  * @endcode
2493  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
2494  * @post      None
2495  * @exception None
2496  * @remark    esplusplayer_set_low_latency_mode().
2497  *            if set ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_SYNC:
2498  *            1, esplusplayer_buffer_status_cb/
2499  *            esplusplayer_buffer_byte_status_cb/
2500  *            esplusplayer_buffer_time_status_cb/
2501  *            esplusplayer_ready_to_prepare_cb/
2502  *            esplusplayer_ready_to_seek_cb/esplusplayer_seek_done_cb
2503  *            callbacks are not invoked
2504  *            2, If es packets are sent after esplusplayer_start() is called,
2505  *            it will be played immediately.
2506  * @see       esplusplayer_open()
2507  */
2508 int esplusplayer_set_low_latency_mode(esplusplayer_handle handle,
2509                                       esplusplayer_low_latency_mode mode);
2510
2511 /**
2512  * @brief     Provided api for enabling video frame peek mode
2513  * @param     [in] handle : esplusplayer handle.
2514  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2515  * esplusplayer_error_type
2516  *            values will be returned.
2517  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2518  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2519  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2520  * failed
2521  * @code
2522  *            esplusplayer_open(esplayer);
2523  *            esplusplayer_set_video_frame_peek_mode(esplayer);
2524  *            // ... your codes ...
2525  *            esplusplayer_close(esplayer);
2526  * @endcode
2527  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
2528  * @post      None
2529  * @exception None
2530  * @see       esplusplayer_open() \n
2531  *            esplusplayer_render_video_frame().
2532  */
2533 int esplusplayer_set_video_frame_peek_mode(esplusplayer_handle handle);
2534
2535 /**
2536  * @brief     Provided api for rendering a video frame which is holded by video
2537  *            frame peek mode.
2538  * @param     [in] handle : esplusplayer handle.
2539  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2540  * esplusplayer_error_type
2541  *            values will be returned.
2542  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2543  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2544  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2545  * failed
2546  * @code
2547  *            prepare esplayer done
2548  *            // ... your codes ...
2549  *            esplusplayer_render_video_frame(esplayer);
2550  *            // ... your codes ...
2551  *            esplusplayer_stop(esplayer);
2552  * @endcode
2553  * @pre       In order to use this api,
2554  *            The player state must be one of #ESPLUSPLAYER_STATE_READY or
2555  *            #ESPLUSPLAYER_STATE_PAUSED after esplusplayer_seek_done_cb or
2556  *            esplusplayer_prepare_async_done_cb is called \n
2557  * @post      None
2558  * @exception None
2559  * @see       esplusplayer_set_video_frame_peek_mode() \n
2560  *            esplusplayer_prepare_async()
2561  */
2562 int esplusplayer_render_video_frame(esplusplayer_handle handle);
2563
2564 /**
2565  * @brief     Provided api for setting unlimited max buffer mode, the player
2566  *            does not limit es packet transmission although in buffer overrun
2567  * status
2568  * @param     [in] handle : esplusplayer handle.
2569  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2570  * esplusplayer_error_type
2571  *            values will be returned.
2572  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2573  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2574  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2575  * failed
2576  * @code
2577  *            esplusplayer_open(esplayer);
2578  *            esplusplayer_set_unlimited_max_buffer_mode(esplayer);
2579  *            // ... your codes ...
2580  *            esplusplayer_close(esplayer);
2581  * @endcode
2582  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
2583  * @post      None
2584  * @exception None
2585  * @remark    esplusplayer_set_unlimited_max_buffer_mode().
2586  *            esplusplayer_buffer_status_cb() will be invoked in
2587  *            overrun/underrun buffer status. but
2588  * esplusplayer_submit_packet()/esplusplayer_submit_trust_zone_packet()
2589  *            /esplusplayer_submit_encrypted_packet()
2590  *            does not return ESPLUSPLAYER_SUBMIT_STATUS_FULL
2591  * @see       esplusplayer_open() \n
2592  *            esplusplayer_submit_packet() \n
2593  *            esplusplayer_submit_trust_zone_packet() \n
2594  *            esplusplayer_submit_encrypted_packet()
2595  */
2596 int esplusplayer_set_unlimited_max_buffer_mode(esplusplayer_handle handle);
2597 /**
2598  * @brief     Provided api to deliver fmm signal and getting fmm auto status.
2599  *            The player just delivers fmm signal to system. It doesn't
2600  * gaurantee
2601  *            activating fmm mode. System refers to fmm signal when it decides
2602  * to activate
2603  *            fmm mode or not.
2604  * @param     [in] handle : esplusplayer handle.
2605  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE fmm auto mode on
2606  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION fmm auto mode off
2607  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_STATE Internal operation failed
2608  * @code
2609  *            esplusplayer_open(esplayer);
2610  *            esplusplayer_set_fmm_mode(esplayer);
2611  *            // ... your codes ...
2612  *            esplusplayer_close(esplayer);
2613  * @endcode
2614  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_IDLE,
2615  *            #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PLAYING
2616  *            or #ESPLUSPLAYER_STATE_PAUSED
2617  * @post      None
2618  * @exception None
2619  * @see       esplusplayer_open()
2620  */
2621 int esplusplayer_set_fmm_mode(esplusplayer_handle handle);
2622 /**
2623  * @brief     Provided api for setting audio codec type for playback.
2624  * @param     [in] handle : esplusplayer handle.
2625  * @param     [in] type : codec type(hardware/software).
2626  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2627  esplusplayer_error_type
2628  *            values will be returned.
2629  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2630  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2631  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2632  failed
2633  * @code
2634  *            esplusplayer_open(esplayer);
2635  * esplusplayer_set_audio_codec_type(esplayer,ESPLUSPLAYER_AUDIO_CODEC_TYPE_SW);
2636  *            // ... your codes ...
2637  *            esplusplayer_close(esplayer);
2638  * @endcode
2639  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
2640               When the audio stream is not set or deactivated, it can be set
2641               in #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PAUSED and
2642               #ESPLUSPLAYER_STATE_PLAYING. The set codec type will be
2643               applied when esplusplayer_activate() is called.
2644  * @post      None
2645  * @exception None
2646  * @see       esplusplayer_open() \n
2647  *            esplusplayer_deactivate() \n
2648               esplusplayer_activate() \n
2649               esplusplayer_set_audio_stream_info()
2650  */
2651 int esplusplayer_set_audio_codec_type(esplusplayer_handle handle,
2652                                       esplusplayer_audio_codec_type type);
2653 /**
2654  * @brief     Provided api for setting video codec type for playback.
2655  * @param     [in] handle : esplusplayer handle.
2656  * @param     [in] type : codec type(hardware/software).
2657  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2658  esplusplayer_error_type
2659  *            values will be returned.
2660  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2661  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2662  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2663  failed
2664  * @code
2665  *            esplusplayer_open(esplayer);
2666  * esplusplayer_set_video_codec_type(esplayer,ESPLUSPLAYER_VIDEO_CODEC_TYPE_SW);
2667  *            // ... your codes ...
2668  *            esplusplayer_close(esplayer);
2669  * @endcode
2670  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
2671               When the video stream is not set or deactivated, it can be set
2672               in #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PAUSED and
2673               #ESPLUSPLAYER_STATE_PLAYING. The set codec type will be
2674               applied when esplusplayer_activate() is called.
2675  * @post      None
2676  * @exception None
2677  * @see       esplusplayer_open() \n
2678  *            esplusplayer_deactivate() \n
2679               esplusplayer_activate() \n
2680               esplusplayer_set_video_stream_info()
2681  */
2682 int esplusplayer_set_video_codec_type(esplusplayer_handle handle,
2683                                       esplusplayer_video_codec_type type);
2684 /**
2685  * @brief     Provided api for setting alternative video resource(sub decoder
2686  *            and sub scaler)
2687  * @param     [in] handle : esplusplayer handle ptr.
2688  * @param     [in] rsc_type : set alternative video resource
2689  *            (@c 0 [defualt] = set all video resources(decoder/scaler) to main
2690  *                              resources,
2691  *             @c 1 = set all video resources(decoder/scaler) to sub resources,
2692  *             @c 2 = set only decoder to sub resource,
2693  *             @c 3 = set only scaler to sub resource)
2694  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2695  * esplusplayer_error_type
2696  *            values will be returned.
2697  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2698  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2699  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2700  * failed
2701  * @code
2702  *            esplusplayer_open(esplayer);
2703  *            esplusplayer_set_alternative_video_resource(esplayer,1);
2704  *             // ... your codes ...
2705  *            esplusplayer_close(esplayer);
2706  * @endcode
2707  * @pre       The player state can be all of #State except
2708  *            #ESPLUSPLAYER_STATE_NONE.
2709  * @post      None
2710  * @exception None
2711  * @remark    if app has set not default resource allocate policy via
2712  *            esplusplayer_set_resource_allocate_policy(), this api will return
2713  * false.
2714  * @version   3.0
2715  * @see       esplusplayer_open()
2716  */
2717 int esplusplayer_set_alternative_video_resource(esplusplayer_handle handle,
2718                                                 unsigned int rsc_type);
2719 /**
2720  * @brief     Provided api for setting alternative audio resource(sub decoder
2721  *            and simple mix audio out)
2722  * @param     [in] handle : esplusplayer handle ptr.
2723  * @param     [in] rsc_type : set alternative audio resource type
2724  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2725  * esplusplayer_error_type
2726  *            values will be returned.
2727  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2728  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2729  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2730  * failed
2731  * @code
2732  *            esplusplayer_open(esplayer);
2733  *            esplusplayer_set_audio_codec_type(esplayer,
2734  * ESPLUSPLAYER_AUDIO_CODEC_TYPE_SW)
2735  *            esplusplayer_set_alternative_audio_resource(esplayer,
2736  * ESPLUSPLAYER_AUDIO_RESOURCE_SIMPLE_MIX_OUT);
2737  *             // ... your codes ...
2738  *            esplusplayer_close(esplayer);
2739  *
2740  *            prepare esplayer done
2741  *             // ... your codes ...
2742  *            esplusplayer_deactivate(esplayer, ESPLUSPLAYER_STREAM_TYPE_AUDIO)
2743  *            esplusplayer_set_audio_codec_type(esplayer,
2744  * ESPLUSPLAYER_AUDIO_CODEC_TYPE_SW)
2745  *            esplusplayer_set_alternative_audio_resource(esplayer,
2746  * ESPLUSPLAYER_AUDIO_RESOURCE_SIMPLE_MIX_OUT);
2747  *            esplusplayer_activate(esplayer, ESPLUSPLAYER_STREAM_TYPE_AUDIO)
2748  *             // ... your codes ...
2749  *            esplusplayer_close(esplayer);
2750  * @endcode
2751  * @pre       The player state can be all of #State except
2752  *            #ESPLUSPLAYER_STATE_NONE.
2753  * @post      None
2754  * @exception None
2755  * @remark    Simple out is no sound effect. Simple mix out sound is mixed with
2756  * main sound and output
2757  *            through only main speaker. Simple mix out output format is
2758  * fixed(eg. 48kh, 2ch).
2759  *            If you use simple mix out resource, audio decoder should be S/W
2760  * type.
2761  * @version   3.8
2762  * @see       esplusplayer_open() \n
2763  *            esplusplayer_set_audio_codec_type()
2764  */
2765 int esplusplayer_set_alternative_audio_resource(
2766     esplusplayer_handle handle, esplusplayer_audio_resource_type rsc_type);
2767 /**
2768  * @brief     Provided api for switching audio stream between the different
2769  *            audio codec types on the fly
2770  * @param     [in] handle : esplusplayer handle ptr.
2771  * @param     [in] stream : audio stream pointer
2772  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2773  * esplusplayer_error_type
2774  *            values will be returned.
2775  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2776  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2777  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2778  * failed
2779  * @code
2780  *            prepare esplayer done
2781  *            // ... your codes ...
2782  *            esplusplayer_audio_stream_info audio_stream;
2783  *            audio_stream.mime_type = ESPLUSPLAYER_AUDIO_MIME_TYPE_AC3;
2784  *            audio_stream.sample_rate = 48000;
2785  *            audio_stream.channels = 2;
2786  *            esplusplayer_switch_audio_stream_onthefly(esplayer,
2787  *                &audio_stream);
2788  *            // ... your codes ...
2789  *            esplusplayer_close(esplayer);
2790  * @endcode
2791  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY,
2792  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING
2793  * @post      None
2794  * @exception   None
2795  * @remark    Audio codec can be switched between only
2796  *            #ESPLUSPLAYER_AUDIO_MIME_TYPE_AAC,
2797  *            #ESPLUSPLAYER_AUDIO_MIME_TYPE_EAC3
2798  *            and #ESPLUSPLAYER_AUDIO_MIME_TYPE_AC3.
2799  *            if other codec is set, this api will return false.
2800  * @version   3.0
2801  * @see       esplusplayer_prepare_async()
2802  */
2803 int esplusplayer_switch_audio_stream_onthefly(
2804     esplusplayer_handle handle, esplusplayer_audio_stream_info* stream);
2805 /**
2806  * @brief     Provided api for setting aifilter
2807  * @param     [in] handle : esplusplayer handle ptr.
2808  * @param     [in] aifilter :  aifilter plugin.
2809  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2810  * esplusplayer_error_type
2811  *            values will be returned.
2812  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2813  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2814  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2815  * failed
2816  * @code
2817  *            esplusplayer_open(esplayer);
2818  *            GstElement* aifilter_ =
2819  *                gst_element_factory_make("aifilter_autozoom","auto_zoom");
2820  *            g_object_set(G_OBJECT(aifilter_), "az_cb_out_fps", 30, NULL);
2821  *            g_object_set(G_OBJECT(aifilter_), "az_inference_fps", 2, NULL);
2822  *            g_object_set(G_OBJECT(aifilter_), "az_disp_width", 1920, NULL);
2823  *            g_object_set(G_OBJECT(aifilter_), "az_disp_height", 1080, NULL);
2824  *            g_object_set(G_OBJECT(aifilter_), "az_detection_type", 2, NULL);
2825  *            g_object_set(G_OBJECT(aifilter_), "az_scaler_type", 1, NULL);
2826  *            g_object_set(G_OBJECT(aifilter_), "az_target_num", 2, NULL);
2827  *            esplusplayer_set_aifilter(esplayer,aifilter_);
2828  *            // ... your codes ...
2829  *            esplusplayer_close(esplayer);
2830  * @endcode
2831  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
2832  * @post      None
2833  * @exception None
2834  * @version   3.0
2835  * @see       esplusplayer_open()
2836  */
2837 int esplusplayer_set_aifilter(esplusplayer_handle handle, void* aifilter);
2838
2839 /**
2840  * @brief     Provided api for setting render time offset
2841  * @param     [in] handle : esplusplayer handle ptr.
2842  * @param     [in] type : stream type
2843  * @param     [in] offset : offset (default in milliseconds, can be set by
2844  * @esplusplayer_set_timeunit_type).
2845  *                          G_MININT64 <= offset * 1000000 <= G_MAXINT64
2846  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2847  * esplusplayer_error_type
2848  *            values will be returned.
2849  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2850  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2851  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2852  * failed
2853  * @code
2854  *            esplusplayer_open(esplayer);
2855  *            esplusplayer_set_low_latency_mode(esplayer,ESPLUSPLAYER_LOW_LATENCY_MODE_NONE);
2856  *            prepare esplayer
2857  *            // ... your codes ...
2858  *            int64_t set_offset = 10;
2859  *            esplusplayer_set_render_time_offset(esplayer,ESPLUSPLAYER_STREAM_TYPE_VIDEO,
2860  *                                                set_offset);
2861  *            int64_t get_offset = 0;
2862  *            esplusplayer_get_render_time_offset(esplayer_,ESPLUSPLAYER_STREAM_TYPE_VIDEO,
2863  *                                                &get_offset);
2864  *            // ... your codes ...
2865  *            esplusplayer_close(esplayer);
2866  * @endcode
2867  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_READY,
2868  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
2869  *            It have to be set to low latency mode. (all mode except
2870  *            # ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_SYNC)
2871  * @remark    esplusplayer_set_low_latency_mode().
2872  * @post      None
2873  * @exception None
2874  * @version   3.0
2875  * @see       esplusplayer_open()
2876  */
2877 int esplusplayer_set_render_time_offset(esplusplayer_handle handle,
2878                                         esplusplayer_stream_type type,
2879                                         int64_t offset);
2880 /**
2881  * @brief     Provided api for getting render time offset
2882  * @param     [in] handle : esplusplayer handle ptr.
2883  * @param     [in] type : stream type
2884  * @param     [in] offset : offset ptr (default in milliseconds, can be set by
2885  * @esplusplayer_set_timeunit_type).
2886  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2887  * esplusplayer_error_type
2888  *            values will be returned.
2889  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2890  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2891  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2892  * failed
2893  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_READY,
2894  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
2895  *            It have to be set to low latency mode.
2896  * @remark    esplusplayer_set_low_latency_mode().
2897  * @post      None
2898  * @exception None
2899  * @version   3.0
2900  * see        esplusplayer_set_render_time_offset
2901  */
2902 int esplusplayer_get_render_time_offset(esplusplayer_handle handle,
2903                                         esplusplayer_stream_type type,
2904                                         int64_t* offset);
2905 /**
2906  * @brief     Provided api for setting catch up speed level in low latency mode
2907  * @param     [in] handle : esplusplayer handle.
2908  * @param     [in] level : speed level to catch up
2909  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2910  * esplusplayer_error_type
2911  *            values will be returned.
2912  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2913  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2914  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2915  * failed
2916  * @code
2917  *            esplusplayer_open(esplayer);
2918  *            esplusplayer_set_low_latency_mode(esplayer,ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO);
2919  *            esplusplayer_set_catch_up_speed(esplayer,ESPLUSPLAYER_CATCH_UP_SPEED_MID);
2920  *            // ... your codes ...
2921  *            esplusplayer_close(esplayer);
2922  * @endcode
2923  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_IDLE,
2924  *            #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PLAYING
2925  *            or #ESPLUSPLAYER_STATE_PAUSED
2926  *            esplusplayer_set_low_latency_mode() should be called as below
2927  *            before this api is called.
2928  *            esplusplayer_set_low_latency_mode(handle,
2929  *                ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO),
2930  *            esplusplayer_set_low_latency_mode(handle,
2931  *                ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO),
2932  *            esplusplayer_set_low_latency_mode(handle,
2933  *                ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_SYNC),
2934  *            esplusplayer_set_low_latency_mode(handle,
2935  *                ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY)
2936  * @post      None
2937  * @exception None
2938  * @version   2.7
2939  * @see       esplusplayer_open()
2940  */
2941 int esplusplayer_set_catch_up_speed(esplusplayer_handle handle,
2942                                     esplusplayer_catch_up_speed level);
2943
2944 /**
2945  * @brief     Provided api for getting current video latency status
2946  * @param     [in] handle : esplusplayer handle.
2947  * @param     [out] status : current latency status
2948  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2949  * esplusplayer_error_type
2950  *            values will be returned.
2951  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2952  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2953  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2954  * failed
2955  * @code
2956  *            prepare esplayer done
2957  *            // ... your codes ...
2958  *            esplusplayer_latency_status current_status =
2959  *                ESPLUSPLAYER_LATENCY_LOW;
2960  *            esplusplayer_get_video_latency_status(esplayer, &current_status);
2961  *            // ... your codes ...
2962  *            esplusplayer_stop(esplayer);
2963  * @endcode
2964  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY,
2965  *            #ESPLUSPLAYER_STATE_PLAYING or #ESPLUSPLAYER_STATE_PAUSED
2966  * @post      None
2967  * @exception None
2968  * @version   2.7
2969  * @see       esplusplayer_prepare_async()
2970  */
2971 int esplusplayer_get_video_latency_status(esplusplayer_handle handle,
2972                                           esplusplayer_latency_status* status);
2973
2974 /**
2975  * @brief     Provided api for getting current audio latency status
2976  * @param     [in] handle : esplusplayer handle.
2977  * @param     [out] status : current latency status
2978  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
2979  * esplusplayer_error_type
2980  *            values will be returned.
2981  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2982  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2983  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
2984  * failed
2985  * @code
2986  *            prepare esplayer done
2987  *            // ... your codes ...
2988  *            esplusplayer_latency_status current_status =
2989  *                ESPLUSPLAYER_LATENCY_LOW;
2990  *            esplusplayer_get_audio_latency_status(esplayer, &current_status);
2991  *            // ... your codes ...
2992  *            esplusplayer_stop(esplayer);
2993  * @endcode
2994  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY,
2995  *            #ESPLUSPLAYER_STATE_PLAYING or #ESPLUSPLAYER_STATE_PAUSED
2996  * @post      None
2997  * @exception None
2998  * @version   2.7
2999  * @see       esplusplayer_prepare_async()
3000  */
3001 int esplusplayer_get_audio_latency_status(esplusplayer_handle handle,
3002                                           esplusplayer_latency_status* status);
3003
3004 /**
3005  * @brief     Provided api for setting video mid latency threshold for low
3006  * latency
3007  * playback
3008  * @param     [in] handle : esplusplayer handle.
3009  * @param     [in] threshold: the threshold(number) of the video frames for mid
3010  * latency.
3011  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3012  * esplusplayer_error_type
3013  *            values will be returned.
3014  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3015  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3016  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3017  * failed
3018  * @code
3019  *            esplusplayer_open(esplayer);
3020  *            esplusplayer_set_low_latency_mode(esplayer,ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO);
3021  *            esplusplayer_set_video_mid_latency_threshold(esplayer,2);
3022  *            // ... your codes ...
3023  *            esplusplayer_close(esplayer);
3024  * @endcode
3025  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_IDLE,
3026  *            #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PLAYING
3027  *            or #ESPLUSPLAYER_STATE_PAUSED
3028  *            esplusplayer_set_low_latency_mode() should be called as below
3029  *            before this api is called.
3030  *            esplusplayer_set_low_latency_mode(handle,
3031  *                ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO),
3032  *            esplusplayer_set_low_latency_mode(handle,
3033  *                ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO),
3034  *            esplusplayer_set_low_latency_mode(handle,
3035  *                ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_SYNC),
3036  *            esplusplayer_set_low_latency_mode(handle,
3037  *                  ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE)
3038  * @post      None
3039  * @exception None
3040  * @version   2.7
3041  * @see       esplusplayer_open()
3042  */
3043 /// TODO:: set the min/max value of the threshold
3044 int esplusplayer_set_video_mid_latency_threshold(esplusplayer_handle handle,
3045                                                  const unsigned int threshold);
3046
3047 /**
3048  * @brief     Provided api for setting audio mid latency threshold for low
3049  * latency
3050  * playback
3051  * @param     [in] handle : esplusplayer handle.
3052  * @param     [in] threshold: the threshold(number) of the audio frames for mid
3053  * latency.
3054  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3055  * esplusplayer_error_type
3056  *            values will be returned.
3057  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3058  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3059  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3060  * failed
3061  * @code
3062  *            esplusplayer_open(esplayer);
3063  *            esplusplayer_set_low_latency_mode(esplayer,ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO);
3064  *            esplusplayer_set_audio_mid_latency_threshold(esplayer,2);
3065  *            // ... your codes ...
3066  *            esplusplayer_close(esplayer);
3067  * @endcode
3068  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_IDLE,
3069  *            #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PLAYING
3070  *            or #ESPLUSPLAYER_STATE_PAUSED
3071  *            esplusplayer_set_low_latency_mode() should be called as below
3072  *            before this api is called.
3073  *            esplusplayer_set_low_latency_mode(handle,
3074  *                ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO),
3075  *            esplusplayer_set_low_latency_mode(handle,
3076  *                ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO),
3077  *            esplusplayer_set_low_latency_mode(handle,
3078  *                ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_SYNC),
3079  *            esplusplayer_set_low_latency_mode(handle,
3080  *                  ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE)
3081  * @post      None
3082  * @exception None
3083  * @version   2.7
3084  * @see       esplusplayer_open()
3085  */
3086 /// TODO:: set the min/max value of the threshold
3087 int esplusplayer_set_audio_mid_latency_threshold(esplusplayer_handle handle,
3088                                                  const unsigned int threshold);
3089
3090 /**
3091  * @brief     Provided api for setting video high latency threshold for low
3092  * latency
3093  * playback
3094  * @param     [in] handle : esplusplayer handle.
3095  * @param     [in] threshold: the threshold(number) of the video frames for high
3096  * latency.
3097  * @param     [in] video_high_latency_cb : high latency callback function to
3098  * register
3099  * @param     [in] userdata : userdata of esplusplayer_high_latency_cb()
3100  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3101  * esplusplayer_error_type
3102  *            values will be returned.
3103  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3104  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3105  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3106  * failed
3107  * @code
3108  *            static void OnVideoHighLatency(void* userdata) {
3109  *                printf ("OnVideoHighLatency\n");
3110  *            }
3111  *            esplusplayer_open(esplayer);
3112  *            esplusplayer_set_low_latency_mode(esplayer,ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO);
3113  *            esplusplayer_set_video_high_latency_threshold(esplayer, 2,
3114  *                OnVideoHighLatency, nullptr);
3115  *            // ... your codes ...
3116  *            esplusplayer_close(esplayer);
3117  * @endcode
3118  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_IDLE,
3119  *            #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PLAYING
3120  *            or #ESPLUSPLAYER_STATE_PAUSED
3121  *            esplusplayer_set_low_latency_mode() should be called as below
3122  *            before this api is called.
3123  *            esplusplayer_set_low_latency_mode(handle,
3124  *                ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO),
3125  *            esplusplayer_set_low_latency_mode(handle,
3126  *                ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO),
3127  *            esplusplayer_set_low_latency_mode(handle,
3128  *                ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_SYNC),
3129  *            esplusplayer_set_low_latency_mode(handle,
3130  *                  ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE)
3131  * @post      None
3132  * @exception None
3133  * @version   2.7
3134  * @see       esplusplayer_open()
3135  */
3136 /// TODO:: set the min/max value of the threshold
3137 int esplusplayer_set_video_high_latency_threshold(
3138     esplusplayer_handle handle, const unsigned int threshold,
3139     esplusplayer_video_high_latency_cb video_high_latency_cb, void* userdata);
3140
3141 /**
3142  * @brief     Provided api for setting audio high latency threshold for low
3143  * latency
3144  * playback
3145  * @param     [in] handle : esplusplayer handle.
3146  * @param     [in] threshold: the threshold(number) of the audio frames for high
3147  * latency.
3148  * @param     [in] audio_high_latency_cb : high latency callback function to
3149  * register
3150  * @param     [in] userdata : userdata of esplusplayer_high_latency_cb()
3151  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3152  * esplusplayer_error_type
3153  *            values will be returned.
3154  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3155  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3156  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3157  * failed
3158  * @code
3159  *            static void OnAudioHighLatency(void* userdata) {
3160  *                printf ("OnAudioHighLatency\n");
3161  *            }
3162  *            esplusplayer_open(esplayer);
3163  *            esplusplayer_set_low_latency_mode(esplayer,ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO);
3164  *            esplusplayer_set_audio_high_latency_threshold(esplayer, 2,
3165  *                OnAudioHighLatency, nullptr);
3166  *            // ... your codes ...
3167  *            esplusplayer_close(esplayer);
3168  * @endcode
3169  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_IDLE,
3170  *            #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PLAYING
3171  *            or #ESPLUSPLAYER_STATE_PAUSED
3172  *            esplusplayer_set_low_latency_mode() should be called as below
3173  *            before this api is called.
3174  *            esplusplayer_set_low_latency_mode(handle,
3175  *                ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO),
3176  *            esplusplayer_set_low_latency_mode(handle,
3177  *                ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO),
3178  *            esplusplayer_set_low_latency_mode(handle,
3179  *                ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_SYNC),
3180  *            esplusplayer_set_low_latency_mode(handle,
3181  *                ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE)
3182  * @post      None
3183  * @exception None
3184  * @version   2.7
3185  * @see       esplusplayer_open()
3186  */
3187 /// TODO:: set the min/max value of the threshold
3188 int esplusplayer_set_audio_high_latency_threshold(
3189     esplusplayer_handle handle, const unsigned int threshold,
3190     esplusplayer_audio_high_latency_cb audio_high_latency_cb, void* userdata);
3191
3192 /**
3193  * @brief     Provided api for getting the maximum number of frames.
3194  * @param     [in] handle : esplusplayer handle.
3195  * @param     [out] frame_count : maximum frame count.
3196  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3197  * esplusplayer_error_type values will be returned.
3198  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3199  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3200  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3201  * failed
3202  * @code
3203  *            esplusplayer_open(esplayer);
3204  *            esplusplayer_set_low_latency_mode(esplayer,
3205  * ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE);
3206  *            esplusplayer_audio_stream_info audio_stream;
3207  *            audio_stream.mime_type = ESPLUSPLAYER_AUDIO_MIME_TYPE_PCM_S16LE;
3208  *            audio_stream.sample_rate = 48000;
3209  *            audio_stream.channels = 6;
3210  *            esplusplayer_set_audio_stream_info(esplayer, &audio_stream);
3211  *            prepare esplayer done
3212  *            // ... your codes ...
3213  *            uint64_t frame_count = 0;
3214  *            esplusplayer_get_low_latency_pcm_buffer_size(esplayer,
3215  * &frame_count)
3216  *            // ... your codes ...
3217  *            esplusplayer_stop(esplayer);
3218  * @endcode
3219  * @pre       The player state must be at least #ESPLUSPLAYER_STATE_READY.
3220  *            It has to be set to game mode, and multi channel pcm.
3221  * @post      None
3222  * @exception None
3223  * @version   6.0
3224  * @see       esplusplayer_get_low_latency_pcm_current_buffer_level() \n
3225  *            esplusplayer_get_low_latency_pcm_underrun_count()
3226  */
3227 int esplusplayer_get_low_latency_pcm_buffer_size(esplusplayer_handle handle,
3228                                                  uint64_t* frame_count);
3229
3230 /**
3231  * @brief     Provided api for getting the number of currently queued frames.
3232  * @param     [in] handle : esplusplayer handle.
3233  * @param     [out] frame_count : queued frame count.
3234  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3235  * esplusplayer_error_type values will be returned.
3236  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3237  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3238  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3239  * failed
3240  * @code
3241  *            esplusplayer_open(esplayer);
3242  *            esplusplayer_set_low_latency_mode(esplayer,
3243  * ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE);
3244  *            esplusplayer_audio_stream_info audio_stream;
3245  *            audio_stream.mime_type = ESPLUSPLAYER_AUDIO_MIME_TYPE_PCM_S16LE;
3246  *            audio_stream.sample_rate = 48000;
3247  *            audio_stream.channels = 6;
3248  *            esplusplayer_set_audio_stream_info(esplayer, &audio_stream);
3249  *            prepare esplayer done
3250  *            // ... your codes ...
3251  *            uint64_t frame_count = 0;
3252  *            esplusplayer_get_low_latency_pcm_current_buffer_level(esplayer,
3253  * &frame_count)
3254  *            // ... your codes ...
3255  *            esplusplayer_stop(esplayer);
3256  * @endcode
3257  * @pre       The player state must be at least #ESPLUSPLAYER_STATE_READY.
3258  *            It has to be set to game mode, and multi channel pcm.
3259  * @post      None
3260  * @exception None
3261  * @version   6.0
3262  * @see       esplusplayer_get_low_latency_pcm_buffer_size() \n
3263  *            esplusplayer_get_low_latency_pcm_underrun_count()
3264  */
3265 int esplusplayer_get_low_latency_pcm_current_buffer_level(
3266     esplusplayer_handle handle, uint64_t* frame_count);
3267
3268 /**
3269  * @brief     Provided api for getting the underrun counts in audio out.
3270  * @param     [in] handle : esplusplayer handle.
3271  * @param     [out] underrun_count : underrun counts in audio out.
3272  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3273  * esplusplayer_error_type values will be returned.
3274  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3275  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3276  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3277  * failed
3278  * @code
3279  *            esplusplayer_open(esplayer);
3280  *            esplusplayer_set_low_latency_mode(esplayer,
3281  * ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE);
3282  *            esplusplayer_audio_stream_info audio_stream;
3283  *            audio_stream.mime_type = ESPLUSPLAYER_AUDIO_MIME_TYPE_PCM_S16LE;
3284  *            audio_stream.sample_rate = 48000;
3285  *            audio_stream.channels = 6;
3286  *            esplusplayer_set_audio_stream_info(esplayer, &audio_stream);
3287  *            prepare esplayer done
3288  *            // ... your codes ...
3289  *            uint64_t underrun_count = 0;
3290  *            esplusplayer_get_low_latency_pcm_underrun_count(esplayer,
3291  * &underrun_count)
3292  *            // ... your codes ...
3293  *            esplusplayer_stop(esplayer);
3294  * @endcode
3295  * @pre       The player state must be at least #ESPLUSPLAYER_STATE_READY.
3296  *            It has to be set to game mode, and multi channel pcm.
3297  * @post      None
3298  * @exception None
3299  * @version   6.0
3300  * @see       esplusplayer_get_low_latency_pcm_buffer_size() \n
3301  *            esplusplayer_get_low_latency_pcm_current_buffer_level()
3302  */
3303 int esplusplayer_get_low_latency_pcm_underrun_count(esplusplayer_handle handle,
3304                                                     uint64_t* underrun_count);
3305
3306 /**
3307  * @brief     Initialize easing info to esplayer.
3308  * @param     [in] handle : esplusplayer handle.
3309  * @param     [in] init_volume : initial easing volume (0 ~ 100).
3310  * @param     [in] elapsed_time : initial elapsed time (millisecond).
3311  * @param     [in] easing_info : target volume, duration, type.
3312  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3313  * esplusplayer_error_type
3314  *            values will be returned.
3315  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3316  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3317  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3318  * failed
3319  * @code
3320  *            esplusplayer_open(esplayer);
3321  *            uint32_t volume = 50, elapsed_time = 10000;
3322  *            esplusplayer_target_audio_easing_info easing_info;
3323  *            easing_info.volume = 30;
3324  *            easing_info.duration = 100;
3325  *            easing_info.type = ESPLUSPLAYER_AUDIO_EASING_INCUBIC;
3326  *            esplusplayer_init_audio_easing_info(esplayer,volume,elapsed_time,&easing_info);
3327  *            // ... your codes ...
3328  *            esplusplayer_close(esplayer);
3329  * @endcode
3330  * @pre       The player state can be all of #esplusplayer_state except
3331  *            #ESPLUSPLAYER_STATE_NONE.
3332  * @post      None
3333  * @exception None
3334  * @version   3.0
3335  * @see       esplusplayer_open()
3336  */
3337 int esplusplayer_init_audio_easing_info(
3338     esplusplayer_handle handle, uint32_t init_volume, uint32_t elapsed_time,
3339     const esplusplayer_target_audio_easing_info* easing_info);
3340
3341 /**
3342  * @brief     Update easing info to esplayer to update target info.
3343  * @param     [in] handle : esplusplayer handle.
3344  * @param     [in] easing_info : target volume, duration, type.
3345  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3346  * esplusplayer_error_type
3347  *            values will be returned.
3348  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3349  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3350  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3351  * failed
3352  * @code
3353  *            esplusplayer_open(esplayer);
3354  *            // ... your codes ...
3355  *            esplusplayer_target_audio_easing_info easing_info;
3356  *            easing_info.volume = 30;
3357  *            easing_info.duration = 100;
3358  *            easing_info.type = ESPLUSPLAYER_AUDIO_EASING_INCUBIC;
3359  *            esplusplayer_update_audio_easing_info(esplayer,&easing_info);
3360  *            // ... your codes ...
3361  *            esplusplayer_close(esplayer);
3362  * @endcode
3363  * @pre       The player state can be all of #esplusplayer_state except
3364  *            #ESPLUSPLAYER_STATE_NONE.
3365  *            This api should be called after
3366  *            esplusplayer_init_audio_easing_info() is called
3367  * @post      None
3368  * @exception None
3369  * @version   3.0
3370  * @see       esplusplayer_open()
3371  */
3372 int esplusplayer_update_audio_easing_info(
3373     esplusplayer_handle handle,
3374     const esplusplayer_target_audio_easing_info* easing_info);
3375
3376 /**
3377  * @brief     Get easing info currently in easing operation from esplayer
3378  * @param     [in] handle : esplusplayer handle.
3379  * @param     [out] current_volume : current volume (0 ~ 100).
3380  * @param     [out] elapsed_time : elapsed time (millisecond).
3381  * @param     [out] easing_info : target volume, duration, type.
3382  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3383  esplusplayer_error_type
3384  *            values will be returned.
3385  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3386  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3387  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3388  failed
3389  * @code
3390  *            esplusplayer_open(esplayer);
3391  *            // ... your codes ...
3392  *            uint32_t cur_volume = 50, elapsed_time = 0;
3393  *            esplusplayer_target_audio_easing_info easing_info;
3394  *
3395  esplusplayer_get_audio_easing_info(esplayer,&cur_volume,&elapsed_time,&easing_info);
3396  *            // ... your codes ...
3397  *            esplusplayer_close(esplayer);
3398  * @endcode
3399  * @pre       The player state can be all of #esplusplayer_state except
3400  *            #ESPLUSPLAYER_STATE_NONE.
3401  *            This api should be called after
3402  *            esplusplayer_init_audio_easing_info() is called
3403  * @post      None
3404  * @exception None
3405  * @version   3.0
3406  * @see       esplusplayer_open()
3407
3408  */
3409 int esplusplayer_get_audio_easing_info(
3410     esplusplayer_handle handle, uint32_t* current_volume,
3411     uint32_t* elapsed_time, esplusplayer_target_audio_easing_info* easing_info);
3412
3413 /**
3414  * @brief     Start audio easing using a registered audio easing info
3415  * @param     [in] handle : esplusplayer handle.
3416  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3417  * esplusplayer_error_type
3418  *            values will be returned.
3419  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3420  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3421  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3422  * failed
3423  * @code
3424  *            prepare esplayer done
3425  *            uint32_t volume = 50, elapsed_time = 10000;
3426  *            esplusplayer_target_audio_easing_info easing_info;
3427  *            easing_info.volume = 30;
3428  *            easing_info.duration = 100;
3429  *            easing_info.type = ESPLUSPLAYER_AUDIO_EASING_INCUBIC;
3430  *            esplusplayer_init_audio_easing_info(esplayer,volume,elapsed_time,&easing_info);
3431  *            esplusplayer_start_audio_easing(esplayer);
3432  *            // ... your codes ...
3433  *            esplusplayer_close(esplayer);
3434  * @endcode
3435  * @pre       The player state should be at least #ESPLUSPLAYER_STATE_READY.
3436  *            This api should be called after
3437  *            esplusplayer_init_audio_easing_info() is called
3438  * @post      None
3439  * @exception None
3440  * @version   3.0
3441  * @see       esplusplayer_open() \n
3442  *            esplusplayer_init_audio_easing_info() \n
3443  *            esplusplayer_update_audio_easing_info() \n
3444  *            esplusplayer_stop_audio_easing() \n
3445  *            esplusplayer_prepare_async()
3446  */
3447 int esplusplayer_start_audio_easing(esplusplayer_handle handle);
3448
3449 /**
3450  * @brief     Stop audio easing
3451  * @param     [in] handle : esplusplayer handle.
3452  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3453  * esplusplayer_error_type
3454  *            values will be returned.
3455  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3456  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3457  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3458  * failed
3459  * @code
3460  *            esplusplayer_open(esplayer);
3461  *            // ... your codes ...
3462  *            esplusplayer_stop_audio_easing(esplayer);
3463  *            // ... your codes ...
3464  *            esplusplayer_close(esplayer);
3465  * @endcode
3466  * @pre       The player state can be all of #esplusplayer_state except
3467  *            #ESPLUSPLAYER_STATE_NONE.
3468  *            This api should be called after
3469  *            esplusplayer_init_audio_easing_info() is called
3470  * @post      None
3471  * @exception   None
3472  * @version   3.0
3473  * @see       esplusplayer_open() \n
3474  *            esplusplayer_start_audio_easing()
3475  */
3476 int esplusplayer_stop_audio_easing(esplusplayer_handle handle);
3477
3478 /**
3479  * @brief     Get virtual resource id
3480  * @param     [in] handle : esplusplayer handle.
3481  * @param     [in] type : The resource type of virtual id.
3482  * @param     [out] virtual_id : Stored virtual resource id value.
3483  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3484  esplusplayer_error_type
3485  *            values will be returned.
3486  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3487  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3488  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3489  failed
3490  * @code
3491  *            prepare esplayer done
3492  *            // ... your codes ...
3493  *            int virtual_id;
3494  *
3495  esplusplayer_get_virtual_rsc_id(esplayer,ESPLUSPLAYER_RSC_TYPE_VIDEO_RENDERER,&virtual_id);
3496  *            // ... your codes ...
3497  *            esplusplayer_close(esplayer);
3498  *            esplusplayer_destroy(esplayer);
3499  * @endcode
3500  * @pre       The player state should be #State::kReady, #State::kPlaying or
3501  *            #State::kPaused
3502  * @post      None
3503  * @return    @c True on success, otherwise @c False ("virtual_id" will be -1)
3504  * @exception None
3505  * @version   3.0
3506  * @remark    This function returns virtual resource id which player is
3507  *            allocated from resource manager. For example, virtual scaler id is
3508  *            required for an application to use capture API directly.
3509  * @see       esplusplayer_prepare_async()
3510
3511  */
3512 int esplusplayer_get_virtual_rsc_id(esplusplayer_handle handle,
3513                                     const esplusplayer_rsc_type type,
3514                                     int* virtual_id);
3515
3516 /**
3517  * @brief     Set advanced picture quality type.
3518  * @param     [in] handle : esplusplayer handle.
3519  * @param     [in] type : The picture quality type.
3520  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
3521  * @post      None
3522  * @return    @c one of esplusplayer_error_type values will be returned.
3523  * @exception  None
3524  * @version   3.1
3525  */
3526 int esplusplayer_set_advanced_picture_quality_type(
3527     esplusplayer_handle handle,
3528     esplusplayer_advanced_picture_quality_type type);
3529
3530 /**
3531  * @brief     Set resource allocate policy.
3532  * @param     [in] handle : esplusplayer handle.
3533  * @param     [in] policy : The resource allocate policy.
3534  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
3535  * @post      None
3536  * @return    @c one of esplusplayer_error_type values will be returned.
3537  * @exception  None
3538  * @version   3.3
3539  * @remark    If app has set not default alternaltive resource via
3540  *            esplusplayer_set_alternative_video_resource(), alternative
3541  *            resource setting will be ignored.
3542  */
3543 int esplusplayer_set_resource_allocate_policy(
3544     esplusplayer_handle handle, esplusplayer_rsc_alloc_policy policy);
3545
3546 /**
3547  * @brief     Requests decoded video frame packet to acquire it. it works only
3548  *            with #ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_MANUAL_COPY
3549  *            mode
3550  * @param     [in] handle : esplusplayer handle.
3551  * @param     [out] packet : the decoded buffer.
3552  * @param     [out] status : (nullable) the result of video frame requested
3553  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY or
3554  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
3555  * @post      None
3556  * @return    #ESPLUSPLAYER_ERROR_TYPE_NONE on success, otherwise one of
3557  *            esplusplayer_error_type values will be returned.
3558  * @exception None
3559  * @version   4.0
3560  * @see       esplusplayer_set_video_frame_buffer_type()
3561  * @see       esplusplayer_decoded_buffer_destroy()
3562  * @see       esplusplayer_decoded_video_frame_buffer_type
3563  * @code
3564  * ...
3565  * esplusplayer_set_video_frame_buffer_type(handle,
3566  * ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_MANUAL_COPY);
3567  * ...
3568  * esplusplayer_prepare_async(handle);
3569  * ...
3570  * // after prepared
3571  * esplusplayer_decoded_video_packet packet;
3572  * esplusplayer_get_decoded_video_frame_status_type state;
3573  * int retval = esplusplayer_get_decoded_video_packet(handle, &packet, &state);
3574  * if (state == ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_SUCCESS) {
3575  *   // successful case.
3576  *   // in this case, retval will be ESPLUSPLAYER_ERROR_TYPE_NONE
3577  *   // you have to call esplusplayer_decoded_buffer_destroy() after using the
3578  *   // packet
3579  *   ...
3580  *   esplusplayer_decoded_buffer_destroy(handle, &packet);
3581  * } else if (state ==
3582  * ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_NO_REMAINING_BUFFER) {
3583  *   // app has to call esplusplayer_decoded_buffer_destroy() with previous
3584  *   // video packet.
3585  *   // it means player couldn't draw the video frame into a buffer due to no
3586  * buffer.
3587  *   // in this case ,retval will be ESPLUSPLAYER_ERROR_TYPE_NONE
3588  * } else if (state ==
3589  * ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_NO_FILLED_BUFFER) {
3590  *   // it means app should retry to get decoded video packet.
3591  *   // in most case, there were no buffers drawn in the timing you called this
3592  *   // api.
3593  *   // in this case, retval will be ESPLUSPLAYER_ERROR_TYPE_NONE
3594  * } else if (state == ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_UNKNOWN) {
3595  *   // internal error happened
3596  *   // in this case, retval will be ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION
3597  * }
3598  * ...
3599  * @endcode
3600  */
3601 int esplusplayer_get_decoded_video_packet(
3602     esplusplayer_handle handle, esplusplayer_decoded_video_packet* packet,
3603     esplusplayer_get_decoded_video_frame_status_type* status);
3604
3605 /**
3606  * @brief     Set preloading of the audio pipeline.
3607  * @param     [in] handle : esplusplayer handle.
3608  * @return    @c one of esplusplayer_error_type values will be returned.
3609  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
3610  * @post      None
3611  * @remark    If the other player is used by pre-loading mode, this player can
3612  *            be prepared before the other player is released.
3613  *            If app call esplusplayer_start before the original player is
3614  *            released, the sound of original player can be affected.
3615  * @exception None
3616  * @version   4.0
3617  * @code
3618  * ...
3619  * esplusplayer_handle esplayer1 = esplusplayer_create();
3620  * esplusplayer_open(esplayer1);
3621  * esplusplayer_set_audio_preloading(esplayer1);
3622  * esplusplayer_audio_stream_info audio_stream_1;
3623  * if (audio_stream_1's mime type is PCM or G711_MULAW)
3624  *   audio_stream_1.mime_type = ESPLUSPLAYER_AUDIO_MIME_TYPE_G711_MULAW;
3625  * else
3626  *   audio_stream_1.mime_type = ESPLUSPLAYER_AUDIO_MIME_TYPE_AAC;
3627  * esplusplayer_set_audio_stream_info(esplayer1, &audio_stream_1);
3628  * esplusplayer_prepare_async(esplayer1);
3629  * esplusplayer_start(esplayer1);
3630  * // ... while playing esplayer1 ...
3631  * // the other player can be prepared if original player is preloading mode.
3632  * esplusplayer_handle esplayer2 = esplusplayer_create();
3633  * esplusplayer_open(esplayer2);
3634  * esplusplayer_set_audio_preloading(esplayer2);
3635  * esplusplayer_audio_stream_info audio_stream_2;
3636  * if (audio_stream_1's mime type is PCM or G711_MULAW) {
3637  *   // audio_stream_2 can use the mime type except for PCM or G711_MULAW type.
3638  *   audio_stream_2.mime_type = ESPLUSPLAYER_AUDIO_MIME_TYPE_AAC;
3639  *   esplusplayer_set_audio_stream_info(esplayer2, &audio_stream_2);
3640  * } else {
3641  *   if (audio_stream_2's mime type is PCM or G711_MULAW) {
3642  *     audio_stream_2.mime_type = ESPLUSPLAYER_AUDIO_MIME_TYPE_G711_MULAW;
3643  *     esplusplayer_set_audio_stream_info(esplayer2, &audio_stream_2);
3644  *   } else {
3645  *     // if all player don't use PCM or G711_MULAW type, one player need to set
3646  *     // sw codec type.
3647  *     audio_stream_2.mime_type = ESPLUSPLAYER_AUDIO_MIME_TYPE_AAC;
3648  *     esplusplayer_set_audio_stream_info(esplayer2, &audio_stream_2);
3649  *     esplusplayer_set_audio_codec_type(esplayer2,
3650  *                                       ESPLUSPLAYER_AUDIO_CODEC_TYPE_SW);
3651  *   }
3652  * }
3653  * esplusplayer_prepare_async(esplayer2);
3654  * // the player can be started after the original player is stopped or the
3655  * // original player's audio stream is deactivated.
3656  * if (the app want to keep the original player instance)
3657  *   esplusplayer_deactivate(esplayer1,ESPLUSPLAYER_STREAM_TYPE_AUDIO);
3658  * else
3659  *   esplusplayer_stop(esplayer1);
3660  * esplusplayer_start(esplayer2);
3661  * ...
3662  * @endcode
3663  */
3664 int esplusplayer_set_audio_preloading(esplusplayer_handle handle);
3665
3666 /**
3667  * @brief     Set a callback function to be invoked when video frames are
3668  *            dropped by SoC.
3669  * @param     [in] handle : esplusplayer handle.
3670  * @param     [in] video_frame_dropped_cb : the callback function to register.
3671  * @param     [in] userdata : userdata of
3672  * esplusplayer_set_video_frame_dropped_cb()
3673  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY or
3674  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
3675  * @post      esplusplayer_video_frame_dropped_cb() will be invoked.
3676  *            if error_cb is set to null, esplusplayer_error_cb() will not be
3677  * @return    #ESPLUSPLAYER_ERROR_TYPE_NONE on success, otherwise one of
3678  *            esplusplayer_error_type values will be returned.
3679  * @exception None
3680  * @version   2.7
3681  * @see       esplusplayer_video_frame_dropped_cb()
3682  * @code
3683  * void video_frame_dropped_cb(const uint64_t count, void* userdata){
3684  * // do you job
3685  * }
3686  * esplusplayer_set_video_frame_dropped_cb(handle,
3687  * video_frame_dropped_cb, userdata);
3688  * ...
3689  * esplusplayer_prepare_async(handle);
3690  * ...
3691  * @endcode
3692  */
3693 int esplusplayer_set_video_frame_dropped_cb(
3694     esplusplayer_handle handle,
3695     esplusplayer_video_frame_dropped_cb video_frame_dropped_cb, void* userdata);
3696
3697 /**
3698  * @brief     Set video scan type.
3699  * @param     [in] handle : esplusplayer handle.
3700  * @param     [in] type : The video scan type.
3701  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
3702  * @post      None
3703  * @return    @c one of esplusplayer_error_type values will be returned.
3704  * @exception  None
3705  * @version   4.0
3706  */
3707 int esplusplayer_set_video_scan_type(esplusplayer_handle handle,
3708                                      esplusplayer_video_scan_type type);
3709
3710 /**
3711  * @brief     Get decoding time of the stream
3712  * @param     [in] handle : esplusplayer handle.
3713  * @param     [in] type : stream type.
3714  * @param     [out] time_in_milliseconds : current decoding time in
3715  * milliseconds.
3716  * @pre       The player must be one of #ESPLUSPLAYER_STATE_PAUSE or
3717  *            #ESPLUSPLAYER_STATE_PLAYING
3718  * @post      None
3719  * @return    @c one of esplusplayer_error_type values will be returned.
3720  * @exception  None
3721  * @version   2.7
3722  */
3723 int esplusplayer_get_decoding_time(esplusplayer_handle handle,
3724                                    esplusplayer_stream_type type,
3725                                    int32_t* time_in_milliseconds);
3726
3727 /**
3728  * @brief     Set the timeunit ms or us. All other espp time related API should
3729  * follow this time unit type.
3730  * @param     [in] handle : esplusplayer handle.
3731  * @param     [in] type : time unit type.
3732  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE
3733  * @post      None
3734  * @return    @c one of esplusplayer_error_type values will be returned.
3735  * @exception  None
3736  * @version   5.0
3737  */
3738 int esplusplayer_set_timeunit_type(esplusplayer_handle handle,
3739                                    esplusplayer_time_unit_type type);
3740
3741 /**
3742  * @brief     Set a callback function to be invoked when decoder receive one
3743  * input buffer.
3744  * @param     [in] handle : esplusplayer handle.
3745  * @param     [in] decoder_buffer_time_cb : the decoder input buffer time
3746  * callback function to register.
3747  * @param     [in] userdata : userdata of
3748  * esplusplayer_set_decoder_input_buffer_time_cb()
3749  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3750  * esplusplayer_error_type
3751  *            values will be returned.
3752  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3753  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3754  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3755  * failed
3756  * @code
3757  *            refer to the sample code of esplusplayer_set_error_cb();
3758  * @endcode
3759  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
3760  *            or #ESPLUSPLAYER_STATE_IDLE.
3761  * @post      None
3762  * @exception None
3763  * @version   5.0
3764  */
3765 int esplusplayer_set_decoder_input_buffer_time_cb(
3766     esplusplayer_handle handle,
3767     esplusplayer_decoder_buffer_time_cb decoder_buffer_time_cb, void* userdata);
3768
3769 /**
3770  * @brief     Set a callback function to be invoked when get one output buffer
3771  * from decoder.
3772  * @param     [in] handle : esplusplayer handle.
3773  * @param     [in] decoder_buffer_time_cb : the decoder output buffer time
3774  * callback function to register.
3775  * @param     [in] userdata : userdata of
3776  * esplusplayer_set_decoder_output_buffer_time_cb()
3777  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3778  * esplusplayer_error_type
3779  *            values will be returned.
3780  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3781  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3782  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3783  * failed
3784  * @code
3785  *            refer to the sample code of esplusplayer_set_error_cb();
3786  * @endcode
3787  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
3788  *            or #ESPLUSPLAYER_STATE_IDLE.
3789  * @post      None
3790  * @exception None
3791  * @version   5.0
3792  */
3793 int esplusplayer_set_decoder_output_buffer_time_cb(
3794     esplusplayer_handle handle,
3795     esplusplayer_decoder_buffer_time_cb decoder_buffer_time_cb, void* userdata);
3796
3797 /**
3798  * @brief     Set App id to esplayer to control resource confliction.
3799  * @param     [in] handle : esplusplayer handle.
3800  * @param     [in] app_info : application id, version, type, runtitle.
3801  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3802  * esplusplayer_error_type
3803  *            values will be returned.
3804  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3805  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3806  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3807  * failed
3808  * @code
3809  *            esplusplayer_app_info appinfo;
3810  *            appinfo.id = "youtube";
3811  *            appinfo.version = "3.0";
3812  *            appinfo.type = "MSE";
3813  *            appinfo.runtitle = "YouTube";
3814  *            esplusplayer_handle esplayer = esplusplayer_create();
3815  *            esplusplayer_open(esplayer);
3816  *            esplusplayer_set_app_info_ex(esplayer,&appinfo);
3817  *            // ... your codes ...
3818  *            esplusplayer_close(esplayer);
3819  * @endcode
3820  * @pre       The player state must be #ESPLUSPLAYER_STATE_IDLE.
3821  * @post      None
3822  * @exception None
3823  * @version   5.0
3824  * @see       esplusplayer_open()
3825  */
3826 int esplusplayer_set_app_info_ex(esplusplayer_handle handle,
3827                                  const esplusplayer_app_info_ex* app_info);
3828
3829 /**
3830  * @brief     Set the rotate angle of the video stream to video sink.
3831  *                 The rotate angle will be delivered to video render control.
3832  * @remark    This API will not actually rotate the video display
3833  * @param     [in] handle : esplusplayer handle.
3834  * @param     [in] rotation : the rotate angle of the video.
3835  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3836  * esplusplayer_error_type
3837  *            values will be returned.
3838  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3839  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3840  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3841  * failed
3842  * @code
3843  *            esplusplayer_open(esplayer);
3844  *            esplusplayer_set_video_stream_rotation_info(esplayer_,ESPLUSPLAYER_VIDEO_ROTATION_90);
3845  *            // ... your codes ...
3846  *            esplusplayer_close(esplayer);
3847  * @endcode
3848  * @pre       The player state can be all of #esplusplayer_state except
3849  *            #ESPLUSPLAYER_STATE_NONE.
3850  * @post      this API worked only when video sink created.
3851  * @exception None
3852  * @version   5.2
3853  * @see       esplusplayer_open() \n
3854  */
3855 int esplusplayer_set_video_stream_rotation_info(
3856     esplusplayer_handle handle,
3857     const esplusplayer_video_stream_rotation_type rotation);
3858
3859 /**
3860  * @brief     Get the rotate angle of the video stream.
3861  * @param     [in] handle : esplusplayer handle.
3862  * @param     [out] rotation : the rotate angle of the video stream which want
3863  * to
3864  * get.
3865  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3866  * esplusplayer_error_type
3867  *            values will be returned.
3868  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3869  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3870  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3871  * failed
3872  * @code
3873  *            esplusplayer_display_rotation_type rotation_get =
3874  * ESPLUSPLAYER_VIDEO_ROTATION_NONE;
3875  *            esplusplayer_open(esplayer);
3876  *            esplusplayer_set_video_stream_rotation_info(esplayer,ESPLUSPLAYER_VIDEO_ROTATION_90);
3877  *            // ... your codes ...
3878  *            esplusplayer_get_video_stream_rotation_info(esplayer,&rotation_get);
3879  *            // ... your codes ...
3880  *            esplusplayer_close(esplayer);
3881  * @endcode
3882  * @pre       The player state can be all of #esplusplayer_state except
3883  *            #ESPLUSPLAYER_STATE_NONE.
3884  * @post      this API worked only when video sink created.
3885  * @exception None
3886  * @version   5.2
3887  * @see       esplusplayer_open() \n
3888  *            esplusplayer_set_video_stream_rotation_info()
3889  */
3890 int esplusplayer_get_video_stream_rotation_info(
3891     esplusplayer_handle handle,
3892     esplusplayer_video_stream_rotation_type* rotation);
3893
3894 /**
3895  * @brief     Provided api for setting buffer level of simple mix out
3896  * @param     [in] handle : esplusplayer handle ptr.
3897  * @param     [in] level : set buffer level of simple mix out
3898  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of
3899  * esplusplayer_error_type values will be returned.
3900  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
3901  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
3902  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation
3903  * failed
3904  * @code
3905  *            esplusplayer_open(esplayer);
3906  *            esplusplayer_set_audio_codec_type(esplayer,
3907  * ESPLUSPLAYER_AUDIO_CODEC_TYPE_SW)
3908  *            esplusplayer_set_alternative_audio_resource(esplayer,
3909  * ESPLUSPLAYER_AUDIO_RESOURCE_SIMPLE_MIX_OUT);
3910  *            esplusplayer_set_simple_mix_out_buffer_level(esplayer,
3911  * ESPLUSPLAYER_SIMPLE_MIX_OUT_BUFFER_LOW);
3912  *             // ... your codes ...
3913  *            esplusplayer_close(esplayer);
3914  *
3915  *            prepare esplayer done
3916  *             // ... your codes ...
3917  *            esplusplayer_deactivate(esplayer, ESPLUSPLAYER_STREAM_TYPE_AUDIO)
3918  *            esplusplayer_set_audio_codec_type(esplayer,
3919  * ESPLUSPLAYER_AUDIO_CODEC_TYPE_SW)
3920  *            esplusplayer_set_alternative_audio_resource(esplayer,
3921  * ESPLUSPLAYER_AUDIO_RESOURCE_SIMPLE_MIX_OUT);
3922  *            esplusplayer_set_simple_mix_out_buffer_level(esplayer,
3923  * ESPLUSPLAYER_SIMPLE_MIX_OUT_BUFFER_LOW);
3924  *            esplusplayer_activate(esplayer, ESPLUSPLAYER_STREAM_TYPE_AUDIO);
3925  *             // ... your codes ...
3926  *            esplusplayer_close(esplayer);
3927  * @endcode
3928  * @pre       The player state can be all of #State except
3929  *            #ESPLUSPLAYER_STATE_NONE.
3930  * @post      None
3931  * @exception None
3932  * @remark    This API can set only before esplusplayer_prepare_async() or
3933  *            after esplusplayer_deactivate(ESPLUSPLAYER_STREAM_TYPE_AUDIO).
3934  * @version   3.8
3935  * @see       esplusplayer_open() \n
3936  *            esplusplayer_set_audio_codec_type()
3937  *            esplusplayer_set_alternative_audio_resource()
3938  */
3939 int esplusplayer_set_simple_mix_out_buffer_level(
3940     esplusplayer_handle handle, esplusplayer_simple_mix_out_buffer_level level);
3941
3942 #ifdef __cplusplus
3943 }
3944 #endif
3945
3946 #endif  // __ESPLUSPLAYER_ESPLUSPLAYER_CAPI_ESPLUSPLAYER_CAPI_H__