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