include/player.h

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