1 /*****************************************************************************
2 * vlc_demux.h: Demuxer descriptor, queries and methods
3 *****************************************************************************
4 * Copyright (C) 1999-2005 VLC authors and VideoLAN
5 * $Id: f359f547fa79d9818ed74420d906a6683be3d037 $
6 *
7 * Authors: Laurent Aimar <fenrir@via.ecp.fr>
8 *
9 * This program is free software; you can redistribute it and/or modify it
10 * under the terms of the GNU Lesser General Public License as published by
11 * the Free Software Foundation; either version 2.1 of the License, or
12 * (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public License
20 * along with this program; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22 *****************************************************************************/
23
24 #ifndef VLC_DEMUX_H
25 #define VLC_DEMUX_H 1
26
27 #include <stdlib.h>
28 #include <string.h>
29
30 #include <vlc_es.h>
31 #include <vlc_stream.h>
32 #include <vlc_es_out.h>
33
34 /**
35 * \defgroup demux Demultiplexer
36 * \ingroup input
37 * Demultiplexers (file format parsers)
38 * @{
39 * \file
40 * Demultiplexer modules interface
41 */
42
43 struct demux_t
44 {
45 VLC_COMMON_MEMBERS
46
47 /* Module properties */
48 module_t *p_module;
49
50 /* eg informative but needed (we can have access+demux) */
51 char *psz_access;
52 char *psz_demux;
53 char *psz_location;
54 char *psz_file;
55
56 union {
57 /**
58 * Input stream
59 *
60 * Depending on the module capability:
61 * - "demux": input byte stream (not NULL)
62 * - "access_demux": a NULL pointer
63 * - "demux_filter": undefined
64 */
65 stream_t *s;
66 /**
67 * Input demuxer
68 *
69 * If the module capability is "demux_filter", this is the upstream
70 * demuxer or demux filter. Otherwise, this is undefined.
71 */
72 demux_t *p_next;
73 };
74
75 /* es output */
76 es_out_t *out; /* our p_es_out */
77
78 bool b_preparsing; /* True if the demux is used to preparse */
79
80 /* set by demuxer */
81 int (*pf_demux) ( demux_t * ); /* demux one frame only */
82 int (*pf_control)( demux_t *, int i_query, va_list args);
83
84 /* Demux has to maintain them uptodate
85 * when it is responsible of seekpoint/title */
86 struct
87 {
88 unsigned int i_update; /* Demux sets them on change,
89 Input removes them once take into account*/
90 /* Seekpoint/Title at demux level */
91 int i_title; /* idem, start from 0 (could be menu) */
92 int i_seekpoint; /* idem, start from 0 */
93 } info;
94 demux_sys_t *p_sys;
95
96 /* Weak link to parent input */
97 input_thread_t *p_input;
98 };
99
100 /* pf_demux return values */
101 #define VLC_DEMUXER_EOF 0
102 #define VLC_DEMUXER_EGENERIC -1
103 #define VLC_DEMUXER_SUCCESS 1
104
105 /* demux_t.info.i_update field */
106 #define INPUT_UPDATE_TITLE 0x0010
107 #define INPUT_UPDATE_SEEKPOINT 0x0020
108 #define INPUT_UPDATE_META 0x0040
109 #define INPUT_UPDATE_TITLE_LIST 0x0100
110
111 /* demux_meta_t is returned by "meta reader" module to the demuxer */
112 typedef struct demux_meta_t
113 {
114 VLC_COMMON_MEMBERS
115 input_item_t *p_item; /***< the input item that is being read */
116
117 vlc_meta_t *p_meta; /**< meta data */
118
119 int i_attachments; /**< number of attachments */
120 input_attachment_t **attachments; /**< array of attachments */
121 } demux_meta_t;
122
123 /**
124 * Control query identifiers for use with demux_t.pf_control
125 *
126 * In the individual identifier description, the input stream refers to
127 * demux_t.s if non-NULL, and the output refers to demux_t.out.
128 *
129 * A demuxer is synchronous if it only accesses its input stream and the
130 * output from within its demux_t callbacks, i.e. demux.pf_demux and
131 * demux_t.pf_control.
132 *
133 * A demuxer is threaded if it accesses either or both input and output
134 * asynchronously.
135 *
136 * An access-demuxer is a demuxer without input, i.e. demux_t.s == NULL).
137 */
138 enum demux_query_e
139 {
140 /** Checks whether the stream supports seeking.
141 * Can fail if seeking is not supported (same as returning false).
142 * \bug Failing should not be allowed.
143 *
144 * arg1 = bool * */
145 DEMUX_CAN_SEEK,
146
147 /** Checks whether (long) pause then stream resumption is supported.
148 * Can fail only if synchronous and <b>not</b> an access-demuxer. The
149 * underlying input stream then determines if pause is supported.
150 * \bug Failing should not be allowed.
151 *
152 * arg1= bool * */
153 DEMUX_CAN_PAUSE = 0x002,
154
155 /** Whether the stream can be read at an arbitrary pace.
156 * Cannot fail.
157 *
158 * arg1= bool * */
159 DEMUX_CAN_CONTROL_PACE,
160
161 /** Retrieves the PTS delay (roughly the default buffer duration).
162 * Can fail only if synchronous and <b>not</b> an access-demuxer. The
163 * underlying input stream then determines the PTS delay.
164 *
165 * arg1= int64_t * */
166 DEMUX_GET_PTS_DELAY = 0x101,
167
168 /** Retrieves stream meta-data.
169 * Should fail if no meta-data were retrieved.
170 *
171 * arg1= vlc_meta_t * */
172 DEMUX_GET_META = 0x105,
173
174 /** Retrieves an estimate of signal quality and strength.
175 * Can fail.
176 *
177 * arg1=double *quality, arg2=double *strength */
178 DEMUX_GET_SIGNAL = 0x107,
179
180 /** Sets the paused or playing/resumed state.
181 *
182 * Streams are initially in playing state. The control always specifies a
183 * change from paused to playing (false) or from playing to paused (true)
184 * and streams are initially playing; a no-op cannot be requested.
185 *
186 * The control is never used if DEMUX_CAN_PAUSE fails.
187 * Can fail.
188 *
189 * arg1= bool */
190 DEMUX_SET_PAUSE_STATE = 0x200,
191
192 /** Seeks to the beginning of a title.
193 *
194 * The control is never used if DEMUX_GET_TITLE_INFO fails.
195 * Can fail.
196 *
197 * arg1= int */
198 DEMUX_SET_TITLE,
199
200 /** Seeks to the beginning of a chapter of the current title.
201 *
202 * The control is never used if DEMUX_GET_TITLE_INFO fails.
203 * Can fail.
204 *
205 * arg1= int */
206 DEMUX_SET_SEEKPOINT, /* arg1= int can fail */
207
208 /** Check which INPUT_UPDATE_XXX flag is set and reset the ones set.
209 *
210 * The unsigned* argument is set with the flags needed to be checked,
211 * on return it contains the values that were reset during the call
212 *
213 * This can can fail, in which case flags from demux_t.info.i_update
214 * are read/reset
215 *
216 * arg1= unsigned * */
217 DEMUX_TEST_AND_CLEAR_FLAGS, /* arg1= unsigned* can fail */
218
219 /** Read the title number currently playing
220 *
221 * Can fail, in which case demux_t.info.i_title is used
222 *
223 * arg1= int * */
224 DEMUX_GET_TITLE, /* arg1= int* can fail */
225
226 /* Read the seekpoint/chapter currently playing
227 *
228 * Can fail, in which case demux_t.info.i_seekpoint is used
229 *
230 * arg1= int * */
231 DEMUX_GET_SEEKPOINT, /* arg1= int* can fail */
232
233 /* I. Common queries to access_demux and demux */
234 /* POSITION double between 0.0 and 1.0 */
235 DEMUX_GET_POSITION = 0x300, /* arg1= double * res= */
236 DEMUX_SET_POSITION, /* arg1= double arg2= bool b_precise res=can fail */
237
238 /* LENGTH/TIME in microsecond, 0 if unknown */
239 DEMUX_GET_LENGTH, /* arg1= int64_t * res= */
240 DEMUX_GET_TIME, /* arg1= int64_t * res= */
241 DEMUX_SET_TIME, /* arg1= int64_t arg2= bool b_precise res=can fail */
242
243 /**
244 * \todo Document
245 *
246 * \warning The prototype is different from STREAM_GET_TITLE_INFO
247 *
248 * Can fail, meaning there is only one title and one chapter.
249 *
250 * arg1= input_title_t ***, arg2=int *, arg3=int *pi_title_offset(0),
251 * arg4= int *pi_seekpoint_offset(0) */
252 DEMUX_GET_TITLE_INFO,
253
254 /* DEMUX_SET_GROUP/SET_ES only a hint for demuxer (mainly DVB) to allow not
255 * reading everything (you should not use this to call es_out_Control)
256 * if you don't know what to do with it, just IGNORE it, it is safe(r)
257 * -1 means all group, 0 default group (first es added) */
258 DEMUX_SET_GROUP, /* arg1= int, arg2=const vlc_list_t * can fail */
259 DEMUX_SET_ES, /* arg1= int can fail */
260
261 /* Ask the demux to demux until the given date at the next pf_demux call
262 * but not more (and not less, at the precision available of course).
263 * XXX: not mandatory (except for subtitle demux) but will help a lot
264 * for multi-input
265 */
266 DEMUX_SET_NEXT_DEMUX_TIME, /* arg1= int64_t can fail */
267 /* FPS for correct subtitles handling */
268 DEMUX_GET_FPS, /* arg1= double * res=can fail */
269
270 /* Meta data */
271 DEMUX_HAS_UNSUPPORTED_META, /* arg1= bool * res can fail */
272
273 /* Attachments */
274 DEMUX_GET_ATTACHMENTS, /* arg1=input_attachment_t***, int* res=can fail */
275
276 /* RECORD you are ensured that it is never called twice with the same state
277 * you should accept it only if the stream can be recorded without
278 * any modification or header addition. */
279 DEMUX_CAN_RECORD, /* arg1=bool* res=can fail(assume false) */
280 /**
281 * \todo Document
282 *
283 * \warning The prototype is different from STREAM_SET_RECORD_STATE
284 *
285 * The control is never used if DEMUX_CAN_RECORD fails or returns false.
286 * Can fail.
287 *
288 * arg1= bool */
289 DEMUX_SET_RECORD_STATE,
290
291 /* II. Specific access_demux queries */
292
293 /* DEMUX_CAN_CONTROL_RATE is called only if DEMUX_CAN_CONTROL_PACE has
294 * returned false. *pb_rate should be true when the rate can be changed
295 * (using DEMUX_SET_RATE). */
296 DEMUX_CAN_CONTROL_RATE, /* arg1= bool*pb_rate */
297 /* DEMUX_SET_RATE is called only if DEMUX_CAN_CONTROL_RATE has returned true.
298 * It should return the value really used in *pi_rate */
299 DEMUX_SET_RATE, /* arg1= int*pi_rate can fail */
300
301 /** Checks whether the stream is actually a playlist, rather than a real
302 * stream.
303 *
304 * \warning The prototype is different from STREAM_IS_DIRECTORY.
305 *
306 * Can fail if the stream is not a playlist (same as returning false).
307 *
308 * arg1= bool * */
309 DEMUX_IS_PLAYLIST,
310
311 /* Menu (VCD/DVD/BD) Navigation */
312 /** Activate the navigation item selected. Can fail */
313 DEMUX_NAV_ACTIVATE,
314 /** Use the up arrow to select a navigation item above. Can fail */
315 DEMUX_NAV_UP,
316 /** Use the down arrow to select a navigation item under. Can fail */
317 DEMUX_NAV_DOWN,
318 /** Use the left arrow to select a navigation item on the left. Can fail */
319 DEMUX_NAV_LEFT,
320 /** Use the right arrow to select a navigation item on the right. Can fail */
321 DEMUX_NAV_RIGHT,
322 /** Activate the popup Menu (for BD). Can fail */
323 DEMUX_NAV_POPUP,
324 /** Activate disc Root Menu. Can fail */
325 DEMUX_NAV_MENU, /* res=can fail */
326 /** Enable/Disable a demux filter
327 * \warning This has limited support, and is likely to break if more than
328 * a single demux_filter is present in the chain. This is not guaranteed to
329 * work in future VLC versions, nor with all demux filters
330 */
331 DEMUX_FILTER_ENABLE,
332 DEMUX_FILTER_DISABLE
333 };
334
335 /*************************************************************************
336 * Main Demux
337 *************************************************************************/
338
339 /* stream_t *s could be null and then it mean a access+demux in one */
340 VLC_API demux_t *demux_New( vlc_object_t *p_obj, const char *psz_name,
341 const char *psz_path, stream_t *s, es_out_t *out );
342
343 VLC_API void demux_Delete( demux_t * );
344
345
346 VLC_API int demux_vaControlHelper( stream_t *, int64_t i_start, int64_t i_end,
347 int64_t i_bitrate, int i_align, int i_query, va_list args );
348
demux_Demux(demux_t * p_demux)349 VLC_USED static inline int demux_Demux( demux_t *p_demux )
350 {
351 if( !p_demux->pf_demux )
352 return VLC_DEMUXER_SUCCESS;
353
354 return p_demux->pf_demux( p_demux );
355 }
356
357 VLC_API int demux_vaControl( demux_t *p_demux, int i_query, va_list args );
358
demux_Control(demux_t * p_demux,int i_query,...)359 static inline int demux_Control( demux_t *p_demux, int i_query, ... )
360 {
361 va_list args;
362 int i_result;
363
364 va_start( args, i_query );
365 i_result = demux_vaControl( p_demux, i_query, args );
366 va_end( args );
367 return i_result;
368 }
369
370 /*************************************************************************
371 * Miscellaneous helpers for demuxers
372 *************************************************************************/
373
demux_UpdateTitleFromStream(demux_t * demux)374 static inline void demux_UpdateTitleFromStream( demux_t *demux )
375 {
376 stream_t *s = demux->s;
377 unsigned title, seekpoint;
378
379 if( vlc_stream_Control( s, STREAM_GET_TITLE, &title ) == VLC_SUCCESS
380 && title != (unsigned)demux->info.i_title )
381 {
382 demux->info.i_title = title;
383 demux->info.i_update |= INPUT_UPDATE_TITLE;
384 }
385
386 if( vlc_stream_Control( s, STREAM_GET_SEEKPOINT,
387 &seekpoint ) == VLC_SUCCESS
388 && seekpoint != (unsigned)demux->info.i_seekpoint )
389 {
390 demux->info.i_seekpoint = seekpoint;
391 demux->info.i_update |= INPUT_UPDATE_SEEKPOINT;
392 }
393 }
394
395 VLC_USED
demux_IsPathExtension(demux_t * p_demux,const char * psz_extension)396 static inline bool demux_IsPathExtension( demux_t *p_demux, const char *psz_extension )
397 {
398 const char *name = (p_demux->psz_file != NULL) ? p_demux->psz_file
399 : p_demux->psz_location;
400 const char *psz_ext = strrchr ( name, '.' );
401 if( !psz_ext || strcasecmp( psz_ext, psz_extension ) )
402 return false;
403 return true;
404 }
405
406 VLC_USED
demux_IsContentType(demux_t * demux,const char * type)407 static inline bool demux_IsContentType(demux_t *demux, const char *type)
408 {
409 return stream_IsMimeType(demux->s, type);
410 }
411
412 VLC_USED
demux_IsForced(demux_t * p_demux,const char * psz_name)413 static inline bool demux_IsForced( demux_t *p_demux, const char *psz_name )
414 {
415 if( !p_demux->psz_demux || strcmp( p_demux->psz_demux, psz_name ) )
416 return false;
417 return true;
418 }
419
420 /**
421 * This function will create a packetizer suitable for a demuxer that parses
422 * elementary stream.
423 *
424 * The provided es_format_t will be cleaned on error or by
425 * demux_PacketizerDestroy.
426 */
427 VLC_API decoder_t * demux_PacketizerNew( demux_t *p_demux, es_format_t *p_fmt, const char *psz_msg ) VLC_USED;
428
429 /**
430 * This function will destroy a packetizer create by demux_PacketizerNew.
431 */
432 VLC_API void demux_PacketizerDestroy( decoder_t *p_packetizer );
433
434 /* */
435 #define DEMUX_INIT_COMMON() do { \
436 p_demux->pf_control = Control; \
437 p_demux->pf_demux = Demux; \
438 p_demux->p_sys = calloc( 1, sizeof( demux_sys_t ) ); \
439 if( !p_demux->p_sys ) return VLC_ENOMEM;\
440 } while(0)
441
442 /**
443 * \defgroup chained_demux Chained demultiplexer
444 * Demultiplexers wrapped by another demultiplexer
445 * @{
446 */
447
448 typedef struct vlc_demux_chained_t vlc_demux_chained_t;
449
450 /**
451 * Creates a chained demuxer.
452 *
453 * This creates a thread running a demuxer whose input stream is generated
454 * directly by the caller. This typically handles some sort of stream within a
455 * stream, e.g. MPEG-TS within something else.
456 *
457 * \note There are a number of limitations to this approach. The chained
458 * demuxer is run asynchronously in a separate thread. Most demuxer controls
459 * are synchronous and therefore unavailable in this case. Also the input
460 * stream is a simple FIFO, so the chained demuxer cannot perform seeks.
461 * Lastly, most errors cannot be detected.
462 *
463 * \param parent parent VLC object
464 * \param name chained demux module name (e.g. "ts")
465 * \param out elementary stream output for the chained demux
466 * \return a non-NULL pointer on success, NULL on failure.
467 */
468 VLC_API vlc_demux_chained_t *vlc_demux_chained_New(vlc_object_t *parent,
469 const char *name,
470 es_out_t *out);
471
472 /**
473 * Destroys a chained demuxer.
474 *
475 * Sends an end-of-stream to the chained demuxer, and releases all underlying
476 * allocated resources.
477 */
478 VLC_API void vlc_demux_chained_Delete(vlc_demux_chained_t *);
479
480 /**
481 * Sends data to a chained demuxer.
482 *
483 * This queues data for a chained demuxer to consume.
484 *
485 * \param block data block to queue
486 */
487 VLC_API void vlc_demux_chained_Send(vlc_demux_chained_t *, block_t *block);
488
489 /**
490 * Controls a chained demuxer.
491 *
492 * This performs a <b>demux</b> (i.e. DEMUX_...) control request on a chained
493 * demux.
494 *
495 * \note In most cases, vlc_demux_chained_Control() should be used instead.
496 * \warning As per vlc_demux_chained_New(), most demux controls are not, and
497 * cannot be, supported; VLC_EGENERIC is returned.
498 *
499 * \param query demux control (see \ref demux_query_e)
500 * \param args variable arguments (depending on the query)
501 */
502 VLC_API int vlc_demux_chained_ControlVa(vlc_demux_chained_t *, int query,
503 va_list args);
504
vlc_demux_chained_Control(vlc_demux_chained_t * dc,int query,...)505 static inline int vlc_demux_chained_Control(vlc_demux_chained_t *dc, int query,
506 ...)
507 {
508 va_list ap;
509 int ret;
510
511 va_start(ap, query);
512 ret = vlc_demux_chained_ControlVa(dc, query, ap);
513 va_end(ap);
514 return ret;
515 }
516
517 /**
518 * @}
519 */
520
521 /**
522 * @}
523 */
524
525 #endif
526