2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __TIZEN_MEDIA_PLAYER_H__
18 #define __TIZEN_MEDIA_PLAYER_H__
21 #include <sound_manager.h>
22 #include <media_packet.h>
29 * @brief The player error class define.
30 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
32 #define PLAYER_ERROR_CLASS TIZEN_ERROR_PLAYER | 0x20
35 * @brief The player custom error class define.
38 #define PLAYER_CUSTOM_ERROR_CLASS TIZEN_ERROR_PLAYER | 0x1000
42 * @brief This file contains the media player API.
46 * @addtogroup CAPI_MEDIA_PLAYER_MODULE
51 * @brief The media player's type handle.
52 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
54 typedef struct player_s *player_h;
57 * @brief Enumeration for media player state.
58 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
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 */
69 * @brief Enumeration for media player's error codes.
70 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
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) */
101 * @brief Enumeration for media player's interruption type.
102 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
105 PLAYER_INTERRUPTED_BY_RESOURCE_CONFLICT = 4, /**< Interrupted by a resource conflict and the player handle will be paused or unprepared */
106 } player_interrupted_code_e;
109 * @brief Enumeration for display type.
110 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
113 PLAYER_DISPLAY_TYPE_OVERLAY = 0, /**< Overlay surface display */
114 PLAYER_DISPLAY_TYPE_EVAS = 3, /**< Evas image object surface display (Since 4.0) */
115 PLAYER_DISPLAY_TYPE_NONE = 4, /**< This disposes of buffers (Since 4.0) */
116 } player_display_type_e;
119 * @brief Enumeration for audio latency mode.
120 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
123 AUDIO_LATENCY_MODE_LOW = 0, /**< Low audio latency mode */
124 AUDIO_LATENCY_MODE_MID, /**< Middle audio latency mode */
125 AUDIO_LATENCY_MODE_HIGH, /**< High audio latency mode */
126 } audio_latency_mode_e;
129 * @brief Enumeration for stream type.
130 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
133 PLAYER_STREAM_TYPE_DEFAULT, /**< Container type */
134 PLAYER_STREAM_TYPE_AUDIO, /**< Audio element stream type */
135 PLAYER_STREAM_TYPE_VIDEO, /**< Video element stream type */
136 PLAYER_STREAM_TYPE_TEXT, /**< Text type */
137 } player_stream_type_e;
140 * @brief Enumeration of media stream buffer status.
141 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
142 * @see player_set_media_stream_buffer_max_size()
143 * @see player_set_media_stream_buffer_min_threshold()
146 PLAYER_MEDIA_STREAM_BUFFER_UNDERRUN, /**< The buffer level is lower than the threshold */
147 PLAYER_MEDIA_STREAM_BUFFER_OVERFLOW, /**< The buffer level is over than the threshold */
148 } player_media_stream_buffer_status_e;
155 * @addtogroup CAPI_MEDIA_PLAYER_DISPLAY_MODULE
160 * @brief The player display handle.
161 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
163 typedef void *player_display_h;
167 * @brief Definition for a display handle from evas object.
168 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
170 #define GET_DISPLAY(x) (void *)(x)
174 * @brief Enumeration for display rotation type.
175 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
178 PLAYER_DISPLAY_ROTATION_NONE, /**< Display is not rotated */
179 PLAYER_DISPLAY_ROTATION_90, /**< Display is rotated 90 degrees */
180 PLAYER_DISPLAY_ROTATION_180, /**< Display is rotated 180 degrees */
181 PLAYER_DISPLAY_ROTATION_270, /**< Display is rotated 270 degrees */
182 } player_display_rotation_e;
185 * @brief Enumeration for display mode.
186 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
189 PLAYER_DISPLAY_MODE_LETTER_BOX = 0, /**< Letter box */
190 PLAYER_DISPLAY_MODE_ORIGIN_SIZE, /**< Origin size */
191 PLAYER_DISPLAY_MODE_FULL_SCREEN, /**< Full-screen */
192 PLAYER_DISPLAY_MODE_CROPPED_FULL, /**< Cropped full-screen */
193 PLAYER_DISPLAY_MODE_ORIGIN_OR_LETTER, /**< Origin size (if surface size is larger than video size(width/height)) or Letter box (if video size(width/height) is larger than surface size) */
194 PLAYER_DISPLAY_MODE_DST_ROI, /**< Dst ROI mode */
195 PLAYER_DISPLAY_MODE_NUM
196 } player_display_mode_e;
203 * @addtogroup CAPI_MEDIA_PLAYER_STREAM_INFO_MODULE
208 * @brief Enumeration for media stream content information.
209 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
212 PLAYER_CONTENT_INFO_ALBUM, /**< Album */
213 PLAYER_CONTENT_INFO_ARTIST, /**< Artist */
214 PLAYER_CONTENT_INFO_AUTHOR, /**< Author */
215 PLAYER_CONTENT_INFO_GENRE, /**< Genre */
216 PLAYER_CONTENT_INFO_TITLE, /**< Title */
217 PLAYER_CONTENT_INFO_YEAR, /**< Year */
218 } player_content_info_e;
226 * @addtogroup CAPI_MEDIA_PLAYER_SUBTITLE_MODULE
231 * @brief Called when the subtitle is updated.
232 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
233 * @remarks The @a text should not be released and it can be used only in the callback.
234 * To use outside, make a copy.
235 * @param[in] duration The duration of the updated subtitle
236 * @param[in] text The text of the updated subtitle
237 * @param[in] user_data The user data passed from the callback registration function
238 * @see player_set_subtitle_updated_cb()
239 * @see player_unset_subtitle_updated_cb()
241 typedef void (*player_subtitle_updated_cb)(unsigned long duration, char *text, void *user_data);
248 * @addtogroup CAPI_MEDIA_PLAYER_MODULE
253 * @brief Called when the media player is prepared.
254 * @details It will be invoked when player has reached the begin of stream.
255 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
256 * @param[in] user_data The user data passed from the callback registration function
257 * @pre player_prepare_async() will cause this callback.
258 * @post The player state will be #PLAYER_STATE_READY.
259 * @see player_prepare_async()
261 typedef void (*player_prepared_cb)(void *user_data);
264 * @brief Called when the media player is completed.
265 * @details It will be invoked when player has reached the end of the stream.
266 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
267 * @param[in] user_data The user data passed from the callback registration function
268 * @pre It will be invoked when the playback is completed if you register this callback using player_set_completed_cb().
269 * @see player_set_completed_cb()
270 * @see player_unset_completed_cb()
272 typedef void (*player_completed_cb)(void *user_data);
275 * @brief Called when the seek operation is completed.
276 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
277 * @param[in] user_data The user data passed from the callback registration function
278 * @see player_set_play_position()
279 * @see player_set_play_position_nsec()
281 typedef void (*player_seek_completed_cb)(void *user_data);
284 * @brief Called when the media player is interrupted.
285 * @details If the code is #PLAYER_INTERRUPTED_BY_RESOURCE_CONFLICT,
286 * the player state will be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, or #PLAYER_STATE_PAUSED.
287 * Application should get exact state by calling player_get_state().
288 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
289 * @param[in] code The interrupted error code
290 * @param[in] user_data The user data passed from the callback registration function
291 * @see player_set_interrupted_cb()
292 * @see player_unset_interrupted_cb()
293 * @see player_get_state()
295 typedef void (*player_interrupted_cb)(player_interrupted_code_e code, void *user_data);
298 * @brief Called when an error occurs in the media player.
299 * @details Following error codes can be delivered.
300 * #PLAYER_ERROR_INVALID_OPERATION
301 * #PLAYER_ERROR_INVALID_STATE
302 * #PLAYER_ERROR_INVALID_URI
303 * #PLAYER_ERROR_CONNECTION_FAILED
304 * #PLAYER_ERROR_DRM_NOT_PERMITTED
305 * #PLAYER_ERROR_FILE_NO_SPACE_ON_DEVICE
306 * #PLAYER_ERROR_NOT_SUPPORTED_FILE
307 * #PLAYER_ERROR_SEEK_FAILED
308 * #PLAYER_ERROR_SERVICE_DISCONNECTED
309 * #PLAYER_ERROR_NOT_SUPPORTED_AUDIO_CODEC (Since 4.0)
310 * #PLAYER_ERROR_NOT_SUPPORTED_VIDEO_CODEC (Since 4.0)
311 * #PLAYER_ERROR_NOT_SUPPORTED_SUBTITLE (Since 4.0)
312 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
313 * @param[in] error_code The error code
314 * @param[in] user_data The user data passed from the callback registration function
315 * @see player_set_error_cb()
316 * @see player_unset_error_cb()
318 typedef void (*player_error_cb)(int error_code, void *user_data);
321 * @brief Called when the video is captured.
322 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
323 * @remarks The color space format of the captured image is IMAGE_UTIL_COLORSPACE_RGB888.
324 * @remarks The @a captured_data should not be released and it can be used only in the callback.
325 * To use outside, make a copy.
326 * @param[in] captured_data The captured image buffer
327 * @param[in] width The width of the captured image
328 * @param[in] height The height of the captured image
329 * @param[in] size The size of the captured image
330 * @param[in] user_data The user data passed from the callback registration function
331 * @see player_capture_video()
333 typedef void (*player_video_captured_cb)(unsigned char *captured_data, int width, int height, unsigned int size, void *user_data);
336 * @brief Called to register for notifications about delivering media packet when every video frame is decoded.
337 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
338 * @remarks The UI update code must not be directly invoked.\n
339 * @remarks The @a packet should be released using media_packet_destroy(). \n
340 * If not, the decoder will fail due to having insufficient buffer space for the decoded frame.
342 * @param[in] packet Reference pointer to the media packet
343 * @param[in] user_data The user data passed from the callback registration function
345 typedef void (*player_media_packet_video_decoded_cb)(media_packet_h packet, void *user_data);
348 * @brief Called when the buffer level drops below the threshold of max size or no free space in buffer.
349 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
350 * @remarks This function is used for media stream playback only.
351 * @param[in] status The buffer status
352 * @param[in] user_data The user data passed from the callback registration function
353 * @see player_set_media_stream_buffer_status_cb()
354 * @see player_set_media_stream_buffer_max_size()
355 * @see player_set_media_stream_buffer_min_threshold()
357 typedef void (*player_media_stream_buffer_status_cb)(player_media_stream_buffer_status_e status, void *user_data);
360 * @brief Called to notify the next push-buffer offset when seeking is occurred.
361 * @details The next push-buffer should produce buffers from the new offset.
362 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
363 * @remarks This function is used for media stream playback only.
364 * @param[in] offset The new byte position to seek
365 * @param[in] user_data The user data passed from the callback registration function
367 typedef void (*player_media_stream_seek_cb)(unsigned long long offset, void *user_data);
374 * @addtogroup CAPI_MEDIA_PLAYER_STREAM_INFO_MODULE
379 * @brief Called to notify the video stream changed.
380 * @details The video stream changing is detected just before rendering operation.
381 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
382 * @param[in] width The width of the captured image
383 * @param[in] height The height of the captured image
384 * @param[in] fps The frame per second of the video \n
385 * It can be @c 0 if there is no video stream information.
386 * @param[in] bit_rate The video bit rate [Hz] \n
387 * It can be an invalid value if there is no video stream information.
388 * @param[in] user_data The user data passed from the callback registration function
389 * @see player_set_video_stream_changed_cb()
391 typedef void (*player_video_stream_changed_cb)(int width, int height, int fps, int bit_rate, void *user_data);
398 * @addtogroup CAPI_MEDIA_PLAYER_STREAMING_MODULE
403 * @brief Called when the buffering percentage of the media playback is updated.
404 * @details If the buffer is full, it will return 100%.
405 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
406 * @param[in] percent The percentage of buffering completed (0~100)
407 * @param[in] user_data The user data passed from the callback registration function
408 * @see player_set_buffering_cb()
409 * @see player_unset_buffering_cb()
411 typedef void (*player_buffering_cb)(int percent, void *user_data);
414 * @brief Called to notify the streaming variant information.
415 * @details The adaptive streaming protocol(hls, mpeg dash) can support variant stream condition.
416 * All the streaming variant information can be shared by calling player_foreach_adaptive_variant().
418 * @param[in] bandwidth The bandwidth of the stream can be supportable, this is mandatory parameter
419 * @param[in] width The width of the stream, this is optional parameter
420 * @param[in] height The height of the stream, this is optional parameter
421 * @param[in] user_data The user data passed from the callback registration function
422 * @see player_foreach_adaptive_variant()
424 typedef void (*player_adaptive_variant_cb)(int bandwidth, int width, int height, void *user_data);
431 * @addtogroup CAPI_MEDIA_PLAYER_MODULE
436 * @brief Creates a player handle for playing multimedia content.
437 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
438 * @remarks You must release @a player by using player_destroy().\n
439 * Although you can create multiple player handles at the same time,
440 * the player cannot guarantee proper operation because of limited resources, such as
441 * audio or display device.
443 * @param[out] player A new handle to the media player
444 * @return @c 0 on success,
445 * otherwise a negative error value
446 * @retval #PLAYER_ERROR_NONE Successful
447 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
448 * @retval #PLAYER_ERROR_OUT_OF_MEMORY Out of memory
449 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
450 * @retval #PLAYER_ERROR_RESOURCE_LIMIT Cannot create more instance due to resource(socket, thread, etc) limitation on system.
451 * @post The player state will be #PLAYER_STATE_IDLE.
452 * @see player_destroy()
454 int player_create(player_h *player);
457 * @brief Destroys the media player handle and releases all its resources.
458 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
459 * @remarks To completely shutdown player operation, call this function with a valid player handle from any player state.
460 * @param[in] player The handle to the media player to be destroyed
461 * @return @c 0 on success,
462 * otherwise a negative error value
463 * @retval #PLAYER_ERROR_NONE Successful
464 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
465 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
466 * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
467 * @post The player state will be #PLAYER_STATE_NONE.
468 * @see player_create()
470 int player_destroy(player_h player);
473 * @brief Prepares the media player for playback.
474 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
475 * @remarks The mediastorage privilege(http://tizen.org/privilege/mediastorage) must be added if any video/audio files are used to play located in the internal storage.
476 * @remarks The externalstorage privilege(http://tizen.org/privilege/externalstorage) must be added if any video/audio files are used to play located in the external storage.
477 * @remarks The internet privilege(http://tizen.org/privilege/internet) must be added if any URLs are used to play from network.
478 * @param[in] player The handle to the media player
479 * @return @c 0 on success,
480 * otherwise a negative error value
481 * @retval #PLAYER_ERROR_NONE Successful
482 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
483 * @retval #PLAYER_ERROR_INVALID_URI Invalid URI
484 * @retval #PLAYER_ERROR_NO_SUCH_FILE File not found
485 * @retval #PLAYER_ERROR_NOT_SUPPORTED_FILE File not supported
486 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
487 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
488 * @retval #PLAYER_ERROR_PERMISSION_DENIED Permission denied
489 * @retval #PLAYER_ERROR_NOT_SUPPORTED_AUDIO_CODEC Not support audio codec format (Since 4.0)
490 * @retval #PLAYER_ERROR_NOT_SUPPORTED_VIDEO_CODEC Not support video codec format (Since 4.0)
491 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare(). After that, call player_set_uri() to load the media content you want to play.
492 * @post The player state will be #PLAYER_STATE_READY.
493 * @see player_prepare_async()
494 * @see player_unprepare()
495 * @see player_set_uri()
497 int player_prepare(player_h player);
500 * @brief Prepares the media player for playback, asynchronously.
501 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
502 * @remarks The mediastorage privilege(http://tizen.org/privilege/mediastorage) must be added if any video/audio files are used to play located in the internal storage.
503 * The externalstorage privilege(http://tizen.org/privilege/externalstorage) must be added if any video/audio files are used to play located in the external storage.
504 * The internet privilege(http://tizen.org/privilege/internet) must be added if any URLs are used to play from network. \n
505 * Since 5.0: To cancel the asynchronous preparing, call player_unprepare() even in #PLAYER_STATE_IDLE state.
506 * @param[in] player The handle to the media player
507 * @param[in] callback The callback function to register
508 * @param[in] user_data The user data to be passed to the callback function
509 * @return @c 0 on success,
510 * otherwise a negative error value
511 * @retval #PLAYER_ERROR_NONE Successful
512 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
513 * @retval #PLAYER_ERROR_INVALID_URI Invalid URI
514 * @retval #PLAYER_ERROR_NO_SUCH_FILE File not found
515 * @retval #PLAYER_ERROR_NOT_SUPPORTED_FILE File not supported
516 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
517 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
518 * @retval #PLAYER_ERROR_PERMISSION_DENIED Permission denied
519 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare(). After that, call player_set_uri() to load the media content you want to play.
520 * @post It invokes player_prepared_cb() when playback is prepared.
521 * @see player_prepare()
522 * @see player_prepared_cb()
523 * @see player_unprepare()
524 * @see player_set_uri()
526 int player_prepare_async(player_h player, player_prepared_cb callback, void *user_data);
529 * @brief Resets the media player.
530 * @details The most recently used media is reset and no longer associated with the player.
531 * Playback is no longer possible. If you want to use the player again, you must set the data URI and call
532 * player_prepare() again.
533 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
534 * @param[in] player The handle to the media player
535 * @return @c 0 on success,
536 * otherwise a negative error value
537 * @retval #PLAYER_ERROR_NONE Successful
538 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
539 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
540 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
541 * @pre Before 5.0: The player state must be one of: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, #PLAYER_STATE_PAUSED. \n
542 * @pre Since 5.0: The player state must be one of: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, #PLAYER_STATE_PAUSED.
543 * #PLAYER_STATE_IDLE is allowed only if player preparation was started with player_prepare_async().
544 * @post The player state will be #PLAYER_STATE_IDLE.
545 * @see player_prepare()
547 int player_unprepare(player_h player);
550 * @brief Sets the data source (file-path, HTTP or RTSP URI) to use.
552 * @details Associates media contents, referred to by the URI, with the player.
553 * If the function call is successful, subsequent calls to player_prepare() and player_start() will start playing the media.
554 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
555 * @remarks If you use HTTP or RTSP, URI must start with "http://" or "rtsp://". The default protocol is "file://".
556 * If you provide an invalid URI, you won't receive an error message until you call player_start().
557 * @remarks This function must be called before calling the player_prepare() or player_prepare_async() to build the player based on the URI information.
558 * @remarks The mediastorage privilege(http://tizen.org/privilege/mediastorage) must be added if any video/audio files are used to play located in the internal storage.
559 * @remarks The externalstorage privilege(http://tizen.org/privilege/externalstorage) must be added if any video/audio files are used to play located in the external storage.
560 * @remarks The internet privilege(http://tizen.org/privilege/internet) must be added if any URLs are used to play from network.
562 * @param[in] player The handle to the media player
563 * @param[in] uri The content location, such as the file path, the URI of the HTTP or RTSP stream you want to play
565 * @return @c 0 on success,
566 * otherwise a negative error value
567 * @retval #PLAYER_ERROR_NONE Successful
568 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
569 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
570 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
571 * @retval #PLAYER_ERROR_PERMISSION_DENIED Permission denied
572 * @if WEARABLE @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature @endif
573 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
574 * @see player_set_memory_buffer()
576 int player_set_uri(player_h player, const char *uri);
579 * @brief Sets memory as the data source.
581 * @details Associates media content, cached in memory, with the player. Unlike the case of player_set_uri(), the media resides in memory.
582 * If the function call is successful, subsequent calls to player_prepare() and player_start() will start playing the media.
583 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
584 * @remarks If you provide an invalid data, you won't receive an error message until you call player_start().
585 * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
586 * to build the player based on the data.
588 * @param[in] player The handle to the media player
589 * @param[in] data The memory pointer of media data
590 * @param[in] size The size of media data
591 * @return @c 0 on success,
592 * otherwise a negative error value
593 * @retval #PLAYER_ERROR_NONE Successful
594 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
595 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
596 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
597 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
598 * @see player_set_uri()
600 int player_set_memory_buffer(player_h player, const void *data, int size);
603 * @brief Gets the player's current state.
604 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
605 * @param[in] player The handle to the media player
606 * @param[out] state The current state of the player
607 * @return @c 0 on success,
608 * otherwise a negative error value
609 * @retval #PLAYER_ERROR_NONE Successful
610 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
611 * @see #player_state_e
613 int player_get_state(player_h player, player_state_e *state);
616 * @brief Sets the player's volume.
617 * @details Setting this volume adjusts the player's instance volume, not the system volume.
618 * The valid range is from 0 to 1.0, inclusive (1.0 = 100%). Default value is 1.0.
619 * To change system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
620 * Finally, it does not support to set other value into each channel currently.
621 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
622 * @param[in] player The handle to the media player
623 * @param[in] left The left volume scalar
624 * @param[in] right The right volume scalar
625 * @return @c 0 on success,
626 * otherwise a negative error value
627 * @retval #PLAYER_ERROR_NONE Successful
628 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
629 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
630 * @see player_get_volume()
632 int player_set_volume(player_h player, float left, float right);
635 * @brief Gets the player's current volume factor.
636 * @details The range of @a left and @a right is from @c 0 to @c 1.0, inclusive (1.0 = 100%).
637 * This function gets the player volume, not the system volume.
638 * To get the system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
639 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
640 * @param[in] player The handle to the media player
641 * @param[out] left The current left volume scalar
642 * @param[out] right The current right volume scalar
643 * @return @c 0 on success,
644 * otherwise a negative error value
645 * @retval #PLAYER_ERROR_NONE Successful
646 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
647 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
648 * @see player_set_volume()
650 int player_get_volume(player_h player, float *left, float *right);
653 * @brief Sets the player's sound manager stream information.
655 * @remarks You can set sound stream information including audio routing and volume type.
656 * For more details, please refer to sound_manager.h
657 * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
658 * to reflect the sound stream information when the player is building.
659 * @remarks This function is related to the following feature:\n
660 * %http://tizen.org/feature/multimedia.player.stream_info\n
661 * If this feature is not supported, the stream_type of the player is fixed to the #SOUND_STREAM_TYPE_MEDIA.
662 * @param[in] player The handle to the media player
663 * @param[in] stream_info The sound manager info type
664 * @return @c 0 on success,
665 * otherwise a negative error value
666 * @retval #PLAYER_ERROR_NONE Successful
667 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
668 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
669 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
670 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
671 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create().
672 * @see #sound_stream_info_h
673 * @see sound_manager_create_stream_information()
674 * @see sound_manager_destroy_stream_information()
678 #include <sound_manager.h>
680 player_h player = NULL;
681 sound_stream_info_h stream_info = NULL;
682 sound_stream_type_e stream_type = SOUND_STREAM_TYPE_MEDIA;
684 sound_manager_create_stream_information (stream_type, _focus_callback, use_data, &stream_info);
685 player_create (&player);
686 player_set_sound_stream_info (player, stream_info);
688 player_prepare_async (player, _prepared_cb, udata);
692 int player_set_sound_stream_info(player_h player, sound_stream_info_h stream_info);
695 * @brief Sets the audio latency mode.
696 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
697 * @remarks The default audio latency mode of the player is #AUDIO_LATENCY_MODE_MID.
698 * To get the current audio latency mode, use player_get_audio_latency_mode().
699 * If it's high mode, audio output interval can be increased so, it can keep more audio data to play.
700 * But, state transition like pause or resume can be more slower than default(mid) mode.
702 * @param[in] player The handle to the media player
703 * @param[in] latency_mode The latency mode to be applied to the audio
704 * @return @c 0 on success,
705 * otherwise a negative error value
706 * @retval #PLAYER_ERROR_NONE Successful
707 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
708 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
709 * @see #audio_latency_mode_e
710 * @see player_get_audio_latency_mode()
712 int player_set_audio_latency_mode(player_h player, audio_latency_mode_e latency_mode);
715 * @brief Gets the current audio latency mode.
716 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
717 * @param[in] player The handle to the media player
718 * @param[out] latency_mode The latency mode to get from the audio
719 * @return @c 0 on success,
720 * otherwise a negative error value
721 * @retval #PLAYER_ERROR_NONE Successful
722 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
723 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
724 * @see #audio_latency_mode_e
725 * @see player_set_audio_latency_mode()
727 int player_get_audio_latency_mode(player_h player, audio_latency_mode_e *latency_mode);
730 * @brief Starts or resumes playback.
731 * @details Plays current media content, or resumes playback if the player is paused or buffering during HTTP streaming play.
732 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
733 * @remarks Even if you don't set visible to true by calling player_set_display_visible(), the video will be shown on #PLAYER_STATE_PLAYING state.
734 * @remarks Since 3.0: \n
735 * Sound can be mixed with other sounds, if you don't control the stream focus in sound-manager module.\n
736 * You can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE.
737 * @remarks Since 5.0: \n
738 * In case of HTTP streaming playback, the player could be internally paused for buffering.
739 * If the application calls this function during the buffering, the playback will be resumed by force
740 * and the buffering message posting by player_buffering_cb() will be stopped.
741 * @param[in] player The handle to the media player
742 * @return @c 0 on success,
743 * otherwise a negative error value
744 * @retval #PLAYER_ERROR_NONE Successful
745 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
746 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
747 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
748 * @retval #PLAYER_ERROR_CONNECTION_FAILED Network connection failed
749 * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
750 * @pre Before 5.0: The player state must be #PLAYER_STATE_READY or #PLAYER_STATE_PAUSED. \n
751 * @pre Since 5.0: The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
752 * @post The player state will be #PLAYER_STATE_PLAYING.
753 * @post It invokes player_completed_cb() when playback completes, if you set a callback with player_set_completed_cb().
754 * @see player_prepare()
755 * @see player_prepare_async()
757 * @see player_pause()
758 * @see player_set_completed_cb()
759 * @see player_completed_cb()
760 * @see player_set_display_visible()
761 * @see player_set_buffering_cb()
762 * @see player_buffering_cb()
764 int player_start(player_h player);
767 * @brief Stops playing media content.
768 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
769 * @param[in] player The handle to the media player
770 * @return @c 0 on success,
771 * otherwise a negative error value
772 * @retval #PLAYER_ERROR_NONE Successful
773 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid state
774 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
775 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
776 * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
777 * @pre The player state must be set to #PLAYER_STATE_PLAYING by calling player_start() or set to #PLAYER_STATE_PAUSED by calling player_pause().
778 * @post The player state will be #PLAYER_STATE_READY.
779 * @see player_start()
780 * @see player_pause()
782 int player_stop(player_h player);
785 * @brief Pauses the player.
786 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
787 * @remarks You can resume playback using player_start().
789 * @param[in] player The handle to the media player
790 * @return @c 0 on success,
791 * otherwise a negative error value
792 * @retval #PLAYER_ERROR_NONE Successful
793 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid state
794 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
795 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
796 * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
797 * @pre The player state must be set to #PLAYER_STATE_PLAYING.
798 * @post The player state will be #PLAYER_STATE_PAUSED.
799 * @see player_start()
801 int player_pause(player_h player);
804 * @brief Sets the seek position for playback, asynchronously.
805 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
806 * @remarks This function will trigger the seeking operation on player instance like in the case of player_set_play_position_nsec().
807 * Normally application needs to wait for player_seek_completed_cb() before calling setting position function again.
808 * Otherwise it will return #PLAYER_ERROR_SEEK_FAILED.
809 * @remarks Calling player_pause() or player_start() before player_seek_completed_cb() is invoked will cause #PLAYER_ERROR_INVALID_OPERATION to be returned.
810 * @remarks Please note that if application is playing external media data via player_set_media_stream_info(),
811 * then consecutive calling of this function will always succeed and there is no need to wait for player_seek_completed_cb()
812 * before next calling of this function.(since_tizen 3.0)
813 * @remarks Even if you don't set visible to true by calling player_set_display_visible(),
814 * the video will be shown when the player_seek_completed_cb() is invoked.
815 * @remarks In case of non-seekable content, the function will return #PLAYER_ERROR_INVALID_OPERATION
816 * and the player will keep playing without changing the play position.
817 * @param[in] player The handle to the media player
818 * @param[in] milliseconds The position in milliseconds from the start to the seek point
819 * @param[in] accurate If @c true the nearest frame position is returned, but this might be considerably slow,
820 * if @c false the nearest key frame position is returned, this might be faster but less accurate.
821 * @param[in] callback The callback function to register
822 * @param[in] user_data The user data to be passed to the callback function
823 * @return @c 0 on success,
824 * otherwise a negative error value
825 * @retval #PLAYER_ERROR_NONE Successful
826 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
827 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
828 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
829 * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
830 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
831 * @post It invokes player_seek_completed_cb() when seek operation completes, if you set a callback.
832 * @see player_get_play_position()
833 * @see player_set_play_position_nsec()
834 * @see player_get_play_position_nsec()
836 int player_set_play_position(player_h player, int milliseconds, bool accurate, player_seek_completed_cb callback, void *user_data);
839 * @brief Sets the seek position in nanoseconds for playback, asynchronously.
841 * @remarks This function will trigger the seeking operation on player instance like in the case of player_set_play_position().
842 * Normally application needs to wait for player_seek_completed_cb() before calling setting position function again.
843 * Otherwise it will return #PLAYER_ERROR_SEEK_FAILED.
844 * @remarks Calling player_pause() or player_start() before player_seek_completed_cb() is invoked will cause #PLAYER_ERROR_INVALID_OPERATION to be returned.
845 * @remarks Please note that if application is playing external media data via player_set_media_stream_info(),
846 * then consecutive calling of this function will always succeed and there is no need to wait for player_seek_completed_cb()
847 * before next calling of this function.
848 * @remarks Even if you don't set visible to true by calling player_set_display_visible(),
849 * the video will be shown when the player_seek_completed_cb() is invoked.
850 * @remarks In case of non-seekable content, the function will return #PLAYER_ERROR_INVALID_OPERATION
851 * and the player will keep playing without changing the play position.
852 * @param[in] player The handle to the media player
853 * @param[in] nanoseconds The position in nanoseconds from the start to the seek point
854 * @param[in] accurate If @c true the nearest frame position is returned, but this might be considerably slow,
855 * if @c false the nearest key frame position is returned, this might be faster but less accurate.
856 * @param[in] callback The callback function to register
857 * @param[in] user_data The user data to be passed to the callback function
858 * @return @c 0 on success,
859 * otherwise a negative error value
860 * @retval #PLAYER_ERROR_NONE Successful
861 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
862 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
863 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
864 * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
865 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
866 * @post It invokes player_seek_completed_cb() when seek operation completes, if you set a callback.
867 * @see player_set_play_position()
868 * @see player_get_play_position()
869 * @see player_get_play_position_nsec()
871 int player_set_play_position_nsec(player_h player, int64_t nanoseconds, bool accurate, player_seek_completed_cb callback, void *user_data);
874 * @brief Gets the current position in milliseconds.
875 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
876 * @param[in] player The handle to the media player
877 * @param[out] milliseconds The current position in milliseconds
878 * @return @c 0 on success,
879 * otherwise a negative error value
880 * @retval #PLAYER_ERROR_NONE Successful
881 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
882 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
883 * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
884 * @see player_set_play_position()
885 * @see player_set_play_position_nsec()
886 * @see player_get_play_position_nsec()
888 int player_get_play_position(player_h player, int *milliseconds);
891 * @brief Gets the current position in nanoseconds.
893 * @param[in] player The handle to the media player
894 * @param[out] nanoseconds The current position in nanoseconds
895 * @return @c 0 on success,
896 * otherwise a negative error value
897 * @retval #PLAYER_ERROR_NONE Successful
898 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
899 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
900 * @retval #PLAYER_ERROR_SEEK_FAILED Seek operation failure
901 * @see player_set_play_position()
902 * @see player_get_play_position()
903 * @see player_set_play_position_nsec()
905 int player_get_play_position_nsec(player_h player, int64_t *nanoseconds);
908 * @brief Sets the player's mute status.
909 * @details If the mute status is @c true, no sounds are played.
910 * If it is @c false, sounds are played at the previously set volume level.
911 * Until this function is called, by default the player is not muted.
912 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
913 * @param[in] player The handle to the media player
914 * @param[in] muted The new mute status: (@c true = mute, @c false = not muted)
915 * @return @c 0 on success,
916 * otherwise a negative error value
917 * @retval #PLAYER_ERROR_NONE Successful
918 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
919 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
920 * @see player_is_muted()
922 int player_set_mute(player_h player, bool muted);
925 * @brief Gets the player's mute status.
926 * @details If the mute status is @c true, no sounds are played.
927 * If it is @c false, sounds are played at the previously set volume level.
928 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
929 * @param[in] player The handle to the media player
930 * @param[out] muted The current mute status: (@c true = mute, @c false = not muted)
931 * @return @c 0 on success,
932 * otherwise a negative error value
933 * @retval #PLAYER_ERROR_NONE Successful
934 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
935 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
936 * @see player_set_mute()
938 int player_is_muted(player_h player, bool *muted);
941 * @brief Sets the player's looping status.
942 * @details If the looping status is @c true, playback automatically restarts upon finishing.
943 * If it is @c false, it won't. The default value is @c false.
944 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
945 * @param[in] player The handle to the media player
946 * @param[in] looping The new looping status: (@c true = looping, @c false = non-looping )
947 * @return @c 0 on success,
948 * otherwise a negative error value
949 * @retval #PLAYER_ERROR_NONE Successful
950 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
951 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
952 * @see player_is_looping()
954 int player_set_looping(player_h player, bool looping);
957 * @brief Gets the player's looping status.
958 * @details If the looping status is @c true, playback automatically restarts upon finishing.
959 * If it is @c false, it won't.
960 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
961 * @param[in] player The handle to the media player
962 * @param[out] looping The looping status: (@c true = looping, @c false = non-looping )
963 * @return @c 0 on success,
964 * otherwise a negative error value
965 * @retval #PLAYER_ERROR_NONE Successful
966 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
967 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
968 * @see player_set_looping()
970 int player_is_looping(player_h player, bool *looping);
973 * @brief Sets the video display.
974 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
975 * @remarks To get @a display to set, use #GET_DISPLAY().
976 * @remarks We are not supporting changing display.
977 * @remarks This function must be called before calling the player_prepare() or player_prepare_async() \n
978 * to reflect the display type.
979 * @remarks This function must be called in main thread of application.
980 * Otherwise, it will return #PLAYER_ERROR_INVALID_OPERATION by internal restriction.
981 * To avoid #PLAYER_ERROR_INVALID_OPERATION in sub thread, ecore_thread_main_loop_begin() and
982 * ecore_thread_main_loop_end() can be used, but deadlock can be also occurred if main thread is busy.
983 * So, it's not recommended to use them. (since 5.0)
984 * @param[in] player The handle to the media player
985 * @param[in] type The display type
986 * @param[in] display The handle to display
987 * @return @c 0 on success,
988 * otherwise a negative error value
989 * @retval #PLAYER_ERROR_NONE Successful
990 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
991 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
992 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
993 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
994 * @see #player_display_type_e
995 * @see player_set_display_mode()
996 * @see player_set_display_roi_area()
997 * @see player_set_display_visible()
998 * @see player_set_display_rotation()
999 * @see ecore_thread_main_loop_begin()
1000 * @see ecore_thread_main_loop_end()
1002 int player_set_display(player_h player, player_display_type_e type, player_display_h display);
1005 * @brief Sets a media packet video callback function to be called once per frame.
1006 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1007 * @remarks This function must be called before calling player_prepare() or player_prepare_async().\n
1008 * A registered callback is called in a separate thread (not in the main loop).\n
1009 * A video frame can be retrieved using a registered callback as a media packet.\n
1010 * The callback function holds the same buffer that will be drawn on the display device.\n
1011 * So if you change the media packet in a registered callback, it will be displayed on the device\n
1012 * and the media packet is available until it's destroyed by media_packet_destroy().\n
1013 * The packet have to be destroyed as quickly as possible after rendering the packet\n
1014 * and all the packets have to be destroyed before player_unprepare() is called.\n
1015 * @param[in] player The handle to the media player
1016 * @param[in] callback The callback function to be registered
1017 * @param[in] user_data The user data to be passed to the callback function
1018 * @return @c 0 on success,
1019 * otherwise a negative error value
1020 * @retval #PLAYER_ERROR_NONE Successful
1021 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1022 * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1023 * @pre The player's state must be #PLAYER_STATE_IDLE. And, #PLAYER_DISPLAY_TYPE_NONE must be set by calling player_set_display().
1024 * @see player_unset_media_packet_video_frame_decoded_cb()
1026 int player_set_media_packet_video_frame_decoded_cb(player_h player, player_media_packet_video_decoded_cb callback, void *user_data);
1029 * @brief Unsets the media packet video frame callback function.
1030 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1031 * @param[in] player The handle to the media player
1032 * @return @c 0 on success,
1033 * otherwise a negative error value
1034 * @retval #PLAYER_ERROR_NONE Successful
1035 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1036 * @pre The player's state must be #PLAYER_STATE_READY or #PLAYER_STATE_IDLE
1037 * @see player_set_media_packet_video_frame_decoded_cb()
1039 int player_unset_media_packet_video_frame_decoded_cb(player_h player);
1042 * @brief Pushes elementary stream to decode audio or video.
1043 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
1044 * @remarks player_set_media_stream_info() must be called before using this function.
1045 * @remarks The available buffer size can be set by calling player_set_media_stream_buffer_max_size().
1046 * If there is no available buffer space, this function will return error since 3.0.
1047 * @param[in] player The handle to media player
1048 * @param[in] packet The media packet to decode
1049 * @return @c 0 on success,
1050 * otherwise a negative error value
1051 * @retval #PLAYER_ERROR_NONE Successful
1052 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1053 * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1054 * @retval #PLAYER_ERROR_NOT_SUPPORTED_FILE File not supported
1055 * @retval #PLAYER_ERROR_BUFFER_SPACE No buffer space available (since 3.0)
1056 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation (since 3.0)
1057 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1058 * @see player_set_media_stream_info()
1059 * @see player_set_media_stream_buffer_max_size()
1061 int player_push_media_stream(player_h player, media_packet_h packet);
1064 * @brief Sets contents information for media stream.
1065 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
1066 * @remarks AV format must be set before pushing elementary stream with player_push_media_stream().
1067 * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
1068 * to reflect the media information.
1069 * @remarks AAC can be supported.
1070 * @remarks H.264 can be supported.
1071 * @param[in] player The handle to media player
1072 * @param[in] type The type of target stream
1073 * @param[in] format The media format to set audio information
1074 * @return @c 0 on success,
1075 * otherwise a negative error value
1076 * @retval #PLAYER_ERROR_NONE Successful
1077 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1078 * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
1079 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
1080 * @see player_push_media_stream()
1082 int player_set_media_stream_info(player_h player, player_stream_type_e type, media_format_h format);
1085 * @brief Sets a callback function to be invoked when buffer underrun or overflow is occurred.
1086 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
1087 * @remarks This function is used for media stream playback only.
1088 * @remarks The callback is called in a separate thread (not in the main loop).
1089 * @param[in] player The handle to the media player
1090 * @param[in] type The type of target stream
1091 * @param[in] callback The buffer status callback function to register
1092 * @param[in] user_data The user data to be passed to the callback function
1093 * @return @c 0 on success,
1094 * otherwise a negative error value
1095 * @retval #PLAYER_ERROR_NONE Successful
1096 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1097 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1098 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
1099 * @post player_media_stream_buffer_status_cb() will be invoked.
1100 * @see player_unset_media_stream_buffer_status_cb()
1101 * @see player_media_stream_buffer_status_cb()
1103 int player_set_media_stream_buffer_status_cb(player_h player, player_stream_type_e type, player_media_stream_buffer_status_cb callback, void *user_data);
1106 * @brief Unsets the buffer status callback function.
1107 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
1108 * @remarks This function is used for media stream playback only.
1109 * @param[in] player The handle to the media player
1110 * @param[in] type The type of target stream
1111 * @return @c 0 on success,
1112 * otherwise a negative error value
1113 * @retval #PLAYER_ERROR_NONE Successful
1114 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1115 * @see player_set_media_stream_buffer_status_cb()
1117 int player_unset_media_stream_buffer_status_cb(player_h player, player_stream_type_e type);
1120 * @brief Sets a callback function to be invoked when seeking is occurred.
1121 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
1122 * @remarks This function is used for media stream playback only.
1123 * @remarks The callback is called in a separate thread (not in the main loop).
1124 * @param[in] player The handle to the media player
1125 * @param[in] type The type of target stream
1126 * @param[in] callback The callback function to register
1127 * @param[in] user_data The user data to be passed to the callback function
1128 * @return @c 0 on success,
1129 * otherwise a negative error value
1130 * @retval #PLAYER_ERROR_NONE Successful
1131 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1132 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1133 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
1134 * @post player_media_stream_seek_cb() will be invoked.
1135 * @see player_unset_media_stream_seek_cb()
1136 * @see player_media_stream_seek_cb()
1138 int player_set_media_stream_seek_cb(player_h player, player_stream_type_e type, player_media_stream_seek_cb callback, void *user_data);
1141 * @brief Unsets the seek callback function.
1142 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
1143 * @param[in] player The handle to the media player
1144 * @param[in] type The type of target stream
1145 * @return @c 0 on success,
1146 * otherwise a negative error value
1147 * @retval #PLAYER_ERROR_NONE Successful
1148 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1149 * @see player_set_media_stream_seek_cb()
1151 int player_unset_media_stream_seek_cb(player_h player, player_stream_type_e type);
1154 * @brief Sets the max size bytes of buffer.
1155 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
1156 * @remarks This function is used for media stream playback only.
1157 * @remarks If the buffer level over the max size, player_media_stream_buffer_status_cb() will be invoked with overflow status.
1158 * @param[in] player The handle to the media player
1159 * @param[in] type The type of target stream
1160 * @param[in] max_size The max bytes of buffer, it has to be bigger than zero. (default: 200000)
1161 * @return @c 0 on success,
1162 * otherwise a negative error value
1163 * @retval #PLAYER_ERROR_NONE Successful
1164 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1165 * @see player_get_media_stream_buffer_max_size()
1166 * @see player_media_stream_buffer_status_cb()
1168 int player_set_media_stream_buffer_max_size(player_h player, player_stream_type_e type, unsigned long long max_size);
1171 * @brief Gets the max size bytes of buffer.
1172 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
1173 * @remarks This function is used for media stream playback only.
1174 * @remarks If the buffer level over the max size, player_media_stream_buffer_status_cb() will be invoked with overflow status.
1175 * @param[in] player The handle to the media player
1176 * @param[in] type The type of target stream
1177 * @param[out] max_size The max bytes of buffer
1178 * @return @c 0 on success,
1179 * otherwise a negative error value
1180 * @retval #PLAYER_ERROR_NONE Successful
1181 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1182 * @see player_set_media_stream_buffer_max_size()
1183 * @see player_media_stream_buffer_status_cb()
1185 int player_get_media_stream_buffer_max_size(player_h player, player_stream_type_e type, unsigned long long *max_size);
1188 * @brief Sets the buffer threshold percent of buffer.
1189 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
1190 * @remarks This function is used for media stream playback only.
1191 * @remarks If the buffer level drops below the percent value, player_media_stream_buffer_status_cb() will be invoked with underrun status.
1192 * @param[in] player The handle to the media player
1193 * @param[in] type The type of target stream
1194 * @param[in] percent The minimum threshold(0~100) of buffer (default: 0)
1195 * @return @c 0 on success,
1196 * otherwise a negative error value
1197 * @retval #PLAYER_ERROR_NONE Successful
1198 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1199 * @see player_get_media_stream_buffer_min_threshold()
1200 * @see player_media_stream_buffer_status_cb()
1202 int player_set_media_stream_buffer_min_threshold(player_h player, player_stream_type_e type, unsigned int percent);
1205 * @brief Gets the buffer threshold percent of buffer.
1206 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
1207 * @remarks This function is used for media stream playback only.
1208 * @remarks If the buffer level drops below the percent value, player_media_stream_buffer_status_cb() will be invoked with underrun status.
1209 * @param[in] player The handle to the media player
1210 * @param[in] type The type of target stream
1211 * @param[out] percent The minimum threshold(0~100) of buffer
1212 * @return @c 0 on success,
1213 * otherwise a negative error value
1214 * @retval #PLAYER_ERROR_NONE Successful
1215 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1216 * @see player_set_media_stream_buffer_min_threshold()
1217 * @see player_media_stream_buffer_status_cb()
1219 int player_get_media_stream_buffer_min_threshold(player_h player, player_stream_type_e type, unsigned int *percent);
1226 * @addtogroup CAPI_MEDIA_PLAYER_DISPLAY_MODULE
1231 * @brief Sets the video display mode.
1232 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1233 * @remarks If no display is set, no operation is performed.
1234 * @param[in] player The handle to the media player
1235 * @param[in] mode The display mode
1236 * @return @c 0 on success,
1237 * otherwise a negative error value
1238 * @retval #PLAYER_ERROR_NONE Successful
1239 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1240 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1241 * @see #player_display_mode_e
1242 * @see player_set_display()
1243 * @see player_get_display_mode()
1245 int player_set_display_mode(player_h player, player_display_mode_e mode);
1248 * @brief Gets the video display mode.
1249 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1250 * @remarks If no display is set, no operation is performed.
1251 * @param[in] player The handle to the media player
1252 * @param[out] mode The current display mode
1253 * @return @c 0 on success,
1254 * otherwise a negative error value
1255 * @retval #PLAYER_ERROR_NONE Successful
1256 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1257 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1258 * @see #player_display_mode_e
1259 * @see player_set_display_mode()
1261 int player_get_display_mode(player_h player, player_display_mode_e *mode);
1264 * @brief Sets the ROI (Region Of Interest) area of display.
1266 * @remarks If no display is set, no operation is performed and
1267 * the ROI area is valid only in #PLAYER_DISPLAY_MODE_DST_ROI display mode.
1268 * @remarks The minimum value of width and height are 1.
1269 * @remarks ROI area can be set before setting ROI display mode. (since 4.0)
1270 * @param[in] player The handle to the media player
1271 * @param[in] x X coordinate of area
1272 * @param[in] y Y coordinate of area
1273 * @param[in] width Width of area
1274 * @param[in] height Height of area
1275 * @return @c 0 on success,
1276 * otherwise a negative error value
1277 * @retval #PLAYER_ERROR_NONE Successful
1278 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1279 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1280 * @see player_set_display()
1281 * @see player_set_display_mode()
1283 int player_set_display_roi_area(player_h player, int x, int y, int width, int height);
1286 * @brief Sets the visibility of the video display.
1287 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1288 * @remarks If no display is set, no operation is performed.
1289 * @remarks If you set visible before calling player_set_display(), it will be applied on #PLAYER_STATE_READY state.
1290 * @param[in] player The handle to the media player
1291 * @param[in] visible The visibility of the display (@c true = visible, @c false = non-visible )
1292 * @return @c 0 on success,
1293 * otherwise a negative error value
1294 * @retval #PLAYER_ERROR_NONE Successful
1295 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1296 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1297 * @see player_set_display()
1298 * @see player_is_display_visible()
1300 int player_set_display_visible(player_h player, bool visible);
1303 * @brief Gets the visibility of the video display.
1304 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1305 * @param[in] player The handle to the media player
1306 * @param[out] visible The current visibility of the display (@c true = visible, @c false = non-visible )
1307 * @return @c 0 on success,
1308 * otherwise a negative error value
1309 * @retval #PLAYER_ERROR_NONE Successful
1310 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1311 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1312 * @see player_set_display_visible()
1314 int player_is_display_visible(player_h player, bool *visible);
1317 * @brief Sets the rotation settings of the video surface display.
1318 * @details Use this function to change the video orientation to portrait mode.
1319 * The video out will be rotated in a counterclockwise direction.
1320 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1321 * @remarks If no display is set, no operation is performed.
1322 * @param[in] player The handle to the media player
1323 * @param[in] rotation The rotation of the display
1324 * @return @c 0 on success,
1325 * otherwise a negative error value
1326 * @retval #PLAYER_ERROR_NONE Successful
1327 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1328 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1329 * @see #player_display_rotation_e
1330 * @see player_set_display()
1331 * @see player_get_display_rotation()
1333 int player_set_display_rotation(player_h player, player_display_rotation_e rotation);
1336 * @brief Gets the rotation of the video surface display.
1337 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1338 * @param[in] player The handle to the media player
1339 * @param[out] rotation The current rotation of the display
1340 * @return @c 0 on success,
1341 * otherwise a negative error value
1342 * @retval #PLAYER_ERROR_NONE Successful
1343 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1344 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1345 * @see #player_display_rotation_e
1346 * @see player_set_display_rotation()
1348 int player_get_display_rotation(player_h player, player_display_rotation_e *rotation);
1356 * @addtogroup CAPI_MEDIA_PLAYER_STREAM_INFO_MODULE
1361 * @brief Gets the media content information.
1362 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1363 * @remarks You must release @a value using @c free().
1364 * @remarks The playback type should be local playback or HTTP streaming playback.
1365 * @param[in] player The handle to the media player
1366 * @param[in] key The key attribute name to get
1367 * @param[out] value The value of the key attribute \n
1368 * It can be an empty string if there is no content information.
1369 * @return @c 0 on success,
1370 * otherwise a negative error value
1371 * @retval #PLAYER_ERROR_NONE Successful
1372 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1373 * @retval #PLAYER_ERROR_OUT_OF_MEMORY Not enough memory is available
1374 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1375 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1376 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1378 int player_get_content_info(player_h player, player_content_info_e key, char **value);
1381 * @brief Gets the audio and video codec information.
1382 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1383 * @remarks You must release @a audio_codec and @a video_codec using free().
1384 * @remarks The playback type should be local playback or HTTP streaming playback.
1385 * @param[in] player The handle to the media player
1386 * @param[out] audio_codec The name of the audio codec \n
1387 * It can be @c NULL if there is no audio codec.
1388 * @param[out] video_codec The name of the video codec \n
1389 * It can be @c NULL if there is no video codec.
1390 * @return @c 0 on success,
1391 * otherwise a negative error value
1392 * @retval #PLAYER_ERROR_NONE Successful
1393 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1394 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1395 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1396 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1398 int player_get_codec_info(player_h player, char **audio_codec, char **video_codec);
1401 * @brief Gets the audio stream information.
1402 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1403 * @remarks The playback type should be local playback or HTTP streaming playback.
1404 * @param[in] player The handle to the media player
1405 * @param[out] sample_rate The audio sample rate [Hz] \n
1406 * Value can be invalid if there is no audio stream information.
1407 * @param[out] channel The audio channel (1: mono, 2: stereo) \n
1408 * Value can be invalid if there is no audio stream information.
1409 * @param[out] bit_rate The audio bit rate [Hz] \n
1410 * Value can be invalid if there is no audio stream information.
1411 * @return @c 0 on success,
1412 * otherwise a negative error value
1413 * @retval #PLAYER_ERROR_NONE Successful
1414 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1415 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1416 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1417 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1419 int player_get_audio_stream_info(player_h player, int *sample_rate, int *channel, int *bit_rate);
1422 * @brief Gets the video stream information.
1423 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1424 * @remarks The playback type should be local playback or HTTP streaming playback.
1425 * @param[in] player The handle to the media player
1426 * @param[out] fps The frame per second of the video \n
1427 * It can be @c 0 if there is no video stream information.
1428 * @param[out] bit_rate The video bit rate [Hz] \n
1429 * It can be an invalid value if there is no video stream information.
1430 * @return @c 0 on success,
1431 * otherwise a negative error value
1432 * @retval #PLAYER_ERROR_NONE Successful
1433 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1434 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1435 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1436 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1438 int player_get_video_stream_info(player_h player, int *fps, int *bit_rate);
1441 * @brief Gets the video display's height and width.
1442 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1443 * @remarks The playback type should be local playback or HTTP streaming playback.
1444 * @param[in] player The handle to the media player
1445 * @param[out] width The width of the video \n
1446 * Value can be invalid if there is no video or no display is set.
1447 * @param[out] height The height of the video \n
1448 * Value can be invalid value if there is no video or no display is set.
1449 * @return @c 0 on success,
1450 * otherwise a negative error value
1451 * @retval #PLAYER_ERROR_NONE Successful
1452 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1453 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1454 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1455 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1457 int player_get_video_size(player_h player, int *width, int *height);
1460 * @brief Gets the album art in the media resource.
1461 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1462 * @remarks You must not release @a album_art.
1463 * The @a album_art is managed by the platform and will be released
1464 * when the player is unprepared or destroyed by calling player_unprepare() or player_destroy().
1465 * @param[in] player The handle to the media player
1466 * @param[out] album_art The encoded artwork image
1467 * @param[out] size The encoded artwork size
1468 * @return @c 0 on success,
1469 * otherwise a negative error value
1470 * @retval #PLAYER_ERROR_NONE Successful
1471 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1472 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1473 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1474 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1476 int player_get_album_art(player_h player, void **album_art, int *size);
1479 * @brief Gets the total running time of the associated media.
1480 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1481 * @remarks The media source is associated with the player, using either player_set_uri() or player_set_memory_buffer().
1482 * @remarks The playback type should be local playback or HTTP streaming playback.
1483 * @param[in] player The handle to the media player
1484 * @param[out] milliseconds The duration in milliseconds
1485 * @return @c 0 on success,
1486 * otherwise a negative error value
1487 * @retval #PLAYER_ERROR_NONE Successful
1488 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1489 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1490 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1491 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1492 * @see player_set_uri()
1493 * @see player_set_memory_buffer()
1494 * @see player_get_duration_nsec()
1496 int player_get_duration(player_h player, int *milliseconds);
1499 * @brief Gets the total running time in nanoseconds of the associated media.
1501 * @param[in] player The handle to the media player
1502 * @param[out] nanoseconds The duration time in nanoseconds
1503 * @return @c 0 on success,
1504 * otherwise a negative error value
1505 * @retval #PLAYER_ERROR_NONE Successful
1506 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1507 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1508 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1509 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
1510 * @see player_set_uri()
1511 * @see player_set_memory_buffer()
1512 * @see player_get_duration()
1514 int player_get_duration_nsec(player_h player, int64_t *nanoseconds);
1522 * @addtogroup CAPI_MEDIA_PLAYER_AUDIO_EFFECT_MODULE
1527 * @brief Gets the number of equalizer bands.
1528 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1529 * @param[in] player The handle to the media player
1530 * @param[out] count The number of equalizer bands
1531 * @return @c 0 on success,
1532 * otherwise a negative error value
1533 * @retval #PLAYER_ERROR_NONE Successful
1534 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1535 * @see player_audio_effect_equalizer_is_available()
1536 * @see player_audio_effect_set_equalizer_band_level()
1537 * @see player_audio_effect_set_equalizer_all_bands()
1539 int player_audio_effect_get_equalizer_bands_count(player_h player, int *count);
1542 * @brief Sets the gain set for the given equalizer band.
1543 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1544 * @param[in] player The handle to the media player
1545 * @param[in] index The index of the equalizer band to be set
1546 * @param[in] level The new gain in decibel that is set to the given band [dB]
1547 * @return @c 0 on success,
1548 * otherwise a negative error value
1549 * @retval #PLAYER_ERROR_NONE Successful
1550 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1551 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1552 * @see player_audio_effect_equalizer_is_available()
1553 * @see player_audio_effect_get_equalizer_bands_count()
1554 * @see player_audio_effect_get_equalizer_level_range()
1555 * @see player_audio_effect_get_equalizer_band_level()
1556 * @see player_audio_effect_set_equalizer_all_bands()
1558 int player_audio_effect_set_equalizer_band_level(player_h player, int index, int level);
1561 * @brief Gets the gain set for the given equalizer band.
1562 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1563 * @param[in] player The handle to the media player
1564 * @param[in] index The index of the requested equalizer band
1565 * @param[out] level The gain in decibel of the given band [dB]
1566 * @return @c 0 on success,
1567 * otherwise a negative error value
1568 * @retval #PLAYER_ERROR_NONE Successful
1569 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1570 * @see player_audio_effect_equalizer_is_available()
1571 * @see player_audio_effect_set_equalizer_band_level()
1573 int player_audio_effect_get_equalizer_band_level(player_h player, int index, int *level);
1576 * @brief Sets all bands of the equalizer.
1577 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1578 * @param[in] player The handle to the media player
1579 * @param[in] band_levels The list of band levels to be set
1580 * @param[in] length The length of the band level
1581 * @return @c 0 on success,
1582 * otherwise a negative error value
1583 * @retval #PLAYER_ERROR_NONE Successful
1584 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1585 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1586 * @see player_audio_effect_equalizer_is_available()
1587 * @see player_audio_effect_get_equalizer_bands_count()
1588 * @see player_audio_effect_get_equalizer_level_range()
1589 * @see player_audio_effect_set_equalizer_band_level()
1591 int player_audio_effect_set_equalizer_all_bands(player_h player, int *band_levels, int length);
1594 * @brief Gets the valid band level range of the equalizer.
1595 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1596 * @param[in] player The handle to the media player
1597 * @param[out] min The minimum value to be set [dB]
1598 * @param[out] max The maximum value to be set [dB]
1599 * @return @c 0 on success,
1600 * otherwise a negative error value
1601 * @retval #PLAYER_ERROR_NONE Successful
1602 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1603 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1604 * @see player_audio_effect_equalizer_is_available()
1605 * @see player_audio_effect_set_equalizer_band_level()
1606 * @see player_audio_effect_set_equalizer_all_bands()
1608 int player_audio_effect_get_equalizer_level_range(player_h player, int *min, int *max);
1611 * @brief Gets the band frequency of the equalizer.
1612 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1613 * @param[in] player The handle to the media player
1614 * @param[in] index The index of the requested equalizer band
1615 * @param[out] frequency The frequency of the given band [dB]
1616 * @return @c 0 on success,
1617 * otherwise a negative error value
1618 * @retval #PLAYER_ERROR_NONE Successful
1619 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1620 * @see player_audio_effect_equalizer_is_available()
1622 int player_audio_effect_get_equalizer_band_frequency(player_h player, int index, int *frequency);
1625 * @brief Gets the band frequency range of the equalizer.
1626 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1627 * @param[in] player The handle to the media player
1628 * @param[in] index The index of the requested equalizer band
1629 * @param[out] range The frequency range of the given band [dB]
1630 * @return @c 0 on success,
1631 * otherwise a negative error value
1632 * @retval #PLAYER_ERROR_NONE Successful
1633 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1634 * @see player_audio_effect_equalizer_is_available()
1636 int player_audio_effect_get_equalizer_band_frequency_range(player_h player, int index, int *range);
1639 * @brief Clears the equalizer effect.
1640 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1641 * @param[in] player The handle to the media player
1642 * @return @c 0 on success,
1643 * otherwise a negative error value
1644 * @retval #PLAYER_ERROR_NONE Successful
1645 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1646 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1647 * @see player_audio_effect_equalizer_is_available()
1648 * @see player_audio_effect_set_equalizer_band_level()
1649 * @see player_audio_effect_set_equalizer_all_bands()
1651 int player_audio_effect_equalizer_clear(player_h player);
1654 * @brief Checks whether the custom equalizer effect is available.
1655 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1656 * @param[in] player The handle to the media player
1657 * @param[out] available If @c true the specified audio effect is available,
1658 * otherwise @c false
1659 * @return @c 0 on success,
1660 * otherwise a negative error value
1661 * @retval #PLAYER_ERROR_NONE Successful
1662 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1663 * @see player_audio_effect_set_equalizer_band_level()
1664 * @see player_audio_effect_set_equalizer_all_bands()
1666 int player_audio_effect_equalizer_is_available(player_h player, bool *available);
1674 * @addtogroup CAPI_MEDIA_PLAYER_MODULE
1679 * @brief Captures the video frame, asynchronously.
1680 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1681 * @param[in] player The handle to the media player
1682 * @param[in] callback The callback function to register
1683 * @param[in] user_data The user data to be passed to the callback function
1684 * @return @c 0 on success,
1685 * otherwise a negative error value
1686 * @retval #PLAYER_ERROR_NONE Successful
1687 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1688 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1689 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1690 * @pre The player state must be set to #PLAYER_STATE_PLAYING by calling player_start() or set to #PLAYER_STATE_PAUSED by calling player_pause().
1691 * @pre Video display type should be set by calling player_set_display() otherwise, audio stream is only processed even though video file is set.
1692 * @post It invokes player_video_captured_cb() when capture completes, if you set a callback.
1693 * @see player_video_captured_cb()
1695 int player_capture_video(player_h player, player_video_captured_cb callback, void *user_data);
1702 * @addtogroup CAPI_MEDIA_PLAYER_STREAMING_MODULE
1707 * @brief Sets the cookie for streaming playback.
1708 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1709 * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
1710 * to reflect the cookie information when the streaming connection is set up.
1711 * @param[in] player The handle to the media player
1712 * @param[in] cookie The cookie to set
1713 * @param[in] size The size of the cookie
1714 * @return @c 0 on success,
1715 * otherwise a negative error value
1716 * @retval #PLAYER_ERROR_NONE Successful
1717 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1718 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1719 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1720 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
1721 * @see player_set_uri()
1722 * @see player_set_streaming_user_agent()
1724 int player_set_streaming_cookie(player_h player, const char *cookie, int size);
1727 * @brief Sets the streaming user agent for playback.
1728 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1729 * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
1730 * to reflect the user agent information when the streaming connection is set up.
1731 * @param[in] player The handle to the media player
1732 * @param[in] user_agent The user agent to set
1733 * @param[in] size The size of the user agent
1734 * @return @c 0 on success,
1735 * otherwise a negative error value
1736 * @retval #PLAYER_ERROR_NONE Successful
1737 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1738 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1739 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1740 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
1741 * @see player_set_uri()
1742 * @see player_set_streaming_cookie()
1744 int player_set_streaming_user_agent(player_h player, const char *user_agent, int size);
1747 * @brief Gets the download progress for streaming playback.
1748 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1749 * @param[in] player The handle to the media player
1750 * @param[out] start The starting position of received data in percentage [0, 100]
1751 * @param[out] end The end position of received data in percentage [0, 100]
1752 * @return @c 0 on success,
1753 * otherwise a negative error value
1754 * @retval #PLAYER_ERROR_NONE Successful
1755 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1756 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1757 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1758 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1760 int player_get_streaming_download_progress(player_h player, int *start, int *end);
1767 * @addtogroup CAPI_MEDIA_PLAYER_MODULE
1772 * @brief Sets a callback function to be invoked when the playback is finished.
1773 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1774 * @param[in] player The handle to the media player
1775 * @param[in] callback The callback function to register
1776 * @param[in] user_data The user data to be passed to the callback function
1777 * @return @c 0 on success,
1778 * otherwise a negative error value
1779 * @retval #PLAYER_ERROR_NONE Successful
1780 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1781 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1782 * @post player_completed_cb() will be invoked.
1783 * @see player_unset_completed_cb()
1784 * @see player_completed_cb()
1785 * @see player_start()
1787 int player_set_completed_cb(player_h player, player_completed_cb callback, void *user_data);
1790 * @brief Unsets the playback completed callback function.
1791 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1792 * @param[in] player The handle to the media player
1793 * @return @c 0 on success,
1794 * otherwise a negative error value
1795 * @retval #PLAYER_ERROR_NONE Successful
1796 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1797 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1798 * @see player_set_completed_cb()
1800 int player_unset_completed_cb(player_h player);
1803 * @brief Sets a callback function to be invoked when the playback is interrupted or the interrupt is completed.
1804 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1805 * @param[in] player The handle to the media player
1806 * @param[in] callback The callback function to register
1807 * @param[in] user_data The user data to be passed to the callback function
1808 * @return @c 0 on success,
1809 * otherwise a negative error value
1810 * @retval #PLAYER_ERROR_NONE Successful
1811 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1812 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1813 * @post player_interrupted_cb() will be invoked.
1814 * @see player_unset_interrupted_cb()
1815 * @see #player_interrupted_code_e
1816 * @see player_interrupted_cb()
1818 int player_set_interrupted_cb(player_h player, player_interrupted_cb callback, void *user_data);
1821 * @brief Unsets the interrupted callback function.
1822 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1823 * @param[in] player The handle to the media player
1824 * @return @c 0 on success,
1825 * otherwise a negative error value
1826 * @retval #PLAYER_ERROR_NONE Successful
1827 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1828 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1829 * @see player_set_interrupted_cb()
1831 int player_unset_interrupted_cb(player_h player);
1834 * @brief Sets a callback function to be invoked when an error occurs.
1835 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1836 * @param[in] player The handle to the media player
1837 * @param[in] callback The callback function to register
1838 * @param[in] user_data The user data to be passed to the callback function
1839 * @return @c 0 on success,
1840 * otherwise a negative error value
1841 * @retval #PLAYER_ERROR_NONE Successful
1842 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1843 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1844 * @post player_error_cb() will be invoked.
1845 * @see player_unset_error_cb()
1846 * @see player_error_cb()
1848 int player_set_error_cb(player_h player, player_error_cb callback, void *user_data);
1851 * @brief Unsets the error callback function.
1852 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1853 * @param[in] player The handle to the media player
1854 * @return @c 0 on success,
1855 * otherwise a negative error value
1856 * @retval #PLAYER_ERROR_NONE Successful
1857 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1858 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1859 * @see player_set_error_cb()
1861 int player_unset_error_cb(player_h player);
1868 * @addtogroup CAPI_MEDIA_PLAYER_STREAMING_MODULE
1873 * @brief Sets a callback function to be invoked when there is a change in the buffering status of a media stream.
1874 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1875 * @remarks The media resource should be streamed over the network.
1876 * @param[in] player The handle to the media player
1877 * @param[in] callback The callback function to register
1878 * @param[in] user_data The user data to be passed to the callback function
1879 * @return @c 0 on success,
1880 * otherwise a negative error value
1881 * @retval #PLAYER_ERROR_NONE Successful
1882 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1883 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1884 * @if WEARABLE @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature @endif
1885 * @post player_buffering_cb() will be invoked.
1886 * @see player_unset_buffering_cb()
1887 * @see player_set_uri()
1888 * @see player_buffering_cb()
1890 int player_set_buffering_cb(player_h player, player_buffering_cb callback, void *user_data);
1893 * @brief Unsets the buffering callback function.
1894 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1895 * @param[in] player The handle to the media player
1896 * @return @c 0 on success,
1897 * otherwise a negative error value
1898 * @retval #PLAYER_ERROR_NONE Successful
1899 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1900 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1901 * @see player_set_buffering_cb()
1903 int player_unset_buffering_cb(player_h player);
1910 * @addtogroup CAPI_MEDIA_PLAYER_MODULE
1915 * @brief Sets the playback rate.
1916 * @details The default value is @c 1.0.
1917 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1918 * @remarks #PLAYER_ERROR_INVALID_OPERATION occurs when streaming playback.
1919 * @remarks No operation is performed, if @a rate is @c 0.
1920 * @remarks The sound is muted, when playback rate is under @c 0.0 and over @c 2.0.
1921 * @param[in] player The handle to the media player
1922 * @param[in] rate The playback rate (-5.0x ~ 5.0x)
1923 * @return @c 0 on success,
1924 * otherwise a negative error value
1925 * @retval #PLAYER_ERROR_NONE Successful
1926 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1927 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1928 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
1929 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
1931 int player_set_playback_rate(player_h player, float rate);
1938 * @addtogroup CAPI_MEDIA_PLAYER_SUBTITLE_MODULE
1943 * @brief Sets a subtitle path.
1944 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1945 * @remarks Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.
1946 * @remarks The mediastorage privilege(http://tizen.org/privilege/mediastorage) must be added if any files are used to play located in the internal storage.
1947 * @remarks The externalstorage privilege(http://tizen.org/privilege/externalstorage) must be added if any files are used to play located in the external storage.
1948 * @remarks The path value can be @c NULL for reset before calling player_prepare() or player_prepare_async().
1950 * @param[in] player The handle to the media player
1951 * @param[in] path The absolute path of the subtitle file, it can be @c NULL in the #PLAYER_STATE_IDLE state.
1952 * @return @c 0 on success,
1953 * otherwise a negative error value
1954 * @retval #PLAYER_ERROR_NONE Successful
1955 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1956 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1957 * @retval #PLAYER_ERROR_PERMISSION_DENIED Permission denied
1958 * @retval #PLAYER_ERROR_NO_SUCH_FILE File not found (Since 4.0)
1960 int player_set_subtitle_path(player_h player, const char *path);
1963 * @brief Sets a callback function to be invoked when a subtitle updates.
1964 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1965 * @remarks The callback is called in a separate thread (not in the main loop).
1966 * @param[in] player The handle to the media player
1967 * @param[in] callback The callback function to register
1968 * @param[in] user_data The user data to be passed to the callback function
1969 * @return @c 0 on success,
1970 * otherwise a negative error value
1971 * @retval #PLAYER_ERROR_NONE Successful
1972 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1973 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1974 * @pre The subtitle must be set by calling player_set_subtitle_path().
1975 * @post player_subtitle_updated_cb() will be invoked.
1976 * @see player_unset_subtitle_updated_cb()
1977 * @see player_subtitle_updated_cb()
1978 * @see player_set_subtitle_path()
1980 int player_set_subtitle_updated_cb(player_h player, player_subtitle_updated_cb callback, void *user_data);
1983 * @brief Unsets the subtitle updated callback function.
1984 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
1985 * @param[in] player The handle to the media player
1986 * @return @c 0 on success,
1987 * otherwise a negative error value
1988 * @retval #PLAYER_ERROR_NONE Successful
1989 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
1990 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
1991 * @see player_set_subtitle_updated_cb()
1993 int player_unset_subtitle_updated_cb(player_h player);
1996 * @brief Sets the seek position for the subtitle.
1997 * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif.1
1998 * @remarks Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.
1999 * @param[in] player The handle to the media player
2000 * @param[in] milliseconds The position in milliseconds from the start to the seek point
2001 * @return @c 0 on success,
2002 * otherwise a negative error value
2003 * @retval #PLAYER_ERROR_NONE Successful
2004 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2005 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2006 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
2007 * @pre The subtitle must be set by calling player_set_subtitle_path().
2008 * @pre The player state must be one of #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
2010 int player_set_subtitle_position_offset(player_h player, int milliseconds);
2018 * @addtogroup CAPI_MEDIA_PLAYER_STREAM_INFO_MODULE
2023 * @brief Sets a callback function to be invoked when video stream is changed.
2024 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
2025 * @remarks The stream changing is detected just before rendering operation.
2026 * @remarks The callback is called in a separate thread (not in the main loop).
2027 * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
2028 * to reflect the requirement when the player is building.
2029 * @param[in] player The handle to the media player
2030 * @param[in] callback The stream changed callback function to register
2031 * @param[in] user_data The user data to be passed to the callback function
2032 * @return @c 0 on success,
2033 * otherwise a negative error value
2034 * @retval #PLAYER_ERROR_NONE Successful
2035 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
2036 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2037 * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
2038 * @post player_video_stream_changed_cb() will be invoked.
2039 * @see player_unset_video_stream_changed_cb()
2040 * @see player_video_stream_changed_cb()
2042 int player_set_video_stream_changed_cb(player_h player, player_video_stream_changed_cb callback, void *user_data);
2045 * @brief Unsets the video stream changed callback function.
2046 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
2047 * @param[in] player The handle to the media player
2048 * @return @c 0 on success,
2049 * otherwise a negative error value
2050 * @retval #PLAYER_ERROR_NONE Successful
2051 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2052 * @see player_set_video_stream_changed_cb()
2054 int player_unset_video_stream_changed_cb(player_h player);
2062 * @addtogroup CAPI_MEDIA_PLAYER_MODULE
2067 * @brief Gets current track index.
2068 * @details Index starts from 0.
2069 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
2070 * @param[in] player The handle to the media player
2071 * @param[in] type The type of target stream which is #PLAYER_STREAM_TYPE_AUDIO or #PLAYER_STREAM_TYPE_TEXT
2072 * @param[out] index The index of track
2073 * @return @c 0 on success,
2074 * otherwise a negative error value
2075 * @retval #PLAYER_ERROR_NONE Successful
2076 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2077 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2078 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
2079 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
2081 int player_get_current_track(player_h player, player_stream_type_e type, int *index);
2084 * @brief Gets language code of a track.
2085 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
2086 * @remarks @a code must be released with @c free() by caller
2087 * @param[in] player The handle to the media player
2088 * @param[in] type The type of target stream which is #PLAYER_STREAM_TYPE_AUDIO or #PLAYER_STREAM_TYPE_TEXT
2089 * @param[in] index The index of track
2090 * @param[out] code A language code in ISO 639-1. "und" will be returned if the language is undefined.
2091 * @return @c 0 on success,
2092 * otherwise a negative error value
2093 * @retval #PLAYER_ERROR_NONE Successful
2094 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2095 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2096 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
2097 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
2099 int player_get_track_language_code(player_h player, player_stream_type_e type, int index, char **code);
2102 * @brief Gets the track count.
2103 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
2104 * @param[in] player The handle to the media player
2105 * @param[in] type The type of target stream which is #PLAYER_STREAM_TYPE_AUDIO or #PLAYER_STREAM_TYPE_TEXT
2106 * @param[out] count The number of track
2107 * @return @c 0 on success,
2108 * otherwise a negative error value
2109 * @retval #PLAYER_ERROR_NONE Successful
2110 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2111 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2112 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
2113 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
2115 int player_get_track_count(player_h player, player_stream_type_e type, int *count);
2118 * @brief Selects a track to play.
2119 * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
2120 * @param[in] player The handle to the media player
2121 * @param[in] type The type of target stream which is #PLAYER_STREAM_TYPE_AUDIO or #PLAYER_STREAM_TYPE_TEXT
2122 * @param[in] index The index of track
2123 * @return @c 0 on success,
2124 * otherwise a negative error value
2125 * @retval #PLAYER_ERROR_NONE Successful
2126 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2127 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2128 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
2129 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
2130 * @see player_get_current_track()
2132 int player_select_track(player_h player, player_stream_type_e type, int index);
2139 * @addtogroup CAPI_MEDIA_PLAYER_STREAMING_MODULE
2144 * @brief Retrieves all the streaming variant information.
2146 * @remarks This function is used for adaptive streaming(hls/mpeg dash) only.
2147 * @param[in] player The handle to the media player
2148 * @param[in] callback The iteration callback function
2149 * @param[in] user_data The user data to be passed to the callback function
2150 * @return @c 0 on success,
2151 * otherwise a negative error value
2152 * @retval #PLAYER_ERROR_NONE Successful
2153 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2154 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2155 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
2156 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
2157 * @see player_adaptive_variant_cb()
2159 int player_foreach_adaptive_variant(player_h player, player_adaptive_variant_cb callback, void *user_data);
2162 * @brief Sets the maximum limit of the streaming variant.
2164 * @remarks This function is used for adaptive streaming(hls/mpeg dash) only.
2165 * @remarks The bandwidth setting can only be applied if there is no width, height information at streaming variant header.
2166 * Application can get all the variant information by calling player_foreach_adaptive_variant() function.
2167 * @remarks If there is no affordable stream for the condition, the minimum bandwidth stream will be selected.
2168 * @param[in] player The handle to the media player
2169 * @param[in] bandwidth The max bandwidth limit of the stream variant (default: -1)
2170 * @param[in] width The max width limit of the stream variant (default: -1)
2171 * @param[in] height The max height limit of the stream variant (default: -1)
2172 * @return @c 0 on success,
2173 * otherwise a negative error value
2174 * @retval #PLAYER_ERROR_NONE Successful
2175 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2176 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2177 * @see player_foreach_adaptive_variant()
2178 * @see player_get_max_adaptive_variant_limit()
2180 int player_set_max_adaptive_variant_limit(player_h player, int bandwidth, int width, int height);
2183 * @brief Gets the maximum limit of the streaming variant.
2185 * @remarks This function is used for adaptive streaming(hls/mpeg dash) only.
2186 * @param[in] player The handle to the media player
2187 * @param[out] bandwidth The max bandwidth limit of the stream variant (default: -1)
2188 * @param[out] width The max width limit of the stream variant (default: -1)
2189 * @param[out] height The max height limit of the stream variant (default: -1)
2190 * @return @c 0 on success,
2191 * otherwise a negative error value
2192 * @retval #PLAYER_ERROR_NONE Successful
2193 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2194 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2195 * @see player_foreach_adaptive_variant()
2196 * @see player_set_max_adaptive_variant_limit()
2198 int player_get_max_adaptive_variant_limit(player_h player, int *bandwidth, int *width, int *height);
2205 * @addtogroup CAPI_MEDIA_PLAYER_MODULE
2210 * @brief Sets the audio only mode.
2211 * @details This function is used to disable or enable video rendering during playback.
2213 * @param[in] player The handle to the media player
2214 * @param[in] audio_only The new audio only status: (@c true = enable audio only, @c false = disable audio only)
2215 * @return @c 0 on success,
2216 * otherwise a negative error value
2217 * @retval #PLAYER_ERROR_NONE Successful
2218 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2219 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2220 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
2221 * @pre The player state must be one of: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
2222 * @see player_is_audio_only()
2224 int player_set_audio_only(player_h player, bool audio_only);
2227 * @brief Gets the audio only mode status.
2229 * @param[in] player The handle to the media player
2230 * @param[out] audio_only The current audio only status: (@c true = audio only enabled, @c false = audio only disabled)
2231 * @return @c 0 on success,
2232 * otherwise a negative error value
2233 * @retval #PLAYER_ERROR_NONE Successful
2234 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2235 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2236 * @see player_set_audio_only()
2238 int player_is_audio_only(player_h player, bool *audio_only);
2241 * @brief Sets the player's replaygain status.
2242 * @details If the replaygain status is @c true, replaygain is applied (if contents has a replaygain tag).
2243 * If it is @c false, the replaygain isn't affected by tag and properties.
2245 * @param[in] player The handle to the media player
2246 * @param[in] enabled The new replaygain status: (@c true = enable, @c false = disable)
2247 * @return @c 0 on success,
2248 * otherwise a negative error value
2249 * @retval #PLAYER_ERROR_NONE Successful
2250 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2251 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2252 * @see player_is_replaygain_enabled()
2254 int player_set_replaygain_enabled(player_h player, bool enabled);
2257 * @brief Gets the player's replaygain status.
2259 * @param[in] player The handle to the media player
2260 * @param[out] enabled Pointer to store current replaygain status:
2261 * (@c true = enabled replaygain,
2262 @c false = disabled replaygain)
2263 * @return @c 0 on success,
2264 * otherwise a negative error value
2265 * @retval #PLAYER_ERROR_NONE Successful
2266 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2267 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2268 * @see player_set_replaygain_enable()
2270 int player_is_replaygain_enabled(player_h player, bool *enabled);
2273 * @brief Sets the ROI (Region Of Interest) area of the content video source.
2274 * @details This function is to set the ROI area of video content to render it
2275 * on #PLAYER_DISPLAY_TYPE_OVERLAY display with current display mode.
2276 * It can be regarded as zooming operation because the selected video area will be rendered fit to the display.
2278 * @remarks This function requires the ratio value of the each coordinate and size based on the video resolution size
2279 * to consider the dynamic resolution video content.
2280 * @remarks This function have to be called after calling player_set_display() and the ROI area is valid only in #PLAYER_DISPLAY_TYPE_OVERLAY.
2281 * @param[in] player The handle to the media player
2282 * @param[in] x_scale X coordinate ratio value of the video source area based on the video width size \n
2283 * Valid range is 0.0~1.0.
2284 * @param[in] y_scale Y coordinate ratio value of the video source area based on the video height size \n
2285 * Valid range is 0.0~1.0.
2286 * @param[in] w_scale Width ratio value of the video source area based on the video width size \n
2287 * Valid range is from greater than 0.0 to 1.0.
2288 * @param[in] h_scale Height ratio value of the video source area based on the video height size \n
2289 * Valid range is from greater than 0.0 to 1.0.
2290 * @return @c 0 on success,
2291 * otherwise a negative error value
2292 * @retval #PLAYER_ERROR_NONE Successful
2293 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2294 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2295 * @see #player_display_type_e
2296 * @see player_set_display()
2297 * @see player_set_display_mode()
2298 * @see player_get_video_size()
2299 * @see player_get_video_roi_area()
2304 player_h player = NULL;
2305 player_display_h display = NULL;
2306 int width = 0, height = 0;
2308 player_set_display (player, PLAYER_DISPLAY_TYPE_OVERLAY, display);
2309 player_get_video_size (player, &width, &height);
2311 player_set_video_roi_area (30/(double)width, 30/(double)height, 480/(double)width, 270/(double)height);
2315 int player_set_video_roi_area(player_h player, double x_scale, double y_scale, double w_scale, double h_scale);
2318 * @brief Gets the ROI (Region Of Interest) area of the content video source.
2320 * @remarks This function gets the ratio value of the each coordinate and size based on the video resolution size.
2321 * @remarks The ROI area is valid only in #PLAYER_DISPLAY_TYPE_OVERLAY.
2322 * @param[in] player The handle to the media player
2323 * @param[out] x_scale The current X coordinate ratio value of the video source area based on the video width size
2324 * @param[out] y_scale The current Y coordinate ratio value of the video source area based on the video height size
2325 * @param[out] w_scale The current width ratio value of the video source area based on the video width size
2326 * @param[out] h_scale The current height ratio value of the video source area based on the video height size
2327 * @return @c 0 on success,
2328 * otherwise a negative error value
2329 * @retval #PLAYER_ERROR_NONE Successful
2330 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2331 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2332 * @see #player_display_type_e
2333 * @see player_set_display()
2334 * @see player_get_video_size()
2335 * @see player_set_video_roi_area()
2337 int player_get_video_roi_area(player_h player, double *x_scale, double *y_scale, double *w_scale, double *h_scale);
2340 * @brief Sets the audio pitch control status.
2342 * @remarks This function is used for audio content only.
2343 * @remarks Enabling pitch control could increase the CPU usage on some devices.
2344 * @param[in] player The handle to the media player
2345 * @param[in] enabled The new audio pitch control status (default: false)
2346 * @return @c 0 on success,
2347 * otherwise a negative error value
2348 * @retval #PLAYER_ERROR_NONE Successful
2349 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
2350 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2351 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2352 * @pre The player state must be #PLAYER_STATE_IDLE.
2353 * @see player_audio_pitch_is_enabled()
2354 * @see player_audio_pitch_set_value()
2355 * @see player_audio_pitch_get_value()
2357 int player_audio_pitch_set_enabled(player_h player, bool enabled);
2360 * @brief Gets the audio pitch control status.
2362 * @remarks This function is used for audio content only.
2363 * @param[in] player The handle to the media player
2364 * @param[out] enabled The audio pitch control status (default: false)
2365 * @return @c 0 on success,
2366 * otherwise a negative error value
2367 * @retval #PLAYER_ERROR_NONE Successful
2368 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2369 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2370 * @see player_audio_pitch_set_enabled()
2371 * @see player_audio_pitch_set_value()
2372 * @see player_audio_pitch_get_value()
2374 int player_audio_pitch_is_enabled(player_h player, bool *enabled);
2377 * @brief Sets the audio pitch value.
2379 * @remarks This function is used for audio content only.
2380 * @param[in] player The handle to the media player
2381 * @param[in] value The audio stream pitch value \n
2382 * Valid range is 0.5~2. Default value is 1.
2383 * @return @c 0 on success,
2384 * otherwise a negative error value
2385 * @retval #PLAYER_ERROR_NONE Successful
2386 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2387 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2388 * @pre The pitch control must be enabled by calling player_audio_pitch_set_enabled() function.
2389 * @see player_audio_pitch_set_enabled()
2390 * @see player_audio_pitch_is_enabled()
2391 * @see player_audio_pitch_get_value()
2393 int player_audio_pitch_set_value(player_h player, float value);
2396 * @brief Gets the audio pitch value.
2398 * @remarks This function is used for audio content only.
2399 * @param[in] player The handle to the media player
2400 * @param[out] value The audio stream pitch value \n
2401 * Valid range is 0.5~2. Default value is 1.
2402 * @return @c 0 on success,
2403 * otherwise a negative error value
2404 * @retval #PLAYER_ERROR_NONE Successful
2405 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2406 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2407 * @see player_audio_pitch_set_enabled()
2408 * @see player_audio_pitch_is_enabled()
2409 * @see player_audio_pitch_set_value()
2411 int player_audio_pitch_get_value(player_h player, float *value);
2418 * @addtogroup CAPI_MEDIA_PLAYER_STREAMING_MODULE
2423 * @brief Sets the streaming buffering time.
2425 * @param[in] player The handle to the media player
2426 * @param[in] prebuffer_ms The time duration of buffering data that must be prerolled to start playback. \n
2427 * The value should be more than 1000 milliseconds to ensure the normal buffering. \n
2428 * There are, however, two exceptions: \n
2429 * 0: Indicate to use platform default value depending on the streaming type and network status (default) \n
2430 * -1: Indicate to use current value (since 5.5)
2431 * @param[in] rebuffer_ms The time duration of buffering data that must be prerolled to resume playback
2432 * if player is paused for buffering internally. \n
2433 * The value should be more than 1000 milliseconds to ensure the normal buffering. \n
2434 * There are, however, two exceptions: \n
2435 * 0: Indicate to use platform default value depending on the streaming type and network status (default) \n
2436 * -1: Indicate to use current value (since 5.5)
2437 * @return @c 0 on success,
2438 * otherwise a negative error value
2439 * @retval #PLAYER_ERROR_NONE Successful
2440 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2441 * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
2442 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation (since 5.5)
2443 * @if WEARABLE @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature @endif
2444 * @pre The player state must be #PLAYER_STATE_IDLE.
2445 * @see player_get_streaming_buffering_time()
2449 bool set_buffering_time(player_h p)
2451 int err = PLAYER_ERROR_NONE;
2453 // sets the prebuffer_ms to 5000 milliseconds but does not change the rebuffer_ms
2454 err = player_set_streaming_buffering_time(p, 5000, -1);
2455 if (err != PLAYER_ERROR_NONE) {
2456 printf("Fail to set buffering time = %x\n", err);
2463 int player_set_streaming_buffering_time(player_h player, int prebuffer_ms, int rebuffer_ms);
2466 * @brief Gets the streaming buffering time.
2468 * @param[in] player The handle to the media player
2469 * @param[out] prebuffer_ms The time duration of buffering data that must be prerolled to start playback
2470 * If the user did not set any value by calling player_set_streaming_buffering_time() function (or if the value was set to 0),
2471 * the value is @c 0 which means platform default value depending on the streaming type and network status. \n
2472 * The value is set to time duration instead of @c 0
2473 * if the player state is one of: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED. (since 5.5)
2474 * @param[out] rebuffer_ms The time duration of buffering data that must be prerolled to resume playback
2475 * if player is paused for buffering internally. \n
2476 * If the user did not set any value by calling player_set_streaming_buffering_time() function (or if the value was set to 0),
2477 * the value is @c 0 which means platform default value depending on the streaming type and network status. \n
2478 * The value is set to time duration instead of @c 0
2479 * if the player state is one of: #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED. (since 5.5)
2480 * @return @c 0 on success,
2481 * otherwise a negative error value
2482 * @retval #PLAYER_ERROR_NONE Successful
2483 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2484 * @if WEARABLE @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature @endif
2485 * @see player_get_streaming_buffering_time()
2487 int player_get_streaming_buffering_time(player_h player, int *prebuffer_ms, int *rebuffer_ms);
2494 * @addtogroup CAPI_MEDIA_PLAYER_360_MODULE
2499 * @brief Gets information whether the current content of the player is spherical.
2501 * @remarks This function is related to the following features:\n
2502 * %http://tizen.org/feature/multimedia.player.spherical_video\n
2503 * %http://tizen.org/feature/opengles.version.2_0\n
2504 * @param[in] player The handle to the media player
2505 * @param[out] is_spherical The value indicating whether the content is spherical
2506 * @return @c 0 on success,
2507 * otherwise a negative error value
2508 * @retval #PLAYER_ERROR_NONE Successful
2509 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2510 * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
2511 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2512 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
2513 * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
2515 int player_360_is_content_spherical(player_h player, bool *is_spherical);
2518 * @brief Sets the 360 video mode.
2519 * @details In case the media content is spherical, display mode can be selected by this function.
2521 * @remarks This function is related to the following features:\n
2522 * %http://tizen.org/feature/multimedia.player.spherical_video\n
2523 * %http://tizen.org/feature/opengles.version.2_0\n
2524 * @param[in] player The handle to the media player
2525 * @param[in] enabled The 360 video display status: @c true = display with 360 video mode,
2526 @c false = display with full panorama mode. The default value is @c true.
2527 * @return @c 0 on success,
2528 * otherwise a negative error value
2529 * @retval #PLAYER_ERROR_NONE Successful
2530 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2531 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2532 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
2533 * @see player_360_is_enabled()
2535 int player_360_set_enabled(player_h player, bool enabled);
2538 * @brief Gets the 360 video display mode.
2540 * @remarks This function is related to the following features:\n
2541 * %http://tizen.org/feature/multimedia.player.spherical_video\n
2542 * %http://tizen.org/feature/opengles.version.2_0\n
2543 * @param[in] player The handle to the media player
2544 * @param[out] enabled Pointer to store current 360 video display mode:
2545 * (@c true = display with 360 video mode,
2546 @c false = display with full panorama mode)
2547 * @return @c 0 on success,
2548 * otherwise a negative error value
2549 * @retval #PLAYER_ERROR_NONE Successful
2550 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2551 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2552 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
2553 * @see player_360_set_enabled()
2555 int player_360_is_enabled(player_h player, bool *enabled);
2558 * @brief Sets the 360 video direction of view.
2559 * @details This function is to set horizontal (yaw) and vertical (pitch) angles
2560 * of current direction of view in radians. Default direction of view
2561 * is taken from meta-data stored in the media. If meta-data omits
2562 * these values, zeros are assumed to be equal to the centre of the
2565 * @remarks This function is related to the following features:\n
2566 * %http://tizen.org/feature/multimedia.player.spherical_video\n
2567 * %http://tizen.org/feature/opengles.version.2_0\n
2568 * @param[in] player The handle to the media player
2569 * @param[in] yaw The angle value around vertical axis. Valid values are in
2570 * range [-PI, PI]. Default value is 0.
2571 * @param[in] pitch The angle value around lateral axis. Valid values are in
2572 * range [-PI/2, PI/2]. Default value is 0.
2573 * @return @c 0 on success,
2574 * otherwise a negative error value
2575 * @retval #PLAYER_ERROR_NONE Successful
2576 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2577 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2578 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
2579 * @see player_360_get_direction_of_view()
2581 int player_360_set_direction_of_view(player_h player, float yaw, float pitch);
2584 * @brief Gets the 360 video direction of view.
2585 * @details This function is to get horizontal (yaw) and vertical (pitch) angles
2586 * of current direction of view in radians.
2588 * @remarks This function is related to the following features:\n
2589 * %http://tizen.org/feature/multimedia.player.spherical_video\n
2590 * %http://tizen.org/feature/opengles.version.2_0\n
2591 * @param[in] player The handle to the media player
2592 * @param[out] yaw Pointer to store current value of direction of view
2593 * angle around vertical axis
2594 * @param[out] pitch Pointer to store current value of direction of view
2595 * angle around lateral axis
2596 * @return @c 0 on success,
2597 * otherwise a negative error value
2598 * @retval #PLAYER_ERROR_NONE Successful
2599 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2600 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2601 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
2602 * @see player_360_set_direction_of_view()
2604 int player_360_get_direction_of_view(player_h player, float *yaw, float *pitch);
2607 * @brief Sets the zoom level of 360 video.
2608 * @details The zoom means scaling of the flat image cut from the panorama.
2609 * The valid range is from 1.0 to 10.0, where 1.0 is the actual image and
2610 * values above are zoom-in factor. Default value is 1.0 - no zoom.
2612 * @remarks This function is related to the following features:\n
2613 * %http://tizen.org/feature/multimedia.player.spherical_video\n
2614 * %http://tizen.org/feature/opengles.version.2_0\n
2615 * @param[in] player The handle to the media player
2616 * @param[in] level The zoom level\n
2617 * Valid range is 1.0~10.0. Default value is 1.0.
2618 * @return @c 0 on success,
2619 * otherwise a negative error value
2620 * @retval #PLAYER_ERROR_NONE Successful
2621 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2622 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2623 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
2624 * @see player_360_get_zoom()
2626 int player_360_set_zoom(player_h player, float level);
2629 * @brief Gets the current zoom level of 360 video.
2630 * @details The zoom means scaling of the flat image cut from the panorama.
2631 * The valid range is from 1.0 to 10.0. Where 1.0 is actual image and
2632 * values above are zoom-in factor. Default value is 1.0 - no zoom.
2634 * @remarks This function is related to the following features:\n
2635 * %http://tizen.org/feature/multimedia.player.spherical_video\n
2636 * %http://tizen.org/feature/opengles.version.2_0\n
2637 * @param[in] player The handle to the media player
2638 * @param[out] level Pointer to store current value of zoom level
2639 * @return @c 0 on success,
2640 * otherwise a negative error value
2641 * @retval #PLAYER_ERROR_NONE Successful
2642 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2643 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2644 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
2645 * @see player_360_set_zoom()
2647 int player_360_get_zoom(player_h player, float *level);
2650 * @brief Sets the field of view information of 360 video.
2651 * @details This function is to set the field of view to decide the output frame size.
2653 * @remarks values above the default ones extend the field of view to significantly
2654 * distorted areas and will not be useful in most cases.
2655 * @remarks This function is related to the following features:\n
2656 * %http://tizen.org/feature/multimedia.player.spherical_video\n
2657 * %http://tizen.org/feature/opengles.version.2_0\n
2658 * @param[in] player The handle to the media player
2659 * @param[in] horizontal_degrees The horizontal field of view to display in degrees\n
2660 * Valid range is 1~360 degrees. Default value is 120 degrees.
2661 * @param[in] vertical_degrees The vertical field of view to display in degrees\n
2662 * Valid range is 1~180 degrees. Default value is 67 degrees.
2663 * @return @c 0 on success,
2664 * otherwise a negative error value
2665 * @retval #PLAYER_ERROR_NONE Successful
2666 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2667 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2668 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
2669 * @see player_360_get_field_of_view()
2671 int player_360_set_field_of_view(player_h player, int horizontal_degrees, int vertical_degrees);
2674 * @brief Gets the field of view information of 360 video.
2675 * @details This function is to get the field of view information.
2677 * @remarks This function is related to the following features:\n
2678 * %http://tizen.org/feature/multimedia.player.spherical_video\n
2679 * %http://tizen.org/feature/opengles.version.2_0\n
2680 * @param[in] player The handle to the media player
2681 * @param[out] horizontal_degrees Pointer to store current value of horizontal
2682 * field of view to display in degrees.
2683 * @param[out] vertical_degrees Pointer to store current value of vertical
2684 * field of view to display in degrees.
2685 * @return @c 0 on success,
2686 * otherwise a negative error value
2687 * @retval #PLAYER_ERROR_NONE Successful
2688 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2689 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2690 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
2691 * @see player_360_set_field_of_view()
2693 int player_360_get_field_of_view(player_h player, int *horizontal_degrees, int *vertical_degrees);
2696 * @brief Sets the zoom level with field of view information of 360 video.
2697 * @details This function is provided to reduce the distortion of zoom operation.
2698 * The zoom means scaling of the flat image cut from the panorama
2699 * which is decided by the field of view data.
2700 * The zoom level valid range is from 1.0 to 10.0, where 1.0 is the actual image and
2701 * values above are zoom-in factor. Default value is 1.0 - no zoom.
2703 * @remarks The degree values above the default ones extend the field of view to significantly
2704 * distorted areas and will not be useful in most cases.
2705 * @remarks This function is related to the following features:\n
2706 * %http://tizen.org/feature/multimedia.player.spherical_video\n
2707 * %http://tizen.org/feature/opengles.version.2_0\n
2708 * @param[in] player The handle to the media player
2709 * @param[in] level The zoom level\n
2710 * Valid range is 1.0~10.0. Default value is 1.0.
2711 * @param[in] horizontal_degrees The horizontal field of view to display in degrees\n
2712 * Valid range is 1~360 degrees. Default value is 120 degrees.
2713 * @param[in] vertical_degrees The vertical field of view to display in degrees\n
2714 * Valid range is 1~180 degrees. Default value is 67 degrees.
2715 * @return @c 0 on success,
2716 * otherwise a negative error value
2717 * @retval #PLAYER_ERROR_NONE Successful
2718 * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
2719 * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
2720 * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
2721 * @see player_360_set_zoom()
2722 * @see player_360_get_zoom()
2723 * @see player_360_set_field_of_view()
2724 * @see player_360_get_field_of_view()
2726 int player_360_set_zoom_with_field_of_view(player_h player, float level, int horizontal_degrees, int vertical_degrees);
2736 #endif /* __TIZEN_MEDIA_PLAYER_H__ */