2 * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __TIZEN_MEDIADEMUXER_H__
18 #define __TIZEN_MEDIADEMUXER_H__
22 #include <media_format.h>
23 #include <media_packet.h>
27 #endif /* __cplusplus */
30 * @file mediademuxer.h
31 * @brief This file contains the capi media demuxer API.
35 * @addtogroup CAPI_MEDIADEMUXER_MODULE
40 * @brief Media Demuxer handle type.
43 typedef struct mediademuxer_s *mediademuxer_h;
46 * @brief Enumeration for media demuxer state
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 */
57 * @brief Enumeration for media demuxer error.
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;
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
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()
92 typedef void (*mediademuxer_error_cb) (mediademuxer_error_e error, void *user_data);
95 * @brief Called when end of stream occurs in media demuxer.
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()
105 typedef void (*mediademuxer_eos_cb) (int track_num, void *user_data);
108 * @brief Creates a media demuxer handle for demuxing.
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()
120 int mediademuxer_create(mediademuxer_h *demuxer);
123 * @brief Sets the source path of input stream.
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.
138 int mediademuxer_set_data_source(mediademuxer_h demuxer, const char *path);
141 * @brief Prepares the media demuxer for demuxing.
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 * @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()
156 int mediademuxer_prepare(mediademuxer_h demuxer);
159 * @brief Gets the total track count present in the container stream.
161 * @param[in] demuxer The media demuxer handle
162 * @param[out] count The number of tracks present
163 * @retval #MEDIADEMUXER_ERROR_NONE Successful
164 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
165 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
166 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
167 * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
168 * @see mediademuxer_prepare()
169 * @see mediademuxer_select_track()
171 int mediademuxer_get_track_count(mediademuxer_h demuxer, int *count);
174 * @brief Selects the track to be performed.
176 * @param[in] demuxer The media demuxer handle
177 * @param[in] track_index The track index on which is selected for read
178 * @return @c 0 on success, otherwise a negative error value
179 * @retval #MEDIADEMUXER_ERROR_NONE Successful
180 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
181 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
182 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
183 * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
184 * @see mediademuxer_get_track_count()
185 * @see mediademuxer_start()
187 int mediademuxer_select_track(mediademuxer_h demuxer, int track_index);
190 * @brief Starts the media demuxer.
192 * @remark User should call this before mediademuxer_read_sample() function.
193 * @param[in] demuxer The media demuxer handle
194 * @return @c 0 on success, otherwise a negative error value
195 * @retval #MEDIADEMUXER_ERROR_NONE Successful
196 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
197 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
198 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
199 * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
200 * @post The media demuxer state will be #MEDIADEMUXER_STATE_DEMUXING.
201 * @see mediademuxer_prepare()
202 * @see mediademuxer_get_track_count()
203 * @see mediademuxer_select_track()
204 * @see mediademuxer_get_track_info()
206 int mediademuxer_start(mediademuxer_h demuxer);
209 * @brief Retrieves the track format of the read sample.
211 * @remarks The @a format should be released using media_format_unref() function.
212 * @param[in] demuxer The media demuxer handle
213 * @param[in] track_index The index of the track
214 * @param[out] format The media format handle
215 * @return @c 0 on success, otherwise a negative error value
216 * @retval #MEDIADEMUXER_ERROR_NONE Successful
217 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
218 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
219 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
220 * @pre The media demuxer state must be set to #MEDIADEMUXER_STATE_DEMUXING by calling
221 * mediademuxer_start() or set to #MEDIADEMUXER_STATE_READY by calling mediademuxer_prepare().
222 * @see mediademuxer_get_track_count()
223 * @see mediademuxer_select_track()
224 * @see media_format_unref()
225 * @see #media_format_h
227 int mediademuxer_get_track_info(mediademuxer_h demuxer, int track_index, media_format_h *format);
230 * @brief Reads a frame(sample) of one single track.
232 * @remark The @a outbuf should be released using media_packet_destroy() function.
233 * @remark Once this API is called, user app can call the mediatool APIs to extract
234 * side information such as pts, size, duration, flags etc.
235 * @param[in] demuxer The media demuxer handle
236 * @param[in] track_index The index of track of which data is needed
237 * @param[out] outbuf The media packet handle
238 * @return @c 0 on success, otherwise a negative error value
239 * @retval #MEDIADEMUXER_ERROR_NONE Successful
240 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
241 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
242 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
243 * @pre The media demuxer state should be #MEDIADEMUXER_STATE_DEMUXING.
244 * @see mediademuxer_start()
245 * @see mediademuxer_get_track_info()
246 * @see mediademuxer_seek() if need to seek to a particular location
247 * @see mediademuxer_unselect_track()
248 * @see mediademuxer_stop()
249 * @see media_packet_destroy()
250 * @see #media_packet_h
252 int mediademuxer_read_sample(mediademuxer_h demuxer, int track_index, media_packet_h *outbuf);
255 * @brief Seeks to a particular instance of time (in milli seconds).
257 * @remark If mediademuxer_seek() is followed by mediademuxer_read_sample(), outbuf will be the key frame right before the seek position.
258 * @param[in] demuxer The media demuxer handle
259 * @param[in] pos The value of the new start position
260 * @return @c 0 on success, otherwise a negative error value
261 * @retval #MEDIADEMUXER_ERROR_NONE Successful
262 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
263 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
264 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
265 * @pre The media demuxer state should be #MEDIADEMUXER_STATE_DEMUXING.
266 * @see mediademuxer_read_sample()
267 * @see mediademuxer_stop()
269 int mediademuxer_seek(mediademuxer_h demuxer, int64_t pos);
272 * @brief Unselects the selected track.
274 * @param[in] demuxer The media demuxer handle
275 * @param[in] track_index The track index to be unselected
276 * @return @c 0 on success, otherwise a negative error value
277 * @retval #MEDIADEMUXER_ERROR_NONE Successful
278 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
279 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
280 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
281 * @pre The media demuxer state must be set to #MEDIADEMUXER_STATE_DEMUXING by calling
282 * mediademuxer_read_sample() or set to #MEDIADEMUXER_STATE_READY by calling mediademuxer_select_track().
283 * @see mediademuxer_select_track()
284 * @see mediademuxer_read_sample()
286 int mediademuxer_unselect_track(mediademuxer_h demuxer, int track_index);
289 * @brief Stops the media demuxer.
291 * @remark User can call this if need to stop demuxing if needed.
292 * @param[in] demuxer The media demuxer handle
293 * @return @c 0 on success, otherwise a negative error value
294 * @retval #MEDIADEMUXER_ERROR_NONE Successful
295 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
296 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
297 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
298 * @pre The media demuxer state must be set to #MEDIADEMUXER_STATE_DEMUXING.
299 * @post The media demuxer state will be in #MEDIADEMUXER_STATE_READY.
300 * @see mediademuxer_start()
301 * @see mediademuxer_unprepare()
303 int mediademuxer_stop(mediademuxer_h demuxer);
306 * @brief Resets the media demuxer.
308 * @remarks User should call this before mediademuxer_destroy() function.
309 * @param[in] demuxer The media demuxer handle
310 * @return @c 0 on success, otherwise a negative error value
311 * @retval #MEDIADEMUXER_ERROR_NONE Successful
312 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
313 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
314 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
315 * @pre The media demuxer state should be #MEDIADEMUXER_STATE_READY.
316 * @post The media demuxer state will be #MEDIADEMUXER_STATE_IDLE.
317 * @see mediademuxer_prepare()
319 int mediademuxer_unprepare(mediademuxer_h demuxer);
322 * @brief Removes the instance of media demuxer and clear all its context memory.
324 * @param[in] demuxer The media demuxer handle
325 * @return @c 0 on success, otherwise a negative error value
326 * @retval #MEDIADEMUXER_ERROR_NONE Successful
327 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
328 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
329 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid Operation
330 * @pre Create a media demuxer handle by calling mediademuxer_create() function.
331 * @post The media demuxer state will be #MEDIADEMUXER_STATE_NONE.
332 * @see mediademuxer_create()
334 int mediademuxer_destroy(mediademuxer_h demuxer);
337 * @brief Gets media demuxer state.
339 * @param[in] demuxer The media demuxer handle
340 * @param[out] state The media demuxer sate
341 * @return @c 0 on success, otherwise a negative error value
342 * @retval #MEDIADEMUXER_ERROR_NONE Successful
343 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
344 * @retval #MEDIADEMUXER_ERROR_INVALID_OPERATION Invalid operation
345 * @pre Create a media demuxer handle by calling mediademuxer_create() function.
346 * @see #mediademuxer_state
348 int mediademuxer_get_state(mediademuxer_h demuxer, mediademuxer_state *state);
351 * @brief Registers an error callback function to be invoked when an error occurs.
353 * @param[in] demuxer The media demuxer handle
354 * @param[in] callback Callback function pointer
355 * @param[in] user_data The user data passed from the code where
356 * mediademuxer_set_error_cb() was invoked
357 * This data will be accessible from mediademuxer_error_cb()
358 * @return @c 0 on success, otherwise a negative error value
359 * @retval #MEDIADEMUXER_ERROR_NONE Successful
360 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
361 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
362 * @pre Create a media demuxer handle by calling mediademuxer_create() function.
363 * @post mediademuxer_error_cb() will be invoked.
364 * @see mediademuxer_unset_error_cb()
365 * @see mediademuxer_error_cb()
367 int mediademuxer_set_error_cb(mediademuxer_h demuxer, mediademuxer_error_cb callback, void *user_data);
370 * @brief Unregisters the error callback function.
372 * @param[in] demuxer The media demuxer handle
373 * @return @c 0 on success, otherwise a negative error value
374 * @retval #MEDIADEMUXER_ERROR_NONE Successful
375 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
376 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
377 * @see mediademuxer_error_cb()
379 int mediademuxer_unset_error_cb(mediademuxer_h demuxer);
382 * @brief Registers an eos callback function to be invoked when an eos occurs.
384 * @param[in] demuxer The media demuxer handle
385 * @param[in] callback Callback function pointer
386 * @param[in] user_data The user data passed from the code where
387 * mediademuxer_set_eos_cb() was invoked
388 * This data will be accessible from mediademuxer_eos_cb()
389 * @return @c 0 on success, otherwise a negative error value
390 * @retval #MEDIADEMUXER_ERROR_NONE Successful
391 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
392 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
393 * @pre Create a media demuxer handle by calling mediademuxer_create() function.
394 * @post mediademuxer_eos_cb() will be invoked.
395 * @see mediademuxer_unset_eos_cb()
396 * @see mediademuxer_eos_cb()
398 int mediademuxer_set_eos_cb(mediademuxer_h demuxer, mediademuxer_eos_cb callback, void *user_data);
401 * @brief Unregisters the eos callback function.
403 * @param[in] demuxer The media demuxer handle
404 * @return @c 0 on success, otherwise a negative error value
405 * @retval #MEDIADEMUXER_ERROR_NONE Successful
406 * @retval #MEDIADEMUXER_ERROR_INVALID_PARAMETER Invalid parameter
407 * @retval #MEDIADEMUXER_ERROR_INVALID_STATE Invalid state
408 * @see mediademuxer_eos_cb()
410 int mediademuxer_unset_eos_cb(mediademuxer_h demuxer);
419 #endif /* __TIZEN_MEDIADEMUXER_H__ */