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