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_MULTIMEDIA_MEDIADEMUXER_H__
  18 #define __TIZEN_MULTIMEDIA_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_STATE_NONE,                /**< The mediademuxer is not created */
  51         MEDIADEMUXER_STATE_IDLE,                /**< The mediademuxer is created, but not prepared */
  52         MEDIADEMUXER_STATE_READY,               /**< The mediademuxer is ready to demux media */
  53         MEDIADEMUXER_STATE_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  * @remarks 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  * @pre mediademuxer_set_error_cb should be called before mediademuxer_prepare().
 152  * @post The media demuxer state will be #MEDIADEMUXER_STATE_READY.
 153  * @see mediademuxer_set_data_source()
 154  * @see mediademuxer_unprepare()
 155  * */
 156 int mediademuxer_prepare(mediademuxer_h demuxer);
 157
 158 /**
 159  * @brief Gets the total track count present in the container stream.
 160  * @since_tizen 3.0
 161  * @param[in]  demuxer The media demuxer handle
 162  * @param[out] count   The number of tracks present
 163  * @return @c 0 on success, otherwise a negative error value
 164  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 165  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 166  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 167  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 168  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
 169  * @see mediademuxer_prepare()
 170  * @see mediademuxer_select_track()
 171  * */
 172 int mediademuxer_get_track_count(mediademuxer_h demuxer, int *count);
 173
 174 /**
 175  * @brief Selects the track to be performed.
 176  * @since_tizen 3.0
 177  * @param[in] demuxer     The media demuxer handle
 178  * @param[in] track_index The track index on which is selected for read
 179  * @return @c 0 on success, otherwise a negative error value
 180  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 181  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 182  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 183  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 184  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
 185  * @see mediademuxer_get_track_count()
 186  * @see mediademuxer_start()
 187  * */
 188 int mediademuxer_select_track(mediademuxer_h demuxer, int track_index);
 189
 190 /**
 191  * @brief Starts the media demuxer.
 192  * @since_tizen 3.0
 193  * @remarks User should call this before mediademuxer_read_sample() function.
 194  * @param[in] demuxer The media demuxer handle
 195  * @return @c 0 on success, otherwise a negative error value
 196  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 197  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 198  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 199  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 200  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
 201  * @post The media demuxer state will be #MEDIADEMUXER_STATE_DEMUXING.
 202  * @see mediademuxer_prepare()
 203  * @see mediademuxer_get_track_count()
 204  * @see mediademuxer_select_track()
 205  * @see mediademuxer_get_track_info()
 206  * */
 207 int mediademuxer_start(mediademuxer_h demuxer);
 208
 209 /**
 210  * @brief Retrieves the track format of the read sample.
 211  * @since_tizen 3.0
 212  * @remarks The @a format should be released using media_format_unref() function.
 213  * @param[in]  demuxer     The media demuxer handle
 214  * @param[in]  track_index The index of the track
 215  * @param[out] format      The media format handle
 216  * @return @c 0 on success, otherwise a negative error value
 217  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 218  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 219  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 220  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 221  * @pre The media demuxer state must be set to #MEDIADEMUXER_STATE_DEMUXING by calling
 222  *      mediademuxer_start() or set to #MEDIADEMUXER_STATE_READY by calling mediademuxer_prepare().
 223  * @see mediademuxer_get_track_count()
 224  * @see mediademuxer_select_track()
 225  * @see media_format_unref()
 226  * @see #media_format_h
 227  * */
 228 int mediademuxer_get_track_info(mediademuxer_h demuxer, int track_index, media_format_h *format);
 229
 230 /**
 231  * @brief Reads a frame(sample) of one single track.
 232  * @since_tizen 3.0
 233  * @remarks The @a outbuf should be released using media_packet_destroy() function.
 234  * @remarks Once this function is called, user app can call the mediatool APIs to extract
 235  *          side information such as pts, size, duration, flags etc.
 236  * @param[in]  demuxer     The media demuxer handle
 237  * @param[in]  track_index The index of track of which data is needed
 238  * @param[out] outbuf      The media packet handle
 239  * @return @c 0 on success, otherwise a negative error value
 240  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 241  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 242  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 243  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 244  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_DEMUXING.
 245  * @see mediademuxer_start()
 246  * @see mediademuxer_get_track_info()
 247  * @see mediademuxer_seek() if need to seek to a particular location
 248  * @see mediademuxer_unselect_track()
 249  * @see mediademuxer_stop()
 250  * @see media_packet_destroy()
 251  * @see #media_packet_h
 252  * */
 253 int mediademuxer_read_sample(mediademuxer_h demuxer, int track_index, media_packet_h *outbuf);
 254
 255 /**
 256  * @brief Seeks to a particular instance of time (in milli seconds).
 257  * @since_tizen 3.0
 258  * @remarks If mediademuxer_seek() is followed by mediademuxer_read_sample(), outbuf will be the key frame right before the seek position.
 259  * @param[in] demuxer The media demuxer handle
 260  * @param[in] pos     The value of the new start position
 261  * @return @c 0 on success, otherwise a negative error value
 262  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 263  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 264  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 265  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 266  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_DEMUXING.
 267  * @see mediademuxer_read_sample()
 268  * @see mediademuxer_stop()
 269  * */
 270 int mediademuxer_seek(mediademuxer_h demuxer, int64_t pos);
 271
 272 /**
 273  * @brief Unselects the selected track.
 274  * @since_tizen 3.0
 275  * @param[in] demuxer     The media demuxer handle
 276  * @param[in] track_index The track index to be unselected
 277  * @return @c 0 on success, otherwise a negative error value
 278  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 279  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 280  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 281  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 282  * @pre The media demuxer state must be set to #MEDIADEMUXER_STATE_DEMUXING by calling
 283  *      mediademuxer_read_sample() or set to #MEDIADEMUXER_STATE_READY by calling mediademuxer_select_track().
 284  * @see mediademuxer_select_track()
 285  * @see mediademuxer_read_sample()
 286  * */
 287 int mediademuxer_unselect_track(mediademuxer_h demuxer, int track_index);
 288
 289 /**
 290  * @brief Stops the media demuxer.
 291  * @since_tizen 3.0
 292  * @remarks User can call this if need to stop demuxing if needed.
 293  * @param[in] demuxer The media demuxer handle
 294  * @return @c 0 on success, otherwise a negative error value
 295  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 296  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 297  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 298  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 299  * @pre The media demuxer state must be set to #MEDIADEMUXER_STATE_DEMUXING.
 300  * @post The media demuxer state will be in  #MEDIADEMUXER_STATE_READY.
 301  * @see mediademuxer_start()
 302  * @see mediademuxer_unprepare()
 303  * */
 304 int mediademuxer_stop(mediademuxer_h demuxer);
 305
 306 /**
 307  * @brief Resets the media demuxer.
 308  * @since_tizen 3.0
 309  * @remarks User should call this before mediademuxer_destroy() function.
 310  * @param[in] demuxer The media demuxer handle
 311  * @return @c 0 on success, otherwise a negative error value
 312  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 313  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 314  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 315  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 316  * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
 317  * @post The media demuxer state will be #MEDIADEMUXER_STATE_IDLE.
 318  * @see mediademuxer_prepare()
 319  * */
 320 int mediademuxer_unprepare(mediademuxer_h demuxer);
 321
 322 /**
 323  * @brief Removes the instance of media demuxer and clear all its context memory.
 324  * @since_tizen 3.0
 325  * @param[in] demuxer The media demuxer handle
 326  * @return @c 0 on success, otherwise a negative error value
 327  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 328  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 329  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 330  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
 331  * @pre Create a media demuxer handle by calling mediademuxer_create() function.
 332  * @post The media demuxer state will be #MEDIADEMUXER_STATE_NONE.
 333  * @see mediademuxer_create()
 334  * */
 335 int mediademuxer_destroy(mediademuxer_h demuxer);
 336
 337 /**
 338  * @brief Gets media demuxer state.
 339  * @since_tizen 3.0
 340  * @param[in]  demuxer The media demuxer handle
 341  * @param[out] state   The media demuxer sate
 342  * @return @c 0 on success, otherwise a negative error value
 343  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 344  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 345  * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid operation
 346  * @pre Create a media demuxer handle by calling mediademuxer_create() function.
 347  * @see #mediademuxer_state
 348  * */
 349 int mediademuxer_get_state(mediademuxer_h demuxer, mediademuxer_state *state);
 350
 351 /**
 352  * @brief Sets an error callback function to be invoked when an error occurs.
 353  * @since_tizen 3.0
 354  * @param[in] demuxer   The media demuxer handle
 355  * @param[in] callback  Callback function pointer
 356  * @param[in] user_data The user data passed from the code where
 357  *                       mediademuxer_set_error_cb() was invoked
 358  *                       This data will be accessible from mediademuxer_error_cb()
 359  * @return @c 0 on success, otherwise a negative error value
 360  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 361  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 362  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 363  * @pre Create a media demuxer handle by calling mediademuxer_create() function.
 364  * @post mediademuxer_error_cb() will be invoked.
 365  * @see mediademuxer_unset_error_cb()
 366  * @see mediademuxer_error_cb()
 367  * */
 368 int mediademuxer_set_error_cb(mediademuxer_h demuxer, mediademuxer_error_cb callback, void *user_data);
 369
 370 /**
 371  * @brief Unsets the error callback function.
 372  * @since_tizen 3.0
 373  * @param[in] demuxer The media demuxer handle
 374  * @return @c 0 on success, otherwise a negative error value
 375  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 376  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 377  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 378  * @see mediademuxer_error_cb()
 379  * */
 380 int mediademuxer_unset_error_cb(mediademuxer_h demuxer);
 381
 382 /**
 383  * @brief Sets an eos callback function to be invoked when an eos occurs.
 384  * @since_tizen 3.0
 385  * @param[in] demuxer   The media demuxer handle
 386  * @param[in] callback  Callback function pointer
 387  * @param[in] user_data The user data passed from the code where
 388  *                       mediademuxer_set_eos_cb() was invoked
 389  *                       This data will be accessible from mediademuxer_eos_cb()
 390  * @return @c 0 on success, otherwise a negative error value
 391  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 392  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 393  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 394  * @pre Create a media demuxer handle by calling mediademuxer_create() function.
 395  * @post mediademuxer_eos_cb() will be invoked.
 396  * @see mediademuxer_unset_eos_cb()
 397  * @see mediademuxer_eos_cb()
 398  * */
 399 int mediademuxer_set_eos_cb(mediademuxer_h demuxer, mediademuxer_eos_cb callback, void *user_data);
 400
 401 /**
 402  * @brief Unsets the eos callback function.
 403  * @since_tizen 3.0
 404  * @param[in] demuxer The media demuxer handle
 405  * @return @c 0 on success, otherwise a negative error value
 406  * @retval #MEDIADEMUXER_ERROR_NONE Successful
 407  * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
 408  * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
 409  * @see mediademuxer_eos_cb()
 410  * */
 411 int mediademuxer_unset_eos_cb(mediademuxer_h demuxer);
 412
 413 /**
 414  * @}
 415  */
 416
 417 #ifdef __cplusplus
 418 }
 419 #endif
 420 #endif  /* __TIZEN_MULTIMEDIA_MEDIADEMUXER_H__ */