include/player.h

   1 /*
   2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   4 * Licensed under the Apache License, Version 2.0 (the "License");
   5 * you may not use this file except in compliance with the License.
   6 * You may obtain a copy of the License at
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  10 * Unless required by applicable law or agreed to in writing, software
  11 * distributed under the License is distributed on an "AS IS" BASIS,
  12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 * See the License for the specific language governing permissions and
  14 * limitations under the License.
  15 */
  16
  17 #ifndef __TIZEN_MEDIA_PLAYER_H__
  18 #define __TIZEN_MEDIA_PLAYER_H__
  19
  20 #include <tizen.h>
  21 #include <sound_manager.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 #define PLAYER_ERROR_CLASS          TIZEN_ERROR_MULTIMEDIA_CLASS | 0x20
  28
  29 /**
  30  * @file player.h
  31  * @brief This file contains the media player API.
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_MEDIA_PLAYER_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Media player handle type.
  41  */
  42 typedef struct player_s *player_h;
  43
  44 /**
  45  * @brief Enumerations of media player state
  46  */
  47 typedef enum
  48 {
  49         PLAYER_STATE_NONE,                      /**< Player is not created */
  50         PLAYER_STATE_IDLE,                              /**< Player is created, but not prepared */
  51         PLAYER_STATE_READY,                     /**< Player is ready to play media */
  52         PLAYER_STATE_PLAYING,           /**< Player is playing media */
  53         PLAYER_STATE_PAUSED,            /**< Player is paused while playing media */
  54 } player_state_e;
  55
  56
  57
  58 /**
  59  * @brief Error codes for media player
  60  */
  61 typedef enum
  62 {
  63                 PLAYER_ERROR_NONE                       = TIZEN_ERROR_NONE,                                                                                      /**< Successful */
  64                 PLAYER_ERROR_OUT_OF_MEMORY          = TIZEN_ERROR_OUT_OF_MEMORY,                            /**< Out of memory */
  65                 PLAYER_ERROR_INVALID_PARAMETER  = TIZEN_ERROR_INVALID_PARAMETER,                /**< Invalid parameter */
  66                 PLAYER_ERROR_NO_SUCH_FILE           = TIZEN_ERROR_NO_SUCH_FILE,                                 /**< No such file or directory */
  67                 PLAYER_ERROR_INVALID_OPERATION  = TIZEN_ERROR_INVALID_OPERATION,                /**< Invalid operation */
  68                 PLAYER_ERROR_FILE_NO_SPACE_ON_DEVICE = TIZEN_ERROR_FILE_NO_SPACE_ON_DEVICE,     /**< No space left on device */
  69                 PLAYER_ERROR_SEEK_FAILED            = PLAYER_ERROR_CLASS | 0x01 ,                               /**< Seek operation failure */
  70                 PLAYER_ERROR_INVALID_STATE          = PLAYER_ERROR_CLASS | 0x02 ,                               /**< Invalid state */
  71                 PLAYER_ERROR_NOT_SUPPORTED_FILE = PLAYER_ERROR_CLASS | 0x03     ,               /**< Not supported file format */
  72                 PLAYER_ERROR_INVALID_URI            = PLAYER_ERROR_CLASS | 0x04 ,                                       /**< Invalid URI */
  73                 PLAYER_ERROR_SOUND_POLICY           = PLAYER_ERROR_CLASS | 0x05 ,                               /**< Sound policy error */
  74                 PLAYER_ERROR_CONNECTION_FAILED  = PLAYER_ERROR_CLASS | 0x06,    /**< Streaming connection failed */
  75                 PLAYER_ERROR_VIDEO_CAPTURE_FAILED = PLAYER_ERROR_CLASS | 0x07,    /**< Video capture failure */
  76                 PLAYER_ERROR_DRM_EXPIRED = PLAYER_ERROR_CLASS | 0x08,                   /**< Expired license */
  77                 PLAYER_ERROR_DRM_NO_LICENSE = PLAYER_ERROR_CLASS | 0x09,                        /**< No license */
  78                 PLAYER_ERROR_DRM_FUTURE_USE = PLAYER_ERROR_CLASS | 0x0a,                /**< License for future use */
  79                 PLAYER_ERROR_DRM_NOT_PERMITTED = PLAYER_ERROR_CLASS | 0x0b              /**< Not permitted format */
  80 } player_error_e;
  81
  82 /**
  83  * @brief Enumerations of player interrupted type
  84  */
  85 typedef enum
  86 {
  87        PLAYER_INTERRUPTED_COMPLETED = 0,                                /**< Interrupt completed*/
  88        PLAYER_INTERRUPTED_BY_MEDIA,                             /**< Interrupted by non-resumable media application*/
  89        PLAYER_INTERRUPTED_BY_CALL,                                              /**< Interrupted by incoming call*/
  90        PLAYER_INTERRUPTED_BY_EARJACK_UNPLUG,                    /**< Interrupted by unplugging headphone*/
  91        PLAYER_INTERRUPTED_BY_RESOURCE_CONFLICT,         /**< Interrupted by resource conflict*/
  92        PLAYER_INTERRUPTED_BY_ALARM,                                     /**< Interrupted by alarm*/
  93        PLAYER_INTERRUPTED_BY_EMERGENCY,                                 /**< Interrupted by emergency*/
  94        PLAYER_INTERRUPTED_BY_RESUMABLE_MEDIA,                           /**< Interrupted by resumable media application*/
  95 } player_interrupted_code_e;
  96
  97 /**
  98  * @brief Enumerations of progressive download message type
  99  */
 100 typedef enum
 101 {
 102                 PLAYER_PD_STARTED = 0,                          /**< Progressive download is started */
 103        PLAYER_PD_COMPLETED,                             /**< Progressive download is completed */
 104 } player_pd_message_type_e;
 105
 106 /**
 107  * @brief
 108  * Enumerations of display type
 109  */
 110 typedef enum
 111 {
 112   PLAYER_DISPLAY_TYPE_X11 = 0,                  /**< X surface display */
 113   PLAYER_DISPLAY_TYPE_EVAS = 1,         /**< Evas image object surface display */
 114 } player_display_type_e;
 115
 116 /**
 117  * @brief Enumerations of audio latency mode
 118  */
 119 typedef enum
 120 {
 121         AUDIO_LATENCY_MODE_LOW = 0,     /**< Low audio latency mode*/
 122         AUDIO_LATENCY_MODE_MID,         /**< Middle audio latency mode*/
 123         AUDIO_LATENCY_MODE_HIGH,                /**< High audio latency mode*/
 124 } audio_latency_mode_e;
 125
 126 /**
 127  * @brief Player display handle
 128  *
 129  */
 130 typedef void* player_display_h;
 131
 132 #ifndef GET_DISPLAY
 133 /**
 134  * @brief Gets a display handle from x window id or evas object
 135  */
 136 #include <stdint.h>
 137 #define GET_DISPLAY(x) ((void*)((intptr_t)(x)))
 138 #endif
 139
 140 /**
 141  * @}
 142  */
 143
 144 /**
 145  * @addtogroup CAPI_MEDIA_PLAYER_X11_DISPLAY_MODULE
 146  * @{
 147  */
 148
 149 /**
 150  * @brief Enumerations of x surface display rotation type.
 151  */
 152 typedef enum
 153 {
 154         PLAYER_DISPLAY_ROTATION_NONE,   /**< Display is not rotated */
 155         PLAYER_DISPLAY_ROTATION_90,             /**< Display is rotated 90 degrees */
 156         PLAYER_DISPLAY_ROTATION_180,    /**< Display is rotated 180 degrees */
 157         PLAYER_DISPLAY_ROTATION_270,    /**< Display is rotated 270 degrees */
 158 } player_display_rotation_e;
 159
 160 /**
 161  * @brief  Enumerations of x surface display aspect ratio
 162  */
 163 typedef enum
 164 {
 165         PLAYER_DISPLAY_MODE_LETTER_BOX = 0,     /**< Letter box*/
 166         PLAYER_DISPLAY_MODE_ORIGIN_SIZE,                /**< Origin size*/
 167         PLAYER_DISPLAY_MODE_FULL_SCREEN,                /**< full-screen*/
 168         PLAYER_DISPLAY_MODE_CROPPED_FULL,       /**< Cropped full-screen*/
 169         PLAYER_DISPLAY_MODE_ORIGIN_OR_LETTER,   /**< Origin size (if surface size is larger than video size(width/height)) or Letter box (if video size(width/height) is larger than surface size)*/
 170         PLAYER_DISPLAY_MODE_ROI,                        /**< ROI mode*/
 171 } player_display_mode_e;
 172
 173
 174 /**
 175  * @}
 176  */
 177
 178 /**
 179  * @addtogroup CAPI_MEDIA_PLAYER_STREAM_INFO_MODULE
 180  * @{
 181  */
 182
 183 /**
 184  * @brief  Enumerations of media stream content information
 185  */
 186 typedef enum
 187 {
 188   PLAYER_CONTENT_INFO_ALBUM,            /**< Album */
 189   PLAYER_CONTENT_INFO_ARTIST,           /**< Artist */
 190   PLAYER_CONTENT_INFO_AUTHOR,   /**< Author */
 191   PLAYER_CONTENT_INFO_GENRE,            /**< Genre */
 192   PLAYER_CONTENT_INFO_TITLE,            /**< Title */
 193   PLAYER_CONTENT_INFO_YEAR,                     /**< Year */
 194 } player_content_info_e;
 195
 196 /**
 197  * @brief  Enumerations of media stream content information
 198  */
 199 typedef enum
 200 {
 201   PLAYER_TRACK_TYPE_AUDIO,              /**< Audio Track */
 202   PLAYER_TRACK_TYPE_VIDEO,              /**< Video Track */
 203   PLAYER_TRACK_TYPE_TEXT,       /**< Text Track */
 204 } player_track_type_e;
 205 /**
 206  * @}
 207  */
 208
 209 /**
 210  * @addtogroup CAPI_MEDIA_PLAYER_AUDIO_EFFECT_MODULE
 211  * @{
 212  */
 213
 214 /**
 215  * @brief Enumerations of audio effect
 216  */
 217 typedef enum{
 218         AUDIO_EFFECT_3D = 1,    /**< 3D effect */
 219         AUDIO_EFFECT_BASS,              /**< Bass effect */
 220         AUDIO_EFFECT_ROOM,              /**< Room effect */
 221         AUDIO_EFFECT_REVERB,    /**< Reverberation effect */
 222         AUDIO_EFFECT_CLARITY,   /**< Clarity effect */
 223 } audio_effect_e;
 224
 225 /**
 226  * @brief Enumerations of preset audio effect
 227  */
 228 typedef enum{
 229         AUDIO_EFFECT_PRESET_AUTO = 0,           /**< Auto */
 230         AUDIO_EFFECT_PRESET_NONE,                       /**< None */
 231         AUDIO_EFFECT_PRESET_POP,                        /**< POP */
 232         AUDIO_EFFECT_PRESET_ROCK,                       /**< Rock */
 233         AUDIO_EFFECT_PRESET_DANCE,                      /**< Dance */
 234         AUDIO_EFFECT_PRESET_JAZZ,                       /**< Jazz */
 235         AUDIO_EFFECT_PRESET_CLASSIC,            /**< Classic */
 236         AUDIO_EFFECT_PRESET_VOCAL,                      /**< Vocal */
 237         AUDIO_EFFECT_PRESET_BASS_BOOST,         /**< Bass boost */
 238         AUDIO_EFFECT_PRESET_TREBLE_BOOST,       /**< Treble boost */
 239         AUDIO_EFFECT_PRESET_MTHEATER,           /**< Theater */
 240         AUDIO_EFFECT_PRESET_EXTERNALIZATION,/**< Externalization */
 241         AUDIO_EFFECT_PRESET_CAFE,                       /**< Cafe */
 242         AUDIO_EFFECT_PRESET_CONCERT_HALL,       /**< Concert Hall */
 243         AUDIO_EFFECT_PRESET_VOICE,                      /**< Voice */
 244         AUDIO_EFFECT_PRESET_MOVIE,                      /**< Movie */
 245         AUDIO_EFFECT_PRESET_VIRTUAL_5_1,        /**< Virtual 5.1 */
 246         AUDIO_EFFECT_PRESET_HIPHOP,                     /**< HipHop */
 247         AUDIO_EFFECT_PRESET_RNB,                        /**< R&B */
 248         AUDIO_EFFECT_PRESET_FLAT,                       /**< Flat */
 249 } audio_effect_preset_e;
 250
 251 /**
 252  * @brief       Called once for each supported audio effect.
 253  * @param[in] effect  The audio effect
 254  * @param[in] user_data The user data passed from the foreach function
 255  * @return      @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 256  * @pre player_audio_effect_foreach_supported_effect() will invoke this callback.
 257  * @see player_audio_effect_foreach_supported_effect()
 258  */
 259 typedef bool (*player_audio_effect_supported_effect_cb)(audio_effect_e effect, void *user_data);
 260
 261 /**
 262  * @brief       Called once for each supported preset audio effect.
 263  * @param[in] preset  The preset audio effect
 264  * @param[in] user_data The user data passed from the foreach function
 265  * @return      @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 266  * @pre player_audio_effect_foreach_supported_preset() will invoke this callback.
 267  * @see player_audio_effect_foreach_supported_preset()
 268  */
 269 typedef bool (*player_audio_effect_supported_preset_cb)(audio_effect_preset_e preset, void *user_data);
 270
 271 /**
 272  * @}
 273  */
 274
 275 /**
 276  * @addtogroup CAPI_MEDIA_PLAYER_X11_DISPLAY_MODULE
 277  * @{
 278  */
 279
 280 /**
 281  * @internal
 282  * @brief  Called when the media player needs updated xid.
 283  * @remarks If current display type is not #PLAYER_DISPLAY_TYPE_X11, no operation is performed.
 284  * @param[in]   user_data  The user data passed from the callback registration function
 285  * @pre It will be invoked when player needs updated xid if you register this callback using player_set_x11_display_pixmap()
 286  * @return      The updated xid
 287  * @see player_set_x11_display_pixmap()
 288  */
 289 typedef unsigned int (*player_x11_pixmap_updated_cb)(void *user_data);
 290
 291 /**
 292  * @internal
 293  * @brief  Called when the media player needs to inform rendering error.
 294  * @remarks If current display type is not #PLAYER_DISPLAY_TYPE_X11, no operation is performed.
 295  * @param[in]   pixmap_id  The pixmap_id where the rendering error is occurred
 296  * @param[in]   user_data  The user data passed from the callback registration function
 297  * @see player_set_x11_display_pixmap_error_cb()
 298  */
 299 typedef void (*player_x11_pixmap_error_cb)(unsigned int *pixmap_id, void *user_data);
 300
 301 /**
 302  * @}
 303  */
 304
 305
 306 /**
 307  * @addtogroup CAPI_MEDIA_PLAYER_MODULE
 308  * @{
 309  */
 310
 311 /**
 312  * @brief  Called when the media player is prepared.
 313  * @details It will be invoked when player has reached the begin of stream
 314  * @param[in]   user_data  The user data passed from the callback registration function
 315  * @pre player_prepare_async() will cause this callback
 316  * @post The player state will be #PLAYER_STATE_READY
 317  * @see player_prepare_async()
 318  */
 319 typedef void (*player_prepared_cb)(void *user_data);
 320
 321 /**
 322  * @brief  Called when the media player is completed.
 323  * @details It will be invoked when player has reached to the end of the stream.
 324  * @param[in]   user_data  The user data passed from the callback registration function
 325  * @pre It will be invoked when playback completed if you register this callback using player_set_completed_cb()
 326  * @see player_set_completed_cb()
 327  * @see player_unset_completed_cb()
 328  */
 329 typedef void (*player_completed_cb)(void *user_data);
 330
 331 /**
 332  * @brief  Called when the seek operation is completed.
 333  * @param[in]   user_data  The user data passed from the callback registration function
 334  * @see player_set_position()
 335  * @see player_set_position_ratio()
 336  */
 337 typedef void (*player_seek_completed_cb)(void *user_data);
 338
 339 /**
 340  * @brief  Called when the media player is interrupted.
 341  * @param[in]   error_code      The interrupted error code
 342  * @param[in]   user_data       The user data passed from the callback registration function
 343  * @see player_set_interrupted_cb()
 344  * @see player_unset_interrupted_cb()
 345  */
 346 typedef void (*player_interrupted_cb)(player_interrupted_code_e code, void *user_data);
 347
 348 /**
 349  * @brief  Called when the media player occured error.
 350  * @param[in]   error_code  Error code
 351  * @param[in]   user_data       The user data passed from the callback registration function
 352  * @see player_set_error_cb()
 353  * @see player_unset_error_cb()
 354  * @see #player_error_e
 355  */
 356 typedef void (*player_error_cb)(int error_code, void *user_data);
 357
 358 /**
 359  * @brief  Called when the buffering percentage of media playback is updated.
 360  * @details If the buffer is full, it will return 100%.
 361  * @param[in]   percent The percentage of buffering completed (0~100)
 362  * @param[in]   user_data       The user data passed from the callback registration function
 363  * @see player_set_buffering_cb()
 364  * @see player_unset_buffering_cb()
 365  */
 366 typedef void (*player_buffering_cb)(int percent, void *user_data);
 367
 368
 369 /**
 370  * @brief  Called when the subtitle is updated.
 371  * @param[in]   duration        The duration of subtitle updated
 372  * @param[in]   text    The text of subtitle updated
 373  * @param[in]   user_data       The user data passed from the callback registration function
 374  * @see player_set_subtitle_updated_cb()
 375  * @see player_unset_subtitle_updated_cb()
 376  */
 377 typedef void (*player_subtitle_updated_cb)(unsigned long duration, char *text, void *user_data);
 378
 379 /**
 380  * @brief  Called when the progressive download is started or completed.
 381  * @param[in]   type    The message type of progressive download
 382  * @param[in]   user_data       The user data passed from the callback registration function
 383  * @see player_set_progressive_download_path()
 384  */
 385 typedef void (*player_pd_message_cb)(player_pd_message_type_e type, void *user_data);
 386
 387 /**
 388  * @brief  Called when the video is captured.
 389  * @remarks The color space format of the captured image is #IMAGE_UTIL_COLORSPACE_RGB888.
 390  * @param[in]   data    The captured image buffer
 391  * @param[in]   width   The width of captured image
 392  * @param[in]   height The height of captured image
 393  * @param[in]   size    The size of captured image
 394  * @param[in]   user_data       The user data passed from the callback registration function
 395  * @see player_capture_video()
 396  */
 397 typedef void (*player_video_captured_cb)(unsigned char *data, int width, int height, unsigned int size, void *user_data);
 398
 399 /**
 400  * @brief  Called when the video frame is decoded.
 401  * @remarks The color space format of the captured image is #IMAGE_UTIL_COLORSPACE_RGB888.
 402  * @param[in]   data    The decoded video frame data
 403  * @param[in]   width   The width of video frame
 404  * @param[in]   height The height of video frame
 405  * @param[in]   size    The size of video frame
 406  * @param[in]   user_data       The user data passed from the callback registration function
 407  * @see player_set_video_frame_decoded_cb()
 408  * @see player_unset_video_frame_decoded_cb()
 409  */
 410 typedef void (*player_video_frame_decoded_cb)(unsigned char *data, int width, int height, unsigned int size, void *user_data);
 411
 412 /**
 413  * @brief  Called when the audio frame is decoded.
 414  * @param[in]   data    The decoded audio frame data
 415  * @param[in]   size    The size of audio frame
 416  * @param[in]   user_data       The user data passed from the callback registration function
 417  * @see player_set_audio_frame_decoded_cb()
 418  * @see player_unset_audio_frame_decoded_cb()
 419  */
 420 typedef void (*player_audio_frame_decoded_cb)(unsigned char *data, unsigned int size, void *user_data);
 421
 422 /**
 423  * @brief Creates a player handle for playing multimedia content.
 424  * @remarks @a player must be released player_destroy() by you.
 425  * @remarks
 426  *  Although you can create multiple player handles at the same time,
 427  *  the player cannot guarantee proper operation because of limited resources, such as
 428  *  audio or display device.
 429  *
 430  * @param[out]  player  A new handle to media player
 431  * @retval #PLAYER_ERROR_NONE Successful
 432  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 433  * @retval #PLAYER_ERROR_OUT_OF_MEMORY Out of memory
 434  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 435  * @post The player state will be #PLAYER_STATE_IDLE.
 436  * @see player_destroy()
 437  */
 438 int player_create(player_h *player);
 439
 440
 441 /**
 442  * @brief Destroys the media player handle and releases all its resources.
 443  *
 444  * @remarks To completely shutdown player operation, call this function with a valid player handle from any player state.
 445  *
 446  * @param[in]           player The handle to media player to be destroyed
 447  * @return 0 on success, otherwise a negative error value.
 448  * @retval #PLAYER_ERROR_NONE Successful
 449  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 450  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 451  * @pre  The player state should be #PLAYER_STATE_IDLE
 452  * @post The player state will be #PLAYER_STATE_NONE.
 453  * @see player_create()
 454  */
 455 int player_destroy(player_h player);
 456
 457 /**
 458  * @brief Prepares the media player for playback.
 459  * @param[in]   player The handle to media player
 460  * @return 0 on success, otherwise a negative error value.
 461  * @retval #PLAYER_ERROR_NONE Successful
 462  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 463  * @retval #PLAYER_ERROR_INVALID_URI Invalid URI
 464  * @retval #PLAYER_ERROR_NO_SUCH_FILE File not found
 465  * @retval #PLAYER_ERROR_NOT_SUPPORTED_FILE Not supported file
 466  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 467  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 468  * @pre The player state should be #PLAYER_STATE_IDLE by player_create() or player_unprepare(). After that, call player_set_uri() to load the media content you want to play.
 469  * @post The player state will be #PLAYER_STATE_READY.
 470  * @see player_prepare_async()
 471  * @see player_unprepare()
 472  * @see player_set_uri()
 473  */
 474 int player_prepare(player_h player);
 475
 476 /**
 477  * @brief Prepares the media player for playback, asynchronously.
 478  * @param[in]   player The handle to media player
 479  * @return 0 on success, otherwise a negative error value.
 480  * @retval #PLAYER_ERROR_NONE Successful
 481  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 482  * @retval #PLAYER_ERROR_INVALID_URI Invalid URI
 483  * @retval #PLAYER_ERROR_NO_SUCH_FILE File not found
 484  * @retval #PLAYER_ERROR_NOT_SUPPORTED_FILE Not supported file
 485  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 486  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 487  * @pre The player state should be #PLAYER_STATE_IDLE by player_create() or player_unprepare().. After that, call player_set_uri() to load the media content you want to play..
 488  * @post It invokes player_prepared_cb() when playback is prepare.
 489  * @see player_prepare()
 490  * @see player_prepared_cb()
 491  * @see player_unprepare()
 492  * @see player_set_uri()
 493  */
 494 int player_prepare_async (player_h player, player_prepared_cb callback, void* user_data);
 495
 496 /**
 497  * @brief Reset the media player.
 498  * @details
 499  *      The most recently used media is reset and no longer associated with the player.
 500  * Playback is no longer possible. If you want to use the player again, you will have to set the data URI and call
 501  * player_prepare() again.
 502  * @param[in]           player The handle to media player
 503  * @return 0 on success, otherwise a negative error value.
 504  * @retval #PLAYER_ERROR_NONE Successful
 505  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 506  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 507  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 508  * @pre The player state should be #PLAYER_STATE_READY by player_prepare() or player_stop().
 509  * @post The player state will be #PLAYER_STATE_IDLE.
 510  * @see player_prepare()
 511  */
 512 int player_unprepare(player_h player);
 513
 514 /**
 515  * @brief Sets the data source (file-path, http or rtsp URI) to use.
 516  *
 517  * @details
 518  *      Associates media contents, referred to by the URI, with the player.
 519  * If the function call is successful, subsequent calls to player_prepare() and player_start() will start playing the media.
 520  *
 521  * @remarks
 522  * If you use http or rtsp, URI should start with "http://" or "rtsp://". The default protocol is "file://".
 523  * If you provide an invalid URI, you won't receive an error message until you call player_start().
 524  *
 525  * @param[in]   player The handle to media player
 526  * @param[in]   uri Specifies the content location, such as the file path, the URI of the http or rtsp stream you want to play
 527  *
 528  * @return 0 on success, otherwise a negative error value.
 529  * @retval #PLAYER_ERROR_NONE Successful
 530  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 531  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 532  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 533  * @pre The player state should be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
 534  * @see player_set_memory_buffer()
 535  */
 536 int player_set_uri(player_h player, const char * uri);
 537
 538 /**
 539  * @brief Sets memory as the data source.
 540  *
 541  * @details
 542  * Associates media content, cached in memory, with the player. Unlike the case of player_set_uri(), the media resides in memory.
 543  * If the function call is successful, subsequent calls to player_prepare() and player_start() will start playing the media.
 544  *
 545  * @remarks
 546  * If you provide an invalid data, you won't receive an error message until you call player_start().
 547  *
 548  *
 549  * @param[in]   player The handle to media player
 550  * @param[in]   data The memory pointer of media data
 551  * @param[in]   size The size of media data
 552  * @return 0 on success, otherwise a negative error value.
 553  * @retval #PLAYER_ERROR_NONE Successful
 554  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 555  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 556  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 557  * @pre The player state should be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
 558  * @see player_set_uri()
 559  */
 560 int player_set_memory_buffer(player_h player, const void * data, int size);
 561
 562 /**
 563  * @brief Gets the player's current state.
 564  * @param[in]   player  The handle to media player
 565  * @param[out]  state   The current state of the player
 566  * @return 0 on success, otherwise a negative error value.
 567  * @retval #PLAYER_ERROR_NONE Successful
 568  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 569  * @see #player_state_e
 570  */
 571 int  player_get_state(player_h player, player_state_e *state);
 572
 573
 574 /**
 575  * @brief Sets the player's volume.
 576  *
 577  * @details
 578  *      The range of @a left and @c right is from 0 to 1.0, inclusive (1.0 = 100%). Default value is 1.0.
 579  *      Setting this volume adjusts the player volume, not the system volume.
 580  * To change system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
 581  *
 582  * @param[in]   player The handle to media player
 583  * @param[in]   left Left volume scalar
 584  * @param[in]   right Right volume scalar
 585  * @return 0 on success, otherwise a negative error value.
 586  * @retval #PLAYER_ERROR_NONE Successful
 587  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 588  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 589  * @see player_get_volume()
 590  */
 591 int player_set_volume(player_h player, float left, float right);
 592
 593
 594 /**
 595  * @brief Gets the player's current volume factor.
 596  *
 597  * @details The range of @a left and @a right is from 0 to 1.0, inclusive (1.0 = 100%). This function gets the player volume, not the system volume.
 598  * To get the system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
 599  *
 600  * @param[in]   player The handle to media player
 601  * @param[out]  left The current left volume scalar
 602  * @param[out]  right The current right volume scalar
 603  * @return 0 on success, otherwise a negative error value.
 604  * @retval #PLAYER_ERROR_NONE Successful
 605  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 606  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 607  * @see player_set_volume()
 608  */
 609 int player_get_volume(player_h player, float *left, float *right);
 610
 611 /**
 612  * @brief Sets the player's sound type.
 613  *
 614  * @remarks
 615  *      The default sound type of player is #SOUND_TYPE_MEDIA.
 616  * To get current sound type, use the sound_manager_get_current_sound_type().
 617  *
 618  * @param[in]   player The handle to media player
 619  * @param[in]   type The sound type
 620  * @return 0 on success, otherwise a negative error value.
 621  * @retval #PLAYER_ERROR_NONE Successful
 622  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 623  * @pre The player state must be #PLAYER_STATE_IDLE by player_create().
 624  * @see sound_manager_get_current_sound_type()
 625  */
 626 int player_set_sound_type(player_h player, sound_type_e type);
 627
 628 /**
 629  * @brief Set the latency mode of audio.
 630  *
 631  * @remarks
 632  *      The default audio latency mode of player is #AUDIO_LATENCY_MODE_MID.
 633  *      To get current audio latency mode, use player_get_audio_latency_mode().
 634  *
 635  * @param[in] player The handle to media player.
 636  * @param[in] latency_mode The latency mode to be applyed to audio.
 637  * @return 0 on success, otherwise a negative error value.
 638  * @retval #PLAYER_ERROR_NONE Successful.
 639  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter.
 640  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation.
 641  * @see #audio_latency_mode_e.
 642  * @see player_get_audio_latency_mode().
 643  */
 644 int player_set_audio_latency_mode(player_h player, audio_latency_mode_e latency_mode);
 645
 646 /**
 647  * @brief Get current latency mode of audio.
 648  * @param[in] player The handle to media player.
 649  * @param[out] latency_mode The latency mode to get from audio.
 650  * @return 0 on success, otherwise a negative error value.
 651  * @retval #PLAYER_ERROR_NONE Successful.
 652  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter.
 653  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation.
 654  * @see #audio_latency_mode_e.
 655  * @see player_set_audio_latency_mode().
 656  */
 657 int player_get_audio_latency_mode(player_h player, audio_latency_mode_e *latency_mode);
 658
 659 /**
 660  * @brief Starts or resumes playback.
 661  *
 662  * @details Plays current media content, or resumes play if paused.
 663  *
 664  * @param[in]   player The handle to media player
 665  * @return 0 on success, otherwise a negative error value.
 666  * @retval #PLAYER_ERROR_NONE Successful
 667  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 668  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 669  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 670  * @retval #PLAYER_ERROR_CONNECTION_FAILED Network connection failed
 671  * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
 672  * @pre Call player_prepare() before calling this function.
 673  * @pre The player state must be #PLAYER_STATE_READY by player_prepare() or #PLAYER_STATE_PAUSED by player_pause().
 674  * @post The player state will be #PLAYER_STATE_PLAYING.
 675  * @post It invokes player_completed_cb() when playback completes, if you set a callback with player_set_completed_cb().
 676  * @post It invokes player_pd_message_cb() when progressive download starts or completes, if you set a download path with player_set_progressive_download_path() and a callback with player_set_progressive_download_message_cb().
 677  * @see player_prepare()
 678  * @see player_prepare_async()
 679  * @see player_stop()
 680  * @see player_pause()
 681  * @see player_set_completed_cb()
 682  * @see player_completed_cb()
 683  * @see player_set_progressive_download_path()
 684  * @see player_set_progressive_download_message_cb()
 685  * @see player_pd_message_cb()
 686  */
 687 int player_start(player_h player);
 688
 689
 690 /**
 691  * @brief Stops playing media content.
 692  * @param[in]   player The handle to media player
 693  * @return 0 on success, otherwise a negative error value.
 694  * @retval #PLAYER_ERROR_NONE Successful
 695  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid state
 696  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 697  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 698  * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
 699  * @pre The player state must be either #PLAYER_STATE_PLAYING by player_start() or #PLAYER_STATE_PAUSED by player_pause().
 700  * @post The player state will be #PLAYER_STATE_READY.
 701  * @post The downloading will be aborted if you use progressive download.
 702  * @see player_start()
 703  * @see player_pause()
 704  */
 705 int player_stop(player_h player);
 706
 707 /**
 708  * @brief Pauses the player.
 709  *
 710  * @remarks     Playback can be resumed with player_start().
 711  *
 712  * @param[in]   player The handle to media player
 713  * @return 0 on success, otherwise a negative error value.
 714  * @retval #PLAYER_ERROR_NONE Successful
 715  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid state
 716  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 717  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 718  * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
 719  * @pre The player state must be #PLAYER_STATE_PLAYING.
 720  * @post The player state will be #PLAYER_STATE_READY.
 721  * @see player_start()
 722  */
 723 int player_pause(player_h player);
 724
 725 /**
 726  * @brief Sets the seek position for playback, asynchronously.
 727  * @param[in] player The handle to media player
 728  * @param[in] millisecond The position in milliseconds from the start to seek to
 729  * @param[in] callback  The callback function to register
 730  * @param[in] user_data The user data to be passed to the callback function
 731  * @return 0 on success, otherwise a negative error value.
 732  * @retval #PLAYER_ERROR_NONE Successful
 733  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 734  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 735  * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
 736  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 737  * @post It invokes player_seek_completed_cb() when seek operation completes, if you set a callback.
 738  * @see player_get_position()
 739  * @see player_get_position_ratio()
 740  * @see player_set_position_ratio()
 741  */
 742 int player_set_position(player_h player, int millisecond, player_seek_completed_cb callback, void *user_data);
 743
 744 /**
 745  * @brief Sets the seek position for playback, asynchronously.
 746  * @param[in] player The handle to media player
 747  * @param[in] millisecond The position in milliseconds from the start to seek to
 748  * @param[in] accurate if true, the position selected will be returned but, this might be considerably slow.
 749  * @param[in] callback  The callback function to register
 750  * @param[in] user_data The user data to be passed to the callback function
 751  * @return 0 on success, otherwise a negative error value.
 752  * @retval #PLAYER_ERROR_NONE Successful
 753  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 754  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 755  * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
 756  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 757  * @post It invokes player_seek_completed_cb() when seek operation completes, if you set a callback.
 758  * @see player_get_position()
 759  * @see player_get_position_ratio()
 760  * @see player_set_position_ratio()
 761  */
 762 int player_seek(player_h player, int millisecond, bool accurate, player_seek_completed_cb callback, void *user_data);
 763
 764 /**
 765  * @brief Sets the playback position specified by percent of media content played, asynchronously.
 766  * @param[in] player The handle to media player
 767  * @param[in] percent The position in percentage from the start to seek to. \n The position is relative to content. (length, 0 = beginning, 100 = end)
 768  * @param[in] callback  The callback function to register
 769  * @param[in] user_data The user data to be passed to the callback function
 770  * @return 0 on success, otherwise a negative error value.
 771  * @retval #PLAYER_ERROR_NONE Successful
 772  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 773  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 774  * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
 775  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 776  * @post It invokes player_seek_completed_cb() when seek operation completes, if you set a callback.
 777  * @see player_get_position()
 778  * @see player_get_position_ratio()
 779  * @see player_set_position()
 780  */
 781 int player_set_position_ratio(player_h player, int percent, player_seek_completed_cb callback, void *user_data);
 782
 783 /**
 784  * @brief Gets current position in milliseconds.
 785  * @param[in]   player The handle to media player
 786  * @param[out]  millisecond The current position in milliseconds
 787  * @return 0 on success, otherwise a negative error value.
 788  * @retval #PLAYER_ERROR_NONE Successful
 789  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 790  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 791  * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
 792  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 793  * @see player_get_position_ratio()
 794  * @see player_set_position()
 795  * @see player_set_position_ratio()
 796  */
 797
 798 int player_get_position(player_h player, int *millisecond);
 799
 800 /**
 801  * @brief Gets the playback position specified by percent of media content played.
 802  * @param[in]   player The handle to media player
 803  * @param[out]  percent The current position in percentage [0, 100]
 804  * @return 0 on success, otherwise a negative error value.
 805  * @retval #PLAYER_ERROR_NONE Successful
 806  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 807  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 808  * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
 809  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 810  * @see player_get_position()
 811  * @see player_set_position()
 812  * @see player_set_position_ratio()
 813  */
 814 int player_get_position_ratio(player_h player, int *percent);
 815
 816 /**
 817  * @brief Sets the player's mute status.
 818  *
 819  * @details  If the mute status is @c true, no sounds will be played. If @c false, sounds will be played at the previously set volume level. Until this function is called, by default the player is not muted.
 820  *
 821  * @param[in]   player The handle to media player
 822  * @param[in]   muted New mute status: (@c true = mute, @c false = not muted)
 823  * @return 0 on success, otherwise a negative error value.
 824  * @retval #PLAYER_ERROR_NONE Successful
 825  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 826  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 827  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 828  * @see player_is_muted()
 829  */
 830 int player_set_mute(player_h player, bool muted);
 831
 832 /**
 833  * @brief Gets the player's mute status.
 834  *
 835  * @details If the mute status is @c true, no sounds are played. If @c false, sounds are played at previously set volume level.
 836  *
 837  * @param[in]   player The handle to media player
 838  * @param[out]  muted  The current mute status: (@c true = mute, @c false = not muted)
 839  * @return 0 on success, otherwise a negative error value.
 840  * @retval #PLAYER_ERROR_NONE Successful
 841  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 842  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 843  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 844  * @see player_set_mute()
 845  */
 846 int player_is_muted(player_h player, bool *muted);
 847
 848 /**
 849  * @brief Sets the player's looping status.
 850  *
 851  * @details     If the looping status is @c true, playback will automatically restart upon finishing. If @c false, it won't. The default value is false.
 852  *
 853  * @param[in]   player The handle to media player
 854  * @param[in]   looping New looping status: (@c true = looping, @c false = non-looping )
 855  * @return 0 on success, otherwise a negative error value.
 856  * @retval #PLAYER_ERROR_NONE Successful
 857  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 858  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 859  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 860  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 861  * @see player_is_looping()
 862  */
 863 int player_set_looping(player_h player, bool looping);
 864
 865
 866 /**
 867  * @brief Gets the player's looping status.
 868  *
 869  * @details  If the looping status is @c true, playback will automatically restart upon finishing. If @c false, it won't.
 870  *
 871  * @param[in]   player The handle to media player
 872  * @param[out]  looping The looping status: (@c true = looping, @c false = non-looping )
 873  * @return 0 on success, otherwise a negative error value.
 874  * @retval #PLAYER_ERROR_NONE Successful
 875  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 876  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 877  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 878  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 879  * @see player_set_looping()
 880  */
 881 int player_is_looping(player_h player, bool *looping);
 882
 883 /**
 884  * @brief Gets the total running time of the associated media.
 885  * @remarks The media source is associated with the player, using either player_set_uri() or player_set_memory_buffer().
 886  * @remarks  The playback type should be local playback or http streaming playback.
 887  * @param[in]   player The handle to media player
 888  * @param[out]  duration The duration is in milliseconds
 889  * @return 0 on success, otherwise a negative error value.
 890  * @retval #PLAYER_ERROR_NONE Successful
 891  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 892  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 893  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 894  * @pre The player state must be one of: #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 895  * @see player_get_position()
 896  * @see player_set_uri()
 897  * @see player_set_memory_buffer()
 898  */
 899 int player_get_duration(player_h player, int *duration);
 900
 901 /**
 902  * @brief Sets the video display.
 903  * @remaks To get @a display to set, use #GET_DISPLAY().
 904  * @remaks To use multiple surface display mode, use player_set_display() again with different display type.
 905  * @param[in]   player The handle to media player
 906  * @param[in]   type The display type
 907  * @param[in]   display The handle to display
 908  * @return 0 on success, otherwise a negative error value.
 909  * @retval #PLAYER_ERROR_NONE Successful
 910  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 911  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 912  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 913  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 914  */
 915 int player_set_display(player_h player, player_display_type_e type, player_display_h display);
 916
 917 /**
 918  * @brief Gets the availability of display mode change
 919  * @remark The result can be changed by display setting.
 920  * @param[in] player The handle to media player
 921  * @param[out] changeable The cuurent availability of display mode change (@c true = changeable, @c false = non-changeable )
 922  * @return 0 on success, otherwise a negative error value.
 923  * @retval  #PLAYER_ERROR_NONE Successful
 924  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 925  * @see player_set_display_mode()
 926  */
 927 int player_is_display_mode_changeable(player_h player, bool* changeable);
 928
 929 /**
 930  * @brief Sets a video display mode
 931  * @remarks If no display is not set, no operation is performed.
 932  * @param[in] player   The handle to media player
 933  * @param[in] mode The display mode
 934  * @return 0 on success, otherwise a negative error value.
 935  * @retval #PLAYER_ERROR_NONE Successful
 936  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 937  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
 938  * @pre The player should be supported display mode changing. (player_is_display_mode_changeable())
 939  * @see player_get_display_mode()
 940  */
 941 int player_set_display_mode(player_h player, player_display_mode_e mode);
 942
 943 /**
 944  * @brief Gets the video display mode
 945  * @remarks If no display is not set, no operation is performed.
 946  * @param[in] player The handle to media player
 947  * @param[out] mode The current display mode
 948  * @return 0 on success, otherwise a negative error value.
 949  * @retval  #PLAYER_ERROR_NONE Successful
 950  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 951  * @see player_set_display_mode()
 952  */
 953 int player_get_display_mode(player_h player, player_display_mode_e *mode);
 954
 955 /**
 956  * @brief Sets the playback rate
 957  * @details The default value is 1.0.
 958  * @remarks #PLAYER_ERROR_INVALID_OPERATION occured if streaming playbak.
 959  * @remarks No operation is performed, if @a rate is 0.
 960  * @remarks The sound is muted, when playback rate is under 0.0 and over 2.0.
 961  * @param[in]   player The handle to media player
 962  * @param[in]   rate The playback rate (-5.0x ~ 5.0x)
 963  * @return 0 on success, otherwise a negative error value.
 964  * @retval #PLAYER_ERROR_NONE Successful
 965  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 966  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 967  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 968  * @pre The player state must be #PLAYER_STATE_PLAYING by player_start().
 969  * @pre The player state must be #PLAYER_STATE_READY by player_prepare() or #PLAYER_STATE_PLAYING by player_start() or #PLAYER_STATE_PAUSED by player_pause().
 970  */
 971 int player_set_playback_rate(player_h player, float rate);
 972
 973 /**
 974  * @}
 975  */
 976
 977 /**
 978  * @addtogroup CAPI_MEDIA_PLAYER_X11_DISPLAY_MODULE
 979  * @{
 980  */
 981
 982 /**
 983  * @brief Sets the rotation settings of the x surface video display
 984  * @details Use this function to change the video orientation to portrait mode.
 985  * @remarks If current display type is not #PLAYER_DISPLAY_TYPE_X11, no operation is performed.
 986  * @param[in] player   The handle to media player
 987  * @param[in] rotation The rotation of display
 988  * @return 0 on success, otherwise a negative error value.
 989  * @retval #PLAYER_ERROR_NONE Successful
 990  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 991  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
 992  * @see  player_get_x11_display_rotation()
 993  */
 994 int player_set_x11_display_rotation(player_h player, player_display_rotation_e rotation);
 995
 996 /**
 997  * @brief Gets a rotation of the x surface video display
 998  * @remarks If current display type is not #PLAYER_DISPLAY_TYPE_X11, no operation is performed.
 999  * @param[in] player The handle to media player
1000  * @param[out] rotation The current rotation of display
1001  * @return 0 on success, otherwise a negative error value.
1002  * @retval  #PLAYER_ERROR_NONE Successful
1003  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1004  * @see player_set_x11_display_rotation()
1005  */
1006 int player_get_x11_display_rotation( player_h player, player_display_rotation_e *rotation);
1007
1008 /**
1009  * @brief Sets the visibility of the x surface video display
1010  * @remarks If current display type is not #PLAYER_DISPLAY_TYPE_X11, no operation is performed.
1011  * @param[in] player   The handle to media player
1012  * @param[in] rotation The visibility of display (@c true = visible, @c false = non-visible )
1013  * @return 0 on success, otherwise a negative error value.
1014  * @retval #PLAYER_ERROR_NONE Successful
1015  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1016  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1017  * @see player_is_x11_display_visible()
1018  */
1019 int player_set_x11_display_visible(player_h player, bool visible);
1020
1021 /**
1022  * @brief Gets a visibility of the x surface video display
1023  * @remarks If current display type is not #PLAYER_DISPLAY_TYPE_X11, no operation is performed.
1024  * @param[in] player The handle to media player
1025  * @param[out] visible The current visibility of display (@c true = visible, @c false = non-visible )
1026  * @return 0 on success, otherwise a negative error value.
1027  * @retval  #PLAYER_ERROR_NONE Successful
1028  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1029  * @see player_set_x11_display_visible()
1030  */
1031 int player_is_x11_display_visible(player_h player, bool* visible);
1032
1033 /**
1034  * @brief Sets the zoom level of the x surface video display
1035  * @remarks If current display type is not #PLAYER_DISPLAY_TYPE_X11, no operation is performed.
1036  * @param[in] player   The handle to media player
1037  * @param[in] level The level of zoom [1~9]
1038  * @return 0 on success, otherwise a negative error value.
1039  * @retval #PLAYER_ERROR_NONE Successful
1040  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1041  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1042  * @see  player_get_x11_display_zoom()
1043  */
1044 int player_set_x11_display_zoom(player_h player, int level);
1045
1046 /**
1047  * @brief Gets a zoom level of the x surface video display
1048  * @remarks If current display type is not #PLAYER_DISPLAY_TYPE_X11, no operation is performed.
1049  * @param[in] player The handle to media player
1050  * @param[out] level The level of zoom [1~9]
1051  * @return 0 on success, otherwise a negative error value.
1052  * @retval  #PLAYER_ERROR_NONE Successful
1053  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1054  * @see player_set_x11_display_zoom()
1055  */
1056 int player_get_x11_display_zoom( player_h player, int *level);
1057
1058 /**
1059  * @internal
1060  * @brief Registers a callback function to be invoked when player need updated xid.
1061  * @param[in] player    The handle to media player
1062  * @param[in] callback  The callback function to register
1063  * @param[in] user_data The user data to be passed to the callback function
1064  * @return 0 on success, otherwise a negative error value.
1065  * @retval #PLAYER_ERROR_NONE Successful
1066  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1067  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1068  * @pre The player state must be either #PLAYER_STATE_IDLE by player_create() or #PLAYER_STATE_READY by player_prepare().
1069  * @post  player_set_x11_display_pixmap() will be invoked
1070  * @see player_set_x11_display_pixmap()
1071  */
1072 int player_set_x11_display_pixmap (player_h player, player_x11_pixmap_updated_cb callback, void *user_data);
1073
1074 /**
1075  * @internal
1076  * @brief Registers a callback function to be invoked when failure of rendering video frame happen.
1077  * @param[in] player    The handle to media player
1078  * @param[in] callback  The callback function to register
1079  * @param[in] user_data The user data to be passed to the callback function
1080  * @return 0 on success, otherwise a negative error value.
1081  * @retval #PLAYER_ERROR_NONE Successful
1082  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1083  * @pre The player state must be either #PLAYER_STATE_IDLE by player_create() or #PLAYER_STATE_READY by player_prepare().
1084  * @post  player_set_x11_display_pixmap_error_cb() will be invoked
1085  * @see player_set_x11_display_pixmap_error_cb()
1086  */
1087 int player_set_x11_display_pixmap_error_cb (player_h player, player_x11_pixmap_error_cb callback, void *user_data);
1088
1089 /**
1090  * @brief Sets information of ROI
1091  * @remarks If current display mode is not #PLAYER_DISPLAY_MODE_ROI, #PLAYER_ERROR_INVALID_OPERATION will be returned.
1092  * @param[in] player   The handle to media player
1093  * @param[in] x The x coordinate of ROI
1094  * @param[in] y The y coordinate of ROI
1095  * @param[in] w The width of ROI
1096  * @param[in] h The height of ROI
1097  * @return 0 on success, otherwise a negative error value.
1098  * @retval #PLAYER_ERROR_NONE Successful
1099  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1100  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1101  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1102  * @see  player_get_x11_display_roi()
1103  */
1104 int player_set_x11_display_roi (player_h player, int x, int y, int w, int h);
1105
1106 /**
1107  * @brief Gets information of ROI
1108  * @remarks If current display mode is not #PLAYER_DISPLAY_MODE_ROI, #PLAYER_ERROR_INVALID_OPERATION will be returned.
1109  * @param[in] player   The handle to media player
1110  * @param[out] x The x coordinate of ROI
1111  * @param[out] y The y coordinate of ROI
1112  * @param[out] w The width of ROI
1113  * @param[out] h The height of ROI
1114  * @return 0 on success, otherwise a negative error value.
1115  * @retval #PLAYER_ERROR_NONE Successful
1116  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1117  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1118  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1119  * @see  player_set_x11_display_roi()
1120  */
1121 int player_get_x11_display_roi (player_h player, int *x, int *y, int *w, int *h);
1122
1123 /**
1124  * @}
1125  */
1126
1127 /**
1128  * @addtogroup CAPI_MEDIA_PLAYER_EVAS_DISPLAY_MODULE
1129  * @{
1130  */
1131
1132 /**
1133  * @brief Sets the evas surface video display scaling status.
1134  * @remarks If current display type is not #PLAYER_DISPLAY_TYPE_EVAS, no operation is performed.
1135  * @remarks If the scaling status is @c false, player_is_display_mode_changeable() always return @a false.
1136  * @param[in]   player The handle to media player
1137  * @param[in]   enable New evas surface video display scaling status: (@c true = scaling, @c false = not scaled)
1138  * @return 0 on success, otherwise a negative error value.
1139  * @retval #PLAYER_ERROR_NONE Successful
1140  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1141  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1142  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1143  */
1144 int player_enable_evas_display_scaling(player_h player, bool enable);
1145
1146 /**
1147  * @}
1148  */
1149
1150 /**
1151  * @addtogroup CAPI_MEDIA_PLAYER_STREAM_INFO_MODULE
1152  * @{
1153  */
1154
1155  /**
1156  * @brief Get the media content information
1157  * @remarks @a value must be released with @c free() by you
1158  * @remarks  The playback type should be local playback or http streaming playback.
1159  * @param[in]  player The handle to media player
1160  * @param[in] key The key attribute name to get
1161  * @param[out] value The value of the key attribute. It can be empty string if there is no content information.
1162  * @return 0 on success, otherwise a negative error value
1163  * @retval #PLAYER_ERROR_NONE Successful
1164  * @retval #PLAYER_ERROR_INVALID_PARAMETER  Invalid parameter
1165  * @retval #PLAYER_ERROR_OUT_OF_MEMORY Not enough memory is available
1166  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1167  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1168  * @pre The player state must be one of: #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1169  */
1170 int player_get_content_info(player_h player, player_content_info_e key, char ** value);
1171
1172 /**
1173  * @brief Gets the audio and video codec information
1174  * @remarks @a audio_codec and @a video_codec must be released with @c free() by you
1175  * @remarks  The playback type should be local playback or http streaming playback.
1176  * @param[in] player The handle to media player
1177  * @param[out] audio_codec The name of audio codec. It can be @c NULL if there is no audio codec.
1178  * @param[out] video_codec The name of video codec. It can be @c NULL if there is no video codec.
1179  * @return 0 on success, otherwise a negative error value.
1180  * @retval #PLAYER_ERROR_NONE Successful
1181  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1182  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1183  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1184  * @pre The player state must be one of: #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1185  */
1186 int player_get_codec_info(player_h player, char **audio_codec, char **video_codec);
1187
1188 /**
1189  * @brief Gets the audio stream information
1190  * @remarks  The playback type should be local playback or http streaming playback.
1191  * @param[in] player The handle to media player
1192  * @param[out]  sample_rate The audio sample rate [Hz]. It can be invalid value if there is no audio stream information.
1193  * @param[out]  channel The audio channel (1: mono, 2: stereo). It can be invalid value if there is no audio stream information.
1194  * @param[out]  bit_rate The audio bit rate [Hz]. It can be invalid value if there is no audio stream information.
1195  * @return 0 on success, otherwise a negative error value.
1196  * @retval #PLAYER_ERROR_NONE Successful
1197  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1198  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1199  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1200  * @pre The player state must be one of: #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1201  */
1202 int player_get_audio_stream_info(player_h player, int *sample_rate, int *channel, int *bit_rate);
1203
1204 /**
1205  * @brief Gets the video stream information
1206  * @remarks  The playback type should be local playback or http streaming playback.
1207  * @param[in] player The handle to media player
1208  * @param[out]  fps The frame per second of video. It can be 0 if there is no video stream information.
1209  * @param[out]  bit_rate The video bit rate [Hz]. It can be invalid value if there is no video stream information.
1210  * @return 0 on success, otherwise a negative error value.
1211  * @retval #PLAYER_ERROR_NONE Successful
1212  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1213  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1214  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1215  * @pre The player state must be one of: #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1216  */
1217 int player_get_video_stream_info(player_h player, int *fps, int *bit_rate);
1218
1219 /**
1220  * @brief Gets the video display's height and width.
1221  * @remarks  The playback type should be local playback or http streaming playback.
1222  * @param[in] player The handle to media player
1223  * @param[out] width The width of video. It can be invalid value if there is no video, no display was set.
1224  * @param[out] height The height of video. It can be invalid value if there is no video, no display was set.
1225  * @return 0 on success, otherwise a negative error value.
1226  * @retval #PLAYER_ERROR_NONE Successful
1227  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1228  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1229  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1230  * @pre The player state must be one of: #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1231  */
1232 int player_get_video_size(player_h player, int *width, int *height);
1233
1234 /**
1235  * @brief Gets the album art in media resource
1236  * @remarks Do not release @a album_art. It will be released by framework when player destroys.
1237  * @param[in] player The handle to media player
1238  * @param [out] artwork encoded artwork image
1239  * @param [out] size encoded artwork size
1240  * @return 0 on success, otherwise a negative error value
1241  * @retval #PLAYER_ERROR_NONE Successful
1242  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1243  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1244  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1245  * @pre The player state must be one of: #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1246  */
1247 int player_get_album_art(player_h player, void **album_art, int *size);
1248
1249 /**
1250  * @brief Gets the track count
1251  * @param[in] player The handle to media player
1252  * @param [in] type The track type
1253  * @param [out] count The count of track
1254  * @return 0 on success, otherwise a negative error value
1255  * @retval #PLAYER_ERROR_NONE Successful
1256  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1257  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1258  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1259  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1260  */
1261 int player_get_track_count(player_h player, player_track_type_e type, int *count);
1262
1263 /**
1264  * @}
1265  */
1266
1267
1268 /**
1269  * @addtogroup CAPI_MEDIA_PLAYER_AUDIO_EFFECT_MODULE
1270  * @{
1271  */
1272
1273 /**
1274  * @brief Sets an audio effect value.
1275  * @param[in] player The handle to media player
1276  * @param[in] effect The audio effect type
1277  * @param[in] value The value of given effect type
1278  * @return 0 on success, otherwise a negative error value.
1279  * @retval #PLAYER_ERROR_NONE Successful
1280  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1281  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1282  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1283  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1284  * @see player_audio_effect_get_value()
1285  * @see player_audio_effect_clear()
1286  * @see player_audio_effect_get_value_range()
1287  */
1288 int player_audio_effect_set_value(player_h player, audio_effect_e effect, int value);
1289
1290 /**
1291  * @brief Gets an audio effect value.
1292  * @param[in] player The handle to media player
1293  * @param[in] effect The audio effect type
1294  * @param[out] value The value of given effect type
1295  * @return 0 on success, otherwise a negative error value.
1296  * @retval #PLAYER_ERROR_NONE Successful
1297  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1298  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1299  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1300  * @see player_audio_effect_set_value()
1301  */
1302 int player_audio_effect_get_value(player_h player, audio_effect_e effect, int *value);
1303
1304 /**
1305  * @brief Clears audio effect.
1306  * @param[in] player The handle to media player
1307  * @param[in] effect The audio effect type
1308  * @return 0 on success, otherwise a negative error value.
1309  * @retval #PLAYER_ERROR_NONE Successful
1310  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1311  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1312  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1313  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1314  * @see player_audio_effect_set_value()
1315  */
1316 int player_audio_effect_clear(player_h player, audio_effect_e effect);
1317
1318 /**
1319  * @brief Gets the range of audio effect value.
1320  * @param[in] player The handle to media player
1321  * @param[in] effect The audio effect type
1322  * @param[out] min The minumum value to be set
1323  * @param[out] max The maximum value to be set
1324  * @return 0 on success, otherwise a negative error value.
1325  * @retval #PLAYER_ERROR_NONE Successful
1326  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1327  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1328  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1329  * @see player_audio_effect_set_value()
1330  */
1331 int player_audio_effect_get_value_range(player_h player, audio_effect_e effect, int* min, int* max);
1332
1333 /**
1334  * @brief Checks whether the given effect is avaliable or not.
1335  * @param[in] player The handle to media player
1336  * @param[in] effect The audio effect to be checked
1337  * @param[out] available @c true if the specified audio effect is available, else @c false
1338  * @retval #PLAYER_ERROR_NONE Successful
1339  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1340  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1341  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1342  */
1343 int player_audio_effect_is_available(player_h player, audio_effect_e effect, bool *available);
1344
1345 /**
1346  * @brief Retrieves all supported audio effects by invoking callback function once for each supported audio effect.
1347  * @param[in] player The handle to media player
1348  * @param[in] callback    The callback function to invoke
1349  * @param[in] user_data The user data to be passed to the callback function
1350  * @retval #PLAYER_ERROR_NONE Successful
1351  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1352  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1353  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1354  * @post        This function invokes player_audio_effect_supported_effect_cb() repeatly to retrieve each supported audio effect.
1355  * @see player_audio_effect_set_value()
1356  * @see player_audio_effect_get_value()
1357  * @see player_audio_effect_foreach_supported_effect()
1358  */
1359 int player_audio_effect_foreach_supported_effect(player_h player, player_audio_effect_supported_effect_cb callback, void *user_data);
1360
1361 /**
1362  * @brief Sets an preset audio effect.
1363  * @remarks Audio effects or equalizer which is set be ignored.
1364  * @param[in] player The handle to media player
1365  * @param[in] preset The preset audio effect
1366  * @return 0 on success, otherwise a negative error value.
1367  * @retval #PLAYER_ERROR_NONE Successful
1368  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1369  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1370  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1371  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1372  * @see player_audio_effect_preset_is_available()
1373  * @see player_audio_effect_foreach_supported_preset()
1374  */
1375 int player_audio_effect_set_preset(player_h player, audio_effect_preset_e preset);
1376
1377 /**
1378  * @brief Checks whether the given preset is avaliable or not.
1379  * @param[in] player The handle to media player
1380  * @param[in] preset The preset to be checked
1381  * @param[out] available @c true if the specified preset is available, else @c false
1382  * @retval #PLAYER_ERROR_NONE Successful
1383  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1384  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1385  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1386  */
1387 int player_audio_effect_preset_is_available(player_h player, audio_effect_preset_e preset, bool *available);
1388
1389 /**
1390  * @brief Retrieves all supported presets by invoking callback function once for each supported preset audio effect.
1391  * @param[in] player The handle to media player
1392  * @param[in] callback    The callback function to invoke
1393  * @param[in] user_data The user data to be passed to the callback function
1394  * @retval #PLAYER_ERROR_NONE Successful
1395  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1396  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1397  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1398  * @post        This function invokes player_audio_effect_supported_preset_cb() repeatly to retrieve each supported preset audio effect.
1399  * @see player_audio_effect_set_preset()
1400  * @see player_audio_effect_supported_preset_cb()
1401  */
1402 int player_audio_effect_foreach_supported_preset(player_h player, player_audio_effect_supported_preset_cb callback, void *user_data);
1403
1404 /**
1405  * @brief Gets the bands number of equalizer.
1406  * @param[in] player The handle to media player
1407  * @param[out] count The number of equalizer bands
1408  * @return 0 on success, otherwise a negative error value.
1409  * @retval #PLAYER_ERROR_NONE Successful
1410  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1411  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1412  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1413  * @see player_audio_effect_set_equalizer_band_level()
1414  * @see player_audio_effect_set_equalizer_all_bands()
1415  */
1416 int player_audio_effect_get_equalizer_bands_count (player_h player, int *count);
1417
1418 /**
1419  * @brief Sets the all bands of equalizer.
1420  * @param[in] player The handle to media player
1421  * @param[in] band_levels The list of band level to be set
1422  * @param[in] length The length of the band level
1423  * @return 0 on success, otherwise a negative error value.
1424  * @retval #PLAYER_ERROR_NONE Successful
1425  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1426  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1427  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1428  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1429  * @see player_audio_effect_get_equalizer_bands_count()
1430  * @see player_audio_effect_get_equalizer_level_range()
1431  * @see player_audio_effect_set_equalizer_band_level()
1432  */
1433 int player_audio_effect_set_equalizer_all_bands(player_h player, int *band_levels, int length);
1434
1435 /**
1436  * @brief Sets the gain set for the given equalizer band.
1437  * @param[in] player The handle to media player
1438  * @param[in] index The index of qualizer band to be set
1439  * @param[in] level New gain in decibel that will be set to the given band.[dB]
1440  * @return 0 on success, otherwise a negative error value.
1441  * @retval #PLAYER_ERROR_NONE Successful
1442  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1443  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1444  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1445  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1446  * @see player_audio_effect_get_equalizer_bands_count()
1447  * @see player_audio_effect_get_equalizer_level_range()
1448  * @see player_audio_effect_get_equalizer_band_level()
1449  * @see player_audio_effect_set_equalizer_all_bands()
1450  */
1451 int player_audio_effect_set_equalizer_band_level(player_h player, int index, int level);
1452
1453 /**
1454  * @brief Gets the gain set for the given equalizer band.
1455  * @param[in]   player The handle to media player
1456  * @param[in]   index The index of qualizer band which is requested
1457  * @param[out]   level The gain in decibel of the given band [dB]
1458  * @return 0 on success, otherwise a negative error value.
1459  * @retval #PLAYER_ERROR_NONE Successful
1460  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1461  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1462  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1463  * @see player_audio_effect_set_equalizer_band_level()
1464  */
1465 int player_audio_effect_get_equalizer_band_level(player_h player, int index, int *level);
1466
1467 /**
1468  * @brief Gets the valid band level range of equalizer.
1469  * @param[in] player The handle to media player
1470  * @param[out] min The minumum value to be set [dB]
1471  * @param[out] max The maximum value to be set [dB]
1472  * @return 0 on success, otherwise a negative error value.
1473  * @retval #PLAYER_ERROR_NONE Successful
1474  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1475  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1476  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1477  * @see player_audio_effect_set_equalizer_band_level()
1478  * @see player_audio_effect_set_equalizer_all_bands()
1479  */
1480 int player_audio_effect_get_equalizer_level_range(player_h player, int* min, int* max);
1481
1482 /**
1483  * @brief Gets the band frequency of equalizer.
1484  * @param[in] player The handle to media player
1485  * @param[in]  index The index of qualizer band which is requested
1486  * @param[out] frequency The frequency of the given band [dB]
1487  * @return 0 on success, otherwise a negative error value.
1488  * @retval #PLAYER_ERROR_NONE Successful
1489  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1490  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1491  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1492  */
1493 int player_audio_effect_get_equalizer_band_frequency(player_h player, int index, int *frequency);
1494
1495 /**
1496  * @brief Gets the band frequency range of equalizer.
1497  * @param[in] player The handle to media player
1498  * @param[in]  index The index of qualizer band which is requested
1499  * @param[out] range The frequency range of the given band [dB]
1500  * @return 0 on success, otherwise a negative error value.
1501  * @retval #PLAYER_ERROR_NONE Successful
1502  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1503  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1504  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1505  */
1506 int player_audio_effect_get_equalizer_band_frequency_range(player_h player, int index, int *range);
1507
1508 /**
1509  * @brief Clears the equalizer effect.
1510  * @param[in] player The handle to media player
1511  * @param[in] effect The audio effect type
1512  * @retval #PLAYER_ERROR_NONE Successful
1513  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1514  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1515  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1516  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1517  * @see player_audio_effect_set_equalizer_band_level()
1518  * @see player_audio_effect_set_equalizer_all_bands()
1519  */
1520 int player_audio_effect_equalizer_clear(player_h player);
1521
1522 /**
1523  * @brief Checks whether the custom equilizer effect is avaliable or not.
1524  * @param[in] player The handle to media player
1525  * @param[out] available @c true if the specified audio effect is available, else @c false
1526  * @retval #PLAYER_ERROR_NONE Successful
1527  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1528  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1529  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1530  * @see player_audio_effect_set_equalizer_band_level()
1531  * @see player_audio_effect_set_equalizer_all_bands()
1532  */
1533 int player_audio_effect_equalizer_is_available(player_h player, bool *available);
1534
1535 /**
1536  * @}
1537  */
1538
1539 /**
1540  * @addtogroup CAPI_MEDIA_PLAYER_MODULE
1541  * @{
1542  */
1543
1544 /**
1545  * @brief Sets a subtitle path.
1546  * @remarks Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.
1547  * @param[in]   player The handle to media player
1548  * @param[in]   path The absolute path of the subtitle file
1549  * @return 0 on success, otherwise a negative error value.
1550  * @retval #PLAYER_ERROR_NONE Successful
1551  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1552  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1553  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1554  * @pre The player state should be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
1555  */
1556 int player_set_subtitle_path(player_h player,const char *path);
1557
1558 /**
1559  * @brief Sets the seek position for subtitle.
1560  * @remarks Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.
1561  * @param[in]  player The handle to media player
1562  * @param[in]  millisecond The position in milliseconds from the start to seek to
1563  * @return 0 on success, otherwise a negative error value.
1564  * @retval #PLAYER_ERROR_NONE Successful
1565  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1566  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1567  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1568  * @pre The subtitle must be set by player_set_subtitle_path().
1569  * @pre The player state must be one of: #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1570  */
1571 int player_set_subtitle_position(player_h player, int millisecond);
1572
1573 /**
1574  * @brief Sets a path to download, progressively.
1575  * @remarks Progressive download will be started when you invoke player_start().
1576  * @param[in]   player The handle to media player
1577  * @param[in]   path The absolute path to download
1578  * @return 0 on success, otherwise a negative error value.
1579  * @retval #PLAYER_ERROR_NONE Successful
1580  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1581  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1582  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1583  * @pre The player state should be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
1584  * @see player_set_progressive_download_message_cb()
1585  * @see player_unset_progressive_download_message_cb()
1586  */
1587 int player_set_progressive_download_path(player_h player, const char *path);
1588
1589 /**
1590  * @brief Gets the staus of progressive download.
1591  * @param[in] player The handle to media player
1592  * @param[out] current The current download position (bytes)
1593  * @param[out] total_size The total size of file (bytes)
1594  * @return 0 on success, otherwise a negative error value.
1595  * @retval #PLAYER_ERROR_NONE Successful
1596  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1597  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1598  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1599  * @pre The progressive download path must be set by player_set_progressive_download_path().
1600  * @pre The player state must be either #PLAYER_STATE_PLAYING by player_start() or #PLAYER_STATE_PAUSED by player_pause().
1601  */
1602 int player_get_progressive_download_status(player_h player, unsigned long *current, unsigned long *total_size);
1603
1604 /**
1605  * @brief Captures the video frame, asynchronously.
1606  * @param[in] player The handle to media player
1607  * @param[in] callback  The callback function to register
1608  * @param[in] user_data The user data to be passed to the callback function
1609  * @return 0 on success, otherwise a negative error value.
1610  * @retval #PLAYER_ERROR_NONE Successful
1611  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1612  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1613  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1614  * @pre The player state must be #PLAYER_STATE_PLAYING by player_start() or #PLAYER_STATE_PAUSED by player_pause().
1615  * @post It invokes player_video_captured_cb() when capture completes, if you set a callback.
1616  * @see player_video_captured_cb()
1617  */
1618 int player_capture_video(player_h player, player_video_captured_cb callback, void *user_data);
1619
1620 /**
1621  * @brief Sets the cookie for streaming playback.
1622  * @param[in] player The handle to media player
1623  * @param[in] cookie    The cookie to set
1624  * @param[in] size      The size of cookie
1625  * @return 0 on success, otherwise a negative error value.
1626  * @retval #PLAYER_ERROR_NONE Successful
1627  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1628  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1629  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1630  * @pre The player state should be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
1631  * @see player_set_streaming_user_agent()
1632  */
1633 int player_set_streaming_cookie(player_h player, const char *cookie, int size);
1634
1635 /**
1636  * @brief Sets the user agent for streaming playback.
1637  * @param[in] player The handle to media player
1638  * @param[in] user_agent        The user agent to set
1639  * @param[in] size      The size of user agent
1640  * @return 0 on success, otherwise a negative error value.
1641  * @retval #PLAYER_ERROR_NONE Successful
1642  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1643  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1644  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1645  * @pre The player state should be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
1646  * @see player_set_streaming_cookie()
1647  */
1648 int player_set_streaming_user_agent(player_h player, const char *user_agent, int size);
1649
1650 /**
1651  * @brief Gets the download progress for streaming playback.
1652  * @param[in] player The handle to media player
1653  * @param[out] start The starting position in percent [0, 100]
1654  * @param[out] current The current position in percent [0, 100]
1655  * @return 0 on success, otherwise a negative error value.
1656  * @retval #PLAYER_ERROR_NONE Successful
1657  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1658  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1659  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1660  * @pre The player state must be either #PLAYER_STATE_PLAYING by player_start() or #PLAYER_STATE_PAUSED by player_pause().
1661  */
1662 int player_get_streaming_download_progress(player_h player, int *start, int *current);
1663
1664 /**
1665  * @brief Registers a callback function to be invoked when the playback finishes.
1666  * @param[in] player    The handle to media player
1667  * @param[in] callback  The callback function to register
1668  * @param[in] user_data The user data to be passed to the callback function
1669  * @return 0 on success, otherwise a negative error value.
1670  * @retval #PLAYER_ERROR_NONE Successful
1671  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1672  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1673  * @post  player_completed_cb() will be invoked
1674  * @see player_unset_completed_cb()
1675  * @see player_completed_cb()
1676  * @see player_start()
1677  */
1678 int player_set_completed_cb(player_h player, player_completed_cb callback, void *user_data);
1679
1680 /**
1681  * @brief       Unregisters the callback function.
1682  * @param[in] player The handle to media player
1683  * @return 0 on success, otherwise a negative error value.
1684  * @retval #PLAYER_ERROR_NONE Successful
1685  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1686  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1687  * @see player_set_completed_cb()
1688  */
1689 int player_unset_completed_cb(player_h player);
1690
1691 /**
1692  * @brief Registers a callback function to be invoked when the playback is interrupted or interrupt completed.
1693  * @param[in] player    The handle to media player
1694  * @param[in] callback  The callback function to register
1695  * @param[in] user_data The user data to be passed to the callback function
1696  * @return 0 on success, otherwise a negative error value.
1697  * @retval #PLAYER_ERROR_NONE Successful
1698  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1699  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1700  * @post  player_interrupted_cb() will be invoked
1701  * @see player_unset_interrupted_cb()
1702  * @see #player_interrupted_code_e
1703  * @see player_interrupted_cb()
1704  */
1705 int player_set_interrupted_cb(player_h player, player_interrupted_cb callback, void *user_data);
1706
1707 /**
1708  * @brief Unregisters the callback function.
1709  * @param[in] player The handle to media player
1710  * @return 0 on success, otherwise a negative error value.
1711  * @retval #PLAYER_ERROR_NONE Successful
1712  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1713  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1714  * @see player_set_interrupted_cb()
1715  */
1716 int player_unset_interrupted_cb(player_h player);
1717
1718 /**
1719  * @brief Registers a callback function to be invoked when error occured.
1720  * @param[in] player    The handle to media player
1721  * @param[in] callback  The callback function to register
1722  * @param[in] user_data The user data to be passed to the callback function
1723  * @return 0 on success, otherwise a negative error value.
1724  * @retval #PLAYER_ERROR_NONE Successful
1725  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1726  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1727  * @post  player_error_cb() will be invoked
1728  * @see player_unset_error_cb()
1729  * @see player_error_cb()
1730  */
1731 int player_set_error_cb(player_h player, player_error_cb callback, void *user_data);
1732
1733 /**
1734  * @brief Unregisters the callback function.
1735  *
1736  * @param[in] player The handle to media player
1737  * @return 0 on success, otherwise a negative error value.
1738  * @retval #PLAYER_ERROR_NONE Successful
1739  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1740  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1741  * @see player_set_error_cb()
1742  */
1743 int player_unset_error_cb(player_h player);
1744
1745 /**
1746  * @brief Registers a callback function to be invoked when there is a change in the buffering status of a media stream.
1747  * @remarks  The media resource should be streamed over the network.
1748  * @param[in] player    The handle to media player
1749  * @param[in] callback  The callback function to register
1750  * @param[in] user_data The user data to be passed to the callback function
1751  * @return 0 on success, otherwise a negative error value.
1752  * @retval #PLAYER_ERROR_NONE Successful
1753  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1754  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1755  * @post  player_buffering_cb() will be invoked
1756  * @see player_unset_buffering_cb()
1757  * @see player_set_uri()
1758  * @see player_buffering_cb()
1759  */
1760 int player_set_buffering_cb(player_h player, player_buffering_cb callback, void *user_data);
1761
1762 /**
1763  * @brief Unregisters the callback function.
1764  * @param[in] player The handle to media player
1765  * @return 0 on success, otherwise a negative error value.
1766  * @retval #PLAYER_ERROR_NONE Successful
1767  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1768  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1769  * @see player_set_buffering_cb()
1770  */
1771 int player_unset_buffering_cb(player_h player);
1772
1773 /**
1774  * @brief Registers a callback function to be invoked when progressive download is starts or completes.
1775  * @param[in] player    The handle to media player
1776  * @param[in] callback  The callback function to register
1777  * @param[in] user_data The user data to be passed to the callback function
1778  * @return 0 on success, otherwise a negative error value.
1779  * @retval #PLAYER_ERROR_NONE Successful
1780  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1781  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1782  * @pre The path to download must be set by player_set_progressive_download_path().
1783  * @post  player_pd_message_cb() will be invoked
1784  * @see player_unset_progressive_download_message_cb()
1785  * @see player_set_progressive_download_path()
1786  */
1787 int player_set_progressive_download_message_cb(player_h player, player_pd_message_cb callback, void *user_data);
1788
1789 /**
1790  * @brief Unregisters the callback function.
1791  * @param[in] player The handle to media player
1792  * @return 0 on success, otherwise a negative error value.
1793  * @retval #PLAYER_ERROR_NONE Successful
1794  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1795  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1796  * @see player_set_progressive_download_message_cb()
1797  */
1798 int player_unset_progressive_download_message_cb(player_h player);
1799
1800 /**
1801  * @brief Registers a callback function to be invoked when subtitle updates.
1802  * @param[in] player    The handle to media player
1803  * @param[in] callback  The callback function to register
1804  * @param[in] user_data The user data to be passed to the callback function
1805  * @return 0 on success, otherwise a negative error value.
1806  * @retval #PLAYER_ERROR_NONE Successful
1807  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1808  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1809  * @pre The subtitle must be set by player_set_subtitle_path().
1810  * @post  player_subtitle_updated_cb() will be invoked
1811  * @see player_unset_subtitle_updated_cb()
1812  * @see player_subtitle_updated_cb()
1813  * @see player_set_subtitle_path()
1814  */
1815 int player_set_subtitle_updated_cb(player_h player, player_subtitle_updated_cb callback, void *user_data);
1816
1817 /**
1818  * @brief Unregisters the callback function.
1819  * @param[in] player The handle to media player
1820  * @return 0 on success, otherwise a negative error value.
1821  * @retval #PLAYER_ERROR_NONE Successful
1822  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1823  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1824  * @see player_set_subtitle_updated_cb()
1825  */
1826 int player_unset_subtitle_updated_cb(player_h player);
1827
1828 /**
1829  * @brief Registers a callback function to be invoked when video frame is decoded.
1830  * @param[in] player    The handle to media player
1831  * @param[in] callback  The callback function to register
1832  * @param[in] user_data The user data to be passed to the callback function
1833  * @return 0 on success, otherwise a negative error value.
1834  * @retval #PLAYER_ERROR_NONE Successful
1835  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1836  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1837  * @pre The player state must be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
1838  * @post  player_video_frame_decoded_cb() will be invoked
1839  * @see player_unset_video_frame_decoded_cb()
1840  * @see player_video_frame_decoded_cb()
1841  */
1842 int player_set_video_frame_decoded_cb(player_h player, player_video_frame_decoded_cb callback, void *user_data);
1843
1844 /**
1845  * @brief Unregisters the callback function.
1846  * @param[in] player The handle to media player
1847  * @return 0 on success, otherwise a negative error value.
1848  * @retval #PLAYER_ERROR_NONE Successful
1849  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1850  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1851  * @see player_set_video_frame_decoded_cb()
1852  */
1853 int player_unset_video_frame_decoded_cb(player_h player);
1854
1855 /**
1856  * @brief Registers a callback function to be invoked when audio frame is decoded.
1857  * @param[in] player    The handle to media player
1858  * @param[in] start The start position to decode.
1859  * @param[in] end       The end position to decode.
1860  * @param[in] callback  The callback function to register
1861  * @param[in] user_data The user data to be passed to the callback function
1862  * @return 0 on success, otherwise a negative error value.
1863  * @retval #PLAYER_ERROR_NONE Successful
1864  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1865  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1866  * @pre The player state must be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
1867  * @post  player_audio_frame_decoded_cb() will be invoked
1868  * @see player_unset_audio_frame_decoded_cb()
1869  * @see player_audio_frame_decoded_cb()
1870  */
1871 int player_set_audio_frame_decoded_cb(player_h player, int start, int end, player_audio_frame_decoded_cb callback, void *user_data);
1872
1873 /**
1874  * @brief Unregisters the callback function.
1875  * @param[in] player The handle to media player
1876  * @return 0 on success, otherwise a negative error value.
1877  * @retval #PLAYER_ERROR_NONE Successful
1878  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1879  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1880  * @see player_set_audio_frame_decoded_cb()
1881  */
1882 int player_unset_audio_frame_decoded_cb(player_h player);
1883
1884 /**
1885  * @}
1886  */
1887
1888 #ifdef __cplusplus
1889 }
1890 #endif
1891
1892 #endif /* __TIZEN_MEDIA_PLAYER_H__ */