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