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