VideoLAN Wiki - User contributions [en]

Documentation:Streaming HowTo/Receive and Save a Stream

2010-03-04T17:52:59Z

Stondage123: fix typo

{{RightMenu|documentation streaming howto toc}}

==Receive a stream with VLC==

===Receive an unicast stream===

% '''vlc -vvv rtp://'''

===Receive a multicast stream===

% '''vlc -vvv rtp://@239.255.12.42'''
where '''239.255.12.42''' is the multicast IP address you want to join.

===Receive an HTTP/FTP/MMS stream===

Use one of the following command lines:

% '''vlc -vvv http://example/stream.xyz'''
where '''http://example/stream.xyz''' is the HTTP address of the stream;

% '''vlc -vvv ftp://example/stream.xyz'''
where '''ftp://example/stream.xyz''' is the FTP address of the stream;

% '''vlc -vvv mms://viptvr.yacast.fr/encoderfranceinfo'''
where '''mms://viptvr.yacast.fr/encoderfranceinfo''' is the MMS address of the stream.

===Receive a RTP stream available through RTSP===

% '''vlc -vvv rtsp://www.hardradio.com/tonbeme.mov'''
where '''rtsp://www.hardradio.com/tonbeme.mov''' is the address of the stream.

===Receive a stream described by an SDP file===

% '''vlc -vvv http://server.example.org/stream.sdp'''

==Save a stream with VLC==

VLC can save the stream to the disk. In order to do this, use the Stream Output of VLC : you can do it via the graphical interface, or you can add to the command line the following argument:

'''--sout file/muxer:stream.xyz'''
where:
*'''muxer''' is one of the formats supported by VLC's stream output, i.e. :
**'''ogg''' for OGG format,
**'''ps''' MPEG2-PS format,
**'''ts''' for MPEG2-TS format.
* and '''stream.xyz''' is the name of the file you want to save the stream to, with the right extension.

==Receive a stream with a set-top-box==

Some set-top-boxes with Ethernet cards can receive MPEG2-TS streams over UDP and support multicast.

Set-top-boxes known to work with VLC are :
*[http://www.pace.co.uk Pace] set top boxes. (Pace Micro DSL 4000)
*[http://www.aminocom.com Aminocom] set top boxes. (all the models with mpeg2)
*tuxia / gct-allwell (mpeg4 and mpeg2) sigma designs8174 chipset
*i3micro mood200 (mpeg4 and mpeg2 in transport streams)

{{Documentation}}

Hacker Guide

2007-07-15T19:23:06Z

Stondage123:

<div style="background:red;">
This guide is still being constructed. Please see http://developers.videolan.org/vlc/ for the current information
</div>
===Authors===
* Derk-Jan Hartman

==Introduction==
* [[Documentation:Hacker's Guide/Introduction| What is this?]]
* What you need to know about VLC

==The many layers of VLC==
* Core
* Access
* Demux
* Packetizers
* Codec
* Stream Output
* Interfaces
* Audio/Video Output
* [[Documentation:Hacker's Guide/VLM Internals| VLM Internals]]
* Filters

==VLC source code overview==
* [[VLC source tree]]
* [[Documentation:Hacker's Guide/Module Writers Guide|VLC modules]] (also see [[Modules source tree]] )
* [[Documentation:Hacker's Guide/Object Management|VLC Object Management]]
* VLC preferences
* VLC variables
* [[Doxygen Documentation]]

==Coding for VLC==
* Coding style
* Adding a module
* Using [[Documentation:Hacker's Guide/libvlc|libvlc]]
* Bindings

{{Documentation}}

Talk:Hacker Guide/How To Write a Module

2007-07-15T19:20:13Z

Stondage123: Talk:Module Writers Guide moved to Documentation Talk:Hacker's Guide/Module Writers Guide: Move to Hacker's Guide for consistency

Nice work! Tell us if you need any help. (on a side note: thedj wanted to start a VLC [[Documentation:Hacker's_Guide|Hacker's Guide]], you could try to see with him if your modules documentation could fit in the "VLC modules" subsection)

-- [[User:Dionoea|Dionoea]] 01:07, 13 February 2007 (CET)

Great. I just made a few Wiki Cosmetic changes, and modify the links to the source code.
-- [[User:J-b|J-b]] 09:16, 13 February 2007 (CET)

Module Writers Guide

2007-07-15T19:20:13Z

Stondage123: Module Writers Guide moved to Documentation:Hacker's Guide/Module Writers Guide: Move to Hacker's Guide for consistency

#REDIRECT [[Documentation:Hacker's Guide/Module Writers Guide]]

Hacker Guide/How To Write a Module

2007-07-15T19:20:13Z

Stondage123: Module Writers Guide moved to Documentation:Hacker's Guide/Module Writers Guide: Move to Hacker's Guide for consistency

* This guide is being written by a {{VLC}} novice. Please check all statements below.
* Using [http://trac.videolan.org/vlc/browser/trunk/modules/access/dvdread.c dvdread.c] as the template.

== Module Descriptor ==

A {{VLC}} Module must include a description of itself, and the parameters it accepts.

The module descriptor begins with:
<pre>
vlc_module_being();
</pre>

You should set some category information on your module:
<pre>
set_shortname( _("DVD without menus") );
set_description( _("DVDRead Input (DVD without menu support)") );
set_category( CAT_INPUT );
</pre>
Note the use of _("") to create a string that needs to be translated.

Predefined Categories include:
* CAT_INTERFACE
* CAT_AUDIO
* CAT_VIDEO
* CAT_INPUT
* CAT_SOUT
* CAT_ADVANCED
* CAT_PLAYLIST

<pre>
set_subcategory( SUBCAT_INPUT_ACCESS );
</pre>
See [http://trac.videolan.org/vlc/browser/trunk/include/vlc_configuration.h include/vlc_configuration.h]
for definition of all categories and sub-categories.

=== Adding Parameters ===
All macros take the following argument list:
<pre> add_integer(name, value, p_callback, text, longtext, advc) </pre>
* '''name''' is the string that identifies this parameter in the configuration. This name may be used at the command prompt to set the configuration value.
* '''value''' is the default value for this parameter,
* '''p_callback''' is a function pointer that will be called when the value of this parameter is changed.
** p_callback is called with the following arguments: <pre>( p_this, psz_name, oldval, val, p_config->p_callback_data )</pre>
*** '''p_this''' is a pointer to a vlc_object_t struct,
*** '''psz_name''' is the '''name''' of your parameter that is being changed,
*** '''oldval''' is the old value of the parameter,
*** '''val''' is the new value of the parameter,
*** '''p_call_back_data''' is void* data that you can assign for each parameter. Usually NULL.
* '''text''' A short description of the parameter,
* '''longtext''' A complete description of the parameter,
* '''advc''' Boolean, ADVanced Configuration. If TRUE, this parameter will only be displayed when using the --advanced flag. e.g.
<pre>vlc -p dvdread --advanced</pre>

e.g.
<pre> add_integer("dvdread-angle", 1, NULL, "DVD Angle", "Default DVD Angle", NULL") </pre>

You may add the following parameters to your module:
* add_integer,
* add_string,
* add_float,
* add_bool,
* add_key,
* add_file,
* add_directory,

For complete definitions, see [http://trac.videolan.org/vlc/browser/trunk/include/vlc_configuration.h include/vlc_configuration.h]

== Open(vlc_object_t *) ==

== Close(vlc_object_t *) ==

[[Category:Coding]]

Hacker Guide/VLM Internals

2007-06-11T16:05:55Z

Stondage123:

==Introduction==
VideoLAN Manager is a small media manager designed to control multiple streams with only one instance of VLC. It allows multiple streaming and video on demand (VoD). VLM can be controlled through the telnet and http interfaces of VLC as described in [[Documentation:Streaming_HowTo/VLM]].

This document will describe the internals of VLM including data structures and functions, as well the the libvlc bindings for control of vlm.

==vlm_t==

In a running instance of VLC or libvlc only 1 instance of VLM can be running. This instance of VLM is represented by '''''struct vlm_t''''' as defined in '''''src/input/vlm_internal.h'''''. '''''vlm_t''''' contains a list of Medias, Schedules and vod servers, as well as a lock for the data structure, and a unique id. In essence, the '''''vlm_t''''' data structure is the global container for all VLM related data.

==Medias and Instances==

A ''Media'' is composed with a list of inputs (the video and audio streams you want to stream), an output (how and where you want to stream them) and some options.

There are two types of medias:
*'''vod''': A vod media is commonly used for Video on Demand. It will be launched only if a vod client asks for it.
*'''broadcast''': A broadcast media is very close to a TV program or channel. It is launched, stopped or paused by the administrator and may be repeated several times. The client has no control over this media.

A media is represented by the structure '''''vlm_media_sys_t''''' defined in '''''src/input/vlm_internal.h'''''. Each '''''vlm_media_sys_t''''' contains a configuration structure, a list of instances of the media, as well as a structure representing a vod server which is initialized only if the media is of type vod.

The configuration structure is of type '''''vlm_media_t''''' (a misnomer due to historical reasons) and contains the name of the media, as well as its type and a host of other details. It is defined in '''''src/input/vlm_internal.h''''' also.

A media instance is represented by the structure '''''vlm_media_instance_sys_t''''' defined in '''''src/input/vlm_internal.h''''' also. This structure contains a playlist index as well as the current input thread and output stream instance. Mulitple media instances can exist for each media.

Each VOD server is represented by the struct '''''vod_t'''''. This structure contains a pointer to the module that will be loaded to help the vod server, as well as a pointer to an RTSP server. It also contains several function pointers to help create and delete vod medias of type '''''vod_media_t'''''. Each '''''vod_media_t''''' is actually referenced by a '''''vlm_media_sys_t''''' if that media is of vod type. '''''vod_t''''' is defined in '''''include/vlc_vod.h''''' and '''''vod_media_t''''' is defined in '''''modules/misc/rtsp.c'''''

The layout of the main vlm structures hierarchically looks like this:
<pre>
vlm_t
vlm_media_sys_t
vlm_media_t
vlm_media_instance_sys_t
vod_media_t
vod_t
</pre>

==Schedules==

==Initializing VLM and Adding Medias==

Since VLM is a part of libvlc, I will describe initialization of VLM with respect to libvlc. If we want to use VLM we are probably going to have at least one media. Therefore we can use the libvlc functions '''''libvlc_vlm_add_broadcast()''''' or '''''libvlc_vlm_add_vod()''''' to instantiate and initialize VLM. Each one of these functions checks to see if a VLM instance exists. If it does not, the function creates a '''''vlm_t''''' instance and creates and adds either a broadcast or vod media to the '''''vlm_t''''' instance. If the media is of type vod, then a separate '''''vod_media_t''''' is created and linked to the media of type '''''vlm_media_sys_t''''' and a vod server of type '''''vod_t''''' is created and linked to the '''''vlm_t''''' instance.

Note also, that the VLM instance is attached to the libvlc instance as a singleton, therefore allowing only one VLM instance per libvlc instance. Both '''''libvlc_vlm_add_broadcast()''''' and '''''libvlc_vlm_add_vod()''''' wrap around the '''''VLM()''''' macro which wraps around '''''__vlm_New()''''' which actually does the instantiation, initialization, and binding of the VLM instance to the libvlc instance. These functions are found in the '''''src/control/vlm.c'''''. '''''__vlm_New()''''' is found in '''''src/input/vlm.c'''''.

==Control==

Once VLM is initialized, there needs to be some way to control it, such as adding medias, starting and stopping a media instance, etc... The '''''vlm_Control()''''' function is used for this purpose. This allows all VLM commands to be issued through one common interface, and it takes care of locking issues. By executing '''''vlm_Control()''''' with the proper command code, such as '''''VLM_ADD_MEDIA''''', and a variable argument list, any VLM command can be executed without the need to understand the lower level details. This allows for easily wrapping the VLM code to be used by many interfaces. '''''vlm_Control()''''' can be found in '''''src/input/vlm.c'''''. The list of VLM command codes can be found in the enumerated type '''''vlm_query_e''''' in the file '''''include/vlc_vlm.h'''''.

==Thread Creation==

VLM is a complex subsystem within VLC. When VLM is initialized, when a media is created etc..., threads are created to handle these tasks. This section will describe the thread model used by VLM.

When new instance of VLM is created by the '''''__vlm_New()''''' function, a management thread is created which has as its start function '''''Manage()''''' residing in '''''src/input/vlm.c'''''. This takes care of scheduling, as well as destruction of dead input objects.

when a new vod media is added to VLM, an input thread is created with '''''Run()''''' as its start function. This thread takes care of all streaming for that media.

If a broadcast media is added, it needs to be played. When The libvlc function '''''libvlc_vlm_play_media()''''' is called, an instance of the broadcast media is created as well as an input thread with '''''Run()''''' as its start function. This thread takes care of all streaming for the broadcast instance by calling appropriate demux, codec, and sout modules.

Hacker Guide/libvlc

2007-06-08T18:18:16Z

Stondage123:

==Libvlc Startup==

===Introduction===
Libvlc represents the underlying API of vlc. VLC itself is just a wrapper around libvlc. By utilizing libvlc developers can take advantage of all the complex functionalities of vlc. Libvlc is generated as a shared library and can be wrapped up with numerous interfaces, including both Python and Java bindings. This allows the end user to build applications around the vlc code base and take advantage of all the plugins available to vlc instead of writing everything from scratch.

This document will explain how to get started using libvlc. It will step through the instantiation of a libvlc instance and explain the typical startup procedure of libvlc.

===Libvlc Instantiation===

Libvlc is a singleton. For each application wrapped around libvlc, only one libvlc instance should be running. In order to create an instance of libvlc, you must call '''''libvlc_new()'''''. This function initializes the thread system and allocates a libvlc instance. '''''libvlc_new()''''' resides in '''''src/control/core.c'''''.

'''''libvlc_new()''''' calls '''''libvlc_InternalInit()''''' which handles command line parsing, loads the module bank, and spawns a number of threads to handle various vlc subsystems. The threads are spawned from inside the function '''''playlist_ThreadCreate()'''''. Below is a list of thread start functions that are run for playlist processing. The threads corresponding to these functions are spawned in the order listed.

* '''''RunPreparse()''''' - Perform initial parsing of the playlist
* '''''RunFetcher()''''' - load artwork associated with playlist item
* '''''RunControlThread()''''' - perform playlist scheduling and playing

See [[Documentation:Hacker's Guide/Playlists|Playlists]] for more details.

Hacker Guide

2007-06-08T18:16:56Z

Stondage123: /* Coding for VLC */

<div style="background:red;">
This guide is still being construced. Please see http://developers.videolan.org/vlc/ for the current information
</div>
===Authors===
* Derk-Jan Hartman

==Introduction==
* [[Documentation:Hacker's Guide/Introduction| What is this?]]
* What you need to know about VLC

==The many layers of VLC==
* Core
* Access
* Demux
* Packetizers
* Codec
* Stream Output
* Interfaces
* Audio/Video Output
* [[Documentation:Hacker's Guide/VLM Internals| VLM Internals]]
* Filters

==VLC source code overview==
* [[VLC source tree]]
* VLC modules
* [[Documentation:Hacker's Guide/Object Management|VLC Object Management]]
* VLC preferences
* VLC variables

==Coding for VLC==
* Coding style
* Adding a module
* Using [[Documentation:Hacker's Guide/libvlc|libvlc]]
* Bindings

{{Documentation}}

Hacker Guide/VLM Internals

2007-06-06T16:07:39Z

Stondage123:

==Introduction==
VideoLAN Manager is a small media manager designed to control multiple streams with only one instance of VLC. It allows multiple streaming and video on demand (VoD). VLM can be controlled through the telnet and http interfaces of VLC as described in [[Documentation:Streaming_HowTo/VLM]].

This document will describe the internals of VLM including data structures and functions, as well the the libvlc bindings for control of vlm.

==vlm_t==

In a running instance of VLC or libvlc only 1 instance of VLM can be running. This instance of VLM is represented by '''''struct vlm_t''''' as defined in '''''src/input/vlm_internal.h'''''. '''''vlm_t''''' contains a list of Medias, Schedules and vod servers, as well as a lock for the data structure, and a unique id. In essence, the '''''vlm_t''''' data structure is the global container for all VLM related data.

==Medias and Instances==

A ''Media'' is composed with a list of inputs (the video and audio streams you want to stream), an output (how and where you want to stream them) and some options.

There are two types of medias:
*'''vod''': A vod media is commonly used for Video on Demand. It will be launched only if a vod client asks for it.
*'''broadcast''': A broadcast media is very close to a TV program or channel. It is launched, stopped or paused by the administrator and may be repeated several times. The client has no control over this media.

A media is represented by the structure '''''vlm_media_sys_t''''' defined in '''''src/input/vlm_internal.h'''''. Each '''''vlm_media_sys_t''''' contains a configuration structure, a list of instances of the media, as well as a structure representing a vod server which is initialized only if the media is of type vod.

The configuration structure is of type '''''vlm_media_t''''' (a misnomer due to historical reasons) and contains the name of the media, as well as its type and a host of other details. It is defined in '''''src/input/vlm_internal.h''''' also.

A media instance is represented by the structure '''''vlm_media_instance_sys_t''''' defined in '''''src/input/vlm_internal.h''''' also. This structure contains a playlist index as well as the current input thread and output stream instance. Mulitple media instances can exist for each media.

Each VOD server is represented by the struct '''''vod_t'''''. This structure contains a pointer to the module that will be loaded to help the vod server, as well as a pointer to an RTSP server. It also contains several function pointers to help create and delete vod medias of type '''''vod_media_t'''''. Each '''''vod_media_t''''' is actually referenced by a '''''vlm_media_sys_t''''' if that media is of vod type. '''''vod_t''''' is defined in '''''include/vlc_vod.h''''' and '''''vod_media_t''''' is defined in '''''modules/misc/rtsp.c'''''

The layout of the main vlm structures hierarchically looks like this:
<pre>
vlm_t
vlm_media_sys_t
vlm_media_t
vlm_media_instance_sys_t
vod_media_t
vod_t
</pre>

==Schedules==

==Initializing VLM and Adding Medias==

Since VLM is a part of libvlc, I will describe initialization of VLM with respect to libvlc. If we want to use VLM we are probably going to have at least one media. Therefore we can use the libvlc functions '''''libvlc_vlm_add_broadcast()''''' or '''''libvlc_vlm_add_vod()''''' to instantiate and initialize VLM. Each one of these functions checks to see if a VLM instance exists. If it does not, the function creates a '''''vlm_t''''' instance and creates and adds either a broadcast or vod media to the '''''vlm_t''''' instance. If the media is of type vod, then a separate '''''vod_media_t''''' is created and linked to the media of type '''''vlm_media_sys_t''''' and a vod server of type '''''vod_t''''' is created and linked to the '''''vlm_t''''' instance.

Note also, that the VLM instance is attached to the libvlc instance as a singleton, therefore allowing only one VLM instance per libvlc instance. Both '''''libvlc_vlm_add_broadcast()''''' and '''''libvlc_vlm_add_vod()''''' wrap around the '''''VLM()''''' macro which actually does the instantiation, initialization, and binding of the VLM instance to the libvlc instance. These functions are found in the '''''src/control/vlm.c'''''.

==Control==

Once VLM is initialized, there needs to be some way to control it, such as adding medias, starting and stopping a media instance, etc... The '''''vlm_Control()''''' function is used for this purpose. This allows all VLM commands to be issued through one common interface, and it takes care of locking issues. By executing '''''vlm_Control()''''' with the proper command code, such as '''''VLM_ADD_MEDIA''''', and a variable argument list, any VLM command can be executed without the need to understand the lower level details. This allows for easily wrapping the VLM code to be used by many interfaces. '''''vlm_Control()''''' can be found in '''''src/input/vlm.c'''''. The list of VLM command codes can be found in the enumerated type '''''vlm_query_e''''' in the file '''''include/vlc_vlm.h'''''.

==TO BE CONTINUED...==

Hacker Guide/VLM Internals

2007-06-06T15:21:09Z

Stondage123: /* Initializing VLM and Adding Medias */

Hacker Guide/VLM Internals

2007-06-06T15:12:57Z

Stondage123:

Hacker Guide/VLM Internals

2007-06-06T13:59:20Z

Stondage123:

User talk:Stondage123

2007-06-06T13:22:15Z

Stondage123:

== Documentation ==

Hi. Thanks for writing documentation. I'd really appreciate if you could keep the documentation pages in the Documentation namespace. (As stated here: [[Documentation_Talk:Hacker's Guide]] ). Thanks, [[User:Dionoea|Dionoea]] 09:32, 6 June 2007 (CEST)

Hi Dionoea. I'm sorry about using the wrong namespace. I'm still new to the wild world of wikis :) I'll put everything in the right place from now on. As I reverse engineer/understand more of the code I will add documentation and some patches. You guys really do some great work here.

-Andrew

: I already moved all the pages to the correct namespaces [[User:J-b|jb]] 15:11, 6 June 2007 (CEST)

Thanks J-B !

User talk:Stondage123

2007-06-06T12:58:34Z

Stondage123:

Hacker Guide/VLM Internals

2007-06-05T22:16:42Z

Stondage123: VLM Internals

Hacker Guide

2007-06-05T22:05:32Z

Stondage123: /* The many layers of VLC */

<div style="background:red;">
This guide is still being construced. Please see http://developers.videolan.org/vlc/ for the current information
</div>
===Authors===
* Derk-Jan Hartman

==Introduction==
* [[What is this?]]
* What you need to know about VLC

==The many layers of VLC==
* Core
* Access
* Demux
* Packetizers
* Codec
* Stream Output
* Interfaces
* Audio/Video Output
* [[VLM Internals]]
* Filters

==VLC source code overview==
* [[VLC source tree]]
* VLC modules
* [[Documentation:Hacker's Guide/Object Management|VLC Object Management]]
* VLC preferences
* VLC variables

==Coding for VLC==
* Coding style
* Adding a module
* Using libvlc
* Bindings

{{Documentation}}

Hacker Guide

2007-06-05T22:04:59Z

Stondage123: /* The many layers of VLC */

<div style="background:red;">
This guide is still being construced. Please see http://developers.videolan.org/vlc/ for the current information
</div>
===Authors===
* Derk-Jan Hartman

==Introduction==
* [[What is this?]]
* What you need to know about VLC

==The many layers of VLC==
* Core
* Access
* Demux
* Packetizers
* Codec
* Stream Output
* Interfaces
* Audio/Video Output
* [[VLM]]
* Filters

==VLC source code overview==
* [[VLC source tree]]
* VLC modules
* [[Documentation:Hacker's Guide/Object Management|VLC Object Management]]
* VLC preferences
* VLC variables

==Coding for VLC==
* Coding style
* Adding a module
* Using libvlc
* Bindings

{{Documentation}}

User talk:Stondage123

2007-06-05T20:14:34Z

Stondage123: Redirecting to Coding:Object Management

#REDIRECT [[Coding:Object Management]]
[[VLM Internals]]

Hacker Guide

2007-06-04T14:57:08Z

Stondage123: /* Introduction */

<div style="background:red;">
This guide is still being construced. Please see http://developers.videolan.org/vlc/ for the current information
</div>
===Authors===
* Derk-Jan Hartman

==Introduction==
* [[What is this?]]
* What you need to know about VLC

==The many layers of VLC==
* Core
* Access
* Demux
* Packetizers
* Codec
* Stream Output
* Interfaces
* Audio/Video Output
* VLM
* Filters

==VLC source code overview==
* [[VLC source tree]]
* VLC modules
* [[Documentation:Hacker's Guide/Object Management|VLC Object Management]]
* VLC preferences
* VLC variables

==Coding for VLC==
* Coding style
* Adding a module
* Using libvlc
* Bindings

{{Documentation}}

Hacker Guide

2007-05-31T21:52:45Z

Stondage123: /* VLC source code overview */

<div style="background:red;">
This guide is still being construced. Please see http://developers.videolan.org/vlc/ for the current information
</div>
===Authors===
* Derk-Jan Hartman

==Introduction==
* What is this?
* What you need to know about VLC

==The many layers of VLC==
* Core
* Access
* Demux
* Packetizers
* Codec
* Stream Output
* Interfaces
* Audio/Video Output
* VLM
* Filters

==VLC source code overview==
* [[VLC source tree]]
* VLC modules
* VLC [[Documentation:Object Management]]
* VLC preferences
* VLC variables

==Coding for VLC==
* Coding style
* Adding a module
* Using libvlc
* Bindings

{{Documentation}}

Hacker Guide

2007-05-31T21:50:14Z

Stondage123: /* VLC source code overview */

<div style="background:red;">
This guide is still being construced. Please see http://developers.videolan.org/vlc/ for the current information
</div>
===Authors===
* Derk-Jan Hartman

==Introduction==
* What is this?
* What you need to know about VLC

==The many layers of VLC==
* Core
* Access
* Demux
* Packetizers
* Codec
* Stream Output
* Interfaces
* Audio/Video Output
* VLM
* Filters

==VLC source code overview==
* [[VLC source tree]]
* VLC modules
* VLC [[Object Management]]
* VLC preferences
* VLC variables

==Coding for VLC==
* Coding style
* Adding a module
* Using libvlc
* Bindings

{{Documentation}}

Hacker Guide/Object Management

2007-05-31T21:45:55Z

Stondage123: Coding:Object Management moved to Documentation:Object Management: I messed up

== VLC Object Management ==

'''Introduction'''

This paper will discuss VLC objects and the general object oriented practices involved in developing and extending libvlc.

'''Object Creation'''

In VLC everything is an object. Each object can have a parent and multiple children. The following functions are used for creating an object and attaching to parents and children. Note that this list may not be complete. For reference see the file ''include/vlc_objects.h''.

''vlc_object_create()'' - create an object and set its refcount to 0

''vlc_object_destroy()'' - de-allocate an object iff its refcount = 0

''vlc_object_attach()'' - bidirectionally link an object with its parent

''vlc_object_detach()'' - remove all links between an object and its parent

'''Inheritance'''

Objects can have multiple levels of inheritance. Each object is represented by the type ''vlc_object_t'' . Every object inherits from this type and can be cast to it. Inheritance is achieved in the C language by embedding a macro of common structure elements (VLC_COMMON_MEMBERS) inside each inherited object structure. For example, a libvlc instance of type ''libvlc_int_t'' inherits from ''vlc_object_t'' by embedding the VLC_COMMON_MEMBERS inside the ''libvlc_int_t structure'' as seen in example 1 below.

<u>Example 1: libvlc_int_t : vlc_object_t</u>
<pre>
struct libvlc_int_t
{
VLC_COMMON_MEMBERS

/* Everything Else */
}
</pre>

'''Reference Counts'''

In order to simplify garbage collection, every object has a reference count. When an object is created (malloc()'d) its reference count is set to 0. Anytime the object is acquired for use by a caller that caller must increase its reference count by 1. When the caller is done using the object it must decrease the object's reference count by 1. Luckily, most of this is handled by internal object management acquisition and removal functions. In order to destroy (free()) the object the reference count of the object must be 0. The following functions are used to manipulate object reference counts. Note that this list may not be complete. For reference see the file ''include/vlc_objects.h''.

''vlc_object_yield()'' - increase the refcount of an object by 1. This function should only be used in object management functions! Careless usage will lead to memory leaks!

''vlc_object_release()'' - decrease the refcount of an object by 1. This function should only be used in object management functions! Careless usage can lead to early object destruction, while the object may still be in use!

'''Threads'''

VLC is a multithreaded application. Thread handling is performed by the following functuions. See ''include/vlc_threads_funcs.h''.

''vlc_thread_create()'' - spawn a new thread

''vlc_thread_set_priority()'' - set the priority of a thread

''vlc_thread_ready()'' - alert the parent that we were successfully spawned

''vlc_thread_join()'' - wait for a thread to exit

'''Mutexes'''

VLC is a multithreaded program and as such it requires objects to be protected from concurrency related issues such as race conditions. In order to protect objects a mutex object is used. The mutex is of type vlc_mutex_t and contains a pointer to the object that the mutex is protecting as well as an OS level mutex primitive. See Example 2 below for a sample declaration of ''vlc_mutex_t'' under Linux using pthreads. Actual implementations for your OS can be found in ''include/vlc_threads.h''.

<u>Example 2: vlc_mutex_t</u>
<pre>
typedef struct
{
pthread_mutex_t mutex; /* OS primitive */
vlc_object_t * p_this; /* pointer to object that mutex protects */
} vlc_mutex_t;
</pre>

Operations on ''vlc_mutex_t'' objects are wrapped by VLC to enhance portability. Below is a list of operations on mutex objects. This list is incomplete. See ''include/vlc_threads_funcs.h''.

''vlc_mutex_init()'' - initialize a mutex

''vlc_mutex_lock()'' - lock an object

''vlc_mutex_unlock()'' - unlock an object

User talk:Stondage123

2007-05-31T21:21:58Z

Stondage123: User talk:Stondage123 moved to Coding:Object Management: Publish for everyone

#REDIRECT [[Coding:Object Management]]

Hacker Guide/Object Management

2007-05-31T21:21:57Z

Stondage123: User talk:Stondage123 moved to Coding:Object Management: Publish for everyone

Hacker Guide/Object Management

2007-05-31T21:14:40Z

Stondage123: VLC Object Management