* @brief Called to register for notifications about delivering media packet when every video frame is decoded.
* @since_tizen 2.3
*
- * @remarks This function is called in the context of gstreamer so the UI update code should not be directly invoked.\n
- * The packet should be released after use by calling media_packet_destroy(). \n
+ * @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
* 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
/**
* @brief Resets the media player.
* @details The most recently used media is reset and no longer associated with the player.
- * Playback is no longer possible. If you want to use the player again, you will have to set the data URI and call
+ * 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 2.3
* @param[in] player The handle to the media player
* @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 should 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()
*/
* @details Associates media contents, referred to by the URI, with the player.
* If the function call is successful, subsequent calls to player_prepare() and player_start() will start playing the media.
* @since_tizen 2.3
- * @remarks If you use HTTP or RSTP, URI should start with "http://" or "rtsp://". The default protocol is "file://".
+ * @remarks If you use HTTP or RSTP, 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 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 RSTP stream you want to play
*
* If the function call is successful, subsequent calls to player_prepare() and player_start() will start playing the media.
* @since_tizen 2.3
* @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()
+ * 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
* @brief Sets the player's sound manager stream information.
* @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
+ * For more details, please refer to sound_manager.h
+ * @remarks This API must be called before calling the player_prepare() or player_prepare_async()
+ * to reflect the sound stream information when the player is building.
*
* @param[in] player The handle to the media player
* @param[in] stream_info The sound manager info type
* @see #sound_stream_info_h
* @see sound_manager_create_stream_information()
* @see sound_manager_destroy_stream_information()
+ * @par Example
+ @code
+ #include <player.h>
+ #include <sound_manager.h>
+ ...
+ player_h player = NULL;
+ sound_stream_info_h stream_info = NULL;
+ sound_stream_type_e stream_type = SOUND_STREAM_TYPE_MEDIA;
+ ...
+ sound_manager_create_stream_information (stream_type, _focus_callback, use_data, &stream_info);
+ player_create (&player);
+ player_set_sound_stream_info (player, stream_info);
+ ...
+ player_prepare_async (player, _prepared_cb, udata);
+ ...
+ @endcode
*/
int player_set_sound_stream_info(player_h player, sound_stream_info_h stream_info);
* @brief Sets the player's sound manager stream information.
* @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
+ * For more details, please refer to sound_manager.h
*
* @param[in] player The handle to the media player
* @param[in] stream_info The sound manager info type
* @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 keyframe position is returned, but this might be faster but less accurate.
+ * 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,
* @since_tizen 2.3
* @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
+ * to reflect the display type.
* @param[in] player The handle to the media player
* @param[in] type The display type
* @param[in] display The handle to display
/**
* @brief Registers a media packet video callback function to be called once per frame.
* @since_tizen 2.3
- * @remarks This function should be called before calling player_prepare() or player_prepare_async().\n
- * A registered callback is called in a seperate thread (not in the main loop).\n
+ * @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
* A video frame can be retrieved using a registered callback as a media packet.\n
* The callback function holds the same buffer that will be drawn on the display device.\n
* So if you change the media packet in a registered callback, it will be displayed on the device\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 should be #PLAYER_STATE_IDLE. And, #PLAYER_DISPLAY_TYPE_NONE should 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);
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
- * @pre The player's state should be #PLAYER_STATE_READY or #PLAYER_STATE_IDLE
+ * @pre The player's state must be #PLAYER_STATE_READY or #PLAYER_STATE_IDLE
* @see player_set_media_packet_video_frame_decoded_cb()
*/
int player_unset_media_packet_video_frame_decoded_cb(player_h player);
/**
* @brief Pushes elementary stream to decode audio or video
* @since_tizen 2.4
- * @remarks player_set_media_stream_info() should be called before using this API.
+ * @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.
* @param[in] player The handle to media player
/**
* @brief Sets contents information for media stream
* @since_tizen 2.4
- * @remarks AV format should be set before pushing elementary stream with player_push_media_stream().
+ * @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()
+ * to reflect the media information.
* @remarks AAC can be supported.
* @remarks H.264 can be supported.
- * @remarks This API should be called before calling the player_prepare() or player_prepare_async() \n
- * to reflect the media information when pipeline is created.
* @param[in] player The handle to media player
* @param[in] type The type of target stream
* @param[in] format The media format to set audio information
* @brief Registers a callback function to be invoked when buffer underrun or overflow is occurred.
* @since_tizen 2.4
* @remarks This API is used for media stream playback only.
- * @remarks The callback is called in a seperate thread (not in the main loop).
+ * @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
* @param[in] callback The buffer status callback function to register
* @brief Registers a callback function to be invoked when seeking is occurred.
* @since_tizen 2.4
* @remarks This API is used for media stream playback only.
- * @remarks The callback is called in a seperate thread (not in the main loop).
+ * @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
* @param[in] callback The callback function to register
* @since_tizen 2.3
* @remarks If no display is set, no operation is performed.
* @param[in] player The handle to the media player
- * @param[in] mode The display mode
+ * @param[in] mode The display mode
* @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 state
- * @pre The player should support display mode changes.
* @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()
* @brief Sets the ROI(Region Of Interest) area of display.
* @since_tizen 3.0
* @remarks If no display is set, no operation is performed.
- * @remarks Before set display ROI area, #PLAYER_DISPLAY_MODE_DST_ROI should be set with player_set_display_mode().
+ * @remarks Before set display ROI area, #PLAYER_DISPLAY_MODE_DST_ROI must be set with player_set_display_mode().
* The minimum value of width and height are 1.
* @param[in] player The handle to the media player
* @param[in] x X coordinate of area
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
- * @pre display_mode should be set to #PLAYER_DISPLAY_MODE_DST_ROI.
+ * @pre display_mode must be set to #PLAYER_DISPLAY_MODE_DST_ROI.
* @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_set_display_mode()
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
- * Video type should be set using player_set_display() otherwises, audio stream is only processed even though video file is set.
* @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
* @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().
+ * @pre Video display type should be set by calling player_set_display() otherwise, audio stream is only processed even though video file is set.
* @post It invokes player_video_captured_cb() when capture completes, if you set a callback.
* @see player_video_captured_cb()
*/
/**
* @brief Sets the cookie for streaming playback.
* @since_tizen 2.3
+ * @remarks This API 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
* @param[in] size The size of the cookie
* @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().
+ * @see player_set_uri()
* @see player_set_streaming_user_agent()
*/
int player_set_streaming_cookie(player_h player, const char *cookie, int size);
/**
* @brief Sets the streaming user agent for playback.
* @since_tizen 2.3
+ * @remarks This API 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
* @param[in] size The size of the user agent
* @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().
+ * @see player_set_uri()
* @see player_set_streaming_cookie()
*/
int player_set_streaming_user_agent(player_h player, const char *user_agent, int size);
* @brief Sets a path to download, progressively.
* @since_tizen 2.3
* @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 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
* @return @c 0 on success,
* @remarks Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.
* @remarks The mediastorage privilege(http://tizen.org/privilege/mediastorage) must be added if any files are used to play located in the internal storage.
* @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.
* @return @c 0 on success,
* @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
* @retval #PLAYER_ERROR_PERMISSION_DENIED Permission denied
* @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
- * @pre The path value can be @c NULL for reset when the player state is set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
*/
int player_set_subtitle_path(player_h player, const char *path);
/**
* @brief Registers a callback function to be invoked when a subtitle updates.
* @since_tizen 2.3
- * @remarks The callback is called in a seperate thread (not in the main loop).
+ * @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
* @brief Registers a callback function to be invoked when video stream is changed.
* @since_tizen 2.4
* @remarks The stream changing is detected just before rendering operation.
- * @remarks The callback is called in a seperate thread (not in the main loop).
+ * @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()
+ * 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
int player_submit_packet(player_h player, guint8 *buf, guint32 len, guint64 pts, player_stream_type_e streamtype);
/**
- * @brief Sets video stream info, escepically used in external demux mode
+ * @brief Sets video stream info, especially used in external demux mode
* @since_tizen 3.0
* @param[in] player The handle to media player
* @param[in] info the info of video stream set by external demux
int player_set_video_stream_info(player_h player, player_video_stream_info_s *info);
/**
- * @brief Sets audio stream info, escepically used in external demux mode
+ * @brief Sets audio stream info, especially used in external demux mode
* @since_tizen 3.0
* @param[in] player The handle to media player
* @param[in] info the info of audio stream set by external demux
* @brief Called to register for notifications about delivering media packet when every video frame is decoded.
* @since_tizen 2.3.1
*
- * @remarks This function is called in the context of gstreamer so the UI update code should not be directly invoked.\n
- * The packet should be released after use by calling media_packet_destroy(). \n
+ * @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
* 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
/**
* @brief Resets the media player.
* @details The most recently used media is reset and no longer associated with the player.
- * Playback is no longer possible. If you want to use the player again, you will have to set the data URI and call
+ * 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 2.3.1
* @param[in] player The handle to the media player
* @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 should 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()
*/
* @details Associates media contents, referred to by the URI, with the player.
* If the function call is successful, subsequent calls to player_prepare() and player_start() will start playing the media.
* @since_tizen 2.3.1
- * @remarks If you use HTTP or RSTP, URI should start with "http://" or "rtsp://". The default protocol is "file://".
+ * @remarks If you use HTTP or RSTP, 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 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 RSTP stream you want to play
*
* If the function call is successful, subsequent calls to player_prepare() and player_start() will start playing the media.
* @since_tizen 2.3.1
* @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()
+ * 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
* @brief Sets the player's sound manager stream information.
* @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
+ * For more details, please refer to sound_manager.h
+ * @remarks This API must be called before calling the player_prepare() or player_prepare_async()
+ * to reflect the sound stream information when the player is building.
*
* @param[in] player The handle to the media player
* @param[in] stream_info The sound manager info type
* @see #sound_stream_info_h
* @see sound_manager_create_stream_information()
* @see sound_manager_destroy_stream_information()
+ * @par Example
+ @code
+ #include <player.h>
+ #include <sound_manager.h>
+ ...
+ player_h player = NULL;
+ sound_stream_info_h stream_info = NULL;
+ sound_stream_type_e stream_type = SOUND_STREAM_TYPE_MEDIA;
+ ...
+ sound_manager_create_stream_information (stream_type, _focus_callback, use_data, &stream_info);
+ player_create (&player);
+ player_set_sound_stream_info (player, stream_info);
+ ...
+ player_prepare_async (player, _prepared_cb, udata);
+ ...
+ @endcode
*/
int player_set_sound_stream_info(player_h player, sound_stream_info_h stream_info);
* @brief Sets the player's sound manager stream information.
* @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
+ * For more details, please refer to sound_manager.h
*
* @param[in] player The handle to the media player
* @param[in] stream_info The sound manager info type
* @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 keyframe position is returned, but this might be faster but less accurate.
+ * 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,
* @since_tizen 2.3.1
* @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
+ * to reflect the display type.
* @param[in] player The handle to the media player
* @param[in] type The display type
* @param[in] display The handle to display
/**
* @brief Registers a media packet video callback function to be called once per frame.
* @since_tizen 2.3.1
- * @remarks This function should be called before calling player_prepare() or player_prepare_async().\n
- * A registered callback is called in a seperate thread (not in the main loop).\n
+ * @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
* A video frame can be retrieved using a registered callback as a media packet.\n
* The callback function holds the same buffer that will be drawn on the display device.\n
* So if you change the media packet in a registered callback, it will be displayed on the device\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 should be #PLAYER_STATE_IDLE. And, #PLAYER_DISPLAY_TYPE_NONE should 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);
* otherwise a negative error value
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
- * @pre The player's state should be #PLAYER_STATE_READY or #PLAYER_STATE_IDLE
+ * @pre The player's state must be #PLAYER_STATE_READY or #PLAYER_STATE_IDLE
* @see player_set_media_packet_video_frame_decoded_cb()
*/
int player_unset_media_packet_video_frame_decoded_cb(player_h player);
/**
* @brief Pushes elementary stream to decode audio or video
* @since_tizen 3.0
- * @remarks player_set_media_stream_info() should be called before using this API.
+ * @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.
* @param[in] player The handle to media player
/**
* @brief Sets contents information for media stream
* @since_tizen 3.0
- * @remarks AV format should be set before pushing elementary stream with player_push_media_stream().
+ * @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()
+ * to reflect the media information.
* @remarks AAC can be supported.
* @remarks H.264 can be supported.
- * @remarks This API should be called before calling the player_prepare() or player_prepare_async() \n
- * to reflect the media information when pipeline is created.
* @param[in] player The handle to media player
* @param[in] type The type of target stream
* @param[in] format The media format to set audio information
* @brief Registers a callback function to be invoked when buffer underrun or overflow is occurred.
* @since_tizen 3.0
* @remarks This API is used for media stream playback only.
- * @remarks The callback is called in a seperate thread (not in the main loop).
+ * @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
* @param[in] callback The buffer status callback function to register
* @brief Registers a callback function to be invoked when seeking is occurred.
* @since_tizen 3.0
* @remarks This API is used for media stream playback only.
- * @remarks The callback is called in a seperate thread (not in the main loop).
+ * @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
* @param[in] callback The callback function to register
* @since_tizen 2.3.1
* @remarks If no display is set, no operation is performed.
* @param[in] player The handle to the media player
- * @param[in] mode The display mode
+ * @param[in] mode The display mode
* @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 state
- * @pre The player should support display mode changes.
* @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()
* @brief Sets the ROI(Region Of Interest) area of display.
* @since_tizen 3.0
* @remarks If no display is set, no operation is performed.
- * @remarks Before set display ROI area, #PLAYER_DISPLAY_MODE_DST_ROI should be set with player_set_display_mode().
+ * @remarks Before set display ROI area, #PLAYER_DISPLAY_MODE_DST_ROI must be set with player_set_display_mode().
* The minimum value of width and height are 1.
* @param[in] player The handle to the media player
* @param[in] x X coordinate of area
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
- * @pre display_mode should be set to #PLAYER_DISPLAY_MODE_DST_ROI.
+ * @pre display_mode must be set to #PLAYER_DISPLAY_MODE_DST_ROI.
* @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_set_display_mode()
* @retval #PLAYER_ERROR_NONE Successful
* @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
- * Video type should be set using player_set_display() otherwises, audio stream is only processed even though video file is set.
* @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
* @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().
+ * @pre Video display type should be set by calling player_set_display() otherwise, audio stream is only processed even though video file is set.
* @post It invokes player_video_captured_cb() when capture completes, if you set a callback.
* @see player_video_captured_cb()
*/
/**
* @brief Sets the cookie for streaming playback.
* @since_tizen 2.3.1
+ * @remarks This API 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
* @param[in] size The size of the cookie
* @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().
+ * @see player_set_uri()
* @see player_set_streaming_user_agent()
*/
int player_set_streaming_cookie(player_h player, const char *cookie, int size);
/**
* @brief Sets the streaming user agent for playback.
* @since_tizen 2.3.1
+ * @remarks This API 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
* @param[in] size The size of the user agent
* @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().
+ * @see player_set_uri()
* @see player_set_streaming_cookie()
*/
int player_set_streaming_user_agent(player_h player, const char *user_agent, int size);
* @brief Sets a path to download, progressively.
* @since_tizen 2.3.1
* @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 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
* @return @c 0 on success,
* @remarks Only MicroDVD/SubViewer(*.sub), SAMI(*.smi), and SubRip(*.srt) subtitle formats are supported.
* @remarks The mediastorage privilege(http://tizen.org/privilege/mediastorage) must be added if any files are used to play located in the internal storage.
* @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.
* @return @c 0 on success,
* @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
* @retval #PLAYER_ERROR_PERMISSION_DENIED Permission denied
* @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
- * @pre The path value can be @c NULL for reset when the player state is set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
*/
int player_set_subtitle_path(player_h player, const char *path);
/**
* @brief Registers a callback function to be invoked when a subtitle updates.
* @since_tizen 2.3.1
- * @remarks The callback is called in a seperate thread (not in the main loop).
+ * @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
* @brief Registers a callback function to be invoked when video stream is changed.
* @since_tizen 3.0
* @remarks The stream changing is detected just before rendering operation.
- * @remarks The callback is called in a seperate thread (not in the main loop).
+ * @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()
+ * 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
projects / platform / core / api / player.git / commitdiff