VideoLAN Wiki - User contributions [en]

Documentation:Building Lua Playlist Scripts

2023-06-06T10:36:01Z

Nhumfrey: Deleted lua scripts that don't exist anymore and added hyperlinks to source code

{{Example code}}
{{RightMenu|Documentation 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 on Windows or Mac OS X and in your local VLC shared data folder on Linux (~/.local/share/vlc/lua/playlist).

== Simple Examples ==

=== URL translation ===

==== What we want to do ====
Let's 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:
<syntaxhighlight lang="lua">
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
</syntaxhighlight>

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
<syntaxhighlight lang="lua">
function probe()
return vlc.access == "http" and string.match( vlc.path, "video.google.com/videoplay" )
end
</syntaxhighlight>

==== 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.
<syntaxhighlight lang="lua">
function parse()
item = {}
item.path = "http://" .. string.gsub( vlc.path, "videoplay", "videogvp" )
item.name = "Some Google video playlist"
return { item }
end
</syntaxhighlight>

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:
<syntaxhighlight lang="lua">
function parse()
return { { path = "http://" .. string.gsub( vlc.path, "videoplay", "videogvp" ); name = "Some Google video playlist" } }
end
</syntaxhighlight>

==== 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 beginning of the file and look for the "gvp_version:" string.
<syntaxhighlight lang="lua">
function probe()
return string.match( vlc.peek( 512 ), "gvp_version:" )
end
</syntaxhighlight>

The '''vlc.peek(''' ''<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:
<syntaxhighlight lang="lua">
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
</syntaxhighlight>

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 useful meta information available in the GVP file. Lets try to use it:
<syntaxhighlight lang="lua">
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
</syntaxhighlight>

Getting the video's title works like the URL parameter.
The duration is a bit more tricky. GVP uses times in milliseconds 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 ==

Information about the VLC Lua scripts is available in your VLC installation in the lua subdirectory.

* [https://code.videolan.org/videolan/vlc/-/blob/master/share/lua/README.txt Global VLC Lua README]
* [https://code.videolan.org/videolan/vlc/-/blob/master/share/lua/playlist/README.txt Playlist script specific README]

== Scripts shipped with VLC ==

Scripts for popular playlist formats and video websites are available in the default VLC installer:
* [https://code.videolan.org/videolan/vlc/-/blob/master/share/lua/playlist/dailymotion.lua dailymotion.lua]: URL translation for Daily Motion video pages;
* [https://code.videolan.org/videolan/vlc/-/blob/master/share/lua/playlist/metacafe.lua metacafe.lua]: URL translation for metacafe video pages and flash player;
* [https://code.videolan.org/videolan/vlc/-/blob/master/share/lua/playlist/vimeo.lua vimeo.lua]: URL translation for Vimeo video pages;
* [https://code.videolan.org/videolan/vlc/-/blob/master/share/lua/playlist/youtube.lua youtube.lua]: URL translation for YouTube video pages and flash player (including fullscreen video URLs);

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

{{Documentation}}

[[Category:Playlist]]

Documentation:Building Lua Playlist Scripts

2023-06-06T10:32:42Z

Nhumfrey: Fixed links to README.txt files

{{Example code}}
{{RightMenu|Documentation 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 on Windows or Mac OS X and in your local VLC shared data folder on Linux (~/.local/share/vlc/lua/playlist).

== Simple Examples ==

=== URL translation ===

==== What we want to do ====
Let's 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:
<syntaxhighlight lang="lua">
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
</syntaxhighlight>

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
<syntaxhighlight lang="lua">
function probe()
return vlc.access == "http" and string.match( vlc.path, "video.google.com/videoplay" )
end
</syntaxhighlight>

==== 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.
<syntaxhighlight lang="lua">
function parse()
item = {}
item.path = "http://" .. string.gsub( vlc.path, "videoplay", "videogvp" )
item.name = "Some Google video playlist"
return { item }
end
</syntaxhighlight>

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:
<syntaxhighlight lang="lua">
function parse()
return { { path = "http://" .. string.gsub( vlc.path, "videoplay", "videogvp" ); name = "Some Google video playlist" } }
end
</syntaxhighlight>

==== 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 beginning of the file and look for the "gvp_version:" string.
<syntaxhighlight lang="lua">
function probe()
return string.match( vlc.peek( 512 ), "gvp_version:" )
end
</syntaxhighlight>

The '''vlc.peek(''' ''<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:
<syntaxhighlight lang="lua">
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
</syntaxhighlight>

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 useful meta information available in the GVP file. Lets try to use it:
<syntaxhighlight lang="lua">
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
</syntaxhighlight>

Getting the video's title works like the URL parameter.
The duration is a bit more tricky. GVP uses times in milliseconds 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 ==

Information about the VLC Lua scripts is available in your VLC installation in the lua subdirectory.

* [https://code.videolan.org/videolan/vlc/-/blob/master/share/lua/README.txt Global VLC Lua README]
* [https://code.videolan.org/videolan/vlc/-/blob/master/share/lua/playlist/README.txt Playlist script specific README]

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

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

{{Documentation}}

[[Category:Playlist]]

Documentation:Modules/mqtt

2014-05-05T10:31:09Z

Nhumfrey: Restructured as a table of commands and responses

'''NOTE: this module is in active development and has not made it into the main tree yet.'''

{{Module|name=mqtt|type=Interface|os=Any that support the [http://mosquitto.org/ mosquitto] library|description=control VLC using the MQTT protocol}}

This module will let you send control messages to VLC using the [http://www.mqtt.org/ MQTT] protocol.

== Options ==
{{Option
|name=mqtt-host
|value=string
|default=localhost
|description=Hostname of MQTT broker to connect to
}}
{{Option
|name=mqtt-port
|value=integer
|default=1883
|description=Port number of MQTT broker to connect to
}}
{{Option
|name=mqtt-username
|value=string
|default=none
|description=The username to connect to the broker with
}}
{{Option
|name=mqtt-password
|value=string
|default=none
|description=The password to connect to the broker with
}}
{{Option
|name=mqtt-prefix
|value=string
|default=vlc/
|description=The topic name prefix to use
}}
{{Option
|name=mqtt-clientid
|value=string
|default=random
|description=The client identifier to connect to the broker as
}}
{{Option
|name=mqtt-keepalive
|value=string
|default=10
|description=The keep alive time for the MQTT protocol (in seconds)
}}
{{Option
|name=mqtt-qos
|value=string
|default=1
|description=The QoS level to publish and subscribe using (0, 1 or 2)
}}

== Protocol ==

=== Commands ===

Sent from client to VLC.

{| class="wikitable"
|-
! Direction !! Topic !! Payload !! Description
|-
| <big>→</big> || vlc/command || <cmd> <arguments> || Any of the below
|-
| <big>→</big> || vlc/command/add || <url> || Add <url> to the playlist
|-
| <big>→</big> || vlc/command/delete || <pos> || delete item <pos> in playlist
|-
| <big>→</big> || vlc/command/clear || || clear the playlist
|-
| <big>→</big> || vlc/command/play || <pos> || Start playing item at <pos>
|-
| <big>→</big> || vlc/command/pause || || Pause Playback
|-
| <big>→</big> || vlc/command/stop || || Stop Playback
|-
| <big>→</big> || vlc/command/goto || <pos> || Goto item at index <pos>
|-
| <big>→</big> || vlc/command/next || || Start playing next item in playlist
|-
| <big>→</big> || vlc/command/prev || || Start playing prev item in playlist
|-
| <big>→</big> || vlc/command/seek || <time> || Seek to <time> in the current item (in seconds)
|-
| <big>→</big> || vlc/command/volume || <vol> || Set volume to <vol> (0 to 255)
|-
| <big>→</big> || vlc/command/volup || <vol> || Increase volume by <vol>
|-
| <big>→</big> || vlc/command/voldown || <vol> || Decrease volume by <vol>
|-
| <big>→</big> || vlc/command/repeat || <mode> || Turn on or off playlist ''repeat'' mode (0 or 1)
|-
| <big>→</big> || vlc/command/random || <mode> || Turn on or off playlist ''random'' mode (0 or 1)
|-
| <big>→</big> || vlc/command/loop || <mode> || Turn on or off playlist ''loop'' mode (0 or 1)
|-
|}

=== Status ===

Sent from VLC to client.

{| class="wikitable"
|-
! Direction !! Topic !! Payload !! Description
|-
| <big>←</big> || vlc/status/playlist || <json> || A JSON representation of the playlist is sent whenever the playlist changes.
|-
| <big>←</big> || vlc/status/state || <state> || This retained message is sent by VLC whenever the player changes state:
* opening
* buffering
* playing
* paused
* stopped
* ended
* error
* notconnected
|-
| <big>←</big> || vlc/status/playing || <json> || Information about the currently playing item as JSON is sent whenever a new item starts playing.
|-
| <big>←</big> || vlc/status/time || <time> || Progress through the current stream as decimal seconds
|-
| <big>←</big> || vlc/status/length || <time> || Duration of current stream as decimal seconds
|-
| <big>←</big> || vlc/status/volume || <vol> || The current volume between 0 and 255 (inclusive)
|}

[[Category:Interfaces]]

Documentation:Modules/mqtt

2014-05-04T21:08:19Z

Nhumfrey: /* Options */

'''NOTE: this module is in active development and has not made it into the main tree yet.'''

{{Module|name=mqtt|type=Interface|os=Any that support the [http://mosquitto.org/ mosquitto] library|description=control VLC using the MQTT protocol}}

This module will let you send control messages to VLC using the [http://www.mqtt.org/ MQTT] protocol.

== Options ==
{{Option
|name=mqtt-host
|value=string
|default=localhost
|description=Hostname of MQTT broker to connect to
}}
{{Option
|name=mqtt-port
|value=integer
|default=1883
|description=Port number of MQTT broker to connect to
}}
{{Option
|name=mqtt-username
|value=string
|default=none
|description=The username to connect to the broker with
}}
{{Option
|name=mqtt-password
|value=string
|default=none
|description=The password to connect to the broker with
}}
{{Option
|name=mqtt-prefix
|value=string
|default=vlc/
|description=The topic name prefix to use
}}
{{Option
|name=mqtt-clientid
|value=string
|default=random
|description=The client identifier to connect to the broker as
}}
{{Option
|name=mqtt-keepalive
|value=string
|default=10
|description=The keep alive time for the MQTT protocol (in seconds)
}}
{{Option
|name=mqtt-qos
|value=string
|default=1
|description=The QoS level to publish and subscribe using (0, 1 or 2)
}}

== Protocol ==

<big>→</big> : From client to VLC 
<big>←</big> : From VLC to client 

=== → vlc/command <cmd> <arguments> ===
The following commands are accepted:
:{|
|-
| '''add''' || <uri> || add <uri> to playlist
|-
| '''delete''' || <pos> || delete item <pos> in playlist
|-
| '''clear''' || || clear the playlist
|-
| '''play''' || <pos> || Start playing item <num>
|-
| '''pause''' || || Pause playback
|-
| '''stop''' || || Stop stream
|-
| '''goto''' || <pos> || Goto item at index
|-
| '''next''' || || Start playing next item in playlist
|-
| '''prev''' || || Start playing previous item in playlist
|-
| '''seek''' || <time> || Seek to <time> in the current item (in seconds)
|-
| '''volume''' || <volume> || Set volume to <volume> (0 to 255)
|-
| '''volup''' || <volume> || Increase volume by <volume>
|-
| '''voldown''' || <volume> || Descrease volume by <volume>
|-
| '''repeat''' || <mode> || Turn on or off playlist repeat mode (0 or 1)
|-
| '''random''' || <mode> || Turn on or off playlist random/shuffle mode (0 or 1)
|-
| '''loop''' || <mode> || Turn on or off playlist loop mode (0 or 1)
|-
|}

=== ← vlc/status/playlist ===
A JSON representation of the playlist is sent whenever the playlist changes.

=== ← vlc/status/state ===
This retained message is sent by VLC whenever the player changes state.
:{|
|-
| '''opening''' ||
|-
| '''buffering''' ||
|-
| '''playing''' ||
|-
| '''paused''' ||
|-
| '''stopped''' ||
|-
| '''ended''' ||
|-
| '''error''' ||
|-
| '''notconnected''' || sent when VLC disconnects from the broker
|-
|}

=== ← vlc/status/playing ===
Information about the currently playing item as JSON is sent whenever a new item starts playing.

=== ← vlc/status/time ===
Progress through the current stream as decimal seconds

=== ← vlc/status/length ===
Duration of current stream as decimal seconds

=== ← vlc/status/volume ===
The current volume between 0 and 255 (inclusive)

[[Category:Interfaces]]

Documentation:Modules/mqtt

2014-05-04T20:51:43Z

Nhumfrey: /* → vlc/command */

'''NOTE: this module is in active development and has not made it into the main tree yet.'''

{{Module|name=mqtt|type=Interface|os=Any that support the [http://mosquitto.org/ mosquitto] library|description=control VLC using the MQTT protocol}}

This module will let you send control messages to VLC using the [http://www.mqtt.org/ MQTT] protocol.

== Options ==
{{Option
|name=mqtt-host
|value=string
|default=localhost
|description=Hostname of MQTT broker to connect to
}}
{{Option
|name=mqtt-port
|value=integer
|default=1883
|description=Port number of MQTT broker to connect to
}}
{{Option
|name=mqtt-prefix
|value=string
|default=vlc/
|description=The topic name prefix to use
}}

== Protocol ==

<big>→</big> : From client to VLC 
<big>←</big> : From VLC to client 

=== → vlc/command <cmd> <arguments> ===
The following commands are accepted:
:{|
|-
| '''add''' || <uri> || add <uri> to playlist
|-
| '''delete''' || <pos> || delete item <pos> in playlist
|-
| '''clear''' || || clear the playlist
|-
| '''play''' || <pos> || Start playing item <num>
|-
| '''pause''' || || Pause playback
|-
| '''stop''' || || Stop stream
|-
| '''goto''' || <pos> || Goto item at index
|-
| '''next''' || || Start playing next item in playlist
|-
| '''prev''' || || Start playing previous item in playlist
|-
| '''seek''' || <time> || Seek to <time> in the current item (in seconds)
|-
| '''volume''' || <volume> || Set volume to <volume> (0 to 255)
|-
| '''volup''' || <volume> || Increase volume by <volume>
|-
| '''voldown''' || <volume> || Descrease volume by <volume>
|-
| '''repeat''' || <mode> || Turn on or off playlist repeat mode (0 or 1)
|-
| '''random''' || <mode> || Turn on or off playlist random/shuffle mode (0 or 1)
|-
| '''loop''' || <mode> || Turn on or off playlist loop mode (0 or 1)
|-
|}

=== ← vlc/status/playlist ===
A JSON representation of the playlist is sent whenever the playlist changes.

=== ← vlc/status/state ===
This retained message is sent by VLC whenever the player changes state.
:{|
|-
| '''opening''' ||
|-
| '''buffering''' ||
|-
| '''playing''' ||
|-
| '''paused''' ||
|-
| '''stopped''' ||
|-
| '''ended''' ||
|-
| '''error''' ||
|-
| '''notconnected''' || sent when VLC disconnects from the broker
|-
|}

=== ← vlc/status/playing ===
Information about the currently playing item as JSON is sent whenever a new item starts playing.

=== ← vlc/status/time ===
Progress through the current stream as decimal seconds

=== ← vlc/status/length ===
Duration of current stream as decimal seconds

=== ← vlc/status/volume ===
The current volume between 0 and 255 (inclusive)

[[Category:Interfaces]]

Documentation:Modules/mqtt

2014-05-04T20:43:48Z

Nhumfrey:

Documentation:Modules/mqtt

2014-05-04T20:18:27Z

Nhumfrey: /* ← vlc/status/state */

Documentation:Modules/mqtt

2014-05-04T18:59:08Z

Nhumfrey:

Documentation:Modules/osc

2014-04-12T09:37:22Z

Nhumfrey:

'''NOTE: this module is was never merged into the main VLC codebase and work on it has stopped'''

* Patch against VLC 0.9.9a: http://www.aelius.com/njh/tmp/vlc-0.9.9a+osc.patch
* Patch against VLC 0.9.8a: http://www.aelius.com/njh/tmp/vlc-0.9.8a+osc.patch
* Patch against GIT master: http://www.aelius.com/njh/tmp/vlc-git+liblo.patch

Documentation:Modules/mqtt

2014-04-12T09:33:02Z

Nhumfrey:

Documentation:Modules/mqtt

2014-04-10T23:58:25Z

Nhumfrey: /* Options */

Documentation:Modules/mqtt

2014-04-10T23:57:36Z

Nhumfrey: Created page with "'''NOTE: this module is in active development and has not made it into the main tree yet.''' {{Module|name=mqtt|type=Interface|os=Any that support the [http://mosquitto.org/ ..."

Documentation:Modules/osc

2009-04-11T21:12:32Z

Nhumfrey: Added patch for 0.9.9a

'''NOTE: this module is currently in development and has not made it into the main tree yet.'''
* Patch against VLC 0.9.9a: http://www.aelius.com/njh/tmp/vlc-0.9.9a+osc.patch
* Patch against VLC 0.9.8a: http://www.aelius.com/njh/tmp/vlc-0.9.8a+osc.patch
* Patch against GIT master: http://www.aelius.com/njh/tmp/vlc-git+liblo.patch

{{Module|name=osc|type=Interface|os=Any that support the [http://liblo.sf.net/ liblo] library|description=control VLC using the Open Sound Control protocol}}

This module lets you send control messages to VLC using the [http://www.opensoundcontrol.org/ Open Sound Control] protocol.

The following methods are currently supported:
<pre>
→ /deck/play - Start playback
→ /deck/pause - Pause playback
→ /deck/stop - Stop playback
→ /deck/eject - Eject (stops and clears the playlist)
→ /deck/load (s) - Load <mrl>
</pre>

NOTE: These paths are designed to be compatible with [http://www.aelius.com/njh/madjack/ MadJACK] and are subject to change. They treat VLC as a single track player and playlist functionality isn't currently supported.

== Options ==
{{Option
|name=osc-port
|value=integer
|default=randomly allocated port number
|description=Port number to listen on
}}

== Example ==

Start VLC with the OSC control interface loaded:
<pre>$ vlc -I dummy --control osc --osc-port 4444
VLC media player 1.0.0-git Goldeneye
[00000001] main libvlc debug: VLC media player - version 1.0.0-git Goldeneye - (c) 1996-2008 the VideoLAN team
[00000001] main libvlc debug: translation test: code is "C"
[00000287] osc interface: Listening for OSC messages on: osc.udp://127.0.0.1:4444/
[00000293] dummy interface: using the dummy interface module...
</pre>

Load a track:
<pre>$ oscsend 127.0.0.1 4444 /deck/load 's' /Users/njh/Music/003820.mp3</pre>

Start the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/play</pre>

Stop the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/stop</pre>

[[Category:Interfaces]]

Documentation:Modules/osc

2008-12-26T17:00:05Z

Nhumfrey: They are methods, not commands

'''NOTE: this module is currently in development and has not made it into the main tree yet.'''
* Patch against VLC 0.9.8a: http://www.aelius.com/njh/tmp/vlc-0.9.8a+osc.patch
* Patch against GIT master: http://www.aelius.com/njh/tmp/vlc-git+liblo.patch

{{Module|name=osc|type=Interface|os=Any that support the [http://liblo.sf.net/ liblo] library|description=control VLC using the Open Sound Control protocol}}

This module lets you send control messages to VLC using the [http://www.opensoundcontrol.org/ Open Sound Control] protocol.

The following methods are currently supported:
<pre>
→ /deck/play - Start playback
→ /deck/pause - Pause playback
→ /deck/stop - Stop playback
→ /deck/eject - Eject (stops and clears the playlist)
→ /deck/load (s) - Load <mrl>
</pre>

NOTE: These paths are designed to be compatible with [http://www.aelius.com/njh/madjack/ MadJACK] and are subject to change. They treat VLC as a single track player and playlist functionality isn't currently supported.

== Options ==
{{Option
|name=osc-port
|value=integer
|default=randomly allocated port number
|description=Port number to listen on
}}

== Example ==

Start VLC with the OSC control interface loaded:
<pre>$ vlc -I dummy --control osc --osc-port 4444
VLC media player 1.0.0-git Goldeneye
[00000001] main libvlc debug: VLC media player - version 1.0.0-git Goldeneye - (c) 1996-2008 the VideoLAN team
[00000001] main libvlc debug: translation test: code is "C"
[00000287] osc interface: Listening for OSC messages on: osc.udp://127.0.0.1:4444/
[00000293] dummy interface: using the dummy interface module...
</pre>

Load a track:
<pre>$ oscsend 127.0.0.1 4444 /deck/load 's' /Users/njh/Music/003820.mp3</pre>

Start the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/play</pre>

Stop the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/stop</pre>

[[Category:Interfaces]]

Documentation:Modules/osc

2008-12-24T16:51:37Z

Nhumfrey:

'''NOTE: this module is currently in development and has not made it into the main tree yet.'''
* Patch against VLC 0.9.8a: http://www.aelius.com/njh/tmp/vlc-0.9.8a+osc.patch
* Patch against GIT master: http://www.aelius.com/njh/tmp/vlc-git+liblo.patch

{{Module|name=osc|type=Interface|os=Any that support the [http://liblo.sf.net/ liblo] library|description=control VLC using the Open Sound Control protocol}}

This module lets you send control messages to VLC using the [http://www.opensoundcontrol.org/ Open Sound Control] protocol.

The following commands are currently supported:
<pre>
→ /deck/play - Start playback
→ /deck/pause - Pause playback
→ /deck/stop - Stop playback
→ /deck/eject - Eject (stops and clears the playlist)
→ /deck/load (s) - Load <mrl>
</pre>

NOTE: These paths are designed to be compatible with [http://www.aelius.com/njh/madjack/ MadJACK] and are subject to change. They treat VLC as a single track player and playlist functionality isn't currently supported.

== Options ==
{{Option
|name=osc-port
|value=integer
|default=randomly allocated port number
|description=Port number to listen on
}}

== Example ==

Start VLC with the OSC control interface loaded:
<pre>$ vlc -I dummy --control osc --osc-port 4444
VLC media player 1.0.0-git Goldeneye
[00000001] main libvlc debug: VLC media player - version 1.0.0-git Goldeneye - (c) 1996-2008 the VideoLAN team
[00000001] main libvlc debug: translation test: code is "C"
[00000287] osc interface: Listening for OSC messages on: osc.udp://127.0.0.1:4444/
[00000293] dummy interface: using the dummy interface module...
</pre>

Load a track:
<pre>$ oscsend 127.0.0.1 4444 /deck/load 's' /Users/njh/Music/003820.mp3</pre>

Start the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/play</pre>

Stop the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/stop</pre>

[[Category:Interfaces]]

Documentation:Modules/osc

2008-12-24T01:14:58Z

Nhumfrey: Added links to patches

'''NOTE: this module is currently in development and has not made it into the main tree yet.'''
* Patch against VLC 0.9.8a: http://www.aelius.com/njh/tmp/vlc-0.9.8a+osc.patch
* Patch against GIT master: http://www.aelius.com/njh/tmp/vlc-git+liblo.patch

{{Module|name=osc|type=Interface|os=Any that support the [http://liblo.sf.net/ liblo] library|description=control VLC using the Open Sound Control protocol}}

This module lets you send control messages to VLC using the [http://www.opensourcecontrol.org/ Open Sound Control] protocol.

The following commands are currently supported:
<pre>
→ /deck/play - Start playback
→ /deck/pause - Pause playback
→ /deck/stop - Stop playback
→ /deck/eject - Eject (stops and clears the playlist)
→ /deck/load (s) - Load <mrl> (stops and clears the playlist first)
</pre>

NOTE: These paths are designed to be compatible with [http://www.aelius.com/njh/madjack/ MadJACK] and are subject to change. They treat VLC as a single track player and playlist functionality isn't currently supported.

== Options ==
{{Option
|name=osc-port
|value=integer
|default=randomly allocated port number
|description=Port number to listen on
}}

== Example ==

Start VLC with the OSC control interface loaded:
<pre>$ vlc -I dummy --control osc --osc-port 4444
VLC media player 1.0.0-git Goldeneye
[00000001] main libvlc debug: VLC media player - version 1.0.0-git Goldeneye - (c) 1996-2008 the VideoLAN team
[00000001] main libvlc debug: translation test: code is "C"
[00000287] osc interface: Listening for OSC messages on: osc.udp://127.0.0.1:4444/
[00000293] dummy interface: using the dummy interface module...
</pre>

Load a track:
<pre>$ oscsend 127.0.0.1 4444 /deck/load 's' /Users/njh/Music/003820.mp3</pre>

Start the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/play</pre>

Stop the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/stop</pre>

[[Category:Interfaces]]

Documentation:Modules/osc

2008-12-20T22:53:01Z

Nhumfrey: NOTE: this module is currently in development and has not made it into the main tree yet.

'''NOTE: this module is currently in development and has not made it into the main tree yet.'''

{{Module|name=osc|type=Interface|os=Any that support the [http://liblo.sf.net/ liblo] library|description=control VLC using the Open Sound Control protocol}}

This module lets you send control messages to VLC using the [http://www.opensourcecontrol.org/ Open Sound Control] protocol.

The following commands are currently supported:
<pre>
→ /deck/play - Start playback
→ /deck/pause - Pause playback
→ /deck/stop - Stop playback
→ /deck/eject - Eject (stops and clears the playlist)
→ /deck/load (s) - Load <mrl> (stops and clears the playlist first)
</pre>

NOTE: These paths are designed to be compatible with [http://www.aelius.com/njh/madjack/ MadJACK] and are subject to change. They treat VLC as a single track player and playlist functionality isn't currently supported.

== Options ==
{{Option
|name=osc-port
|value=integer
|default=randomly allocated port number
|description=Port number to listen on
}}

== Example ==

Start VLC with the OSC control interface loaded:
<pre>$ vlc -I dummy --control osc --osc-port 4444
VLC media player 1.0.0-git Goldeneye
[00000001] main libvlc debug: VLC media player - version 1.0.0-git Goldeneye - (c) 1996-2008 the VideoLAN team
[00000001] main libvlc debug: translation test: code is "C"
[00000287] osc interface: Listening for OSC messages on: osc.udp://127.0.0.1:4444/
[00000293] dummy interface: using the dummy interface module...
</pre>

Load a track:
<pre>$ oscsend 127.0.0.1 4444 /deck/load 's' /Users/njh/Music/003820.mp3</pre>

Start the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/play</pre>

Stop the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/stop</pre>

[[Category:Interfaces]]

Documentation:Modules/osc

2008-12-14T20:40:45Z

Nhumfrey: Added to the Interfaces category

{{Module|name=osc|type=Interface|os=Any that support the [http://liblo.sf.net/ liblo] library|description=control VLC using the Open Sound Control protocol}}

This module lets you send control messages to VLC using the [http://www.opensourcecontrol.org/ Open Sound Control] protocol.

The following commands are currently supported:
<pre>
→ /deck/play - Start playback
→ /deck/pause - Pause playback
→ /deck/stop - Stop playback
→ /deck/eject - Eject (stops and clears the playlist)
→ /deck/load (s) - Load <mrl> (stops and clears the playlist first)
</pre>

NOTE: These paths are designed to be compatible with [http://www.aelius.com/njh/madjack/ MadJACK] and are subject to change. They treat VLC as a single track player and playlist functionality isn't currently supported.

== Options ==
{{Option
|name=osc-port
|value=integer
|default=randomly allocated port number
|description=Port number to listen on
}}

== Example ==

Start VLC with the OSC control interface loaded:
<pre>$ vlc -I dummy --control osc --osc-port 4444
VLC media player 1.0.0-git Goldeneye
[00000001] main libvlc debug: VLC media player - version 1.0.0-git Goldeneye - (c) 1996-2008 the VideoLAN team
[00000001] main libvlc debug: translation test: code is "C"
[00000287] osc interface: Listening for OSC messages on: osc.udp://127.0.0.1:4444/
[00000293] dummy interface: using the dummy interface module...
</pre>

Load a track:
<pre>$ oscsend 127.0.0.1 4444 /deck/load 's' /Users/njh/Music/003820.mp3</pre>

Start the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/play</pre>

Stop the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/stop</pre>

[[Category:Interfaces]]

Documentation:Modules/osc

2008-12-13T23:26:04Z

Nhumfrey: changed version number in 'screenshot'

{{Module|name=osc|type=Interface|os=Any that support the [http://liblo.sf.net/ liblo] library|description=control VLC using the Open Sound Control protocol}}

This module lets you send control messages to VLC using the [http://www.opensourcecontrol.org/ Open Sound Control] protocol.

The following commands are currently supported:
<pre>
→ /deck/play - Start playback
→ /deck/pause - Pause playback
→ /deck/stop - Stop playback
→ /deck/eject - Eject (stops and clears the playlist)
→ /deck/load (s) - Load <mrl> (stops and clears the playlist first)
</pre>

NOTE: These paths are designed to be compatible with [http://www.aelius.com/njh/madjack/ MadJACK] and are subject to change. They treat VLC as a single track player and playlist functionality isn't currently supported.

== Options ==
{{Option
|name=osc-port
|value=integer
|default=randomly allocated port number
|description=Port number to listen on
}}

== Example ==

Start VLC with the OSC control interface loaded:
<pre>$ vlc -I dummy --control osc --osc-port 4444
VLC media player 1.0.0-git Goldeneye
[00000001] main libvlc debug: VLC media player - version 1.0.0-git Goldeneye - (c) 1996-2008 the VideoLAN team
[00000001] main libvlc debug: translation test: code is "C"
[00000287] osc interface: Listening for OSC messages on: osc.udp://vmware.aelius.co.uk:4444/
[00000293] dummy interface: using the dummy interface module...
</pre>

Load a track:
<pre>$ oscsend 127.0.0.1 4444 /deck/load 's' /Users/njh/Music/003820.mp3</pre>

Start the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/play</pre>

Stop the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/stop</pre>

Documentation:Modules/osc

2008-12-13T20:48:23Z

Nhumfrey: Added example

{{Module|name=osc|type=Interface|os=Any that support the [http://liblo.sf.net/ liblo] library|description=control VLC using the Open Sound Control protocol}}

This module lets you send control messages to VLC using the [http://www.opensourcecontrol.org/ Open Sound Control] protocol.

The following commands are currently supported:
<pre>
→ /deck/play - Start playback
→ /deck/pause - Pause playback
→ /deck/stop - Stop playback
→ /deck/eject - Eject (stops and clears the playlist)
→ /deck/load (s) - Load <mrl> (stops and clears the playlist first)
</pre>

NOTE: These paths are designed to be compatible with [http://www.aelius.com/njh/madjack/ MadJACK] and are subject to change. They treat VLC as a single track player and playlist functionality isn't currently supported.

== Options ==
{{Option
|name=osc-port
|value=integer
|default=randomly allocated port number
|description=Port number to listen on
}}

== Example ==

Start VLC with the OSC control interface loaded:
<pre>$ vlc -I dummy --control osc --osc-port 4444
VLC media player 0.9.8a Grishenko
[00000001] main libvlc debug: VLC media player - version 0.9.8a Grishenko - (c) 1996-2008 the VideoLAN team
[00000001] main libvlc debug: translation test: code is "C"
[00000287] osc interface: Listening for OSC messages on: osc.udp://vmware.aelius.co.uk:4444/
[00000293] dummy interface: using the dummy interface module...
</pre>

Load a track:
<pre>$ oscsend 127.0.0.1 4444 /deck/load 's' /Users/njh/Music/003820.mp3</pre>

Start the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/play</pre>

Stop the track playing:
<pre>$ oscsend 127.0.0.1 4444 /deck/stop</pre>

Documentation:Modules/lirc

2008-12-13T18:10:34Z

Nhumfrey: New page: {{Module|name=lirc|type=Interface|os=Any that supports [http://www.lirc.org/ lirc] library|description=Infrared remote control interface}} This module lets you control VLC using your infr...

{{Module|name=lirc|type=Interface|os=Any that supports [http://www.lirc.org/ lirc] library|description=Infrared remote control interface}}

This module lets you control VLC using your infrared remote control using lirc.

== Options ==
{{Option
|name=lirc-file
|value=string
|description=Tell lirc to read this configuration file. By default it searches in the users home directory.
}}

Documentation:Modules/osc

2008-12-13T17:01:35Z

Nhumfrey: Changed type from Control to Interface

Documentation:Modules/rc

2008-12-13T17:00:38Z

Nhumfrey:

{{Module|name=rc|type=Interface|description=Text based command interface}}

== Introduction ==
The remote control interface (rc for short) is one of the three console interfaces provided by VLC. The other two being [[Documentation:Modules/ncurses|ncurses]] and [[Documentation:Modules/telnet|telnet]].

To force VLC into using this interface, do the following:

vlc -I rc

This interface is operated through textual commands typed into the invoking terminal window.

This is the default interface if no GUI environment is available.

== Command reference ==
Type <tt>help</tt> followed by enter for a terse list of commands or <tt>longhelp</tt> for the complete list.



== Command line options ==
There are several options you can use in conjunction with the rc interface:

{|
| '''Option'''
| '''Description'''
| '''Enabled by default'''
|-
| <tt>--rc-show-pos</tt>
| Show stream position
| No
|-
| <tt>--no-rc-show-pos</tt>
| Show the current position in seconds within the stream from time to time.
| No
|-
| <tt>--rc-fake-tty</tt>
| Fake TTY
| No
|-
| <tt>--no-rc-fake-tty</tt>
| Force the rc module to use stdin as if it was a TTY.
| No
|-
| <tt>--rc-unix=<string></tt>
| UNIX socket command input. Accept commands over a Unix socket rather than stdin.
| <nowiki>-</nowiki>
|-
| <tt>--rc-host=<string></tt>
| TCP command input. Accept commands over a socket rather than stdin. You can set the address and port the interface will bind to.
| <nowiki>-</nowiki>
|-
| <tt>--rc-quiet</tt>
| Do not open a DOS command box interface
|-
| <tt>--no-rc-quiet</tt>
| By default the rc interface plugin will start a DOS command box. Enabling the quiet mode will not bring this command box but can also be pretty annoying when you want to stop VLC and no video window is open.
| No
|}

To get this list run
vlc -p rc --advanced --help-verbose

== Miscellaneous ==
Starting with VLC 0.8.0 you can access this interface through a network with a telnet-client by using the <tt>--rc-host localhost:port</tt> option.

Documentation:Modules/osc

2008-12-13T16:58:40Z

Nhumfrey: Added OSC interface module page

{{Module|name=osc|type=Control|os=Any that support the [http://liblo.sf.net/ liblo] library|description=control VLC using the Open Sound Control protocol}}

This module lets you send control messages to VLC using the [http://www.opensourcecontrol.org/ Open Sound Control] protocol.

The following commands are currently supported:
<pre>
→ /deck/play - Start deck playing
→ /deck/pause - Pause deck
→ /deck/stop - Stop Deck playback
→ /deck/eject - Eject the current track from deck
→ /deck/load (s) - Load <mrl> into deck
→ /deck/volume (i) - Load <filename> into deck
</pre>

NOTE: These paths are designed to be compatible with [http://www.aelius.com/njh/madjack/ MadJACK] but are subject to change.

== Options ==
{{Option
|name=osc-port
|value=integer
|default=randomly allocated port number
|description=Port number to listen on
}}

Documentation:Modules

2008-12-13T16:57:53Z

Nhumfrey: Put OSC in the wrong interfaces section

__NOTOC__

This page lists most of the modules present in the official VLC source code. Understanding these pages might require that you know about VLC and its command line usage. It is recommended that you read the other [[Documentation:Documentation|documentation]] first.

To list all the available modules in your VLC build, use:
% '''vlc --list'''

To list a module's configuration options, use:
% '''vlc -p <modulename> --advanced --help-verbose'''

== Interfaces ==

=== Graphical ===

*[[Documentation:Modules/wxWidgets|wxWidgets]]
*[[Documentation:Modules/skins2|Skins2]]
*[[Documentation:Modules/Qt4|Qt4]]
*[[Documentation:Modules/macosx_gui|Mac OS X]]
*[[Documentation:Modules/beos_gui|BeOS]]
*[[Documentation:Modules/wince|Windows CE]]

=== Text ===

*[[Documentation:Modules/rc|remote control (rc)]]
*[[Documentation:Modules/telnet|telnet]]
*[[Documentation:Modules/ncurses|ncurses]]

=== Other ===

*[[Documentation:Modules/http_intf|HTTP]]
*[[Documentation:Modules/hotkeys|Hotkeys]]
*[[Documentation:Modules/lirc|lirc]]
*[[Documentation:Modules/osc|osc]]

== Outputs ==

=== Audio Output ===

*[[Documentation:Modules/directx_aout|DirectX]]
*[[Documentation:Modules/waveout|waveout]]
*[[Documentation:Modules/portaudio|portaudio]]
*[[Documentation:Modules/sdl_aout|SDL]]

*[[Documentation:Modules/auhal|AUHAL]]
*[[Documentation:Modules/jack|jack]]

*[[Documentation:Modules/alsa|Alsa]]
*[[Documentation:Modules/oss|OSS]]
*[[Documentation:Modules/arts|aRts]]
*[[Documentation:Modules/esd|esound]]

*[[Documentation:Modules/file_aout|file]]

=== Video Output ===
*[[Documentation:Modules/direct3d|Direct3D]]
*[[Documentation:Modules/directx_vout|DirectX]]
*[[Documentation:Modules/wingdi|Windows GDI]]
*[[Documentation:Modules/glwin32|OpenGL for windows]]

*[[Documentation:Modules/opengl|OpenGL]]

*[[Documentation:Modules/xvideo|XVideo]]
*[[Documentation:Modules/x11|X11]]
*[[Documentation:Modules/glx|OpenGL (GLX)]]
*[[Documentation:Modules/fb|Framebuffer]]
*[[Documentation:Modules/directfb|Direct framebuffer]]

*[[Documentation:Modules/sdl_vout|SDL]]
*[[Documentation:Modules/caca|Colored ASCII Art]]
*[[Documentation:Modules/aa|ASCII Art]]
*[[Documentation:Modules/image|Image]]

=== Stream Output ===

*[[Documentation:Modules/standard|Standard (std)]]
*[[Documentation:Modules/transcode|Transcode]]
*[[Documentation:Modules/duplicate|Duplicate]]
*[[Documentation:Modules/rtp|RTP]]
*[[Documentation:Modules/es|Elementary Stream (es)]]
*[[Documentation:Modules/display|Display]]
*[[Documentation:Modules/dummy_sout|Dummy]]

*[[Documentation:Modules/bridge-out|Bridge Out]]
*[[Documentation:Modules/bridge-in|Bridge In]]
*[[Documentation:Modules/mosaic-bridge|Mosaic Bridge]]

*[[Documentation:Modules/autodel|Autodel]]
*[[Documentation:Modules/gather|Gather]]
*[[Documentation:Modules/description|Description]]
*[[Documentation:Modules/switcher|Switcher]]
*[[Documentation:Modules/transrate|Transrate]]

== Filters ==

=== Audio Filters ===

=== Video Filters ===

*[[Documentation:Modules/adjust|Adjust]]
*[[Documentation:Modules/gradient|Gradient]]
*[[Documentation:Modules/invert|Invert]]
*[[Documentation:Modules/wave|Wave]]
*[[Documentation:Modules/ripple|Ripple]]
*[[Documentation:Modules/motionblur|Motion Blur]]
*[[Documentation:Modules/psychedelic|Psychedelic]]
*[[Documentation:Modules/noise|Noise]]
*[[Documentation:Modules/colorthres|Color Threshold]]
*[[Documentation:Modules/rotate|Rotate]]
*[[Documentation:Modules/extract|Extract]]
*[[Documentation:Modules/erase|Logo Erase]]
*[[Documentation:Modules/gaussianblur|Gaussian Blur]]
*[[Documentation:Modules/sharpen|Sharpen]]

The following video filters are for use in transcode only:
*[[Documentation:Modules/croppadd|Crop Padd]]
*[[Documentation:Modules/canvas|Canvas]]

The following video filters are for use in the mosaic framework only:
*[[Documentation:Modules/bluescreen|Blue Screen]]
*[[Documentation:Modules/alphamask|Alpha mask]]

=== Video Sub-Filters ===

*[[Documentation:Modules/marq|Marq]]
*[[Documentation:Modules/rss|RSS]]
*[[Documentation:Modules/logo|Logo]]
*[[Documentation:Modules/mosaic|Mosaic]]
*[[Documentation:Modules/time|Time]] (up to 0.8.6)

=== Video Output Filters ===

*[[Documentation:Modules/deinterlace|Deinterlace]]
*[[Documentation:Modules/transform|Transform]]
*[[Documentation:Modules/wall|Wall]]
*[[Documentation:Modules/crop|Crop]]
*[[Documentation:Modules/panoramix|Panoramix]]
*[[Documentation:Modules/clone|Clone]]
*[[Documentation:Modules/logo|Logo]]
*[[Documentation:Modules/magnify|Magnify]]
*[[Documentation:Modules/puzzle|Puzzle]]
*[[Documentation:Modules/distort|Distort]] (up to 0.8.6)

=== Visualizations ===

*[[Documentation:Modules/visualizer|Visualizer]]
*[[Documentation:Modules/goom|Goom]]
*[[Documentation:Modules/galaktos|Galaktos]]

=== Access Filters ===
*[[Documentation:Modules/timeshift|Timeshift]]
*[[Documentation:Modules/record|Record]]
*[[Documentation:Modules/dump|Dump]]
*[[Documentation:Modules/bandwidth|Bandwidth]]

== Other ==

=== Accesses ===
*[[Documentation:Modules/file|File Input]] - for reading local files
*[[Documentation:Modules/directory|Directory]]
*[[Documentation:Modules/dvdnav|DVDnav Input]]
*[[Documentation:Modules/dvdread|DVDRead Input]] - DVD without menu support
*[[Documentation:Modules/vcd|VCD]]
*[[Documentation:Modules/http|HTTP Input]]
*[[Documentation:Modules/ftp|FTP Input]]
*[[Documentation:Modules/udp|UDP/RTP Input]]
*[[Documentation:Modules/rtsp|RTSP]] -
*[[Documentation:Modules/rtmp|RTMP]] - Real Time Media Player
*[[Documentation:Modules/mms|MMS]] - reading from the MicroSoft Media Server
*[[Documentation:Modules/screen|Screen Input]] - grabbing the currently active screen
*[[Documentation:Modules/fake|Fake]] - presents a static image as a video stream
*[[Documentation:Modules/rawvid|Raw Video]] - streams of bitmap images
*[[Documentation:Modules/mkv|Matroska stream]]
*[[Documentation:Modules/h264|H.264 Video]]
*[[Documentation:Modules/pvr|IVTV MPEG Encoding Card Input]]

Linux specific:
*[[Documentation:Modules/dv|DV]]
*[[Documentation:Modules/dvb|DVB Input]]
*[[Documentation:Modules/pvr|PVR]]
*[[Documentation:Modules/v4l|Video4Linux (v4l)]]
*[[Documentation:Modules/v4l2|Video4Linux2 (v4l2)]]
*[[Dc1394|Dc 1394]] FIXME: shouldn't link outside of Documentation:Modules/
Windows specific:
*[[Documentation:Modules/bda|BDA]]
*[[Documentation:Modules/dshow|DirectShow]]

=== Access Outputs ===

=== Codecs ===

==== Audio ====
==== Video ====
==== Subtitles ====

=== Demuxers ===
==== Playlist ====
*[[Documentation:Modules/m3u-open|m3u]]
*[[Documentation:Modules/pls-open|pls]]
*[[Documentation:Modules/b4s-open|b4s]]
*[[Documentation:Modules/dvb-open|dvb]]
*[[Documentation:Modules/podcast|podcast]]
*[[Documentation:Modules/xspf-open|XSPF]]
*[[Documentation:Modules/shout-winamp|Winamp Shoutcast]]
*[[Documentation:Modules/asx-open|ASX]]
*[[Documentation:Modules/sgimb|sgimb]]
*[[Documentation:Modules/qtl|QTL]]
*[[Documentation:Modules/gvi|gvi]]

=== Muxers ===

=== Service Discovery ===

*[[Documentation:Modules/sap|SAP]]
*[[Documentation:Modules/shout|Shoutcast]]
*[[Documentation:Modules/podcast_sd|Podcast]]
*[[Documentation:Modules/hal|HAL]]
*[[Documentation:Modules/daap|DAAP]]
*[[Documentation:Modules/bonjour|Bonjour]]
*[[Documentation:Modules/upnp_intel|UPnP (intel)]]
*[[Documentation:Modules/upnp_cc|UPnP (cyberlink)]]

=== Misc ===
*[[Documentation:Modules/netsync|netsync]]
*[[Documentation:Modules/motion_control|motion control]]

{{Documentation}}

Documentation:Modules

2008-12-13T16:37:16Z

Nhumfrey: Added OSC

__NOTOC__

This page lists most of the modules present in the official VLC source code. Understanding these pages might require that you know about VLC and its command line usage. It is recommended that you read the other [[Documentation:Documentation|documentation]] first.

To list all the available modules in your VLC build, use:
% '''vlc --list'''

To list a module's configuration options, use:
% '''vlc -p <modulename> --advanced --help-verbose'''

== Interfaces ==

=== Graphical ===

*[[Documentation:Modules/wxWidgets|wxWidgets]]
*[[Documentation:Modules/skins2|Skins2]]
*[[Documentation:Modules/Qt4|Qt4]]
*[[Documentation:Modules/macosx_gui|Mac OS X]]
*[[Documentation:Modules/beos_gui|BeOS]]
*[[Documentation:Modules/wince|Windows CE]]

=== Text ===

*[[Documentation:Modules/rc|remote control (rc)]]
*[[Documentation:Modules/telnet|telnet]]
*[[Documentation:Modules/ncurses|ncurses]]
*[[Documentation:Modules/osc|osc]]

=== Other ===

*[[Documentation:Modules/http_intf|HTTP]]
*[[Documentation:Modules/hotkeys|Hotkeys]]
*[[Documentation:Modules/lirc|lirc]]

== Outputs ==

=== Audio Output ===

*[[Documentation:Modules/directx_aout|DirectX]]
*[[Documentation:Modules/waveout|waveout]]
*[[Documentation:Modules/portaudio|portaudio]]
*[[Documentation:Modules/sdl_aout|SDL]]

*[[Documentation:Modules/auhal|AUHAL]]
*[[Documentation:Modules/jack|jack]]

*[[Documentation:Modules/alsa|Alsa]]
*[[Documentation:Modules/oss|OSS]]
*[[Documentation:Modules/arts|aRts]]
*[[Documentation:Modules/esd|esound]]

*[[Documentation:Modules/file_aout|file]]

=== Video Output ===
*[[Documentation:Modules/direct3d|Direct3D]]
*[[Documentation:Modules/directx_vout|DirectX]]
*[[Documentation:Modules/wingdi|Windows GDI]]
*[[Documentation:Modules/glwin32|OpenGL for windows]]

*[[Documentation:Modules/opengl|OpenGL]]

*[[Documentation:Modules/xvideo|XVideo]]
*[[Documentation:Modules/x11|X11]]
*[[Documentation:Modules/glx|OpenGL (GLX)]]
*[[Documentation:Modules/fb|Framebuffer]]
*[[Documentation:Modules/directfb|Direct framebuffer]]

*[[Documentation:Modules/sdl_vout|SDL]]
*[[Documentation:Modules/caca|Colored ASCII Art]]
*[[Documentation:Modules/aa|ASCII Art]]
*[[Documentation:Modules/image|Image]]

=== Stream Output ===

*[[Documentation:Modules/standard|Standard (std)]]
*[[Documentation:Modules/transcode|Transcode]]
*[[Documentation:Modules/duplicate|Duplicate]]
*[[Documentation:Modules/rtp|RTP]]
*[[Documentation:Modules/es|Elementary Stream (es)]]
*[[Documentation:Modules/display|Display]]
*[[Documentation:Modules/dummy_sout|Dummy]]

*[[Documentation:Modules/bridge-out|Bridge Out]]
*[[Documentation:Modules/bridge-in|Bridge In]]
*[[Documentation:Modules/mosaic-bridge|Mosaic Bridge]]

*[[Documentation:Modules/autodel|Autodel]]
*[[Documentation:Modules/gather|Gather]]
*[[Documentation:Modules/description|Description]]
*[[Documentation:Modules/switcher|Switcher]]
*[[Documentation:Modules/transrate|Transrate]]

== Filters ==

=== Audio Filters ===

=== Video Filters ===

*[[Documentation:Modules/adjust|Adjust]]
*[[Documentation:Modules/gradient|Gradient]]
*[[Documentation:Modules/invert|Invert]]
*[[Documentation:Modules/wave|Wave]]
*[[Documentation:Modules/ripple|Ripple]]
*[[Documentation:Modules/motionblur|Motion Blur]]
*[[Documentation:Modules/psychedelic|Psychedelic]]
*[[Documentation:Modules/noise|Noise]]
*[[Documentation:Modules/colorthres|Color Threshold]]
*[[Documentation:Modules/rotate|Rotate]]
*[[Documentation:Modules/extract|Extract]]
*[[Documentation:Modules/erase|Logo Erase]]
*[[Documentation:Modules/gaussianblur|Gaussian Blur]]
*[[Documentation:Modules/sharpen|Sharpen]]

The following video filters are for use in transcode only:
*[[Documentation:Modules/croppadd|Crop Padd]]
*[[Documentation:Modules/canvas|Canvas]]

The following video filters are for use in the mosaic framework only:
*[[Documentation:Modules/bluescreen|Blue Screen]]
*[[Documentation:Modules/alphamask|Alpha mask]]

=== Video Sub-Filters ===

*[[Documentation:Modules/marq|Marq]]
*[[Documentation:Modules/rss|RSS]]
*[[Documentation:Modules/logo|Logo]]
*[[Documentation:Modules/mosaic|Mosaic]]
*[[Documentation:Modules/time|Time]] (up to 0.8.6)

=== Video Output Filters ===

*[[Documentation:Modules/deinterlace|Deinterlace]]
*[[Documentation:Modules/transform|Transform]]
*[[Documentation:Modules/wall|Wall]]
*[[Documentation:Modules/crop|Crop]]
*[[Documentation:Modules/panoramix|Panoramix]]
*[[Documentation:Modules/clone|Clone]]
*[[Documentation:Modules/logo|Logo]]
*[[Documentation:Modules/magnify|Magnify]]
*[[Documentation:Modules/puzzle|Puzzle]]
*[[Documentation:Modules/distort|Distort]] (up to 0.8.6)

=== Visualizations ===

*[[Documentation:Modules/visualizer|Visualizer]]
*[[Documentation:Modules/goom|Goom]]
*[[Documentation:Modules/galaktos|Galaktos]]

=== Access Filters ===
*[[Documentation:Modules/timeshift|Timeshift]]
*[[Documentation:Modules/record|Record]]
*[[Documentation:Modules/dump|Dump]]
*[[Documentation:Modules/bandwidth|Bandwidth]]

== Other ==

=== Accesses ===
*[[Documentation:Modules/file|File Input]] - for reading local files
*[[Documentation:Modules/directory|Directory]]
*[[Documentation:Modules/dvdnav|DVDnav Input]]
*[[Documentation:Modules/dvdread|DVDRead Input]] - DVD without menu support
*[[Documentation:Modules/vcd|VCD]]
*[[Documentation:Modules/http|HTTP Input]]
*[[Documentation:Modules/ftp|FTP Input]]
*[[Documentation:Modules/udp|UDP/RTP Input]]
*[[Documentation:Modules/rtsp|RTSP]] -
*[[Documentation:Modules/rtmp|RTMP]] - Real Time Media Player
*[[Documentation:Modules/mms|MMS]] - reading from the MicroSoft Media Server
*[[Documentation:Modules/screen|Screen Input]] - grabbing the currently active screen
*[[Documentation:Modules/fake|Fake]] - presents a static image as a video stream
*[[Documentation:Modules/rawvid|Raw Video]] - streams of bitmap images
*[[Documentation:Modules/mkv|Matroska stream]]
*[[Documentation:Modules/h264|H.264 Video]]
*[[Documentation:Modules/pvr|IVTV MPEG Encoding Card Input]]

Linux specific:
*[[Documentation:Modules/dv|DV]]
*[[Documentation:Modules/dvb|DVB Input]]
*[[Documentation:Modules/pvr|PVR]]
*[[Documentation:Modules/v4l|Video4Linux (v4l)]]
*[[Documentation:Modules/v4l2|Video4Linux2 (v4l2)]]
*[[Dc1394|Dc 1394]] FIXME: shouldn't link outside of Documentation:Modules/
Windows specific:
*[[Documentation:Modules/bda|BDA]]
*[[Documentation:Modules/dshow|DirectShow]]

=== Access Outputs ===

=== Codecs ===

==== Audio ====
==== Video ====
==== Subtitles ====

=== Demuxers ===
==== Playlist ====
*[[Documentation:Modules/m3u-open|m3u]]
*[[Documentation:Modules/pls-open|pls]]
*[[Documentation:Modules/b4s-open|b4s]]
*[[Documentation:Modules/dvb-open|dvb]]
*[[Documentation:Modules/podcast|podcast]]
*[[Documentation:Modules/xspf-open|XSPF]]
*[[Documentation:Modules/shout-winamp|Winamp Shoutcast]]
*[[Documentation:Modules/asx-open|ASX]]
*[[Documentation:Modules/sgimb|sgimb]]
*[[Documentation:Modules/qtl|QTL]]
*[[Documentation:Modules/gvi|gvi]]

=== Muxers ===

=== Service Discovery ===

*[[Documentation:Modules/sap|SAP]]
*[[Documentation:Modules/shout|Shoutcast]]
*[[Documentation:Modules/podcast_sd|Podcast]]
*[[Documentation:Modules/hal|HAL]]
*[[Documentation:Modules/daap|DAAP]]
*[[Documentation:Modules/bonjour|Bonjour]]
*[[Documentation:Modules/upnp_intel|UPnP (intel)]]
*[[Documentation:Modules/upnp_cc|UPnP (cyberlink)]]

=== Misc ===
*[[Documentation:Modules/netsync|netsync]]
*[[Documentation:Modules/motion_control|motion control]]

{{Documentation}}

DBus-spec

2008-04-12T11:25:06Z

Nhumfrey: Added link to MPRIS specification

Specification for a Common, Desktop neutral, Media Player D-Bus interface

'''Please note this document is not specific to VLC and is a work in progress.'''

OBSOLETE, KEPT FOR HISTORICAL REASONS

MPRIS discussion is at http://wiki.xmms2.xmms.se/index.php/Media_Player_Interfaces

MPRIS specification is at http://wiki.xmms2.xmms.se/index.php/MPRIS

What follows has been largely stolen from http://bmpx.beep-media-player.org/site/MPRIS_Interfacing_Specification

This is an attempt to create a specification for media players to use, for '''YOUR''' applications to be able to interact with '''ANY''' Media Player '''YOU''' want to use on '''ANY''' desktop '''YOU''' want to use.

This is in the spirit of http://www.freedesktop.org and uses code and ideas from this project, most notably D-Bus : http://dbus.freedesktop.org and uses ideas from http://www.musicbrainz.org

= Other players =

How other "Media Players" interact with D-Bus

== bmpx ==

http://bmpx.beep-media-player.org/site/MPRIS_Interfacing_Specification

== banshee ==

http://cvs.gnome.org/viewcvs/*checkout*/banshee/src/Banshee.Base/DBusPlayer.cs

== rhythmbox ==

http://cvs.gnome.org/viewcvs/rhythmbox/remote/dbus/rb-client.c?view=markup

== muine ==

http://cvs.gnome.org/viewcvs/muine/DBusLib/Player.cs?view=markup

== amarok ==

http://amarok.kde.org/wiki/DCOP_Functions
(D-Bus will replace DCOP in KDE4, Amarok 2.0)

= Definitions =

== "Media Player" ==

An application, either with GUI or GUI-less (or which allows for both modes of operation) which is capable of playing back audio/video streams. The means by which it does accomplish that (e.g. which audio backend to use, and which output method) is out of the scope of this document.

The "Media Player" '''must''':
* Be able to play back at least local storage file streams.
* Be able to play back at least one stream at a time.

== "Client" ==

The Client is an unspecified application that will interact with the "Media Player" using D-Bus protocol.
For example:

* A softphone, that pauses, or step the volume down, when a call is being received.
* An applet that nicely integrates in your desktop environment, to control your "Media Player".
* An instant messaging client which informs your buddies of what you're listening to.
* A monitor that stores in a database what you are listening to, for statistics purpose.
* A video editing software that calls an external "Media Player" to preview your work.

== "Tracklist" ==

A list of media files which resides within the "Media Player", and whose implementation is opaque to the remote interface.

The "Tracklist" '''must''':
* Hold an ordered list of locations of the media files as URIs (e.g. file:// or <nowiki>http://</nowiki>). The implementation of this can be opaque, which means, it does not neccesarily need to store URIs, but upon remote request, it must be able to return an URI for a given media file.
* Keep the list in an ordered fashion. The order can be changed at any time trough e.g. sorting algorithms, in which case the "Media Player" must send information about the reordering trough it's remote interface

The "Tracklist" '''can''', but does not '''need''' to:
* Hold "Metadata" about media files

== "Metadata" ==

"Metadata" is data that the files carry within themselves as a means of self-identification (commonly known as "tags"), or data that has been retrieved about the files trough other means, e.g. an internet service that provides additional data about particular media files.
"Metadata" is an array of dict entries, like ("length", 253), ("name", "Bolero"), ("video-codec", "DIVX"). The dict entry is in the form (string, variant) eg: {sv}.

Furthermore, "Metadata" can be split into two categories:

1) Technical metadata:
* "URI":"s"
* "length":"i" (length in seconds)
* "video-codec":"s" (video codec as a fourcc)
* "audio-codec":"s" (audio codec as a fourcc)
* "video-bitrate":"i" video bitrate
* "audio-bitrate":"i" audio bitrate
* "audio-samplerate":"i" (audio samplerate)

2) Informational metadata
* "name":"s"
* "artist":"s"
* "album":"s"
* "unique-id":"s" : Musicbrainz Track Identifier as specified on http://musicbrainz.org/docs/specs/metadata_tags.html
* "genre":"s"

This list is informative, and can be extended up to your needs, for example: "age of the captain":"i"

Only Required fields are: "URI" and "length"

= D-Bus =

== The Service ==

org.freedesktop.MediaPlayer

All "Media Players" '''must''' request this name and do not let other "Media Players" 'steal' this name.
Using libdbus, that would be:

DBusConnection *dbus_connection;
DBusError dbus_error;
dbus_bus_request_name( dbus_connection, "org.freedesktop.MediaPlayer", 0, &dbus_error );

To be able to request the name, and so, be able to communicate via D-Bus, no "Media Player" must be running. The "Media Player" may call the Quit method, and wait till the name is unregistered, to ensure this is the case.

: I think this is a bad idea, it's not the place for a interop Spec to force single instance behaviour without a good reason (i run amarok all the time and use vlc to play videos or streams...). Why not suggest that mediaplayers register with the well known service name ("org.freedesktop.MediaPlayer") with the options QueueService and suggest the media player should register an application specific service in addition?

: if done that way we gain the feature to query the dbus daemon for all clients queued for that dbus name, so enumerating all current musicplayers that support the Spec is not problem. Contacting the players is not problem to because every client on dbus has a unique name anyway. DBus signal do AFAIK carry the dbus service name of the sending client, so there is no trouble knowing which player send a signal. [[User:textshell|textshell]]

== The Object Hierarchy ==

* / : Media Player identification

* /Player : Playback control

* /TrackList : TrackList management

== The interface ==

All methods must be accessed through the interface org.freedesktop.MediaPlayer

i.e. calling Quit with qdbus would be:
$ qdbus org.freedesktop.MediaPlayer /Player org.freedesktop.MediaPlayer.Quit

== The Methods ==

What's missing: we could use musicbrainz unique identifier to identify current element in the playlist
From fd.o : GetTrackList (using xspf?), ClearTrackList

* /

Identity : Identify the "Media Player" as in "VLC 0.9.0", "bmpx 0.34.9", "Totem 2.16.2" ...

<method name="Identity">
<arg type="s" direction="out"/>
</method>

* /TrackList

GetMetadata : Gives all meta data available for element at given position in the "TrackList"

<method name="GetMetadata">
<arg type="i" direction="in" />
<arg type="a{sv}" direction="out" />
</method>

GetCurrentTrack : Position of Current URI in the "TrackList"

<method name="GetCurrentTrack">
<arg type="i" direction="out" />
</method>

GetLength : Number of elements in the "TrackList"

<method name="GetLength">
<arg type="i" direction="out" />
</method>

AddTrack : Appends an URI in the "TrackList", play it immediately if the 2nd argument is TRUE

<method name="AddTrack">
<arg type="s" />
<arg type="b" />
</method>

DelTrack : Removes an URI from the "TrackList", given its position

<method name="DelTrack">
<arg type="i" />
</method>

* /Player

Next : Goes to the next element (what if we're at the end?)

<method name="Next">
</method>

Prev : Goes to the previous element (what if we're at the beginning?)

<method name="Prev">
</method>

Pause : If playing : pause. If paused : unpause. If stopped : start playing

<method name="Pause">
</method>

Stop : Stop playing.

<method name="Stop">
</method>

Play : If playing : rewind to the beginning of current track, else : start playing.

<method name="Play">
</method>

Quit : Makes the "Media Player" exit.

<method name="Quit">
</method>

GetStatus : Return the status of "Media Player": 0 = Playing, 1 = Paused, 2 = Stopped.

<method name="GetStatus">
<arg type="i" direction="out"/>
</method>

VolumeSet : Sets the volume (argument must be in [0;100])

<method name="VolumeSet">
<arg type="i"/>
</method>

GetVolume : Returns the current volume (must be in [0;100])

<method name="VolumeGet">
<arg type="i" direction="out"/>
</method>

PositionSet : Sets the playing position (argument must be in [0;100])

<method name="PositionSet">
<arg type="i"/>
</method>

PositionGet : Returns the playing position (must be in [0;100])

<method name="PositionGet">
<arg type="i" direction="out"/>
</method>

== The signals ==

TrackChange : Signal is emitted when the "Media Player" plays another "Track". Argument of the signal is the metadata attached to the new "Track"

<signal name="TrackChange">
<arg type="a{sv}"/>
</signal>

StatusChange : Signal is emitted when the status of the "Media Player" change. The argument has the same meaning than the value returned by GetStatus.

<signal name="StatusChange">
<arg type="i"/>
</signal>

CapabilityChange : [TODO] Signal is emitted when the "Media Player" changes capabilities, Flags are CAN_GO_NEXT CAN_GO_PREV CAN_PAUSE CAN_PLAY CAN_SEEK CAN_PROVIDE_METADATA PROVIDES_TIMING

<signal name="CapabilityChange">
<arg type=TODO />
</signal>

= See Also =
* [http://bmpx.beep-media-player.org/site/MPRIS_Interfacing_Specification MPRIS Interfacing Specification] (BMPx wiki)
* [http://wiki.xmms2.xmms.se/index.php/Media_Player_Interfaces Media Player Interfaces] (XMMS2 wiki)

DBus-spec

2008-04-12T11:24:38Z

Nhumfrey: Added link to MPRIS specification

Specification for a Common, Desktop neutral, Media Player D-Bus interface

'''Please note this document is not specific to VLC and is a work in progress.'''

OBSOLETE, KEPT FOR HISTORICAL REASONS

MPRIS discussion is at http://wiki.xmms2.xmms.se/index.php/Media_Player_Interfaces
MPRIS specification is at http://wiki.xmms2.xmms.se/index.php/MPRIS

What follows has been largely stolen from http://bmpx.beep-media-player.org/site/MPRIS_Interfacing_Specification

This is an attempt to create a specification for media players to use, for '''YOUR''' applications to be able to interact with '''ANY''' Media Player '''YOU''' want to use on '''ANY''' desktop '''YOU''' want to use.

This is in the spirit of http://www.freedesktop.org and uses code and ideas from this project, most notably D-Bus : http://dbus.freedesktop.org and uses ideas from http://www.musicbrainz.org

= Other players =

How other "Media Players" interact with D-Bus

== bmpx ==

http://bmpx.beep-media-player.org/site/MPRIS_Interfacing_Specification

== banshee ==

http://cvs.gnome.org/viewcvs/*checkout*/banshee/src/Banshee.Base/DBusPlayer.cs

== rhythmbox ==

http://cvs.gnome.org/viewcvs/rhythmbox/remote/dbus/rb-client.c?view=markup

== muine ==

http://cvs.gnome.org/viewcvs/muine/DBusLib/Player.cs?view=markup

== amarok ==

http://amarok.kde.org/wiki/DCOP_Functions
(D-Bus will replace DCOP in KDE4, Amarok 2.0)

= Definitions =

== "Media Player" ==

An application, either with GUI or GUI-less (or which allows for both modes of operation) which is capable of playing back audio/video streams. The means by which it does accomplish that (e.g. which audio backend to use, and which output method) is out of the scope of this document.

The "Media Player" '''must''':
* Be able to play back at least local storage file streams.
* Be able to play back at least one stream at a time.

== "Client" ==

The Client is an unspecified application that will interact with the "Media Player" using D-Bus protocol.
For example:

* A softphone, that pauses, or step the volume down, when a call is being received.
* An applet that nicely integrates in your desktop environment, to control your "Media Player".
* An instant messaging client which informs your buddies of what you're listening to.
* A monitor that stores in a database what you are listening to, for statistics purpose.
* A video editing software that calls an external "Media Player" to preview your work.

== "Tracklist" ==

A list of media files which resides within the "Media Player", and whose implementation is opaque to the remote interface.

The "Tracklist" '''must''':
* Hold an ordered list of locations of the media files as URIs (e.g. file:// or <nowiki>http://</nowiki>). The implementation of this can be opaque, which means, it does not neccesarily need to store URIs, but upon remote request, it must be able to return an URI for a given media file.
* Keep the list in an ordered fashion. The order can be changed at any time trough e.g. sorting algorithms, in which case the "Media Player" must send information about the reordering trough it's remote interface

The "Tracklist" '''can''', but does not '''need''' to:
* Hold "Metadata" about media files

== "Metadata" ==

"Metadata" is data that the files carry within themselves as a means of self-identification (commonly known as "tags"), or data that has been retrieved about the files trough other means, e.g. an internet service that provides additional data about particular media files.
"Metadata" is an array of dict entries, like ("length", 253), ("name", "Bolero"), ("video-codec", "DIVX"). The dict entry is in the form (string, variant) eg: {sv}.

Furthermore, "Metadata" can be split into two categories:

1) Technical metadata:
* "URI":"s"
* "length":"i" (length in seconds)
* "video-codec":"s" (video codec as a fourcc)
* "audio-codec":"s" (audio codec as a fourcc)
* "video-bitrate":"i" video bitrate
* "audio-bitrate":"i" audio bitrate
* "audio-samplerate":"i" (audio samplerate)

2) Informational metadata
* "name":"s"
* "artist":"s"
* "album":"s"
* "unique-id":"s" : Musicbrainz Track Identifier as specified on http://musicbrainz.org/docs/specs/metadata_tags.html
* "genre":"s"

This list is informative, and can be extended up to your needs, for example: "age of the captain":"i"

Only Required fields are: "URI" and "length"

= D-Bus =

== The Service ==

org.freedesktop.MediaPlayer

All "Media Players" '''must''' request this name and do not let other "Media Players" 'steal' this name.
Using libdbus, that would be:

DBusConnection *dbus_connection;
DBusError dbus_error;
dbus_bus_request_name( dbus_connection, "org.freedesktop.MediaPlayer", 0, &dbus_error );

To be able to request the name, and so, be able to communicate via D-Bus, no "Media Player" must be running. The "Media Player" may call the Quit method, and wait till the name is unregistered, to ensure this is the case.

: I think this is a bad idea, it's not the place for a interop Spec to force single instance behaviour without a good reason (i run amarok all the time and use vlc to play videos or streams...). Why not suggest that mediaplayers register with the well known service name ("org.freedesktop.MediaPlayer") with the options QueueService and suggest the media player should register an application specific service in addition?

: if done that way we gain the feature to query the dbus daemon for all clients queued for that dbus name, so enumerating all current musicplayers that support the Spec is not problem. Contacting the players is not problem to because every client on dbus has a unique name anyway. DBus signal do AFAIK carry the dbus service name of the sending client, so there is no trouble knowing which player send a signal. [[User:textshell|textshell]]

== The Object Hierarchy ==

* / : Media Player identification

* /Player : Playback control

* /TrackList : TrackList management

== The interface ==

All methods must be accessed through the interface org.freedesktop.MediaPlayer

i.e. calling Quit with qdbus would be:
$ qdbus org.freedesktop.MediaPlayer /Player org.freedesktop.MediaPlayer.Quit

== The Methods ==

What's missing: we could use musicbrainz unique identifier to identify current element in the playlist
From fd.o : GetTrackList (using xspf?), ClearTrackList

* /

Identity : Identify the "Media Player" as in "VLC 0.9.0", "bmpx 0.34.9", "Totem 2.16.2" ...

<method name="Identity">
<arg type="s" direction="out"/>
</method>

* /TrackList

GetMetadata : Gives all meta data available for element at given position in the "TrackList"

<method name="GetMetadata">
<arg type="i" direction="in" />
<arg type="a{sv}" direction="out" />
</method>

GetCurrentTrack : Position of Current URI in the "TrackList"

<method name="GetCurrentTrack">
<arg type="i" direction="out" />
</method>

GetLength : Number of elements in the "TrackList"

<method name="GetLength">
<arg type="i" direction="out" />
</method>

AddTrack : Appends an URI in the "TrackList", play it immediately if the 2nd argument is TRUE

<method name="AddTrack">
<arg type="s" />
<arg type="b" />
</method>

DelTrack : Removes an URI from the "TrackList", given its position

<method name="DelTrack">
<arg type="i" />
</method>

* /Player

Next : Goes to the next element (what if we're at the end?)

<method name="Next">
</method>

Prev : Goes to the previous element (what if we're at the beginning?)

<method name="Prev">
</method>

Pause : If playing : pause. If paused : unpause. If stopped : start playing

<method name="Pause">
</method>

Stop : Stop playing.

<method name="Stop">
</method>

Play : If playing : rewind to the beginning of current track, else : start playing.

<method name="Play">
</method>

Quit : Makes the "Media Player" exit.

<method name="Quit">
</method>

GetStatus : Return the status of "Media Player": 0 = Playing, 1 = Paused, 2 = Stopped.

<method name="GetStatus">
<arg type="i" direction="out"/>
</method>

VolumeSet : Sets the volume (argument must be in [0;100])

<method name="VolumeSet">
<arg type="i"/>
</method>

GetVolume : Returns the current volume (must be in [0;100])

<method name="VolumeGet">
<arg type="i" direction="out"/>
</method>

PositionSet : Sets the playing position (argument must be in [0;100])

<method name="PositionSet">
<arg type="i"/>
</method>

PositionGet : Returns the playing position (must be in [0;100])

<method name="PositionGet">
<arg type="i" direction="out"/>
</method>

== The signals ==

TrackChange : Signal is emitted when the "Media Player" plays another "Track". Argument of the signal is the metadata attached to the new "Track"

<signal name="TrackChange">
<arg type="a{sv}"/>
</signal>

StatusChange : Signal is emitted when the status of the "Media Player" change. The argument has the same meaning than the value returned by GetStatus.

<signal name="StatusChange">
<arg type="i"/>
</signal>

CapabilityChange : [TODO] Signal is emitted when the "Media Player" changes capabilities, Flags are CAN_GO_NEXT CAN_GO_PREV CAN_PAUSE CAN_PLAY CAN_SEEK CAN_PROVIDE_METADATA PROVIDES_TIMING

<signal name="CapabilityChange">
<arg type=TODO />
</signal>

= See Also =
* [http://bmpx.beep-media-player.org/site/MPRIS_Interfacing_Specification MPRIS Interfacing Specification] (BMPx wiki)
* [http://wiki.xmms2.xmms.se/index.php/Media_Player_Interfaces Media Player Interfaces] (XMMS2 wiki)

User:Nhumfrey

2008-04-12T11:08:53Z

Nhumfrey: New page: == Nicholas J Humfrey == Homepage: http://www.aelius.com/njh/

== Nicholas J Humfrey ==

Homepage: http://www.aelius.com/njh/