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_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 */
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 * @post The media demuxer state will be #MEDIADEMUXER_STATE_READY.
152 * @see mediademuxer_set_data_source()
153 * @see mediademuxer_unprepare()
155 int mediademuxer_prepare(mediademuxer_h demuxer);
158 * @brief Gets the total track count present in the container stream.
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()
170 int mediademuxer_get_track_count(mediademuxer_h demuxer, int *count);
173 * @brief Selects the track to be performed.
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()
186 int mediademuxer_select_track(mediademuxer_h demuxer, int track_index);
189 * @brief Starts the media demuxer.
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()
205 int mediademuxer_start(mediademuxer_h demuxer);
208 * @brief Retrieves the track format of the read sample.
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
226 int mediademuxer_get_track_info(mediademuxer_h demuxer, int track_index, media_format_h *format);
229 * @brief Reads a frame(sample) of one single track.
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
251 int mediademuxer_read_sample(mediademuxer_h demuxer, int track_index, media_packet_h *outbuf);
254 * @brief Seeks to a particular instance of time (in micro seconds).
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()
267 int mediademuxer_seek(mediademuxer_h demuxer, int64_t pos);
270 * @brief Unselects the selected track.
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()
284 int mediademuxer_unselect_track(mediademuxer_h demuxer, int track_index);
287 * @brief Stops the media demuxer.
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()
301 int mediademuxer_stop(mediademuxer_h demuxer);
304 * @brief Resets the media demuxer.
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()
317 int mediademuxer_unprepare(mediademuxer_h demuxer);
320 * @brief Removes the instance of media demuxer and clear all its context memory.
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()
332 int mediademuxer_destroy(mediademuxer_h demuxer);
335 * @brief Gets media demuxer state.
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
346 int mediademuxer_get_state(mediademuxer_h demuxer, mediademuxer_state *state);
349 * @brief Registers an error callback function to be invoked when an error occurs.
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()
365 int mediademuxer_set_error_cb(mediademuxer_h demuxer, mediademuxer_error_cb callback, void *user_data);
368 * @brief Unregisters the error callback function.
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()
377 int mediademuxer_unset_error_cb(mediademuxer_h demuxer);
380 * @brief Registers an eos callback function to be invoked when an eos occurs.
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()
396 int mediademuxer_set_eos_cb(mediademuxer_h demuxer, mediademuxer_eos_cb callback, void *user_data);
399 * @brief Unregisters the eos callback function.
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()
408 int mediademuxer_unset_eos_cb(mediademuxer_h demuxer);
417 #endif /* __TIZEN_MEDIADEMUXER_H__ */