VideoLAN Wiki - User contributions [en]

Documentation:Streaming HowTo/VLM

2010-01-04T23:41:44Z

Thehtoad: /* Configuration Files */ spelling

{{RightMenu|documentation streaming howto toc}}

==VLM==

''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). This manager being a new feature, it can only be controlled by the telnet interface or the http interface.

===Interfaces===

====Telnet interface====

You can launch the telnet interface as a common interface using the command line:
% '''vlc --intf telnet'''

% '''vlc --extraintf telnet'''

The telnet interface can also be launched in the wxWindows interface:

http://www.videolan.org/doc/streaming-howto/en/images/streaming-howto/intf-wx-extraintf-telnet.jpg Launching the Telnet interface - wxWindows interface

The default port is 4212. The default password is "admin". These can be changed using '''--telnet-port <integer>''' and '''--telnet-password <string>''' command line options. They can also be changed in the preferences panel when using the wxWindows interface in the ''Modules''->''interface''->''telnet'' section (check the ''Advanced options'' checkbox).

====HTTP interface====

Launching the HTTP interface is described in [[Control_VLC_via_a_browser]]

To access the vlm section of the http interface, use the following URL: ''http://host:port/vlm.html'' (''http://host:port/vlm/'' for VLC 0.8.4 and older).

'''Note:''' People who aren't used to command line streaming with VLC but want to use VLM's features are advised to use the HTTP interface.

===VLM Elements===

====Medias====

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.

====Schedules====

A ''Schedule'' is a script with a date. When the schedule date is reached, the script is launched. There are several options available like a period or a number of repetitions.

===Command line syntax===

====Command lines====

*'''help''': Displays an exhaustive command lines list
*'''new (name) vod|broadcast|schedule [properties]''': Create a new vod, broadcast or schedule element. Element names must be unique and cannot be "media" or "schedule". You can specify properties in this command line or later on by using the '''setup''' command.
*'''setup (name) (properties)''': Set an elements property. See <xref linkend="vlmprop" endterm="tvlmprop" />.
*'''show [(name)|media|schedule]''': Display current element states and configurations.
**'''show (name)''': Specify an element's name to show all information concerning this element.
**'''show media''' displays a summary of media states.
**'''show schedule''' displays a summary of schedule states.
*'''del (name)|all|media|schedule''': Delete an element or a group of elements. If the element wasn't stopped, it is first stopped before being deleted.
**'''del (name)''': Delete the (name) element.
**'''del all''': Delete all elements
**'''del media''': Delete all media elements.
**'''del schedule''': Delete all schedule elements.
*'''control (name) [instance_name] (command)''': Change the state of the (instance_name) instance of the (name) media. If (instance_name) isn't specified, the control command affects the default instance. See <xref linkend="vlmctrl" endterm="tvlmctrl" /> for available control commands.
*'''save (config_file)''': Save all media and schedule configurations in the specified config file. The config file path is relative to the directory in which vlc was launched. If the file exists it will be overwritten. Note that states, such as playing, paused or stop, are not saved. See <xref linkend="vlmconf" endterm="tvlmconf" /> for more info.
*'''load (config_file)''': Load a configuration file. The config file path is relative to the directory in which vlc was launched. See <xref linkend="vlmconf" endterm="tvlmconf"/> for more info.

====Media Properties====

Note: Except the "append" property, all properties can be followed by another one.

*'''input (input_name)''': Add an input to the end of the media's input list.
*'''output (output_name)''': Define the media's output. The syntax is the same as the vlc ":sout=..." vlc option but you do not have to put the ":sout=..." string. See <xref linkend="cmdline" endterm="tcmdline" /> for more information concerning stream outputs (sout). Note: You do not have to specify an output for vod elements.
*'''option (option_name)[=value]''' : Adds the (option_name) to the media option list. The syntax is equivalent to the ":(option)=..." option , but you do not have to put the ":" string. Options are global: they are applied to all inputs of the media.
*'''enabled|disabled''': Enable or Disable the media. If a media is disabled, it cannot be streamed, paused, launched by a schedule, or played as VoD.
*'''loop|unloop (broadcast only)''': If a media with the "loop" option receives the "play" command, it will automatically restart to play the input list once the end of the input list is reached. Note: '''loop|unloop''' is only used for broadcast media types.
*'''mux (mux_name)''': This option should only be specified if you want the elementary streams to be sent encapsulated instead of raw. The (mux_name) should be specified as a four characters length identifier such as mp2t for MPEG TS or mp2p for MPEG PS. See <xref linkend="smc" endterm="tsmc" />. Note: The '''mux''' property is only used for vod media types.

====Schedule Properties====

*'''enabled|disabled''': A disabled schedule will never be launched.
*'''append (command_until_rest_of_the_line)''': Add a command to the command line lit. The command line can be every command VLM can understand. Note: The rest of the line will be considered as part of the command line. You cannot put another option after the '''append''' one.
*'''date (year)/(month)/(day)-(hour):(minutes):(seconds)|now''': Specify the first date the schedule should be launched. You can specify a date using the '''(year)/(month)/(day)-(hour):(minutes):(seconds)''' format (example: 2004/11/16-00:43:12) or using the '''now''' keyword. If '''now''' is used, the schedule will be launched as soon as possible (i.e. as soon as it is enabled) and the current date will be used as the first date of the schedule.
*'''period (years_aka_12_months)/(months_aka_30_days)/(days)-(hours):(minutes):(seconds)''': Specify the period of time a schedule must wait for launching itself another time. (Months are considered as 30 days, Years as 12 months) If a period is specified without a '''repeat''' property, the schedule will be launched endlessly.
*'''repeat (number_of_repetitions)''': Specify the number of times the schedule will be launched again. For example, if a schedule has '''repeat 11''' it will be launched 12 times.

====Control Commands====

*'''play''': Stat a broadcast media. The media begins to launch the first item of the input list, then launches the next one and so on. (like a play list)
*'''pause''': Put the broadcast media in paused status.
*'''stop''': Stop the broadcast media.
*'''seek (percentage)''': Seek in the current playing item of the input list.

===Configuration Files===

A VLM configuration file is a list of command lines : one line corresponds to one command line.

To create a configuration file, just edit a text file and type a list of VLM commands. Beware of recursive calls: you can put a '''load (file)''' in a configuration file which can lead to recursive inclusion of the same file and result in VLC's crash.

You can automatically load a VLM configuration when launching VLC with the --vlm-conf <vlm conf filename> command line option. The minimal command to make that work is:
% '''vlc -I telnet --vlm-conf vlm.conf'''

As of versions > 0.8.1, any line where the first non white space character is a # is considered as a comment.

==Examples==

This section provides several small vlm configuration files.

===Multiple streams===

====Simple broadcasting====

new channel1 broadcast enabled
setup channel1 input http://host.mydomain/movie.mpeg
setup channel1 output #rtp{mux=ts,dst=239.255.1.1,port=5004,sdp=sap://,name="Channel 1"}

new channel2 broadcast enabled
setup channel2 input udp://@239.255.12.42
setup channel2 output #rtp{mux=ts,dst=239.255.1.2,port=5004,sdp=sap://,name="Channel 2"}

control channel1 play
control channel2 play

*if you are using direct show and are getting "control : unknown error" try "setup ''channel'' enabled"

====Scheduled broadcasting====

new my_media broadcast enabled
setup my_media input my_video.mpeg input my_other_movie.mpeg
setup my_media output #rtp{mux=ts,dst=239.255.1.1,sdp=sap://,name="My Media"}

new my_sched schedule enabled
setup my_sched date 2012/12/12-12:12:12
setup my_sched append control my_media play

===Video On Demand===

====Basic example====

First launch the vlc
% '''vlc --ttl 12 -vvv --color -I telnet --telnet-password videolan --rtsp-host 0.0.0.0:5554'''
where:
*'''12''' is the value of the TTL (Time To Live) of your IP packets (which means that the stream will be able to cross 11 routers).
*'''telnet''' launches the telnet interface of the vlc.
*'''videolan''' is the password to connect to the telnet interface.
*'''0.0.0.0''' is the host address.
*'''5554''' is the port on which you stream.

Then you connect to the vlc telnet interface and create the vod object
new Test vod enabled
setup Test input my_video.mpg
You can access to the stream with:
% '''vlc rtsp://server:5554/Test'''
where:
* '''server''' is the address of the streaming server (IP or DNS)

{{Documentation}}

Documentation:Advanced Use of VLC

2010-01-04T16:36:44Z

Thehtoad: /* Modules selection */ grammar

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast RTP/UDP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@:5004'''

If 5004 is the port to which packets are sent. 1234 is another commonly used port number. you use the default port (1234), '''vlc rtp://''' will do.
For more information, look at the Streaming Howto.

To receive an multicast UDP/RTP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@multicast_address:port'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc rtp://server_address@multicast_address:port'''

This only works on OSs that support SSM (Windows XP and Linux).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always tries to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--grayscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--video-filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

See the [[Documentation:WebPlugin|documentation]] for building page for this plugin.

{{Documentation}}

=Snapshot Tool=
Did you know you can use special codes to automatically generate filenames in the [[SnapshotTool|Snaphot Tool]]?

Hacker Guide/Interfaces

2010-01-04T15:59:35Z

Thehtoad: spelling

=VLC Interface=

==A typical VLC run course==

This section describes what happens when you launch the vlc program. After the ELF dynamic loader blah blah blah, the main thread becomes the interface thread. It passes through the following steps :

#CPU detection : which CPU are we running on, what are its capabilities (MMX, MMXEXT, 3DNow, AltiVec...) ?
#Message interface initialization ;
#Command line options parsing ;
#Playlist creation ;
#Module bank initialization ;
#Interface opening ;
#Signal handler installation : SIGHUP, SIGINT and SIGQUIT are caught to manage a clean quit (please note that the SDL library also catches SIGSEGV) ;
#Audio output thread spawning ;
#Video output thread spawning ;
#Main loop : events management ;

Following sections describe each of these steps in particular, and many more.

==The message interface==

It is a known fact that printf() functions are not necessarily thread-safe. As a result, one thread interrupted in a printf() call, followed by another calls to it, will leave the program in an undetermined state. So an API must be set up to print messages without crashing.

This API is implemented in two ways. If INTF_MSG_QUEUE is defined in config.h , every printf-like (see below) call will queue the message into a chained list. This list will be printed and flushed by the interface thread once upon an event loop. If INTF_MSG_QUEUE is undefined, the calling thread will acquire the print lock (which prevents two print operations to occur at the same time) and print the message directly (default behaviour).

Functions available to print messages are :

*msg_Info ( p_this, ... ) : Print a message to stdout , plain and stupid (for instance "it works!").
*msg_Err( p_this, ... ) : Print an error message to stderr .
*msg_Warn( p_this, ... ) : Print a message to stderr if the warning level (determined by -v, -vv and -vvv) is low enough. ''Please note that the lower the level, the less important the message is.''
*msg_Dbg( p_this, ... ) : This function is designed for optional checkpoint messages, such as "we are now entering function dvd_foo_thingy". It does
nothing in non-trace mode. If the VLC is compiled with --enable-trace, the message is either written to the file vlc-trace.log (if TRACE_LOG is defined in config.h), or printed to stderr (otherwise).
*msg_Flush(p_this) : Flush the message queue, if it is in use.

==Command line options==

VLC uses GNU getopt to parse command line options. getopt structures are defined in src/extras/getopt.c and command line parsing is done in src/config/cmdline.c

Most configuration directives are exchanged via the environment array, using main_Put*Variable and main_Get*Variable. As a result, ./vlc --height 240 is strictly equivalent to : vlc_height=240 ./vlc. That way configuration variables are available everywhere, including plugins.

===Warning===

Please note that for thread-safety issues, you should not use main_Put*Variable once the second thread has been spawned

==Playlist management==

The playlist is created on startup from files given in the command line. An appropriate interface plugin can then add or remove files from it. Functions to be used are described in src/playlist/control.c.

==Module bank==

On startup, VLC creates a bank of all available .so files (plugins) in ., ./lib, /usr/local/lib/videolan/vlc (PLUGIN_PATH), and built-in plugins. Every plugin is checked with its capability, which is set by a call to set_capability(void* capability, int score). The different capabilities are:

*interface : An interface plugin (in modules/control and modules/gui)
*access :
*access_filter :
*sout access : stream output
*sout stream :
*audio filter :
*video filter :
*video filter2 :
*audio mixer :
*demux : démultiplexeur
*packetizer :
*meta reader : meta engine
*sout mux : multiplexeur streaming output
*services_discovery :
*chroma :
*decoder : decoder. Pour définir un decoder audio ou video, utiliser set_subcategory( SUBCAT_INPUT_ACODEC ) ou set_subcategory( SUBCAT_INPUT_VCODEC )
*audio output : An audio output module
*video output : A video output module
*vizualisation :
*packetizer :

How to write a plugin is described in the latter sections. Other threads can request a plugin descriptor with module_Need ( module_bank_t * p_bank, int i_capabilities, void * p_data ). p_data is an optional parameter (reserved for future use) for the pf_probe() function. The returned module_t structure contains pointers to the functions of the plug-in. See include/modules.h for more information.

==The interface main loop==

The interface thread will first look for a suitable interface plugin. Then it enters the main interface loop, with the plugin's pf_run function. This function will do what's appropriate, and every 100 ms will call (typically via a GUI timer callback) InteractionManage.

InteractionManage cleans up the module bank by unloading unnecessary modules, manages the playlist, and flushes waiting messages (if the message queue is in use).

==How to write an interface plugin==
===API for the Module===

Have a look the files in directories modules/misc/control, modules/misc/access, or modules/gui. However the GUI interfaces are not very easy to understand, since they are quite big. I suggest to start digging into a non-graphical interface modules first. For example modules/control/hotkeys.c.

An interface module is made of 3 entry functions and a module description:

*The module description is made of macros that declares the capabilities of the module (interface, in this case) with their priority, the module description as it will appear in the preferences of GUI modules that implement them, some configuration variables specific to the module, shortcuts, sub-modules, etc.
*Open ( vlc_object_t* p_object ): This is called by VLC to initialize the module.
*Run ( vlc_object_t* p_object ): really does the job of the interface module (waiting for user input and displaying info). It should check periodically that p_intf->b_die is not VLC_TRUE.
*Close ( vcl_object_t * p_object ) function is called by VLC to uninitialize the module (basically, this consists in destroying whatever have been allocated by Open)

The above functions take a vlc_object_t* as argument, but that may need to be cast into a intf_thread_t* depending on your needs. This structure is often needed as a parameter for exported VLC functions, such as msg_Err(), msg_Warn(), ...

Define intf_sys_t to contain any variable you need (don't use static variables, they suck in a multi-threaded application :-).

If additional capabilities (such as Open button, playlist, menus, etc.) are needed, consult one of the GUI modules. One of the simpler GUI modules to consult might be modules/gui/ncurses/ncurses.c. It is a quite simple complete interface module with playlist interaction, and progress bar, among other things.

===Arranging for your Module to get Compiled===

If you create a new directory for your module, add a Modules.am file in it. In this file, put something like : SOURCES_yourmodule = myfile1.c myfile2.c

Then go to the main configure.ac file, and add in the AC_CONFIG_FILES section (towards the end of the file) a line similar to the others.

If you don't create a directory for your plugin (but instead just put it in an existing directory), you only have to add the two SOURCES_... lines to the existing Modules.am file

This declares your module; it does not arrange for it to be automatically compiled; automatic compilatoin is described further below.

You do not write a Makefile for your module. Instead this is done via the bootstrap and configuration process. So now run:

./bootstrap

./configure configure-options

make

To build the module manually, go to the directory it resides and type make libyourmodule_plugin.so (or .dll, or whatever the file type for a shared library is on your Operating System.)

To automatically have your module get built, you also set this in the configure.ac file; add your module name to the default modules section in one of the AX_ADD_PLUGINS directives.