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)
182 strsub : extract substring of ST(1) from character number ST(2)
183 to character number ST(3)
185 dup : duplicate ST(1) on the stack
187 swap : swap ST(1) and ST(2)
188 flush : empty the stack
189 * variables manipulation:
190 store : store ST(2) in a locale variable named ST(1)
191 value : push the value of the local variable named ST(1)
192 url_extract : push the value of the ST(1) part of the url parameters.
199 When asking for a page, you can pass arguments to it through the url.
201 Ex: http://host:port/page.html?var=value&var2=value2&...
203 The "control" macro warm a page to parse such arguments and give control
204 on which one will be authorized.
206 param1 of this macro say which command are allowed, if empty then all
212 -------------------------------------------------------------------------------
213 | play | item(integer)| Play the specified item
216 | next | | Go to the next playlist element
217 | previous | | Got to the previous playlist element
218 | fullscreen | | toggle fullscreen
219 | volume | value(string)| set volume level (absolute or relative)
220 | seek | seek_value | c.f. notes
221 | add | mrl(string) | Add a mrl to the playlist (with its options)
222 | delete | item(integer)| Deletes an (list of) element of the playlist
223 | keep | item(integer)| Deletes all but (list of) element of the playlist
224 | sort | type,order | c.f. notes
225 | empty | | Empty the playlist
226 | close | id(hexa) | Close a specific connection
227 | shutdown | | Quit vlc
229 For example, you can restrict the execution of the shutdown command to
230 protected pages (through a .access) using the control macro in all pages
234 Seek: The seek command is used to seek in current playing stream. the
235 seek_value argument is a string which represents a relative or absolute
236 position in the stream: a percentage, or a time.
237 For examples "+12min 42sec", "01:13:43", "-12%", "42%", or
238 "1 hour 12 minutes" are valid argument values.
239 Sort: sorts the playlist by type (string), and with the order (integer).
240 If order is "0", it is normal order. Otherwise it is reverse order. The
241 type can be "title", "group", "author".
247 This macro will be replaced by the value of the configuration variable
248 which name is stored in param1 and the type is given by param2.
250 - param1 should be a existing name of a configuration variable
251 - param2 should be the correct type of this variable. You have
257 <vlc id="get" param1="sout" param2="string" />
258 will be replaced in the output page by the value of sout.
263 This macro allow to set the value of a configuration variable.
264 The name is given by param1 and the type by param2 (like for get).
265 The value is retrieve from the url using the name in param1.
267 So if player.html contain <vlc id="set" param1="sout" param2="string" />
268 and then you can call http://host:ip/player.html?sout=sout_value to
269 set sout to the value "sout_value"
271 If the url doesn't contain sout, then nothing is done.
275 This macro allows you to interpret RPN commands.
279 5. Macro "if" "else" "end"
280 --------------------------
281 It allows to control the parsing of the html page.
283 -> if param1 isn't empty, it is first executed with the RPN evaluator.
284 -> if the first element from the stack isn't 0 the test value is true
288 <vlc id="if" param1="1 2 =" />
289 <!-- Never reached -->
291 <p> Test succeed 1 isn't equal to 2 <p>
294 You can also just use "if" and "end".
298 ->if param1 isn't empty, it is first executed with the RPN evaluator.
299 ->the macro is replaced with the value of the first element of the stack.
301 Remarks: if it's in fact a locale variable name, the value of this
302 variable will be displayed (instead of it name).
304 7. Macro "foreach" "end"
305 ------------------------
307 param1 : name of the variable used for the loop
308 param2 : name of the set to be build:
309 - "integer" : take the first element from the stack to construct
310 a set of integer. The stack element should be a string like:
311 first:last[:step][,first2:last2[:step2][,...]
312 Ex: 1:5:2,6:8:1 will be expanded into 1,3,5,6,7,8
314 - "directory" : take the first element of the stack as the base
315 directory and construct a set of filename and directly in it.
316 Each element has the following fields:
317 - name : file/directory name
318 - type : "directory" or "file" or "unknown"
319 - size : size of the file
324 - current : 1 if currently selected else 0
325 - index : the index value (to be used for example for the
326 "delete" control command.
327 - name : the name of the item (it is equal to uri most of the time).
328 - uri : the URI of the item
329 - group : the group number
331 - "informations" : Create informations for the current playing
334 - name : Category name
335 - value : Category value
336 - info : a new set so you can parse it with another foreach.
340 - "hosts" : Create the list of host we are listening.
347 - "urls" : Create the list of urls currently available
350 - stream: 1 if it's a stream else 0.
353 - protected: 1 if protected else 0.
355 - "connections" : Create the list of current connections.
357 - id : opaque id, used by "control" macro (with close command)
360 - status: HTTP error code.
362 - the name of a foreach variable if it's a set of set of value.
364 <vlc id="foreach" param1="cat" param2="informations" />
365 <p> <vlc id="value" param1="cat.name" />
367 <vlc id="foreach" param1="info" param2="cat.info" />
369 <vlc id="value" param1="info.name" /> :
370 <vlc id="value" param1="info.value" />
379 Have a look at share/http directory of the VLC sources...
381 Any remarks, suggestions, ... -> fenrir@via.ecp.fr