VideoLAN Wiki - User contributions [en]

Documentation Talk:Streaming HowTo New

2012-04-26T22:54:10Z

Gth: Suggestion to remove the 'new' version...

== New page? ==
It's rather a mixed message to have this 'new' version of the page. Is there a list of what remains to be added/updated so we can remove this confusion? --[[User:Gth|Gth]] 00:54, 27 April 2012 (CEST)

Documentation:Streaming HowTo New

2012-04-26T22:45:05Z

Gth: /* More Links */ Link was incorrect; moved to "See Also" and corrected.

This documentation explains how to stream, transcode and save streams using [[VLC media player]].

'''NOTE: This is work in progress. For a more complete, yet outdated, documentation on Streaming with VLC please see the old [[Documentation:Streaming HowTo|Streaming HowTo]].'''

==Introduction==
VLC media player is able to stream, transcode and save different media streams. For more information about the formats and codecs supported please see the [http://www.videolan.org/streaming-features.html VideoLAN Streaming Features list].

==Transcoding==
[[Transcode|Transcoding]] is the process of taking a media file or stream and converting it to a different format or bitrate. There are two methods for transcoding in VLC, via the GUI (VLC's default interface) or via the commandline. The term ''transcode'' by itself normally refers to converting one media format to another and saving the output to a file (i.e. no streaming involved).

===Transcoding using the GUI===
One of the methods of transcoding is via the GUI. To access this:
#In VLC, go to "Media >> Convert / Save..." (Ctrl+R).
#Add the input file(s) or stream(s) you want to transcode. Press "Convert / Save".
#In the "Convert" windows specify the destination file name (including file extension - e.g. on Windows "C:\out.mp3").
#Select the desired codec from the profile list. To check/edit the settings of a given profile press the "Edit selected profile" button. Profiles can also be added/deleted.
#Press "Start".
If the profile settings were compatible and transcoding was sucessful a playable destination file should be created.

[[File:Basic_interface_convert.png]]

===Using the commandline===
Another method of transcoding is via the commandline. This is more flexible than via the GUI as it enables full usage of the modules and options available in VLC.

To use the VLC's commandline you need to have access to the commandline interface, for example via a shell.
====Windows-based systems====
On Windows-based system Command Prompt can be used. This can be found in the "Accessories" folder of the Start menu. Alternatively by going to "Start >> Run..." or pressing "Windows key + R", entering "cmd" into the text field and press "OK" or Enter.

Once the Command Prompt window is opened navigating to the folder/directory where VLC is located is easiest for using the commandline as only "vlc.exe" or "vlc" (as the .exe part is assumed) needs to entered to run VLC. If VLC is installed in the default location (on a 32-bit system) running:
cd "C:\Program Files\VideoLAN\VLC"
Should change to the directory where vlc.exe is located.

====Unix systems====
On Unix-based system (such as Linux and Mac OS X) a terminal window can be opened. Running "vlc" should be all that is needed to open VLC.

====Transcoding commandline string structure====
A typical commandline string for converting a file to another format is:
vlc --sout "#transcode{[TRANSCODE_OPTIONS]}:std{[OUTPUT_OPTIONS]}" INPUT
Where <tt>INPUT</tt> is the input stream, <tt>[TRANSCODE_OPTIONS]</tt> are the options set for the desired output format, codecs, bitrate etc. and <tt>[OUTPUT_OPTIONS]</tt> are the option set for the output type. <tt>--sout</tt> is the stream output commandline option.

====Example commandline: Converting an audio file to a MP3 file====
An example usage might be converting an audio file to a MP3 file:
vlc --sout "#transcode{acodec=mp3,ab=128,channels=2,samplerate=44100}:std{access=file,mux=raw,dst=OUTPUT}" INPUT
Where INPUT is the input file ans OUTPUT is the destination file (for example "C:\out.mp3" on Windows or "/home/username/out.mp3" on a *nix system).
The above sout string is the default "Audio - MP3" profile setting accessible via the GUI. It will convert an audio input to a 128kbps CBR MP3 file (sample rate 44100Hz, 2 channels).
====Other examples commandline strings====
Convert an audio input to an uncompressed WAVE (*.wav) file:
vlc --sout "#transcode{acodec=s16l,channels=2,samplerate=44100}:std{access=file,mux=wav,dst=OUTPUT}" INPUT
Convert an audio input to an AAC file (MP4 container):
vlc --sout "#transcode{acodec=mp4a,ab=128,channels=2,samplerate=44100}:std{access=file,mux=mp4,dst=OUTPUT}" INPUT

==Streaming==

===Streaming using the GUI===

Basically, to stream using the GUI, open VLC, then Media [menu] -> Streaming -> (select any media to stream, then hit Stream button). At this point it asks you *how* to stream it. The most common way is via HTTP. To stream via HTTP, click on "Destinations", choose HTTP from the drop down as a "New Destination" and click add. Now if you are streaming video, you will want to stream to something like "/go.mpg." Now hit stream, and you should be able to use a different instance of VLC as a client, and listen to that stream now (ex: on the same computer it would be "Media" [menu] -> Open Network Stream -> "http://localhost:8080/go.mpg" and it should work.

A few caveats:
* even though you click on "enable transcoding" and specify some other container type, it will give you the flv container type unless you use a suffix, like ".mpg" [http://forum.videolan.org/viewtopic.php?f=14&t=80722 ref]
* VLC client cannot receive a stream at less than 5 fps, though it can stream it all right for those speeds (and other players can receive it). [http://trac.videolan.org/vlc/ticket/214 ref].
* NB that *many* times when using the GUI to stream it will choose the wrong thing. Like if you give a path of "/" it will use FLV container type (which you probably didn't want, and which overrides your transcoding settings' container type *silently*), and if you give it "/go.mp4" it will *silently* fail (you can look at the log messages to see what the error is--it says "mp4 type is not supported except for files"). It is tricky to get it setup. It's like the GUI sets it up wrong most times. Here is a [[http://forum.videolan.org/viewtopic.php?f=14&t=80722 laundry list]].

First there is an input text called '''Source''', where you'll find your media path and the its type.

[[File:VlcStream.png]]

If you'll click on Destination you'll see the destination of stream that could be: ''File'', ''HTTP'', ''MS-WSMP'', ''RTSP'', ''RTP/MPG'', ''RTP, Audio/Video'', ''UDP'' and ''Icecast''.

[[File:Stream-destination.png]]

You can abilitate '''Transcoding''' to transcode your video to one in the list or in a one you can specify by clicking on the proper icon.

Last you have the option of stream you'll share.

[[File:Stream-option.png]]

By clicking stream it will return to VLC main user interface and the playbar will scroll as the video will play.

===Streaming using the command line interface===

If you want to stream using the command line interface instead of the GUI (more control, for example you can specify your own container), you can "sniff" the options the GUI is using by opening up the logger (Tools menu -> message) and setting verbosity level to "2" then doing a stream. It will output debug messages that basically tell you what it is using for command line parameters, then you will take those same parameters and use them on the command line (you may need to add quotation marks around words that have spaces in them, and you may need to add --'s).

An example is in a unique command line:

C:\Program Files\VideoLAN\VLC>vlc "C:\Users\Public\Videos\Sample Videos\Wildlife.wmv":
sout=#transcode{vcodec=h264,acodec=mp3,ab=128,channels=2,samplerate=44100}:http{dst=:8090/go.mpg}

==See also==
* [[Documentation:Streaming HowTo|Streaming HowTo]] - Outdated HowTo for streaming with VLC
* [[Transcode]] - Further information about transcoding with VLC
* [http://www.videolan.org/doc/vlc-user-guide/en/ch04.html VideoLAN documentation site, chapter 4]

Documentation:Streaming HowTo New

2012-04-26T22:44:15Z

Gth: /* See also */ Moved a link to this more appropriate section, and corrected it

This documentation explains how to stream, transcode and save streams using [[VLC media player]].

'''NOTE: This is work in progress. For a more complete, yet outdated, documentation on Streaming with VLC please see the old [[Documentation:Streaming HowTo|Streaming HowTo]].'''

==Introduction==
VLC media player is able to stream, transcode and save different media streams. For more information about the formats and codecs supported please see the [http://www.videolan.org/streaming-features.html VideoLAN Streaming Features list].

==Transcoding==
[[Transcode|Transcoding]] is the process of taking a media file or stream and converting it to a different format or bitrate. There are two methods for transcoding in VLC, via the GUI (VLC's default interface) or via the commandline. The term ''transcode'' by itself normally refers to converting one media format to another and saving the output to a file (i.e. no streaming involved).

===Transcoding using the GUI===
One of the methods of transcoding is via the GUI. To access this:
#In VLC, go to "Media >> Convert / Save..." (Ctrl+R).
#Add the input file(s) or stream(s) you want to transcode. Press "Convert / Save".
#In the "Convert" windows specify the destination file name (including file extension - e.g. on Windows "C:\out.mp3").
#Select the desired codec from the profile list. To check/edit the settings of a given profile press the "Edit selected profile" button. Profiles can also be added/deleted.
#Press "Start".
If the profile settings were compatible and transcoding was sucessful a playable destination file should be created.

[[File:Basic_interface_convert.png]]

===Using the commandline===
Another method of transcoding is via the commandline. This is more flexible than via the GUI as it enables full usage of the modules and options available in VLC.

To use the VLC's commandline you need to have access to the commandline interface, for example via a shell.
====Windows-based systems====
On Windows-based system Command Prompt can be used. This can be found in the "Accessories" folder of the Start menu. Alternatively by going to "Start >> Run..." or pressing "Windows key + R", entering "cmd" into the text field and press "OK" or Enter.

Once the Command Prompt window is opened navigating to the folder/directory where VLC is located is easiest for using the commandline as only "vlc.exe" or "vlc" (as the .exe part is assumed) needs to entered to run VLC. If VLC is installed in the default location (on a 32-bit system) running:
cd "C:\Program Files\VideoLAN\VLC"
Should change to the directory where vlc.exe is located.

====Unix systems====
On Unix-based system (such as Linux and Mac OS X) a terminal window can be opened. Running "vlc" should be all that is needed to open VLC.

====Transcoding commandline string structure====
A typical commandline string for converting a file to another format is:
vlc --sout "#transcode{[TRANSCODE_OPTIONS]}:std{[OUTPUT_OPTIONS]}" INPUT
Where <tt>INPUT</tt> is the input stream, <tt>[TRANSCODE_OPTIONS]</tt> are the options set for the desired output format, codecs, bitrate etc. and <tt>[OUTPUT_OPTIONS]</tt> are the option set for the output type. <tt>--sout</tt> is the stream output commandline option.

====Example commandline: Converting an audio file to a MP3 file====
An example usage might be converting an audio file to a MP3 file:
vlc --sout "#transcode{acodec=mp3,ab=128,channels=2,samplerate=44100}:std{access=file,mux=raw,dst=OUTPUT}" INPUT
Where INPUT is the input file ans OUTPUT is the destination file (for example "C:\out.mp3" on Windows or "/home/username/out.mp3" on a *nix system).
The above sout string is the default "Audio - MP3" profile setting accessible via the GUI. It will convert an audio input to a 128kbps CBR MP3 file (sample rate 44100Hz, 2 channels).
====Other examples commandline strings====
Convert an audio input to an uncompressed WAVE (*.wav) file:
vlc --sout "#transcode{acodec=s16l,channels=2,samplerate=44100}:std{access=file,mux=wav,dst=OUTPUT}" INPUT
Convert an audio input to an AAC file (MP4 container):
vlc --sout "#transcode{acodec=mp4a,ab=128,channels=2,samplerate=44100}:std{access=file,mux=mp4,dst=OUTPUT}" INPUT

==Streaming==

===Streaming using the GUI===

Basically, to stream using the GUI, open VLC, then Media [menu] -> Streaming -> (select any media to stream, then hit Stream button). At this point it asks you *how* to stream it. The most common way is via HTTP. To stream via HTTP, click on "Destinations", choose HTTP from the drop down as a "New Destination" and click add. Now if you are streaming video, you will want to stream to something like "/go.mpg." Now hit stream, and you should be able to use a different instance of VLC as a client, and listen to that stream now (ex: on the same computer it would be "Media" [menu] -> Open Network Stream -> "http://localhost:8080/go.mpg" and it should work.

A few caveats:
* even though you click on "enable transcoding" and specify some other container type, it will give you the flv container type unless you use a suffix, like ".mpg" [http://forum.videolan.org/viewtopic.php?f=14&t=80722 ref]
* VLC client cannot receive a stream at less than 5 fps, though it can stream it all right for those speeds (and other players can receive it). [http://trac.videolan.org/vlc/ticket/214 ref].
* NB that *many* times when using the GUI to stream it will choose the wrong thing. Like if you give a path of "/" it will use FLV container type (which you probably didn't want, and which overrides your transcoding settings' container type *silently*), and if you give it "/go.mp4" it will *silently* fail (you can look at the log messages to see what the error is--it says "mp4 type is not supported except for files"). It is tricky to get it setup. It's like the GUI sets it up wrong most times. Here is a [[http://forum.videolan.org/viewtopic.php?f=14&t=80722 laundry list]].

First there is an input text called '''Source''', where you'll find your media path and the its type.

[[File:VlcStream.png]]

If you'll click on Destination you'll see the destination of stream that could be: ''File'', ''HTTP'', ''MS-WSMP'', ''RTSP'', ''RTP/MPG'', ''RTP, Audio/Video'', ''UDP'' and ''Icecast''.

[[File:Stream-destination.png]]

You can abilitate '''Transcoding''' to transcode your video to one in the list or in a one you can specify by clicking on the proper icon.

Last you have the option of stream you'll share.

[[File:Stream-option.png]]

By clicking stream it will return to VLC main user interface and the playbar will scroll as the video will play.

===Streaming using the command line interface===

If you want to stream using the command line interface instead of the GUI (more control, for example you can specify your own container), you can "sniff" the options the GUI is using by opening up the logger (Tools menu -> message) and setting verbosity level to "2" then doing a stream. It will output debug messages that basically tell you what it is using for command line parameters, then you will take those same parameters and use them on the command line (you may need to add quotation marks around words that have spaces in them, and you may need to add --'s).

An example is in a unique command line:

C:\Program Files\VideoLAN\VLC>vlc "C:\Users\Public\Videos\Sample Videos\Wildlife.wmv":
sout=#transcode{vcodec=h264,acodec=mp3,ab=128,channels=2,samplerate=44100}:http{dst=:8090/go.mpg}

=== More Links ===
The [http://www.videolan.org/doc/videolan-howto/en/ch04.html Documentation chapter 4].

==See also==
* [[Documentation:Streaming HowTo|Streaming HowTo]] - Outdated HowTo for streaming with VLC
* [[Transcode]] - Further information about transcoding with VLC
* [http://www.videolan.org/doc/vlc-user-guide/en/ch04.html VideoLAN documentation site, chapter 4]

Talk:VideoLAN Design

2012-04-25T05:59:49Z

Gth: Question about wiki vs. the videolan doc website area

==Wiki vs. Doc pages==
I've been messing with the http interface and noticed quite a variation in the information available from the videolan/doc/ area compared to wiki.videolan.org. Is there a migration progress likely? This discussion page seems as good as any to find out about the plans for the wiki, although I'm not sure why the talk page was previously deleted. Anyway, the wiki seems much more comprehensive and up to date - some of the http interface info in the wiki is scattered across several articles, but that's easily fixable. Look forward to updating it, if that's going to be useful. --[[User:Gth|Gth]] 07:59, 25 April 2012 (CEST)

Documentation Talk:Building Pages for the HTTP Interface

2012-04-23T16:26:45Z

Gth: Suggestion for some examples.

==Undocumented RPN operators==
[[User:Teyut|Teyut]] 19:38, 15 April 2007 (CEST): I've added informations about some RPN operators using the source code in ''rpn.c''. However, I didn't test them all, and especially, I'm not sure how '''vlc_get_meta''' and '''snapshot''' works, and I have no clue what '''vlm_command''' and '''services_discovery_*''' commands are made for. So if someone can confirm what I've written, and give a better example for '''vlm_command''', it would be better I think.
:Thanks for the help! The descriptions look ok. (except the VLM example which is kind of not using a VLM command, but I'll fix it) [[User:Dionoea|Dionoea]] 21:59, 15 April 2007 (CEST)

==Updated RPN: examples?==
I fixed some wiki formatting on the RPN section, but it really needs an example or two to explain how RPN works, say an example of seeking forward 20 seconds? --[[User:Gth|Gth]] 18:26, 23 April 2012 (CEST)

Help talk:Editing

2012-04-23T16:16:49Z

Gth: Question about external links.

==Link to Wikimedia, not Wikipedia==
Shouldn't the Editing Help at the foot of an 'Editing' Page, ie. the content of this page, link to a Wikimedia page, and not to a Wikipedia page? [[User:Stq|Stq]]

:Agreed; it's a much better editing help reference, too. The wikipedia one has various style guides for encyclopedic referencing, etc. I've updated the link. --[[User:Gth|Gth]] 18:16, 23 April 2012 (CEST)

==External Link icon==
Anyone else see the videolan witch-hat obscuring the last few letters of any external link in their browser? --[[User:Gth|Gth]] 18:16, 23 April 2012 (CEST)

Documentation:Building Pages for the HTTP Interface

2012-04-23T15:59:01Z

Gth: /* RPN Introduction */ Minor reformatting of table.

{{RightMenu|documentation play howto toc}}

==Introduction==

This appendix describes the language used for writing dynamic web pages for the HTTP interface.

Pages must be placed in the share/http folder in either VLC's folder (Windows, Mac) or /usr/share/vlc/share/http or /usr/local/share/vlc/share/http (or wherever vlc's shared files are installed).

Some files are handled a bit specially:
*Files beginning with '.' are not exported.
*A '.access' file will be opened and the http interface will expect to find at the first line a login/password (written as login:password). This login/password will be used to protect all files in this directory. Be careful that only files in this directory will be protected. (sub-directories won't be protected.)
* A '.hosts' file will be opened and the http interface will expect to find a list of network/mask pairs separated by new line, for instance 192.168.0.0/255.255.255.0. If this file is present, then the default behaviour is to deny access from hosts which don't match any of the network/mask pairs to all the files of the directory. If the file is not present, then any host has access to the files of the directory. Be careful that only files in this directory will be protected. (sub-directories won't be protected.)
*The file <dir>/index.html will be exported as <dir> and <dir>/ and not as index.html.

The MIME type is set by looking at the file extension and cannot be specified nor modified for a specific file. Unknown extensions will have "application/octet-stream" as MIME type.

You should avoid exporting big files. Each file is indeed first loaded into the memory before being sent to the client, so please be careful.

==VLC macros==

Each time a .html/.htm page is requested, it is parsed by VLC before being sent. The parser searches for the VLC macros, and executes or substitutes them. Moreover, URL arguments received by the GET method can be interpreted.

A VLC macro looks like:
<vlc id="macro-name" param1="macro-parameters1" param2="macro-parameters2" />
"id" is the only mandatory field, param1 and param2 may or may not be present and depend on the value of "id".

You should take care that you '''have to''' respect this syntax, VLC won't like invalid syntax. (It could easily leads to crashes).

Examples:

Correct:
<vlc id="value" param1="version" />
Incorrect:
<vlc id="value" param1="version" > (missing tag ending)
<vlc id=value param1="version" /> (missing "" )

Valid macros are:
*'''control''' (1 optional parameter)
*'''include''' (1 parameter)
*'''get''' (2 parameters)
*'''set''' (2 parameters)
*'''rpn''' (1 parameter)
*'''if''' (1 optional parameter)
*'''else''' (no parameter)
*'''end''' (no parameter)
*'''value''' (1 optional parameter)
*'''foreach''' (2 parameters)

For powerful macros, you may use these tools:

*RPN Evaluator (see part 2)
*Stacks: The stack is a place where you can push numbers and strings, and then pop them backs. It's used with the little RPN evaluator.
*Local variables: You can dynamically create new variables and changes their values. Some local variables are predefined:
**'''url_value''': parameter of the URL
**'''url_param''': 1 if url_value isn't empty else 0
**'''version''': the VLC version
**'''copyright''': the VLC copyright
**'''vlc_compile_time, vlc_compile_by, vlc_compile_host, vlc_compile_domain, vlc_compiler, vlc_changeset''': information on the VLC build
**'''stream_position, stream_time, stream_length, stream_state''': information on the currently playing stream
**'''volume''': current volume setting

Remark: The stacks, and local variables context is reset before the page is executed.

==The RPN evaluator==

RPN means Reverse Polish Notation.

===RPN Introduction===

RPN may look strange but it's a fast and easy way to write expressions. It also avoids the use of ( and ).

Instead of writing ( 1 + 2 ) * 5 you just use 1 2 + 5 *.

The idea behind it is: if we have a number or a string (using <nowiki>''</nowiki>), push it on the stack. If it is an operator (like +), pop the arguments from the stack, execute the operators and then push the result onto the stack. The result of the RPN sequence is the value on the top of the stack. A step by step explanation of the sequence '''1 2 + 5 *''' is shown below, to illustrate this process:

{| border="1" cellpadding="2" cellspacing="0"
! Stack Contents
! Word
! Action taken on the stack
|-
| empty
| 1
| 1 is pushed on the stack
|-
| 1
| 2
| 2 is pushed onto the stack, 'above' 1
|-
| 1 <nowiki>|</nowiki> 2
| +
| The plus operator results in removal of 1 and 2 from the stack, then write 3 onto the stack
|-
| 3
| 5
| 5 is pushed on the stack
|-
| 3 <nowiki>|</nowiki> 5
| *
| The multiplication operator removes 3 and 5 and writes 15 onto the stack.
|-
| 15
|
| Final result.
|}

===Operators===

Notation: ST(1) means the first stack element, ST(2) the second one ... and op is the operator.

You have access to :

*Standard arithmetics operators: '''+, -, *, /, %''' these ones push the result of ST(1) op ST(2) onto the stack

*Binary operators: '''!''' (push !ST(1)); '''^, &, |''': push the result ST(1) op ST(2)

*test: '''=, <, <=, >, >=''': execute ST(1) op ST(2) and push -1 if true else 0

*string functions:
**'''strcat''': pushes the result of 'ST(1)ST(2)
**'''strcmp''': compares ST(1) and ST(2) (0 if equal)
**'''strncmp''': compares the first ST(1) characters of ST(2) and ST(3) (0 if equal)
**'''strsub''': extracts characters ST(2) to ST(1) of string ST(3)
**'''strlen''': pushes the length of ST(1)
**'''str_replace''': replaces string ST(2) with ST(1) in ST(3)
**'''url_encode''': encodes non-alphanumeric characters of ST(1) as %XX so that they can be safely passed as GET or POST variables
**'''url_extract''': performs the reverse operation of url_encode
**'''addslashes''': protects single quotes (') and double quotes (") of ST(1) with backslashes (\) so that they can be safely passed to a VLC playlist function
**'''stripslashes''': performs the reverse operation of addslashes
**'''htmlspecialchars''': encodes &, ', ", <, and > of ST(1) as their &stuff; HTML counterpart, so that they don't interact with HTML tags
**'''realpath''': parses ST(1) as a filename path, and pushes an absolute path to that file, removing ~ and ../

*stack manipulation:
**'''dup''': pops ST(1) and pushes the same string twice
**'''drop''': pops ST(1) and drops it
**'''swap''': exchanges ST(1) and ST(2)
**'''flush''': empties the stack

*variables manipulation:
**'''store''': stores ST(2) in a local variable named ST(1)
**'''value''': pushes the value of the local variable named ST(1)

*player control:
**'''vlc_play''': plays the playlist item whose ID is ST(1), and pushes the return value of the play function (0 in case of success); see playlist functions below
**'''vlc_stop''': stops the playlist
**'''vlc_pause''': pauses the playlist
**'''vlc_next''': plays the next playlist item
**'''vlc_previous''': plays the previous playlist item
**'''vlc_seek''': seeks the current input to a location defined in ST(1), for instance+3m (minutes), -20s, 45%, 1:12, 1h12m25s
**'''vlc_var_type''': pushes the type of the variable ST(2) of object ST(1); the type is one of these strings '''VLC_VAR_BOOL, VLC_VAR_INTEGER, VLC_VAR_HOTKEY, VLC_VAR_STRING, VLC_VAR_MODULE, VLC_VAR_FILE, VLC_VAR_DIRECTORY, VLC_VAR_VARIABLE, VLC_VAR_FLOAT, UNDEFINED''' (no such variable) or '''INVALID''' (no input stream); the object is one of '''VLC_OBJECT_ROOT, VLC_OBJECT_VLC, VLC_OBJECT_INTF, VLC_OBJECT_PLAYLIST, VLC_OBJECT_INPUT, VLC_OBJECT_VOUT, VLC_OBJECT_AOUT''' or '''VLC_OBJECT_SOUT'''
**'''vlc_var_set''': sets variable ST(2) of object ST(1) to ST(3)
**'''vlc_var_get''': pushes the value of the variable ST(2) of object ST(1)
**'''vlc_object_exists''': checks if object ST(1) exists
**'''vlc_config_type''': pushes the type of the configuration variable ST(1); see '''vlc_var_type''' for a list of types
**'''vlc_config_set''': sets configuration variable ST(1) to ST(2)
**'''vlc_config_get''': pushes the value of the configuration variable ST(1)
**'''vlc_config_save''': saves the modification made to the configuration variables of module ST(1) to the configuration file (ST(1) may be empty, in which case the whole configuration is saved) and pushes the return status (0 in case of success)
**'''vlc_config_reset''': resets the configuration file to the default value (use with caution)
**'''vlc_volume_set''': sets the volume value to ST(1) which can be a raw value between 0 and 1024, or a relative one between 0% and 400%, where 1% is equal to the maximum volume value divided by 400 (thus, the maximum volume value is equal to 400%, that is 1024). If ST(1) begins with a '+' (or '-') operator, the volume is increased (or decreased) by the raw value which follows this operator
**'''vlc_get_meta''': pushes the value of the meta information named by ST(1) from the stream being played. Available meta names are: "Title" (or "TITLE"), "Author", "Artist" (or "ARTIST"), "Genre" (or "GENRE"), "Copyright", "Album/movie/show title" (or "ALBUM"), "Track number/position in set", "Description", "Rating", "Date", "Setting", "URL", "Language", "Now Playing", "Publisher"
**'''vlm_command''' or '''vlm_cmd''': sends the command that is on the stack to the VLM (VideoLan Manager). Since the command can contain more than one component on the stack, it must be ended by an ';' or an empty string pushed on the stack (e.g.: param1="';' 'command' 'my' 'this is' vlm_command"). Once the VLM has executed the command, the return value is assigned to the local variable '''vlm_value''' and the error string (if available) is assigned to '''vlm_error'''
**'''snapshot''': takes a snapshot

*playlist functions:
**'''playlist_add''': adds MRL ST(1) to the playlist, with name ST(2) and returns the playlist ID associated to this item; special characters must be escaped with addslashes first; it is very convenient to call 'toto.mpg' playlist_add vlc_play
**'''playlist_empty''': clears the playlist of all items
**'''playlist_move''': moves playlist item at position ST(2) to position ST(1)
**'''playlist_delete''': deletes playlist item ID ST(1)
**'''playlist_sort''': sorts the playlist using the mode ST(2) and order ST(1). Available order values are 0 (normal order) and 1 (reverse order). Available mode values are 0 (sort by ID), 1 (sort by title), 2 (sort by title, nodes first), 3 (sort by author), 4 (sort by genre), 5 (sort randomly), 6 (sort by duration), 7 (numerically sort by title) and 8 (sort by album)
**'''services_discovery_add''': adds the service discovery ST(1) to the playlist
**'''services_discovery_remove''': removes the service discovery ST(1) from the playlist
**'''services_discovery_is_loaded''': checks if the service discovery ST(1) is loaded in the playlist, and pushes the answer on the stack

==The macros==

===The ''control'' macro===

'''The use of the control macro is now deprecated in favour of the RPN functions above. The documentation is provided here for the maintainance of HTML pages still using this old API. The main problem with this API is that there is no way to retrieve the playlist ID of the last added item.'''

When asking for a page, you can give arguments to it through the url. (e.g. using a <form>). Ex: http://host:port/page.html?var=value&var2=value2&... The "control" macro tells a page to parse these arguments and to execute the ones that are allowed. param1 of this macro says which commands are allowed. If empty, all commands will be permitted.

Some commands require an argument that must be passed in the URL too.
*URL commands
**Name, Argument, Description
**'''play''', item (integer), Play the specified playlist item
**'''stop''', ,Stop
**'''pause''', Pause
**'''next''', , Go to next playlist item
**'''previous''', , Go to previous playlist item
**'''add''', mrl (string), Add a [[MRL]] to the playlist
**'''delete''', item (integer), Delete the specified playlist item or list of playlist items
**'''empty''', , Empty the playlist
**'''close''', id (hexa), Close a specific connection
**'''shutdown''', , Quit VLC

For example, you can restrict execution of the '''shutdown''' command to protected page (through a ''.access'' file), using the control macro in all unprotected pages.

===The ''include'' macro===

This macro is replaced by the contents of the file param1. If the file contains vlc macros, they are correctly parsed and replaced.

===The ''get'' macro===

This macro will be replaced by the value of the configuration variable which name is stored in param1 and which type is given by param2.

param1 must be the name of an existing configuration variable. param2 must be the right type of the variable. It can be one of ''int'', ''float'', or ''string''.

Example:
<vlc id="get" param1="sout" param2="string" /> will be replaced in the output page by the value of sout.

===The ''set'' macro===

This macro allows to set the value of a configuration variable. The name is given by param1 and the type by param2 (like for get). The value is retrieved from the url using the name given in param1.

For example, if player.html contains
<vlc id="set" param1="sout" param2="string" />
and if you browse at <emphasis> http://host:ip/player.html?sout=sout_value</emphasis>, the sout variable will be set to "sout_value". If the URL doesn't contain sout, nothing will be done.

===The ''rpn'' macro===

This macro allows you to interpret RPN commands. (See II).

===The ''if,else,end'' macro===

This macro allows you to control the parsing of the HTML page.

If param1 isn't empty, it is first executed with the RPN evaluator. If the first element from the stack is not 0, the test value is true, else false..

<vlc id="if" param1="1 2 =" />

<vlc id="else" />
<p> Test succeed: 1 isn't equal to 2 </p>
<vlc id="end" />

You can also just use "if" and "end".

===The ''value'' macro===

If param1 isn't empty, it is first executed with the RPN evaluator. The macro is replaced with the value of the first element of the stack.

Note: If the element is the name of a local variable, its value will be displayed instead of its name.

===The ''foreach,end'' macro===

param1 is the name of the variable that will be used for the loop. param2 is the name of the set to be built:
*integer: take the first element from the stack to construct a set of integer. The stack element should be a string like: ''first:last[:step][,first2:last2[:step2][,...]'' (Ex:1:5:2,6:8:1 will be expanded into 1,3,5,6,7,8)
*directory: take the first element of the stack as the base directory and construct a set of filename and directly in it. Each element has the following fields:
**basename: file/directory name
**name: complete file/directory name (including path)
**ext: file extension in lowercase
**type: "directory" or "file" or "unknown"
**size: size of the file
**date
*playlist: set based on the playlist with fields: current is 1 if item is currently selected, 0 else. index is the index value, that can be used by the play or delete control command. name is the
name of the item.
*"information": Create information for the current playing stream. name is the name of the category, value is its value, info is a new set that can be parsed with a new foreach (subfields of info are name and value).
*input variables such as "program", "title", "chapter", "audio-es", "video-es" and "spu-es": Create lists for the current playing stream. Every list has the following fields:
**name: item name (language for elementary streams, tracks, etc.) to display in places where a human-readable format is preferred
**id: item ID to pass to the RPN function vlc_var_set, and returned by vlc_var_get
**selected: 1 if the item is selected, 0 otherwise
*the name of a foreach variable if it's a set of set of value.

<vlc id="foreach" param1="cat" param2="informations" />
<vlc id="value" param1="cat.name" />
<ul>
<vlc id="foreach" param1="info" param2="cat.info" />
<li>
<vlc id="value" param1="info.name" /> :
<vlc id="value" param1="info.value" />
</li>
<vlc id="end" />
</ul>
<vlc id="end" />

For more details, have a look at the share/http directory of the VLC source tree...

{{Documentation}}

Documentation:Building Pages for the HTTP Interface

2012-04-23T15:57:03Z

Gth: /* Introduction */

{{RightMenu|documentation play howto toc}}

==Introduction==

This appendix describes the language used for writing dynamic web pages for the HTTP interface.

Pages must be placed in the share/http folder in either VLC's folder (Windows, Mac) or /usr/share/vlc/share/http or /usr/local/share/vlc/share/http (or wherever vlc's shared files are installed).

Some files are handled a bit specially:
*Files beginning with '.' are not exported.
*A '.access' file will be opened and the http interface will expect to find at the first line a login/password (written as login:password). This login/password will be used to protect all files in this directory. Be careful that only files in this directory will be protected. (sub-directories won't be protected.)
* A '.hosts' file will be opened and the http interface will expect to find a list of network/mask pairs separated by new line, for instance 192.168.0.0/255.255.255.0. If this file is present, then the default behaviour is to deny access from hosts which don't match any of the network/mask pairs to all the files of the directory. If the file is not present, then any host has access to the files of the directory. Be careful that only files in this directory will be protected. (sub-directories won't be protected.)
*The file <dir>/index.html will be exported as <dir> and <dir>/ and not as index.html.

The MIME type is set by looking at the file extension and cannot be specified nor modified for a specific file. Unknown extensions will have "application/octet-stream" as MIME type.

You should avoid exporting big files. Each file is indeed first loaded into the memory before being sent to the client, so please be careful.

==VLC macros==

Each time a .html/.htm page is requested, it is parsed by VLC before being sent. The parser searches for the VLC macros, and executes or substitutes them. Moreover, URL arguments received by the GET method can be interpreted.

A VLC macro looks like:
<vlc id="macro-name" param1="macro-parameters1" param2="macro-parameters2" />
"id" is the only mandatory field, param1 and param2 may or may not be present and depend on the value of "id".

You should take care that you '''have to''' respect this syntax, VLC won't like invalid syntax. (It could easily leads to crashes).

Examples:

Correct:
<vlc id="value" param1="version" />
Incorrect:
<vlc id="value" param1="version" > (missing tag ending)
<vlc id=value param1="version" /> (missing "" )

Valid macros are:
*'''control''' (1 optional parameter)
*'''include''' (1 parameter)
*'''get''' (2 parameters)
*'''set''' (2 parameters)
*'''rpn''' (1 parameter)
*'''if''' (1 optional parameter)
*'''else''' (no parameter)
*'''end''' (no parameter)
*'''value''' (1 optional parameter)
*'''foreach''' (2 parameters)

For powerful macros, you may use these tools:

*RPN Evaluator (see part 2)
*Stacks: The stack is a place where you can push numbers and strings, and then pop them backs. It's used with the little RPN evaluator.
*Local variables: You can dynamically create new variables and changes their values. Some local variables are predefined:
**'''url_value''': parameter of the URL
**'''url_param''': 1 if url_value isn't empty else 0
**'''version''': the VLC version
**'''copyright''': the VLC copyright
**'''vlc_compile_time, vlc_compile_by, vlc_compile_host, vlc_compile_domain, vlc_compiler, vlc_changeset''': information on the VLC build
**'''stream_position, stream_time, stream_length, stream_state''': information on the currently playing stream
**'''volume''': current volume setting

Remark: The stacks, and local variables context is reset before the page is executed.

==The RPN evaluator==

RPN means Reverse Polish Notation.

===RPN Introduction===

RPN may look strange but it's a fast and easy way to write expressions. It also avoids the use of ( and ).

Instead of writing ( 1 + 2 ) * 5 you just use 1 2 + 5 *.

The idea behind it is: if we have a number or a string (using <nowiki>''</nowiki>), push it on the stack. If it is an operator (like +), pop the arguments from the stack, execute the operators and then push the result onto the stack. The result of the RPN sequence is the value on the top of the stack. A step by step explanation of the sequence '''1 2 + 5 *''' is shown below, to illustrate this process:

{| border="1" cellpadding="2" cellspacing="0"
! Stack Contents
! Word
! Action taken on the stack
|-
| empty
| 1
| 1 is pushed on the stack
|-
| 1
| 2
| 2 is pushed onto the stack, 'above' 1
|-
| 1 | 2
| +
| The plus operator results in removal of 1 and 2 from the stack, then write 3 onto the stack
|-
| 3
| 5
| 5 is pushed on the stack
|-
| 3 | 5
| *
| The multiplication operator removes 3 and 5 and writes 15 onto the stack.
|-
| 15
|
| Final result.
|}

===Operators===

Notation: ST(1) means the first stack element, ST(2) the second one ... and op is the operator.

You have access to :

*Standard arithmetics operators: '''+, -, *, /, %''' these ones push the result of ST(1) op ST(2) onto the stack

*Binary operators: '''!''' (push !ST(1)); '''^, &, |''': push the result ST(1) op ST(2)

*test: '''=, <, <=, >, >=''': execute ST(1) op ST(2) and push -1 if true else 0

*string functions:
**'''strcat''': pushes the result of 'ST(1)ST(2)
**'''strcmp''': compares ST(1) and ST(2) (0 if equal)
**'''strncmp''': compares the first ST(1) characters of ST(2) and ST(3) (0 if equal)
**'''strsub''': extracts characters ST(2) to ST(1) of string ST(3)
**'''strlen''': pushes the length of ST(1)
**'''str_replace''': replaces string ST(2) with ST(1) in ST(3)
**'''url_encode''': encodes non-alphanumeric characters of ST(1) as %XX so that they can be safely passed as GET or POST variables
**'''url_extract''': performs the reverse operation of url_encode
**'''addslashes''': protects single quotes (') and double quotes (") of ST(1) with backslashes (\) so that they can be safely passed to a VLC playlist function
**'''stripslashes''': performs the reverse operation of addslashes
**'''htmlspecialchars''': encodes &, ', ", <, and > of ST(1) as their &stuff; HTML counterpart, so that they don't interact with HTML tags
**'''realpath''': parses ST(1) as a filename path, and pushes an absolute path to that file, removing ~ and ../

*stack manipulation:
**'''dup''': pops ST(1) and pushes the same string twice
**'''drop''': pops ST(1) and drops it
**'''swap''': exchanges ST(1) and ST(2)
**'''flush''': empties the stack

*variables manipulation:
**'''store''': stores ST(2) in a local variable named ST(1)
**'''value''': pushes the value of the local variable named ST(1)

*player control:
**'''vlc_play''': plays the playlist item whose ID is ST(1), and pushes the return value of the play function (0 in case of success); see playlist functions below
**'''vlc_stop''': stops the playlist
**'''vlc_pause''': pauses the playlist
**'''vlc_next''': plays the next playlist item
**'''vlc_previous''': plays the previous playlist item
**'''vlc_seek''': seeks the current input to a location defined in ST(1), for instance+3m (minutes), -20s, 45%, 1:12, 1h12m25s
**'''vlc_var_type''': pushes the type of the variable ST(2) of object ST(1); the type is one of these strings '''VLC_VAR_BOOL, VLC_VAR_INTEGER, VLC_VAR_HOTKEY, VLC_VAR_STRING, VLC_VAR_MODULE, VLC_VAR_FILE, VLC_VAR_DIRECTORY, VLC_VAR_VARIABLE, VLC_VAR_FLOAT, UNDEFINED''' (no such variable) or '''INVALID''' (no input stream); the object is one of '''VLC_OBJECT_ROOT, VLC_OBJECT_VLC, VLC_OBJECT_INTF, VLC_OBJECT_PLAYLIST, VLC_OBJECT_INPUT, VLC_OBJECT_VOUT, VLC_OBJECT_AOUT''' or '''VLC_OBJECT_SOUT'''
**'''vlc_var_set''': sets variable ST(2) of object ST(1) to ST(3)
**'''vlc_var_get''': pushes the value of the variable ST(2) of object ST(1)
**'''vlc_object_exists''': checks if object ST(1) exists
**'''vlc_config_type''': pushes the type of the configuration variable ST(1); see '''vlc_var_type''' for a list of types
**'''vlc_config_set''': sets configuration variable ST(1) to ST(2)
**'''vlc_config_get''': pushes the value of the configuration variable ST(1)
**'''vlc_config_save''': saves the modification made to the configuration variables of module ST(1) to the configuration file (ST(1) may be empty, in which case the whole configuration is saved) and pushes the return status (0 in case of success)
**'''vlc_config_reset''': resets the configuration file to the default value (use with caution)
**'''vlc_volume_set''': sets the volume value to ST(1) which can be a raw value between 0 and 1024, or a relative one between 0% and 400%, where 1% is equal to the maximum volume value divided by 400 (thus, the maximum volume value is equal to 400%, that is 1024). If ST(1) begins with a '+' (or '-') operator, the volume is increased (or decreased) by the raw value which follows this operator
**'''vlc_get_meta''': pushes the value of the meta information named by ST(1) from the stream being played. Available meta names are: "Title" (or "TITLE"), "Author", "Artist" (or "ARTIST"), "Genre" (or "GENRE"), "Copyright", "Album/movie/show title" (or "ALBUM"), "Track number/position in set", "Description", "Rating", "Date", "Setting", "URL", "Language", "Now Playing", "Publisher"
**'''vlm_command''' or '''vlm_cmd''': sends the command that is on the stack to the VLM (VideoLan Manager). Since the command can contain more than one component on the stack, it must be ended by an ';' or an empty string pushed on the stack (e.g.: param1="';' 'command' 'my' 'this is' vlm_command"). Once the VLM has executed the command, the return value is assigned to the local variable '''vlm_value''' and the error string (if available) is assigned to '''vlm_error'''
**'''snapshot''': takes a snapshot

*playlist functions:
**'''playlist_add''': adds MRL ST(1) to the playlist, with name ST(2) and returns the playlist ID associated to this item; special characters must be escaped with addslashes first; it is very convenient to call 'toto.mpg' playlist_add vlc_play
**'''playlist_empty''': clears the playlist of all items
**'''playlist_move''': moves playlist item at position ST(2) to position ST(1)
**'''playlist_delete''': deletes playlist item ID ST(1)
**'''playlist_sort''': sorts the playlist using the mode ST(2) and order ST(1). Available order values are 0 (normal order) and 1 (reverse order). Available mode values are 0 (sort by ID), 1 (sort by title), 2 (sort by title, nodes first), 3 (sort by author), 4 (sort by genre), 5 (sort randomly), 6 (sort by duration), 7 (numerically sort by title) and 8 (sort by album)
**'''services_discovery_add''': adds the service discovery ST(1) to the playlist
**'''services_discovery_remove''': removes the service discovery ST(1) from the playlist
**'''services_discovery_is_loaded''': checks if the service discovery ST(1) is loaded in the playlist, and pushes the answer on the stack

==The macros==

===The ''control'' macro===

'''The use of the control macro is now deprecated in favour of the RPN functions above. The documentation is provided here for the maintainance of HTML pages still using this old API. The main problem with this API is that there is no way to retrieve the playlist ID of the last added item.'''

When asking for a page, you can give arguments to it through the url. (e.g. using a <form>). Ex: http://host:port/page.html?var=value&var2=value2&... The "control" macro tells a page to parse these arguments and to execute the ones that are allowed. param1 of this macro says which commands are allowed. If empty, all commands will be permitted.

Some commands require an argument that must be passed in the URL too.
*URL commands
**Name, Argument, Description
**'''play''', item (integer), Play the specified playlist item
**'''stop''', ,Stop
**'''pause''', Pause
**'''next''', , Go to next playlist item
**'''previous''', , Go to previous playlist item
**'''add''', mrl (string), Add a [[MRL]] to the playlist
**'''delete''', item (integer), Delete the specified playlist item or list of playlist items
**'''empty''', , Empty the playlist
**'''close''', id (hexa), Close a specific connection
**'''shutdown''', , Quit VLC

For example, you can restrict execution of the '''shutdown''' command to protected page (through a ''.access'' file), using the control macro in all unprotected pages.

===The ''include'' macro===

This macro is replaced by the contents of the file param1. If the file contains vlc macros, they are correctly parsed and replaced.

===The ''get'' macro===

This macro will be replaced by the value of the configuration variable which name is stored in param1 and which type is given by param2.

param1 must be the name of an existing configuration variable. param2 must be the right type of the variable. It can be one of ''int'', ''float'', or ''string''.

Example:
<vlc id="get" param1="sout" param2="string" /> will be replaced in the output page by the value of sout.

===The ''set'' macro===

This macro allows to set the value of a configuration variable. The name is given by param1 and the type by param2 (like for get). The value is retrieved from the url using the name given in param1.

For example, if player.html contains
<vlc id="set" param1="sout" param2="string" />
and if you browse at <emphasis> http://host:ip/player.html?sout=sout_value</emphasis>, the sout variable will be set to "sout_value". If the URL doesn't contain sout, nothing will be done.

===The ''rpn'' macro===

This macro allows you to interpret RPN commands. (See II).

===The ''if,else,end'' macro===

This macro allows you to control the parsing of the HTML page.

If param1 isn't empty, it is first executed with the RPN evaluator. If the first element from the stack is not 0, the test value is true, else false..

<vlc id="if" param1="1 2 =" />

<vlc id="else" />
<p> Test succeed: 1 isn't equal to 2 </p>
<vlc id="end" />

You can also just use "if" and "end".

===The ''value'' macro===

If param1 isn't empty, it is first executed with the RPN evaluator. The macro is replaced with the value of the first element of the stack.

Note: If the element is the name of a local variable, its value will be displayed instead of its name.

===The ''foreach,end'' macro===

param1 is the name of the variable that will be used for the loop. param2 is the name of the set to be built:
*integer: take the first element from the stack to construct a set of integer. The stack element should be a string like: ''first:last[:step][,first2:last2[:step2][,...]'' (Ex:1:5:2,6:8:1 will be expanded into 1,3,5,6,7,8)
*directory: take the first element of the stack as the base directory and construct a set of filename and directly in it. Each element has the following fields:
**basename: file/directory name
**name: complete file/directory name (including path)
**ext: file extension in lowercase
**type: "directory" or "file" or "unknown"
**size: size of the file
**date
*playlist: set based on the playlist with fields: current is 1 if item is currently selected, 0 else. index is the index value, that can be used by the play or delete control command. name is the
name of the item.
*"information": Create information for the current playing stream. name is the name of the category, value is its value, info is a new set that can be parsed with a new foreach (subfields of info are name and value).
*input variables such as "program", "title", "chapter", "audio-es", "video-es" and "spu-es": Create lists for the current playing stream. Every list has the following fields:
**name: item name (language for elementary streams, tracks, etc.) to display in places where a human-readable format is preferred
**id: item ID to pass to the RPN function vlc_var_set, and returned by vlc_var_get
**selected: 1 if the item is selected, 0 otherwise
*the name of a foreach variable if it's a set of set of value.

<vlc id="foreach" param1="cat" param2="informations" />
<vlc id="value" param1="cat.name" />
<ul>
<vlc id="foreach" param1="info" param2="cat.info" />
<li>
<vlc id="value" param1="info.name" /> :
<vlc id="value" param1="info.value" />
</li>
<vlc id="end" />
</ul>
<vlc id="end" />

For more details, have a look at the share/http directory of the VLC source tree...

{{Documentation}}

Documentation:Building Pages for the HTTP Interface

2012-04-23T15:55:18Z

Gth: /* Introduction */

{{RightMenu|documentation play howto toc}}

==Introduction==

This appendix describes the language used for writing dynamic web pages for the HTTP interface.

Pages must be placed in the share/http folder in either VLC's folder (Windows, Mac) or /usr/share/vlc/share/http or /usr/local/share/vlc/share/http (or wherever vlc's shared files are installed).

Some files are handled a bit specially:
*Files beginning with '.' are not exported.
*A '.access' file will be opened and the http interface will expect to find at the first line a login/password (written as login:password). This login/password will be used to protect all files in this directory. Be careful that only files in this directory will be protected. (sub-directories won't be protected.)
* A '.hosts' file will be opened and the http interface will expect to find a list of network/mask pairs separated by new line, for instance 192.168.0.0/255.255.255.0. If this file is present, then the default behaviour is to deny access from hosts which don't match any of the network/mask pairs to all the files of the directory. If the file is not present, then any host has access to the files of the directory. Be careful that only files in this directory will be protected. (sub-directories won't be protected.)
*The file <dir>/index.html will be exported as <dir> and <dir>/ and not as index.html.

The MIME type is set by looking at the file extension and cannot be specified nor modified for a specific file. Unknown extensions will have "application/octet-stream" as MIME type.

You should avoid exporting big files. Each file is indeed first loaded into the memory before being sent to the client, so please be careful.

==VLC macros==

Each time a .html/.htm page is requested, it is parsed by VLC before being sent. The parser searches for the VLC macros, and executes or substitutes them. Moreover, URL arguments received by the GET method can be interpreted.

A VLC macro looks like:
<vlc id="macro-name" param1="macro-parameters1" param2="macro-parameters2" />
"id" is the only mandatory field, param1 and param2 may or may not be present and depend on the value of "id".

You should take care that you '''have to''' respect this syntax, VLC won't like invalid syntax. (It could easily leads to crashes).

Examples:

Correct:
<vlc id="value" param1="version" />
Incorrect:
<vlc id="value" param1="version" > (missing tag ending)
<vlc id=value param1="version" /> (missing "" )

Valid macros are:
*'''control''' (1 optional parameter)
*'''include''' (1 parameter)
*'''get''' (2 parameters)
*'''set''' (2 parameters)
*'''rpn''' (1 parameter)
*'''if''' (1 optional parameter)
*'''else''' (no parameter)
*'''end''' (no parameter)
*'''value''' (1 optional parameter)
*'''foreach''' (2 parameters)

For powerful macros, you may use these tools:

*RPN Evaluator (see part 2)
*Stacks: The stack is a place where you can push numbers and strings, and then pop them backs. It's used with the little RPN evaluator.
*Local variables: You can dynamically create new variables and changes their values. Some local variables are predefined:
**'''url_value''': parameter of the URL
**'''url_param''': 1 if url_value isn't empty else 0
**'''version''': the VLC version
**'''copyright''': the VLC copyright
**'''vlc_compile_time, vlc_compile_by, vlc_compile_host, vlc_compile_domain, vlc_compiler, vlc_changeset''': information on the VLC build
**'''stream_position, stream_time, stream_length, stream_state''': information on the currently playing stream
**'''volume''': current volume setting

Remark: The stacks, and local variables context is reset before the page is executed.

==The RPN evaluator==

RPN means Reverse Polish Notation.

===Introduction===

RPN may look strange but it's a fast and easy way to write expressions. It also avoids the use of ( and ).

Instead of writing ( 1 + 2 ) * 5 you just use 1 2 + 5 *.

The idea behind it is: if we have a number or a string (using <nowiki>''</nowiki>), push it on the stack. If it is an operator (like +), pop the arguments from the stack, execute the operators and then push the result onto the stack. The result of the RPN sequence is the value on the top of the stack. A step by step explanation of the sequence '''1 2 + 5 *''' is shown below, to illustrate this process:

{| border="1"
! Stack Contents
! Word
! Action taken on the stack
|-
| empty
| 1
| 1 is pushed on the stack
|-
| 1
| 2
| 2 is pushed onto the stack, 'above' 1
|-
| 1 | 2
| +
| The plus operator results in removal of 1 and 2 from the stack, then write 3 onto the stack
|-
| 3
| 5
| 5 is pushed on the stack
|-
| 3 | 5
| *
| The multiplication operator removes 3 and 5 and writes 15 onto the stack.
|-
| 15
|
| Final result.
|}

===Operators===

Notation: ST(1) means the first stack element, ST(2) the second one ... and op is the operator.

You have access to :

*Standard arithmetics operators: '''+, -, *, /, %''' these ones push the result of ST(1) op ST(2) onto the stack

*Binary operators: '''!''' (push !ST(1)); '''^, &, |''': push the result ST(1) op ST(2)

*test: '''=, <, <=, >, >=''': execute ST(1) op ST(2) and push -1 if true else 0

*string functions:
**'''strcat''': pushes the result of 'ST(1)ST(2)
**'''strcmp''': compares ST(1) and ST(2) (0 if equal)
**'''strncmp''': compares the first ST(1) characters of ST(2) and ST(3) (0 if equal)
**'''strsub''': extracts characters ST(2) to ST(1) of string ST(3)
**'''strlen''': pushes the length of ST(1)
**'''str_replace''': replaces string ST(2) with ST(1) in ST(3)
**'''url_encode''': encodes non-alphanumeric characters of ST(1) as %XX so that they can be safely passed as GET or POST variables
**'''url_extract''': performs the reverse operation of url_encode
**'''addslashes''': protects single quotes (') and double quotes (") of ST(1) with backslashes (\) so that they can be safely passed to a VLC playlist function
**'''stripslashes''': performs the reverse operation of addslashes
**'''htmlspecialchars''': encodes &, ', ", <, and > of ST(1) as their &stuff; HTML counterpart, so that they don't interact with HTML tags
**'''realpath''': parses ST(1) as a filename path, and pushes an absolute path to that file, removing ~ and ../

*stack manipulation:
**'''dup''': pops ST(1) and pushes the same string twice
**'''drop''': pops ST(1) and drops it
**'''swap''': exchanges ST(1) and ST(2)
**'''flush''': empties the stack

*variables manipulation:
**'''store''': stores ST(2) in a local variable named ST(1)
**'''value''': pushes the value of the local variable named ST(1)

*player control:
**'''vlc_play''': plays the playlist item whose ID is ST(1), and pushes the return value of the play function (0 in case of success); see playlist functions below
**'''vlc_stop''': stops the playlist
**'''vlc_pause''': pauses the playlist
**'''vlc_next''': plays the next playlist item
**'''vlc_previous''': plays the previous playlist item
**'''vlc_seek''': seeks the current input to a location defined in ST(1), for instance+3m (minutes), -20s, 45%, 1:12, 1h12m25s
**'''vlc_var_type''': pushes the type of the variable ST(2) of object ST(1); the type is one of these strings '''VLC_VAR_BOOL, VLC_VAR_INTEGER, VLC_VAR_HOTKEY, VLC_VAR_STRING, VLC_VAR_MODULE, VLC_VAR_FILE, VLC_VAR_DIRECTORY, VLC_VAR_VARIABLE, VLC_VAR_FLOAT, UNDEFINED''' (no such variable) or '''INVALID''' (no input stream); the object is one of '''VLC_OBJECT_ROOT, VLC_OBJECT_VLC, VLC_OBJECT_INTF, VLC_OBJECT_PLAYLIST, VLC_OBJECT_INPUT, VLC_OBJECT_VOUT, VLC_OBJECT_AOUT''' or '''VLC_OBJECT_SOUT'''
**'''vlc_var_set''': sets variable ST(2) of object ST(1) to ST(3)
**'''vlc_var_get''': pushes the value of the variable ST(2) of object ST(1)
**'''vlc_object_exists''': checks if object ST(1) exists
**'''vlc_config_type''': pushes the type of the configuration variable ST(1); see '''vlc_var_type''' for a list of types
**'''vlc_config_set''': sets configuration variable ST(1) to ST(2)
**'''vlc_config_get''': pushes the value of the configuration variable ST(1)
**'''vlc_config_save''': saves the modification made to the configuration variables of module ST(1) to the configuration file (ST(1) may be empty, in which case the whole configuration is saved) and pushes the return status (0 in case of success)
**'''vlc_config_reset''': resets the configuration file to the default value (use with caution)
**'''vlc_volume_set''': sets the volume value to ST(1) which can be a raw value between 0 and 1024, or a relative one between 0% and 400%, where 1% is equal to the maximum volume value divided by 400 (thus, the maximum volume value is equal to 400%, that is 1024). If ST(1) begins with a '+' (or '-') operator, the volume is increased (or decreased) by the raw value which follows this operator
**'''vlc_get_meta''': pushes the value of the meta information named by ST(1) from the stream being played. Available meta names are: "Title" (or "TITLE"), "Author", "Artist" (or "ARTIST"), "Genre" (or "GENRE"), "Copyright", "Album/movie/show title" (or "ALBUM"), "Track number/position in set", "Description", "Rating", "Date", "Setting", "URL", "Language", "Now Playing", "Publisher"
**'''vlm_command''' or '''vlm_cmd''': sends the command that is on the stack to the VLM (VideoLan Manager). Since the command can contain more than one component on the stack, it must be ended by an ';' or an empty string pushed on the stack (e.g.: param1="';' 'command' 'my' 'this is' vlm_command"). Once the VLM has executed the command, the return value is assigned to the local variable '''vlm_value''' and the error string (if available) is assigned to '''vlm_error'''
**'''snapshot''': takes a snapshot

*playlist functions:
**'''playlist_add''': adds MRL ST(1) to the playlist, with name ST(2) and returns the playlist ID associated to this item; special characters must be escaped with addslashes first; it is very convenient to call 'toto.mpg' playlist_add vlc_play
**'''playlist_empty''': clears the playlist of all items
**'''playlist_move''': moves playlist item at position ST(2) to position ST(1)
**'''playlist_delete''': deletes playlist item ID ST(1)
**'''playlist_sort''': sorts the playlist using the mode ST(2) and order ST(1). Available order values are 0 (normal order) and 1 (reverse order). Available mode values are 0 (sort by ID), 1 (sort by title), 2 (sort by title, nodes first), 3 (sort by author), 4 (sort by genre), 5 (sort randomly), 6 (sort by duration), 7 (numerically sort by title) and 8 (sort by album)
**'''services_discovery_add''': adds the service discovery ST(1) to the playlist
**'''services_discovery_remove''': removes the service discovery ST(1) from the playlist
**'''services_discovery_is_loaded''': checks if the service discovery ST(1) is loaded in the playlist, and pushes the answer on the stack

==The macros==

===The ''control'' macro===

'''The use of the control macro is now deprecated in favour of the RPN functions above. The documentation is provided here for the maintainance of HTML pages still using this old API. The main problem with this API is that there is no way to retrieve the playlist ID of the last added item.'''

When asking for a page, you can give arguments to it through the url. (e.g. using a <form>). Ex: http://host:port/page.html?var=value&var2=value2&... The "control" macro tells a page to parse these arguments and to execute the ones that are allowed. param1 of this macro says which commands are allowed. If empty, all commands will be permitted.

Some commands require an argument that must be passed in the URL too.
*URL commands
**Name, Argument, Description
**'''play''', item (integer), Play the specified playlist item
**'''stop''', ,Stop
**'''pause''', Pause
**'''next''', , Go to next playlist item
**'''previous''', , Go to previous playlist item
**'''add''', mrl (string), Add a [[MRL]] to the playlist
**'''delete''', item (integer), Delete the specified playlist item or list of playlist items
**'''empty''', , Empty the playlist
**'''close''', id (hexa), Close a specific connection
**'''shutdown''', , Quit VLC

For example, you can restrict execution of the '''shutdown''' command to protected page (through a ''.access'' file), using the control macro in all unprotected pages.

===The ''include'' macro===

This macro is replaced by the contents of the file param1. If the file contains vlc macros, they are correctly parsed and replaced.

===The ''get'' macro===

This macro will be replaced by the value of the configuration variable which name is stored in param1 and which type is given by param2.

param1 must be the name of an existing configuration variable. param2 must be the right type of the variable. It can be one of ''int'', ''float'', or ''string''.

Example:
<vlc id="get" param1="sout" param2="string" /> will be replaced in the output page by the value of sout.

===The ''set'' macro===

This macro allows to set the value of a configuration variable. The name is given by param1 and the type by param2 (like for get). The value is retrieved from the url using the name given in param1.

For example, if player.html contains
<vlc id="set" param1="sout" param2="string" />
and if you browse at <emphasis> http://host:ip/player.html?sout=sout_value</emphasis>, the sout variable will be set to "sout_value". If the URL doesn't contain sout, nothing will be done.

===The ''rpn'' macro===

This macro allows you to interpret RPN commands. (See II).

===The ''if,else,end'' macro===

This macro allows you to control the parsing of the HTML page.

If param1 isn't empty, it is first executed with the RPN evaluator. If the first element from the stack is not 0, the test value is true, else false..

<vlc id="if" param1="1 2 =" />

<vlc id="else" />
<p> Test succeed: 1 isn't equal to 2 </p>
<vlc id="end" />

You can also just use "if" and "end".

===The ''value'' macro===

If param1 isn't empty, it is first executed with the RPN evaluator. The macro is replaced with the value of the first element of the stack.

Note: If the element is the name of a local variable, its value will be displayed instead of its name.

===The ''foreach,end'' macro===

param1 is the name of the variable that will be used for the loop. param2 is the name of the set to be built:
*integer: take the first element from the stack to construct a set of integer. The stack element should be a string like: ''first:last[:step][,first2:last2[:step2][,...]'' (Ex:1:5:2,6:8:1 will be expanded into 1,3,5,6,7,8)
*directory: take the first element of the stack as the base directory and construct a set of filename and directly in it. Each element has the following fields:
**basename: file/directory name
**name: complete file/directory name (including path)
**ext: file extension in lowercase
**type: "directory" or "file" or "unknown"
**size: size of the file
**date
*playlist: set based on the playlist with fields: current is 1 if item is currently selected, 0 else. index is the index value, that can be used by the play or delete control command. name is the
name of the item.
*"information": Create information for the current playing stream. name is the name of the category, value is its value, info is a new set that can be parsed with a new foreach (subfields of info are name and value).
*input variables such as "program", "title", "chapter", "audio-es", "video-es" and "spu-es": Create lists for the current playing stream. Every list has the following fields:
**name: item name (language for elementary streams, tracks, etc.) to display in places where a human-readable format is preferred
**id: item ID to pass to the RPN function vlc_var_set, and returned by vlc_var_get
**selected: 1 if the item is selected, 0 otherwise
*the name of a foreach variable if it's a set of set of value.

<vlc id="foreach" param1="cat" param2="informations" />
<vlc id="value" param1="cat.name" />
<ul>
<vlc id="foreach" param1="info" param2="cat.info" />
<li>
<vlc id="value" param1="info.name" /> :
<vlc id="value" param1="info.value" />
</li>
<vlc id="end" />
</ul>
<vlc id="end" />

For more details, have a look at the share/http directory of the VLC source tree...

{{Documentation}}

Help:Editing

2012-04-23T15:54:01Z

Gth: Improved help reference added.

Help in editing the wiki and syntax reference can be found on [http://meta.wikimedia.org/wiki/Help:Editing wikimedia], which is the wiki software we use.

Help talk:Editing

2012-04-23T15:53:38Z

Gth:

==Link to Wikimedia, not Wikipedia==
Shouldn't the Editing Help at the foot of an 'Editing' Page, ie. the content of this page, link to a Wikimedia page, and not to a Wikipedia page? [[User:Stq|Stq]]

:Agreed; it's a much better editing help reference, too. The wikipedia one has various style guides for encyclopedic referencing, etc. I've updated the link.

==External Link icon==
Anyone else see the videolan witch-hat obscuring the last few letters of any external link in their browser?

Documentation:Building Pages for the HTTP Interface

2012-04-23T15:46:00Z

Gth: Formatted stack example into a table. Also corrected text being mistaken for wiki code

{{RightMenu|documentation play howto toc}}

==Introduction==

This appendix describes the language used for writing dynamic web pages for the HTTP interface.

Pages must be placed in the share/http folder in either VLC's folder (Windows, Mac) or /usr/share/vlc/share/http or /usr/local/share/vlc/share/http (or wherever vlc's shared files are installed).

Some files are handled a bit specially:
*Files beginning with '.' are not exported.
*A '.access' file will be opened and the http interface will expect to find at the first line a login/password (written as login:password). This login/password will be used to protect all files in this directory. Be careful that only files in this directory will be protected. (sub-directories won't be protected.)
* A '.hosts' file will be opened and the http interface will expect to find a list of network/mask pairs separated by new line, for instance 192.168.0.0/255.255.255.0. If this file is present, then the default behaviour is to deny access from hosts which don't match any of the network/mask pairs to all the files of the directory. If the file is not present, then any host has access to the files of the directory. Be careful that only files in this directory will be protected. (sub-directories won't be protected.)
*The file <dir>/index.html will be exported as <dir> and <dir>/ and not as index.html.

The MIME type is set by looking at the file extension and cannot be specified nor modified for a specific file. Unknown extensions will have "application/octet-stream" as MIME type.

You should avoid exporting big files. Each file is indeed first loaded into the memory before being sent to the client, so please be careful.

==VLC macros==

Each time a .html/.htm page is requested, it is parsed by VLC before being sent. The parser searches for the VLC macros, and executes or substitutes them. Moreover, URL arguments received by the GET method can be interpreted.

A VLC macro looks like:
<vlc id="macro-name" param1="macro-parameters1" param2="macro-parameters2" />
"id" is the only mandatory field, param1 and param2 may or may not be present and depend on the value of "id".

You should take care that you '''have to''' respect this syntax, VLC won't like invalid syntax. (It could easily leads to crashes).

Examples:

Correct:
<vlc id="value" param1="version" />
Incorrect:
<vlc id="value" param1="version" > (missing tag ending)
<vlc id=value param1="version" /> (missing "" )

Valid macros are:
*'''control''' (1 optional parameter)
*'''include''' (1 parameter)
*'''get''' (2 parameters)
*'''set''' (2 parameters)
*'''rpn''' (1 parameter)
*'''if''' (1 optional parameter)
*'''else''' (no parameter)
*'''end''' (no parameter)
*'''value''' (1 optional parameter)
*'''foreach''' (2 parameters)

For powerful macros, you may use these tools:

*RPN Evaluator (see part 2)
*Stacks: The stack is a place where you can push numbers and strings, and then pop them backs. It's used with the little RPN evaluator.
*Local variables: You can dynamically create new variables and changes their values. Some local variables are predefined:
**'''url_value''': parameter of the URL
**'''url_param''': 1 if url_value isn't empty else 0
**'''version''': the VLC version
**'''copyright''': the VLC copyright
**'''vlc_compile_time, vlc_compile_by, vlc_compile_host, vlc_compile_domain, vlc_compiler, vlc_changeset''': information on the VLC build
**'''stream_position, stream_time, stream_length, stream_state''': information on the currently playing stream
**'''volume''': current volume setting

Remark: The stacks, and local variables context is reset before the page is executed.

==The RPN evaluator==

RPN means Reverse Polish Notation.

===Introduction===

RPN may look strange but it's a fast and easy way to write expressions. It also avoids the use of ( and ).

Instead of writing ( 1 + 2 ) * 5 you just use 1 2 + 5 *.

The idea behind it is: if we have a number or a string (using <nowiki>''</nowiki>), push it on the stack. If it is an operator (like +), pop the arguments from the stack, execute the operators and then push the result onto the stack. The result of the RPN sequence is the value on the top of the stack. A step by step explanation of the sequence '''1 2 + 5 *''' is shown below, to illustrate this process:

{|
! Stack Contents
! Word
! Action taken on the stack
|-
| empty
| 1
| 1 is pushed on the stack
|-
| 1
| 2
| 2 is pushed onto the stack, 'above' 1
|-
| 1 | 2
| +
| The plus operator results in removal of 1 and 2 from the stack, then write 3 onto the stack
|-
| 3
| 5
| 5 is pushed on the stack
|-
| 3 | 5
| *
| The multiplication operator removes 3 and 5 and writes 15 onto the stack.
|-
| 15
|
| Final result.
|}

===Operators===

Notation: ST(1) means the first stack element, ST(2) the second one ... and op is the operator.

You have access to :

*Standard arithmetics operators: '''+, -, *, /, %''' these ones push the result of ST(1) op ST(2) onto the stack

*Binary operators: '''!''' (push !ST(1)); '''^, &, |''': push the result ST(1) op ST(2)

*test: '''=, <, <=, >, >=''': execute ST(1) op ST(2) and push -1 if true else 0

*string functions:
**'''strcat''': pushes the result of 'ST(1)ST(2)
**'''strcmp''': compares ST(1) and ST(2) (0 if equal)
**'''strncmp''': compares the first ST(1) characters of ST(2) and ST(3) (0 if equal)
**'''strsub''': extracts characters ST(2) to ST(1) of string ST(3)
**'''strlen''': pushes the length of ST(1)
**'''str_replace''': replaces string ST(2) with ST(1) in ST(3)
**'''url_encode''': encodes non-alphanumeric characters of ST(1) as %XX so that they can be safely passed as GET or POST variables
**'''url_extract''': performs the reverse operation of url_encode
**'''addslashes''': protects single quotes (') and double quotes (") of ST(1) with backslashes (\) so that they can be safely passed to a VLC playlist function
**'''stripslashes''': performs the reverse operation of addslashes
**'''htmlspecialchars''': encodes &, ', ", <, and > of ST(1) as their &stuff; HTML counterpart, so that they don't interact with HTML tags
**'''realpath''': parses ST(1) as a filename path, and pushes an absolute path to that file, removing ~ and ../

*stack manipulation:
**'''dup''': pops ST(1) and pushes the same string twice
**'''drop''': pops ST(1) and drops it
**'''swap''': exchanges ST(1) and ST(2)
**'''flush''': empties the stack

*variables manipulation:
**'''store''': stores ST(2) in a local variable named ST(1)
**'''value''': pushes the value of the local variable named ST(1)

*player control:
**'''vlc_play''': plays the playlist item whose ID is ST(1), and pushes the return value of the play function (0 in case of success); see playlist functions below
**'''vlc_stop''': stops the playlist
**'''vlc_pause''': pauses the playlist
**'''vlc_next''': plays the next playlist item
**'''vlc_previous''': plays the previous playlist item
**'''vlc_seek''': seeks the current input to a location defined in ST(1), for instance+3m (minutes), -20s, 45%, 1:12, 1h12m25s
**'''vlc_var_type''': pushes the type of the variable ST(2) of object ST(1); the type is one of these strings '''VLC_VAR_BOOL, VLC_VAR_INTEGER, VLC_VAR_HOTKEY, VLC_VAR_STRING, VLC_VAR_MODULE, VLC_VAR_FILE, VLC_VAR_DIRECTORY, VLC_VAR_VARIABLE, VLC_VAR_FLOAT, UNDEFINED''' (no such variable) or '''INVALID''' (no input stream); the object is one of '''VLC_OBJECT_ROOT, VLC_OBJECT_VLC, VLC_OBJECT_INTF, VLC_OBJECT_PLAYLIST, VLC_OBJECT_INPUT, VLC_OBJECT_VOUT, VLC_OBJECT_AOUT''' or '''VLC_OBJECT_SOUT'''
**'''vlc_var_set''': sets variable ST(2) of object ST(1) to ST(3)
**'''vlc_var_get''': pushes the value of the variable ST(2) of object ST(1)
**'''vlc_object_exists''': checks if object ST(1) exists
**'''vlc_config_type''': pushes the type of the configuration variable ST(1); see '''vlc_var_type''' for a list of types
**'''vlc_config_set''': sets configuration variable ST(1) to ST(2)
**'''vlc_config_get''': pushes the value of the configuration variable ST(1)
**'''vlc_config_save''': saves the modification made to the configuration variables of module ST(1) to the configuration file (ST(1) may be empty, in which case the whole configuration is saved) and pushes the return status (0 in case of success)
**'''vlc_config_reset''': resets the configuration file to the default value (use with caution)
**'''vlc_volume_set''': sets the volume value to ST(1) which can be a raw value between 0 and 1024, or a relative one between 0% and 400%, where 1% is equal to the maximum volume value divided by 400 (thus, the maximum volume value is equal to 400%, that is 1024). If ST(1) begins with a '+' (or '-') operator, the volume is increased (or decreased) by the raw value which follows this operator
**'''vlc_get_meta''': pushes the value of the meta information named by ST(1) from the stream being played. Available meta names are: "Title" (or "TITLE"), "Author", "Artist" (or "ARTIST"), "Genre" (or "GENRE"), "Copyright", "Album/movie/show title" (or "ALBUM"), "Track number/position in set", "Description", "Rating", "Date", "Setting", "URL", "Language", "Now Playing", "Publisher"
**'''vlm_command''' or '''vlm_cmd''': sends the command that is on the stack to the VLM (VideoLan Manager). Since the command can contain more than one component on the stack, it must be ended by an ';' or an empty string pushed on the stack (e.g.: param1="';' 'command' 'my' 'this is' vlm_command"). Once the VLM has executed the command, the return value is assigned to the local variable '''vlm_value''' and the error string (if available) is assigned to '''vlm_error'''
**'''snapshot''': takes a snapshot

*playlist functions:
**'''playlist_add''': adds MRL ST(1) to the playlist, with name ST(2) and returns the playlist ID associated to this item; special characters must be escaped with addslashes first; it is very convenient to call 'toto.mpg' playlist_add vlc_play
**'''playlist_empty''': clears the playlist of all items
**'''playlist_move''': moves playlist item at position ST(2) to position ST(1)
**'''playlist_delete''': deletes playlist item ID ST(1)
**'''playlist_sort''': sorts the playlist using the mode ST(2) and order ST(1). Available order values are 0 (normal order) and 1 (reverse order). Available mode values are 0 (sort by ID), 1 (sort by title), 2 (sort by title, nodes first), 3 (sort by author), 4 (sort by genre), 5 (sort randomly), 6 (sort by duration), 7 (numerically sort by title) and 8 (sort by album)
**'''services_discovery_add''': adds the service discovery ST(1) to the playlist
**'''services_discovery_remove''': removes the service discovery ST(1) from the playlist
**'''services_discovery_is_loaded''': checks if the service discovery ST(1) is loaded in the playlist, and pushes the answer on the stack

==The macros==

===The ''control'' macro===

'''The use of the control macro is now deprecated in favour of the RPN functions above. The documentation is provided here for the maintainance of HTML pages still using this old API. The main problem with this API is that there is no way to retrieve the playlist ID of the last added item.'''

When asking for a page, you can give arguments to it through the url. (e.g. using a <form>). Ex: http://host:port/page.html?var=value&var2=value2&... The "control" macro tells a page to parse these arguments and to execute the ones that are allowed. param1 of this macro says which commands are allowed. If empty, all commands will be permitted.

Some commands require an argument that must be passed in the URL too.
*URL commands
**Name, Argument, Description
**'''play''', item (integer), Play the specified playlist item
**'''stop''', ,Stop
**'''pause''', Pause
**'''next''', , Go to next playlist item
**'''previous''', , Go to previous playlist item
**'''add''', mrl (string), Add a [[MRL]] to the playlist
**'''delete''', item (integer), Delete the specified playlist item or list of playlist items
**'''empty''', , Empty the playlist
**'''close''', id (hexa), Close a specific connection
**'''shutdown''', , Quit VLC

For example, you can restrict execution of the '''shutdown''' command to protected page (through a ''.access'' file), using the control macro in all unprotected pages.

===The ''include'' macro===

This macro is replaced by the contents of the file param1. If the file contains vlc macros, they are correctly parsed and replaced.

===The ''get'' macro===

This macro will be replaced by the value of the configuration variable which name is stored in param1 and which type is given by param2.

param1 must be the name of an existing configuration variable. param2 must be the right type of the variable. It can be one of ''int'', ''float'', or ''string''.

Example:
<vlc id="get" param1="sout" param2="string" /> will be replaced in the output page by the value of sout.

===The ''set'' macro===

This macro allows to set the value of a configuration variable. The name is given by param1 and the type by param2 (like for get). The value is retrieved from the url using the name given in param1.

For example, if player.html contains
<vlc id="set" param1="sout" param2="string" />
and if you browse at <emphasis> http://host:ip/player.html?sout=sout_value</emphasis>, the sout variable will be set to "sout_value". If the URL doesn't contain sout, nothing will be done.

===The ''rpn'' macro===

This macro allows you to interpret RPN commands. (See II).

===The ''if,else,end'' macro===

This macro allows you to control the parsing of the HTML page.

If param1 isn't empty, it is first executed with the RPN evaluator. If the first element from the stack is not 0, the test value is true, else false..

<vlc id="if" param1="1 2 =" />

<vlc id="else" />
<p> Test succeed: 1 isn't equal to 2 </p>
<vlc id="end" />

You can also just use "if" and "end".

===The ''value'' macro===

If param1 isn't empty, it is first executed with the RPN evaluator. The macro is replaced with the value of the first element of the stack.

Note: If the element is the name of a local variable, its value will be displayed instead of its name.

===The ''foreach,end'' macro===

param1 is the name of the variable that will be used for the loop. param2 is the name of the set to be built:
*integer: take the first element from the stack to construct a set of integer. The stack element should be a string like: ''first:last[:step][,first2:last2[:step2][,...]'' (Ex:1:5:2,6:8:1 will be expanded into 1,3,5,6,7,8)
*directory: take the first element of the stack as the base directory and construct a set of filename and directly in it. Each element has the following fields:
**basename: file/directory name
**name: complete file/directory name (including path)
**ext: file extension in lowercase
**type: "directory" or "file" or "unknown"
**size: size of the file
**date
*playlist: set based on the playlist with fields: current is 1 if item is currently selected, 0 else. index is the index value, that can be used by the play or delete control command. name is the
name of the item.
*"information": Create information for the current playing stream. name is the name of the category, value is its value, info is a new set that can be parsed with a new foreach (subfields of info are name and value).
*input variables such as "program", "title", "chapter", "audio-es", "video-es" and "spu-es": Create lists for the current playing stream. Every list has the following fields:
**name: item name (language for elementary streams, tracks, etc.) to display in places where a human-readable format is preferred
**id: item ID to pass to the RPN function vlc_var_set, and returned by vlc_var_get
**selected: 1 if the item is selected, 0 otherwise
*the name of a foreach variable if it's a set of set of value.

<vlc id="foreach" param1="cat" param2="informations" />
<vlc id="value" param1="cat.name" />
<ul>
<vlc id="foreach" param1="info" param2="cat.info" />
<li>
<vlc id="value" param1="info.name" /> :
<vlc id="value" param1="info.value" />
</li>
<vlc id="end" />
</ul>
<vlc id="end" />

For more details, have a look at the share/http directory of the VLC source tree...

{{Documentation}}