Difference between revisions of "Documentation:WebPlugin"

From VideoLAN Wiki
Jump to navigation Jump to search
m (set Embedded category (subcategory of Bindings))
(→‎Playlist object: Improve description for vlc.playlist.parse())
 
(147 intermediate revisions by 17 users not shown)
Line 1: Line 1:
−
==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==
+
{{Outdated}}
  
−
The following description works for any of the browsers VLC supports. The JavaScript API has been unified between Mozilla/Firefox/IE (ActiveX) and Safari, thus targetting at all of the major OS out there.  
+
This Documentation speaks about the {{VLC}} Web plugins and how to write pages for it.  
 +
{{RightMenu|Documentation TOC}}
  
−
This is only valid for {{VLC}} version 0.8.6 and above.
+
== Introduction: Building Web pages with Video ==
  
−
Additionally to viewing video on all pages, you can build custom pages that will use the advanced features of the plugin, using Javascript functions to control playback or extract information from the
+
The {{VLC}} webplugins are native browser plugins, similar to Flash or Silverlight plugins and allow playback inside the browser of all the videos that {{VLC}} can read.
−
plugin.
 
  
−
== API description ==
+
Additionally to viewing video on all pages, you can build custom pages that will use the advanced features of the plugin, using JavaScript functions to control playback or extract information from the plugin.  
−
The vlc plugin exports serveral objects that can be accessed for setting and getting information. When used improperly the API's will throw an exception that includes a string that explains what happened. For example when asking for vlc.input.length when there is no playlist item playing.
 
  
−
The vlc plugin knows the following objects:
+
There are 2 main plugins: one is ActiveX for IE, the other is NPAPI for the other browsers. They feature the same amount of features.
  
−
*'''audio''': Access audio properties.
+
In older versions, those plugins were very crashy. '''We URGE YOU''' to use VLC '''2.0.0''' or newer versions.
 +
 
 +
=== Browsers support ===
 +
It has been tested with:
 +
{| class="wikitable"
 +
|-
 +
| Mozilla Firefox (up to v51) || [[File:Firefox-logo.png|40x40px]]
 +
|-
 +
| Internet Explorer || [[File:Internet Explorer.png|40x40px]]
 +
|-
 +
| Safari (up to v11) || [[File:Apple Safari.png|40x40px]]
 +
|-
 +
| Chrome (up to v44) ||
 +
|-
 +
| Konqueror ||
 +
|-
 +
| Opera (up to v36) ||
 +
|}
 +
 
 +
It has been tested on GNU/Linux, Windows and MacOS.
 +
 
 +
 
 +
'''Note:'''
 +
 
 +
In the most of browsers, the support for NPAPI plugins was dropped. Only in some forks of Firefox like Waterfox or Pale Moon, NPAPI plugins are still supported.
 +
 
 +
For this reason, the NPAPI plugin will be dropped in vlc version 4.
 +
 
 +
== Embed tag attributes ==
 +
 
 +
To embed the plugin into a webpage, use the following {{tag|embed}} template:
 +
 
 +
<syntaxhighlight lang="html5" line>
 +
<embed type="application/x-vlc-plugin" width="640" height="480" />
 +
</syntaxhighlight>
 +
 
 +
 
 +
If you are using vlc version < 2.2.0 with Internet Explorer, use instead the following {{tag|object}} template:
 +
 
 +
<syntaxhighlight lang="html5" line>
 +
<object classid="clsid:9BE31822-FDAD-461B-AD51-BE1D1C159921" width="640" height="480"></object>
 +
</syntaxhighlight>
 +
 
 +
For the declaration of tag attributes, use the tag {{tag|param}}. Here an example:
 +
 
 +
<syntaxhighlight lang="html5" line>
 +
<object classid="clsid:9BE31822-FDAD-461B-AD51-BE1D1C159921" width="640" height="480">
 +
    <param name="autostart" value="true" />
 +
    <param name="allowfullscreen" value="false" />
 +
</object>
 +
</syntaxhighlight>
 +
 
 +
For compatibility with the mozilla plugin, you can combine both tags:
 +
 
 +
<syntaxhighlight lang="html5" line>
 +
<object classid="clsid:9BE31822-FDAD-461B-AD51-BE1D1C159921" id="vlc" width="640" height="480">
 +
    <embed type="application/x-vlc-plugin" name="vlc" width="640" height="480" />
 +
</object>
 +
</syntaxhighlight>
 +
 
 +
=== Required elements ===
 +
These are '''required''' attributes for the {{tag|embed}} tag:
 +
 
 +
*'''width''': Specifies the width of the plugin.
 +
*'''height''': Specifies the height of the plugin.
 +
*'''target''' (or one of these alias: '''mrl''', '''filename''', '''src'''): Specifies the source location (URL) of the video to load.
 +
 
 +
=== Optional elements ===
 +
These are additional attributes for the {{tag|embed}} tag:
 +
 
 +
*'''autoplay''', '''autostart''': Specifies whether the plugin starts playing on load. Default: ''true''
 +
*'''allowfullscreen''' (or '''fullscreenEnabled''', '''fullscreen'''): (since VLC version 2.0.0) Specifies whether the user can switch into fullscreen mode. Default: ''true''
 +
*'''windowless''': (since VLC version 2.0.6, only for Mozilla) Draw the video on a window-less (non-accelerated) surface and allow styling (CSS overlay, 3D transformations, and much more). Default: ''false''
 +
*'''mute''': Specifies whether the audio volume is initially muted. Default: ''false''
 +
*'''volume''': (since VLC version 2.2.2) Specifies the initial audio volume as a percentage. Default: ''100''
 +
*'''loop''', '''autoloop''': Specifies whether the video loops on end. Default: ''false''
 +
*'''controls''' (or '''toolbar'''): Specifies whether the controls are shown by default. Default: ''true''
 +
*'''bgcolor''': Specifies the background color of the video player. Default: ''#000000''
 +
*'''text''': (only for Mozilla on MacOS) Specifies a text displayed as long as no video is shown. Default: empty
 +
*'''branding''': (in vlc version < 2.2.2 only for Mozilla on MacOS) Specifies whether VLC branding should be displayed in the web plugin's drawing context. Default: ''true''
 +
 
 +
=== Normal DOM elements ===
 +
*'''id''': DOM id
 +
*'''name''': DOM name
 +
 
 +
== Javascript API description  ==
 +
 
 +
The vlc plugin exports several objects that can be accessed for setting and getting information. When used improperly the API's will throw an exception that includes a string that explains what happened. For example when you set vlc.audio.track out of range.
 +
 
 +
=== VLC objects ===
 +
The vlc plugin knows the following objects:
 +
 
 +
*'''audio''': Access audio properties.  
 
*'''input''': Access input properties.
 
*'''input''': Access input properties.
−
*'''playlist''': Access playlist properties.
+
**'''input.title''': Access title properties (available in vlc version ≥ 2.2.2, supported only ≥ 3.0.0)
−
*'''subtitle''': Access subtitle properties.
+
**'''input.chapter''': Access chapter properties (available in vlc version ≥ 2.2.2, supported only ≥ 3.0.0)
−
*'''video''': Access video properties.
+
*'''playlist''': Access playlist properties.
−
*'''video.marquee''': Access marquee properties.  
+
**'''playlist.items''': Access playlist items properties.
−
*'''log''': Access log properties.
+
*'''subtitle''': Access subtitle properties.  
−
*'''messages''': Access to log message properties.
+
*'''video''': Access video properties.  
−
*'''iterator''': Access to log iterator properties.
+
**'''video.deinterlace''': Access deinterlace properties.
 +
**'''video.marquee''': Access marquee video filter properties.  
 +
**'''video.logo''': Access logo video filter properties.  
 +
*'''mediaDescription''': Access media info properties (available in vlc version ≥ 2.0.2).
  
−
The following JavaScript code shows howto get a reference to the vlc plugin. This reference can then be used to access the objects of the vlc plugin.
+
The following are deprecated:
 +
*'''log''': Access log properties (only available in vlc version ≤ 1.0.0-rc1).
 +
*'''messages''': Access to log message properties (only available in vlc version ≤ 1.0.0-rc1).
 +
*'''iterator''': Access to log iterator properties (only available in vlc version ≤ 1.0.0-rc1).
 +
*'''message''': Access to log message properties (only available in vlc version ≤ 1.0.0-rc1).  
  
−
&lt;html&gt;
+
==== Example ====
−
&lt;title&gt;VLC Mozilla plugin test page&lt;/title&gt;
+
The following JavaScript code shows howto get a reference to the vlc plugin. This reference can then be used to access the objects of the vlc plugin.  
−
&lt;body&gt;
 
−
&lt;embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
 
−
    width="640"
 
−
    height="480"
 
−
    id="vlc"&gt;
 
−
&lt;/embed&gt;
 
−
&lt;script language="Javascript"&gt;
 
−
&lt;!--
 
−
var vlc = document.getElementById("vlc");
 
−
vlc.audio.toggleMute();
 
−
!--&gt;
 
−
&lt;/script&gt;
 
−
&lt;/body&gt;
 
−
&lt;/html&gt;
 
  
−
====Root object====
+
<syntaxhighlight lang="html5" line>
 +
<!DOCTYPE html>
 +
<html>
 +
<title>VLC Mozilla plugin test page</title>
 +
<body>
 +
<embed type="application/x-vlc-plugin"
 +
      width="640"
 +
      height="480"
 +
      id="vlc" />
 +
<script type="text/javascript">
 +
</syntaxhighlight><syntaxhighlight lang="javascript" start="10" line>
 +
<!--
 +
var vlc = document.getElementById("vlc");
 +
vlc.audio.toggleMute();
 +
//-->
 +
</syntaxhighlight><syntaxhighlight lang="html5" start="14" line>
 +
</script>
 +
</body>
 +
</html>
 +
</syntaxhighlight>
  
−
readonly properties
+
=== Root object  ===
−
*'''VersionInfo''': returns version information string
+
 
 +
readonly properties  
 +
 
 +
*'''vlc.VersionInfo''': returns version information string
 +
 
 +
read/write properties
  
−
read/write properties
 
 
*''none''
 
*''none''
  
−
methods
+
methods  
−
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)
+
 
 +
*'''vlc.versionInfo()''': (only for Mozilla) returns version information string (same as VersionInfo)
 +
*'''vlc.getVersionInfo()''': (supported in vlc version ≥ 2.2.2) returns version information string (same as VersionInfo and versionInfo())
 +
 
 +
*'''vlc.addEventListener(eventname, callback, bubble)''': (only for Mozilla) add a listener for mentioned event name, callback expects a function and bubble influences the order of eventhandling by JS (usually it is set to false).
 +
*'''vlc.removeEventListener(eventname, callback, bubble)''': (only for Mozilla) remove listener for mentioned event name, callback expects a function and bubble influences the order of eventhandling by JS (usually it is set to false).
 +
 
 +
*'''vlc.attachEvent(eventname, callback)''': (only for ActiveX) add listener for mentioned event name, callback expects a function
 +
*'''vlc.detachEvent(eventname, callback)''': (only for ActiveX) remove listener for mentioned event name, callback expects a function
 +
 
 +
events
 +
 
 +
*'''MediaPlayerNothingSpecial''': vlc is in idle state doing nothing but waiting for a command to be issued
 +
*'''MediaPlayerOpening''': vlc is opening an media resource locator ([[MRL]])
 +
*'''MediaPlayerBuffering(int cache)''': vlc is buffering
 +
*'''MediaPlayerPlaying''': vlc is playing a media
 +
*'''MediaPlayerPaused''': vlc is in paused state
 +
*'''MediaPlayerStopped''': vlc is in stopped state
 +
*'''MediaPlayerStopAsyncDone''': (supported in vlc version ≥ 3.0.0) playback has stopped asynchronously
 +
*'''MediaPlayerForward''': vlc is fastforwarding through the media (this never gets invoked)
 +
*'''MediaPlayerBackward''': vlc is going backwards through the media (this never gets invoked)
 +
*'''MediaPlayerEncounteredError''': vlc has encountered an error and is unable to continue
 +
*'''MediaPlayerEndReached''': vlc has reached the end of current playlist
 +
*'''MediaPlayerTimeChanged(int time)''': time has changed
 +
*'''MediaPlayerPositionChanged(float position)''': media position has changed
 +
*'''MediaPlayerSeekableChanged(bool seekable)''': media seekable flag has changed (true means media is seekable, false means it is not)
 +
*'''MediaPlayerPausableChanged(bool pausable)''': media pausable flag has changed (true means media is pauseable, false means it is not)
 +
*'''MediaPlayerMediaChanged''': (supported in vlc version ≥ 2.2.0) media has changed
 +
*'''MediaPlayerTitleChanged(int title)''': (in vlc version < 2.2.0 only for Mozilla) title has changed (DVD/Blu-ray)
 +
*'''MediaPlayerChapterChanged(int chapter)''': (supported in vlc version ≥ 3.0.0) chapter has changed (DVD/Blu-ray)
 +
*'''MediaPlayerLengthChanged(int length)''': (in vlc version < 2.2.0 only for Mozilla) length has changed
 +
*'''MediaPlayerVout(int count)''': (supported in vlc version ≥ 2.2.7) the number of video output has changed
 +
*'''MediaPlayerMuted''': (supported in vlc version ≥ 2.2.7) audio volume was muted
 +
*'''MediaPlayerUnmuted''': (supported in vlc version ≥ 2.2.7) audio volume was unmuted
 +
*'''MediaPlayerAudioVolume(float volume)''': (supported in vlc version ≥ 2.2.7) audio volume has changed
 +
 
 +
==== Example ====
 +
The following code snippet provides easy functions to register and unregister event callbacks on all supported platforms.
 +
<syntaxhighlight lang="html5" line>
 +
<script type="text/javascript">
 +
</syntaxhighlight><syntaxhighlight lang="javascript" start="2" line>
 +
<!--
 +
function registerVLCEvent(event, handler) {
 +
    var vlc = getVLC("vlc");
 +
    if (vlc) {
 +
        if (vlc.attachEvent) {
 +
            // Microsoft
 +
            vlc.attachEvent (event, handler);
 +
        } else if (vlc.addEventListener) {
 +
            // Mozilla: DOM level 2
 +
            vlc.addEventListener (event, handler, false);
 +
        }
 +
    }
 +
}
 +
// stop listening to event
 +
function unregisterVLCEvent(event, handler) {
 +
    var vlc = getVLC("vlc");
 +
    if (vlc) {
 +
        if (vlc.detachEvent) {
 +
            // Microsoft
 +
            vlc.detachEvent (event, handler);
 +
        } else if (vlc.removeEventListener) {
 +
            // Mozilla: DOM level 2
 +
            vlc.removeEventListener (event, handler, false);
 +
        }
 +
    }
 +
}
 +
// event callbacks
 +
function handle_MediaPlayerNothingSpecial(){
 +
    console.log("Idle");
 +
}
 +
function handle_MediaPlayerOpening(){
 +
    console.log("Opening");
 +
}
 +
function handle_MediaPlayerBuffering(val){
 +
    console.log("Buffering: " + val + "%");
 +
}
 +
function handle_MediaPlayerPlaying(){
 +
    console.log("Playing");
 +
}
 +
function handle_MediaPlayerPaused(){
 +
    console.log("Paused");
 +
}
 +
function handle_MediaPlayerStopped(){
 +
    console.log("Stopped");
 +
}
 +
function handle_MediaPlayerStopAsyncDone(){
 +
    console.log("Stopped asynchronously");
 +
}
 +
function handle_MediaPlayerForward(){
 +
    console.log("Forward");
 +
}
 +
function handle_MediaPlayerBackward(){
 +
    console.log("Backward");
 +
}
 +
function handle_MediaPlayerEndReached(){
 +
    console.log("EndReached");
 +
}
 +
function handle_MediaPlayerEncounteredError(){
 +
    console.log("EncounteredError");
 +
}
 +
function handle_MediaPlayerTimeChanged(time){
 +
    console.log("Time changed: " + time + " ms");
 +
}
 +
function handle_MediaPlayerPositionChanged(val){
 +
    console.log("Position changed: " + val);
 +
}
 +
function handle_MediaPlayerSeekableChanged(val){
 +
    console.log("Seekable changed: " + val);
 +
}
 +
function handle_MediaPlayerPausableChanged(val){
 +
    console.log("Pausable changed: " + val);
 +
}
 +
function handle_MediaPlayerMediaChanged(){
 +
    console.log("Media changed");
 +
}
 +
function handle_MediaPlayerTitleChanged(val){
 +
    console.log("Title changed: " + val);
 +
}
 +
function handle_MediaPlayerChapterChanged(val){
 +
    console.log("Chapter changed: " + val);
 +
}
 +
function handle_MediaPlayerLengthChanged(val){
 +
    console.log("Length changed: " + val + " ms");
 +
}
 +
function handle_MediaPlayerVout(val){
 +
    console.log("Number of video output changed: " + val);
 +
}
 +
function handle_MediaPlayerMuted(){
 +
    console.log("Audio volume muted");
 +
}
 +
function handle_MediaPlayerUnmuted(){
 +
    console.log("Audio volume unmuted");
 +
}
 +
function handle_MediaPlayerAudioVolume(volume){
 +
    console.log("Audio volume changed: " + Math.round(volume * 100) + "%");
 +
}
 +
// Register a bunch of callbacks.
 +
registerVLCEvent("MediaPlayerNothingSpecial", handle_MediaPlayerNothingSpecial);
 +
registerVLCEvent("MediaPlayerOpening", handle_MediaPlayerOpening);
 +
registerVLCEvent("MediaPlayerBuffering", handle_MediaPlayerBuffering);
 +
registerVLCEvent("MediaPlayerPlaying", handle_MediaPlayerPlaying);
 +
registerVLCEvent("MediaPlayerPaused", handle_MediaPlayerPaused);
 +
registerVLCEvent("MediaPlayerStopped", handle_MediaPlayerStopped);
 +
registerVLCEvent("MediaPlayerStopAsyncDone", handle_MediaPlayerStopAsyncDone);
 +
registerVLCEvent("MediaPlayerForward", handle_MediaPlayerForward);
 +
registerVLCEvent("MediaPlayerBackward", handle_MediaPlayerBackward);
 +
registerVLCEvent("MediaPlayerEndReached", handle_MediaPlayerEndReached);
 +
registerVLCEvent("MediaPlayerEncounteredError", handle_MediaPlayerEncounteredError);
 +
registerVLCEvent("MediaPlayerTimeChanged", handle_MediaPlayerTimeChanged);
 +
registerVLCEvent("MediaPlayerPositionChanged", handle_MediaPlayerPositionChanged);
 +
registerVLCEvent("MediaPlayerSeekableChanged", handle_MediaPlayerSeekableChanged);
 +
registerVLCEvent("MediaPlayerPausableChanged", handle_MediaPlayerPausableChanged);
 +
registerVLCEvent("MediaPlayerMediaChanged", handle_MediaPlayerMediaChanged);
 +
registerVLCEvent("MediaPlayerTitleChanged", handle_MediaPlayerTitleChanged);
 +
registerVLCEvent("MediaPlayerChapterChanged", handle_MediaPlayerChapterChanged);
 +
registerVLCEvent("MediaPlayerLengthChanged", handle_MediaPlayerLengthChanged);
 +
registerVLCEvent("MediaPlayerVout", handle_MediaPlayerVout);
 +
registerVLCEvent("MediaPlayerMuted", handle_MediaPlayerMuted);
 +
registerVLCEvent("MediaPlayerUnmuted", handle_MediaPlayerUnmuted);
 +
registerVLCEvent("MediaPlayerAudioVolume", handle_MediaPlayerAudioVolume);
 +
//-->
 +
</syntaxhighlight><syntaxhighlight lang="html5" start="119" line>
 +
</script>
 +
</syntaxhighlight>
 +
 
 +
==== Event registration issue with IE11 ====
 +
Since IE11, the methods attachEvent() and detachEvent() are not longer available. So the registration of events is not possible. But there are two workarounds:
 +
 
 +
Workaround 1 - Use the IE10 compatibility mode to re-enable the missing methods. For using the compatibility mode, add this meta tag to the header of your page:
 +
<syntaxhighlight lang="html5" line>
 +
<meta http-equiv="X-UA-Compatible" content="IE=10"/>
 +
</syntaxhighlight>
 +
 
 +
Workaround 2 - Use an old IE-only implementation of event registration. An example with the MediaPlayerBuffering event:
 +
<syntaxhighlight lang="javascript" line>
 +
<script for="vlc" event="MediaPlayerBuffering(val)">
 +
console.log("Buffering: " + val + "%");
 +
</script>
 +
</syntaxhighlight>
 +
 
 +
=== Audio object  ===
  
−
====Audio object====
+
readonly properties
  
−
readonly properties
+
*'''vlc.audio.count''': (supported in vlc version ≥ 1.1.0) returns the number of audio track available.
−
*'''vlc.audio.count''': (supported in vlc version >= 1.1.0) returns the number of audio track available.
 
  
−
read/write properties
+
read/write properties  
−
*'''vlc.audio.mute''': boolean value to mute and ummute the audio.
+
 
−
*'''vlc.audio.volume''': a value between [0-200] which indicates a percentage of the volume.
+
*'''vlc.audio.mute''': boolean value to mute and unmute the audio.  
−
*'''vlc.audio.track''': (supported in vlc version > 0.8.6) a value between [1-65535] which indicates the audio track to play or that is playing. a value of 0 means the audio is/will be disabled.
+
*'''vlc.audio.volume''': a value between [0-200] which indicates a percentage of the volume.  
 +
*'''vlc.audio.track''': (supported in vlc version > 0.8.6) a value between [1-65535] which indicates the audio track to play or that is playing. a value of 0 means the audio is/will be disabled.  
 
*'''vlc.audio.channel''': (supported in vlc version > 0.8.6) integer value between [1-5] that indicates which audio channel mode is used, values can be: "1=stereo", "2=reverse stereo", "3=left", "4=right", "5=dolby". Use vlc.audio.channel to check if setting of the audio channel mode has succeeded.
 
*'''vlc.audio.channel''': (supported in vlc version > 0.8.6) integer value between [1-5] that indicates which audio channel mode is used, values can be: "1=stereo", "2=reverse stereo", "3=left", "4=right", "5=dolby". Use vlc.audio.channel to check if setting of the audio channel mode has succeeded.
  
−
Audio Channel:
+
methods
−
<SELECT readonly onChange='doAudioChannel(this.value)'>
+
 
−
    <OPTION value=1>Stereo</OPTION>
+
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state.
−
    <OPTION value=2>Reverse stereo</OPTION>
+
*'''vlc.audio.description(int i)''': (supported in vlc version ≥ 1.1.0) give the i-th audio track name. 0 corresponds to disable and 1 to the first audio track.
−
    <OPTION value=3>Left</OPTION>
+
 
−
    <OPTION value=4>Right</OPTION>
+
==== Example ====
−
    <OPTION value=5>Dolby</OPTION>
 
−
</SELECT>
 
  
−
<SCRIPT language="javascript">
+
<syntaxhighlight lang="html5" line>
−
&lt;!--
+
Audio Channel:
−
function doAudioChannel(value)
+
<select onChange='doAudioChannel(this.value)'>
−
{
+
    <option value=1>Stereo</option>
 +
    <option value=2>Reverse stereo</option>
 +
    <option value=3>Left</option>
 +
    <option value=4>Right</option>
 +
    <option value=5>Dolby</option>
 +
</select>
 +
<script type="text/javascript">
 +
</syntaxhighlight><syntaxhighlight lang="javascript" line start="10">
 +
<!--
 +
function doAudioChannel(value)
 +
{
 
     var vlc = getVLC("vlc");
 
     var vlc = getVLC("vlc");
 
     vlc.audio.channel = parseInt(value);
 
     vlc.audio.channel = parseInt(value);
 
     alert(vlc.audio.channel);
 
     alert(vlc.audio.channel);
−
};
+
}
−
--&gt;
+
//-->
 +
</syntaxhighlight><syntaxhighlight lang="html5" line start="18">
 +
</script>
 +
</syntaxhighlight>
  
−
methods
+
=== Input object  ===
−
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state.
 
−
*'''vlc.audio.description(int i)''': (supported in vlc version >= 1.1.0) give the i-th audio track name. 0 corresponds to disable and 1 to the first audio track.
 
  
−
====Input object====
+
readonly properties
  
−
readonly properties
 
 
*'''vlc.input.length''': length of the input file in number of milliseconds. 0 is returned for 'live' streams or clips whose length cannot be determined by VLC. It returns -1 if no input is playing.  
 
*'''vlc.input.length''': length of the input file in number of milliseconds. 0 is returned for 'live' streams or clips whose length cannot be determined by VLC. It returns -1 if no input is playing.  
−
*'''vlc.input.fps''': frames per second returned as a float (typically 60.0, 50.0, 23.976, etc...)
+
*'''vlc.input.fps''': frames per second returned as a float (typically 60.0, 50.0, 23.976, etc...)  
 
*'''vlc.input.hasVout''': a boolean that returns true when the video is being displayed, it returns false when video is not displayed
 
*'''vlc.input.hasVout''': a boolean that returns true when the video is being displayed, it returns false when video is not displayed
  
−
read/write properties
+
read/write properties  
−
*'''vlc.input.position''': normalized position in multimedia stream item given as a float value between [0.0 - 1.0]
+
 
 +
*'''vlc.input.position''': normalized position in multimedia stream item given as a float value between [0.0 - 1.0]  
 
*'''vlc.input.time''': the absolute position in time given in milliseconds, this property can be used to seek through the stream
 
*'''vlc.input.time''': the absolute position in time given in milliseconds, this property can be used to seek through the stream
−
  &lt;!-- absolute seek in stream !--&gt;
+
 
−
  vlc.input.time = &lt;absolute seek&gt;
+
<syntaxhighlight lang="javascript">
−
  &lt;!-- relative seek in stream !--&gt;
+
  <!-- absolute seek in stream -->
−
  vlc.input.time = vlc.input.time + &lt;relative seek&gt;
+
  vlc.input.time = <absolute seek>
−
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ENDED=6, ERROR=7). Note: Test for ENDED=6 to catch end of playback. Checking for STOPPING=5 is NOT ENOUGH.
+
  <!-- relative seek in stream -->
 +
  vlc.input.time = vlc.input.time + <relative seek>
 +
</syntaxhighlight>
 +
 
 +
*'''vlc.input.state''': current state of the input chain given as enumeration:
 +
{| class="wikitable"
 +
|-
 +
| 0 || IDLE
 +
|-
 +
| 1 || OPENING
 +
|-
 +
| 2 || BUFFERING
 +
|-
 +
| 3 || PLAYING
 +
|-
 +
| 4 || PAUSED
 +
|-
 +
| 5 || STOPPING
 +
|-
 +
| 6 || ENDED
 +
|-
 +
| 7 || ERROR
 +
|}
 +
 
 +
Note: Test for ENDED=6 to catch end of playback. Checking for STOPPING=5 is NOT ENOUGH.  
 
*'''vlc.input.rate''': input speed given as float (1.0 for normal speed, 0.5 for half speed, 2.0 for twice as fast, etc.).
 
*'''vlc.input.rate''': input speed given as float (1.0 for normal speed, 0.5 for half speed, 2.0 for twice as fast, etc.).
−
rate &gt; 1              : is fastforward
 
−
rate &gt; 0 and rate &lt; 1 : is slow motion
 
−
rate &lt; 0              : is rewind
 
  
−
methods
+
{| class="wikitable"
 +
|-
 +
| rate > 1 || fast forward
 +
|-
 +
| rate = 1 || normal speed
 +
|-
 +
| rate < 1 || slow motion
 +
|}
 +
 
 +
methods  
 +
 
 
*''none''
 
*''none''
  
−
====Playlist object====
+
==== Title object ====
 +
 
 +
readonly properties
 +
 
 +
*'''vlc.input.title.count''': (supported in vlc version ≥ 2.2.2) returns the number of title available.
 +
 
 +
read/write properties
 +
 
 +
*'''vlc.input.title.track''': (supported in vlc version ≥ 2.2.2) get and set the title track. The property takes an integer as input value [0..65535]. It returns -1 if no titles are available.
 +
 
 +
methods
 +
 
 +
*'''vlc.input.title.description(int i)''': (supported in vlc version ≥ 2.2.2) give the i-th title name.
 +
 
 +
==== Chapter object  ====
 +
 
 +
readonly properties
 +
 
 +
*'''vlc.input.chapter.count''': (supported in vlc version ≥ 2.2.2) returns the number of chapter available in the current title.
 +
 
 +
read/write properties
  
−
readonly properties
+
*'''vlc.input.chapter.track''': (supported in vlc version ≥ 2.2.2) get and set the chapter track. The property takes an integer as input value [0..65535]. It returns -1 if no chapters are available.
−
*'''vlc.playlist.itemCount''': number that returns the amount of items currently in the playlist ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])
+
 
−
*'''vlc.playlist.isPlaying''': a boolean that returns true if the current playlist item is playing and false when it is not playing
+
methods
−
*'''vlc.playlist.items''': return the playlist items collection, see [[#Playlist_items_object| Playlist items]]
+
 
 +
*'''vlc.input.chapter.description(int i)''': (supported in vlc version ≥ 2.2.2) give the i-th chapter name.
 +
*'''vlc.input.chapter.countForTitle(int i)''': (supported in vlc version ≥ 2.2.2) returns the number of chapter available for a specific title.
 +
*'''vlc.input.chapter.prev()''': (supported in vlc version ≥ 2.2.2) play the previous chapter.
 +
*'''vlc.input.chapter.next()''': (supported in vlc version ≥ 2.2.2) play the next chapter.
 +
 
 +
=== Playlist object ===
 +
 
 +
readonly properties  
 +
 
 +
*'''vlc.playlist.itemCount''': number that returns the amount of items currently in the playlist ('''deprecated''', do not use, see [[#Playlist_items_object|Playlist items]])  
 +
*'''vlc.playlist.isPlaying''': a boolean that returns true if the current playlist item is playing and false when it is not playing  
 +
*'''vlc.playlist.currentItem''': (supported in vlc version ≥ 2.2.0) number that returns the index of the current item in the playlist. It returns -1 if the playlist is empty or no item is active.
 +
*'''vlc.playlist.items''': return the playlist items collection, see [[#Playlist_items_object|Playlist items]]
 +
 
 +
read/write properties
  
−
read/write properties
 
 
*''none''
 
*''none''
  
−
methods
+
methods  
−
*'''vlc.playlist.add(mrl)''': add a playlist item as [[MRL]]. The MRL must be given as a string. Returns a number as an item identifier in playlist (this is not a position  in playlist).
+
 
−
*'''vlc.playlist.add(mrl,name,options)''': add a playlist item as MRL, with metaname 'name' and options 'options'. options are text arguments which can be provided either as a single string containing space separated values, akin to VLC command line, or as an array of string values. Returns a number as an item identifier in playlist (this is not a position in playlist).
+
*'''vlc.playlist.add(mrl)''': add a playlist item as [[MRL]]. The MRL must be given as a string. Returns the index of the just added item in the playlist as a number.
−
  var options = new Array(":aspect-ratio=4:3", "--rtsp-tcp");
+
*'''vlc.playlist.add(mrl,name,options)''': add a playlist item as MRL, with metaname 'name' and options 'options'. options are text arguments which can be provided either as a single string containing space separated values, akin to VLC command line, or as an array of string values. Returns the index of the just added item in the playlist as a number.
−
  var id = vlc.playlist.add("rtsp://servername/item/to/play", "fancy name", options);
+
 
−
  vlc.playlist.playItem(id);
+
<syntaxhighlight lang="javascript" line>
−
*'''vlc.playlist.play()''': start playing the current playlist item
+
var options = new Array(":aspect-ratio=4:3", "--rtsp-tcp");
−
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
+
// Or: var options = ":aspect-ratio=4:3 --rtsp-tcp";
−
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
+
var id = vlc.playlist.add("rtsp://servername/item/to/play", "fancy name", options);
−
*'''vlc.playlist.stop()''': stop playing the current playlist item
+
vlc.playlist.playItem(id);
−
*'''vlc.playlist.next()''': iterate to the next playlist item
+
</syntaxhighlight>
−
*'''vlc.playlist.prev()''': iterate to the previous playlist item
+
 
−
*'''vlc.playlist.clear()''': empty the current playlist, all items will be deleted from the playlist ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])
+
*'''vlc.playlist.play()''': start playing the current playlist item  
−
*'''vlc.playlist.removeItem(number)''': remove the item from playlist whose identifier is number <!-- (note: this number isn't the position in the playlist, but the number given by vlc.playlist.add() ) --> ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])
+
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number  
 +
*'''vlc.playlist.pause()''': pause the current playlist item
 +
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item  
 +
*'''vlc.playlist.stop()''': stop playing the current playlist item  
 +
*'''vlc.playlist.stop_async()''': (supported in vlc version ≥ 3.0.0) stop playing the current playlist item asynchronously and fire the event MediaPlayerStopAsyncDone, if done
 +
*'''vlc.playlist.next()''': iterate to the next playlist item  
 +
*'''vlc.playlist.prev()''': iterate to the previous playlist item  
 +
*'''vlc.playlist.clear()''': empty the current playlist, all items will be deleted from the playlist ('''deprecated''', do not use, see [[#Playlist_items_object|Playlist items]])  
 +
*'''vlc.playlist.removeItem(number)''': remove the item from playlist whose identifier is number <!-- (note: this number isn't the position in the playlist, but the number given by vlc.playlist.add() ) --> ('''deprecated''', do not use, see [[#Playlist_items_object|Playlist items]])
 +
*'''vlc.playlist.parse(options, timeout)''': (supported in vlc version ≥ 3.0.0) Parse the first media in the playlist. This fetches (local or network) art, meta data and/or tracks information. A timeout for parsing can be set in milliseconds or to indefinitely (0). Returns the parsed status.
 +
 
 +
Available options flags for parsing (which can be combined):
 +
{| class="wikitable"
 +
|-
 +
| 0 || Parse media if it's a local file.
 +
|-
 +
| 1 || Parse media even if it's a network file.
 +
|-
 +
| 2 || Fetch meta and covert art using local resources.
 +
|-
 +
| 4 || Fetch meta and covert art using network resources.
 +
|-
 +
| 8 || Interact with the user. Set this flag in order to receive a callback when the input is asking for credentials.
 +
|}
 +
 
 +
Parsed status given as enumeration:
 +
{| class="wikitable"
 +
|-
 +
| 1 || skipped
 +
|-
 +
| 2 || failed
 +
|-
 +
| 3 || timeout
 +
|-
 +
| 4 || done
 +
|}
 +
 
 +
==== Playlist items object  ====
  
−
====Playlist items object====
+
readonly properties
  
−
readonly properties
 
 
*'''vlc.playlist.items.count''': number of items currently in the playlist
 
*'''vlc.playlist.items.count''': number of items currently in the playlist
  
−
read/write properties
+
read/write properties  
 +
 
 
*''none''
 
*''none''
  
−
methods
+
methods  
−
*'''vlc.playlist.items.clear()''': empty the current playlist, all items will be deleted from the playlist. If a movie is playing, it stop. Note that when this method returns, playlist may not have been entirely been cleared as this operation is performed asynchronously; use the ''count'' property to verify/wait until the playlist is empty.
+
 
−
*'''vlc.playlist.items.remove(number)''': remove the item whose identifier is number from playlist. (note: this number isn't the position in the playlist, but the number given by vlc.playlist.add() )
+
*'''vlc.playlist.items.clear()''': empty the current playlist, all items will be deleted from the playlist. (note: if a movie is playing, it will not stop)
 +
*'''vlc.playlist.items.remove(number)''': remove the item whose identifier is number from playlist. (note: this number is the current position in the playlist. It's not the number given by vlc.playlist.add(), if any items of the playlist were removed in the meantime.)
  
−
====Subtitle object====
+
=== Subtitle object ===
  
−
readonly properties
+
readonly properties  
  
−
*'''vlc.subtitle.count''': (supported in vlc version >= 1.1.0) returns the number of subtitle available.
+
*'''vlc.subtitle.count''': (supported in vlc version ≥ 1.1.0) returns the number of subtitle available.
  
 
read/write properties  
 
read/write properties  
  
−
*'''vlc.subtitle.track''': (supported in vlc version >= 1.1.0) get and set the subtitle track to show on the video screen. The property takes an integer as input value [1..65535]. If subtitle track is set to 0, the subtitles will be disabled. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.
+
*'''vlc.subtitle.track''': (supported in vlc version ≥ 1.1.0) get and set the subtitle track to show on the video screen. The property takes an integer as input value [1..65535]. If subtitle track is set to 0, the subtitles will be disabled.
 +
 
 +
methods
  
−
methods
+
*'''vlc.subtitle.description(int i)''': (supported in vlc version ≥ 1.1.0) give the i-th subtitle name. 0 correspond to disable and 1 to the first subtitle.
  
−
*'''vlc.subtitle.description(int i)''': (supported in vlc version >= 1.1.0) give the i-th subtitle name. 0 correspond to disable and 1 to the first subtitle.
+
=== Video object  ===
  
−
====Video object====
+
readonly properties
  
−
readonly properties
+
*'''vlc.video.width''': returns the horizontal size of the video  
−
*'''vlc.video.width''': returns the horizontal size of the video
 
 
*'''vlc.video.height''': returns the vertical size of the video
 
*'''vlc.video.height''': returns the vertical size of the video
 +
*'''vlc.video.count''': (supported in vlc version ≥ 2.2.7) returns the number of video track available.
 +
 +
read/write properties
 +
 +
*'''vlc.video.fullscreen''': when set to true the video will be displayed in fullscreen mode, when set to false the video will be shown inside the video output size. The property takes a boolean as input.
 +
*'''vlc.video.aspectRatio''': get and set the aspect ratio to use in the video screen. The property takes a string as input value. Typical values are: "1:1", "4:3", "16:9", "16:10", "221:100" and "5:4"
 +
*'''vlc.video.scale''': (supported in vlc version ≥ 3.0.0) get and set the video scaling factor as float. That is the ratio of the number of pixels on screen to the number of pixels in the original decoded video in each dimension. Zero is a special value; it will adjust the video to the output window.
 +
*'''vlc.video.subtitle''': (supported in vlc version > 0.8.6a) get and set the subtitle track to show on the video screen. The property takes an integer as input value [1..65535]. If subtitle track is set to 0, the subtitles will be disabled.
 +
*'''vlc.video.crop''': (removed with vlc version 4.0.0) get and set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>. A possible value is: "120x120+10+10"
 +
*'''vlc.video.teletext''': (supported in vlc version ≥ 0.9.0) get and set teletext page to show on the video stream. This will only work if a teletext elementary stream is available in the video stream. The property takes an integer as input value [0..1000] for indicating the teletext page to view, setting the value to 0 means hide teletext.
 +
*'''vlc.video.track''': (supported in vlc version ≥ 2.2.7) a value between [1-65535] which indicates the video track to play or that is playing. a value of 0 means the video is/will be disabled.
 +
 +
methods
 +
 +
*'''vlc.video.takeSnapshot()''': (supported in vlc version ≥ 0.9.0, only for ActiveX) generates a snapshot and saves it on the desktop
 +
*'''vlc.video.toggleFullscreen()''': toggle the fullscreen mode based on the previous setting
 +
*'''vlc.video.toggleTeletext()''': (supported in vlc version ≥ 0.9.0) toggle the teletext page to overlay transparent or not, based on the previous setting
 +
*'''vlc.video.description(int i)''': (supported in vlc version ≥ 2.2.7) give the i-th video track name. 0 corresponds to disable and 1 to the first video track.
 +
*'''vlc.video.crop_ratio(int numerator, int denominator)''': (supported in vlc version ≥ 4.0.0) Forces a crop ratio on any and all video tracks rendered by the media player. To disable video crop, set a crop ratio with zero as denominator.
 +
*'''vlc.video.crop_window(int x, int y, int width, int height)''': (supported in vlc version ≥ 4.0.0) Selects a sub-rectangle of video to show. Any pixels outside the rectangle will not be shown. To unset the video crop window, use vlc.video.crop_ratio() or vlc.video.crop_border().
 +
*'''vlc.video.crop_border(int left, int right, int top, int bottom)''': (supported in vlc version ≥ 4.0.0) Selects the size of video edges to be cropped out. To unset the video crop borders, set all borders to zero.
 +
 +
==== Deinterlace Object  ====
 +
 +
readonly properties
 +
 +
*''none''
 +
 +
read/write properties
  
−
read/write properties
+
*''none''
−
*'''vlc.video.fullscreen''': when set to true the video will be displayed in fullscreen mode, when set to false the video will be shown inside the video output size. The property takes a boolean as input.
 
−
*'''vlc.video.aspectRatio''': get and set the aspect ratio to use in the video screen. The property takes a string as input value. Typical values are: "1:1", "4:3", "16:9", "16:10", "221:100" and "5:4"
 
−
*'''vlc.video.subtitle''': (supported in vlc version > 0.8.6a) get and set the subtitle track to show on the video screen. The property takes an integer as input value [1..65535]. If subtitle track is set to 0, the subtitles will be disabled. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.
 
−
*'''vlc.video.teletext''': (supported in vlc version >= 0.9.0) get and set teletext page to show on the video stream. This will only work if a teletext elementary stream is available in the video stream. The property takes an integer as input value [0..999] for indicating the teletext page to view, setting the value to 0 means hide teletext. On error it will return -1 and display an error message.
 
  
−
methods
+
methods  
−
*'''vlc.video.toggleFullscreen()''': toggle the fullscreen mode based on the previous setting
 
−
*'''vlc.video.toggleTeletext()''': (supported in vlc version >= 0.9.0) toggle the teletext page to overlay transparent or not, based on the previous setting
 
−
*'''vlc.video.deinterlaceEnable("my_mode")''': (supported in vlc version >= 1.1.0) enable deinterlacing with my_mode. You can enable it with "blend", "bob", "discard", "linear", "mean" or "x" mode. Enabling too soon deinterlacing may cause some problems. You have to wait that all variable are available before enabling it.
 
−
*'''vlc.video.deinterlaceDisable()''': (supported in vlc version >= 1.1.0) disable deinterlacing.
 
  
−
=====Marquee Object=====
+
*'''vlc.video.deinterlace.enable("my_mode")''': (supported in vlc version ≥ 1.1.0) enable deinterlacing with my_mode. You can enable it with "blend", "bob", "discard", "linear", "mean", "x", "yadif" or "yadif2x" mode. Enabling too soon deinterlacing may cause some problems. You have to wait that all variable are available before enabling it.
 +
*'''vlc.video.deinterlace.disable()''': (supported in vlc version ≥ 1.1.0) disable deinterlacing.
  
−
readonly properties
+
==== Marquee Object  ====
  
−
* ''none''
+
readonly properties
  
−
read/write properties
+
*''none''
  
−
* ''none''
+
read/write properties
  
−
methods
+
*'''vlc.video.marquee.text''': (supported in vlc version ≥ 1.1.0, since vlc version 4.0.0 writeonly) display my text on the screen.
−
*'''vlc.video.marquee.enable()''': (supported in vlc version >= 1.1.0) enable marquee filter.
+
*'''vlc.video.marquee.color''': (supported in vlc version ≥ 1.1.0) change the text color. val is the new color to use (WHITE=0x000000, BLACK=0xFFFFFF, RED=0xFF0000, GREEN=0x00FF00, BLUE=0x0000FF...).  
−
*'''vlc.video.marquee.disable()''': (supported in vlc version >= 1.1.0) disable marquee filter.
+
*'''vlc.video.marquee.opacity''': (supported in vlc version ≥ 1.1.0) change the text opacity, val is defined from 0 (completely transparent) to 255 (completely opaque).  
−
*'''vlc.video.marquee.text("my text")''': (supported in vlc version >= 1.1.0) display my text on the screen.
+
*'''vlc.video.marquee.position''': (supported in vlc version ≥ 1.1.0) change the text position ("center", "left", "right", "top", "top-left", "top-right", "bottom", "bottom-left", "bottom-right").  
−
*'''vlc.video.marquee.color(int val)''': (supported in vlc version >= 1.1.0) change the text color. val is the new color to use (WHITE=0x000000, BLACK=0xFFFFFF, RED=0xFF0000, GREEN=0x00FF00, BLUE=0x0000FF...).
+
*'''vlc.video.marquee.refresh''': (supported in vlc version ≥ 1.1.0) change the marquee refresh period.  
−
*'''vlc.video.marquee.opacity(int val)''': (supported in vlc version >= 1.1.0) change the text opacity, val is defined from 0 (completely transparent) to 255 (completely opaque).
+
*'''vlc.video.marquee.size''': (supported in vlc version ≥ 1.1.0) val define the new size for the text displayed on the screen. If the text is bigger than the screen then the text is not displayed.  
−
*'''vlc.video.marquee.position(int val)''': (supported in vlc version >= 1.1.0) change the text position (CENTER=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
+
*'''vlc.video.marquee.timeout''': (supported in vlc version ≥ 1.1.0) change the timeout value. val is defined in ms, but 0 value correspond to unlimited.  
−
*'''vlc.video.marquee.refresh(int val)''': (supported in vlc version >= 1.1.0) change the marquee refresh period.
+
*'''vlc.video.marquee.x''': (supported in vlc version ≥ 1.1.0) change text abscissa.  
−
*'''vlc.video.marquee.size(int val)''': (supported in vlc version >= 1.1.0) val define the new size for the text displayed on the screen. If the text is bigger than the screen then the text is not displayed.
+
*'''vlc.video.marquee.y''': (supported in vlc version ≥ 1.1.0) change text ordinate.
−
*'''vlc.video.marquee.timeout(int val)''': (supported in vlc version >= 1.1.0) change the timeout value. val is defined in ms, but 0 value correspond to unlimited.
 
−
*'''vlc.video.marquee.x(int val)''': (supported in vlc version >= 1.1.0) change text abscissa.
 
−
*'''vlc.video.marquee.y(int val)''': (supported in vlc version >= 1.1.0) change text ordinate.
 
  
−
Some problems may happen (option like color or text will not be applyed) because of the VLC asynchronous functioning. To avoid it, after enabling marquee, you have to wait a little time before changing an option. But it should be fixed by the new vout implementation.
+
methods
  
−
====Log object====
+
*'''vlc.video.marquee.enable()''': (supported in vlc version ≥ 1.1.0) enable marquee filter.  
−
: '''CAUTION''': For security concern, VLC 1.0.0-rc1 is probably the latest (near-to-stable) version in which this object and its children are supported.
+
*'''vlc.video.marquee.disable()''': (supported in vlc version ≥ 1.1.0) disable marquee filter.
  
 +
Some problems may happen (option like color or text will not be applied) because of the VLC asynchronous functioning. To avoid it, after enabling marquee, you have to wait a little time before changing an option. But it should be fixed by the new vout implementation.
  
−
This object allows accessing VLC main message logging queue. Typically this queue capacity is very small (no nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.
+
NOTE: see [https://forum.videolan.org/viewtopic.php?f=16&t=89427#p295058 this forum post]
  
−
readonly properties
+
==== Logo Object  ====
−
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]
 
  
−
read/write properties
+
readonly properties  
−
*'''vlc.log.verbosity''': write number [-1,0,1,2,3] for changing the verbosity level of the log messages; messages whose verbosity is higher than set will be not be logged in the queue. The numbers have the following meaning: -1 disable, 0 info, 1 error, 2 warning, 3 debug.
 
  
−
methods
 
 
*''none''
 
*''none''
  
−
====Messages object====
+
read/write properties
  
−
readonly properties
+
*'''vlc.video.logo.opacity''': (supported in vlc version ≥ 1.1.0) change the picture opacity, val is defined from 0 (completely transparent) to 255 (completely opaque).
−
*'''messages.count''': returns number of messages in the log
+
*'''vlc.video.logo.position''': (supported in vlc version ≥ 1.1.0) change the text position ("center", "left", "right", "top", "top-left", "top-right", "bottom", "bottom-left", "bottom-right").
 +
*'''vlc.video.logo.delay''': (supported in vlc version ≥ 1.1.0) display each picture for a duration of 1000 ms (default) before displaying the next picture.
 +
*'''vlc.video.logo.repeat''': (supported in vlc version ≥ 1.1.0) number of loops for picture animation (-1=continuous, 0=disabled, n=n-times). The default is -1 (continuous).
 +
*'''vlc.video.logo.x''': (supported in vlc version ≥ 1.1.0) change the x-offset for displaying the picture counting from top-left on the screen.
 +
*'''vlc.video.logo.y''': (supported in vlc version ≥ 1.1.0) change the y-offset for displaying the picture counting from top-left on the screen.
 +
 
 +
methods
 +
 
 +
*'''vlc.video.logo.enable()''': (supported in vlc version ≥ 1.1.0) enable logo video filter.
 +
*'''vlc.video.logo.disable()''': (supported in vlc version ≥ 1.1.0) disable logo video filter.
 +
*'''vlc.video.logo.file("file.png")''': (supported in vlc version ≥ 1.1.0) display my file.png as logo on the screen.
 +
 
 +
Some problems may happen because of the VLC asynchronous functioning. To avoid it, after enabling logo video filter, you have to wait a little time before changing an option. But it should be fixed by the new vout implementation.
 +
 
 +
=== MediaDescription Object  ===
 +
 
 +
readonly properties  
 +
 
 +
*'''vlc.mediaDescription.title''': (supported in vlc version ≥ 2.0.2) returns title meta information field.
 +
*'''vlc.mediaDescription.artist''': (supported in vlc version ≥ 2.0.2) returns artist meta information field.
 +
*'''vlc.mediaDescription.genre''': (supported in vlc version ≥ 2.0.2) returns genre meta information field.
 +
*'''vlc.mediaDescription.copyright''': (supported in vlc version ≥ 2.0.2) returns copyright meta information field.
 +
*'''vlc.mediaDescription.album''': (supported in vlc version ≥ 2.0.2) returns album meta information field.
 +
*'''vlc.mediaDescription.trackNumber''': (supported in vlc version ≥ 2.0.2) returns trackNumber meta information field.
 +
*'''vlc.mediaDescription.description''': (supported in vlc version ≥ 2.0.2) returns description meta information field.
 +
*'''vlc.mediaDescription.rating''': (supported in vlc version ≥ 2.0.2) returns rating meta information field.
 +
*'''vlc.mediaDescription.date''': (supported in vlc version ≥ 2.0.2) returns date meta information field.
 +
*'''vlc.mediaDescription.setting''': (supported in vlc version ≥ 2.0.2) returns setting meta information field.
 +
*'''vlc.mediaDescription.URL''': (supported in vlc version ≥ 2.0.2) returns URL meta information field.
 +
*'''vlc.mediaDescription.language''': (supported in vlc version ≥ 2.0.2) returns language meta information field.
 +
*'''vlc.mediaDescription.nowPlaying''': (supported in vlc version ≥ 2.0.2) returns nowPlaying meta information field.
 +
*'''vlc.mediaDescription.publisher''': (supported in vlc version ≥ 2.0.2) returns publisher meta information field.
 +
*'''vlc.mediaDescription.encodedBy''': (supported in vlc version ≥ 2.0.2) returns encodedBy meta information field.
 +
*'''vlc.mediaDescription.artworkURL''': (supported in vlc version ≥ 2.0.2) returns artworkURL meta information field.
 +
*'''vlc.mediaDescription.trackID''': (supported in vlc version ≥ 2.0.2) returns trackID meta information field.
 +
 
 +
read/write properties
  
−
read/write properties
 
 
*''none''
 
*''none''
  
 
methods
 
methods
−
*'''messages.clear()''': clear the current log buffer. It should be called as frequently as possible to not overflow the message queue. Call this method after the log messages of interest are read.
 
−
*'''messages.iterator()''': creates and returns an iterator object, used to iterate over the messages in the log. '''Don't clear the log buffer while holding an iterator object.'''
 
  
−
====Messages Iterator object====
+
*''none''
 +
 
 +
=== DEPRECATED APIs ===
 +
==== DEPRECATED: Log object ====
 +
 
 +
:'''CAUTION''': For security concern, VLC 1.0.0-rc1 is the latest (near-to-stable) version in which this object and its children are supported.
 +
 
 +
This object allows accessing VLC main message logging queue. Typically this queue capacity is very small (no more than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.
  
−
readonly properties
+
readonly properties  
−
*'''iterator.hasNext''': returns a boolean that indicates whether ''vlc.log.messages.next()'' will return the next message.
 
  
−
read/write properties
+
*'''vlc.log.messages''': returns the message collection, see [[#DEPRECATED:_Messages_object|Messages object]]
−
*''none''
 
  
−
methods
+
read/write properties
−
*'''iterator.next()''': returns the next message object in the log, see [[Message object]]
 
  
−
====Message object====
+
*'''vlc.log.verbosity''': write number [-1,0,1,2,3] for changing the verbosity level of the log messages; messages whose verbosity is higher than set will be not be logged in the queue. The numbers have the following meaning: -1 disable, 0 info, 1 error, 2 warning, 3 debug.
  
−
*'''message.severity''': number that indicates the severity of the log message (0 = info, 1 = error, 2 = warning, 3 = debug)
+
methods
−
*'''message.name''': name of VLC module that printed the log message (e.g: main, http, directx, etc...)
 
−
*'''message.type''': type of VLC module that printed the log message (eg: input, access, vout, sout, etc...)
 
−
*'''message.message''': the message text
 
  
−
==Build HTML pages that use the plugin (VLC version up to 0.8.5)==
+
*''none''
  
−
'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,
+
==== DEPRECATED: Messages object  ====
  
−
The following API description is only valid uptill version 0.8.5 of the mozilla plugin.
+
:'''CAUTION''': For security concern, VLC 1.0.0-rc1 is the latest (near-to-stable) version in which this object and its children are supported.
  
−
Additionally to viewing video on all pages, you can build custom pages that will use the advanced features of the plugin, using Javascript functions to control playback or extract information from the
+
readonly properties
−
plugin.
 
  
−
The vlc plugin supports the following function calls:
+
*'''messages.count''': returns number of messages in the log
−
*'''play()''': Start playing media in the plugin.
 
−
*'''pause()''': Pause playback.
 
−
*'''stop()''': Stop media playback.
 
−
*'''fullscreen()''': Switch the video to full screen.
 
−
*'''set_volume(vol)''': Set the volume. '''vol''' has to be an int in the 0-200 range.
 
−
*'''get_volume()''': Get the current volume setting.
 
−
*'''mute()''': Toggle volume muting.
 
−
*'''set_int_variable(var_name, value)''':
 
−
*'''set_bool_variable(var_name, value)''':
 
−
*'''set_str_variable(var_name, value)''':
 
−
*'''get_int_variable(var_name)''':
 
−
*'''get_bool_variable(var_name)''':
 
−
*'''get_str_variable(var_name)''':
 
−
*'''clear_playlist()''': Clear the playlist.
 
−
*'''add_item(mrl)''': Append an item whose location is given by the [[media resource locator]] to the playlist.
 
−
*'''next()'''
 
−
*'''previous()'''
 
−
*'''isplaying()''': return true if the plugin is playing something.
 
−
*'''get_length()''': Get the media's length in seconds.
 
−
*'''get_position()''': Get the current position in the media in percent.
 
−
*'''get_time()''': Get the current position in the media in seconds.
 
−
*'''seek(seconds,is_relative)''': If is_relative is true, seek relatively to current time, else seek from beginning of the stream. Seek time is specified in seconds.
 
  
 +
read/write properties
  
−
Here are a few examples of HTML pages that use the
+
*''none''
−
Mozilla plugin.
 
  
−
===Example 1===
+
methods
  
−
In this example, the plugin will read an HTTP stream inside the web page. If the user goes fullscreen, he will have to press ''f'' or double-click on the video to go back in normal view.
+
*'''messages.clear()''': clear the current log buffer. It should be called as frequently as possible to not overflow the message queue. Call this method after the log messages of interest are read.
 +
*'''messages.iterator()''': creates and returns an iterator object, used to iterate over the messages in the log. '''Don't clear the log buffer while holding an iterator object.'''
  
−
  &lt;html&gt;
+
==== DEPRECATED: Messages Iterator object ====
−
&lt;head&gt;&lt;title&gt;Demo of VLC mozilla plugin&lt;/title&gt;&lt;/head&gt;
 
  
−
&lt;body&gt;
+
:'''CAUTION''': For security concern, VLC 1.0.0-rc1 is the latest (near-to-stable) version in which this object and its children are supported.
  
−
&lt;h1&gt;Demo of VLC mozilla plugin - Example 1&lt;/h1&gt;
+
readonly properties
  
−
&lt;embed type="application/x-vlc-plugin"
+
*'''iterator.hasNext''': returns a boolean that indicates whether ''vlc.log.messages.next()'' will return the next message.
−
          name="video1"
 
−
          autoplay="no" loop="yes" width="400" height="300"
 
−
          target="http://server.example.org/video1.vob" /&gt;
 
−
&lt;br /&gt;
 
−
  &lt;a href="javascript:;" onclick='document.video1.play()'&gt;Play video1&lt;/a&gt;
 
−
  &lt;a href="javascript:;" onclick='document.video1.pause()'&gt;Pause video1&lt;/a&gt;
 
−
  &lt;a href="javascript:;" onclick='document.video1.stop()'&gt;Stop video1&lt;/a&gt;
 
−
  &lt;a href="javascript:;" onclick='document.video1.fullscreen()'&gt;Fullscreen&lt;/a&gt;
 
  
−
&lt;/body&gt;
+
read/write properties
−
&lt;/html&gt;
 
  
−
===Example 2===
+
*''none''
  
−
In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.
+
methods
  
−
&lt;html&gt;
+
*'''iterator.next()''': returns the next message object in the log, see [[#DEPRECATED:_Message_subobject|Message object]]
−
&lt;head&gt;&lt;title&gt;Demo of VLC mozilla plugin&lt;/title&gt;&lt;/head&gt;
 
  
−
  &lt;body&gt;
+
==== DEPRECATED: Message subobject ====
  
−
&lt;h1&gt;Demo of VLC mozilla plugin - Example 2&lt;/h1&gt;
+
:'''CAUTION''': For security concern, VLC 1.0.0-rc1 is the latest (near-to-stable) version in which this object and its children are supported.
  
−
&lt;embed type="application/x-vlc-plugin"
+
*'''message.severity''': number that indicates the severity of the log message (0 = info, 1 = error, 2 = warning, 3 = debug)
−
          name="video2"
+
*'''message.name''': name of VLC module that printed the log message (e.g: main, http, directx, etc...)
−
          autoplay="no" loop="no" hidden="yes"
+
*'''message.type''': type of VLC module that printed the log message (eg: input, access, vout, sout, etc...)  
−
          target="rtp://@239.255.12.42:5004" /&gt;
+
*'''message.message''': the message text
−
&lt;br /&gt;
 
−
  &lt;a href="javascript:;" onclick='document.video2.play()'&gt;Play video2&lt;/a&gt;
 
−
  &lt;a href="javascript:;" onclick='document.video2.stop()'&gt;Stop video2&lt;/a&gt;
 
−
  &lt;a href="javascript:;" onclick='document.video2.fullscreen()'&gt;Fullscreen&lt;/a&gt;
 
  
−
&lt;/body&gt;
+
{{Documentation}}
−
&lt;/html&gt;
 
  
−
{{Documentation}}
+
[[Category:Development‏‎]]
−
{{Category:Embedded}}
+
[[Category:VLC plugins]]

Latest revision as of 19:57, 5 July 2020

This page is outdated and information might be incorrect.
Create an account to start editing, and then click here to update this article.

This Documentation speaks about the VLC media player Web plugins and how to write pages for it.

VLC User Guide

Quick Start Guide
Installing VLC
History
Usage
Interface
Open Media
Audio
Video
Playback
Playlist
Subtitles
Video and Audio Filters
Snapshots
Hotkeys
Uninstalling VLC
Troubleshooting
Advanced usage
Using VLC inside a webpage
Command line
Alternative Interfaces
Misc

Appendix
Building Pages for the HTTP Interface
Format String
Building Lua Playlist Scripts
View this alone

Introduction: Building Web pages with Video

The VLC media player webplugins are native browser plugins, similar to Flash or Silverlight plugins and allow playback inside the browser of all the videos that VLC media player can read.

Additionally to viewing video on all pages, you can build custom pages that will use the advanced features of the plugin, using JavaScript functions to control playback or extract information from the plugin.

There are 2 main plugins: one is ActiveX for IE, the other is NPAPI for the other browsers. They feature the same amount of features.

In older versions, those plugins were very crashy. We URGE YOU to use VLC 2.0.0 or newer versions.

Browsers support

It has been tested with:

Mozilla Firefox (up to v51) Firefox-logo.png
Internet Explorer Internet Explorer.png
Safari (up to v11) Apple Safari.png
Chrome (up to v44)
Konqueror
Opera (up to v36)

It has been tested on GNU/Linux, Windows and MacOS.


Note:

In the most of browsers, the support for NPAPI plugins was dropped. Only in some forks of Firefox like Waterfox or Pale Moon, NPAPI plugins are still supported.

For this reason, the NPAPI plugin will be dropped in vlc version 4.

Embed tag attributes

To embed the plugin into a webpage, use the following <embed> template: 

<embed type="application/x-vlc-plugin" width="640" height="480" />


If you are using vlc version < 2.2.0 with Internet Explorer, use instead the following <object> template: 

<object classid="clsid:9BE31822-FDAD-461B-AD51-BE1D1C159921" width="640" height="480"></object>

For the declaration of tag attributes, use the tag <param>. Here an example: 

<object classid="clsid:9BE31822-FDAD-461B-AD51-BE1D1C159921" width="640" height="480">
    <param name="autostart" value="true" />
    <param name="allowfullscreen" value="false" />
</object>

For compatibility with the mozilla plugin, you can combine both tags: 

<object classid="clsid:9BE31822-FDAD-461B-AD51-BE1D1C159921" id="vlc" width="640" height="480">
    <embed type="application/x-vlc-plugin" name="vlc" width="640" height="480" />
</object>

Required elements

These are required attributes for the <embed> tag:

  • width: Specifies the width of the plugin.
  • height: Specifies the height of the plugin.
  • target (or one of these alias: mrl, filename, src): Specifies the source location (URL) of the video to load.

Optional elements

These are additional attributes for the <embed> tag:

  • autoplay, autostart: Specifies whether the plugin starts playing on load. Default: true
  • allowfullscreen (or fullscreenEnabled, fullscreen): (since VLC version 2.0.0) Specifies whether the user can switch into fullscreen mode. Default: true
  • windowless: (since VLC version 2.0.6, only for Mozilla) Draw the video on a window-less (non-accelerated) surface and allow styling (CSS overlay, 3D transformations, and much more). Default: false
  • mute: Specifies whether the audio volume is initially muted. Default: false
  • volume: (since VLC version 2.2.2) Specifies the initial audio volume as a percentage. Default: 100
  • loop, autoloop: Specifies whether the video loops on end. Default: false
  • controls (or toolbar): Specifies whether the controls are shown by default. Default: true
  • bgcolor: Specifies the background color of the video player. Default: #000000
  • text: (only for Mozilla on MacOS) Specifies a text displayed as long as no video is shown. Default: empty
  • branding: (in vlc version < 2.2.2 only for Mozilla on MacOS) Specifies whether VLC branding should be displayed in the web plugin's drawing context. Default: true

Normal DOM elements

  • id: DOM id
  • name: DOM name

Javascript API description

The vlc plugin exports several objects that can be accessed for setting and getting information. When used improperly the API's will throw an exception that includes a string that explains what happened. For example when you set vlc.audio.track out of range.

VLC objects

The vlc plugin knows the following objects:

  • audio: Access audio properties.
  • input: Access input properties.
    • input.title: Access title properties (available in vlc version ≥ 2.2.2, supported only ≥ 3.0.0)
    • input.chapter: Access chapter properties (available in vlc version ≥ 2.2.2, supported only ≥ 3.0.0)
  • playlist: Access playlist properties.
    • playlist.items: Access playlist items properties.
  • subtitle: Access subtitle properties.
  • video: Access video properties.
    • video.deinterlace: Access deinterlace properties.
    • video.marquee: Access marquee video filter properties.
    • video.logo: Access logo video filter properties.
  • mediaDescription: Access media info properties (available in vlc version ≥ 2.0.2).

The following are deprecated:

  • log: Access log properties (only available in vlc version ≤ 1.0.0-rc1).
  • messages: Access to log message properties (only available in vlc version ≤ 1.0.0-rc1).
  • iterator: Access to log iterator properties (only available in vlc version ≤ 1.0.0-rc1).
  • message: Access to log message properties (only available in vlc version ≤ 1.0.0-rc1).

Example

The following JavaScript code shows howto get a reference to the vlc plugin. This reference can then be used to access the objects of the vlc plugin. 

<!DOCTYPE html>
<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin"
       width="640"
       height="480"
       id="vlc" />
<script type="text/javascript">
<!--
var vlc = document.getElementById("vlc");
vlc.audio.toggleMute();
//-->
</script>
</body>
</html>

Root object

readonly properties

  • vlc.VersionInfo: returns version information string

read/write properties

  • none

methods

  • vlc.versionInfo(): (only for Mozilla) returns version information string (same as VersionInfo)
  • vlc.getVersionInfo(): (supported in vlc version ≥ 2.2.2) returns version information string (same as VersionInfo and versionInfo())
  • vlc.addEventListener(eventname, callback, bubble): (only for Mozilla) add a listener for mentioned event name, callback expects a function and bubble influences the order of eventhandling by JS (usually it is set to false).
  • vlc.removeEventListener(eventname, callback, bubble): (only for Mozilla) remove listener for mentioned event name, callback expects a function and bubble influences the order of eventhandling by JS (usually it is set to false).
  • vlc.attachEvent(eventname, callback): (only for ActiveX) add listener for mentioned event name, callback expects a function
  • vlc.detachEvent(eventname, callback): (only for ActiveX) remove listener for mentioned event name, callback expects a function

events

  • MediaPlayerNothingSpecial: vlc is in idle state doing nothing but waiting for a command to be issued
  • MediaPlayerOpening: vlc is opening an media resource locator (MRL)
  • MediaPlayerBuffering(int cache): vlc is buffering
  • MediaPlayerPlaying: vlc is playing a media
  • MediaPlayerPaused: vlc is in paused state
  • MediaPlayerStopped: vlc is in stopped state
  • MediaPlayerStopAsyncDone: (supported in vlc version ≥ 3.0.0) playback has stopped asynchronously
  • MediaPlayerForward: vlc is fastforwarding through the media (this never gets invoked)
  • MediaPlayerBackward: vlc is going backwards through the media (this never gets invoked)
  • MediaPlayerEncounteredError: vlc has encountered an error and is unable to continue
  • MediaPlayerEndReached: vlc has reached the end of current playlist
  • MediaPlayerTimeChanged(int time): time has changed
  • MediaPlayerPositionChanged(float position): media position has changed
  • MediaPlayerSeekableChanged(bool seekable): media seekable flag has changed (true means media is seekable, false means it is not)
  • MediaPlayerPausableChanged(bool pausable): media pausable flag has changed (true means media is pauseable, false means it is not)
  • MediaPlayerMediaChanged: (supported in vlc version ≥ 2.2.0) media has changed
  • MediaPlayerTitleChanged(int title): (in vlc version < 2.2.0 only for Mozilla) title has changed (DVD/Blu-ray)
  • MediaPlayerChapterChanged(int chapter): (supported in vlc version ≥ 3.0.0) chapter has changed (DVD/Blu-ray)
  • MediaPlayerLengthChanged(int length): (in vlc version < 2.2.0 only for Mozilla) length has changed
  • MediaPlayerVout(int count): (supported in vlc version ≥ 2.2.7) the number of video output has changed
  • MediaPlayerMuted: (supported in vlc version ≥ 2.2.7) audio volume was muted
  • MediaPlayerUnmuted: (supported in vlc version ≥ 2.2.7) audio volume was unmuted
  • MediaPlayerAudioVolume(float volume): (supported in vlc version ≥ 2.2.7) audio volume has changed

Example

The following code snippet provides easy functions to register and unregister event callbacks on all supported platforms. 

<script type="text/javascript">
<!--
function registerVLCEvent(event, handler) {
    var vlc = getVLC("vlc");
    if (vlc) {
        if (vlc.attachEvent) {
            // Microsoft
            vlc.attachEvent (event, handler);
        } else if (vlc.addEventListener) {
            // Mozilla: DOM level 2
            vlc.addEventListener (event, handler, false);
        }
    }
}
// stop listening to event
function unregisterVLCEvent(event, handler) {
    var vlc = getVLC("vlc");
    if (vlc) {
        if (vlc.detachEvent) {
            // Microsoft
            vlc.detachEvent (event, handler);
        } else if (vlc.removeEventListener) {
            // Mozilla: DOM level 2
            vlc.removeEventListener (event, handler, false);
        }
    }
}
// event callbacks
function handle_MediaPlayerNothingSpecial(){
    console.log("Idle");
}
function handle_MediaPlayerOpening(){
    console.log("Opening");
}
function handle_MediaPlayerBuffering(val){
    console.log("Buffering: " + val + "%");
}
function handle_MediaPlayerPlaying(){
    console.log("Playing");
}
function handle_MediaPlayerPaused(){
    console.log("Paused");
}
function handle_MediaPlayerStopped(){
    console.log("Stopped");
}
function handle_MediaPlayerStopAsyncDone(){
    console.log("Stopped asynchronously");
}
function handle_MediaPlayerForward(){
    console.log("Forward");
}
function handle_MediaPlayerBackward(){
    console.log("Backward");
}
function handle_MediaPlayerEndReached(){
    console.log("EndReached");
}
function handle_MediaPlayerEncounteredError(){
    console.log("EncounteredError");
}
function handle_MediaPlayerTimeChanged(time){
    console.log("Time changed: " + time + " ms");
}
function handle_MediaPlayerPositionChanged(val){
    console.log("Position changed: " + val);
}
function handle_MediaPlayerSeekableChanged(val){
    console.log("Seekable changed: " + val);
}
function handle_MediaPlayerPausableChanged(val){
    console.log("Pausable changed: " + val);
}
function handle_MediaPlayerMediaChanged(){
    console.log("Media changed");
}
function handle_MediaPlayerTitleChanged(val){
    console.log("Title changed: " + val);
}
function handle_MediaPlayerChapterChanged(val){
    console.log("Chapter changed: " + val);
}
function handle_MediaPlayerLengthChanged(val){
    console.log("Length changed: " + val + " ms");
}
function handle_MediaPlayerVout(val){
    console.log("Number of video output changed: " + val);
}
function handle_MediaPlayerMuted(){
    console.log("Audio volume muted");
}
function handle_MediaPlayerUnmuted(){
    console.log("Audio volume unmuted");
}
function handle_MediaPlayerAudioVolume(volume){
    console.log("Audio volume changed: " + Math.round(volume * 100) + "%");
}
// Register a bunch of callbacks.
registerVLCEvent("MediaPlayerNothingSpecial", handle_MediaPlayerNothingSpecial);
registerVLCEvent("MediaPlayerOpening", handle_MediaPlayerOpening);
registerVLCEvent("MediaPlayerBuffering", handle_MediaPlayerBuffering);
registerVLCEvent("MediaPlayerPlaying", handle_MediaPlayerPlaying);
registerVLCEvent("MediaPlayerPaused", handle_MediaPlayerPaused);
registerVLCEvent("MediaPlayerStopped", handle_MediaPlayerStopped);
registerVLCEvent("MediaPlayerStopAsyncDone", handle_MediaPlayerStopAsyncDone);
registerVLCEvent("MediaPlayerForward", handle_MediaPlayerForward);
registerVLCEvent("MediaPlayerBackward", handle_MediaPlayerBackward);
registerVLCEvent("MediaPlayerEndReached", handle_MediaPlayerEndReached);
registerVLCEvent("MediaPlayerEncounteredError", handle_MediaPlayerEncounteredError);
registerVLCEvent("MediaPlayerTimeChanged", handle_MediaPlayerTimeChanged);
registerVLCEvent("MediaPlayerPositionChanged", handle_MediaPlayerPositionChanged);
registerVLCEvent("MediaPlayerSeekableChanged", handle_MediaPlayerSeekableChanged);
registerVLCEvent("MediaPlayerPausableChanged", handle_MediaPlayerPausableChanged);
registerVLCEvent("MediaPlayerMediaChanged", handle_MediaPlayerMediaChanged);
registerVLCEvent("MediaPlayerTitleChanged", handle_MediaPlayerTitleChanged);
registerVLCEvent("MediaPlayerChapterChanged", handle_MediaPlayerChapterChanged);
registerVLCEvent("MediaPlayerLengthChanged", handle_MediaPlayerLengthChanged);
registerVLCEvent("MediaPlayerVout", handle_MediaPlayerVout);
registerVLCEvent("MediaPlayerMuted", handle_MediaPlayerMuted);
registerVLCEvent("MediaPlayerUnmuted", handle_MediaPlayerUnmuted);
registerVLCEvent("MediaPlayerAudioVolume", handle_MediaPlayerAudioVolume);
//-->
</script>

Event registration issue with IE11

Since IE11, the methods attachEvent() and detachEvent() are not longer available. So the registration of events is not possible. But there are two workarounds:

Workaround 1 - Use the IE10 compatibility mode to re-enable the missing methods. For using the compatibility mode, add this meta tag to the header of your page: 

<meta http-equiv="X-UA-Compatible" content="IE=10"/>

Workaround 2 - Use an old IE-only implementation of event registration. An example with the MediaPlayerBuffering event: 

<script for="vlc" event="MediaPlayerBuffering(val)"> 
console.log("Buffering: " + val + "%");
</script>

Audio object

readonly properties

  • vlc.audio.count: (supported in vlc version ≥ 1.1.0) returns the number of audio track available.

read/write properties

  • vlc.audio.mute: boolean value to mute and unmute the audio.
  • vlc.audio.volume: a value between [0-200] which indicates a percentage of the volume.
  • vlc.audio.track: (supported in vlc version > 0.8.6) a value between [1-65535] which indicates the audio track to play or that is playing. a value of 0 means the audio is/will be disabled.
  • vlc.audio.channel: (supported in vlc version > 0.8.6) integer value between [1-5] that indicates which audio channel mode is used, values can be: "1=stereo", "2=reverse stereo", "3=left", "4=right", "5=dolby". Use vlc.audio.channel to check if setting of the audio channel mode has succeeded.

methods

  • vlc.audio.toggleMute(): boolean toggle that mutes and unmutes the audio based upon the previous state.
  • vlc.audio.description(int i): (supported in vlc version ≥ 1.1.0) give the i-th audio track name. 0 corresponds to disable and 1 to the first audio track.

Example

Audio Channel:
<select onChange='doAudioChannel(this.value)'>
    <option value=1>Stereo</option>
    <option value=2>Reverse stereo</option>
    <option value=3>Left</option>
    <option value=4>Right</option>
    <option value=5>Dolby</option>
</select>
<script type="text/javascript">
<!--
function doAudioChannel(value)
{
    var vlc = getVLC("vlc");
    vlc.audio.channel = parseInt(value);
    alert(vlc.audio.channel);
}
//-->
</script>

Input object

readonly properties

  • vlc.input.length: length of the input file in number of milliseconds. 0 is returned for 'live' streams or clips whose length cannot be determined by VLC. It returns -1 if no input is playing.
  • vlc.input.fps: frames per second returned as a float (typically 60.0, 50.0, 23.976, etc...)
  • vlc.input.hasVout: a boolean that returns true when the video is being displayed, it returns false when video is not displayed

read/write properties

  • vlc.input.position: normalized position in multimedia stream item given as a float value between [0.0 - 1.0]
  • vlc.input.time: the absolute position in time given in milliseconds, this property can be used to seek through the stream
 <!-- absolute seek in stream -->
 vlc.input.time = <absolute seek>
 <!-- relative seek in stream -->
 vlc.input.time = vlc.input.time + <relative seek>
  • vlc.input.state: current state of the input chain given as enumeration:
0 IDLE
1 OPENING
2 BUFFERING
3 PLAYING
4 PAUSED
5 STOPPING
6 ENDED
7 ERROR

Note: Test for ENDED=6 to catch end of playback. Checking for STOPPING=5 is NOT ENOUGH.

  • vlc.input.rate: input speed given as float (1.0 for normal speed, 0.5 for half speed, 2.0 for twice as fast, etc.).
rate > 1 fast forward
rate = 1 normal speed
rate < 1 slow motion

methods

  • none

Title object

readonly properties

  • vlc.input.title.count: (supported in vlc version ≥ 2.2.2) returns the number of title available.

read/write properties

  • vlc.input.title.track: (supported in vlc version ≥ 2.2.2) get and set the title track. The property takes an integer as input value [0..65535]. It returns -1 if no titles are available.

methods

  • vlc.input.title.description(int i): (supported in vlc version ≥ 2.2.2) give the i-th title name.

Chapter object

readonly properties

  • vlc.input.chapter.count: (supported in vlc version ≥ 2.2.2) returns the number of chapter available in the current title.

read/write properties

  • vlc.input.chapter.track: (supported in vlc version ≥ 2.2.2) get and set the chapter track. The property takes an integer as input value [0..65535]. It returns -1 if no chapters are available.

methods

  • vlc.input.chapter.description(int i): (supported in vlc version ≥ 2.2.2) give the i-th chapter name.
  • vlc.input.chapter.countForTitle(int i): (supported in vlc version ≥ 2.2.2) returns the number of chapter available for a specific title.
  • vlc.input.chapter.prev(): (supported in vlc version ≥ 2.2.2) play the previous chapter.
  • vlc.input.chapter.next(): (supported in vlc version ≥ 2.2.2) play the next chapter.

Playlist object

readonly properties

  • vlc.playlist.itemCount: number that returns the amount of items currently in the playlist (deprecated, do not use, see Playlist items)
  • vlc.playlist.isPlaying: a boolean that returns true if the current playlist item is playing and false when it is not playing
  • vlc.playlist.currentItem: (supported in vlc version ≥ 2.2.0) number that returns the index of the current item in the playlist. It returns -1 if the playlist is empty or no item is active.
  • vlc.playlist.items: return the playlist items collection, see Playlist items

read/write properties

  • none

methods

  • vlc.playlist.add(mrl): add a playlist item as MRL. The MRL must be given as a string. Returns the index of the just added item in the playlist as a number.
  • vlc.playlist.add(mrl,name,options): add a playlist item as MRL, with metaname 'name' and options 'options'. options are text arguments which can be provided either as a single string containing space separated values, akin to VLC command line, or as an array of string values. Returns the index of the just added item in the playlist as a number.
var options = new Array(":aspect-ratio=4:3", "--rtsp-tcp");
// Or: var options = ":aspect-ratio=4:3 --rtsp-tcp";
var id = vlc.playlist.add("rtsp://servername/item/to/play", "fancy name", options);
vlc.playlist.playItem(id);
  • vlc.playlist.play(): start playing the current playlist item
  • vlc.playlist.playItem(number): start playing the item whose identifier is number
  • vlc.playlist.pause(): pause the current playlist item
  • vlc.playlist.togglePause(): toggle the pause state for the current playlist item
  • vlc.playlist.stop(): stop playing the current playlist item
  • vlc.playlist.stop_async(): (supported in vlc version ≥ 3.0.0) stop playing the current playlist item asynchronously and fire the event MediaPlayerStopAsyncDone, if done
  • vlc.playlist.next(): iterate to the next playlist item
  • vlc.playlist.prev(): iterate to the previous playlist item
  • vlc.playlist.clear(): empty the current playlist, all items will be deleted from the playlist (deprecated, do not use, see Playlist items)
  • vlc.playlist.removeItem(number): remove the item from playlist whose identifier is number (deprecated, do not use, see Playlist items)
  • vlc.playlist.parse(options, timeout): (supported in vlc version ≥ 3.0.0) Parse the first media in the playlist. This fetches (local or network) art, meta data and/or tracks information. A timeout for parsing can be set in milliseconds or to indefinitely (0). Returns the parsed status.

Available options flags for parsing (which can be combined):

0 Parse media if it's a local file.
1 Parse media even if it's a network file.
2 Fetch meta and covert art using local resources.
4 Fetch meta and covert art using network resources.
8 Interact with the user. Set this flag in order to receive a callback when the input is asking for credentials.

Parsed status given as enumeration:

1 skipped
2 failed
3 timeout
4 done

Playlist items object

readonly properties

  • vlc.playlist.items.count: number of items currently in the playlist

read/write properties

  • none

methods

  • vlc.playlist.items.clear(): empty the current playlist, all items will be deleted from the playlist. (note: if a movie is playing, it will not stop)
  • vlc.playlist.items.remove(number): remove the item whose identifier is number from playlist. (note: this number is the current position in the playlist. It's not the number given by vlc.playlist.add(), if any items of the playlist were removed in the meantime.)

Subtitle object

readonly properties

  • vlc.subtitle.count: (supported in vlc version ≥ 1.1.0) returns the number of subtitle available.

read/write properties

  • vlc.subtitle.track: (supported in vlc version ≥ 1.1.0) get and set the subtitle track to show on the video screen. The property takes an integer as input value [1..65535]. If subtitle track is set to 0, the subtitles will be disabled.

methods

  • vlc.subtitle.description(int i): (supported in vlc version ≥ 1.1.0) give the i-th subtitle name. 0 correspond to disable and 1 to the first subtitle.

Video object

readonly properties

  • vlc.video.width: returns the horizontal size of the video
  • vlc.video.height: returns the vertical size of the video
  • vlc.video.count: (supported in vlc version ≥ 2.2.7) returns the number of video track available.

read/write properties

  • vlc.video.fullscreen: when set to true the video will be displayed in fullscreen mode, when set to false the video will be shown inside the video output size. The property takes a boolean as input.
  • vlc.video.aspectRatio: get and set the aspect ratio to use in the video screen. The property takes a string as input value. Typical values are: "1:1", "4:3", "16:9", "16:10", "221:100" and "5:4"
  • vlc.video.scale: (supported in vlc version ≥ 3.0.0) get and set the video scaling factor as float. That is the ratio of the number of pixels on screen to the number of pixels in the original decoded video in each dimension. Zero is a special value; it will adjust the video to the output window.
  • vlc.video.subtitle: (supported in vlc version > 0.8.6a) get and set the subtitle track to show on the video screen. The property takes an integer as input value [1..65535]. If subtitle track is set to 0, the subtitles will be disabled.
  • vlc.video.crop: (removed with vlc version 4.0.0) get and set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>. A possible value is: "120x120+10+10"
  • vlc.video.teletext: (supported in vlc version ≥ 0.9.0) get and set teletext page to show on the video stream. This will only work if a teletext elementary stream is available in the video stream. The property takes an integer as input value [0..1000] for indicating the teletext page to view, setting the value to 0 means hide teletext.
  • vlc.video.track: (supported in vlc version ≥ 2.2.7) a value between [1-65535] which indicates the video track to play or that is playing. a value of 0 means the video is/will be disabled.

methods

  • vlc.video.takeSnapshot(): (supported in vlc version ≥ 0.9.0, only for ActiveX) generates a snapshot and saves it on the desktop
  • vlc.video.toggleFullscreen(): toggle the fullscreen mode based on the previous setting
  • vlc.video.toggleTeletext(): (supported in vlc version ≥ 0.9.0) toggle the teletext page to overlay transparent or not, based on the previous setting
  • vlc.video.description(int i): (supported in vlc version ≥ 2.2.7) give the i-th video track name. 0 corresponds to disable and 1 to the first video track.
  • vlc.video.crop_ratio(int numerator, int denominator): (supported in vlc version ≥ 4.0.0) Forces a crop ratio on any and all video tracks rendered by the media player. To disable video crop, set a crop ratio with zero as denominator.
  • vlc.video.crop_window(int x, int y, int width, int height): (supported in vlc version ≥ 4.0.0) Selects a sub-rectangle of video to show. Any pixels outside the rectangle will not be shown. To unset the video crop window, use vlc.video.crop_ratio() or vlc.video.crop_border().
  • vlc.video.crop_border(int left, int right, int top, int bottom): (supported in vlc version ≥ 4.0.0) Selects the size of video edges to be cropped out. To unset the video crop borders, set all borders to zero.

Deinterlace Object

readonly properties

  • none

read/write properties

  • none

methods

  • vlc.video.deinterlace.enable("my_mode"): (supported in vlc version ≥ 1.1.0) enable deinterlacing with my_mode. You can enable it with "blend", "bob", "discard", "linear", "mean", "x", "yadif" or "yadif2x" mode. Enabling too soon deinterlacing may cause some problems. You have to wait that all variable are available before enabling it.
  • vlc.video.deinterlace.disable(): (supported in vlc version ≥ 1.1.0) disable deinterlacing.

Marquee Object

readonly properties

  • none

read/write properties

  • vlc.video.marquee.text: (supported in vlc version ≥ 1.1.0, since vlc version 4.0.0 writeonly) display my text on the screen.
  • vlc.video.marquee.color: (supported in vlc version ≥ 1.1.0) change the text color. val is the new color to use (WHITE=0x000000, BLACK=0xFFFFFF, RED=0xFF0000, GREEN=0x00FF00, BLUE=0x0000FF...).
  • vlc.video.marquee.opacity: (supported in vlc version ≥ 1.1.0) change the text opacity, val is defined from 0 (completely transparent) to 255 (completely opaque).
  • vlc.video.marquee.position: (supported in vlc version ≥ 1.1.0) change the text position ("center", "left", "right", "top", "top-left", "top-right", "bottom", "bottom-left", "bottom-right").
  • vlc.video.marquee.refresh: (supported in vlc version ≥ 1.1.0) change the marquee refresh period.
  • vlc.video.marquee.size: (supported in vlc version ≥ 1.1.0) val define the new size for the text displayed on the screen. If the text is bigger than the screen then the text is not displayed.
  • vlc.video.marquee.timeout: (supported in vlc version ≥ 1.1.0) change the timeout value. val is defined in ms, but 0 value correspond to unlimited.
  • vlc.video.marquee.x: (supported in vlc version ≥ 1.1.0) change text abscissa.
  • vlc.video.marquee.y: (supported in vlc version ≥ 1.1.0) change text ordinate.

methods

  • vlc.video.marquee.enable(): (supported in vlc version ≥ 1.1.0) enable marquee filter.
  • vlc.video.marquee.disable(): (supported in vlc version ≥ 1.1.0) disable marquee filter.

Some problems may happen (option like color or text will not be applied) because of the VLC asynchronous functioning. To avoid it, after enabling marquee, you have to wait a little time before changing an option. But it should be fixed by the new vout implementation.

NOTE: see this forum post

Logo Object

readonly properties

  • none

read/write properties

  • vlc.video.logo.opacity: (supported in vlc version ≥ 1.1.0) change the picture opacity, val is defined from 0 (completely transparent) to 255 (completely opaque).
  • vlc.video.logo.position: (supported in vlc version ≥ 1.1.0) change the text position ("center", "left", "right", "top", "top-left", "top-right", "bottom", "bottom-left", "bottom-right").
  • vlc.video.logo.delay: (supported in vlc version ≥ 1.1.0) display each picture for a duration of 1000 ms (default) before displaying the next picture.
  • vlc.video.logo.repeat: (supported in vlc version ≥ 1.1.0) number of loops for picture animation (-1=continuous, 0=disabled, n=n-times). The default is -1 (continuous).
  • vlc.video.logo.x: (supported in vlc version ≥ 1.1.0) change the x-offset for displaying the picture counting from top-left on the screen.
  • vlc.video.logo.y: (supported in vlc version ≥ 1.1.0) change the y-offset for displaying the picture counting from top-left on the screen.

methods

  • vlc.video.logo.enable(): (supported in vlc version ≥ 1.1.0) enable logo video filter.
  • vlc.video.logo.disable(): (supported in vlc version ≥ 1.1.0) disable logo video filter.
  • vlc.video.logo.file("file.png"): (supported in vlc version ≥ 1.1.0) display my file.png as logo on the screen.

Some problems may happen because of the VLC asynchronous functioning. To avoid it, after enabling logo video filter, you have to wait a little time before changing an option. But it should be fixed by the new vout implementation.

MediaDescription Object

readonly properties

  • vlc.mediaDescription.title: (supported in vlc version ≥ 2.0.2) returns title meta information field.
  • vlc.mediaDescription.artist: (supported in vlc version ≥ 2.0.2) returns artist meta information field.
  • vlc.mediaDescription.genre: (supported in vlc version ≥ 2.0.2) returns genre meta information field.
  • vlc.mediaDescription.copyright: (supported in vlc version ≥ 2.0.2) returns copyright meta information field.
  • vlc.mediaDescription.album: (supported in vlc version ≥ 2.0.2) returns album meta information field.
  • vlc.mediaDescription.trackNumber: (supported in vlc version ≥ 2.0.2) returns trackNumber meta information field.
  • vlc.mediaDescription.description: (supported in vlc version ≥ 2.0.2) returns description meta information field.
  • vlc.mediaDescription.rating: (supported in vlc version ≥ 2.0.2) returns rating meta information field.
  • vlc.mediaDescription.date: (supported in vlc version ≥ 2.0.2) returns date meta information field.
  • vlc.mediaDescription.setting: (supported in vlc version ≥ 2.0.2) returns setting meta information field.
  • vlc.mediaDescription.URL: (supported in vlc version ≥ 2.0.2) returns URL meta information field.
  • vlc.mediaDescription.language: (supported in vlc version ≥ 2.0.2) returns language meta information field.
  • vlc.mediaDescription.nowPlaying: (supported in vlc version ≥ 2.0.2) returns nowPlaying meta information field.
  • vlc.mediaDescription.publisher: (supported in vlc version ≥ 2.0.2) returns publisher meta information field.
  • vlc.mediaDescription.encodedBy: (supported in vlc version ≥ 2.0.2) returns encodedBy meta information field.
  • vlc.mediaDescription.artworkURL: (supported in vlc version ≥ 2.0.2) returns artworkURL meta information field.
  • vlc.mediaDescription.trackID: (supported in vlc version ≥ 2.0.2) returns trackID meta information field.

read/write properties

  • none

methods

  • none

DEPRECATED APIs

DEPRECATED: Log object

CAUTION: For security concern, VLC 1.0.0-rc1 is the latest (near-to-stable) version in which this object and its children are supported.

This object allows accessing VLC main message logging queue. Typically this queue capacity is very small (no more than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties

read/write properties

  • vlc.log.verbosity: write number [-1,0,1,2,3] for changing the verbosity level of the log messages; messages whose verbosity is higher than set will be not be logged in the queue. The numbers have the following meaning: -1 disable, 0 info, 1 error, 2 warning, 3 debug.

methods

  • none

DEPRECATED: Messages object

CAUTION: For security concern, VLC 1.0.0-rc1 is the latest (near-to-stable) version in which this object and its children are supported.

readonly properties

  • messages.count: returns number of messages in the log

read/write properties

  • none

methods

  • messages.clear(): clear the current log buffer. It should be called as frequently as possible to not overflow the message queue. Call this method after the log messages of interest are read.
  • messages.iterator(): creates and returns an iterator object, used to iterate over the messages in the log. Don't clear the log buffer while holding an iterator object.

DEPRECATED: Messages Iterator object

CAUTION: For security concern, VLC 1.0.0-rc1 is the latest (near-to-stable) version in which this object and its children are supported.

readonly properties

  • iterator.hasNext: returns a boolean that indicates whether vlc.log.messages.next() will return the next message.

read/write properties

  • none

methods

  • iterator.next(): returns the next message object in the log, see Message object

DEPRECATED: Message subobject

CAUTION: For security concern, VLC 1.0.0-rc1 is the latest (near-to-stable) version in which this object and its children are supported.
  • message.severity: number that indicates the severity of the log message (0 = info, 1 = error, 2 = warning, 3 = debug)
  • message.name: name of VLC module that printed the log message (e.g: main, http, directx, etc...)
  • message.type: type of VLC module that printed the log message (eg: input, access, vout, sout, etc...)
  • message.message: the message text
This page is part of official VLC media player Documentation (User Guide • Streaming HowTo • Hacker Guide • Modules)
Please read the Documentation Editing Guidelines before you edit the documentation
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Retrieved from "https://wiki.videolan.org/index.php?title=Documentation:WebPlugin&oldid=62058"