This is some documentation on the Lua scripting API for VLC Media Player. It covers the modules and script types that are available to VLC addon developers.
Script Basics
Installation
Scripts are placed into their own special folders in the VLC install directory. Below are the install directories for VLC scripts on different platforms.
- Windows (all users): %ProgramFiles%\VideoLAN\VLC\lua\
- Windows (current user): %APPDATA%\VLC\lua\
- Linux (all users): /usr/lib/vlc/lua/
- Linux (current user): ~/.local/share/vlc/lua/
- Mac OS X (all users): /Applications/VLC.app/Contents/MacOS/share/lua/
- Mac OS X (current user): /Users/%your_name%/Library/Application Support/org.videolan.vlc/lua/
Types of Scripts
Name | Description | Install Subdirectory | Version Range |
---|---|---|---|
Art | Scripts called to download album/track artwork | /lua/meta/art/ | 0.9+ |
Extensions | Addons to VLC, found in the “Views” menu (has access to the dialog module) | /lua/extensions/ | 1.1+ |
Interfaces | Run in the background (custom interfaces must be enabled) | /lua/intf/ | 0.9+ |
Meta Fetcher | ? | /lua/meta/fetcher | 1.1+ |
Meta Reader | ? | /lua/meta/reader/ | 1.1+ |
Playlist Parsers | Scripts called to handle files when VLC is given a specific URL (e.g. when VLC gets http://somewebsite.com/playlist/id_string”) | /lua/playlist/ | 0.9+ |
Services Discovery | Used to generate media from a service (found on the sidebar) | /lua/sd/ | 1.1+ |
Modules
In Lua, there are special tables called Modules. VLC’s Lua Modules are available via the global vlc
table and are assigned their own symbols (e.g. vlc.config
=> configuration module). Depending on the type of script that is running, certain modules may not be available.
Name | Symbol(s) | Description | Availability |
---|---|---|---|
Configuration | config |
Access and modify VLC configuration options | Extension, Interface |
Dialog | dialog |
Create and manage a dialog window (UI) | Extension |
Equalizer | equalizer |
Access and modify equalizer settings and presets | Interface |
Errno | errno |
Error values | Extension, Interface |
GetText | gettext |
Alias for libvlc gettext | Interface, Service Discovery |
HTTPd | httpd |
HTTP Daemon | Interface |
I/O | io |
Input/Output (i.e. file read/write, directories, etc…) | Extension, Interface |
Messages | msg |
Output to the Messages console (Tools->Messages) | All types |
Miscellaneous | misc |
Uncategroized functionality | Interface |
Network | net |
Some network methods | Extension, Interface |
Objects | object |
Provides access to various objects | Extension, Interface, Meta, Service Discovery |
OSD | osd |
On-screen display functionality (ex. Display OSD messages, modify channels) | Extension, Interface |
Player | player (pre 4.0: input ) |
Access the VLC player (Called “input” pre 4.0) | Extension, Interface, Service Discovery |
Playlist | playlist |
Access and modify playlists | Extension, Interface |
Random | rand |
Get random numbers/bytes | Extension, Interface |
Renderer Discovery | rd |
? | ? |
Services Discovery | sd |
Functionality for service discovery scripts (i.e. add nodes, items) | Service Discovery |
Stream | stream , memory_stream , directory_stream |
Access to data streams and methods to read/modify them | All Types |
Strings | strings |
String utils (ex. parse URI/URL, handle special chars) | All Types |
Variables | var |
Create and manipulate variables in VLC objects | All Types |
Video | video |
VLC video interface | Extension, Interface |
VLM | vlm |
VideoLAN Manager | Extension, Interface |
Volume | volume |
Modify volume | Extension, Interface |
Windows | win |
Access to Windows console | Extension, Interface (Windows builds only) |
XML | xml |
XML reader, can be replaced by simplexml | All types |
Non-VLC Modules
Outside of the modules in the global vlc
table, VLC provides some other modules to aid in developing more complex scripts. These modules are found in VLC_INSTALL_PATH/lua/modules/ and must be explicitly imported into lua code using the built-in require function. Furthermore, any custom Lua modules placed in the lua/modules folder may also be ‘required’ in a Lua script.
require "module1" -- This works
local mod2 = require("module2") -- This also works
LUAC
LUAC is a command line tool that lets you translate Lua scripts (.lua) into binary files (.luac), which are accepted as scripts by VLC when placed in an install directory.
A more detailed description of LUAC can be found on it’s man page, but here’s a quick summary:
What LUAC does
- Precompiles Lua chunks into bytecode and saves them in a file, ensuring faster load times by saving on compilation time
- Adds resistance against small changes to a Lua program that might inadvertently change the program after it has been compiled
What LUAC does NOT do
- Create files that are necessarily smaller than the source code
- Speed up execution times or perform any optimizations that wouldn’t already be done at runtime
- Apply any encryption or obfuscation that would prevent someone from easily reverse engineering Lua programs (decompilers exist)