include/mediademuxer.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 #ifndef __TIZEN_MEDIADEMUXER_H__
  18 #define __TIZEN_MEDIADEMUXER_H__
  19
  20 #include <tizen.h>
  21 #include <stdint.h>
  22 #include <media_format.h>
  23 #include <media_packet.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif  /* __cplusplus */
  28
  29 /**
  30  * @file mediademuxer.h
  31  * @brief This file contains the capi media demuxer API.
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_MEDIADEMUXER_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Media Demuxer handle type.
  41  * @since_tizen 3.0
  42  */
  43 typedef struct mediademuxer_s *mediademuxer_h;
  44
  45 /**
  46  * @brief Enumeration for media demuxer state
  47  * @since_tizen 3.0
  48  */
  49 typedef enum {
  50         MEDIADEMUXER_NONE,              /**< The mediademuxer is not created */
  51         MEDIADEMUXER_IDLE,                      /**< The mediademuxer is created, but not prepared */
  52         MEDIADEMUXER_READY,             /**< The mediademuxer is ready to demux media */
  53         MEDIADEMUXER_DEMUXING           /**< The mediademuxer is demuxing media */
  54 } mediademuxer_state;
  55
  56 /**
  57  * @brief Enumeration for media demuxer error.
  58  * @since_tizen 3.0
  59  */
  60 typedef enum {
  61         MEDIADEMUXER_ERROR_NONE = TIZEN_ERROR_NONE,     /*< Successful */
  62         MEDIADEMUXER_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,   /**< Out of memory */
  63         MEDIADEMUXER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  64         MEDIADEMUXER_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,   /**< Invalid operation */
  65         MEDIADEMUXER_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,   /**< Not supported */
  66         MEDIADEMUXER_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,   /**< Permission denied */
  67         MEDIADEMUXER_ERROR_INVALID_STATE = TIZEN_ERROR_MEDIA_DEMUXER | 0x01,    /**< Invalid state */
  68         MEDIADEMUXER_ERROR_INVALID_PATH = TIZEN_ERROR_MEDIA_DEMUXER | 0x02,     /**< Invalid path */
  69         MEDIADEMUXER_ERROR_RESOURCE_LIMIT = TIZEN_ERROR_MEDIA_DEMUXER | 0x03,   /**< Resource limit */
  70         MEDIADEMUXER_ERROR_SEEK_FAILED = TIZEN_ERROR_MEDIA_DEMUXER | 0x04,      /**< Seek operation failure */
  71         MEDIADEMUXER_ERROR_DRM_NOT_PERMITTED = TIZEN_ERROR_MEDIA_DEMUXER | 0x05 /**< Not permitted format */
  72 } mediademuxer_error_e;
  73
  74 /**
  75  * @brief Called when error occurs in media demuxer.
  76  * @details Following error codes can be delivered.
  77  *          #MEDIADEMUXER_ERROR_INVALID_OPERATION,
  78  *          #MEDIADEMUXER_ERROR_NOT_SUPPORTED,
  79  *          #MEDIADEMUXER_ERROR_INVALID_PATH,
  80  *          #MEDIADEMUXER_ERROR_RESOURCE_LIMIT,
  81  *          #MEDIADEMUXER_ERROR_SEEK_FAILED,
  82  *          #MEDIADEMUXER_ERROR_DRM_NOT_PERMITTED
  83  * @since_tizen 3.0
  84  * @param[in] error  The error that occurred in media demuxer
  85  * @param[in] user_data   The user data passed from the code where
  86  *                         mediademuxer_set_error_cb() was invoked
  87  *                         This data will be accessible from mediademuxer_error_cb()
  88  * @pre Create media demuxer handle by calling mediademuxer_create() function.
  89  * @see mediademuxer_set_error_cb()
  90  * @see mediademuxer_unset_error_cb()
  91  */
  92 typedef void (*mediademuxer_error_cb) (mediademuxer_error_e error, void *user_data);
  93
  94 /**
  95  * @brief Called when end of stream occurs in media demuxer.
  96  * @since_tizen 3.0
  97  * @param[in] track_num  The track_num which indicate eos for which track number occured
  98  * @param[in] user_data   The user data passed from the code where
  99  *                         mediademuxer_set_eos_cb() was invoked
 100  *                         This data will be accessible from mediademuxer_eos_cb()
 101  * @pre Create media demuxer handle by calling mediademuxer_create() function.
 102  * @see mediademuxer_set_eos_cb()
 103  * @see mediademuxer_unset_eos_cb()
 104  */
 105 typedef void (*mediademuxer_eos_cb) (int track_num, void *user_data);
 106
 107 /**
 108  * @brief Creates a media demuxer handle for demuxing.
 109  * @since_tizen 3.0
 110  * @remarks You must release @a demuxer using mediademuxer_destroy() function.
 111  * @param[out] demuxer    A new handle to media demuxer
 112  * @return @c 0 on success, otherwise a negative error value
 113  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 114  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 115  * @retval #MEDIADEMUXER_ERROR_OUT_OF_MEMORY Out of memory
 116  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 117  * @post The media demuxer state will be #MEDIADEMUXER_STATE_IDLE.
 118  * @see mediademuxer_destroy()
 119  */
 120 int mediademuxer_create(mediademuxer_h *demuxer);
 121
 122 /**
 123  * @brief Sets the source path of input stream.
 124  * @since_tizen 3.0
 125  * @remarks The mediastorage privilege(http://tizen.org/privilege/mediastorage) should be added if any video/audio files are used to play located in the internal storage.
 126  * @remarks The externalstorage privilege(http://tizen.org/privilege/externalstorage) should be added if any video/audio files are used to play located in the external storage.
 127  * @remarks You must release @a demuxer using mediademuxer_destroy() function.
 128  * @param[in] demuxer    The media demuxer handle
 129  * @param[in] path    The content location, such as the file path
 130  * @return @c 0 on success, otherwise a negative error value
 131  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 132  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 133  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 134  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 135  * @retval #MEDIADEMUXER_ERROR_INVALID_PATH Invalid path
 136  * @pre The media muxer state will be #MEDIADEMUXER_STATE_IDLE by calling mediademuxer_create() function.
 137  * */
 138 int mediademuxer_set_data_source(mediademuxer_h demuxer, const char *path);
 139
 140 /**
 141  * @brief Prepares the media demuxer for demuxing.
 142  * @since_tizen 3.0
 143  * @remark User should call this before mediademuxer_start() function.
 144  * @param[in] demuxer    The media demuxer handle
 145  * @return @c 0 on success, otherwise a negative error value
 146  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 147  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 148  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 149  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 150  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_IDLE.
 151  * @post The media demuxer state will be #MEDIADEMUXER_STATE_READY.
 152  * @see mediademuxer_set_data_source()
 153  * @see mediademuxer_unprepare()
 154  * */
 155 int mediademuxer_prepare(mediademuxer_h demuxer);
 156
 157 /**
 158  * @brief Gets the total track count present in the container stream.
 159  * @since_tizen 3.0
 160  * @param[in] demuxer    The media demuxer handle
 161  * @param[out] count     The number of tracks present
 162  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 163  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 164  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 165  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 166  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
 167  * @see mediademuxer_prepare()
 168  * @see mediademuxer_select_track()
 169  * */
 170 int mediademuxer_get_track_count(mediademuxer_h demuxer, int *count);
 171
 172 /**
 173  * @brief Selects the track to be performed.
 174  * @since_tizen 3.0
 175  * @param[in] demuxer    The media demuxer handle
 176  * @param[in] track_index      The track index on which is selected for read
 177  * @return @c 0 on success, otherwise a negative error value
 178  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 179  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 180  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 181  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 182  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
 183  * @see mediademuxer_get_track_count()
 184  * @see mediademuxer_start()
 185  * */
 186 int mediademuxer_select_track(mediademuxer_h demuxer, int track_index);
 187
 188 /**
 189  * @brief Starts the media demuxer.
 190  * @since_tizen 3.0
 191  * @remark User should call this before mediademuxer_read_sample() function.
 192  * @param[in] demuxer    The media demuxer handle
 193  * @return @c 0 on success, otherwise a negative error value
 194  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 195  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 196  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 197  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 198  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
 199  * @post The media demuxer state will be #MEDIADEMUXER_STATE_DEMUXING.
 200  * @see mediademuxer_prepare()
 201  * @see mediademuxer_get_track_count()
 202  * @see mediademuxer_select_track()
 203  * @see mediademuxer_get_track_info()
 204  * */
 205 int mediademuxer_start(mediademuxer_h demuxer);
 206
 207 /**
 208  * @brief Retrieves the track format of the read sample.
 209  * @since_tizen 3.0
 210  * @remarks The @a format should be released using media_format_unref() function.
 211  * @param[in] demuxer    The media demuxer handle
 212  * @param[in] track_index     The index of the track
 213  * @param[out] format    The media format handle
 214  * @return @c 0 on success, otherwise a negative error value
 215  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 216  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 217  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 218  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 219  * @pre The media demuxer state must be set to #MEDIADEMUXER_STATE_DEMUXING by calling
 220  *      mediademuxer_start() or set to #MEDIADEMUXER_STATE_READY by calling mediademuxer_prepare().
 221  * @see mediademuxer_get_track_count()
 222  * @see mediademuxer_select_track()
 223  * @see media_format_unref()
 224  * @see #media_format_h
 225  * */
 226 int mediademuxer_get_track_info(mediademuxer_h demuxer, int track_index, media_format_h *format);
 227
 228 /**
 229  * @brief Reads a frame(sample) of one single track.
 230  * @since_tizen 3.0
 231  * @remark The @a outbuf should be released using media_packet_destroy() function.
 232  * @remark Once this API is called, user app can call the mediatool APIs to extract
 233  *          side information such as pts, size, duration, flags etc.
 234  * @param[in] demuxer    The media demuxer handle
 235  * @param[in] track_index      The index of track of which data is needed
 236  * @param[out] outbuf      The media packet handle
 237  * @return @c 0 on success, otherwise a negative error value
 238  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 239  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 240  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 241  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 242  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_DEMUXING.
 243  * @see mediademuxer_start()
 244  * @see mediademuxer_get_track_info()
 245  * @see mediademuxer_seek() if need to seek to a particular location
 246  * @see mediademuxer_unselect_track()
 247  * @see mediademuxer_stop()
 248  * @see media_packet_destroy()
 249  * @see #media_packet_h
 250  * */
 251 int mediademuxer_read_sample(mediademuxer_h demuxer, int track_index, media_packet_h *outbuf);
 252
 253 /**
 254  * @brief Seeks to a particular instance of time (in micro seconds).
 255  * @since_tizen 3.0
 256  * @param[in] demuxer    The media demuxer handle
 257  * @param[in] pos       The value of the new start position
 258  * @return @c 0 on success, otherwise a negative error value
 259  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 260  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 261  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 262  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 263 * @pre The media demuxer state should be #MEDIADEMUXER_STATE_DEMUXING.
 264  * @see mediademuxer_read_sample()
 265  * @see mediademuxer_stop()
 266  * */
 267 int mediademuxer_seek(mediademuxer_h demuxer, int64_t pos);
 268
 269 /**
 270  * @brief Unselects the selected track.
 271  * @since_tizen 3.0
 272  * @param[in] demuxer    The media demuxer handle
 273  * @param[in] track_index      The track index to be unselected
 274  * @return @c 0 on success, otherwise a negative error value
 275  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 276  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 277  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 278  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 279  * @pre The media demuxer state must be set to #MEDIADEMUXER_STATE_DEMUXING by calling
 280  *      mediademuxer_read_sample() or set to #MEDIADEMUXER_STATE_READY by calling mediademuxer_select_track().
 281  * @see mediademuxer_select_track()
 282  * @see mediademuxer_read_sample()
 283  * */
 284 int mediademuxer_unselect_track(mediademuxer_h demuxer, int track_index);
 285
 286 /**
 287  * @brief Stops the media demuxer.
 288  * @since_tizen 3.0
 289  * @remark User can call this if need to stop demuxing if needed.
 290  * @param[in] demuxer    The media demuxer handle
 291  * @return @c 0 on success, otherwise a negative error value
 292  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 293  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 294  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 295  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 296  * @pre The media demuxer state must be set to #MEDIADEMUXER_STATE_DEMUXING.
 297  * @post The media demuxer state will be in  #MEDIADEMUXER_READY.
 298  * @see mediademuxer_start()
 299  * @see mediademuxer_unprepare()
 300  * */
 301 int mediademuxer_stop(mediademuxer_h demuxer);
 302
 303 /**
 304  * @brief Resets the media demuxer.
 305  * @since_tizen 3.0
 306  * @remarks User should call this before mediademuxer_destroy() function.
 307  * @param[in] demuxer    The media demuxer handle
 308  * @return @c 0 on success, otherwise a negative error value
 309  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 310  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 311  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 312  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 313  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
 314  * @post The media demuxer state will be #MEDIADEMUXER_STATE_IDLE.
 315  * @see mediademuxer_prepare()
 316  * */
 317 int mediademuxer_unprepare(mediademuxer_h demuxer);
 318
 319 /**
 320  * @brief Removes the instance of media demuxer and clear all its context memory.
 321  * @since_tizen 3.0
 322  * @param[in] demuxer    The media demuxer handle
 323  * @return @c 0 on success, otherwise a negative error value
 324  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 325  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 326  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 327  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 328  * @pre Create a media demuxer handle by calling mediademuxer_create() function.
 329  * @post The media demuxer state will be #MEDIADEMUXER_STATE_NONE.
 330  * @see mediademuxer_create()
 331  * */
 332 int mediademuxer_destroy(mediademuxer_h demuxer);
 333
 334 /**
 335  * @brief Gets media demuxer state.
 336  * @since_tizen 3.0
 337  * @param[in] demuxer   The media demuxer handle
 338  * @param[out] state   The media demuxer sate
 339  * @return @c 0 on success, otherwise a negative error value
 340  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 341  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 342  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid operation
 343  * @pre Create a media demuxer handle by calling mediademuxer_create() function.
 344  * @see #mediademuxer_state
 345  * */
 346 int mediademuxer_get_state(mediademuxer_h demuxer, mediademuxer_state *state);
 347
 348 /**
 349  * @brief Registers an error callback function to be invoked when an error occurs.
 350  * @since_tizen 3.0
 351  * @param[in] demuxer   The media demuxer handle
 352  * @param[in] callback  Callback function pointer
 353  * @param[in] user_data   The user data passed from the code where
 354  *                         mediademuxer_set_error_cb() was invoked
 355  *                         This data will be accessible from mediademuxer_error_cb()
 356  * @return @c 0 on success, otherwise a negative error value
 357  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 358  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 359  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 360  * @pre Create a media demuxer handle by calling mediademuxer_create() function.
 361  * @post mediademuxer_error_cb() will be invoked.
 362  * @see mediademuxer_unset_error_cb()
 363  * @see mediademuxer_error_cb()
 364  * */
 365 int mediademuxer_set_error_cb(mediademuxer_h demuxer, mediademuxer_error_cb callback, void *user_data);
 366
 367 /**
 368  * @brief Unregisters the error callback function.
 369  * @since_tizen 3.0
 370  * @param[in] demuxer   The media demuxer handle
 371  * @return @c 0 on success, otherwise a negative error value
 372  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 373  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 374  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 375  * @see mediademuxer_error_cb()
 376  * */
 377 int mediademuxer_unset_error_cb(mediademuxer_h demuxer);
 378
 379 /**
 380  * @brief Registers an eos callback function to be invoked when an eos occurs.
 381  * @since_tizen 3.0
 382  * @param[in] demuxer   The media demuxer handle
 383  * @param[in] callback  Callback function pointer
 384  * @param[in] user_data   The user data passed from the code where
 385  *                         mediademuxer_set_eos_cb() was invoked
 386  *                         This data will be accessible from mediademuxer_eos_cb()
 387  * @return @c 0 on success, otherwise a negative error value
 388  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 389  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 390  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 391  * @pre Create a media demuxer handle by calling mediademuxer_create() function.
 392  * @post mediademuxer_eos_cb() will be invoked.
 393  * @see mediademuxer_unset_eos_cb()
 394  * @see mediademuxer_eos_cb()
 395  * */
 396 int mediademuxer_set_eos_cb(mediademuxer_h demuxer, mediademuxer_eos_cb callback, void *user_data);
 397
 398 /**
 399  * @brief Unregisters the eos callback function.
 400  * @since_tizen 3.0
 401  * @param[in] demuxer   The media demuxer handle
 402  * @return @c 0 on success, otherwise a negative error value
 403  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 404  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 405  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 406  * @see mediademuxer_eos_cb()
 407  * */
 408 int mediademuxer_unset_eos_cb(mediademuxer_h demuxer);
 409
 410 /**
 411  * @}
 412  */
 413
 414 #ifdef __cplusplus
 415 }
 416 #endif
 417 #endif  /* __TIZEN_MEDIADEMUXER_H__ */