Chapter 5.  The HTTP interface

Table of Contents

Introduction
The RPN evaluator
The macros

Introduction

This page is incomplete.

Presentation

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)

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

VLC is shipped with a set of files that should be enough for generic needs. The rest of this chapter will cover the ways to customize these pages.

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.)

  • The file <dir>/index.html will be exported ad <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 specifi 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 type a .html/.htm page is requested, it is parsed by VLC before being sent. The parser searchs 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 crashs).

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)

  • 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

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

The RPN evaluator

RPN means Reverse Polish Notation

Introduction

RPN could 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 beyond it is: if we have a number or a string (using ''), 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.

 stack:      Word processed
 empty      1                   1 is pushed on the stack
 1          2                   2 same things
 1 | 2      +                   +: remove 1 and 2 and write 3 on the stack
 3          5                   5 is pushed on the stack
 3 | 5      *                   *: remove 3 and 5 and write 15
 15                             <- result

Operators

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

You have access to :

  • Standard arithmetics operators: +, -, *, /, %: these ones push the result of ST(1) op ST(2) to 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: strcat pushes the result of 'ST(1)ST(2)', strcmp compares ST(1) and ST(2), pushes -1 if ST(1)<ST(2), 0 if equal, 1 else, strlen pushes the length of ST(1).

  • stack manipulation: dup duplicates ST(1), drop removes ST(1), swap exchanges ST(1) and ST(2), and 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), url_extract pushes the value of the ST(1) part of the url parameters.

The macros

The control macro

When asking for a page, you can pass arguments to it through the url. (eg 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.

Table 5.1.  URL commands

NameArgument 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 (Media Resource Locator) 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 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 http://host:ip/player.html?sout=sout_value, 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 =" />
    <!-- Never reached -->
 <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:

    • name: file/directory name

    • 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.

  • "informations": Create informations 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).

  • "hosts": Create the list of host we are listening. Contains the "id" (opaque id), host, ip and port fields.

  • "urls": Create the list of urls currently available. Fields are id, stream (1 if we have a stream, 0 else), url, mime, protected (1 if protected, 0 else), used (is it currently used ?).

  • "connections": Create the list of current connections. Fields are: id, an opaque id that can be used in the close command, ip, url, and status (HTTP error code).

  • the name of a foreach variable if it's a set of set of value.

    ;<vlc id="foreach" param1="cat" param2="informations" />
                    <p> <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...