extern "C" {
#endif
+/**
+ * @brief The player error class define.
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
+ */
#define PLAYER_ERROR_CLASS TIZEN_ERROR_PLAYER | 0x20
-/* This is for custom defined player error. */
+/**
+ * @brief The player custom error class define.
+ * @since_tizen 3.0
+ */
#define PLAYER_CUSTOM_ERROR_CLASS TIZEN_ERROR_PLAYER | 0x1000
/**
} player_stream_type_e;
/**
- * @brief Enumeration of media stream buffer status
+ * @brief Enumeration of media stream buffer status.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
+ * @see player_set_media_stream_buffer_max_size()
+ * @see player_set_media_stream_buffer_min_threshold()
*/
typedef enum {
- PLAYER_MEDIA_STREAM_BUFFER_UNDERRUN,
- PLAYER_MEDIA_STREAM_BUFFER_OVERFLOW,
+ PLAYER_MEDIA_STREAM_BUFFER_UNDERRUN, /**< The buffer level is lower than the threshold */
+ PLAYER_MEDIA_STREAM_BUFFER_OVERFLOW, /**< The buffer level is over than the threshold */
} player_media_stream_buffer_status_e;
/**
/**
* @brief Called when the subtitle is updated.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] duration The duration of the updated subtitle
- * @param[in] text The text of the updated subtitle
- * @param[in] user_data The user data passed from the callback registration function
+ * @remarks The @a text should not be released and it can be used only in the callback.
+ * To use outside, make a copy.
+ * @param[in] duration The duration of the updated subtitle
+ * @param[in] text The text of the updated subtitle
+ * @param[in] user_data The user data passed from the callback registration function
* @see player_set_subtitle_updated_cb()
* @see player_unset_subtitle_updated_cb()
*/
* #PLAYER_ERROR_NOT_SUPPORTED_VIDEO_CODEC (Since 4.0)
* #PLAYER_ERROR_NOT_SUPPORTED_SUBTITLE (Since 4.0)
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] error_code The error code
- * @param[in] user_data The user data passed from the callback registration function
+ * @param[in] error_code The error code
+ * @param[in] user_data The user data passed from the callback registration function
* @see player_set_error_cb()
* @see player_unset_error_cb()
*/
* @brief Called when the buffering percentage of the media playback is updated.
* @details If the buffer is full, it will return 100%.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] percent The percentage of buffering completed (0~100)
- * @param[in] user_data The user data passed from the callback registration function
+ * @param[in] percent The percentage of buffering completed (0~100)
+ * @param[in] user_data The user data passed from the callback registration function
* @see player_set_buffering_cb()
* @see player_unset_buffering_cb()
*/
/**
* @brief Called when progressive download is started or completed.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] type The message type for progressive download
- * @param[in] user_data The user data passed from the callback registration function
+ * @param[in] type The message type for progressive download
+ * @param[in] user_data The user data passed from the callback registration function
* @see player_set_progressive_download_path()
*/
typedef void (*player_pd_message_cb)(player_pd_message_type_e type, void *user_data);
* @brief Called when the video is captured.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks The color space format of the captured image is IMAGE_UTIL_COLORSPACE_RGB888.
- * @param[in] data The captured image buffer
- * @param[in] width The width of the captured image
- * @param[in] height The height of the captured image
- * @param[in] size The size of the captured image
- * @param[in] user_data The user data passed from the callback registration function
+ * @remarks The @a captured_data should not be released and it can be used only in the callback.
+ * To use outside, make a copy.
+ * @param[in] captured_data The captured image buffer
+ * @param[in] width The width of the captured image
+ * @param[in] height The height of the captured image
+ * @param[in] size The size of the captured image
+ * @param[in] user_data The user data passed from the callback registration function
* @see player_capture_video()
*/
-typedef void (*player_video_captured_cb)(unsigned char *data, int width, int height, unsigned int size, void *user_data);
+typedef void (*player_video_captured_cb)(unsigned char *captured_data, int width, int height, unsigned int size, void *user_data);
/**
* @brief Called to register for notifications about delivering media packet when every video frame is decoded.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- *
- * @remarks This function is called in the context of gstreamer so the UI update code must not be directly invoked.\n
- * The packet must be released after use by calling media_packet_destroy(). \n
+ * @remarks The UI update code must not be directly invoked.\n
+ * @remarks The @a packet should be released using media_packet_destroy(). \n
* If not, the decoder will fail due to having insufficient buffer space for the decoded frame.
*
- * @param[in] pkt Reference pointer to the media packet
- * @param[in] user_data The user data passed from the callback registration function
+ * @param[in] packet Reference pointer to the media packet
+ * @param[in] user_data The user data passed from the callback registration function
*/
-typedef void (*player_media_packet_video_decoded_cb)(media_packet_h pkt, void *user_data);
+typedef void (*player_media_packet_video_decoded_cb)(media_packet_h packet, void *user_data);
/**
* @brief Called when the buffer level drops below the threshold of max size or no free space in buffer.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @remarks This API is used for media stream playback only.
+ * @remarks This function is used for media stream playback only.
* @param[in] status The buffer status
* @param[in] user_data The user data passed from the callback registration function
* @see player_set_media_stream_buffer_status_cb()
* @brief Called to notify the next push-buffer offset when seeking is occurred.
* @details The next push-buffer should produce buffers from the new offset.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @remarks This API is used for media stream playback only.
+ * @remarks This function is used for media stream playback only.
* @param[in] offset The new byte position to seek
* @param[in] user_data The user data passed from the callback registration function
*/
* @brief Called to notify the video stream changed.
* @details The video stream changing is detected just before rendering operation.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @param[in] width The width of the captured image
- * @param[in] height The height of the captured image
- * @param[in] fps The frame per second of the video \n
- * It can be @c 0 if there is no video stream information.
- * @param[in] bit_rate The video bit rate [Hz] \n
- * It can be an invalid value if there is no video stream information.
- * @param[in] user_data The user data passed from the callback registration function
+ * @param[in] width The width of the captured image
+ * @param[in] height The height of the captured image
+ * @param[in] fps The frame per second of the video \n
+ * It can be @c 0 if there is no video stream information.
+ * @param[in] bit_rate The video bit rate [Hz] \n
+ * It can be an invalid value if there is no video stream information.
+ * @param[in] user_data The user data passed from the callback registration function
* @see player_set_video_stream_changed_cb()
*/
typedef void (*player_video_stream_changed_cb) (int width, int height, int fps, int bit_rate, void *user_data);
* @details The adaptive streaming protocol(hls, mpeg dash) can support variant stream condition.
* All the streaming variant information can be shared by calling player_foreach_adaptive_variant().
* @since_tizen 4.0
- * @param[in] bandwidth The bandwidth of the stream can be supportable, this is mandatory parameter
- * @param[in] width The width of the stream, this is optional parameter
- * @param[in] height The height of the stream, this is optional parameter
- * @param[in] user_data The user data passed from the callback registration function
+ * @param[in] bandwidth The bandwidth of the stream can be supportable, this is mandatory parameter
+ * @param[in] width The width of the stream, this is optional parameter
+ * @param[in] height The height of the stream, this is optional parameter
+ * @param[in] user_data The user data passed from the callback registration function
* @see player_foreach_adaptive_variant()
*/
typedef void (*player_adaptive_variant_cb) (int bandwidth, int width, int height, void *user_data);
* the player cannot guarantee proper operation because of limited resources, such as
* audio or display device.
*
- * @param[out] player A new handle to the media player
+ * @param[out] player A new handle to the media player
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @brief Destroys the media player handle and releases all its resources.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks To completely shutdown player operation, call this function with a valid player handle from any player state.
- * @param[in] player The handle to the media player to be destroyed
+ * @param[in] player The handle to the media player to be destroyed
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @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.
* @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.
* @remarks The internet privilege(http://tizen.org/privilege/internet) must be added if any URLs are used to play from network.
- * @param[in] player The handle to the media player
+ * @param[in] player The handle to the media player
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_PERMISSION_DENIED Permission denied
* @retval #PLAYER_ERROR_NOT_SUPPORTED_AUDIO_CODEC Not support audio codec format (Since 4.0)
* @retval #PLAYER_ERROR_NOT_SUPPORTED_VIDEO_CODEC Not support video codec format (Since 4.0)
- * @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.
+ * @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.
* @post The player state will be #PLAYER_STATE_READY.
* @see player_prepare_async()
* @see player_unprepare()
* @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.
* @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.
* @remarks The internet privilege(http://tizen.org/privilege/internet) must be added if any URLs are used to play from network.
- * @param[in] player The handle to the media player
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @param[in] player The handle to the media player
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
* @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
* @retval #PLAYER_ERROR_PERMISSION_DENIED Permission denied
- * @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.
+ * @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.
* @post It invokes player_prepared_cb() when playback is prepared.
* @see player_prepare()
* @see player_prepared_cb()
* Playback is no longer possible. If you want to use the player again, you must set the data URI and call
* player_prepare() again.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] player The handle to the media player
+ * @param[in] player The handle to the media player
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
* @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
- * @pre The player state must be higher than #PLAYER_STATE_IDLE.
+ * @pre The player state must be higher than #PLAYER_STATE_IDLE.
* @post The player state will be #PLAYER_STATE_IDLE.
* @see player_prepare()
*/
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks If you use HTTP or RTSP, URI must start with "http://" or "rtsp://". The default protocol is "file://".
* If you provide an invalid URI, you won't receive an error message until you call player_start().
- * @remarks This API must be called before calling the player_prepare() or player_prepare_async() to build the player based on the uri information.
+ * @remarks This function must be called before calling the player_prepare() or player_prepare_async() to build the player based on the URI information.
* @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.
* @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.
* @remarks The internet privilege(http://tizen.org/privilege/internet) must be added if any URLs are used to play from network.
*
- * @param[in] player The handle to the media player
- * @param[in] uri The content location, such as the file path, the URI of the HTTP or RTSP stream you want to play
+ * @param[in] player The handle to the media player
+ * @param[in] uri The content location, such as the file path, the URI of the HTTP or RTSP stream you want to play
*
* @return @c 0 on success,
* otherwise a negative error value
* If the function call is successful, subsequent calls to player_prepare() and player_start() will start playing the media.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks If you provide an invalid data, you won't receive an error message until you call player_start().
- * @remarks This API must be called before calling the player_prepare() or player_prepare_async()
+ * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
* to build the player based on the data.
*
- * @param[in] player The handle to the media player
- * @param[in] data The memory pointer of media data
- * @param[in] size The size of media data
+ * @param[in] player The handle to the media player
+ * @param[in] data The memory pointer of media data
+ * @param[in] size The size of media data
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
* @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
- * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
+ * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
* @see player_set_uri()
*/
int player_set_memory_buffer(player_h player, const void * data, int size);
/**
* @brief Gets the player's current state.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] player The handle to the media player
- * @param[out] state The current state of the player
+ * @param[in] player The handle to the media player
+ * @param[out] state The current state of the player
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* To change system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
* Finally, it does not support to set other value into each channel currently.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] player The handle to the media player
- * @param[in] left The left volume scalar
- * @param[in] right The right volume scalar
+ * @param[in] player The handle to the media player
+ * @param[in] left The left volume scalar
+ * @param[in] right The right volume scalar
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* This function gets the player volume, not the system volume.
* To get the system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] player The handle to the media player
- * @param[out] left The current left volume scalar
- * @param[out] right The current right volume scalar
+ * @param[in] player The handle to the media player
+ * @param[out] left The current left volume scalar
+ * @param[out] right The current right volume scalar
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @since_tizen 3.0
* @remarks You can set sound stream information including audio routing and volume type.
* For more details, please refer to sound_manager.h
- * @remarks This API must be called before calling the player_prepare() or player_prepare_async()
+ * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
* to reflect the sound stream information when the player is building.
* @remarks This function is related to the following feature:\n
* %http://tizen.org/feature/multimedia.player.stream_info\n
* @brief Sets the audio latency mode.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks The default audio latency mode of the player is #AUDIO_LATENCY_MODE_MID.
- * To get the current audio latency mode, use player_get_audio_latency_mode().
- * If it's high mode, audio output interval can be increased so, it can keep more audio data to play.
- * But, state transition like pause or resume can be more slower than default(mid) mode.
+ * To get the current audio latency mode, use player_get_audio_latency_mode().
+ * If it's high mode, audio output interval can be increased so, it can keep more audio data to play.
+ * But, state transition like pause or resume can be more slower than default(mid) mode.
*
* @param[in] player The handle to the media player
* @param[in] latency_mode The latency mode to be applied to the audio
/**
* @brief Pauses the player.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @remarks You can resume playback using player_start().
+ * @remarks You can resume playback using player_start().
*
* @param[in] player The handle to the media player
* @return @c 0 on success,
/**
* @brief Sets the seek position for playback, asynchronously.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @remarks This api will trigger the seeking operation on player instance.
+ * @remarks This function will trigger the seeking operation on player instance.
* Normally application need to wait for player_seek_completed_cb() before calling it again.
* Otherwise it will return PLAYER_ERROR_SEEK_FAILED.
* Please note that if application is playing external media data via player_set_media_stream_info(),
- * then consecutive calling of this api will always success and no need to wait for player_seek_completed_cb()
- * before next calling of this api.(since_tizen 3.0)
+ * then consecutive calling of this function will always success and no need to wait for player_seek_completed_cb()
+ * before next calling of this function.(since_tizen 3.0)
* @remarks Even if you don't set visible to true by calling player_set_display_visible,
* the video will be shown when the _seek_completed cb is invoked.
* @remarks In case of non-seekable content, it will return PLAYER_ERROR_INVALID_OPERATION.
* If application ignore this error, player will keep playing without changing play position.
- * @param[in] player The handle to the media player
- * @param[in] millisecond The position in milliseconds from the start to the seek point
- * @param[in] accurate If @c true the selected position is returned, but this might be considerably slow,
- * if @c false the nearest key frame position is returned, but this might be faster but less accurate.
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @param[in] player The handle to the media player
+ * @param[in] millisecond The position in milliseconds from the start to the seek point
+ * @param[in] accurate If @c true the selected position is returned, but this might be considerably slow,
+ * if @c false the nearest key frame position is returned, but this might be faster but less accurate.
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks To get @a display to set, use #GET_DISPLAY().
* @remarks We are not supporting changing display.
- * @remarks This API have be called before calling the player_prepare() or player_prepare_async() \n
+ * @remarks This function have be called before calling the player_prepare() or player_prepare_async() \n
* to reflect the display type.
* @param[in] player The handle to the media player
* @param[in] type The display type
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
* @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
- * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
+ * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
* @see #player_display_type_e
* @see player_set_display_mode
* @see player_set_display_roi_area
int player_set_display(player_h player, player_display_type_e type, player_display_h display);
/**
- * @brief Registers a media packet video callback function to be called once per frame.
+ * @brief Sets a media packet video callback function to be called once per frame.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks This function must be called before calling player_prepare() or player_prepare_async().\n
* A registered callback is called in a separate thread (not in the main loop).\n
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #PLAYER_ERROR_INVALID_STATE Invalid state
- * @pre The player's state must be #PLAYER_STATE_IDLE. And, #PLAYER_DISPLAY_TYPE_NONE must be set by calling player_set_display().
+ * @pre The player's state must be #PLAYER_STATE_IDLE. And, #PLAYER_DISPLAY_TYPE_NONE must be set by calling player_set_display().
* @see player_unset_media_packet_video_frame_decoded_cb
*/
int player_set_media_packet_video_frame_decoded_cb(player_h player, player_media_packet_video_decoded_cb callback, void *user_data);
/**
- * @brief Unregisters the callback function.
+ * @brief Unsets the media packet video frame callback function.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @param[in] player The handle to the media player
* @return @c 0 on success,
int player_unset_media_packet_video_frame_decoded_cb(player_h player);
/**
- * @brief Pushes elementary stream to decode audio or video
+ * @brief Pushes elementary stream to decode audio or video.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @remarks player_set_media_stream_info() must be called before using this API.
- * @remarks The available buffer size can be set by calling player_set_media_stream_buffer_max_size() API.
- * If there is no available buffer space, this api will return error since 3.0.
+ * @remarks player_set_media_stream_info() must be called before using this function.
+ * @remarks The available buffer size can be set by calling player_set_media_stream_buffer_max_size().
+ * If there is no available buffer space, this function will return error since 3.0.
* @param[in] player The handle to media player
* @param[in] packet The media packet to decode
* @return @c 0 on success,
int player_push_media_stream(player_h player, media_packet_h packet);
/**
- * @brief Sets contents information for media stream
+ * @brief Sets contents information for media stream.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
* @remarks AV format must be set before pushing elementary stream with player_push_media_stream().
- * @remarks This API must be called before calling the player_prepare() or player_prepare_async()
+ * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
* to reflect the media information.
* @remarks AAC can be supported.
* @remarks H.264 can be supported.
int player_set_media_stream_info(player_h player, player_stream_type_e type, media_format_h format);
/**
- * @brief Registers a callback function to be invoked when buffer underrun or overflow is occurred.
+ * @brief Sets a callback function to be invoked when buffer underrun or overflow is occurred.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @remarks This API is used for media stream playback only.
+ * @remarks This function is used for media stream playback only.
* @remarks The callback is called in a separate thread (not in the main loop).
* @param[in] player The handle to the media player
* @param[in] type The type of target stream
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);
/**
- * @brief Unregisters the buffer status callback function.
+ * @brief Unsets the buffer status callback function.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @remarks This API is used for media stream playback only.
+ * @remarks This function is used for media stream playback only.
* @param[in] player The handle to the media player
* @param[in] type The type of target stream
* @return @c 0 on success,
int player_unset_media_stream_buffer_status_cb(player_h player, player_stream_type_e type);
/**
- * @brief Registers a callback function to be invoked when seeking is occurred.
+ * @brief Sets a callback function to be invoked when seeking is occurred.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @remarks This API is used for media stream playback only.
+ * @remarks This function is used for media stream playback only.
* @remarks The callback is called in a separate thread (not in the main loop).
* @param[in] player The handle to the media player
* @param[in] type The type of target stream
int player_set_media_stream_seek_cb(player_h player, player_stream_type_e type, player_media_stream_seek_cb callback, void *user_data);
/**
- * @brief Unregisters the seek callback function.
+ * @brief Unsets the seek callback function.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
* @param[in] player The handle to the media player
* @param[in] type The type of target stream
/**
* @brief Sets the max size bytes of buffer.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @remarks This API is used for media stream playback only.
+ * @remarks This function is used for media stream playback only.
* @remarks If the buffer level over the max size, player_media_stream_buffer_status_cb() will be invoked with overflow status.
* @param[in] player The handle to the media player
* @param[in] type The type of target stream
/**
* @brief Gets the max size bytes of buffer.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @remarks This API is used for media stream playback only.
+ * @remarks This function is used for media stream playback only.
* @remarks If the buffer level over the max size, player_media_stream_buffer_status_cb() will be invoked with overflow status.
* @param[in] player The handle to the media player
* @param[in] type The type of target stream
/**
* @brief Sets the buffer threshold percent of buffer.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @remarks This API is used for media stream playback only.
+ * @remarks This function is used for media stream playback only.
* @remarks If the buffer level drops below the percent value, player_media_stream_buffer_status_cb() will be invoked with underrun status.
* @param[in] player The handle to the media player
* @param[in] type The type of target stream
/**
* @brief Gets the buffer threshold percent of buffer.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @remarks This API is used for media stream playback only.
+ * @remarks This function is used for media stream playback only.
* @remarks If the buffer level drops below the percent value, player_media_stream_buffer_status_cb() will be invoked with underrun status.
* @param[in] player The handle to the media player
* @param[in] type The type of target stream
* @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
* @see #player_display_mode_e
* @see player_set_display()
- * @see player_get_display_mode()
+ * @see player_get_display_mode()
*/
int player_set_display_mode(player_h player, player_display_mode_e mode);
int player_set_display_roi_area(player_h player, int x, int y, int width, int height);
/**
- * @brief Sets the visibility of the video display
+ * @brief Sets the visibility of the video display.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks If no display is set, no operation is performed.
* @remarks If you set visible before calling player_set_display, it will be applied on #PLAYER_STATE_READY state.
* @retval #PLAYER_ERROR_INVALID_STATE Invalid state
* @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
* @see player_set_display()
- * @see player_is_display_visible()
+ * @see player_is_display_visible()
*/
int player_set_display_visible(player_h player, bool visible);
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
* @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
- * @see player_set_display_visible()
+ * @see player_set_display_visible()
*/
int player_is_display_visible(player_h player, bool* visible);
/**
* @brief Gets the album art in the media resource.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @remarks You must not release @a album_art. It will be released by framework when the player is destroyed.
+ * @remarks You must not release @a album_art.
+ * The @a album_art is managed by the platform and will be released
+ * when the player is unprepared or destroyed by calling player_unprepare() or player_destroy().
* @param[in] player The handle to the media player
* @param[out] album_art The encoded artwork image
* @param[out] size The encoded artwork size
/**
* @brief Captures the video frame, asynchronously.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] player The handle to the media player
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @param[in] player The handle to the media player
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
/**
* @brief Sets the cookie for streaming playback.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @remarks This API must be called before calling the player_prepare() or player_prepare_async()
+ * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
* to reflect the cookie information when the streaming connection is set up.
* @param[in] player The handle to the media player
* @param[in] cookie The cookie to set
/**
* @brief Sets the streaming user agent for playback.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @remarks This API must be called before calling the player_prepare() or player_prepare_async()
+ * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
* to reflect the user agent information when the streaming connection is set up.
* @param[in] player The handle to the media player
* @param[in] user_agent The user agent to set
int player_get_streaming_download_progress(player_h player, int *start, int *current);
/**
- * @brief Registers a callback function to be invoked when the playback is finished.
+ * @brief Sets a callback function to be invoked when the playback is finished.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] player The handle to the media player
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @param[in] player The handle to the media player
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
int player_set_completed_cb(player_h player, player_completed_cb callback, void *user_data);
/**
- * @brief Unregisters the callback function.
+ * @brief Unsets the playback completed callback function.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @param[in] player The handle to the media player
* @return @c 0 on success,
int player_unset_completed_cb(player_h player);
/**
- * @brief Registers a callback function to be invoked when the playback is interrupted or the interrupt is completed.
+ * @brief Sets a callback function to be invoked when the playback is interrupted or the interrupt is completed.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] player The handle to the media player
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @param[in] player The handle to the media player
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
int player_set_interrupted_cb(player_h player, player_interrupted_cb callback, void *user_data);
/**
- * @brief Unregisters the callback function.
+ * @brief Unsets the interrupted callback function.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @param[in] player The handle to the media player
* @return @c 0 on success,
int player_unset_interrupted_cb(player_h player);
/**
- * @brief Registers a callback function to be invoked when an error occurs.
+ * @brief Sets a callback function to be invoked when an error occurs.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] player The handle to the media player
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @param[in] player The handle to the media player
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
int player_set_error_cb(player_h player, player_error_cb callback, void *user_data);
/**
- * @brief Unregisters the callback function.
+ * @brief Unsets the error callback function.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @param[in] player The handle to the media player
* @return @c 0 on success,
int player_unset_error_cb(player_h player);
/**
- * @brief Registers a callback function to be invoked when there is a change in the buffering status of a media stream.
+ * @brief Sets a callback function to be invoked when there is a change in the buffering status of a media stream.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks The media resource should be streamed over the network.
- * @param[in] player The handle to the media player
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @param[in] player The handle to the media player
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
int player_set_buffering_cb(player_h player, player_buffering_cb callback, void *user_data);
/**
- * @brief Unregisters the callback function.
+ * @brief Unsets the buffering callback function.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @param[in] player The handle to the media player
* @return @c 0 on success,
* @brief Sets a path to download, progressively.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks Progressive download will be started when you invoke player_start().
- * @remarks This API must be called before calling the player_prepare() or player_prepare_async() to reflect the download path when the player is building.
+ * @remarks This function must be called before calling the player_prepare() or player_prepare_async() to reflect the download path when the player is building.
* @remarks The mediastorage privilege(http://tizen.org/privilege/mediastorage) must be added if any files are used to download and play located in the internal storage.
* @remarks The externalstorage privilege(http://tizen.org/privilege/externalstorage) must be added if any files are used to download and play located in the external storage.
*
- * @param[in] player The handle to the media player
- * @param[in] path The absolute path to download
+ * @param[in] player The handle to the media player
+ * @param[in] path The absolute path to download
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
/**
* @deprecated Deprecated since 4.0.
- * @brief Registers a callback function to be invoked when progressive download is started or completed.
+ * @brief Sets a callback function to be invoked when progressive download is started or completed.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
- * @param[in] player The handle to the media player
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @param[in] player The handle to the media player
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
/**
* @deprecated Deprecated since 4.0.
- * @brief Unregisters the callback function.
+ * @brief Unsets the progressive download message callback function.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @param[in] player The handle to the media player
* @return @c 0 on success,
* @remarks #PLAYER_ERROR_INVALID_OPERATION occurs when streaming playback.
* @remarks No operation is performed, if @a rate is @c 0.
* @remarks The sound is muted, when playback rate is under @c 0.0 and over @c 2.0.
- * @param[in] player The handle to the media player
- * @param[in] rate The playback rate (-5.0x ~ 5.0x)
+ * @param[in] player The handle to the media player
+ * @param[in] rate The playback rate (-5.0x ~ 5.0x)
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @remarks The externalstorage privilege(http://tizen.org/privilege/externalstorage) must be added if any files are used to play located in the external storage.
* @remarks The path value can be @c NULL for reset before calling player_prepare() or player_prepare_async().
*
- * @param[in] player The handle to the media player
- * @param[in] path The absolute path of the subtitle file, it can be @c NULL in the #PLAYER_STATE_IDLE state.
+ * @param[in] player The handle to the media player
+ * @param[in] path The absolute path of the subtitle file, it can be @c NULL in the #PLAYER_STATE_IDLE state.
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
int player_set_subtitle_path(player_h player, const char *path);
/**
- * @brief Registers a callback function to be invoked when a subtitle updates.
+ * @brief Sets a callback function to be invoked when a subtitle updates.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @remarks The callback is called in a separate thread (not in the main loop).
- * @param[in] player The handle to the media player
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @param[in] player The handle to the media player
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
int player_set_subtitle_updated_cb(player_h player, player_subtitle_updated_cb callback, void *user_data);
/**
- * @brief Unregisters the callback function.
+ * @brief Unsets the subtitle updated callback function.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
* @param[in] player The handle to the media player
* @return @c 0 on success,
* @brief Sets the seek position for the subtitle.
* @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif.1
* @remarks Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.
- * @param[in] player The handle to the media player
- * @param[in] millisecond The position in milliseconds from the start to the seek point
+ * @param[in] player The handle to the media player
+ * @param[in] millisecond The position in milliseconds from the start to the seek point
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
*/
/**
- * @brief Registers a callback function to be invoked when video stream is changed.
+ * @brief Sets a callback function to be invoked when video stream is changed.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
* @remarks The stream changing is detected just before rendering operation.
* @remarks The callback is called in a separate thread (not in the main loop).
- * @remarks This API must be called before calling the player_prepare() or player_prepare_async()
+ * @remarks This function must be called before calling the player_prepare() or player_prepare_async()
* to reflect the requirement when the player is building.
- * @param[in] player The handle to the media player
- * @param[in] callback The stream changed callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @param[in] player The handle to the media player
+ * @param[in] callback The stream changed callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
int player_set_video_stream_changed_cb(player_h player, player_video_stream_changed_cb callback, void *user_data);
/**
- * @brief Unregisters the video stream changed callback function.
+ * @brief Unsets the video stream changed callback function.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @param[in] player The handle to the media player
+ * @param[in] player The handle to the media player
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @brief Gets current track index.
* @details Index starts from 0.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @param[in] player The handle to the media player
- * @param[in] type The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
- * @param[out] index The index of track
+ * @param[in] player The handle to the media player
+ * @param[in] type The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
+ * @param[out] index The index of track
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @brief Gets language code of a track.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
* @remarks @a code must be released with @c free() by caller
- * @param[in] player The handle to the media player
- * @param[in] type The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
- * @param[in] index The index of track
+ * @param[in] player The handle to the media player
+ * @param[in] type The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
+ * @param[in] index The index of track
* @param[out] code A language code in ISO 639-1. "und" will be returned if the language is undefined.
* @return @c 0 on success,
* otherwise a negative error value
/**
* @brief Gets the track count.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @param[in] player The handle to the media player
- * @param[in] type The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
+ * @param[in] player The handle to the media player
+ * @param[in] type The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
* @param[out] count The number of track
* @return @c 0 on success,
* otherwise a negative error value
/**
* @brief Selects a track to play.
* @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
- * @param[in] player The handle to the media player
- * @param[in] type The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
- * @param[in] index The index of track
+ * @param[in] player The handle to the media player
+ * @param[in] type The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
+ * @param[in] index The index of track
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
/**
* @brief Retrieves all the streaming variant information.
* @since_tizen 4.0
- * @remarks This API is used for adaptive streaming(hls/mpeg dash) only.
- * @param[in] player The handle to the media player
- * @param[in] callback The iteration callback function
- * @param[in] user_data The user data to be passed to the callback function
+ * @remarks This function is used for adaptive streaming(hls/mpeg dash) only.
+ * @param[in] player The handle to the media player
+ * @param[in] callback The iteration callback function
+ * @param[in] user_data The user data to be passed to the callback function
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
/**
* @brief Sets the maximum limit of the streaming variant.
* @since_tizen 4.0
- * @remarks This API is used for adaptive streaming(hls/mpeg dash) only.
+ * @remarks This function is used for adaptive streaming(hls/mpeg dash) only.
* @remarks The bandwidth setting can only be applied if there is no width, height information at streaming variant header.
* Application can get all the variant information by calling player_foreach_adaptive_variant() function.
* @remarks If there is no affordable stream for the condition, the minimum bandwidth stream will be selected.
- * @param[in] player The handle to the media player
- * @param[in] bandwidth The max bandwidth limit of the stream variant (default: -1)
- * @param[in] width The max width limit of the stream variant (deafult: -1)
- * @param[in] height The max height limit of the stream variant (deafult: -1)
+ * @param[in] player The handle to the media player
+ * @param[in] bandwidth The max bandwidth limit of the stream variant (default: -1)
+ * @param[in] width The max width limit of the stream variant (deafult: -1)
+ * @param[in] height The max height limit of the stream variant (deafult: -1)
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
/**
* @brief Gets the maximum limit of the streaming variant.
* @since_tizen 4.0
- * @remarks This API is used for adaptive streaming(hls/mpeg dash) only.
- * @param[in] player The handle to the media player
- * @param[out] bandwidth The max bandwidth limit of the stream variant (default: -1)
- * @param[out] width The max width limit of the stream variant (deafult: -1)
- * @param[out] height The max height limit of the stream variant (deafult: -1)
+ * @remarks This function is used for adaptive streaming(hls/mpeg dash) only.
+ * @param[in] player The handle to the media player
+ * @param[out] bandwidth The max bandwidth limit of the stream variant (default: -1)
+ * @param[out] width The max width limit of the stream variant (deafult: -1)
+ * @param[out] height The max height limit of the stream variant (deafult: -1)
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
/**
* @brief Gets the audio only mode status.
* @since_tizen 4.0
- * @param[in] player The handle to the media player
- * @param[out] audio_only The current audio only status: (@c true = audio only enabled, @c false = audio only disabled)
+ * @param[in] player The handle to the media player
+ * @param[out] audio_only The current audio only status: (@c true = audio only enabled, @c false = audio only disabled)
* @return @c 0 on success,
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
projects / platform / core / api / player.git / commitdiff