From c27a9028a283bd0edae59bab453b56826abae5ed Mon Sep 17 00:00:00 2001 From: Eunhae Choi Date: Thu, 8 Dec 2016 15:35:28 +0900 Subject: [PATCH] [doxygen] modify the API doxygen - add example code at player_set_sound_stream_info API. - add remark description which must be called before prepare()/prepare_async(). - modify expression about 'should' Change-Id: I53b0dab0a05386bfc67fcc47aee6376ac4789293 Signed-off-by: Eunhae Choi (cherry picked from commit f46cc5e594ebc60c8b7fcbbff61e53b5512aa513) --- include/common/player.h | 86 ++++++++++++++++++++++---------- include/common/player_internal.h | 4 +- include/wearable/player.h | 86 ++++++++++++++++++++++---------- 3 files changed, 122 insertions(+), 54 deletions(-) diff --git a/include/common/player.h b/include/common/player.h index d5ce899..12ac356 100644 --- a/include/common/player.h +++ b/include/common/player.h @@ -348,8 +348,8 @@ typedef void (*player_video_captured_cb)(unsigned char *data, int width, int hei * @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 @@ -485,7 +485,7 @@ int player_prepare_async(player_h player, player_prepared_cb callback, void* use /** * @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 @@ -495,7 +495,7 @@ int player_prepare_async(player_h player, player_prepared_cb callback, void* use * @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() */ @@ -507,11 +507,13 @@ int player_unprepare(player_h player); * @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 * @@ -534,6 +536,8 @@ int player_set_uri(player_h player, const char * uri); * 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 @@ -626,7 +630,9 @@ int player_set_sound_type(player_h player, sound_type_e type) TIZEN_DEPRECATED_A * @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 @@ -641,6 +647,22 @@ int player_set_sound_type(player_h player, sound_type_e type) TIZEN_DEPRECATED_A * @see #sound_stream_info_h * @see sound_manager_create_stream_information() * @see sound_manager_destroy_stream_information() + * @par Example + @code + #include + #include + ... + 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); @@ -648,7 +670,7 @@ int player_set_sound_stream_info(player_h player, sound_stream_info_h stream_inf * @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 @@ -786,7 +808,7 @@ int player_pause(player_h player); * @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, @@ -899,6 +921,8 @@ int player_is_looping(player_h player, bool *looping); * @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 @@ -920,8 +944,8 @@ int player_set_display(player_h player, player_display_type_e type, player_displ /** * @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 @@ -936,7 +960,7 @@ int player_set_display(player_h player, player_display_type_e type, player_displ * @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); @@ -949,7 +973,7 @@ int player_set_media_packet_video_frame_decoded_cb(player_h player, player_media * 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); @@ -957,7 +981,7 @@ 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 @@ -979,11 +1003,11 @@ int player_push_media_stream(player_h player, media_packet_h packet); /** * @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 @@ -1001,7 +1025,7 @@ int player_set_media_stream_info(player_h player, player_stream_type_e type, med * @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 @@ -1037,7 +1061,7 @@ int player_unset_media_stream_buffer_status_cb(player_h player, player_stream_ty * @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 @@ -1158,14 +1182,13 @@ int player_get_media_stream_buffer_min_threshold(player_h player, player_stream_ * @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() @@ -1194,7 +1217,7 @@ int player_get_display_mode(player_h player, player_display_mode_e *mode); * @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 @@ -1206,7 +1229,7 @@ int player_get_display_mode(player_h player, player_display_mode_e *mode); * @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() @@ -1606,9 +1629,9 @@ int player_audio_effect_equalizer_is_available(player_h player, bool *available) * @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() */ @@ -1617,6 +1640,8 @@ int player_capture_video(player_h player, player_video_captured_cb callback, voi /** * @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 @@ -1627,6 +1652,7 @@ int player_capture_video(player_h player, player_video_captured_cb callback, voi * @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); @@ -1634,6 +1660,8 @@ 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 @@ -1644,6 +1672,7 @@ int player_set_streaming_cookie(player_h player, const char *cookie, int size); * @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); @@ -1792,8 +1821,10 @@ int player_unset_buffering_cb(player_h player); * @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, @@ -1889,6 +1920,8 @@ int player_set_playback_rate(player_h player, float rate); * @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, @@ -1899,14 +1932,13 @@ int player_set_playback_rate(player_h player, float rate); * @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 @@ -1957,7 +1989,9 @@ int player_set_subtitle_position_offset(player_h player, int millisecond); * @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 diff --git a/include/common/player_internal.h b/include/common/player_internal.h index 3c4ffdf..1313449 100644 --- a/include/common/player_internal.h +++ b/include/common/player_internal.h @@ -290,7 +290,7 @@ typedef void (*player_buffer_need_data_cb) (unsigned int size, void *user_data); 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 @@ -299,7 +299,7 @@ int player_submit_packet(player_h player, guint8 *buf, guint32 len, guint64 pts, 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 diff --git a/include/wearable/player.h b/include/wearable/player.h index 483638d..42c7073 100644 --- a/include/wearable/player.h +++ b/include/wearable/player.h @@ -348,8 +348,8 @@ typedef void (*player_video_captured_cb)(unsigned char *data, int width, int hei * @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 @@ -485,7 +485,7 @@ int player_prepare_async(player_h player, player_prepared_cb callback, void* use /** * @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 @@ -495,7 +495,7 @@ int player_prepare_async(player_h player, player_prepared_cb callback, void* use * @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() */ @@ -507,11 +507,13 @@ int player_unprepare(player_h player); * @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 * @@ -535,6 +537,8 @@ int player_set_uri(player_h player, const char * uri); * 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 @@ -627,7 +631,9 @@ int player_set_sound_type(player_h player, sound_type_e type) TIZEN_DEPRECATED_A * @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 @@ -642,6 +648,22 @@ int player_set_sound_type(player_h player, sound_type_e type) TIZEN_DEPRECATED_A * @see #sound_stream_info_h * @see sound_manager_create_stream_information() * @see sound_manager_destroy_stream_information() + * @par Example + @code + #include + #include + ... + 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); @@ -649,7 +671,7 @@ int player_set_sound_stream_info(player_h player, sound_stream_info_h stream_inf * @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 @@ -787,7 +809,7 @@ int player_pause(player_h player); * @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, @@ -900,6 +922,8 @@ int player_is_looping(player_h player, bool *looping); * @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 @@ -921,8 +945,8 @@ int player_set_display(player_h player, player_display_type_e type, player_displ /** * @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 @@ -937,7 +961,7 @@ int player_set_display(player_h player, player_display_type_e type, player_displ * @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); @@ -950,7 +974,7 @@ int player_set_media_packet_video_frame_decoded_cb(player_h player, player_media * 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); @@ -958,7 +982,7 @@ 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 @@ -980,11 +1004,11 @@ int player_push_media_stream(player_h player, media_packet_h packet); /** * @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 @@ -1002,7 +1026,7 @@ int player_set_media_stream_info(player_h player, player_stream_type_e type, med * @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 @@ -1038,7 +1062,7 @@ int player_unset_media_stream_buffer_status_cb(player_h player, player_stream_ty * @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 @@ -1159,14 +1183,13 @@ int player_get_media_stream_buffer_min_threshold(player_h player, player_stream_ * @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() @@ -1195,7 +1218,7 @@ int player_get_display_mode(player_h player, player_display_mode_e *mode); * @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 @@ -1207,7 +1230,7 @@ int player_get_display_mode(player_h player, player_display_mode_e *mode); * @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() @@ -1607,9 +1630,9 @@ int player_audio_effect_equalizer_is_available(player_h player, bool *available) * @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() */ @@ -1618,6 +1641,8 @@ int player_capture_video(player_h player, player_video_captured_cb callback, voi /** * @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 @@ -1628,6 +1653,7 @@ int player_capture_video(player_h player, player_video_captured_cb callback, voi * @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); @@ -1635,6 +1661,8 @@ 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 @@ -1645,6 +1673,7 @@ int player_set_streaming_cookie(player_h player, const char *cookie, int size); * @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); @@ -1794,8 +1823,10 @@ int player_unset_buffering_cb(player_h player); * @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, @@ -1893,6 +1924,8 @@ int player_set_playback_rate(player_h player, float rate); * @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, @@ -1903,14 +1936,13 @@ int player_set_playback_rate(player_h player, float rate); * @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 @@ -1961,7 +1993,9 @@ int player_set_subtitle_position_offset(player_h player, int millisecond); * @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 -- 2.34.1