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]   volume The volume scalar
 504  * @return @c 0 on success,
 505  *         otherwise a negative error value
 506  * @retval #PLAYER_ERROR_NONE Successful
 507  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 508  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 509  * @see legacy_player_get_volume()
 510  */
 511 int legacy_player_set_volume(legacy_player_h player, float volume);
 512
 513 /**
 514  * @brief Gets the player's current volume factor.
 515  * @since_tizen 2.3
 516  * @details The range of @a volume is from @c 0 to @c 1.0, inclusive (1.0 = 100%).
 517  *          This function gets the player volume, not the system volume.
 518  *          To get the system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
 519  *
 520  * @param[in]   player The handle to the media player
 521  * @param[out]  volume The current volume scalar
 522  * @return @c 0 on success,
 523  *         otherwise a negative error value
 524  * @retval #PLAYER_ERROR_NONE Successful
 525  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 526  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 527  * @see legacy_player_set_volume()
 528  */
 529 int legacy_player_get_volume(legacy_player_h player, float *volume);
 530
 531 /**
 532  * @brief Sets the player's sound manager stream information.
 533  * @since_tizen 3.0
 534  * @remarks You can set sound stream information including audio routing and volume type.
 535  * For more details, please refer to sound_manager.h
 536  *
 537  * @param[in] player The handle to the media player
 538  * @param[in] stream_info The sound manager info type
 539  * @return @c 0 on success,
 540  *         otherwise a negative error value
 541  * @retval #PLAYER_ERROR_NONE Successful
 542  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 543  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 544  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 545  * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
 546  * @pre The player state must be set to #PLAYER_STATE_IDLE by calling legacy_player_create().
 547  * @see #sound_stream_info_h
 548  * @see sound_manager_create_stream_information()
 549  * @see sound_manager_destroy_stream_information()
 550  */
 551 int legacy_player_set_sound_stream_info(legacy_player_h player, sound_stream_info_h stream_info);
 552
 553 /**
 554  * @brief Sets the audio latency mode.
 555  * @since_tizen 2.3
 556  * @remarks The default audio latency mode of the player is #AUDIO_LATENCY_MODE_MID.
 557  *              To get the current audio latency mode, use legacy_player_get_audio_latency_mode().
 558  *              If it's high mode, audio output interval can be increased so, it can keep more audio data to play.
 559  *              But, state transition like pause or resume can be more slower than default(mid) mode.
 560  *
 561  * @param[in] player The handle to the media player
 562  * @param[in] latency_mode The latency mode to be applied to the audio
 563  * @return @c 0 on success,
 564  *         otherwise a negative error value
 565  * @retval #PLAYER_ERROR_NONE Successful
 566  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 567  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 568  * @see #audio_latency_mode_e
 569  * @see legacy_player_get_audio_latency_mode()
 570  */
 571 int legacy_player_set_audio_latency_mode(legacy_player_h player, audio_latency_mode_e latency_mode);
 572
 573 /**
 574  * @brief Gets the current audio latency mode.
 575  * @since_tizen 2.3
 576  * @param[in] player The handle to the media player
 577  * @param[out] latency_mode The latency mode to get from the audio
 578  * @return @c 0 on success,
 579  *         otherwise a negative error value
 580  * @retval #PLAYER_ERROR_NONE Successful
 581  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 582  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 583  * @see #audio_latency_mode_e
 584  * @see legacy_player_set_audio_latency_mode()
 585  */
 586 int legacy_player_get_audio_latency_mode(legacy_player_h player, audio_latency_mode_e *latency_mode);
 587
 588 /**
 589  * @brief Starts or resumes playback.
 590  * @since_tizen 2.3
 591  * @remarks Sound can be mixed with other sounds if you don't control the stream focus in sound-manager module since 3.0.\n
 592  * You can refer to @ref CAPI_MEDIA_SUOND_MANAGER_MODULE.
 593  * @details Plays current media content, or resumes play if paused.
 594  *
 595  * @param[in]   player The handle to the media player
 596  * @return @c 0 on success,
 597  * otherwise a negative error value
 598  * @retval #PLAYER_ERROR_NONE Successful
 599  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 600  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 601  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 602  * @retval #PLAYER_ERROR_CONNECTION_FAILED Network connection failed
 603  * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
 604  * @pre legacy_player_prepare() must be called before calling this function.
 605  * @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().
 606  * @post The player state will be #PLAYER_STATE_PLAYING.
 607  * @post It invokes legacy_player_completed_cb() when playback completes, if you set a callback with legacy_player_set_completed_cb().
 608  * @see legacy_player_prepare()
 609  * @see legacy_player_prepare_async()
 610  * @see legacy_player_stop()
 611  * @see legacy_player_pause()
 612  * @see legacy_player_set_completed_cb()
 613  * @see legacy_player_completed_cb()
 614  */
 615 int legacy_player_start(legacy_player_h player);
 616
 617 /**
 618  * @brief Stops playing media content.
 619  * @since_tizen 2.3
 620  * @param[in]   player The handle to the media player
 621  * @return @c 0 on success,
 622  *         otherwise a negative error value
 623  * @retval #PLAYER_ERROR_NONE Successful
 624  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid state
 625  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 626  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 627  * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
 628  * @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().
 629  * @post The player state will be #PLAYER_STATE_READY.
 630  * @see legacy_player_start()
 631  * @see legacy_player_pause()
 632  */
 633 int legacy_player_stop(legacy_player_h player);
 634
 635 /**
 636  * @brief Pauses the player.
 637  * @since_tizen 2.3
 638  * @remarks     You can resume playback using legacy_player_start().
 639  *
 640  * @param[in]   player The handle to the media player
 641  * @return @c 0 on success,
 642  *         otherwise a negative error value
 643  * @retval #PLAYER_ERROR_NONE Successful
 644  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid state
 645  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 646  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 647  * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
 648  * @pre The player state must be set to #PLAYER_STATE_PLAYING.
 649  * @post The player state will be #PLAYER_STATE_READY.
 650  * @see legacy_player_start()
 651  */
 652 int legacy_player_pause(legacy_player_h player);
 653
 654 /**
 655  * @brief Sets the seek position for playback, asynchronously.
 656  * @since_tizen 2.3
 657  * @param[in] player       The handle to the media player
 658  * @param[in] nanoseconds  The position in milliseconds from the start to the seek point
 659  * @param[in] accurate     If @c true the selected position is returned, but this might be considerably slow,
 660  *                         otherwise @c false
 661  * @param[in] callback     The callback function to register
 662  * @param[in] user_data    The user data to be passed to the callback function
 663  * @return @c 0 on success,
 664  *         otherwise a negative error value
 665  * @retval #PLAYER_ERROR_NONE Successful
 666  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 667  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 668  * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
 669  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 670  * @post It invokes legacy_player_seek_completed_cb() when seek operation completes, if you set a callback.
 671  * @see legacy_player_get_play_position()
 672  */
 673 int legacy_player_set_play_position(legacy_player_h player, int64_t nanoseconds, bool accurate, player_seek_completed_cb callback, void *user_data);
 674
 675 /**
 676  * @brief Gets the current position in milliseconds.
 677  * @since_tizen 2.3
 678  * @param[in]   player        The handle to the media player
 679  * @param[out]  nanoseconds   The current position in milliseconds
 680  * @return @c 0 on success,
 681  *         otherwise a negative error value
 682  * @retval #PLAYER_ERROR_NONE Successful
 683  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 684  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 685  * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
 686  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 687  * @see legacy_player_set_play_position()
 688  */
 689 int legacy_player_get_play_position(legacy_player_h player, int64_t *nanoseconds);
 690
 691 /**
 692  * @brief Sets the player's mute status.
 693  * @since_tizen 2.3
 694  * @details If the mute status is @c true, no sounds are played.
 695  *          If it is @c false, sounds are played at the previously set volume level.
 696  *          Until this function is called, by default the player is not muted.
 697  *
 698  * @param[in]   player The handle to the media player
 699  * @param[in]   muted The new mute status: (@c true = mute, @c false = not muted)
 700  * @return @c 0 on success,
 701  *         otherwise a negative error value
 702  * @retval #PLAYER_ERROR_NONE Successful
 703  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 704  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 705  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 706  * @see legacy_player_is_muted()
 707  */
 708 int legacy_player_set_mute(legacy_player_h player, bool muted);
 709
 710 /**
 711  * @brief Gets the player's mute status.
 712  * @since_tizen 2.3
 713  * @details If the mute status is @c true, no sounds are played.
 714  *          If it is @c false, sounds are played at the previously set volume level.
 715  *
 716  * @param[in]   player The handle to the media player
 717  * @param[out]  muted  The current mute status: (@c true = mute, @c false = not muted)
 718  * @return @c 0 on success,
 719  *         otherwise a negative error value
 720  * @retval #PLAYER_ERROR_NONE Successful
 721  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 722  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 723  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 724  * @see legacy_player_set_mute()
 725  */
 726 int legacy_player_is_muted(legacy_player_h player, bool *muted);
 727
 728 /**
 729  * @brief Sets the player's looping status.
 730  * @since_tizen 2.3
 731  * @details If the looping status is @c true, playback automatically restarts upon finishing.
 732  *          If it is @c false, it won't. The default value is @c false.
 733  *
 734  * @param[in]   player The handle to the media player
 735  * @param[in]   looping The new looping status: (@c true = looping, @c false = non-looping )
 736  * @return @c 0 on success,
 737  *         otherwise a negative error value
 738  * @retval #PLAYER_ERROR_NONE Successful
 739  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 740  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 741  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 742  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 743  * @see legacy_player_is_looping()
 744  */
 745 int legacy_player_set_looping(legacy_player_h player, bool looping);
 746
 747 /**
 748  * @brief Gets the player's looping status.
 749  * @since_tizen 2.3
 750  * @details If the looping status is @c true, playback automatically restarts upon finishing.
 751  *          If it is @c false, it won't.
 752  *
 753  * @param[in]   player The handle to the media player
 754  * @param[out]  looping The looping status: (@c true = looping, @c false = non-looping )
 755  * @return @c 0 on success,
 756  *         otherwise a negative error value
 757  * @retval #PLAYER_ERROR_NONE Successful
 758  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 759  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 760  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 761  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 762  * @see legacy_player_set_looping()
 763  */
 764 int legacy_player_is_looping(legacy_player_h player, bool *looping);
 765
 766 /**
 767  * @brief Sets the video display.
 768  * @since_tizen 2.3
 769  * @remarks To get @a display to set, use #GET_DISPLAY().
 770  * @remarks To use the multiple surface display mode, use legacy_player_set_display() again with a different display type.
 771  * @remarks We are not supporting changing display between different types. \n
 772  *          If you want to change display handle after calling legacy_player_prepare(), you must use the same display type as what you set before.
 773  * @param[in]   player The handle to the media player
 774  * @param[in]   type The display type
 775  * @param[in]   wl_surface_id Wayland surface grobal id
 776  * @return @c 0 on success,
 777  *         otherwise a negative error value
 778  * @retval #PLAYER_ERROR_NONE Successful
 779  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 780  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 781  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 782  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 783  * @see legacy_player_set_display_rotation
 784  */
 785 int legacy_player_set_display(legacy_player_h player, player_display_type_e type, unsigned int wl_surface_id);
 786
 787 int legacy_player_release_video_stream_bo(legacy_player_h player, void *bo);
 788
 789 /**
 790  * @brief Registers a media packet video callback function to be called once per frame.
 791  * @remarks This function should be called before preparing. \n
 792  *              A registered callback is called on the internal thread of the player. \n
 793  *          A video frame can be retrieved using a registered callback.\n
 794  *          The callback function holds the same buffer that will be drawn on the display device.\n
 795  * @param[in] player The handle to the media player
 796  * @param[in] callback The callback function to be registered
 797  * @param[in] user_data The user data to be passed to the callback function
 798  * @return @c 0 on success,
 799  *         otherwise a negative error value
 800  * @retval #PLAYER_ERROR_NONE Successful
 801  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 802  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
 803  * @pre The player's state should be #PLAYER_STATE_IDLE. And, #PLAYER_DISPLAY_TYPE_NONE should be set by calling legacy_player_set_display().
 804  */
 805 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);
 806
 807 /**
 808  * @brief  Pushes elementary stream to decode audio or video
 809  * @since_tizen 2.4
 810  * @remarks legacy_player_set_media_stream_info() should be called before using this API.
 811  * @remarks The available buffer size can be set by calling legacy_player_set_media_stream_buffer_max_size() API.
 812  *          If there is no available buffer space, this api will return error since 3.0.
 813  * @param[in]  player   The handle to media player
 814  * @param[in]  packet   The media packet to decode
 815  * @return @c 0 on success,
 816  *         otherwise a negative error value
 817  * @retval #PLAYER_ERROR_NONE Successful
 818  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 819  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
 820  * @retval #PLAYER_ERROR_NOT_SUPPORTED_FILE File not supported
 821  * @retval #PLAYER_ERROR_BUFFER_SPACE No buffer space available (since 3.0)
 822  * @pre The player state must be set to #PLAYER_STATE_IDLE at least.
 823  * @see legacy_player_set_media_stream_info()
 824  * @see legacy_player_set_media_stream_buffer_max_size()
 825  */
 826 int legacy_player_push_media_stream(legacy_player_h player, media_packet_h packet);
 827
 828 /**
 829  * @brief  Sets contents information for media stream
 830  * @since_tizen 2.4
 831  * @remarks AV format should be set before pushing elementary stream with legacy_player_push_media_stream().
 832  * @remarks AAC can be supported.
 833  * @remarks H.264 can be supported.
 834  * @remarks This API should be called before calling the legacy_player_prepare() or legacy_player_prepare_async() \n
 835  *          to reflect the media information when pipeline is created.
 836  * @param[in] player The handle to media player
 837  * @param[in] type   The type of target stream
 838  * @param[in] format The media format to set audio information
 839  * @return @c 0 on success,
 840  *         otherwise a negative error value
 841  * @retval #PLAYER_ERROR_NONE Successful
 842  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 843  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
 844  * @pre The player state must be set to #PLAYER_STATE_IDLE by calling legacy_player_create() or legacy_player_unprepare().
 845  * @see legacy_player_push_media_stream()
 846  */
 847 int legacy_player_set_media_stream_info(legacy_player_h player, player_stream_type_e type, media_format_h format);
 848
 849 /**
 850  * @brief Registers a callback function to be invoked when buffer underrun or overflow is occurred.
 851  * @since_tizen 2.4
 852  * @remarks This API is used for media stream playback only.
 853  * @param[in] player   The handle to the media player
 854  * @param[in] type     The type of target stream
 855  * @param[in] callback The buffer status callback function to register
 856  * @param[in] user_data The user data to be passed to the callback function
 857  * @return @c 0 on success,
 858  *         otherwise a negative error value
 859  * @retval #PLAYER_ERROR_NONE Successful
 860  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 861  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 862  * @pre The player state must be set to #PLAYER_STATE_IDLE by calling legacy_player_create() or legacy_player_unprepare().
 863  * @post legacy_player_media_stream_buffer_status_cb() will be invoked.
 864  * @see legacy_player_unset_media_stream_buffer_status_cb()
 865  * @see legacy_player_media_stream_buffer_status_cb()
 866  */
 867 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);
 868
 869 /**
 870  * @brief Unregisters the buffer status callback function.
 871  * @since_tizen 2.4
 872  * @remarks This API is used for media stream playback only.
 873  * @param[in] player The handle to the media player
 874  * @param[in] type   The type of target stream
 875  * @return @c 0 on success,
 876  *         otherwise a negative error value
 877  * @retval #PLAYER_ERROR_NONE Successful
 878  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 879  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 880  * @see legacy_player_set_media_stream_buffer_status_cb()
 881  */
 882 int legacy_player_unset_media_stream_buffer_status_cb(legacy_player_h player, player_stream_type_e type);
 883
 884 /**
 885  * @brief Registers a callback function to be invoked when seeking is occurred.
 886  * @since_tizen 2.4
 887  * @remarks This API is used for media stream playback only.
 888  * @param[in] player    The handle to the media player
 889  * @param[in] type      The type of target stream
 890  * @param[in] callback  The callback function to register
 891  * @param[in] user_data The user data to be passed to the callback function
 892  * @return @c 0 on success,
 893  *         otherwise a negative error value
 894  * @retval #PLAYER_ERROR_NONE Successful
 895  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 896  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 897  * @pre The player state must be set to #PLAYER_STATE_IDLE by calling legacy_player_create() or legacy_player_unprepare().
 898  * @post legacy_player_media_stream_seek_cb() will be invoked.
 899  * @see legacy_player_unset_media_stream_seek_cb()
 900  * @see legacy_player_media_stream_seek_cb()
 901  */
 902 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);
 903
 904 /**
 905  * @brief Unregisters the seek callback function.
 906  * @since_tizen 2.4
 907  * @param[in] player The handle to the media player
 908  * @param[in] type   The type of target stream
 909  * @return @c 0 on success,
 910  *         otherwise a negative error value
 911  * @retval #PLAYER_ERROR_NONE Successful
 912  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 913  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 914  * @see legacy_player_set_media_stream_seek_cb()
 915  */
 916 int legacy_player_unset_media_stream_seek_cb(legacy_player_h player, player_stream_type_e type);
 917
 918 /**
 919  * @brief Sets the max size bytes of buffer.
 920  * @since_tizen 2.4
 921  * @remarks This API is used for media stream playback only.
 922  * @remarks If the buffer level over the max size, legacy_player_media_stream_buffer_status_cb() will be invoked with overflow status.
 923  * @param[in] player The handle to the media player
 924  * @param[in] type   The type of target stream
 925  * @param[in] max_size The max bytes of buffer, it has to be bigger than zero. (default: 200000)
 926  * @return @c 0 on success,
 927  *         otherwise a negative error value
 928  * @retval #PLAYER_ERROR_NONE Successful
 929  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 930  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 931  * @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)
 932  * @see legacy_player_get_media_stream_buffer_max_size()
 933  * @see legacy_player_media_stream_buffer_status_cb()
 934  */
 935 int legacy_player_set_media_stream_buffer_max_size(legacy_player_h player, player_stream_type_e type, unsigned long long max_size);
 936
 937 /**
 938  * @brief Gets the max size bytes of buffer.
 939  * @since_tizen 2.4
 940  * @remarks This API is used for media stream playback only.
 941  * @remarks If the buffer level over the max size, legacy_player_media_stream_buffer_status_cb() will be invoked with overflow status.
 942  * @param[in] player The handle to the media player
 943  * @param[in] type   The type of target stream
 944  * @param[out] max_size The max bytes of buffer
 945  * @return @c 0 on success,
 946  *         otherwise a negative error value
 947  * @retval #PLAYER_ERROR_NONE Successful
 948  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 949  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 950  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 951  * @see legacy_player_set_media_stream_buffer_max_size()
 952  * @see legacy_player_media_stream_buffer_status_cb()
 953  */
 954 int legacy_player_get_media_stream_buffer_max_size(legacy_player_h player, player_stream_type_e type, unsigned long long *max_size);
 955
 956 /**
 957  * @brief Sets the buffer threshold percent of buffer.
 958  * @since_tizen 2.4
 959  * @remarks This API is used for media stream playback only.
 960  * @remarks If the buffer level drops below the percent value, legacy_player_media_stream_buffer_status_cb() will be invoked with underrun status.
 961  * @param[in] player The handle to the media player
 962  * @param[in] type   The type of target stream
 963  * @param[in] percent The minimum threshold(0~100) of buffer (default: 0)
 964  * @return @c 0 on success,
 965  *         otherwise a negative error value
 966  * @retval #PLAYER_ERROR_NONE Successful
 967  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 968  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 969  * @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)
 970  * @see legacy_player_get_media_stream_buffer_min_threshold()
 971  * @see legacy_player_media_stream_buffer_status_cb()
 972  */
 973 int legacy_player_set_media_stream_buffer_min_threshold(legacy_player_h player, player_stream_type_e type, unsigned int percent);
 974
 975 /**
 976  * @brief Gets the buffer threshold percent of buffer.
 977  * @since_tizen 2.4
 978  * @remarks This API is used for media stream playback only.
 979  * @remarks If the buffer level drops below the percent value, legacy_player_media_stream_buffer_status_cb() will be invoked with underrun status.
 980  * @param[in] player The handle to the media player
 981  * @param[in] type   The type of target stream
 982  * @param[out] percent The minimum threshold(0~100) of buffer
 983  * @return @c 0 on success,
 984  *         otherwise a negative error value
 985  * @retval #PLAYER_ERROR_NONE Successful
 986  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 987  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 988  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 989  * @see legacy_player_set_media_stream_buffer_min_threshold()
 990  * @see legacy_player_media_stream_buffer_status_cb()
 991  */
 992 int legacy_player_get_media_stream_buffer_min_threshold(legacy_player_h player, player_stream_type_e type, unsigned int *percent);
 993
 994 /**
 995  * @brief Sets the video display mode.
 996  * @since_tizen 2.3
 997  * @remarks If no display is set, no operation is performed.
 998  * @param[in] player   The handle to the media player
 999  * @param[in] mode The display mode
1000  * @return @c 0 on success,
1001  *         otherwise a negative error value
1002  * @retval #PLAYER_ERROR_NONE Successful
1003  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1004  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1005  * @pre The player should support display mode changes.
1006  * @see legacy_player_get_display_mode()
1007  */
1008 int legacy_player_set_display_mode(legacy_player_h player, player_display_mode_e mode);
1009
1010 /**
1011  * @brief Gets the video display mode.
1012  * @since_tizen 2.3
1013  * @remarks If no display is set, no operation is performed.
1014  * @param[in] player The handle to the media player
1015  * @param[out] mode The current display mode
1016  * @return @c 0 on success,
1017  *         otherwise a negative error value
1018  * @retval  #PLAYER_ERROR_NONE Successful
1019  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1020  * @see legacy_player_set_display_mode()
1021  */
1022 int legacy_player_get_display_mode(legacy_player_h player, player_display_mode_e *mode);
1023
1024 /**
1025  * @brief Sets the visibility of the video surface display
1026  * @since_tizen 2.3
1027  * @param[in] player   The handle to the media player
1028  * @param[in] visible The visibility of the display (@c true = visible, @c false = non-visible )
1029  * @return @c 0 on success,
1030  *         otherwise a negative error value
1031  * @retval #PLAYER_ERROR_NONE Successful
1032  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1033  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1034  * @see legacy_player_is_display_visible()
1035  */
1036 int legacy_player_set_display_visible(legacy_player_h player, bool visible);
1037
1038 /**
1039  * @brief Gets the visibility of the video surface display.
1040  * @since_tizen 2.3
1041  * @param[in] player The handle to the media player
1042  * @param[out] visible The current visibility of the display (@c true = visible, @c false = non-visible )
1043  * @return @c 0 on success,
1044  *         otherwise a negative error value
1045  * @retval  #PLAYER_ERROR_NONE Successful
1046  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1047  * @see legacy_player_set_display_visible()
1048  */
1049 int legacy_player_is_display_visible(legacy_player_h player, bool *visible);
1050
1051 /**
1052  * @brief Sets the rotation settings of the video surface display.
1053  * @since_tizen 2.3
1054  * @details Use this function to change the video orientation to portrait mode.
1055  * @param[in] player   The handle to the media player
1056  * @param[in] rotation The rotation of the display
1057  * @return @c 0 on success,
1058  *         otherwise a negative error value
1059  * @retval #PLAYER_ERROR_NONE Successful
1060  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1061  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1062  * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
1063  * @see  legacy_player_set_display
1064  * @see  legacy_player_get_display_rotation()
1065  */
1066 int legacy_player_set_display_rotation(legacy_player_h player, player_display_rotation_e rotation);
1067
1068 /**
1069  * @brief Gets the rotation of the video surface display.
1070  * @since_tizen 2.3
1071  * @param[in] player The handle to the media player
1072  * @param[out] rotation The current rotation of the display
1073  * @return @c 0 on success,
1074  *         otherwise a negative error value
1075  * @retval  #PLAYER_ERROR_NONE Successful
1076  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1077  * @see     legacy_player_set_display_rotation()
1078  */
1079 int legacy_player_get_display_rotation(legacy_player_h player, player_display_rotation_e *rotation);
1080
1081  /**
1082  * @brief Gets the media content information.
1083  * @since_tizen 2.3
1084  * @remarks You must release @a value using @c free().
1085  * @remarks The playback type should be local playback or HTTP streaming playback.
1086  * @param[in]  player The handle to the media player
1087  * @param[in] key The key attribute name to get
1088  * @param[out] value The value of the key attribute \n
1089  *                   It can be an empty string if there is no content information.
1090  * @return @c 0 on success,
1091  *         otherwise a negative error value
1092  * @retval #PLAYER_ERROR_NONE Successful
1093  * @retval #PLAYER_ERROR_INVALID_PARAMETER  Invalid parameter
1094  * @retval #PLAYER_ERROR_OUT_OF_MEMORY Not enough memory is available
1095  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1096  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1097  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1098  */
1099 int legacy_player_get_content_info(legacy_player_h player, player_content_info_e key, char **value);
1100
1101 /**
1102  * @brief Gets the audio and video codec information.
1103  * @since_tizen 2.3
1104  * @remarks You must release @a audio_codec and @a video_codec using free().
1105  * @remarks The playback type should be local playback or HTTP streaming playback.
1106  * @param[in] player The handle to the media player
1107  * @param[out] audio_codec The name of the audio codec \n
1108  *                         It can be @c NULL if there is no audio codec.
1109  * @param[out] video_codec The name of the video codec \n
1110  *                         It can be @c NULL if there is no video codec.
1111  * @return @c 0 on success,
1112  *         otherwise a negative error value
1113  * @retval #PLAYER_ERROR_NONE Successful
1114  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1115  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1116  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1117  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1118  */
1119 int legacy_player_get_codec_info(legacy_player_h player, char **audio_codec, char **video_codec);
1120
1121 /**
1122  * @brief Gets the audio stream information.
1123  * @since_tizen 2.3
1124  * @remarks The playback type should be local playback or HTTP streaming playback.
1125  * @param[in] player The handle to the media player
1126  * @param[out]  sample_rate The audio sample rate [Hz] \n
1127  *                          Value can be invalid if there is no audio stream information.
1128  * @param[out]  channel The audio channel (1: mono, 2: stereo) \n
1129  *                      Value can be invalid if there is no audio stream information.
1130  * @param[out]  bit_rate The audio bit rate [Hz] \n
1131  *                       Value can be invalid if there is no audio stream information.
1132  * @return @c 0 on success,
1133  *         otherwise a negative error value
1134  * @retval #PLAYER_ERROR_NONE Successful
1135  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1136  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1137  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1138  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1139  */
1140 int legacy_player_get_audio_stream_info(legacy_player_h player, int *sample_rate, int *channel, int *bit_rate);
1141
1142 /**
1143  * @brief Gets the video stream information.
1144  * @since_tizen 2.3
1145  * @remarks The playback type should be local playback or HTTP streaming playback.
1146  * @param[in] player The handle to the media player
1147  * @param[out]  fps The frame per second of the video \n
1148  *                  It can be @c 0 if there is no video stream information.
1149  * @param[out]  bit_rate The video bit rate [Hz] \n
1150  *                       It can be an invalid value if there is no video stream information.
1151  * @return @c 0 on success,
1152  *         otherwise a negative error value
1153  * @retval #PLAYER_ERROR_NONE Successful
1154  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1155  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1156  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1157  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1158  */
1159 int legacy_player_get_video_stream_info(legacy_player_h player, int *fps, int *bit_rate);
1160
1161 /**
1162  * @brief Gets the video display's height and width.
1163  * @since_tizen 2.3
1164  * @remarks The playback type should be local playback or HTTP streaming playback.
1165  * @param[in] player The handle to the media player
1166  * @param[out] width The width of the video \n
1167  *                   Value can be invalid if there is no video or no display is set.
1168  * @param[out] height The height of the video \n
1169  *                    Value can be invalid value if there is no video or no display is set.
1170  * @return @c 0 on success,
1171  *         otherwise a negative error value
1172  * @retval #PLAYER_ERROR_NONE Successful
1173  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1174  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1175  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1176  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1177  */
1178 int legacy_player_get_video_size(legacy_player_h player, int *width, int *height);
1179
1180 /**
1181  * @brief Gets the album art in the media resource.
1182  * @since_tizen 2.3
1183  * @remarks You must not release @a album_art. It will be released by framework when the player is destroyed.
1184  * @param[in] player The handle to the media player
1185  * @param[out] album_art The encoded artwork image
1186  * @param[out] size The encoded artwork size
1187  * @return @c 0 on success,
1188  *         otherwise a negative error value
1189  * @retval #PLAYER_ERROR_NONE Successful
1190  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1191  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1192  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1193  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1194  */
1195 int legacy_player_get_album_art(legacy_player_h player, void **album_art, int *size);
1196
1197 /**
1198  * @brief Gets the total running time of the associated media.
1199  * @since_tizen 2.3
1200  * @remarks The media source is associated with the player, using either legacy_player_set_uri() or legacy_player_set_memory_buffer().
1201  * @remarks The playback type should be local playback or HTTP streaming playback.
1202  * @param[in]   player The handle to the media player
1203  * @param[out]  duration The duration in nanoseconds
1204  * @return @c 0 on success,
1205  *         otherwise a negative error value
1206  * @retval #PLAYER_ERROR_NONE Successful
1207  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1208  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1209  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1210  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1211  * @see legacy_player_set_uri()
1212  * @see legacy_player_set_memory_buffer()
1213  */
1214 int legacy_player_get_duration(legacy_player_h player, int64_t *duration);
1215
1216 /**
1217  * @brief Gets the number of equalizer bands.
1218  * @since_tizen 2.3
1219  * @param[in] player The handle to the media player
1220  * @param[out] count The number of equalizer bands
1221  * @return @c 0 on success,
1222  *         otherwise a negative error value
1223  * @retval #PLAYER_ERROR_NONE Successful
1224  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1225  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1226  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1227  * @see legacy_player_audio_effect_set_equalizer_band_level()
1228  * @see legacy_player_audio_effect_set_equalizer_all_bands()
1229  */
1230 int legacy_player_audio_effect_get_equalizer_bands_count(legacy_player_h player, int *count);
1231
1232 /**
1233  * @brief Sets the gain set for the given equalizer band.
1234  * @since_tizen 2.3
1235  * @param[in] player The handle to the media player
1236  * @param[in] index The index of the equalizer band to be set
1237  * @param[in] level The new gain in decibel that is set to the given band [dB]
1238  * @return @c 0 on success,
1239  *         otherwise a negative error value
1240  * @retval #PLAYER_ERROR_NONE Successful
1241  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1242  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1243  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1244  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1245  * @see legacy_player_audio_effect_get_equalizer_bands_count()
1246  * @see legacy_player_audio_effect_get_equalizer_level_range()
1247  * @see legacy_player_audio_effect_get_equalizer_band_level()
1248  * @see legacy_player_audio_effect_set_equalizer_all_bands()
1249  */
1250 int legacy_player_audio_effect_set_equalizer_band_level(legacy_player_h player, int index, int level);
1251
1252 /**
1253  * @brief Gets the gain set for the given equalizer band.
1254  * @since_tizen 2.3
1255  * @param[in]   player The handle to the media player
1256  * @param[in]   index The index of the requested equalizer band
1257  * @param[out]   level The gain in decibel of the given band [dB]
1258  * @return @c 0 on success,
1259  *         otherwise a negative error value
1260  * @retval #PLAYER_ERROR_NONE Successful
1261  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1262  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1263  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1264  * @see legacy_player_audio_effect_set_equalizer_band_level()
1265  */
1266 int legacy_player_audio_effect_get_equalizer_band_level(legacy_player_h player, int index, int *level);
1267
1268 /**
1269  * @brief Sets all bands of the equalizer.
1270  * @since_tizen 2.3
1271  * @param[in] player The handle to the media player
1272  * @param[in] band_levels The list of band levels to be set
1273  * @param[in] length The length of the band level
1274  * @return @c 0 on success,
1275  *         otherwise a negative error value
1276  * @retval #PLAYER_ERROR_NONE Successful
1277  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1278  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1279  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1280  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1281  * @see legacy_player_audio_effect_get_equalizer_bands_count()
1282  * @see legacy_player_audio_effect_get_equalizer_level_range()
1283  * @see legacy_player_audio_effect_set_equalizer_band_level()
1284  */
1285 int legacy_player_audio_effect_set_equalizer_all_bands(legacy_player_h player, int *band_levels, int length);
1286
1287 /**
1288  * @brief Gets the valid band level range of the equalizer.
1289  * @since_tizen 2.3
1290  * @param[in] player The handle to the media player
1291  * @param[out] min The minimum value to be set [dB]
1292  * @param[out] max The maximum value to be set [dB]
1293  * @return @c 0 on success,
1294  *         otherwise a negative error value
1295  * @retval #PLAYER_ERROR_NONE Successful
1296  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1297  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1298  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1299  * @see legacy_player_audio_effect_set_equalizer_band_level()
1300  * @see legacy_player_audio_effect_set_equalizer_all_bands()
1301  */
1302 int legacy_player_audio_effect_get_equalizer_level_range(legacy_player_h player, int *min, int *max);
1303
1304 /**
1305  * @brief Gets the band frequency of the equalizer.
1306  * @since_tizen 2.3
1307  * @param[in] player The handle to the media player
1308  * @param[in]  index The index of the requested equalizer band
1309  * @param[out] frequency The frequency of the given band [dB]
1310  * @return @c 0 on success,
1311  *         otherwise a negative error value
1312  * @retval #PLAYER_ERROR_NONE Successful
1313  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1314  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1315  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1316  */
1317 int legacy_player_audio_effect_get_equalizer_band_frequency(legacy_player_h player, int index, int *frequency);
1318
1319 /**
1320  * @brief Gets the band frequency range of the equalizer.
1321  * @since_tizen 2.3
1322  * @param[in] player The handle to the media player
1323  * @param[in]  index The index of the requested equalizer band
1324  * @param[out] range The frequency range of the given band [dB]
1325  * @return @c 0 on success,
1326  *         otherwise a negative error value
1327  * @retval #PLAYER_ERROR_NONE Successful
1328  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1329  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1330  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1331  */
1332 int legacy_player_audio_effect_get_equalizer_band_frequency_range(legacy_player_h player, int index, int *range);
1333
1334 /**
1335  * @brief Clears the equalizer effect.
1336  * @since_tizen 2.3
1337  * @param[in] player The handle to the media player
1338  * @retval #PLAYER_ERROR_NONE Successful
1339  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1340  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1341  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1342  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1343  * @see legacy_player_audio_effect_set_equalizer_band_level()
1344  * @see legacy_player_audio_effect_set_equalizer_all_bands()
1345  */
1346 int legacy_player_audio_effect_equalizer_clear(legacy_player_h player);
1347
1348 /**
1349  * @brief Checks whether the custom equalizer effect is available.
1350  * @since_tizen 2.3
1351  * @param[in] player The handle to the media player
1352  * @param[out] available If @c true the specified audio effect is available,
1353  *                       otherwise @c false
1354  * @retval #PLAYER_ERROR_NONE Successful
1355  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1356  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1357  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1358  * @see legacy_player_audio_effect_set_equalizer_band_level()
1359  * @see legacy_player_audio_effect_set_equalizer_all_bands()
1360  */
1361 int legacy_player_audio_effect_equalizer_is_available(legacy_player_h player, bool *available);
1362
1363 /**
1364  * @brief Captures the video frame, asynchronously.
1365  * @since_tizen 2.3
1366  * @param[in] player The handle to the media player
1367  * @param[in] callback  The callback function to register
1368  * @param[in] user_data The user data to be passed to the callback function
1369  * @return @c 0 on success,
1370  *         otherwise a negative error value
1371  * @retval #PLAYER_ERROR_NONE Successful
1372  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1373  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1374  *              Video type should be set using legacy_player_set_display() otherwises, audio stream is only processed even though video file is set.
1375  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1376  * @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().
1377  * @post It invokes legacy_player_video_captured_cb() when capture completes, if you set a callback.
1378  * @see legacy_player_video_captured_cb()
1379  */
1380 int legacy_player_capture_video(legacy_player_h player, player_video_captured_cb callback, void *user_data);
1381
1382 /**
1383  * @brief Sets the cookie for streaming playback.
1384  * @since_tizen 2.3
1385  * @param[in] player The handle to the media player
1386  * @param[in] cookie The cookie to set
1387  * @param[in] size The size of the cookie
1388  * @return @c 0 on success,
1389  *         otherwise a negative error value
1390  * @retval #PLAYER_ERROR_NONE Successful
1391  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1392  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1393  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1394  * @pre The player state must be set to #PLAYER_STATE_IDLE by calling legacy_player_create() or legacy_player_unprepare().
1395  * @see legacy_player_set_streaming_user_agent()
1396  */
1397 int legacy_player_set_streaming_cookie(legacy_player_h player, const char *cookie, int size);
1398
1399 /**
1400  * @brief Sets the streaming user agent for playback.
1401  * @since_tizen 2.3
1402  * @param[in] player The handle to the media player
1403  * @param[in] user_agent The user agent to set
1404  * @param[in] size The size of the user agent
1405  * @return @c 0 on success,
1406  *         otherwise a negative error value
1407  * @retval #PLAYER_ERROR_NONE Successful
1408  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1409  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1410  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1411  * @pre The player state must be set to #PLAYER_STATE_IDLE by calling legacy_player_create() or legacy_player_unprepare().
1412  * @see legacy_player_set_streaming_cookie()
1413  */
1414 int legacy_player_set_streaming_user_agent(legacy_player_h player, const char *user_agent, int size);
1415
1416 /**
1417  * @brief Gets the download progress for streaming playback.
1418  * @since_tizen 2.3
1419  * @param[in] player The handle to the media player
1420  * @param[out] start The starting position in percentage [0, 100]
1421  * @param[out] end The end position in percentage [0, 100]
1422  * @return @c 0 on success,
1423  *         otherwise a negative error value
1424  * @retval #PLAYER_ERROR_NONE Successful
1425  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1426  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1427  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1428  * @pre The player state must be set to #PLAYER_STATE_PLAYING by calling legacy_player_start() or set to #PLAYER_STATE_PAUSED by calling legacy_player_pause().
1429  */
1430 int legacy_player_get_streaming_download_progress(legacy_player_h player, int *start, int *end);
1431
1432 /**
1433  * @brief Registers a callback function to be invoked when the playback is finished.
1434  * @since_tizen 2.3
1435  * @param[in] player    The handle to the media player
1436  * @param[in] callback  The callback function to register
1437  * @param[in] user_data The user data to be passed to the callback function
1438  * @return @c 0 on success,
1439  *         otherwise a negative error value
1440  * @retval #PLAYER_ERROR_NONE Successful
1441  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1442  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1443  * @post  legacy_player_completed_cb() will be invoked.
1444  * @see legacy_player_unset_completed_cb()
1445  * @see legacy_player_completed_cb()
1446  * @see legacy_player_start()
1447  */
1448 int legacy_player_set_completed_cb(legacy_player_h player, player_completed_cb callback, void *user_data);
1449
1450 /**
1451  * @brief Unregisters the callback function.
1452  * @since_tizen 2.3
1453  * @param[in] player The handle to the media player
1454  * @return @c 0 on success,
1455  *         otherwise a negative error value
1456  * @retval #PLAYER_ERROR_NONE Successful
1457  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1458  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1459  * @see legacy_player_set_completed_cb()
1460  */
1461 int legacy_player_unset_completed_cb(legacy_player_h player);
1462
1463 /**
1464  * @brief Registers a callback function to be invoked when the playback is interrupted or the interrupt is completed.
1465  * @since_tizen 2.3
1466  * @param[in] player    The handle to the media player
1467  * @param[in] callback  The callback function to register
1468  * @param[in] user_data The user data to be passed to the callback function
1469  * @return @c 0 on success,
1470  *         otherwise a negative error value
1471  * @retval #PLAYER_ERROR_NONE Successful
1472  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1473  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1474  * @post  player_interrupted_cb() will be invoked.
1475  * @see legacy_player_unset_interrupted_cb()
1476  * @see legacy_player_interrupted_cb()
1477  */
1478 int legacy_player_set_interrupted_cb(legacy_player_h player, player_interrupted_cb callback, void *user_data);
1479
1480 /**
1481  * @brief Unregisters the callback function.
1482  * @since_tizen 2.3
1483  * @param[in] player The handle to the media player
1484  * @return @c 0 on success,
1485  *         otherwise a negative error value
1486  * @retval #PLAYER_ERROR_NONE Successful
1487  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1488  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1489  * @see legacy_player_set_interrupted_cb()
1490  */
1491 int legacy_player_unset_interrupted_cb(legacy_player_h player);
1492
1493 /**
1494  * @brief Registers a callback function to be invoked when an error occurs.
1495  * @since_tizen 2.3
1496  * @param[in] player    The handle to the media player
1497  * @param[in] callback  The callback function to register
1498  * @param[in] user_data The user data to be passed to the callback function
1499  * @return @c 0 on success,
1500  *         otherwise a negative error value
1501  * @retval #PLAYER_ERROR_NONE Successful
1502  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1503  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1504  * @post  legacy_player_error_cb() will be invoked.
1505  * @see legacy_player_unset_error_cb()
1506  * @see legacy_player_error_cb()
1507  */
1508 int legacy_player_set_error_cb(legacy_player_h player, player_error_cb callback, void *user_data);
1509
1510 /**
1511  * @brief Unregisters the callback function.
1512  * @since_tizen 2.3
1513  * @param[in] player The handle to the media player
1514  * @return @c 0 on success,
1515  *         otherwise a negative error value
1516  * @retval #PLAYER_ERROR_NONE Successful
1517  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1518  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1519  * @see legacy_player_set_error_cb()
1520  */
1521 int legacy_player_unset_error_cb(legacy_player_h player);
1522
1523 /**
1524  * @brief Registers a callback function to be invoked when there is a change in the buffering status of a media stream.
1525  * @since_tizen 2.3
1526  * @remarks The media resource should be streamed over the network.
1527  * @param[in] player    The handle to the media player
1528  * @param[in] callback  The callback function to register
1529  * @param[in] user_data The user data to be passed to the callback function
1530  * @return @c 0 on success,
1531  *         otherwise a negative error value
1532  * @retval #PLAYER_ERROR_NONE Successful
1533  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1534  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1535  * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
1536  * @post  legacy_player_buffering_cb() will be invoked.
1537  * @see legacy_player_unset_buffering_cb()
1538  * @see legacy_player_set_uri()
1539  * @see legacy_player_buffering_cb()
1540  */
1541 int legacy_player_set_buffering_cb(legacy_player_h player, player_buffering_cb callback, void *user_data);
1542
1543 /**
1544  * @brief Unregisters the callback function.
1545  * @since_tizen 2.3
1546  * @param[in] player The handle to the media player
1547  * @return @c 0 on success,
1548  *         otherwise a negative error value
1549  * @retval #PLAYER_ERROR_NONE Successful
1550  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1551  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1552  * @see legacy_player_set_buffering_cb()
1553  */
1554 int legacy_player_unset_buffering_cb(legacy_player_h player);
1555
1556 /**
1557  * @brief Sets the playback rate.
1558  * @since_tizen 2.3
1559  * @details The default value is @c 1.0.
1560  * @remarks #PLAYER_ERROR_INVALID_OPERATION occurs when streaming playback.
1561  * @remarks No operation is performed, if @a rate is @c 0.
1562  * @remarks The sound is muted, when playback rate is under @c 0.0 and over @c 2.0.
1563  * @param[in]   player The handle to the media player
1564  * @param[in]   rate The playback rate (-5.0x ~ 5.0x)
1565  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1566  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1567  * @pre The player state must be set to #PLAYER_STATE_PLAYING by calling legacy_player_start().
1568  * @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().
1569  */
1570 int legacy_player_set_playback_rate(legacy_player_h player, float rate);
1571
1572 /**
1573  * @brief Sets a subtitle path.
1574  * @since_tizen 2.3
1575  * @remarks Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.
1576  * @param[in]   player The handle to the media player
1577  * @param[in]   path The absolute path of the subtitle file, it can be @c NULL in the #PLAYER_STATE_IDLE state.
1578  * @return @c 0 on success,
1579  *         otherwise a negative error value
1580  * @retval #PLAYER_ERROR_NONE Successful
1581  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1582  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1583  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1584  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1585  * @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().
1586  */
1587 int legacy_player_set_subtitle_path(legacy_player_h player, const char *path);
1588
1589 /**
1590  * @brief Registers a callback function to be invoked when a subtitle updates.
1591  * @since_tizen 2.3
1592  * @param[in] player    The handle to the media player
1593  * @param[in] callback  The callback function to register
1594  * @param[in] user_data The user data to be passed to the callback function
1595  * @return @c 0 on success,
1596  *         otherwise a negative error value
1597  * @retval #PLAYER_ERROR_NONE Successful
1598  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1599  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1600  * @pre The subtitle must be set by calling legacy_player_set_subtitle_path().
1601  * @post  legacy_player_subtitle_updated_cb() will be invoked.
1602  * @see legacy_player_unset_subtitle_updated_cb()
1603  * @see legacy_player_subtitle_updated_cb()
1604  * @see legacy_player_set_subtitle_path()
1605  */
1606 int legacy_player_set_subtitle_updated_cb(legacy_player_h player, player_subtitle_updated_cb callback, void *user_data);
1607
1608 /**
1609  * @brief Unregisters the callback function.
1610  * @since_tizen 2.3
1611  * @param[in] player The handle to the media player
1612  * @return @c 0 on success,
1613  *         otherwise a negative error value
1614  * @retval #PLAYER_ERROR_NONE Successful
1615  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1616  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1617  * @see legacy_player_set_subtitle_updated_cb()
1618  */
1619 int legacy_player_unset_subtitle_updated_cb(legacy_player_h player);
1620
1621 /**
1622  * @brief Sets the seek position for the subtitle.
1623  * @since_tizen 2.3.1
1624  * @remarks Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.
1625  * @param[in]  player The handle to the media player
1626  * @param[in]  millisecond The position in milliseconds from the start to the seek point
1627  * @return @c 0 on success,
1628  *         otherwise a negative error value
1629  * @retval #PLAYER_ERROR_NONE Successful
1630  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1631  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1632  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1633  * @pre The subtitle must be set by calling legacy_player_set_subtitle_path().
1634  * @pre The player state must be one of these: #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1635  */
1636 int legacy_player_set_subtitle_position_offset(legacy_player_h player, int millisecond);
1637
1638 /**
1639  * @brief Registers a callback function to be invoked when video stream is changed.
1640  * @since_tizen 2.4
1641  * @remarks The stream changing is detected just before rendering operation.
1642  * @param[in] player   The handle to the media player
1643  * @param[in] callback The stream changed callback function to register
1644  * @param[in] user_data The user data to be passed to the callback function
1645  * @return @c 0 on success,
1646  *         otherwise a negative error value
1647  * @retval #PLAYER_ERROR_NONE Successful
1648  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1649  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1650  * @pre The player state must be set to #PLAYER_STATE_IDLE by calling legacy_player_create() or legacy_player_unprepare().
1651  * @post legacy_player_video_stream_changed_cb() will be invoked.
1652  * @see legacy_player_unset_video_stream_changed_cb()
1653  * @see legacy_player_video_stream_changed_cb()
1654  */
1655 int legacy_player_set_video_stream_changed_cb(legacy_player_h player, player_video_stream_changed_cb callback, void *user_data);
1656
1657 /**
1658  * @brief Unregisters the video stream changed callback function.
1659  * @since_tizen 2.4
1660  * @param[in] player The handle to the media player
1661  * @return @c 0 on success,
1662  *         otherwise a negative error value
1663  * @retval #PLAYER_ERROR_NONE Successful
1664  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1665  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1666  * @see legacy_player_set_video_stream_changed_cb()
1667  */
1668 int legacy_player_unset_video_stream_changed_cb(legacy_player_h player);
1669
1670 /**
1671  * @brief Gets current track index.
1672  * @since_tizen 2.4
1673  * @details Index starts from 0.
1674  * @remarks PLAYER_STREAM_TYPE_VIDEO is not supported.
1675  * @param[in] player The handle to the media player
1676  * @param[in] type The type of target stream
1677  * @param[out] index  The index of track
1678  * @return @c 0 on success,
1679  *         otherwise a negative error value
1680  * @retval #PLAYER_ERROR_NONE Successful
1681  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1682  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1683  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1684  * @retval #PLAYER_ERROR_NOT_SUPPORTD Not supported
1685  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
1686  */
1687 int legacy_player_get_current_track(legacy_player_h player, player_stream_type_e type, int *index);
1688
1689 /**
1690  * @brief Gets language code of a track.
1691  * @since_tizen 2.4
1692  * @remarks @a code must be released with @c free() by caller
1693  * @remarks PLAYER_STREAM_TYPE_VIDEO is not supported.
1694  * @param[in] player The handle to the media player
1695  * @param[in] type The type of target stream
1696  * @param[in] index  The index of track
1697  * @param[out] code A language code in ISO 639-1. "und" will be returned if the language is undefined.
1698  * @param[out] len length of language code.
1699  * @return @c 0 on success,
1700  *         otherwise a negative error value
1701  * @retval #PLAYER_ERROR_NONE Successful
1702  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1703  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1704  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1705  * @retval #PLAYER_ERROR_NOT_SUPPORTD Not supported
1706  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
1707  */
1708 int legacy_player_get_track_language_code(legacy_player_h player, player_stream_type_e type, int index, char **code, int *len);
1709
1710 /**
1711  * @brief Gets the track count.
1712  * @since_tizen 2.4
1713  * @remarks PLAYER_STREAM_TYPE_VIDEO is not supported.
1714  * @param[in] player The handle to the media player
1715  * @param[in] type The type of target stream
1716  * @param[out] count The number of track
1717  * @return @c 0 on success,
1718  *         otherwise a negative error value
1719  * @retval #PLAYER_ERROR_NONE Successful
1720  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1721  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1722  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1723  * @retval #PLAYER_ERROR_NOT_SUPPORTD Not supported
1724  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
1725  */
1726 int legacy_player_get_track_count(legacy_player_h player, player_stream_type_e type, int *count);
1727
1728 /**
1729  * @brief Selects a track to play.
1730  * @since_tizen 2.4
1731  * @remarks PLAYER_STREAM_TYPE_VIDEO is not supported.
1732  * @param[in] player The handle to the media player
1733  * @param[in] type The type of target stream
1734  * @param[in] index  The index of track
1735  * @return @c 0 on success,
1736  *         otherwise a negative error value
1737  * @retval #PLAYER_ERROR_NONE Successful
1738  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1739  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1740  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1741  * @retval #PLAYER_ERROR_NOT_SUPPORTD Not supported
1742  * @pre The player state must be one of these: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
1743  * @see legacy_player_get_current_track()
1744  */
1745 int legacy_player_select_track(legacy_player_h player, player_stream_type_e type, int index);
1746
1747 #ifdef TIZEN_FEATURE_EVAS_RENDERER
1748 /**
1749  * @brief Registers a callback function that is to be invoked when the buffer needs to be released for gapless.
1750  * @since_tizen 4.0
1751  * @param[in] player    The handle to the media player
1752  * @param[in] callback  The callback function to register
1753  * @param[in] user_data The user data to be passed to the callback function
1754  * @return @c 0 on success,
1755  *         otherwise a negative error value
1756  * @retval #PLAYER_ERROR_NONE Successful
1757  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1758  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1759  * @post  player_retrieve_buffer_cb() will be invoked.
1760  * @see legacy_player_unset_retrieve_buffer_cb()
1761  */
1762 int legacy_player_set_retrieve_buffer_cb(legacy_player_h player, player_retrieve_buffer_cb callback, void *user_data);
1763
1764 /**
1765  * @brief Unregisters the callback function.
1766  * @since_tizen 4.0
1767  * @param[in] player The handle to the media player
1768  * @return @c 0 on success,
1769  *         otherwise a negative error value
1770  * @retval #PLAYER_ERROR_NONE Successful
1771  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1772  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1773  * @see legacy_player_set_retrieve_buffer_cb()
1774  */
1775 int legacy_player_unset_retrieve_buffer_cb(legacy_player_h player);
1776 #endif
1777
1778 /**
1779  * @brief Manage the external storage state
1780  * @since_tizen 3.0
1781  * @param[in] player The handle to the media player
1782  * @param[in] id The id of external storage
1783  * @param[in] state The state of external storage
1784  * @return @c 0 on success,
1785  *         otherwise a negative error value
1786  * @retval  #PLAYER_ERROR_NONE Successful
1787  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1788  * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1789  */
1790 int legacy_player_manage_external_storage_state(legacy_player_h player, int id, int state);
1791
1792 /**
1793  * @brief Sets the ROI (Region Of Interest) area of the content video source.
1794  * @details This function is to set the ROI area of video content to render it
1795  *          on #PLAYER_DISPLAY_TYPE_OVERLAY display with current display mode.
1796  *          It can be regarded as zooming operation because the selected video area will be rendered fit to the display.
1797  * @since_tizen 5.0
1798  * @remarks This function requires the ratio value of the each coordinate and size based on the video resolution size
1799  *          to consider the dynamic resolution video content.
1800  * @remarks The ROI area is valid only in #PLAYER_DISPLAY_TYPE_OVERLAY.
1801  * @param[in] player        The handle to the media player
1802  * @param[in] scale_x       X coordinate ratio value of the video source area based on the video width size \n
1803  *                          Valid range is 0.0~1.0.
1804  * @param[in] scale_y       Y coordinate ratio value of the video source area based on the video height size \n
1805  *                          Valid range is 0.0~1.0.
1806  * @param[in] scale_width   Width ratio value of the video source area based on the video width size \n
1807  *                          Valid range is from greater than 0.0 to 1.0.
1808  * @param[in] scale_height  Height ratio value of the video source area based on the video height size \n
1809  *                          Valid range is from greater than 0.0 to 1.0.
1810  * @return @c 0 on success,
1811  *         otherwise a negative error value
1812  * @retval  #PLAYER_ERROR_NONE Successful
1813  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1814  * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1815  * @see legacy_player_set_display()
1816  * @see legacy_player_set_display_mode()
1817  * @see legacy_player_get_video_size()
1818  * @see legacy_player_get_video_roi_area()
1819  */
1820 int legacy_player_set_video_roi_area(legacy_player_h player, double scale_x, double scale_y, double scale_width, double scale_height);
1821
1822 /**
1823  * @brief Gets the ROI (Region Of Interest) area of the content video source.
1824  * @since_tizen 5.0
1825  * @remarks This function gets the ratio value of the each coordinate and size based on the video resolution size.
1826  * @remarks The ROI area is valid only in #PLAYER_DISPLAY_TYPE_OVERLAY.
1827  * @param[in]  player        The handle to the media player
1828  * @param[out] scale_x       The current X coordinate ratio value of the video source area based on the video width size
1829  * @param[out] scale_y       The current Y coordinate ratio value of the video source area based on the video height size
1830  * @param[out] scale_width   The current width ratio value of the video source area based on the video width size
1831  * @param[out] scale_height  The current height ratio value of the video source area based on the video height size
1832  * @return @c 0 on success,
1833  *         otherwise a negative error value
1834  * @retval  #PLAYER_ERROR_NONE Successful
1835  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1836  * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1837  * @see legacy_player_set_display()
1838  * @see legacy_player_get_video_size()
1839  * @see legacy_player_set_video_roi_area()
1840  */
1841 int legacy_player_get_video_roi_area(legacy_player_h player, double *scale_x, double *scale_y, double *scale_width, double *scale_height);
1842
1843 /**
1844  * @brief Sets the ROI(Region Of Interest) area of display.
1845  * @since_tizen 3.0
1846  * @remarks If no display is set, no operation is performed.
1847  * @remarks Before set display ROI area, #PLAYER_DISPLAY_MODE_DST_ROI must be set with legacy_player_set_display_mode().
1848  *          The minimum value of width and height are 1.
1849  * @param[in] player The handle to the media player
1850  * @param[in] x X coordinate of area
1851  * @param[in] y Y coordinate of area
1852  * @param[in] width Width of area
1853  * @param[in] height Height of area
1854  * @return @c 0 on success,
1855  *         otherwise a negative error value
1856  * @retval  #PLAYER_ERROR_NONE Successful
1857  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1858  * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1859  * @pre display_mode must be set to #PLAYER_DISPLAY_MODE_DST_ROI.
1860  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1861  * @see legacy_player_set_display()
1862  * @see legacy_player_set_display_mode()
1863  */
1864 int legacy_player_set_roi_area(legacy_player_h player, int x, int y, int w, int h);
1865
1866 /**
1867  * @brief Sets sound stream info
1868  * @since_tizen 3.0
1869  * @param[in] player The handle to the media player
1870  * @param[in] stream_type The type of stream
1871  * @param[in] stream_index The index of stream
1872  * @return @c 0 on success,
1873  *         otherwise a negative error value
1874  * @retval  #PLAYER_ERROR_NONE Successful
1875  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1876  * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1877  */
1878 int legacy_player_set_sound_stream_info_for_mused(legacy_player_h player, char *stream_type, int stream_index);
1879
1880 /**
1881  * @brief Gets time out time from muse-server
1882  * @since_tizen 3.0
1883  * @param[in] player The handle to the media player
1884  * @param[in] timeout The time out time of muse-server
1885  * @return @c 0 on success,
1886  *         otherwise a negative error value
1887  * @retval  #PLAYER_ERROR_NONE Successful
1888  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1889  * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1890  */
1891 int legacy_player_get_timeout_for_muse(legacy_player_h player, int *timeout);
1892
1893 /**
1894  * @brief Gets number of video out buffers
1895  * @since_tizen 3.0
1896  * @param[in] player The handle to the media player
1897  * @param[in] num The number of video buffer
1898  * @param[in] extra_num The number of extra video buffer
1899  * @return @c 0 on success,
1900  *         otherwise a negative error value
1901  * @retval  #PLAYER_ERROR_NONE Successful
1902  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1903  * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1904  */
1905 int legacy_player_get_num_of_video_out_buffers(legacy_player_h player, int *num, int *extra_num);
1906
1907 /**
1908  * @brief Retrieves all the streaming variant information.
1909  * @since_tizen 4.0
1910  * @remarks This API is used for adaptive streaming(hls/mpeg dash) only.
1911  * @param[in] player The handle to the media player
1912  * @param[out] num The number of the variant list
1913  * @param[out] var_info The string value which includes variant information.
1914  * @return @c 0 on success,
1915  *         otherwise a negative error value
1916  * @retval #PLAYER_ERROR_NONE Successful
1917  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1918  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1919  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1920  * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
1921  * @see player_adaptive_variant_cb
1922  */
1923 int legacy_player_get_adaptive_variant_info(legacy_player_h player, int *num, char **var_info);
1924
1925 /**
1926  * @brief Sets the maximum limit of the streaming variant.
1927  * @since_tizen 4.0
1928  * @remarks This API is used for adaptive streaming(hls/mpeg dash) only.
1929  * @remarks The bandwidth setting can only be applied if there is no width, height information at streaming variant header.
1930  *          Application can get all the variant information by calling player_foreach_adaptive_variant() function.
1931  * @remarks If there is no affordable stream for the condition, the minimum bandwidth stream will be selected.
1932  * @param[in] player The handle to the media player
1933  * @param[in] bandwidth The max bandwidth limit of the stream variant (default: -1)
1934  * @param[in] width The max width limit of the stream variant (deafult: -1)
1935  * @param[in] height The max height limit of the stream variant (deafult: -1)
1936  * @return @c 0 on success,
1937  *         otherwise a negative error value
1938  * @retval #PLAYER_ERROR_NONE Successful
1939  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1940  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1941  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1942  * @see legacy_player_get_adaptive_variant_info()
1943  * @see legacy_player_get_max_adaptive_variant_limit()
1944  */
1945 int legacy_player_set_max_adaptive_variant_limit(legacy_player_h player, int bandwidth, int width, int height);
1946
1947 /**
1948  * @brief Gets the maximum limit of the streaming variant.
1949  * @since_tizen 4.0
1950  * @remarks This API is used for adaptive streaming(hls/mpeg dash) only.
1951  * @param[in] player The handle to the media player
1952  * @param[out] bandwidth The max bandwidth limit of the stream variant (default: -1)
1953  * @param[out] width The max width limit of the stream variant (deafult: -1)
1954  * @param[out] height The max height limit of the stream variant (deafult: -1)
1955  * @return @c 0 on success,
1956  *         otherwise a negative error value
1957  * @retval #PLAYER_ERROR_NONE Successful
1958  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1959  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1960  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1961  * @see legacy_player_get_adaptive_variant_info()
1962  * @see legacy_player_set_max_adaptive_variant_limit()
1963  */
1964 int legacy_player_get_max_adaptive_variant_limit(legacy_player_h player, int *bandwidth, int *width, int *height);
1965
1966 /**
1967  * @brief Checks user callback lock
1968  * @since_tizen 3.0
1969  * @param[in] type The event type of player
1970  * @return @c 1 on success, 0 on failure
1971  */
1972 bool _check_enabled_user_cb_lock(int event_id);
1973
1974 /**
1975  * @brief Sets the audio only mode.
1976  * @since_tizen 4.0
1977  * @details This function is used to disable or enable video rendering during playback.
1978  * @param[in] player       The handle to the media player
1979  * @param[in] audio_only   The new audio only status: (@c true = enable audio only, @c false = disable audio only)
1980  * @return @c 0 on success,
1981  *         otherwise a negative error value
1982  * @retval #PLAYER_ERROR_NONE                Successful
1983  * @retval #PLAYER_ERROR_INVALID_PARAMETER   Invalid parameter
1984  * @retval #PLAYER_ERROR_INVALID_OPERATION   Invalid operation
1985  * @retval #PLAYER_ERROR_INVALID_STATE       Invalid player state
1986  * @pre The player state must be one of: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1987  * @see player_is_audio_only()
1988  */
1989 int legacy_player_set_audio_only(legacy_player_h player, bool audio_only);
1990
1991 /**
1992  * @brief Gets the audio only mode status.
1993  * @since_tizen 4.0
1994  * @param[in]  player      The handle to the media player
1995  * @param[out] paudio_only  The current audio only status: (@c true = audio only enabled, @c false = audio only disabled)
1996  * @return @c 0 on success,
1997  *         otherwise a negative error value
1998  * @retval #PLAYER_ERROR_NONE                Successful
1999  * @retval #PLAYER_ERROR_INVALID_PARAMETER   Invalid parameter
2000  * @retval #PLAYER_ERROR_INVALID_OPERATION   Invalid operation
2001  * @pre The player state must be one of: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
2002  * @see player_set_audio_only()
2003  */
2004 int legacy_player_is_audio_only(legacy_player_h player, bool *paudio_only);
2005
2006 /* Set/Get the streaming buffering time */
2007 int legacy_player_set_streaming_buffering_time(legacy_player_h player, int prebuffer_ms, int rebuffer_ms);
2008 int legacy_player_get_streaming_buffering_time(legacy_player_h player, int *prebuffer_ms, int *rebuffer_ms);
2009
2010 /* 360 video display */
2011 int legacy_player_360_is_content_spherical(legacy_player_h player, bool *is_spherical);
2012 int legacy_player_360_set_enabled(legacy_player_h player, bool enabled);
2013 int legacy_player_360_is_enabled(legacy_player_h player, bool *enabled);
2014 int legacy_player_360_set_direction_of_view(legacy_player_h player, float yaw, float pitch);
2015 int legacy_player_360_get_direction_of_view(legacy_player_h player, float *yaw, float *pitch);
2016 int legacy_player_360_set_zoom(legacy_player_h player, float level);
2017 int legacy_player_360_get_zoom(legacy_player_h player, float *level);
2018 int legacy_player_360_set_field_of_view(legacy_player_h player, int horizontal_degrees, int vertical_degrees);
2019 int legacy_player_360_get_field_of_view(legacy_player_h player, int *horizontal_degrees, int *vertical_degrees);
2020 int legacy_player_set_replaygain_enabled(legacy_player_h player, bool enabled);
2021 int legacy_player_is_replaygain_enabled(legacy_player_h player, bool *enabled);
2022
2023 /* audio offload */
2024 int legacy_player_set_audio_offload_enabled(legacy_player_h player, bool enabled);
2025 int legacy_player_is_audio_offload_enabled(legacy_player_h player, bool *enabled);
2026
2027 /* audio pitch */
2028 int legacy_player_pitch_set_enabled(legacy_player_h player, bool enabled);
2029 int legacy_player_pitch_is_enabled(legacy_player_h player, bool *enabled);
2030 int legacy_player_pitch_set_value(legacy_player_h player, float pitch);
2031 int legacy_player_pitch_get_value(legacy_player_h player, float *pitch);
2032
2033 #ifdef __cplusplus
2034 }
2035 #endif
2036
2037 #endif /* __TIZEN_MEDIA_LEGACY_PLAYER_H__ */