1 Instructions to code your own VLC Lua scripts.
7 Lua documenation is available on http://www.lua.org . The reference manual
8 is very usefull: http://www.lua.org/manual/5.1/ .
10 All the Lua standard libraries are available.
15 3 types of VLC Lua scripts can currently be coded:
16 * Playlist (see playlist/README.txt)
17 * Art fetcher (see meta/README.txt)
18 * Interface (see intf/README.txt)
20 Lua scripts are tried in alphabetical order in the user's VLC config
21 directory lua/{playlist,meta,intf}/ subdirectory on Windows and Mac OS X or
22 in the user's local share directory (~/.local/share/vlc/lua/... on linux),
23 then in the global VLC lua/{playlist,meta,intf}/ directory.
25 3 - VLC specific Lua modules
26 ============================
28 All VLC specifc modules are in the "vlc" object. For example, if you want
29 to use the "info" function of the "msg" VLC specific Lua module:
30 vlc.msg.info( "This is an info message and will be displayed in the console" )
32 Note: availability of the different VLC specific Lua modules depends on
33 the type of VLC Lua script your are in.
37 local a = vlc.acl(true) -> new ACL with default set to allow
38 a:check("10.0.0.1") -> 0 == allow, 1 == deny, -1 == error
39 a("10.0.0.1") -> same as a:check("10.0.0.1")
40 a:duplicate() -> duplicate ACL object
41 a:add_host("10.0.0.1",true) -> allow 10.0.0.1
42 a:add_net("10.0.0.0",24,true) -> allow 10.0.0.0/24 (not sure)
43 a:load_file("/path/to/acl") -> load ACL from file
47 config.get( name ): Get the VLC configuration option "name"'s value.
48 config.set( name, value ): Set the VLC configuration option "name"'s value.
52 http( host, port, [cert, key, ca, crl]): create a new HTTP (SSL) daemon.
54 local h = vlc.httpd( "localhost", 8080 )
55 h:handler( url, user, password, acl, callback, data ) -- add a handler for given url. If user and password are non nil, they will be used to authenticate connecting clients. If acl is non nil, it will be used to restrict access. callback will be called to handle connections. The callback function takes 7 arguments: data, url, request, type, in, addr, host. It returns the reply as a string.
56 h:file( url, mime, user, password, acl, callback, data ) -- add a file for given url with given mime type. If user and password are non nil, they will be used to authenticate connecting clients. If acl is non nil, it will be used to restrict access. callback will be called to handle connections. The callback function takes 2 arguments: data and request. It returns the reply as a string.
57 h:redirect( url_dst, url_src ): Redirect all connections from url_src to url_dst.
61 input.info(): Get the current input's info. Return value is a table of tables. Keys of the top level table are info category labels.
62 input.is_playing(): Return true if input exists.
63 input.get_title(): Get the input's name.
64 input.stats(): Get statistics about the input. This is a table with the following fields:
81 msg.dbg( [str1, [str2, [...]]] ): Output debug messages (-vv).
82 msg.warn( [str1, [str2, [...]]] ): Output warning messages (-v).
83 msg.err( [str1, [str2, [...]]] ): Output error messages.
84 msg.info( [str1, [str2, [...]]] ): Output info messages.
88 misc.version(): Get the VLC version string.
89 misc.copyright(): Get the VLC copyright statement.
90 misc.license(): Get the VLC license.
92 misc.datadir(): Get the VLC data directory.
93 misc.userdatadir(): Get the user's VLC data directory.
94 misc.homedir(): Get the user's home directory.
95 misc.configdir(): Get the user's VLC config directory.
96 misc.cachedir(): Get the user's VLC cache directory.
98 misc.datadir_list( name ): FIXME: write description ... or ditch function if it isn't usefull anymore, we have datadir and userdatadir :)
100 misc.mdate(): Get the current date (in milliseconds).
101 misc.mwait(): Wait for the given date (in milliseconds).
103 misc.lock_and_wait(): Lock our object thread and wait for a wake up signal.
104 misc.signal(): Wake up our object thread.
106 misc.should_die(): Returns true if the interface should quit.
107 misc.quit(): Quit VLC.
111 net.url_parse( url, [option delimiter] ): Parse URL. Returns a table with
112 fields "protocol", "username", "password", "host", "port", path" and
114 net.listen_tcp( host, port ): Listen to TCP connections. This returns an
115 object with an accept method. This method takes an optional timeout
116 argument (in milliseconds). For example:
117 local l = vlc.net.listen_tcp( "localhost", 1234 )
119 local fd = l:accept( 500 )
121 net.send( fd, "blabla" )
125 net.close( fd ): Close file descriptor.
126 net.send( fd, string, [length] ): Send data on fd.
127 net.recv( fd, [max length] ): Receive data from fd.
128 net.select( nfds, fds_read, fds_write, timeout ): Monitor a bunch of file descriptors. Returns number of fds to handle and the amount of time not slept. See "man select".
129 net.fd_set_new(): Create a new fd_set.
130 local fds = vlc.net.fd_set_new()
131 fds:clr( fd ) -- remove fd from set
132 fds:isset( fd ) -- check if fd is set
133 fds:set( fd ) -- add fd to set
134 fds:zero() -- clear the set
135 net.fd_read( fd, [max length] ): Read data from fd.
136 net.fd_write( fd, string, [length] ): Write data to fd.
137 net.stat( path ): Stat a file. Returns a table with the following fields:
146 net.opendir( path ): List a directory's contents.
150 object.input(): Get the current input object.
151 object.playlist(): Get the playlist object.
152 object.libvlc(): Get the libvlc object.
154 object.find( object, type, mode ): Find an object of given type. mode can
155 be any of "parent", "child" and "anywhere". If set to "parent", it will
156 look in "object"'s parent objects. If set to "child" it will look in
157 "object"'s children. If set to "anywhere", it will look in all the
158 objects. If object is unset, the current module's object will be used.
159 Type can be: "libvlc", "module", "intf", "playlist", "input", "decoder",
160 "vout", "aout", "packetizer", "encoder", "dialogs", "announce", "demux",
161 "access", "stream", "opengl", "filter", "osdmenu", "httpd_host",
162 "interaction", "generic". This function is slow and should be avoided.
163 object.find_name( object, name, mode ): Same as above except that it matches
164 on the object's name and not type. This function is also slow and should
165 be avoided if possible.
169 osd.icon( type, [id] ): Display an icon on the given OSD channel. Uses the
170 default channel is none is given. Icon types are: "pause", "play",
171 "speaker" and "mute".
172 osd.message( string, [id] ): Display text message on the given OSD channel.
173 osd.slider( position, type, [id] ): Display slider. Position is an integer
174 from 0 to 100. Type can be "horizontal" or "vertical".
175 osd.channel_register(): Register a new OSD channel. Returns the channel id.
176 osd.channel_clear( id ): Clear OSD channel.
180 playlist.prev(): Play previous track.
181 playlist.next(): Play next track.
182 playlist.skip( n ): Skip n tracs.
183 playlist.play(): Play.
184 playlist.pause(): Pause.
185 playlist.stop(): Stop.
186 playlist.clear(): Clear the playlist.
187 playlist.repeat( [status] ): Toggle item repeat or set to specified value.
188 playlist.loop( [status] ): Toggle playlist loop or set to specified value.
189 playlist.random( [status] ): Toggle playlsit random or set to specified value.
190 playlist.goto( id ): Go to specified track.
191 playlist.add( ... ): Add a bunch of items to the playlist.
192 The playlist is a table of playlist objects.
193 A playlist object has the following members:
194 .path: the item's full path / URL
195 .name: the item's name in playlist (OPTIONAL)
196 .title: the item's Title (OPTIONAL, meta data)
197 .artist: the item's Artist (OPTIONAL, meta data)
198 .genre: the item's Genre (OPTIONAL, meta data)
199 .copyright: the item's Copyright (OPTIONAL, meta data)
200 .album: the item's Album (OPTIONAL, meta data)
201 .tracknum: the item's Tracknum (OPTIONAL, meta data)
202 .description: the item's Description (OPTIONAL, meta data)
203 .rating: the item's Rating (OPTIONAL, meta data)
204 .date: the item's Date (OPTIONAL, meta data)
205 .setting: the item's Setting (OPTIONAL, meta data)
206 .url: the item's URL (OPTIONAL, meta data)
207 .language: the item's Language (OPTIONAL, meta data)
208 .nowplaying: the item's NowPlaying (OPTIONAL, meta data)
209 .publisher: the item's Publisher (OPTIONAL, meta data)
210 .encodedby: the item's EncodedBy (OPTIONAL, meta data)
211 .arturl: the item's ArtURL (OPTIONAL, meta data)
212 .trackid: the item's TrackID (OPTIONAL, meta data)
213 .options: a list of VLC options (OPTIONAL)
214 example: .options = { "fullscreen" }
215 .duration: stream duration in seconds (OPTIONAL)
216 .meta: custom meta data (OPTIONAL, meta data)
217 A .meta field is a table of custom meta categories which
218 each have custom meta properties.
219 example: .meta = { ["Google video"] = { ["docid"] = "-5784010886294950089"; ["GVP version"] = "1.1" }; ["misc"] = { "Hello" = "World!" } }
220 Invalid playlist items will be discarded by VLC.
221 playlist.enqueue( ... ): like playlist.add() except that track isn't played.
222 playlist.get( [what, [tree]] ): Get the playist.
223 If "what" is a number, then this will return the corresponding playlist
224 item's playlist hierarchy. If it is "normal" or "playlist", it will
225 return the normal playlist. If it is "ml" or "media library", it will
226 return the media library. If it is "root" it will return the full playlist.
227 If it is a service discovery module's name, it will return that service
228 discovery's playlist. If it is any other string, it won't return anything.
229 Else it will return the fullplaylist.
230 The second argument, "tree", is optional. If set to true or unset, the
231 playlist will be returned in a tree layout. If set to false, the playlist
232 will be returned using the flat layout.
233 Each playlist item returned will have the following members:
235 .flags: a table with the following members if the corresponing flag is
245 .duration: (-1 if unknown)
247 .children: A table of children playlist items.
249 FIXME: add methods to get an item's meta, options, es ...
253 sd.get_services_names(): Get a table of all available service discovery
254 modules. The module name is used as key, the long name is used as value.
255 sd.add( name ): Add service discovery.
256 sd.remove( name ): Remove service discovery.
257 sd.is_loaded( name ): Check if service discovery is loaded.
261 stream( url ): Instantiate a stream object for specific url.
263 s = vlc.stream( "http://www.videolan.org/" )
264 s:read( 128 ) -- read up to 128 characters. Return 0 if no more data is available (FIXME?).
265 s:readline() -- read a line. Return nil if EOF was reached.
269 strings.decode_uri( [uri1, [uri2, [...]]] ): Decode a list of URIs. This
270 function returns as many variables as it had arguments.
271 strings.encode_uri_component( [uri1, [uri2, [...]]] ): Encode a list of URI
272 components. This function returns as many variables as it had arguments.
273 strings.resolve_xml_special_chars( [str1, [str2, [...]]] ): Resolve XML
274 special characters in a list of strings. This function returns as many
275 variables as it had arguments.
276 strings.convert_xml_special_chars( [str1, [str2, [...]]] ): Do the inverse
281 var.get( object, name ): Get the object's variable "name"'s value.
282 var.set( object, name, value ): Set the object's variable "name" to "value".
283 var.get_list( object, name ): Get the object's variable "name"'s value list.
284 1st return value is the value list, 2nd return value is the text list.
285 var.create( object, name, value ): Create and set the object's variable "name"
286 to "value". Created vars can be of type float, string or bool.
288 var.add_callback( object, name, function, data ): Add a callback to the
289 object's "name" variable. Callback functions take 4 arguments: the
290 variable name, the old value, the new value and data.
291 var.del_callback( object, name, function, data ): Delete a callback to
292 the object's "name" variable. "function" and "data" must be the same as
293 when add_callback() was called.
295 var.command( object name, name, argument ): Issue "object name"'s "name"
296 command with argument "argument".
297 var.libvlc_command( name, arguement ): Issue libvlc's "name" command with
302 video.fullscreen( [status] ):
303 * toggle fullscreen if no arguments are given
304 * switch to fullscreen 1st argument is true
305 * disable fullscreen if 1st argument is false
309 vlm(): Instanciate a VLM object.
312 v:execute_command( "new test broadcast" ) -- execute given VLM command
314 Note: if the VLM object is deleted and you were the last person to hold
315 a reference to it, all VLM items will be deleted.
319 volume.set( level ): Set volume to an absolute level between 0 and 1024.
320 volume.get(): Get volume.
321 volume.up( [n] ): Increment volume by n steps of 32. n defaults to 1.
322 volume.down( [n] ): Decrement volume by n steps of 32. n defaults to 1.