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.

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

What LUAC does NOT do