View source for Documentation:Building Lua Playlist Scripts

{{RightMenu|documentation play howto toc}}

== 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\lua\playlist\ on Windows;
* VLC.app/Contents/MacOS/share/lua/playlist/ on Mac OS X;
* /usr/share/vlc/lua/playlist/ on Linux.

You can add your own Lua playlist scripts in this directory or in your VLC's preferences folder "lua/playlist" 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
 <nowiki>http://video.google.com/videoplay?docid=-5784010886294950089</nowiki>
to the URL of the corresponding Google Video Playlist file which is
 <nowiki>http://video.google.com/videogvp?docid=-5784010886294950089</nowiki>

==== 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).

A shorter version would be:
 function parse()
     return { { path = "http://" .. string.gsub( vlc.path, "videoplay", "videogvp" ); name = "Some Google video playlist" } }
 end

==== 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:
<pre>
# download the free Google Video Player from http://video.google.com/
gvp_version:1.1
url:http://vp.video.google.com/videodownload?version=0&secureurl=uQAAAAznrU3q0BdxTkn_lLSpVJQ4a4JBDFAc5V8lB5OXXPqJ6Dts-Hq5Ll-2dIgeBIDGN1ZAMv65MMP0Zu5cwbIrgAhinWRNl-UtZCU4CgPpnYrR5IwLCk-sEXjs4o89dTT8MQxWcSo3lFPKulC0_TT9L0EW_IyANloBjyoEld5KGkcXdUTtXvj1TmaRh5Yvq4zIfxmYPQ4fehJY6rucnqMQLm8NTD32NvVpSp1bJ06ub_YJgDz4Nic-_qpW0rnFReSyrQ&sigh=zy8gMs8AhAM0Hv3N1PR7djz3m2I&begin=0&len=72640&docid=-5784010886294950089
docid:-5784010886294950089
duration:72640
title:Penguins go for a stroll
description:African penguins caught a breath of fresh air as they were out for a stroll through Tokyo's aquarium. Ikebukuro Sunshine Aquarium offer spectators a chance to get a closer encounter with penguins as they are taken for a walk through the aquariums compound.
description:
description:During the parade the penguins were separated from spectators, mainly children, by portable fences on wheels which were pushed by the zookeepers. The fence ensures they don't run away and also prevents them from biting spectators. 
description:
description:"I came up with this idea to let people get a close look at penguins walking." said Keeper Masahiro Tomiyama, adding only penguins born and raised at the aquarium can walk outside their cage without feeling stressed by all the attention.
description:
description:Reuters 16094/06
description:Keywords: animals, cute, sweet, funny, ITN Source.
</pre>

==== Probe ====
The first thing we need to worry about is making sure that the file we're playing is a Google Video Playlist (GVP) file. We could rely on the URL, but that would prevent playing GVP files from our hard drive. Fortunately, the file's contents, especially the "gvp_version:" string seem specific to GVP files. We'll thus try reading a bunch of characters from the begining of the file and look for the "gvp_version:" string.
 function probe()
     return string.match( vlc.probe( 512 ), "gvp_version:" )
 end

The '''vlc.probe(''' ''<number of chars>'' ''')''' function asks VLC to return the first <number of chars> characters. If the string "gvp_version:" isn't found in a file's first 512 characters, we're almost 100% sure that it's not a valid GVP file.

==== Parse ====
We now need to read information from the file to create our new playlist item. A simple version would only fetch the URL:
 function parse()
     item = {}
     while true
     do
         line = vlc.readline()
         if not line
         then
             break
         end
         if string.match( line, "^url:" )
         then
             item.path = string.sub( line, 5 )
         end
     end
     return { item }
 end

We read all the file's lines using the '''vlc.readline()''' function. If we encounter the line starting with '''"url:"''' (''string.match( line, "url:" )'' would match lines containing "url:", while ''string.match( line, "^url:" )'' only matches those starting with "url:"), we use that as our new item's path.

If vlc.readline() returns nil, this means that we've finished reading the file so we break out of the while loop and return our new playlist.

This simple '''parse()''' function unfortunately discards all the other usefull meta information available in the GVP file. Lets try to use it:
 function parse()
     item = {}
     while true
     do
         line = vlc.readline()
         if not line
         then
             break
         end
         if string.match( line, "^url:" )
         then
             item.path = string.sub( line, 5 )
         elseif string.match( line, "^title:" )
         then
             item.name = string.sub( line, 7 )
         elseif string.match( line, "^duration:" )
         then
             item.duration = string.sub( line, 10 ) / 1000
         elseif string.match( line, "^description:" )
         then
             if item.description
             then
                 item.description = item.description .. "\n" .. string.sub( line, 13 )
             else
                 item.description = string.sub( line, 13 )
             end
         end
     end
     return { item }
 end

Getting the video's title works like the URL parameter.
The duration is a bit more tricky. GVP uses times in miliseconds while VLC wants a time in seconds. We thus have to divide it by 1000.
For the description, it works like the URL and title parameters except that a GVP file can have more than one description parameter. If we read more than one parameter we thus concatenate the different description lines.

== Reference ==
=== VLC Lua playlist script ===
VLC Lua playlist modules should define two functions:
* '''probe()''': returns true if we want to handle the playlist in this script
* '''parse()''': read the incoming data and return playlist item(s)

The playlist is a table of playlist objects.
A playlist object has the following members:
* '''.path''': the item's full path / URL
* '''.name''': the item's name in playlist ''(OPTIONAL)''
* '''.title''': the item's Title ''(OPTIONAL, meta data)''
* '''.artist''': the item's Artist ''(OPTIONAL, meta data)''
* '''.genre''': the item's Genre ''(OPTIONAL, meta data)''
* '''.copyright''': the item's Copyright ''(OPTIONAL, meta data)''
* '''.album''': the item's Album ''(OPTIONAL, meta data)''
* '''.tracknum''': the item's Tracknum ''(OPTIONAL, meta data)''
* '''.description''': the item's Description ''(OPTIONAL, meta data)''
* '''.rating''': the item's Rating ''(OPTIONAL, meta data)''
* '''.date''': the item's Date ''(OPTIONAL, meta data)''
* '''.setting''': the item's Setting ''(OPTIONAL, meta data)''
* '''.url''': the item's URL ''(OPTIONAL, meta data)''
* '''.language''': the item's Language ''(OPTIONAL, meta data)''
* '''.nowplaying''': the item's NowPlaying ''(OPTIONAL, meta data)''
* '''.publisher''': the item's Publisher ''(OPTIONAL, meta data)''
* '''.encodedby''': the item's EncodedBy ''(OPTIONAL, meta data)''
* '''.arturl''': the item's ArtURL ''(OPTIONAL, meta data)''
* '''.trackid''': the item's TrackID ''(OPTIONAL, meta data)''
* '''.options''': a list of VLC options ''(OPTIONAL)'' <br/> example: .options = { "fullscreen" }
* '''.duration''': stream duration in seconds ''(OPTIONAL)''
* '''.meta''': custom meta data ''(OPTIONAL, meta data)'' <br/> A .meta field is a table of custom meta categories which each have custom meta properties. <br/> example: .meta = { ["Google video"] = { ["docid"] = "-5784010886294950089"; ["GVP version"] = "1.1" }; ["misc"] = { "Hello" = "World!" } }

Invalid playlist items will be discarded by VLC.

=== The vlc Lua object ===
VLC defines a global vlc object with the following members:
* '''vlc.path''': the URL string (without the leading http:// or file:// element)
* '''vlc.access''': the access used ("http" for <nowiki>http://,</nowiki> "file" for file://, etc.)
* '''vlc.peek(''' ''<int>'' ''')''': return the first <int> characters from the playlist file.
* '''vlc.read(''' ''<int>'' ''')''': read <int> characters from the playlist file. '''THIS FUNCTION CANNOT BE USED IN peek().'''
* '''vlc.readline()''': return a new line of playlist data on each call. '''THIS FUNCTION CANNOT BE USED IN peek().'''
* '''vlc.decode_uri(''' ''<string>'' ''')''': decode %xy characters in a string.
* '''vlc.resolve_xml_special_chars(''' ''<string>'' ''')''': decode &abc; characters in a string.
* '''vlc.msg_dbg(''' ''<string>'' ''')''': print a debug message.
* '''vlc.msg_warn(''' ''<string>'' ''')''': print a warning message.
* '''vlc.msg_err(''' ''<string>'' ''')''': print an error message.
* '''vlc.msg_info(''' ''<string>'' ''')''': print an info message.

== Scripts shipped with VLC ==

Scripts for popular playlist formats and video websites are available in the default VLC installer:
* dailymotion.lua: URL translation for Daily Motion video pages;
* googlevideo.lua: URL translation for Google Video video pages;
* metacafe.lua: URL translation for metacafe video pages and flash player;
* youtube.lua: URL translation for YouTube video pages and flash player (including fullscreen video URLs);
* youtube_hompage.lua: Parse YouTube homepage and browse page.


== Usefull links ==
* [http://www.lua.org/manual/5.1/ Lua 5.1 reference manual]
* [http://lua-users.org/wiki/TutorialDirectory Lua tutorials]