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