1 - About Lua
=============
-Lua documenation is available on http://www.lua.org . The reference manual
+Lua documention is available on http://www.lua.org . The reference manual
is very usefull: http://www.lua.org/manual/5.1/ .
VLC uses Lua 5.1
All the Lua standard libraries are available.
2 - Lua in VLC
==============
-3 types of VLC Lua scripts can currently be coded:
+Several types of VLC Lua scripts can currently be coded:
* Playlist (see playlist/README.txt)
* Art fetcher (see meta/README.txt)
* Interface (see intf/README.txt)
+ * Extensions (see extensions/README.txt)
+ * Services Discovery (see sd/README.txt)
Lua scripts are tried in alphabetical order in the user's VLC config
directory lua/{playlist,meta,intf}/ subdirectory on Windows and Mac OS X or
config.get( name ): Get the VLC configuration option "name"'s value.
config.set( name, value ): Set the VLC configuration option "name"'s value.
+Dialog
+------
+local d = vlc.dialog( "My VLC Extension" ): Create a new UI dialog, with a human-readble title: "My VLC Extension"
+d:show(): Show this dialog.
+d:hide(): Hide (but not close) this dialog.
+d:delete(): Close and delete this dialog.
+d:del_widget( widget ): Delete 'widget'. It disappears from the dialog and repositionning may occur.
+d:update(): Update the dialog immediately (don't wait for the current function to return)
+
+In the following functions, you can always add some optional parameters: col, row, col_span, row_span, width, height.
+They define the position of a widget in the dialog:
+- row, col are the absolute positions on a grid of widgets. First row, col are 1.
+- row_span, col_span represent the relative size of a widget on the grid. A widget with col_span = 4 will be displayed as wide as 4 widgets of col_span = 1.
+- width and height are size hints (in pixels) but may be discarded by the GUI module
+Example: w = d:add_label( "My Label", 2, 3, 4, 5 ) will create a label at row 3, col 2, with a relative width of 4, height of 5.
+
+d:add_button( text, func, ... ): Create a button with caption "text" (string). When clicked, call function "func". func is a function reference.
+d:add_label( text, ... ): Create a text label with caption "text" (string).
+d:add_html( text, ... ): Create a rich text label with caption "text" (string), that supports basic HTML formatting (such as <i> or <h1> for instance).
+d:add_text_input( text, ... ): Create an editable text field, in order to read user input.
+d:add_password( text, ... ): Create an editable text field, in order to read user input. Text entered in this box will not be readable (replaced by asterisks).
+d:add_check_box( text, ... ): Create a check box with a text. They have a boolean state (true/false).
+d:add_dropdown( ... ): Create a drop-down widget. Only 1 element can be selected the same time.
+d:add_list( ... ): Create a list widget. Allows multiple or empty selections.
+d:add_image( path, ... ): Create an image label. path is a relative or absolute path to the image on the local computer.
+
+Some functions can also be applied on widgets:
+w:set_text( text ): Change text displayed by the widget. Applies to: button, label, html, text_input, password, check_box.
+w:get_text(): Read text displayed by the widget. Returns a string. Applies to: button, label, html, text_input, password, check_box.
+w:set_checked( bool ): Set check state of a check box. Applies to: check_box.
+w:get_checked(): Read check state of a check box. Returns a boolean. Applies to: check_box.
+w:add_value( text, id ): Add a value with identifier 'id' (integer) and text 'text'. It's always best to have unique identifiers. Applies to: drop_down.
+w:get_value(): Return identifier of the selected item. Corresponds to the text value chosen by the user. Applies to: drop_down.
+w:clear(): Clear a list or drop_down widget. After that, all values previously added are lost.
+w:get_selection(): Retrieve a table representing the current selection. Keys are the ids, values are the texts associated. Applies to: list.
+
+
+Extension
+---------
+deactivate(): Deactivate current extension (after the end of the current function).
+
HTTPd
-----
http( host, port, [cert, key, ca, crl]): create a new HTTP (SSL) daemon.
Input
-----
-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.
input.is_playing(): Return true if input exists.
-input.get_title(): Get the input's name.
-input.stats(): Get statistics about the input. This is a table with the following fields:
+input.add_subtitle(url): Add a subtitle to the current input
+input.item(): Get the current input item. Input item methods are:
+ :uri(): Get item's URI.
+ :name(): Get item's name.
+ :duration(): Get item's duration in seconds or negative value if unavailable.
+ :is_preparsed(): Return true if meta data has been preparsed
+ :metas(): Get meta data as a table.
+ :set_meta(key, value): Set meta data.
+ :info(): Get the current input's info. Return value is a table of tables. Keys of the top level table are info category labels.
+ :stats(): Get statistics about the input. This is a table with the following fields:
+ .read_packets
.read_bytes
.input_bitrate
+ .average_input_bitrate
+ .demux_read_packets
.demux_read_bytes
.demux_bitrate
+ .average_demux_bitrate
+ .demux_corrupted
+ .demux_discontinuity
+ .decoded_audio
.decoded_video
.displayed_pictures
.lost_pictures
- .decoded_audio
- .played_abuffers
- .lost_abuffers
.sent_packets
.sent_bytes
.send_bitrate
+ .played_abuffers
+ .lost_abuffers
+
+MD5
+---
+md5( str ): return the string's hash
+md5(): create an md5 object with the following methods:
+ :add( str ): add a string to the hash
+ :end_(): finish hashing
+ :hash(): return the hash
Messages
--------
misc.configdir(): Get the user's VLC config directory.
misc.cachedir(): Get the user's VLC cache directory.
-misc.datadir_list( name ): FIXME: write description ... or ditch function if it isn't usefull anymore, we have datadir and userdatadir :)
+misc.datadir_list( name ): FIXME: write description ... or ditch function
+ if it isn't usefull anymore, we have datadir and userdatadir :)
misc.mdate(): Get the current date (in milliseconds).
misc.mwait(): Wait for the given date (in milliseconds).
fields "protocol", "username", "password", "host", "port", path" and
"option".
net.listen_tcp( host, port ): Listen to TCP connections. This returns an
- object with an accept method. This method takes an optional timeout
- argument (in milliseconds). For example:
+ object with an accept and an fds method. accept is blocking (Poll on the
+ fds with the net.POLLIN flag if you want to be non blockin).
+ The fds method returns a list of fds you can call poll on before using
+ the accept method. For example:
local l = vlc.net.listen_tcp( "localhost", 1234 )
while true do
- local fd = l:accept( 500 )
+ local fd = l:accept()
if fd >= 0 do
net.send( fd, "blabla" )
net.close( fd )
net.close( fd ): Close file descriptor.
net.send( fd, string, [length] ): Send data on fd.
net.recv( fd, [max length] ): Receive data from fd.
-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".
-net.fd_set_new(): Create a new fd_set.
-local fds = vlc.net.fd_set_new()
-fds:clr( fd ) -- remove fd from set
-fds:isset( fd ) -- check if fd is set
-fds:set( fd ) -- add fd to set
-fds:zero() -- clear the set
+net.poll( { fd = events }, [timeout in seconds] ): Implement poll function.
+ Retruns the numbers of file descriptors with a non 0 revent. The function
+ modifies the input table to { fd = revents }. See "man poll".
+net.POLLIN/POLLPRI/POLLOUT/POLLRDHUP/POLLERR/POLLHUP/POLLNVAL: poll event flags
net.fd_read( fd, [max length] ): Read data from fd.
net.fd_write( fd, string, [length] ): Write data to fd.
net.stat( path ): Stat a file. Returns a table with the following fields:
"object"'s children. If set to "anywhere", it will look in all the
objects. If object is unset, the current module's object will be used.
Type can be: "libvlc", "playlist", "input", "decoder",
- "vout", "aout", "packetizer", "encoder", "generic".
+ "vout", "aout", "packetizer", "generic".
This function is deprecated and slow and should be avoided.
object.find_name( object, name, mode ): Same as above except that it matches
on the object's name and not type. This function is also slow and should
from 0 to 100. Type can be "horizontal" or "vertical".
osd.channel_register(): Register a new OSD channel. Returns the channel id.
osd.channel_clear( id ): Clear OSD channel.
+osd.menu.show(): Show the OSD menu.
+osd.menu.hide(): Hide the OSD menu.
+osd.menu.prev(): Select previous/left item.
+osd.menu.next(): Select next/right item.
+osd.menu.up(): Move selection up.
+osd.menu.down(): Move selection down.
+osd.menu.activate(): Activate/validate current selection.
Playlist
--------
playlist.pause(): Pause.
playlist.stop(): Stop.
playlist.clear(): Clear the playlist.
-playlist.repeat( [status] ): Toggle item repeat or set to specified value.
+playlist.repeat_( [status] ): Toggle item repeat or set to specified value.
playlist.loop( [status] ): Toggle playlist loop or set to specified value.
playlist.random( [status] ): Toggle playlsit random or set to specified value.
playlist.goto( id ): Go to specified track.
sd.add( name ): Add service discovery.
sd.remove( name ): Remove service discovery.
sd.is_loaded( name ): Check if service discovery is loaded.
+sd.add_item( ... ): Add an item to the service discovery.
+ The item object has the same members as the one in playlist.add().
+ Returns the input item.
+sd.add_node( ... ): Add a node to the service discovery.
+ The node object has the following members:
+ .title: the node's name
+ .arturl: the node's ArtURL (OPTIONAL)
+
+n = vlc.sd.add_node( {title="Node"} )
+n:add_subitem( ... ): Same as sd.add_item(), but as a subitem of n.
+n:add_node( ... ): Same as sd.add_node(), but as a subnode of n.
Stream
------
stream( url ): Instantiate a stream object for specific url.
+memory_stream( string ): Instantiate a stream object containing a specific string.
+ Those two functions return the stream object upon success and nil if an
+ error occured, in that case, the second return value will be an error message.
s = vlc.stream( "http://www.videolan.org/" )
s:read( 128 ) -- read up to 128 characters. Return 0 if no more data is available (FIXME?).
s:readline() -- read a line. Return nil if EOF was reached.
+s:addfilter() -- add a stream filter. If no argument was specified, try to add all automatic stream filters.
Strings
-------
var.del_callback( object, name, function, data ): Delete a callback to
the object's "name" variable. "function" and "data" must be the same as
when add_callback() was called.
+var.trigger_callback( object, name ): Trigger the callbacks associated with the
+ object's "name" variable.
var.command( object name, name, argument ): Issue "object name"'s "name"
command with argument "argument".
Volume
------
volume.set( level ): Set volume to an absolute level between 0 and 1024.
+ 256 is 100%.
volume.get(): Get volume.
volume.up( [n] ): Increment volume by n steps of 32. n defaults to 1.
volume.down( [n] ): Decrement volume by n steps of 32. n defaults to 1.