doc/player_doc.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_MEDIA_PLAYER_DOC_H__
  19 #define __TIZEN_MEDIA_PLAYER_DOC_H__
  20
  21
  22 /**
  23  * @file player_doc.h
  24  * @brief This file contains high level documentation on the Player API.
  25  */
  26
  27 /**
  28  * @ingroup CAPI_MEDIA_FRAMEWORK
  29  * @defgroup CAPI_MEDIA_PLAYER_MODULE Player
  30  * @brief The @ref CAPI_MEDIA_PLAYER_MODULE API provides functions for media playback and controlling media playback attributes.
  31  *
  32  * @section CAPI_MEDIA_PLAYER_MODULE_HEADER Required Header
  33  *    \#include <player.h>
  34  *
  35  * @section CAPI_MEDIA_PLAYER_OVERVIEW Overview
  36  * The Player API provides a way to play multimedia content. Content can be played from a file, from the network, or from memory.
  37  * It gives the ability to start/stop/pause/mute, set the playback position (that is, seek), perform various status queries, and control the display.
  38  *
  39  * Additional functions allow registering notifications via callback functions for various state change events.
  40  *
  41  * This API also enables collaboration with the GUI service to present a video.
  42  *
  43  * @subsection CAPI_MEDIA_PLAYER_LIFE_CYCLE_STATE_DIAGRAM State Diagram
  44  * Playback of multimedia content is controlled by a state machine.
  45  * The following diagram shows the life cycle and states of the Player.
  46  *
  47  * @image html capi_media_player_state_diagram.png
  48  *
  49  * @subsection CAPI_MEDIA_PLAYER_LIFE_CYCLE_STATE_TRANSITIONS State Transitions
  50  * <div><table class="doxtable" >
  51  *     <tr>
  52  *        <th><b>FUNCTION</b></th>
  53  *        <th><b>PRE-STATE</b></th>
  54  *        <th><b>POST-STATE</b></th>
  55  *        <th><b>SYNC TYPE</b></th>
  56  *     </tr>
  57  *     <tr>
  58  *        <td>player_create()</td>
  59  *        <td>NONE</td>
  60  *        <td>IDLE</td>
  61  *        <td>SYNC</td>
  62  *     </tr>
  63  *     <tr>
  64  *         <td>player_destroy()</td>
  65  *         <td>IDLE</td>
  66  *         <td>NONE</td>
  67  *         <td>SYNC</td>
  68  *     </tr>
  69  *     <tr>
  70  *        <td>player_prepare()</td>
  71  *        <td>IDLE</td>
  72  *        <td>READY</td>
  73  *        <td>SYNC</td>
  74  *     </tr>
  75  *     <tr>
  76  *        <td>player_prepare_async()</td>
  77  *        <td>IDLE</td>
  78  *        <td>READY</td>
  79  *        <td>ASYNC</td>
  80  *     </tr>
  81  *     <tr>
  82  *        <td>player_unprepare()</td>
  83  *        <td>READY, PLAYING or PAUSED</td>
  84  *        <td>IDLE</td>
  85  *        <td>SYNC</td>
  86  *     </tr>
  87  *     <tr>
  88  *        <td>player_start()</td>
  89  *        <td>READY or PAUSED</td>
  90  *        <td>PLAYING</td>
  91  *        <td>SYNC</td>
  92  *     </tr>
  93  *     <tr>
  94  *        <td>player_stop()</td>
  95  *        <td>PLAYING</td>
  96  *        <td>READY</td>
  97  *        <td>SYNC</td>
  98  *     </tr>
  99  *     <tr>
 100  *        <td>player_pause()</td>
 101  *        <td>PLAYING</td>
 102  *        <td>PAUSED</td>
 103  *        <td>SYNC</td>
 104  *     </tr>
 105  * </table></div>
 106  *
 107  * @subsection CAPI_MEDIA_PLAYER_LIFE_CYCLE_STATE_DEPENDENT_FUNCTIONS State Dependent Function Calls
 108  * The following table shows state-dependent function calls.
 109  * It is forbidden to call the functions listed below in wrong states.
 110  * Violation of this rule may result in unpredictable behavior.
 111  * <div><table class="doxtable" >
 112  * <tr>
 113  *    <th><b>FUNCTION</b></th>
 114  *    <th><b>VALID STATES</b></th>
 115  *    <th><b>DESCRIPTION</b></th>
 116  * </tr>
 117  * <tr>
 118  *    <td>player_create()</td>
 119  *    <td>ANY</td>
 120  *    <td>-</td>
 121  * </tr>
 122  * <tr>
 123  *    <td>player_destroy()</td>
 124  *    <td>ANY</td>
 125  *    <td>-</td>
 126  * </tr>
 127  * <tr>
 128  *    <td>player_prepare()</td>
 129  *    <td>IDLE</td>
 130  *    <td>This function must be called after player_create()</td>
 131  * </tr>
 132  * <tr>
 133  *    <td>player_unprepare()</td>
 134  *    <td>READY/PAUSED/PLAYING</td>
 135  *    <td>This function must be called after player_stop() or player_start() or player_pause()</td>
 136  * </tr>
 137  * <tr>
 138  *    <td>player_start()</td>
 139  *    <td>READY/ PAUSED</td>
 140  *    <td>This function must be called after player_prepare()</td>
 141  * </tr>
 142  * <tr>
 143  *    <td>player_stop()</td>
 144  *    <td>PLAYING/ PAUSED</td>
 145  *    <td>This function must be called after player_start() or player_pause()</td>
 146  * </tr>
 147  * <tr>
 148  *    <td>player_pause()</td>
 149  *    <td>PLAYING</td>
 150  *    <td>This function must be called after player_start()</td>
 151  * </tr>
 152  * <tr>
 153  *    <td>player_set_completed_cb()<BR> player_set_interrupted_cb()<BR> player_set_error_cb()<BR> player_set_buffering_cb()<BR> player_set_subtitle_updated_cb()</td>
 154  *    <td>IDLE/ READY/ PLAYING/ PAUSED</td>
 155  *    <td>This function must be called after player_create()</td>
 156  * </tr>
 157  * <tr>
 158  *    <td>player_unset_completed_cb()<BR> player_unset_interrupted_cb()<BR> player_unset_error_cb()<BR> player_unset_buffering_cb()<BR> player_unset_subtitle_updated_cb()</td>
 159  *    <td>IDLE/ READY/ PLAYING/ PAUSED</td>
 160  *    <td>This function must be called after register callback functions such as player_set_completed_cb()</td>
 161  * </tr>
 162  * <tr>
 163  *    <td>player_get_state()</td>
 164  *    <td>ANY</td>
 165  *    <td>-</td>
 166  * </tr>
 167  * <tr>
 168  *    <td>player_set_uri()</td>
 169  *    <td>IDLE</td>
 170  *    <td>This function must be called before player_prepare() </td>
 171  * </tr>
 172  * <tr>
 173  *    <td>player_set_memory_buffer()</td>
 174  *    <td>IDLE</td>
 175  *    <td>This function must be called before player_prepare() </td>
 176  * </tr>
 177  * <tr>
 178  *    <td>player_set_subtitle_path()</td>
 179  *    <td>IDLE</td>
 180  *    <td>This function must be called before player_prepare() </td>
 181  * </tr>
 182  * <tr>
 183  *    <td>player_set_volume()</td>
 184  *    <td>IDLE/ READY/ PLAYING/ PAUSED</td>
 185  *    <td>This function must be called after player_create()</td>
 186  * </tr>
 187  * <tr>
 188  *    <td>player_get_volume()</td>
 189  *    <td>IDLE/ READY/ PLAYING/ PAUSED</td>
 190  *    <td>This function must be called after player_create()</td>
 191  * </tr>
 192  * <tr>
 193  *    <td>player_set_sound_type()</td>
 194  *    <td>IDLE</td>
 195  *    <td>This function must be called after player_create()</td>
 196  * </tr>
 197  * <tr>
 198  *    <td>player_set_mute()</td>
 199  *    <td>IDLE/ READY/ PLAYING/ PAUSED</td>
 200  *    <td>This function must be called after player_create()</td>
 201  * </tr>
 202  * <tr>
 203  *    <td>player_is_muted()</td>
 204  *    <td>IDLE/ READY/ PLAYING/ PAUSED</td>
 205  *    <td>This function must be called after player_create()</td>
 206  * </tr>
 207  * <tr>
 208  *    <td>player_set_looping()</td>
 209  *    <td>IDLE/ READY/ PLAYING/ PAUSED</td>
 210  *    <td>This function must be called after player_create()</td>
 211  * </tr>
 212  * <tr>
 213  *    <td>player_is_looping()</td>
 214  *    <td>IDLE/ READY/ PLAYING/ PAUSED</td>
 215  *    <td>This function must be called after player_create()</td>
 216  * </tr>
 217  * <tr>
 218  *    <td>player_get_duration()</td>
 219  *    <td>PLAYING/ PAUSED</td>
 220  *    <td>This function must be called after player_start()</td>
 221  * </tr>
 222  * <tr>
 223  *    <td>player_set_display()</td>
 224  *    <td>IDLE</td>
 225  *    <td>This function must be called before player_prepare()</td>
 226  * </tr>
 227  * <tr>
 228  *    <td>player_set_display_mode() <BR> player_set_display_visible()</td>
 229  *    <td>IDLE/ READY/ PLAYING/ PAUSED</td>
 230  *    <td>This function must be called after player_create()</td>
 231  * </tr>
 232   * <tr>
 233  *    <td>player_get_display_rotation() <BR> player_is_display_visible()</td>
 234  *    <td>IDLE/ READY/ PLAYING/ PAUSED</td>
 235  *    <td>This function must be called after player_create()</td>
 236  * </tr>
 237  * <tr>
 238  *    <td>player_get_video_size()</td>
 239  *    <td>READY/ PLAYING/ PAUSED</td>
 240  *    <td>This function must be called after player_prepare()</td>
 241  * </tr>
 242  * </table></div>
 243  *
 244  * @subsection CAPI_MEDIA_PLAYER_LIFE_CYCLE_ASYNCHRONOUS_OPERATIONS Asynchronous Operations
 245  * All functions that change the player state are synchronous except player_prepare_async(), player_set_play_position(), and player_capture_video().
 246  * Thus the result is passed to the application via the callback mechanism.
 247  *
 248  * @subsection CAPI_MEDIA_PLAYER_LIFE_CYCLE_CALLBACK_OPERATIONS Callback(Event) Operations
 249  * <div><table class="doxtable" >
 250  *     <tr>
 251  *        <th><b>REGISTER</b></th>
 252  *        <th><b>UNREGISTER</b></th>
 253  *        <th><b>CALLBACK</b></th>
 254  *        <th><b>DESCRIPTION</b></th>
 255  *     </tr>
 256  *               <tr>
 257  *        <td>player_set_completed_cb()</td>
 258  *        <td>player_unset_completed_cb()</td>
 259  *        <td>player_completed_cb()</td>
 260  *        <td>called when playback is completed </td>
 261  *     </tr>
 262  *               <tr>
 263  *        <td>player_set_interrupted_cb()</td>
 264  *        <td>player_unset_interrupted_cb()</td>
 265  *        <td>player_interrupted_cb()</td>
 266  *        <td>called when playback is interrupted by #player_interrupted_code_e </td>
 267  *     </tr>
 268  *               <tr>
 269  *        <td>player_set_error_cb()</td>
 270  *        <td>player_unset_error_cb()</td>
 271  *        <td>player_error_cb()</td>
 272  *        <td>called when an error has occurred</td>
 273  *     </tr>
 274  *               <tr>
 275  *        <td>player_set_buffering_cb()</td>
 276  *        <td>player_unset_buffering_cb()</td>
 277  *        <td>player_buffering_cb()</td>
 278  *        <td>called during content buffering </td>
 279  *     </tr>
 280  *               <tr>
 281  *        <td>player_set_progressive_download_message_cb()</td>
 282  *        <td>player_unset_progressive_download_message_cb()</td>
 283  *        <td>player_pd_message_cb()</td>
 284  *        <td>called when a progressive download starts or completes</td>
 285  *     </tr>
 286  *               <tr>
 287  *        <td>player_set_subtitle_updated_cb()</td>
 288  *        <td>player_unset_subtitle_updated_cb()</td>
 289  *        <td>player_subtitle_updated_cb()</td>
 290  *        <td>called when a subtitle updates </td>
 291  *     </tr>
 292  *               <tr>
 293  *        <td>player_set_media_packet_video_frame_decoded_cb()</td>
 294  *        <td>player_unset_media_packet_video_frame_decoded_cb()</td>
 295  *        <td>player_media_packet_video_decoded_cb()</td>
 296  *        <td>called when a video frame is decoded </td>
 297  *     </tr>
 298
 299  *</table></div>
 300  *
 301  */
 302
 303
 304 /**
 305  * @ingroup CAPI_MEDIA_PLAYER_MODULE
 306  * @defgroup CAPI_MEDIA_PLAYER_DISPLAY_MODULE Display
 307  * @brief The @ref CAPI_MEDIA_PLAYER_DISPLAY_MODULE API provides functions to control the display.
 308  * @section CAPI_MEDIA_PLAYER_DISPLAY_MODULE_HEADER Required Header
 309  *    \#include <player.h>
 310  *
 311  * @section CAPI_MEDIA_PLAYER_DISPLAY_MODULE_OVERVIEW Overview
 312  * The API allows you to manage the display of the player.
 313  * This API provides functions to set and get various display properties:
 314  * - mode
 315  * - rotation
 316  * - visibility
 317  *
 318 */
 319
 320 /**
 321  * @ingroup CAPI_MEDIA_PLAYER_MODULE
 322  * @defgroup CAPI_MEDIA_PLAYER_STREAM_INFO_MODULE Stream Information
 323  * @brief The @ref CAPI_MEDIA_PLAYER_STREAM_INFO_MODULE API provides functions to get audio and video stream information, such as codec type, video width or height, bit rate, and so on.
 324  * @section CAPI_MEDIA_PLAYER_AUDIO_EFFECT_MODULE_HEADER Required Header
 325  *    \#include <player.h>
 326  *
 327  * @section CAPI_MEDIA_PLAYER_STREAM_INFO_MODULE_OVERVIEW Overview
 328  * The Player stream information API allows you to get media stream information, including:
 329  * - Content metadata, such as the tile, artist, album title and genre.
 330  * - Audio stream information, such as audio codec type, sample rate, channels, and bit rate.
 331  * - Video stream information, such as video codec type, video width and height.
 332  *
 333 */
 334
 335 /**
 336  * @ingroup CAPI_MEDIA_PLAYER_MODULE
 337  * @defgroup CAPI_MEDIA_PLAYER_AUDIO_EFFECT_MODULE Audio Effect
 338  * @brief The @ref CAPI_MEDIA_PLAYER_AUDIO_EFFECT_MODULE API provides functions to control the audio effect.
 339  * @section CAPI_MEDIA_PLAYER_AUDIO_EFFECT_MODULE_HEADER Required Header
 340  *    \#include <player.h>
 341  *
 342  * @section CAPI_MEDIA_PLAYER_AUDIO_EFFECT_MODULE_MODULE_OVERVIEW Overview
 343  * The Audio effect API allows you to apply effects to the player:
 344  * - Equalizer
 345  *
 346  *
 347 */
 348
 349 /**
 350  * @ingroup CAPI_MEDIA_PLAYER_MODULE
 351  * @defgroup CAPI_MEDIA_PLAYER_SUBTITLE_MODULE Subtitle
 352  * @brief The @ref CAPI_MEDIA_PLAYER_SUBTITLE_MODULE API provides functions to control the subtitle.
 353  * @section CAPI_MEDIA_PLAYER_SUBTITLE_MODULE_HEADER Required Header
 354  *    \#include <player.h>
 355  *
 356  *
 357 */
 358
 359 #endif /* __TIZEN_MEDIA_PLAYER_DOC_H__ */