mirror of
https://code.videolan.org/videolan/vlc
synced 2024-10-03 01:31:53 +02:00
32ed571bf3
played item * doc/intf-http.txt : adding "pl.group" * share/http/index.html : little cosmetic change (better according to gibalou).
380 lines
13 KiB
Plaintext
380 lines
13 KiB
Plaintext
HTTP interface
|
|
--------------
|
|
|
|
I. Presentation
|
|
###############
|
|
|
|
1. VLC has a little HTTP server
|
|
-------------------------------
|
|
|
|
You can launch the HTTP interface with :
|
|
|
|
vlc -I http --http-src /directory/ --http-host host:port
|
|
|
|
The HTTP interface will listen at host:port and will reproduce the
|
|
structure of /directory at http://host:ip/
|
|
|
|
While exporting /director, some files are a bit special :
|
|
|
|
* files beginning with '.' : they won't be exported.
|
|
* file '.access' : It will be opened and http interface 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,
|
|
particularly sub-directory won't be protected.
|
|
* file <dir>/index.html will be exported as <dir> and <dir>/ and not as
|
|
index.html.
|
|
|
|
Examples:
|
|
Sources URL
|
|
directory/index.html -> http://host:port/
|
|
directory/help.html -> http://host:port/help.html
|
|
directory/help.gif -> http://host:port/help.gif
|
|
directory/.access -> "Not exported"
|
|
directory/dir2/essai.html -> http://host:port/dir2/essai.html
|
|
|
|
The mime type is set looking at file extension and it cannot be
|
|
specified/modified for specific file. Unknown extensions will have
|
|
"application/octet-stream" as the mime type.
|
|
|
|
You should avoid exported big files. Actually, each file is first
|
|
loaded in memory before being sent to a client, so be careful ...
|
|
|
|
|
|
2. VLC macro in .html/.htm pages
|
|
--------------------------------
|
|
|
|
a. Presentation
|
|
---------------
|
|
|
|
Each type, a .html/.htm page is requested, it is parsed by the vlc
|
|
before sent. This parser search for special vlc macro, and then execute
|
|
them or substitute them.
|
|
Moreover, when receiving URL arguments (by a GET method), they could be
|
|
interpreted.
|
|
|
|
b. Syntax
|
|
---------
|
|
A vlc macro have to respect :
|
|
<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 depends 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 segfaults)
|
|
|
|
For examples :
|
|
Correct:
|
|
<vlc id="value" param1="version" /> is correct
|
|
Invalid:
|
|
<vlc id="value" param1="version" > <- invalid tag ending
|
|
<vlc id=value param1="version" /> <- missing "" around value
|
|
|
|
c. Valid macro list
|
|
-------------------
|
|
|
|
For now the following macro are valid :
|
|
|
|
Macro | Parameter 1 | Parameter 2
|
|
----------------------------------------------
|
|
control | Optional |
|
|
get | Yes | Yes
|
|
set | Yes | Yes
|
|
rpn | Yes |
|
|
if | Optional |
|
|
else | |
|
|
end | |
|
|
value | Optional |
|
|
foreach | Yes | Yes
|
|
|
|
3. RPN, Stacks and locale variables
|
|
------------------------------
|
|
|
|
To provide powerful macro, you have access to
|
|
|
|
a. RPN evaluator
|
|
----------------
|
|
See II.
|
|
|
|
b. Stacks
|
|
---------
|
|
The stacks is a place where you can push numbers and strings, and then
|
|
pop them backs. It's used with the little RPN evaluator.
|
|
|
|
c. Locales variables
|
|
--------------------
|
|
You can dynamically create new variables and changes their values.
|
|
Some locales 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
|
|
- stream_position : current position of the VLC in the stream (percentage)
|
|
- stream_time : current position of the VLC in the stream (in seconds)
|
|
- stream_length : total length of the current stream (in seconds)
|
|
- volume : current volume level
|
|
- stream_state : current state of the VLC (playing, paused, stop)
|
|
|
|
Variables could have fields, just use . to access them.
|
|
Ex: var.field, var.field.subfield, ...
|
|
A field could in fact be a set, so use [] to access a particular element.
|
|
Ex: var.field[2], var.field[3].subfield[12]
|
|
|
|
Remarks: you cannot create (yet) such variables with fields.
|
|
|
|
4. Remarks:
|
|
-----------
|
|
The stacks, and locales variables context is reseted before a page is
|
|
executed.
|
|
|
|
II. RPN evaluator
|
|
#################
|
|
|
|
RPN means Reverse Polish Notation.
|
|
|
|
1.introduction
|
|
--------------
|
|
|
|
RPN could be strange but it's a fast and easy way to write expressions.
|
|
It also avoid the use of ( and ).
|
|
|
|
Instead of writing ( 1 + 2 ) * 5 you just use 1 2 + 5 *
|
|
The idea beyond it is :
|
|
- if it is 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 at the top of the stack.
|
|
|
|
|
|
Ex: instead of writing (1+2)*5 you enter 1 2 + 5 *
|
|
|
|
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
|
|
|
|
|
|
2. 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:
|
|
+, -, *, /, % : push the result of ST(1) op ST(2)
|
|
* standard binary operators:
|
|
! : push !ST(1)
|
|
^, &, | : push the result of ST(1) op ST(2)
|
|
* test:
|
|
=, <, <=, >, >= : do ST(1) op ST(2) and push -1 if true else 0
|
|
* string:
|
|
strcat : push the result of 'ST(1)ST(2)'
|
|
strcmp : compare ST(1) and ST(2), push -1, 0, or 1
|
|
strncmp : compare the ST(3) first characters of ST(1) and ST(2),
|
|
push -1, 0, or 1
|
|
strlen : push the length of ST(1)
|
|
* stack manipulation
|
|
dup : duplicate ST(1) on the stack
|
|
drop : remove ST(1)
|
|
swap : swap ST(1) and ST(2)
|
|
flush : empty the stack
|
|
* variables manipulation:
|
|
store : store ST(2) in a locale variable named ST(1)
|
|
value : push the value of the local variable named ST(1)
|
|
url_extract : push the value of the ST(1) part of the url parameters.
|
|
|
|
III. Macros
|
|
###########
|
|
|
|
1. Macro "control"
|
|
------------------
|
|
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 warm a page to parse such arguments and give control
|
|
on which one will be authorized.
|
|
|
|
param1 of this macro say which command are allowed, if empty then all
|
|
commands will work.
|
|
|
|
Url commands are :
|
|
|
|
| Name | arguments |
|
|
-------------------------------------------------------------------------------
|
|
| play | item(integer)| Play the specified item
|
|
| stop | | Stop
|
|
| pause | | Pause
|
|
| next | | Go to the next playlist element
|
|
| previous | | Got to the previous playlist element
|
|
| fullscreen | | toggle fullscreen
|
|
| volume | value(string)| set volume level (absolute or relative)
|
|
| seek | seek_value | c.f. notes
|
|
| add | mrl(string) | Add a mrl to the playlist (with its options)
|
|
| delete | item(integer)| Deletes an (list of) element of the playlist
|
|
| keep | item(integer)| Deletes all but (list of) element of the playlist
|
|
| sort | type,order | c.f. notes
|
|
| empty | | Empty the playlist
|
|
| close | id(hexa) | Close a specific connection
|
|
| shutdown | | Quit vlc
|
|
|
|
For example, you can restrict the execution of the shutdown command to
|
|
protected pages (through a .access) using the control macro in all pages
|
|
unprotected.
|
|
|
|
Notes:
|
|
Seek: The seek command is used to seek in current playing stream. the
|
|
seek_value argument is a string which represents a relative or absolute
|
|
position in the stream: a percentage, or a time.
|
|
For examples "+12min 42sec", "01:13:43", "-12%", "42%", or
|
|
"1 hour 12 minutes" are valid argument values.
|
|
Sort: sorts the playlist by type (string), and with the order (integer).
|
|
If order is "0", it is normal order. Otherwise it is reverse order. The
|
|
type can be "title", "group", "author".
|
|
|
|
|
|
2. Macro "get"
|
|
--------------
|
|
|
|
This macro will be replaced by the value of the configuration variable
|
|
which name is stored in param1 and the type is given by param2.
|
|
|
|
- param1 should be a existing name of a configuration variable
|
|
- param2 should be the correct type of this variable. You have
|
|
- int
|
|
- float
|
|
- string
|
|
|
|
Example:
|
|
<vlc id="get" param1="sout" param2="string" />
|
|
will be replaced in the output page by the value of sout.
|
|
|
|
3. Macro "set"
|
|
--------------
|
|
|
|
This macro allow 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 retrieve from the url using the name in param1.
|
|
|
|
So if player.html contain <vlc id="set" param1="sout" param2="string" />
|
|
and then you can call http://host:ip/player.html?sout=sout_value to
|
|
set sout to the value "sout_value"
|
|
|
|
If the url doesn't contain sout, then nothing is done.
|
|
|
|
4. Macro "rpn"
|
|
-------------
|
|
This macro allows you to interpret RPN commands.
|
|
See II.
|
|
|
|
|
|
5. Macro "if" "else" "end"
|
|
--------------------------
|
|
It allows 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 isn't 0 the test value is true
|
|
else false.
|
|
|
|
ex:
|
|
<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".
|
|
|
|
6. Macro "value"
|
|
----------------
|
|
->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.
|
|
|
|
Remarks: if it's in fact a locale variable name, the value of this
|
|
variable will be displayed (instead of it name).
|
|
|
|
7. Macro "foreach" "end"
|
|
------------------------
|
|
|
|
param1 : name of the variable used for the loop
|
|
param2 : name of the set to be build:
|
|
- "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" :
|
|
Fields:
|
|
- current : 1 if currently selected else 0
|
|
- index : the index value (to be used for example for the
|
|
"delete" control command.
|
|
- name
|
|
- group : the group number
|
|
|
|
- "informations" : Create informations for the current playing
|
|
stream.
|
|
Fields:
|
|
- name : Category name
|
|
- value : Category value
|
|
- info : a new set so you can parse it with another foreach.
|
|
Sub fields :
|
|
- name : Info name
|
|
- value Info value
|
|
- "hosts" : Create the list of host we are listening.
|
|
Fields:
|
|
- id : opaque id
|
|
- host:
|
|
- ip :
|
|
- port:
|
|
|
|
- "urls" : Create the list of urls currently available
|
|
Fields:
|
|
- id :
|
|
- stream: 1 if it's a stream else 0.
|
|
- url :
|
|
- mime :
|
|
- protected: 1 if protected else 0.
|
|
- used :
|
|
- "connections" : Create the list of current connections.
|
|
Fields:
|
|
- id : opaque id, used by "control" macro (with close command)
|
|
- ip :
|
|
- url:
|
|
- status: HTTP error code.
|
|
|
|
- the name of a foreach variable if it's a set of set of value.
|
|
Ex :
|
|
<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" />
|
|
|
|
IV. Conclusion
|
|
##############
|
|
|
|
Have a look at share/http directory of the VLC sources...
|
|
|
|
Any remarks, suggestions, ... -> fenrir@via.ecp.fr
|
|
|