Documentation:Building Lua Playlist Scripts

Introduction

Starting with version 0.9.0, VLC gives you the possible to implement your own playlist loading modules easily. Such modules can do stuff like:

• URL translation: You give it the youtube webpage URL and VLC starts playing the corresponding video;
• Text playlist parsing: You use some custom text playlist format.

Lua playlist scripts shipped with VLC are stored in the following directory:

• C:\Program Files\VideoLAN\VLC\luaplaylist\ on Windows;
• VLC.app/luaplaylist/ on Mac OS X (?);
• /usr/share/vlc/luaplaylist/ on Linux.

You can add your own Lua playlist scripts in this directory or in your VLC's preferences folder "luaplaylist" subdirectory.

Simple Examples

URL translation

What we want to do

Lets say that we want VLC to open Google Video links automatically. Google Video pages have URLs like

http://video.google.com/videoplay?docid=6660281632801251601

to the URL of the corresponding Google Video Playlist file which is

http://video.google.com/videogvp?docid=6660281632801251601

Probe

The Lua script is going to be made of 2 functions. The first one is the probe() function. This function tells VLC if the Lua script should be used (function returns true) or not (function returns false). Here it would look like:

function probe()
    if vlc.access ~= "http"
    then
        return false
    end
    if string.match( vlc.path, "video.google.com/videoplay" )
    then
        return true
    else
        return false
    end
end

Lets analyse that function step by step. First we check that VLC is using HTTP. If it isn't (for example it's reading a file off your hard drive or a DVD), we don't want to trigger the Google Video URL translation. The vlc Lua object provides vlc.access which should be equal to string "http". Then we check that the URL is a Google Video page. This is easily done by trying to find the "video.google.com/videoplay" string in vlc.path.

Note that the same function can be written as

function probe()
    return vlc.access == "http" and string.match( vlc.path, "video.google.com/videoplay" )
end

Parse

If the probe() function returns true, VLC will use the parse() to ask for the new playlist item(s) which need to be added.

function parse()
    item = {}
    item.path = "http://" .. string.gsub( vlc.path, "videoplay", "videogvp" )
    item.name = "Some Google video playlist"
    return { item }
end

We create a new playlist item (a Lua table). We set the item's path to the appropriate string: 1/ we prepend "http://" since the vlc.path string doesn't include that part of the original URL and 2/ we replace "videoplay" by "videogvp".

We also set the new playlist item's name to "Some Google video playlist".

We then return the new playlist to VLC (a Lua table which basically represents a list of items).

Saving that to a file

To make that script available to VLC, simply create a new something.lua file in one of the directories listed in the introduction (You should also remove the googlevideo.lua file shipped with VLC to make sure that it isn't used instead of your new script).

Text Playlist Parsing

In the previous example we translated a URL to another URL. This new URL redirects VLC to a Google Video Playlist which is basically a text file. This file needs to be read to get the final video's true URL. Here's what such a file would look like if you were to open it with a text editor: