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