include/mediademuxer_port.h

   1 /*
   2  * Copyright (c) 2015 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  * @file mediademuxer_port.h
  19  * @brief general port based functions. sets specific function pointers
  20  */
  21
  22 #ifndef __TIZEN_MEDIADEMUXER_PORT_H__
  23 #define __TIZEN_MEDIADEMUXER_PORT_H__
  24
  25 /*===========================================================================================
  26 |                                                                                           |
  27 |  INCLUDE FILES                                        |
  28 |                                                                                           |
  29 ========================================================================================== */
  30
  31 #include <glib.h>
  32 #include <mm_types.h>
  33 #include <mm_message.h>
  34 #include <media_format.h>
  35 #include <mediademuxer_util.h>
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /**
  42     @{
  43
  44     @par
  45     This part describes APIs used for playback of multimedia contents.
  46     All multimedia contents are created by a media demuxer through handle of playback.
  47     In creating a demuxer, it displays the demuxer's status or information
  48     by registering callback function.
  49
  50     @par
  51     In case of streaming playback, network has to be opend by using datanetwork API.
  52     If proxy, cookies and the other attributes for streaming playback are needed,
  53     set those attributes using mm_demuxer_set_attribute() before create demuxer.
  54
  55     @par
  56     The subtitle for local video playback is supported. Set "subtitle_uri" attribute
  57     using mm_demuxer_set_attribute() before the application creates the demuxer.
  58     Then the application could receive MMMessageParamType which includes subtitle string and duration.
  59
  60     @par
  61     MediaDemuxer can have 5 states, and each state can be changed by calling
  62     described functions on "Figure1. State of MediaDemuxer".
  63
  64     @par
  65     @image html         demuxer_state.jpg       "Figure1. State of MediaDemuxer"        width=12cm
  66     @image latex        demuxer_state.jpg       "Figure1. State of MediaDemuxer"        width=12cm
  67
  68     @par
  69     Most of functions which change demuxer state work as synchronous. But, mm_demuxer_start() should be used
  70     asynchronously. Both mm_demuxer_pause() and mm_demuxer_resume() should also be used asynchronously
  71     in the case of streaming data.
  72     So, application have to confirm the result of those APIs through message callback function.
  73
  74     @par
  75     Note that "None" and Null" state could be reached from any state
  76     by calling mm_demuxer_destroy() and mm_demuxer_unrealize().
  77
  78     @par
  79     <div><table>
  80     <tr>
  81     <td><B>FUNCTION</B></td>
  82     <td><B>PRE-STATE</B></td>
  83     <td><B>POST-STATE</B></td>
  84     <td><B>SYNC TYPE</B></td>
  85     </tr>
  86     <tr>
  87     <td>md_create()</td>
  88     <td>NONE</td>
  89     <td>NULL</td>
  90     <td>SYNC</td>
  91     </tr>
  92     <tr>
  93     <td>md_destroy()</td>
  94     <td>NULL</td>
  95     <td>NONE</td>
  96     <td>SYNC</td>
  97     </tr>
  98     <tr>
  99     <td>md_set_data_source()</td>
 100     <td>NULL</td>
 101     <td>READY</td>
 102     <td>SYNC</td>
 103     </tr>
 104     </table></div>
 105
 106     @par
 107     Following are the attributes supported in demuxer which may be set after initialization. \n
 108     Those are handled as a string.
 109
 110     @par
 111     <div><table>
 112     <tr>
 113     <td>PROPERTY</td>
 114     <td>TYPE</td>
 115     <td>VALID TYPE</td>
 116     </tr>
 117     <tr>
 118     <td>"profile_uri"</td>
 119     <td>string</td>
 120     <td>N/A</td>
 121     </tr>
 122     <tr>
 123     <td>"content_duration"</td>
 124     <td>int</td>
 125     <td>range</td>
 126     </tr>
 127     <tr>
 128     <td>"content_video_width"</td>
 129     <td>int</td>
 130     <td>range</td>
 131     </tr>
 132     <tr>
 133     <td>"content_video_height"</td>
 134     <td>int</td>
 135     <td>range</td>
 136     </tr>
 137     <tr>
 138     <td>"profile_user_param"</td>
 139     <td>data</td>
 140     <td>N/A</td>
 141     </tr>
 142     <tr>
 143     <td>"profile_play_count"</td>
 144     <td>int</td>
 145     <td>range</td>
 146     </tr>
 147     <tr>
 148     <td>"streaming_type"</td>
 149     <td>int</td>
 150     <td>range</td>
 151     </tr>
 152     <tr>
 153     <td>"streaming_udp_timeout"</td>
 154     <td>int</td>
 155     <td>range</td>
 156     </tr>
 157     <tr>
 158     <td>"streaming_user_agent"</td>
 159     <td>string</td>
 160     <td>N/A</td>
 161     </tr>
 162     <tr>
 163     <td>"streaming_wap_profile"</td>
 164     <td>string</td>
 165     <td>N/A</td>
 166     </tr>
 167     <tr>
 168     <td>"streaming_network_bandwidth"</td>
 169     <td>int</td>
 170     <td>range</td>
 171     </tr>
 172     <tr>
 173     <td>"streaming_cookie"</td>
 174     <td>string</td>
 175     <td>N/A</td>
 176     </tr>
 177     <tr>
 178     <td>"streaming_proxy_ip"</td>
 179     <td>string</td>
 180     <td>N/A</td>
 181     </tr>
 182     <tr>
 183     <td>"streaming_proxy_port"</td>
 184     <td>int</td>
 185     <td>range</td>
 186     </tr>
 187     <tr>
 188     <td>"subtitle_uri"</td>
 189     <td>string</td>
 190     <td>N/A</td>
 191     </tr>
 192     </table></div>
 193
 194     @par
 195     Following attributes are supported for playing stream data. Those value can be readable only and valid after starting playback.\n
 196     Please use mm_fileinfo for local playback.
 197
 198     @par
 199     <div><table>
 200     <tr>
 201     <td>PROPERTY</td>
 202     <td>TYPE</td>
 203     <td>VALID TYPE</td>
 204     </tr>
 205     <tr>
 206     <td>"content_video_found"</td>
 207     <td>string</td>
 208     <td>N/A</td>
 209     </tr>
 210     <tr>
 211     <td>"content_video_codec"</td>
 212     <td>string</td>
 213     <td>N/A</td>
 214     </tr>
 215     <tr>
 216     <td>"content_video_track_num"</td>
 217     <td>int</td>
 218     <td>range</td>
 219     </tr>
 220     <tr>
 221     <td>"content_audio_found"</td>
 222     <td>string</td>
 223     <td>N/A</td>
 224     </tr>
 225     <tr>
 226     <td>"content_audio_codec"</td>
 227     <td>string</td>
 228     <td>N/A</td>
 229     </tr>
 230     <tr>
 231     <td>"content_audio_bitrate"</td>
 232     <td>int</td>
 233     <td>array</td>
 234     </tr>
 235     <tr>
 236     <td>"content_audio_channels"</td>
 237     <td>int</td>
 238     <td>range</td>
 239     </tr>
 240     <tr>
 241     <td>"content_audio_samplerate"</td>
 242     <td>int</td>
 243     <td>array</td>
 244     </tr>
 245     <tr>
 246     <td>"content_audio_track_num"</td>
 247     <td>int</td>
 248     <td>range</td>
 249     </tr>
 250     <tr>
 251     <td>"content_text_track_num"</td>
 252     <td>int</td>
 253     <td>range</td>
 254     </tr>
 255     <tr>
 256     <td>"tag_artist"</td>
 257     <td>string</td>
 258     <td>N/A</td>
 259     </tr>
 260     <tr>
 261     <td>"tag_title"</td>
 262     <td>string</td>
 263     <td>N/A</td>
 264     </tr>
 265     <tr>
 266     <td>"tag_album"</td>
 267     <td>string</td>
 268     <td>N/A</td>
 269     </tr>
 270     <tr>
 271     <td>"tag_genre"</td>
 272     <td>string</td>
 273     <td>N/A</td>
 274     </tr>
 275     <tr>
 276     <td>"tag_author"</td>
 277     <td>string</td>
 278     <td>N/A</td>
 279     </tr>
 280     <tr>
 281     <td>"tag_copyright"</td>
 282     <td>string</td>
 283     <td>N/A</td>
 284     </tr>
 285     <tr>
 286     <td>"tag_date"</td>
 287     <td>string</td>
 288     <td>N/A</td>
 289     </tr>
 290     <tr>
 291     <td>"tag_description"</td>
 292     <td>string</td>
 293     <td>N/A</td>
 294     </tr>
 295     <tr>
 296     <td>"tag_track_num"</td>
 297     <td>int</td>
 298     <td>range</td>
 299     </tr>
 300     </table></div>
 301
 302  */
 303
 304 /*===========================================================================================
 305 |                                                                                           |
 306 |  GLOBAL DEFINITIONS AND DECLARATIONS                                        |
 307 |                                                                                           |
 308 ========================================================================================== */
 309 /**
 310  * @brief Called when error occurs in media demuxer.
 311  * @details Following error codes can be delivered.
 312  *          #MEDIADEMUXER_ERROR_INVALID_OPERATION,
 313  *          #MEDIADEMUXER_ERROR_NOT_SUPPORTED,
 314  *          #MEDIADEMUXER_ERROR_INVALID_PATH,
 315  *          #MEDIADEMUXER_ERROR_RESOURCE_LIMIT,
 316  *          #MEDIADEMUXER_ERROR_SEEK_FAILED,
 317  *          #MEDIADEMUXER_ERROR_DRM_NOT_PERMITTED
 318  * @since_tizen 3.0
 319  * @param[in] error  The error that occurred in media demuxer
 320  * @param[in] user_data   The user data passed from the code where
 321  *                         mediademuxer_set_error_cb() was invoked
 322  *                         This data will be accessible from @a mediademuxer_error_cb
 323  * @pre Create media demuxer handle by calling mediademuxer_create() function.
 324  * @see mediademuxer_set_error_cb()
 325  * @see mediademuxer_unset_error_cb()
 326  */
 327 typedef void (*md_error_cb)(mediademuxer_error_e error, void *user_data);
 328
 329 /**
 330  * @brief Called when eos occurs in media demuxer.
 331  * @since_tizen 3.0
 332  * @param[in] track_num  The track_num which indicate eos has occurred in which track numbe
 333  * @param[in] user_data   The user data passed from the code where
 334  *                         mediademuxer_set_eos_cb() was invoked
 335  *                         This data will be accessible from @a mediademuxer_eos_cb
 336  * @pre Create media demuxer handle by calling mediademuxer_create() function.
 337  * @see mediademuxer_set_eos_cb()
 338  * @see mediademuxer_unset_eos_cb()
 339  */
 340 typedef void (*md_eos_cb)(int track_num, void *user_data);
 341
 342 /**
 343  * Enumerations of demuxer state.
 344  */
 345 /**
 346  * Attribute validity structure
 347  */
 348 typedef struct _media_port_demuxer_ops {
 349         unsigned int n_size;
 350         int (*init)(MMHandleType *pHandle);
 351         int (*prepare)(MMHandleType pHandle, char *uri);
 352         int (*get_track_count)(MMHandleType pHandle, int *count);
 353         int (*set_track)(MMHandleType pHandle, int track);
 354         int (*start)(MMHandleType pHandle);
 355         int (*get_track_info)(MMHandleType pHandle, media_format_h *format, int track);
 356         int (*read_sample)(MMHandleType pHandle, media_packet_h *outbuf, int track_indx);
 357         int (*seek)(MMHandleType pHandle, int64_t pos1);
 358         int (*unset_track)(MMHandleType pHandle, int track);
 359         int (*stop)(MMHandleType pHandle);
 360         int (*unprepare)(MMHandleType pHandle);
 361         int (*destroy)(MMHandleType pHandle);
 362         int (*set_error_cb)(MMHandleType demuxer, md_error_cb callback, void *user_data);
 363         int (*set_eos_cb)(MMHandleType demuxer, md_eos_cb callback, void *user_data);
 364         int (*get_data)(MMHandleType pHandle, char *buffer);
 365 } media_port_demuxer_ops;
 366
 367 /*===========================================================================================
 368 |                                                                                           |
 369 |  GLOBAL FUNCTION PROTOTYPES                                        |
 370 |                                                                                           |
 371 ========================================================================================== */
 372
 373 /**
 374  * This function creates a demuxer object for parsing multimedia contents. \n
 375  * The attributes of demuxer are created to get/set some values with application. \n
 376  * And, proper port is selected to do the actual parsing of the mdia.
 377  *
 378  * @param   demuxer [out]   Handle of demuxer
 379  *
 380  * @return  This function returns zero on success, or negative value with error code. \n
 381  *          Please refer 'mm_demuxer_error.h' to know it in detail.
 382  *
 383  * @par Example
 384  * @code
 385   MMHandleType demuxer;
 386   md_create(&demuxer);
 387   ...
 388   md_destroy(&demuxer);
 389  * @endcode
 390  */
 391 int md_create(MMHandleType *demuxer);
 392
 393 /**
 394  * This function sets the input data source to parse. \n
 395  * The source can be a local file or remote server file
 396  *
 397  * @param   demuxer     [in]    Handle of demuxer
 398  * @param   uri         [in]    absolute path for the source media
 399  *
 400  * @return  This function returns zero on success, or negative value with error code. \n
 401  *          Please refer 'mm_demuxer_error.h' to know it in detail.
 402  *
 403  * @par Example
 404  * @code
 405   MPhandle demuxer;
 406   md_create(&demuxer);
 407   if (md_set_data_source(demuxer) != MM_ERROR_NONE)
 408 {
 409     MD_E("failed to set the source \n");
 410 }
 411   md_destroy(&demuxer);
 412  * @endcode
 413  */
 414 int md_set_data_source(MMHandleType demuxer, const char *uri);
 415
 416 /**
 417  * This function releases demuxer object and all resources which were created by md_create(). \n
 418  * And, demuxer handle will also be destroyed.
 419  *
 420  * @param   demuxer     [in]    Handle of demuxer
 421  *
 422  * @return  This function returns zero on success, or negative value with error code.
 423  * @see     md_create
 424  *
 425  * @par Example
 426  * @code
 427 if (md_destroy(g_demuxer) != MM_ERROR_NONE)
 428 {
 429     MD_E("failed to destroy demuxer\n");
 430 }
 431  * @endcode
 432  */
 433 int md_destroy(MMHandleType demuxer);
 434
 435 /**
 436  * This function set up the internal structure of gstreamer, ffmpeg & custom to handle data set up md_set_data_source
 437  *
 438  * @param   demuxer     [in]    Handle of demuxer
 439  *
 440  * @return  This function returns zero on success, or negative value with error code.
 441  * @see     md_set_data_source
 442  *
 443  * @par Example
 444  * @code
 445 if (md_prepare(g_demuxer) != MM_ERROR_NONE)
 446 {
 447     MD_E("failed to prepare demuxer\n");
 448 }
 449  * @endcode
 450  */
 451 int md_prepare(MMHandleType demuxer);
 452
 453 /**
 454  * This function get the total number of tracks present in the stream.
 455  *
 456  * @param   demuxer     [in]    Handle of demuxer
 457  * @param   count     [out]    Total track number of streams available in the media
 458  *
 459  * @return  This function returns zero on success, or negative value with error code.
 460  * @see     md_set_data_source
 461  *
 462  * @par Example
 463  * @code
 464 if (md_get_track_count(g_demuxer,count) != MM_ERROR_NONE)
 465 {
 466         MD_E("failed to get count\n");
 467 }
 468  * @endcode
 469  */
 470 int md_get_track_count(MMHandleType demuxer, int *count);
 471
 472 /**
 473  * This function get the  format of selected track present in the stream.
 474  *
 475  * @param   demuxer            [in]    Handle of demuxer
 476  * @param   track              [in]    index for the track
 477  * @param   format             [out]   pointer to the Handle of media_format
 478  *
 479  * @return  This function returns zero on success, or negative value with error code.
 480  *
 481  * @par Example
 482  * @code
 483 if (md_get_track_info(g_demuxer, format, track) != MM_ERROR_NONE)
 484 {
 485         MD_E("failed to get track info\n");
 486 }
 487  * @endcode
 488  */
 489 int md_get_track_info(MMHandleType demuxer, int track, media_format_h *format);
 490
 491 /**
 492  * This function start the pipeline(in case of gst port it set the pipeline to play state).
 493  *
 494  * @param   demuxer     [in]    Handle of demuxer
 495  *
 496  * @return  This function returns zero on success, or negative value with error code.
 497  */
 498 int md_start(MMHandleType demuxer);
 499
 500 /**
 501  * This function read a packet of data from demuxer
 502  *
 503  * @param   demuxer     [in]    Handle of demuxer
 504  * @param   track_indx  [in]   selected track number
 505  * @param   outbuf      [out]    demuxed packet
 506  *
 507  * @return  This function returns zero on success, or negative value with error code.
 508  */
 509 int md_read_sample(MMHandleType demuxer, int track_indx, media_packet_h *outbuf);
 510
 511 /**
 512  * This function stop the pipeline in case of gst_port
 513  *
 514  * @param   demuxer     [in]    Handle of demuxer
 515  *
 516  * @return  This function returns zero on success, or negative value with error code.
 517  * @see     md_set_data_source
 518  */
 519 int md_stop(MMHandleType demuxer);
 520
 521 /**
 522  * This function destroy the pipeline
 523  *
 524  * @param   demuxer     [in]    Handle of demuxer
 525  *
 526  * @return  This function returns zero on success, or negative value with error code.
 527  * @see     md_set_data_source
 528  */
 529 int md_unprepare(MMHandleType demuxer);
 530
 531 /**
 532  * This function is to select a track on which read need to be performed
 533  *
 534  * @param   demuxer     [in]    Handle of demuxer
 535  * @param   index       [in]    index for the track to be selected
 536  *
 537  * @return  This function returns zero on success, or negative value with error code.
 538  * @see     md_set_data_source
 539  */
 540 int md_select_track(MMHandleType demuxer, int index);
 541
 542 /**
 543  * This function is to unselect a track on which readsample can't be performed
 544  *
 545  * @param   demuxer     [in]    Handle of demuxer
 546  * @param   index       [in]    index for the track to be selected
 547  *
 548  * @return  This function returns zero on success, or negative value with error code.
 549  * @see     md_set_data_source
 550  */
 551 int md_unselect_track(MMHandleType demuxer, int index);
 552
 553 /**
 554  * This function is to seek to a particular position relative to current position
 555  *
 556  * @param   demuxer     [in]    Handle of demuxer
 557  * @param   pos         [in]    relative position to seek
 558  *
 559  * @return  This function returns zero on success, or negative value with error code.
 560  * @see     md_set_data_source
 561  */
 562 int md_seek(MMHandleType demuxer, int64_t pos);
 563
 564 /**
 565  * This function is to set error call back function
 566  *
 567  * @param   demuxer     [in]    Handle of demuxer
 568  * @param   callback    [in]    call back function pointer
 569  * @param   user_data   [in]    user specific data pointer
 570  *
 571  * @return  This function returns zero on success, or negative value with error code.
 572  */
 573 int md_set_error_cb(MMHandleType demuxer, md_error_cb callback, void *user_data);
 574
 575 /**
 576  * This function is to set eos call back function
 577  *
 578  * @param   demuxer     [in]    Handle of demuxer
 579  * @param   callback    [in]    call back function pointer
 580  * @param   user_data   [in]    user specific data pointer
 581  *
 582  * @return  This function returns zero on success, or negative value with error code.
 583  */
 584 int md_set_eos_cb(MMHandleType demuxer, md_eos_cb callback, void *user_data);
 585
 586 #ifdef __cplusplus
 587 }
 588 #endif
 589 #endif  /* __TIZEN_MEDIADEMUXER_PORT_H__ */