include/player.h

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