Stream output

Collaboration diagram for Stream output:

Modules
	Encoder
	Audio, video and text encoders.
	Access output
	Raw output byte streams.
	Multiplexer
	Multiplexers (file formatters)

Files
file	vlc_sout.h
	Stream output modules interface.

Data Structures
struct	sout_stream_operations
struct	sout_stream_t

Macros
#define	sout_EncoderCreate(o, s)   sout_EncoderCreate(VLC_OBJECT(o),s)
#define	sout_AnnounceRegisterSDP(o, sdp, addr)    sout_AnnounceRegisterSDP(VLC_OBJECT (o), sdp, addr)
#define	sout_AnnounceUnRegister(o, a)    sout_AnnounceUnRegister(VLC_OBJECT (o), a)

Typedefs
typedef struct vlc_frame_t	vlc_frame_t

Enumerations
enum	sout_stream_query_e { SOUT_STREAM_WANTS_SUBSTREAMS , SOUT_STREAM_ID_SPU_HIGHLIGHT , SOUT_STREAM_IS_SYNCHRONOUS }
	Stream output control list. More...

Functions
sout_stream_t *	sout_StreamNew (vlc_object_t *parent, const char *config)
	Allocate an empty Stream Output object.
void	sout_StreamChainDelete (sout_stream_t *first, sout_stream_t *end)
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.
void *	sout_StreamIdAdd (sout_stream_t *s, const es_format_t *fmt, const char *es_id)
	Add an ES to the stream output.
void	sout_StreamIdDel (sout_stream_t *s, void *id)
	Delete an ES from the stream output.
int	sout_StreamIdSend (sout_stream_t *s, void *id, vlc_frame_t *f)
	Pass a vlc_frame_t to the stream output.
void	sout_StreamFlush (sout_stream_t *s, void *id)
	Signal a flush of an ES to the stream output.
void	sout_StreamSetPCR (sout_stream_t *, vlc_tick_t pcr)
	Signal a PCR update to the stream output.
vlc_clock_main_t *	sout_ClockMainCreate (sout_stream_t *)
void	sout_ClockMainDelete (vlc_clock_main_t *)
void	sout_ClockMainSetFirstPcr (vlc_clock_main_t *, vlc_tick_t pcr)
vlc_clock_t *	sout_ClockCreate (vlc_clock_main_t *, const es_format_t *)
void	sout_ClockDelete (vlc_clock_t *)
int	sout_StreamControlVa (sout_stream_t *, int i_query, va_list args)
static int	sout_StreamControl (sout_stream_t *s, int i_query,...)
	Various controls forwarded through the stream output chain.
static bool	sout_StreamIsSynchronous (sout_stream_t *s)
encoder_t *	sout_EncoderCreate (vlc_object_t *, size_t)
session_descriptor_t *	sout_AnnounceRegisterSDP (vlc_object_t *, const char *, const char *)
	Registers a new session with the announce handler, using a pregenerated SDP.
void	sout_AnnounceUnRegister (vlc_object_t *, session_descriptor_t *)
	Unregisters an existing session.

Detailed Description

Macro Definition Documentation

sout_AnnounceRegisterSDP

#define sout_AnnounceRegisterSDP	(		o,
			sdp,
			addr
	)		sout_AnnounceRegisterSDP(VLC_OBJECT (o), sdp, addr)

sout_AnnounceUnRegister

#define sout_AnnounceUnRegister	(		o,
			a
	)		sout_AnnounceUnRegister(VLC_OBJECT (o), a)

sout_EncoderCreate

#define sout_EncoderCreate	(		o,
			s
	)		sout_EncoderCreate(VLC_OBJECT(o),s)

Typedef Documentation

vlc_frame_t

typedef struct vlc_frame_t vlc_frame_t

Enumeration Type Documentation

sout_stream_query_e

enum sout_stream_query_e

Stream output control list.

Call the related actions with sout_StreamControl().

Enumerator
SOUT_STREAM_WANTS_SUBSTREAMS	Some ES such as closed captions are considered optional and shouldn't be added to the stream output modules that return false for that query. Parameters bool* Closed caption support value, should be assumed false if the control fails. Usage: bool supports_substreams; if (sout_StreamControl(stream, SOUT_STREAM_WANTS_SUBSTREAMS, &supports_substreams) != VLC_SUCCESS) supports_substreams = false;
SOUT_STREAM_ID_SPU_HIGHLIGHT	Signal the currently selected subtitle track that should be displayed to the stream output. This control should fail and do nothing if not implemented. Parameters void* Stream ID vlc_spu_highlight_t* Selected spu data. Usage: void *stream_id; const vlc_spu_highlight_t hl_data = {... SPU infos...}; sout_StreamControl(stream, SOUT_STREAM_ID_SPU_HIGHLIGHT, stream_id, &hl_data);
SOUT_STREAM_IS_SYNCHRONOUS	A synchronous stream output is a stream paced by the input clock. The data will be sent at input rate if true is returned. Parameters bool* True if the stream output should be input paced. Should be assumed false if the control fails. Usage: bool is_input_paced; if (sout_StreamControl(stream, SOUT_STREAM_IS_SYNCHRONOUS, &supports_substreams) != VLC_SUCCESS) supports_substreams = false;

Function Documentation

sout_AnnounceRegisterSDP()

session_descriptor_t * sout_AnnounceRegisterSDP	(	vlc_object_t *	obj,
		const char *	sdp,
		const char *	dst
	)

Registers a new session with the announce handler, using a pregenerated SDP.

Parameters

obj	a VLC object
sdp	the SDP to register
dst	session address (needed for SAP address auto detection)

Returns

the new session descriptor structure

References sap_address_t::a, session_descriptor_t::addr, AddressCreate(), AddressDestroy(), session_descriptor_t::data, sap_address_t::group, sap_address_t::in, sap_address_t::in6, vlc_memstream::length, session_descriptor_t::length, msg_Dbg, msg_Err, NI_MAXNUMERICHOST, session_descriptor_t::node, sap_address_t::node, sap_address_t::orig, vlc_memstream::ptr, RunThread(), sap_addrs, sap_mutex, sap_address_t::session_count, sap_address_t::sessions, vlc_memstream::stream, sap_address_t::thread, unlikely, vlc_assert_unreachable, vlc_clone(), vlc_cond_signal(), vlc_getaddrinfo(), vlc_getnameinfo(), vlc_list_append(), vlc_list_foreach, vlc_memstream_close(), vlc_memstream_open(), vlc_memstream_putc(), vlc_memstream_puts(), vlc_memstream_write(), vlc_mutex_lock(), vlc_mutex_unlock(), vlc_tick_now(), and sap_address_t::wait.

sout_AnnounceUnRegister()

void sout_AnnounceUnRegister	(	vlc_object_t *	obj,
		session_descriptor_t *	session
	)

Unregisters an existing session.

Parameters

obj	a VLC object
session	the session descriptor

References session_descriptor_t::addr, AddressDestroy(), session_descriptor_t::data, msg_Dbg, session_descriptor_t::node, sap_address_t::node, sap_mutex, sap_address_t::session_count, sap_address_t::sessions, sap_address_t::thread, vlc_cond_signal(), vlc_join(), vlc_list_is_empty(), vlc_list_remove(), vlc_mutex_lock(), vlc_mutex_unlock(), and sap_address_t::wait.

sout_ClockCreate()

vlc_clock_t * sout_ClockCreate	(	vlc_clock_main_t *	main_clock,
		const es_format_t *	fmt
	)

References es_format_t::i_cat, vlc_clock_main_CreateSlave(), vlc_clock_main_Lock(), and vlc_clock_main_Unlock().

sout_ClockDelete()

void sout_ClockDelete

(

vlc_clock_t *

clock

)

References vlc_clock_Delete().

sout_ClockMainCreate()

vlc_clock_main_t * sout_ClockMainCreate

(

sout_stream_t *

p_stream

)

References vlc_object_t::logger, sout_stream_t::obj, vlc_clock_main_New(), and vlc_object_get_tracer().

sout_ClockMainDelete()

void sout_ClockMainDelete

(

vlc_clock_main_t *

main_clock

)

References vlc_clock_main_Delete().

sout_ClockMainSetFirstPcr()

void sout_ClockMainSetFirstPcr	(	vlc_clock_main_t *	main_clock,
		vlc_tick_t	pcr
	)

References vlc_clock_main_Lock(), vlc_clock_main_Reset(), vlc_clock_main_SetFirstPcr(), vlc_clock_main_Unlock(), and vlc_tick_now().

sout_EncoderCreate()

encoder_t * sout_EncoderCreate	(	vlc_object_t *	p_this,
		size_t	owner_size
	)

References vlc_custom_create.

sout_StreamChainDelete()

void sout_StreamChainDelete	(	sout_stream_t *	first,
		sout_stream_t *	end
	)

References sout_stream_t::p_next, and sout_StreamDelete().

Referenced by DestroySout(), and EsOutSetRecord().

sout_StreamChainNew()

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.

Chain format: module1{option=*:option=*}[:module2{option=*:...}]

The modules are created starting from the last one and linked together

Return values

A	pointer to the first module.
NULL	if the chain creation failed.

References config_ChainCreate(), config_ChainDestroy(), name, sout_stream_t::p_next, psz_name, sout_StreamDelete(), sout_StreamNewModule(), strdup(), vlc_array_append_or_abort(), vlc_array_clear(), vlc_array_count(), vlc_array_init(), and vlc_array_item_at_index.

Referenced by sout_NewInstance().

sout_StreamControl()

static int sout_StreamControl ( sout_stream_t *  s, int  i_query,   ...  )

inlinestatic

Various controls forwarded through the stream output chain.

Controls are various misc accessors or set of actions that can be used to query the stream output. See sout_stream_query_e for the list of availables controls.

References sout_StreamControlVa().

Referenced by DecoderSendSubstream(), sout_InputControlVa(), and sout_StreamIsSynchronous().

sout_StreamControlVa()

int sout_StreamControlVa	(	sout_stream_t *	s,
		int	i_query,
		va_list	args
	)

References sout_stream_operations::control, sout_stream_t::ops, sout_StreamLock(), sout_StreamUnlock(), and VLC_EGENERIC.

Referenced by sout_StreamControl().

sout_StreamFlush()

void sout_StreamFlush	(	sout_stream_t *	s,
		void *	id
	)

Signal a flush of an ES to the stream output.

Flush is an optional control, if implemented, it will drop all the bufferized data from ES and/or forward the Flush command to the next stream.

Parameters

s
id	An identifier of the ES to flush.

References sout_stream_operations::flush, sout_stream_t::ops, sout_StreamLock(), and sout_StreamUnlock().

Referenced by sout_InputFlush().

sout_StreamIdAdd()

void * sout_StreamIdAdd	(	sout_stream_t *	s,
		const es_format_t *	fmt,
		const char *	es_id
	)

Add an ES to the stream output.

The returned opaque identifier should be released by sout_StreamIdDel().

Parameters

s
fmt	A non-NULL es-format descriptor.
es_id	A non-NULL unique string describing the ES. This string is guaranteed to be valid for the whole lifetime of the ES (at least until sout_StreamIdDel() is called). Note that if stream output filters creates or duplicate a new ES, they are responsible for the validity and uniqueness of the string ID they pass to the next stream.

Returns

An opaque pointer identifying the ES.

Return values

NULL	In case of error.

References sout_stream_operations::add, sout_stream_t::ops, sout_StreamLock(), and sout_StreamUnlock().

Referenced by sout_InputNew().

sout_StreamIdDel()

void sout_StreamIdDel	(	sout_stream_t *	s,
		void *	id
	)

Delete an ES from the stream output.

Parameters

s
id	An opaque pointer identifying the ES returned by sout_StreamIdAdd().

References sout_stream_operations::del, sout_stream_t::ops, sout_StreamLock(), and sout_StreamUnlock().

Referenced by sout_InputDelete().

sout_StreamIdSend()

int sout_StreamIdSend	(	sout_stream_t *	s,
		void *	id,
		vlc_frame_t *	f
	)

Pass a vlc_frame_t to the stream output.

Takes ownership of the frame, it should be considered as invalid and released after this call.

Warning

Only single frames are expected through this call, for frame chains, you'll have to call this for each frames.

Parameters

s
id	The ES identifier that sent the frame.
f	a frame that will be consumed (through vlc_frame_Release)

Return values

VLC_SUCCESS	on success.
VLC_EGENERIC	on non-recoverable unspecific error cases.
(-ERRNO)	A negated errno value describing the error case.

References sout_stream_t::ops, vlc_frame_t::p_next, sout_stream_operations::send, sout_StreamLock(), and sout_StreamUnlock().

Referenced by sout_InputSendBuffer().

sout_StreamIsSynchronous()

static bool sout_StreamIsSynchronous ( sout_stream_t *  s )

inlinestatic

References SOUT_STREAM_IS_SYNCHRONOUS, and sout_StreamControl().

Referenced by EsOutSend(), and Init().

sout_StreamNew()

sout_stream_t * sout_StreamNew	(	vlc_object_t *	parent,
		const char *	config
	)

Allocate an empty Stream Output object.

The object is empty, operation callbacks should be populated manually by the caller. To create a stream output associated with a module, use sout_StreamChainNew() instead.

Note

The stream should be destroyed with sout_StreamChainDelete().

Parameters

parent	The parent object of the stream output.
config	A valid config chain of the object, of the form "objname{option=*,option=*,...}"

Return values

An	empty allocated Stream Output object.
NULL	on allocation error.

References config, config_ChainCreate(), name, sout_stream_t::p_cfg, sout_StreamNewEmpty(), sout_stream_private::stream, and unlikely.

sout_StreamSetPCR()

void sout_StreamSetPCR	(	sout_stream_t *	s,
		vlc_tick_t	pcr
	)

Signal a PCR update to the stream output.

The PCR (Program Clock Reference from the MPEG-TS spec.) gives a global stream advancement timestamp. The demuxer is required to:

• Yield a PCR value at fix and frequent interval. Even if no ES are added to the stream output.
• Send frames that have timestamp values greater than the last PCR value.

Note

PCR resets in case of handled discontinuity are implied by a frame marked by VLC_FRAME_FLAG_DISCONTINUITY and/or by a sout_StreamFlush() call.

References sout_stream_t::ops, sout_stream_operations::set_pcr, sout_StreamLock(), and sout_StreamUnlock().

Referenced by EsOutVaControlLocked().