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