VLC 4.0.0-dev
Loading...
Searching...
No Matches
vlc_sout.h
Go to the documentation of this file.
1/*****************************************************************************
2 * vlc_sout.h : stream output module
3 *****************************************************************************
4 * Copyright (C) 2002-2008 VLC authors and VideoLAN
5 *
6 * Authors: Christophe Massiot <massiot@via.ecp.fr>
7 * Laurent Aimar <fenrir@via.ecp.fr>
8 * Eric Petit <titer@videolan.org>
9 * Jean-Paul Saman <jpsaman #_at_# m2x.nl>
10 * RĂ©mi Denis-Courmont
11 *
12 * This program is free software; you can redistribute it and/or modify it
13 * under the terms of the GNU Lesser General Public License as published by
14 * the Free Software Foundation; either version 2.1 of the License, or
15 * (at your option) any later version.
16 *
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Lesser General Public License for more details.
21 *
22 * You should have received a copy of the GNU Lesser General Public License
23 * along with this program; if not, write to the Free Software Foundation,
24 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
25 *****************************************************************************/
26
27#ifndef VLC_SOUT_H_
28#define VLC_SOUT_H_
29
30#include <sys/types.h>
31#include <vlc_es.h>
32#include <vlc_clock.h>
33#include <vlc_tick.h>
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/**
40 * \defgroup sout Stream output
41 * \ingroup output
42 * @{
43 * \file
44 * Stream output modules interface
45 */
46
47/**
48 * \defgroup sout_access Access output
49 * Raw output byte streams
50 * @{
51 */
52
53/** Stream output access_output */
56 struct vlc_object_t obj;
61 char *psz_path;
62 void *p_sys;
63 int (*pf_seek)( sout_access_out_t *, uint64_t );
64 ssize_t (*pf_read)( sout_access_out_t *, block_t * );
66 int (*pf_control)( sout_access_out_t *, int, va_list );
69};
70
73 ACCESS_OUT_CONTROLS_PACE, /* arg1=bool *, can fail (assume true) */
74 ACCESS_OUT_CAN_SEEK, /* arg1=bool *, can fail (assume false) */
75};
76
77VLC_API sout_access_out_t * sout_AccessOutNew( vlc_object_t *, const char *psz_access, const char *psz_name ) VLC_USED;
78#define sout_AccessOutNew( obj, access, name ) \
79 sout_AccessOutNew( VLC_OBJECT(obj), access, name )
85
86static inline bool sout_AccessOutCanControlPace( sout_access_out_t *p_ao )
88 bool b;
90 return true;
91 return b;
92}
93
94/**
95 * @}
96 * \defgroup sout_mux Multiplexer
97 * Multiplexers (file formatters)
98 * @{
99 */
100
101/** Muxer structure */
102struct sout_mux_t
104 struct vlc_object_t obj;
107 char *psz_mux;
112 int (*pf_addstream)( sout_mux_t *, sout_input_t * );
114 int (*pf_mux) ( sout_mux_t * );
115 int (*pf_control) ( sout_mux_t *, int, va_list );
117 /* here are all inputs accepted by muxer */
118 int i_nb_inputs;
121 /* mux private */
122 void *p_sys;
124 /* XXX private to stream_output.c */
125 /* if muxer doesn't support adding stream at any time then we first wait
126 * for stream then we refuse all stream and start muxing */
129 /* we wait 1.5 second after first stream added */
132
135 /* capabilities */
136 MUX_CAN_ADD_STREAM_WHILE_MUXING, /* arg1= bool *, res=cannot fail */
137 /* properties */
138 MUX_GET_MIME, /* arg1= char ** res=can fail */
140
141struct sout_input_t
149
157
158static inline int sout_MuxControl( sout_mux_t *p_mux, int i_query, ... )
160 va_list args;
161 int i_result;
162
163 va_start( args, i_query );
164 i_result = p_mux->pf_control( p_mux, i_query, args );
165 va_end( args );
166 return i_result;
167}
168
169/** @} */
170
171/**
172 * Stream output control list.
173 *
174 * Call the related actions with ::sout_StreamControl().
175 */
178 /**
179 * Some ES such as closed captions are considered optional and shouldn't be
180 * added to the stream output modules that return false for that query.
181 *
182 * \param bool* Closed caption support value, should be assumed false if the
183 * control fails.
184 *
185 * Usage:
186 * \code{c}
187 * bool supports_substreams;
188 * if (sout_StreamControl(stream, SOUT_STREAM_WANTS_SUBSTREAMS, &supports_substreams) != VLC_SUCCESS)
189 * supports_substreams = false;
190 * \endcode
191 */
194 /**
195 * Signal the currently selected subtitle track that should be displayed to
196 * the stream output.
197 * This control should fail and do nothing if not implemented.
198 *
199 * \param void* Stream ID
200 * \param vlc_spu_highlight_t* Selected spu data.
201 *
202 * Usage:
203 * \code{c}
204 * void *stream_id;
205 * const vlc_spu_highlight_t hl_data = {... SPU infos...};
206 * sout_StreamControl(stream, SOUT_STREAM_ID_SPU_HIGHLIGHT, stream_id, &hl_data);
207 * \endcode
208 */
211 /**
212 * A synchronous stream output is a stream paced by the input clock. The
213 * data will be sent at input rate if true is returned.
214 *
215 * \param bool* True if the stream output should be input paced. Should be
216 * assumed false if the control fails.
217 *
218 * Usage:
219 * \code{c}
220 * bool is_input_paced;
221 * if (sout_StreamControl(stream, SOUT_STREAM_IS_SYNCHRONOUS, &supports_substreams) != VLC_SUCCESS)
222 * supports_substreams = false;
223 * \endcode
224 */
227
228typedef struct vlc_frame_t vlc_frame_t;
230 /**
231 * Implementation of ::sout_StreamIdAdd().
232 *
233 * \note Mandatory callback.
234 */
235 void *(*add)(sout_stream_t *, const es_format_t *, const char *);
236 /**
237 * Implementation of ::sout_StreamIdDel().
238 *
239 * \note Mandatory callback.
240 */
241 void (*del)(sout_stream_t *, void *);
242 /**
243 * Implementation of ::sout_StreamIdSend().
244 *
245 * \note Mandatory callback.
246 */
247 int (*send)(sout_stream_t *, void *, vlc_frame_t *);
248 /**
249 * Implementation of ::sout_StreamControl().
250 *
251 * \note Optional callback.
252 */
253 int (*control)( sout_stream_t *, int, va_list );
254 /**
255 * Implementation of ::sout_StreamFlush().
256 *
257 * \note Optional callback.
258 */
259 void (*flush)( sout_stream_t *, void *);
260 /**
261 * Implementation of ::sout_StreamSetPCR().
262 *
263 * \note Optional callback.
264 */
265 void (*set_pcr)(sout_stream_t *, vlc_tick_t);
266 /**
267 * \note Optional callback.
268 */
269 void (*close)(sout_stream_t *);
271
272struct sout_stream_t
284/**
285 * Allocate an empty Stream Output object.
286 *
287 * The object is empty, operation callbacks should be populated manually by the
288 * caller. To create a stream output associated with a module, use
289 * ::sout_StreamChainNew() instead.
290 *
291 * \note The stream should be destroyed with ::sout_StreamChainDelete().
292 *
293 * \param parent The parent object of the stream output.
294 * \param config A valid config chain of the object, of the form
295 * "objname{option=*,option=*,...}"
296 *
297 * \retval An empty allocated Stream Output object.
298 * \retval NULL on allocation error.
299 */
301
303
304/**
305 * Creates a complete "stream_out" modules chain
306 *
307 * Chain format: module1{option=*:option=*}[:module2{option=*:...}]
308 *
309 * The modules are created starting from the last one and linked together
310 *
311 * \retval A pointer to the first module.
312 * \retval NULL if the chain creation failed.
313 */
315 const char *psz_chain, sout_stream_t *p_next) VLC_USED;
316
317/**
318 * Add an ES to the stream output.
319 *
320 * The returned opaque identifier should be released by ::sout_StreamIdDel().
321 *
322 * \param s
323 * \param fmt A non-NULL es-format descriptor.
324 * \param es_id A non-NULL unique string describing the ES. This string is
325 * guaranteed to be valid for the whole lifetime of the ES (at
326 * least until ::sout_StreamIdDel() is called).
327 * Note that if stream output filters creates or duplicate a new
328 * ES, they are responsible for the validity and uniqueness of the
329 * string ID they pass to the next stream.
330 *
331 * \return An opaque pointer identifying the ES.
332 * \retval NULL In case of error.
333 */
335 const es_format_t *fmt,
336 const char *es_id) VLC_USED;
337
338/**
339 * Delete an ES from the stream output.
340 *
341 * \param s
342 * \param id An opaque pointer identifying the ES returned by
343 * ::sout_StreamIdAdd().
344 */
345VLC_API void sout_StreamIdDel(sout_stream_t *s, void *id);
346
347/**
348 * Pass a \ref vlc_frame_t to the stream output.
349 *
350 * Takes ownership of the frame, it should be considered as invalid
351 * and released after this call.
352 *
353 * \warning Only single frames are expected through this call, for frame chains,
354 * you'll have to call this for each frames.
355 *
356 * \param s
357 * \param id The ES identifier that sent the frame.
358 * \param f a frame that will be consumed (through vlc_frame_Release)
359 *
360 * \retval VLC_SUCCESS on success.
361 * \retval VLC_EGENERIC on non-recoverable unspecific error cases.
362 * \retval (-ERRNO) A negated errno value describing the error case.
363 */
365
366/**
367 * Signal a flush of an ES to the stream output.
368 *
369 * Flush is an optional control, if implemented, it will drop all the bufferized
370 * data from ES and/or forward the Flush command to the next stream.
371 *
372 * \param s
373 * \param id An identifier of the ES to flush.
374 */
375VLC_API void sout_StreamFlush(sout_stream_t *s, void *id);
376
377/**
378 * Signal a PCR update to the stream output.
379 *
380 * The PCR (Program Clock Reference from the MPEG-TS spec.) gives a global
381 * stream advancement timestamp.
382 * The demuxer is required to:
383 * - Yield a PCR value at fix and frequent interval. Even if no ES are added
384 * to the stream output.
385 * - Send frames that have timestamp values greater than the last PCR value.
386 *
387 * \note PCR resets in case of handled discontinuity are implied by a frame
388 * marked by \ref VLC_FRAME_FLAG_DISCONTINUITY and/or by a ::sout_StreamFlush()
389 * call.
390 */
392
398
399
400VLC_API int sout_StreamControlVa(sout_stream_t *, int i_query, va_list args);
401
402/**
403 * Various controls forwarded through the stream output chain.
404 *
405 * Controls are various misc accessors or set of actions that can be used to
406 * query the stream output.
407 * See \ref sout_stream_query_e for the list of availables controls.
408 */
409static inline int sout_StreamControl( sout_stream_t *s, int i_query, ... )
411 va_list args;
412 int i_result;
413
414 va_start( args, i_query );
415 i_result = sout_StreamControlVa( s, i_query, args );
416 va_end( args );
417 return i_result;
418}
419
420static inline bool sout_StreamIsSynchronous(sout_stream_t *s)
422 bool b;
423
425 b = false;
426
427 return b;
428}
429
430/****************************************************************************
431 * Encoder
432 ****************************************************************************/
433
435#define sout_EncoderCreate(o,s) sout_EncoderCreate(VLC_OBJECT(o),s)
437/****************************************************************************
438 * Announce handler
439 ****************************************************************************/
442#define sout_AnnounceRegisterSDP(o, sdp, addr) \
443 sout_AnnounceRegisterSDP(VLC_OBJECT (o), sdp, addr)
444#define sout_AnnounceUnRegister(o, a) \
445 sout_AnnounceUnRegister(VLC_OBJECT (o), a)
446
447/** @} */
448
449#ifdef __cplusplus
450}
451#endif
452
453#endif
static struct @13 config
#define VLC_USED
Definition fourcc_gen.c:32
#define VLC_API
Definition fourcc_gen.c:31
int sout_AccessOutSeek(sout_access_out_t *, uint64_t)
Definition stream_output.c:276
static bool sout_AccessOutCanControlPace(sout_access_out_t *p_ao)
Definition vlc_sout.h:87
access_out_query_e
Definition vlc_sout.h:73
ssize_t sout_AccessOutWrite(sout_access_out_t *, block_t *)
Definition stream_output.c:295
int sout_AccessOutControl(sout_access_out_t *, int,...)
sout_AccessOutControl
Definition stream_output.c:303
#define sout_AccessOutNew(obj, access, name)
Definition vlc_sout.h:79
void sout_AccessOutDelete(sout_access_out_t *)
Definition stream_output.c:258
ssize_t sout_AccessOutRead(sout_access_out_t *, block_t *)
Definition stream_output.c:286
@ ACCESS_OUT_CAN_SEEK
Definition vlc_sout.h:75
@ ACCESS_OUT_CONTROLS_PACE
Definition vlc_sout.h:74
void sout_MuxDelete(sout_mux_t *)
Definition stream_output.c:383
sout_input_t * sout_MuxAddStream(sout_mux_t *, const es_format_t *)
Definition stream_output.c:399
sout_mux_t * sout_MuxNew(sout_access_out_t *, const char *)
Definition stream_output.c:320
static int sout_MuxControl(sout_mux_t *p_mux, int i_query,...)
Definition vlc_sout.h:159
int sout_MuxGetStream(sout_mux_t *, unsigned, vlc_tick_t *)
Definition stream_output.c:508
void sout_MuxFlush(sout_mux_t *, sout_input_t *)
Definition stream_output.c:499
void sout_MuxDeleteStream(sout_mux_t *, sout_input_t *)
Definition stream_output.c:441
int sout_MuxSendBuffer(sout_mux_t *, sout_input_t *, block_t *)
Definition stream_output.c:475
sout_mux_query_e
Definition vlc_sout.h:135
@ MUX_GET_MIME
Definition vlc_sout.h:139
@ MUX_CAN_ADD_STREAM_WHILE_MUXING
Definition vlc_sout.h:137
vlc_clock_main_t * sout_ClockMainCreate(sout_stream_t *)
Definition stream_output.c:782
static bool sout_StreamIsSynchronous(sout_stream_t *s)
Definition vlc_sout.h:421
void sout_StreamIdDel(sout_stream_t *s, void *id)
Delete an ES from the stream output.
Definition stream_output.c:711
static int sout_StreamControl(sout_stream_t *s, int i_query,...)
Various controls forwarded through the stream output chain.
Definition vlc_sout.h:410
void sout_StreamChainDelete(sout_stream_t *first, sout_stream_t *end)
Definition stream_output.c:824
void sout_ClockMainDelete(vlc_clock_main_t *)
Definition stream_output.c:788
void * sout_StreamIdAdd(sout_stream_t *s, const es_format_t *fmt, const char *es_id)
Add an ES to the stream output.
Definition stream_output.c:699
int sout_StreamControlVa(sout_stream_t *, int i_query, va_list args)
Definition stream_output.c:750
vlc_clock_t * sout_ClockCreate(vlc_clock_main_t *, const es_format_t *)
Definition stream_output.c:801
void sout_StreamFlush(sout_stream_t *s, void *id)
Signal a flush of an ES to the stream output.
Definition stream_output.c:730
#define sout_AnnounceRegisterSDP(o, sdp, addr)
Definition vlc_sout.h:443
void sout_ClockMainSetFirstPcr(vlc_clock_main_t *, vlc_tick_t pcr)
Definition stream_output.c:793
#define sout_AnnounceUnRegister(o, a)
Definition vlc_sout.h:445
sout_stream_t * sout_StreamNew(vlc_object_t *parent, const char *config)
Allocate an empty Stream Output object.
Definition stream_output.c:854
void sout_ClockDelete(vlc_clock_t *)
Definition stream_output.c:812
#define sout_EncoderCreate(o, s)
Definition vlc_sout.h:436
sout_stream_query_e
Stream output control list.
Definition vlc_sout.h:178
sout_stream_t * sout_StreamChainNew(vlc_object_t *parent, const char *psz_chain, sout_stream_t *p_next)
Creates a complete "stream_out" modules chain.
Definition stream_output.c:904
int sout_StreamIdSend(sout_stream_t *s, void *id, vlc_frame_t *f)
Pass a vlc_frame_t to the stream output.
Definition stream_output.c:718
void sout_StreamSetPCR(sout_stream_t *, vlc_tick_t pcr)
Signal a PCR update to the stream output.
Definition stream_output.c:740
@ SOUT_STREAM_ID_SPU_HIGHLIGHT
Signal the currently selected subtitle track that should be displayed to the stream output.
Definition vlc_sout.h:210
@ SOUT_STREAM_WANTS_SUBSTREAMS
Some ES such as closed captions are considered optional and shouldn't be added to the stream output m...
Definition vlc_sout.h:193
@ SOUT_STREAM_IS_SYNCHRONOUS
A synchronous stream output is a stream paced by the input clock.
Definition vlc_sout.h:226
Definition vlc_configuration.h:320
Definition vlc_codec.h:255
Definition vlc_es.h:633
Internal module descriptor.
Definition modules.h:76
Definition sap.c:49
Stream output access_output.
Definition vlc_sout.h:56
config_chain_t * p_cfg
Definition vlc_sout.h:69
char * psz_path
Definition vlc_sout.h:62
module_t * p_module
Definition vlc_sout.h:59
int(* pf_control)(sout_access_out_t *, int, va_list)
Definition vlc_sout.h:67
int(* pf_seek)(sout_access_out_t *, uint64_t)
Definition vlc_sout.h:64
struct vlc_object_t obj
Definition vlc_sout.h:57
ssize_t(* pf_write)(sout_access_out_t *, block_t *)
Definition vlc_sout.h:66
char * psz_access
Definition vlc_sout.h:60
ssize_t(* pf_read)(sout_access_out_t *, block_t *)
Definition vlc_sout.h:65
void * p_sys
Definition vlc_sout.h:63
Definition vlc_sout.h:143
block_fifo_t * p_fifo
Definition vlc_sout.h:145
es_format_t fmt
Definition vlc_sout.h:147
void * p_sys
Definition vlc_sout.h:146
const es_format_t * p_fmt
Definition vlc_sout.h:144
Muxer structure.
Definition vlc_sout.h:104
module_t * p_module
Definition vlc_sout.h:106
void * p_sys
Definition vlc_sout.h:123
int i_nb_inputs
Definition vlc_sout.h:119
bool b_add_stream_any_time
Definition vlc_sout.h:128
int(* pf_mux)(sout_mux_t *)
Definition vlc_sout.h:115
int(* pf_control)(sout_mux_t *, int, va_list)
Definition vlc_sout.h:116
struct vlc_object_t obj
Definition vlc_sout.h:105
void(* pf_delstream)(sout_mux_t *, sout_input_t *)
Definition vlc_sout.h:114
sout_input_t ** pp_inputs
Definition vlc_sout.h:120
vlc_tick_t i_add_stream_start
Definition vlc_sout.h:131
sout_access_out_t * p_access
Definition vlc_sout.h:111
char * psz_mux
Definition vlc_sout.h:108
bool b_waiting_stream
Definition vlc_sout.h:129
int(* pf_addstream)(sout_mux_t *, sout_input_t *)
Definition vlc_sout.h:113
config_chain_t * p_cfg
Definition vlc_sout.h:109
Definition vlc_sout.h:230
void(* set_pcr)(sout_stream_t *, vlc_tick_t)
Implementation of sout_StreamSetPCR().
Definition vlc_sout.h:266
int(* control)(sout_stream_t *, int, va_list)
Implementation of sout_StreamControl().
Definition vlc_sout.h:254
void(* close)(sout_stream_t *)
Definition vlc_sout.h:270
void(* del)(sout_stream_t *, void *)
Implementation of sout_StreamIdDel().
Definition vlc_sout.h:242
int(* send)(sout_stream_t *, void *, vlc_frame_t *)
Implementation of sout_StreamIdSend().
Definition vlc_sout.h:248
void(* flush)(sout_stream_t *, void *)
Implementation of sout_StreamFlush().
Definition vlc_sout.h:260
Definition vlc_sout.h:274
const struct sout_stream_operations * ops
Definition vlc_sout.h:281
char * psz_name
Definition vlc_sout.h:277
struct vlc_object_t obj
Definition vlc_sout.h:275
config_chain_t * p_cfg
Definition vlc_sout.h:278
void * p_sys
Definition vlc_sout.h:282
sout_stream_t * p_next
Definition vlc_sout.h:279
Definition clock.c:43
Definition clock.c:88
Internal state for block queues.
Definition fifo.c:39
Definition vlc_frame.h:123
VLC object common members.
Definition vlc_objects.h:53
const char * psz_name
Definition text_style.c:33
This file is a collection of common definitions and types.
This file defines the elementary streams format types.
int64_t vlc_tick_t
High precision date or time interval.
Definition vlc_tick.h:48