7 1. VLC has a little HTTP server
8 -------------------------------
10 You can launch the HTTP interface with :
12 vlc -I http --http-src /directory/ --http-host host:port
14 The HTTP interface will listen at host:port and will reproduce the
15 structure of /directory at http://host:ip/
17 While exporting /director, some files are a bit special :
19 * files beginning with '.' : they won't be exported.
20 * file '.access' : It will be opened and http interface expect to find
21 at the first line a login/password (written as login:password). This
22 login/password will be used to protect all files in this directory.
23 Be careful that only files in this directory will be protected,
24 particularly sub-directory won't be protected.
25 * file <dir>/index.html will be exported as <dir> and <dir>/ and not as
30 directory/index.html -> http://host:port/
31 directory/help.html -> http://host:port/help.html
32 directory/help.gif -> http://host:port/help.gif
33 directory/.access -> "Not exported"
34 directory/dir2/essai.html -> http://host:port/dir2/essai.html
36 The mime type is set looking at file extension and it cannot be
37 specified/modified for specific file. Unknown extensions will have
38 "application/octet-stream" as the mime type.
40 You should avoid exported big files. Actually, each file is first
41 loaded in memory before being sent to a client, so be careful ...
44 2. VLC macro in .html/.htm pages
45 --------------------------------
50 Each type, a .html/.htm page is requested, it is parsed by the vlc
51 before sent. This parser search for special vlc macro, and then execute
52 them or substitute them.
53 Moreover, when receiving URL arguments (by a GET method), they could be
58 A vlc macro have to respect :
59 <vlc id="macro-name" param1="macro-parameters1" param2="macro-parameters2" />
61 "id" is the only mandatory field, param1 and param2 may or may not be
62 present and depends on the value of "id".
64 You should take care that you _have to_ respect this syntax, VLC won't
65 like invalid syntax. (It could easily leads to segfaults)
69 <vlc id="value" param1="version" /> is correct
71 <vlc id="value" param1="version" > <- invalid tag ending
72 <vlc id=value param1="version" /> <- missing "" around value
77 For now the following macro are valid :
79 Macro | Parameter 1 | Parameter 2
80 ----------------------------------------------
91 3. RPN, Stacks and locale variables
92 ------------------------------
94 To provide powerful macro, you have access to
102 The stacks is a place where you can push numbers and strings, and then
103 pop them backs. It's used with the little RPN evaluator.
107 You can dynamically create new variables and changes their values.
108 Some locales variables are predefined
109 - url_value : parameter of the url
110 - url_param : 1 if url_value isn't empty else 0
111 - version : the VLC version
112 - copyright : the VLC copyright
113 - stream_position : current position of the VLC in the stream (percentage)
114 - stream_time : current position of the VLC in the stream (in seconds)
115 - stream_length : total length of the current stream (in seconds)
116 - volume : current volume level
117 - stream_state : current state of the VLC (playing, paused, stop)
119 Variables could have fields, just use . to access them.
120 Ex: var.field, var.field.subfield, ...
121 A field could in fact be a set, so use [] to access a particular element.
122 Ex: var.field[2], var.field[3].subfield[12]
124 Remarks: you cannot create (yet) such variables with fields.
128 The stacks, and locales variables context is reseted before a page is
134 RPN means Reverse Polish Notation.
139 RPN could be strange but it's a fast and easy way to write expressions.
140 It also avoid the use of ( and ).
142 Instead of writing ( 1 + 2 ) * 5 you just use 1 2 + 5 *
143 The idea beyond it is :
144 - if it is a number or a string (using '') push it on the stack
145 - if it is an operator (like +), pop the arguments from the stack,
146 execute the operators and then push the result onto the stack.
147 The result of the RPN sequence is the value at the top of the stack.
150 Ex: instead of writing (1+2)*5 you enter 1 2 + 5 *
152 stack: Word processed
153 <empty> 1 1 is pushed on the stack
155 1 | 2 + + : remove 1 and 2 and write 3 on the stack
156 3 5 5 is pushed on the stack
157 3 | 5 * * : remove 3 and 5 and write 15
164 Notation : ST(1) means the first stack element, ST(2) the second one ...
169 * standard arithmetics operators:
170 +, -, *, /, % : push the result of ST(1) op ST(2)
171 * standard binary operators:
173 ^, &, | : push the result of ST(1) op ST(2)
175 =, <, <=, >, >= : do ST(1) op ST(2) and push -1 if true else 0
177 strcat : push the result of 'ST(1)ST(2)'
178 strcmp : compare ST(1) and ST(2), push -1, 0, or 1
179 strncmp : compare the ST(3) first characters of ST(1) and ST(2),
181 strlen : push the length of ST(1)
183 dup : duplicate ST(1) on the stack
185 swap : swap ST(1) and ST(2)
186 flush : empty the stack
187 * variables manipulation:
188 store : store ST(2) in a locale variable named ST(1)
189 value : push the value of the local variable named ST(1)
190 url_extract : push the value of the ST(1) part of the url parameters.
197 When asking for a page, you can pass arguments to it through the url.
199 Ex: http://host:port/page.html?var=value&var2=value2&...
201 The "control" macro warm a page to parse such arguments and give control
202 on which one will be authorized.
204 param1 of this macro say which command are allowed, if empty then all
210 -------------------------------------------------------------------------------
211 | play | item(integer)| Play the specified item
214 | next | | Go to the next playlist element
215 | previous | | Got to the previous playlist element
216 | fullscreen | | toggle fullscreen
217 | volume | value(string)| set volume level (absolute or relative)
218 | seek | seek_value | c.f. notes
219 | add | mrl(string) | Add a mrl to the playlist (with its options)
220 | delete | item(integer)| Deletes an (list of) element of the playlist
221 | keep | item(integer)| Deletes all but (list of) element of the playlist
222 | sort | type,order | c.f. notes
223 | empty | | Empty the playlist
224 | close | id(hexa) | Close a specific connection
225 | shutdown | | Quit vlc
227 For example, you can restrict the execution of the shutdown command to
228 protected pages (through a .access) using the control macro in all pages
232 Seek: The seek command is used to seek in current playing stream. the
233 seek_value argument is a string which represents a relative or absolute
234 position in the stream: a percentage, or a time.
235 For examples "+12min 42sec", "01:13:43", "-12%", "42%", or
236 "1 hour 12 minutes" are valid argument values.
237 Sort: sorts the playlist by type (string), and with the order (integer).
238 If order is "0", it is normal order. Otherwise it is reverse order. The
239 type can be "title", "group", "author".
245 This macro will be replaced by the value of the configuration variable
246 which name is stored in param1 and the type is given by param2.
248 - param1 should be a existing name of a configuration variable
249 - param2 should be the correct type of this variable. You have
255 <vlc id="get" param1="sout" param2="string" />
256 will be replaced in the output page by the value of sout.
261 This macro allow to set the value of a configuration variable.
262 The name is given by param1 and the type by param2 (like for get).
263 The value is retrieve from the url using the name in param1.
265 So if player.html contain <vlc id="set" param1="sout" param2="string" />
266 and then you can call http://host:ip/player.html?sout=sout_value to
267 set sout to the value "sout_value"
269 If the url doesn't contain sout, then nothing is done.
273 This macro allows you to interpret RPN commands.
277 5. Macro "if" "else" "end"
278 --------------------------
279 It allows to control the parsing of the html page.
281 -> if param1 isn't empty, it is first executed with the RPN evaluator.
282 -> if the first element from the stack isn't 0 the test value is true
286 <vlc id="if" param1="1 2 =" />
287 <!-- Never reached -->
289 <p> Test succeed 1 isn't equal to 2 <p>
292 You can also just use "if" and "end".
296 ->if param1 isn't empty, it is first executed with the RPN evaluator.
297 ->the macro is replaced with the value of the first element of the stack.
299 Remarks: if it's in fact a locale variable name, the value of this
300 variable will be displayed (instead of it name).
302 7. Macro "foreach" "end"
303 ------------------------
305 param1 : name of the variable used for the loop
306 param2 : name of the set to be build:
307 - "integer" : take the first element from the stack to construct
308 a set of integer. The stack element should be a string like:
309 first:last[:step][,first2:last2[:step2][,...]
310 Ex: 1:5:2,6:8:1 will be expanded into 1,3,5,6,7,8
312 - "directory" : take the first element of the stack as the base
313 directory and construct a set of filename and directly in it.
314 Each element has the following fields:
315 - name : file/directory name
316 - type : "directory" or "file" or "unknown"
317 - size : size of the file
322 - current : 1 if currently selected else 0
323 - index : the index value (to be used for example for the
324 "delete" control command.
326 - group : the group number
328 - "informations" : Create informations for the current playing
331 - name : Category name
332 - value : Category value
333 - info : a new set so you can parse it with another foreach.
337 - "hosts" : Create the list of host we are listening.
344 - "urls" : Create the list of urls currently available
347 - stream: 1 if it's a stream else 0.
350 - protected: 1 if protected else 0.
352 - "connections" : Create the list of current connections.
354 - id : opaque id, used by "control" macro (with close command)
357 - status: HTTP error code.
359 - the name of a foreach variable if it's a set of set of value.
361 <vlc id="foreach" param1="cat" param2="informations" />
362 <p> <vlc id="value" param1="cat.name" />
364 <vlc id="foreach" param1="info" param2="cat.info" />
366 <vlc id="value" param1="info.name" /> :
367 <vlc id="value" param1="info.value" />
376 Have a look at share/http directory of the VLC sources...
378 Any remarks, suggestions, ... -> fenrir@via.ecp.fr