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