VideoLAN Wiki - User contributions [en]

VDD13

2013-09-01T09:59:28Z

Jpsaman: /* Afternoon */

= VideoLAN Dev Days '13 =
'''The Multimedia Conference that frees the cone in you!'''

This is a technical un-conference, please bring laptops, cords, RJ45 cables, and a good mood with you.

=== Nota Bene ===
* The hotel is the [http://www.ibishotel.com/gb/hotel-5543-ibis-paris-avenue-d-italie-13eme/index.shtml Ibis] Avenue d'Italie.

* If you expect us to refund your travel, please bring a printed copy of your tickets, one that shows the total cost. If you are not in our reimbursement database, bring a printed IBAN too.

* On Saturday and Sunday, enter the Free HQ by the '''16 Rue de la Ville-l'Évêque''' ([http://goo.gl/EKHWEc map]).
** There will be a smoking area inside the building, as the entrance cannot be used once inside the building for security reasons.

* There will be a WiFi connection.

= Schedule =

== Thursday, August 29th 2013 ==

{| class="wikitable" width="70%"
| 21h00 || Meeting at the Sputnik, for the brave... || NB: VideoLAN will not pay for expenses at the bar...
|}

[http://www.sputnik.fr/ Sputnik bar]

== Friday, August 30th 2013 ==
[[Image:Asterix VLC.svg|right|270px]]
Friday is an '''<u>optional</u>''' day in the Asterix amusement park to bind together our community. If you wish to attend, the meeting in front of the hotel is at 8:30.
There will be a bus that will be responsible for bringing everyone to and back from the park. More details on the park are available below.

Notes:
* that bus and park entrance fees are paid by us, so there are NO costs with the exception of food and drinks
* do not burden yourself too much with unneeded stuff and particularly '''don't bring your laptop'''!

{| class="wikitable" width="70%"
|-
! Time !! Place !! Description
|-
| 8h30 || [http://www.ibishotel.com/gb/hotel-5543-ibis-paris-avenue-d-italie-13eme/index.shtml Hotel] || Meeting point in front of the hotel
|-
| 10h00 – 18h00 || Visit to Asterix park
|-
| 21h00 || Meeting at the Sputnik, for the brave... || NB: VideoLAN will not pay for expenses at the bar...
|}

If you cannot be present at the meeting point, you will be able to join us directly there, but you '''MUST''' tell us. For reference here are directions to the park: Take RER B3 from Paris Gare du Nord, platform 43 and get off at “Aéroport Charles De Gaulle Terminal 1, Terminal 3”. Go to the “Parcs de Loisirs” counter and board the Parc Astérix shuttle buses.

== Saturday, August 31st 2013 ==
All the meetings happen in the '''auditorium'''.

=== Morning ===
Schedule information is not currently available.

{| class="wikitable" width="70%"
|-
! Time !! Description
|-
| 9h30 – 10h00 || Welcome, registration, coffee, juice and croissants
|-
| 10h00 – 10h15 || Welcome, VideoLAN, VLC
|-
| 10h20 – 10h45 || x265
|-
| 10h50 – 11h15 || VLC and DCP
|-
| 11h15 – 11h30 || '''Coffee Break'''
|-
| 11h30 – 11h55 || VLC annotations
|-
| 11h55 – 12h15 || VP9
|-
| 12h15 – 12h30 || VLC 2.1.0 and next
|-
|}

=== Lunch ===
Individual tray meal (chicken, salmon, vegetarian or beef) with dessert and drinks.

=== UnConference ===
[[wikipedia:Unconference|What is an UnConference?]]

UnConference schedule to be published...
{| class="wikitable" width="70%"
! Time !! Hacking Room 1 !! Hacking Room 2 !! Hacking Room 3 !! Hacking Room 4 !! Hacking Room 5
|-
| 14h00 - 16h00 || libav technical discussion || FFmpeg technical discussion || - Open - || VLC technical discussion || HACKING ROOM
|-
| 16h00 - 16h30 || ''Break'' ||''Break'' ||''Break'' ||''Break'' || HACKING ROOM
|-
| 16h30 - 18h30 || libav documentation session || x264 || - Open - || VLC mobile ports || HACKING ROOM
|-
| 18h30 - 19h00 || || || || || Day Wrap up (In the cafeteria)
|-
|}

=== Dinner ===
[http://www.tripadvisor.fr/Restaurant_Review-g187147-d2459770-Reviews-Restaurant_Du_Paradis-Paris_Ile_de_France.html Restaurant du Paradis]<br />
66 Rue du Faubourg Poissonniere<br />
75010 Paris<br />

Metro: Line 7, Poissonière

Starting at 20h00, dinner will consist of 2 special menus prepared by the chef. (drinks included - wine and non-alcoholic)

The menu will consist of 4 choices for starters, principal meal and deserts. There is also a vegan menu available.

== Sunday, September 1st 2013 ==
=== Session Proposals ===
* Opus in MPEG TS design session
* Daala video codec discussion
* VLC Mac session
* Building an official VLC SDK for C#/Winform that is cross platform
* keysigning
* HEVC decoder review/clean up

=== Morning ===
Schedule to be posted.
{| class="wikitable" width="70%"
|-
! Time !! HR1 !! HR2 !! HR3 !! HR4 !! HR5
|-
| 10h00 - 11h30 || HEVC decoder review/cleanup || TBD || || VideoLAN association meeting || HACKING ROOM
|-
| 11h30 - 12h30 || Daala video codec || TBD  || || Building an official VLC SDK for C#/Winform that is cross platform || HACKING ROOM
|-
|}

=== Lunch & Group Photo ===
Location: Cafeteria of Free HQ (a really beautiful and spacious place!)

'''Sandwiches''' with coleslaw or crisps and choices of drinks (including Dr Pepper) + desserts (Pecan pies, Oreo pies, lemon pies, or cheese cakes).

=== Afternoon ===
{| class="wikitable" width="70%"
|-
! Time !! HR1 !! HR2 !! HR3 !! HR4 !! HR5
|-
| 14h00 - 15h00 || Opus in TS || Handbrake || FFmtech || || HACKING ROOM || N/A
|-
| 15h00 - 16h00 || x265 || Roots meeting|| || VLC on the Mac || HACKING ROOM || N/A
|-
| 16h00 - 17h00 || Broadcast || || Hack || Hack || HACKING ROOM || N/A
|-
| 17h00 - 18h00 || libavcodec whining room || TBD || Hack || Hack || HACKING ROOM || N/A
|-
|}

__NOTOC__

= Places =

== Map and Itinerary ==

[http://goo.gl/EGmdKQ Here], a Google Map for all places.

[http://images.videolan.org/videolan/events/vdd13/Itinerary.pdf Here] a map with itineraries to go between the different places.

== Asterix Park ==
60128 Plailly, France<br />
Metro / RER: '''B3'''

http://www.parcasterix.fr/

== Free HQ ==
16 Rue de la Ville-l'Évêque<br />
75008 Paris, France ([http://goo.gl/EKHWEc map])

Metro 8: Madeleine<br />
Metro 12: Madeleine<br />
Metro 14: Madeleine<br />

From CDG airport, take:<br />
the RER B (Paris by train) to Châtelet-les-Halles<br />
then Metro line 14 to Madeleine.

http://www.free.fr/

== Hotel Ibis ==
[http://www.ibishotel.com/gb/hotel-5543-ibis-paris-avenue-d-italie-13eme/index.shtml Hotel IBIS Paris Avenue d'Italie]<br />
15 bis Avenue d'Italie<br />
75013 Paris ([http://goo.gl/MKmwjx map])

== Emergencies ==
* In case of emergency, call the European emergency number '''112'''.
* To place a call most credit cards can be used directly in public phones.

[[Category:About VideoLAN]]

VLC Dev Projects

2010-12-16T12:04:41Z

Jpsaman: /* VideoLAN Subtitle Editor */

This is a list of small independent improvements to {{VLC}} for which we are looking for interested developers, because we simply don't have enough time.

These do not require advanced knowledge of VLC internals but they can still vastly improve many parts of VLC

'''For each project''', we list a '''contact''' person, who knows the subject best and who will be able to assist you if you are interested in working on these. We generally are very often present on irc.videolan.org, chan #videolan, so please don't hesitate to drop by or to send a mail if you are interested in a given problem (our mail adresses are generally <nick>@videolan.org).

'''Be careful, some projects may be unrelated, or deprecated, because of fast evolving software! Ask before !'''

= Easy projects =

These projects are junior projects, the most easy ones to do, that require minimum knowledge of VLC.

We also have a number of "easy" bugs. You can check them out [http://trac.videolan.org/vlc/query?status=new&status=assigned&status=reopened&difficulty=easy&order=priority` here]

== Code Janitorial ==

It basically means to clean the code, it is helpful for all programmers. It helps to find bugs, and is a good way to learn about VLC's internals.

It is covered in the [[Code Janitorial]] section.

== Video Filters ==

You can do video filters for {{VLC}}.

You can inspire yourself on this [http://movavi.com/enhancemovie/filters.html list of filters] from a commercial product.

You can start the code [http://git.videolan.org/?p=vlc.git;a=tree;f=modules/video_filter here].

== Audio Filters ==

You can do audio filters for {{VLC}}

You can start the code [http://git.videolan.org/?p=vlc.git;a=tree;f=modules/audio_filter here].

== Lua Playlist parsers for websites ==

VLC already supports youtube, dailymotion or other websites using the .lua scripts! Add new sites and new URLs support!

== Close bugs ==

Go to our bugtracker on http://trac.videolan.org/vlc/ and close a bug !

= Normal small projects =

== Windows Media Center (WMC) IR Remote Control ==

Basic Controls work (e.g. Volume, Mute etc), but I would like to get Play/Pause/Stop/DVD Menu etc to work!

Contact: [[User:Some1|some1]]

== DirectX 9 video output ==

DirectX 9 features some improvements that we could use in our video output

Contact: [[User:Geal|Geal]]

== DirectWrite support ==

DirectWrite is another API introduced in Windows 7, used to write nicely shaped characters to screen. Someone should look into it, to see what could be done (like subtitles display).

Contact: [[User:Geal|Geal]]

== Pixel shaders in OpenGL video output ==

It would be nice to have a small proof of concept video output which takes care of chroma conversion using pixel shaders.

Contact: [[User:Dionoea|dionoea]]

== mozila and activex javascript api ==

Add a callback to signal playlist state changes such as item started, item ended, next item started, last item ended, and so on.

Contact: [[User:Jpsaman|jpsaman]]

== Improved Podcast support ==

Our current podcast support is very weak. We can read them, but that's all. We need a real infrastructure to handle them correctly. This will require some changes to the playlist code, so you will need to work closely with existing developers.

Contacts: [[User:Dionoea|Dionoea]] [[User:Zorglub|Zorglub]]

== WTV support ==

We would love to have a .wtv demuxer for the new wtv files from Windows Media center

Contact [[User:J-b|jb]]

== Improved ASX support ==

ASX is a playlist format used by Microsoft stuff. We can read it but we could do much better. More information is available at https://trac.videolan.org/vlc/ticket/20

Contact: [[User:Dnumgis|Dnumgis]]

== Hint MP4/MOV Files ==

Add video and audio hint tracks as the output file is muxed. Resulting files can be streamed from RTSP server with trickplay, like DSS/QTSS. Probably requires use of GPAC libraries.

== LastFM radios ==

http://gabistapler.de/blog/index.php?/archives/268-Play-last.fm-streams-without-the-player.html

Talk to dionoea or funman

== ASM optims ==

If you know how to code in x86 ASM, we have a few tasks for you

Contact [[User:J-b|jb]]

== DVD Audio ==

If you are a coder and fan of DVD-Audio, you can help to improve the support of DVD-Audio playback. Especially decryption.

Contact [[User:J-b|jb]]

== Performant VLC streaming server ==

There are many bottlenecks currently limiting the performance and scalability of VLC as a streaming server:

*The I/O blocks are linear, which implies lots of avoidable memory copying and dynamic memory allocations (particularly in the streaming output).
*mdate() (the timestamping function) is invoked in too many places to count them; but it is not a cheap operation on modern systems and should be avoided on the fast path. Ideally, a single thread would only need to call mdate() at most once per wake-up. In some case, mdate() is only used for debugging purpose which is really inefficient.
*The HTTP/RTSP core is single-threaded. This prevents scaling to SMP systems (which are the norm on server-side nowadays) properly. This also implies not very scalable I/O event polling. Finally, this gets problematic if one HTTP/RTSP client triggers a computationally intensive operation (such as establishing a TLS context if HTTP/SSL is used).
*There are many dynamic memory allocations that could be avoided. Video filters and codecs are very careful about this, but the stream output plugins are not. In many case, a stack-based buffer can be used (stack buffer, has constant time fast lock-less allocation, and needs not be freed explicitly) instead.
*The messaging subsystems might be adding more locking (needs checking); this should be avoided particularly if the message is anyway ignord (e.g. debug message in non-debug mode).

Other improvements that would be particularly benefitial on the server side:

*Memory allocation failure are not always duly handled. In some cases, that could potentially be leveraged by a client to crash a VLC server by causing a very large allocation attempt.
*Rewrite and revive the root wrapper to allow VLC to bind to the RTSP (554) port while not retaining root privileges.

Contact: [[User:Courmisch|Courmisch]]

== VideoLAN Subtitle Editor ==

The "VideoLAN Subtitle Editor" is runs on any OS that is supported by [[Libvlc]].

Features:
* Qt4 Interface
* Media playback based on [[Libvlc]]
* Multiple OS support (Linux, MacOS X, Windows, *BSD, ...)
* Internationalisation of subtitles
* Exporting to many subtitle formats (.srt, .ssa/.ass, .sub, .srt, .ssf, ...).

Examples of subtile editors:
* Subtitle Editor http://home.gna.org/subtitleeditor/
* Open Subtitle Editor http://opensubtitleed.sourceforge.net/
* Subtile formats: http://en.wikipedia.org/wiki/Subtitles

Contact: [[User:jpsaman|jpsaman]]

= Finished projects =

== Audioscrobbler ==

An [http://www.audioscrobbler.net/ Audioscrobbler] VLC Plug-in for the social music network [http://www.last.fm Last.Fm]<br>

Plugin is finished, now part of vlc 0.9.0 (development version). Done by [[User:Funman|funman]]

== DVB support for Windows / BDA Drivers ==

DVB is the norm for :

*Digital Terrestrial TV (aka DVB-T)
*Digital Cable TV (aka DVB-C)
*Digital Satellite TV (aka DVB-S)

Several DVB input cards exist. We support these on Linux, but not on Windows. For Windows, we need to support so-called BDA drivers.

The problem is that we don't have both the time and the required hardware on Windows comps.

This project is probably not terribly complex, but you need the hardware.

Plugin is done and availabe in the current Git version. Code by kenS

== DBus Integration ==

[[DBus]] is a communication mechanism for Linux (mainly).

We would like VLC to be able to use it so that other programs can interact with vlc (start/stop, know what is being played, ...)

Work is well advanced, see [[DBus]], by funman and Mr_Mirsal

Contact: [[User:Xtophe|Xtophe]], [[User:Funman|funman]]

== V4L2 support ==

VLC currently has a pvr module and a v4l (video for linux) module. However

*some cards are only supported in the new v4l2 API
*The linux kernel will soon drop v4l support

So if someone could update VLC's current modules to work with V4L2 and the new ivtv api, this would be a welcome addition. This is not a very difficult project, but you will need to have the hardware to test against. The code has been began, so it should not be too difficult.

Plugin is done and available in the current Git version. Code by Richard Hosking, [[User:Dionoea|dionoea]] and Dennis Lou.

== RTCP support ==

Our RTSP implementation (for broadcasting and video on demand) does not support the RTCP protocol. This is a must to have a real support for RTSP. Some work has already been started, but there is still much to do.

Contact: [[User:JPSaman|JPSaman]]

== Windows port ==

Finish port libcddb and libcdio for Windows.

Port libzvbi for Windows

Contact [[User:J-b|jb]]

== Improvements to the X11 video output ==

Fullscreen support to improve .

[[Category:Coding]] [[Category:Activities]]

== Subtitles improvements ==

{{VLC}} does not support all the styles for a lot of subtitles type. Take a look at [http://trac.videolan.org/vlc/browser/trunk/modules/codec/subtitles/subsdec.c here] to start coding.

Contact bitmap

== Direct2D video output ==

Direct2D is a new API introduced in Windows 7. VLC could use a a Direct2D vout.

Contact: [[User:Geal|Geal]]
== Interaction with online services ==
Hello, I would like to present their concept idea, it involves interaction with online services and some changes in the user interface of VLC Media Player.

On the first tab (Movie) is very straightforward, a user inserts a DVD, HD-DVD or BlyRay selects the desired slot and begin viewing.
In the future it will be possible to implement view of the disk image.

The second tab (Video), makes it possible to watch media files directly from the HDD.
Setting up a profile can be all sorted by category (Films, TV shows, etc.), the category of Films on (Action, Horror, Camedy), the category of TV show on (Lost, House M. D, X-Files), etc.
After watching a movie or TV show, you can not closing VLC media player immediately to share impressions with your friends on Twitter, MySpace, Facebook.

The third tab (Music), provides an opportunity to listen to music as a straight line from the HDD.
Similar to the previous tab, everything can be sorted into categories (Hip-Hop, R'n'B, Dance, Rock).

Another idea is to tab Online TV, where you can make a small internet browser tied to popular online Servas (YouTube) and send links to interesting videos to friends directly from the VLC Player.

Contact: [[User_talk:Jack.LJ|Jack.LJ]]

=Discussions on projects=

==Proposals==

* [[Newplaylist|Playlist improvement]]<br/>
* [[Newsoundslider|Soundslider improevment]]

VLC Dev Projects

2010-12-16T12:03:31Z

Jpsaman: /* VideoLAN Subtitle Editor */

This is a list of small independent improvements to {{VLC}} for which we are looking for interested developers, because we simply don't have enough time.

These do not require advanced knowledge of VLC internals but they can still vastly improve many parts of VLC

'''For each project''', we list a '''contact''' person, who knows the subject best and who will be able to assist you if you are interested in working on these. We generally are very often present on irc.videolan.org, chan #videolan, so please don't hesitate to drop by or to send a mail if you are interested in a given problem (our mail adresses are generally <nick>@videolan.org).

'''Be careful, some projects may be unrelated, or deprecated, because of fast evolving software! Ask before !'''

= Easy projects =

These projects are junior projects, the most easy ones to do, that require minimum knowledge of VLC.

We also have a number of "easy" bugs. You can check them out [http://trac.videolan.org/vlc/query?status=new&status=assigned&status=reopened&difficulty=easy&order=priority` here]

== Code Janitorial ==

It basically means to clean the code, it is helpful for all programmers. It helps to find bugs, and is a good way to learn about VLC's internals.

It is covered in the [[Code Janitorial]] section.

== Video Filters ==

You can do video filters for {{VLC}}.

You can inspire yourself on this [http://movavi.com/enhancemovie/filters.html list of filters] from a commercial product.

You can start the code [http://git.videolan.org/?p=vlc.git;a=tree;f=modules/video_filter here].

== Audio Filters ==

You can do audio filters for {{VLC}}

You can start the code [http://git.videolan.org/?p=vlc.git;a=tree;f=modules/audio_filter here].

== Lua Playlist parsers for websites ==

VLC already supports youtube, dailymotion or other websites using the .lua scripts! Add new sites and new URLs support!

== Close bugs ==

Go to our bugtracker on http://trac.videolan.org/vlc/ and close a bug !

= Normal small projects =

== Windows Media Center (WMC) IR Remote Control ==

Basic Controls work (e.g. Volume, Mute etc), but I would like to get Play/Pause/Stop/DVD Menu etc to work!

Contact: [[User:Some1|some1]]

== DirectX 9 video output ==

DirectX 9 features some improvements that we could use in our video output

Contact: [[User:Geal|Geal]]

== DirectWrite support ==

DirectWrite is another API introduced in Windows 7, used to write nicely shaped characters to screen. Someone should look into it, to see what could be done (like subtitles display).

Contact: [[User:Geal|Geal]]

== Pixel shaders in OpenGL video output ==

It would be nice to have a small proof of concept video output which takes care of chroma conversion using pixel shaders.

Contact: [[User:Dionoea|dionoea]]

== mozila and activex javascript api ==

Add a callback to signal playlist state changes such as item started, item ended, next item started, last item ended, and so on.

Contact: [[User:Jpsaman|jpsaman]]

== Improved Podcast support ==

Our current podcast support is very weak. We can read them, but that's all. We need a real infrastructure to handle them correctly. This will require some changes to the playlist code, so you will need to work closely with existing developers.

Contacts: [[User:Dionoea|Dionoea]] [[User:Zorglub|Zorglub]]

== WTV support ==

We would love to have a .wtv demuxer for the new wtv files from Windows Media center

Contact [[User:J-b|jb]]

== Improved ASX support ==

ASX is a playlist format used by Microsoft stuff. We can read it but we could do much better. More information is available at https://trac.videolan.org/vlc/ticket/20

Contact: [[User:Dnumgis|Dnumgis]]

== Hint MP4/MOV Files ==

Add video and audio hint tracks as the output file is muxed. Resulting files can be streamed from RTSP server with trickplay, like DSS/QTSS. Probably requires use of GPAC libraries.

== LastFM radios ==

http://gabistapler.de/blog/index.php?/archives/268-Play-last.fm-streams-without-the-player.html

Talk to dionoea or funman

== ASM optims ==

If you know how to code in x86 ASM, we have a few tasks for you

Contact [[User:J-b|jb]]

== DVD Audio ==

If you are a coder and fan of DVD-Audio, you can help to improve the support of DVD-Audio playback. Especially decryption.

Contact [[User:J-b|jb]]

== Performant VLC streaming server ==

There are many bottlenecks currently limiting the performance and scalability of VLC as a streaming server:

*The I/O blocks are linear, which implies lots of avoidable memory copying and dynamic memory allocations (particularly in the streaming output).
*mdate() (the timestamping function) is invoked in too many places to count them; but it is not a cheap operation on modern systems and should be avoided on the fast path. Ideally, a single thread would only need to call mdate() at most once per wake-up. In some case, mdate() is only used for debugging purpose which is really inefficient.
*The HTTP/RTSP core is single-threaded. This prevents scaling to SMP systems (which are the norm on server-side nowadays) properly. This also implies not very scalable I/O event polling. Finally, this gets problematic if one HTTP/RTSP client triggers a computationally intensive operation (such as establishing a TLS context if HTTP/SSL is used).
*There are many dynamic memory allocations that could be avoided. Video filters and codecs are very careful about this, but the stream output plugins are not. In many case, a stack-based buffer can be used (stack buffer, has constant time fast lock-less allocation, and needs not be freed explicitly) instead.
*The messaging subsystems might be adding more locking (needs checking); this should be avoided particularly if the message is anyway ignord (e.g. debug message in non-debug mode).

Other improvements that would be particularly benefitial on the server side:

*Memory allocation failure are not always duly handled. In some cases, that could potentially be leveraged by a client to crash a VLC server by causing a very large allocation attempt.
*Rewrite and revive the root wrapper to allow VLC to bind to the RTSP (554) port while not retaining root privileges.

Contact: [[User:Courmisch|Courmisch]]

== VideoLAN Subtitle Editor ==

The "VideoLAN Subtitle Editor" is runs on any OS that is supported by Libvlc.

Features:
* Qt4 Interface
* Media playback based on Libvlc
* Multiple OS support (Linux, MacOS X, Windows, *BSD, ...)
* Internationalisation of subtitles
* Exporting to many subtitle formats (.srt, .ssa/.ass, .sub, .srt, .ssf, ...).

Examples of subtile editors:
* Subtitle Editor http://home.gna.org/subtitleeditor/
* Open Subtitle Editor http://opensubtitleed.sourceforge.net/
* Subtile formats: http://en.wikipedia.org/wiki/Subtitles

Contact: [[User:jpsaman|jpsaman]]

= Finished projects =

== Audioscrobbler ==

An [http://www.audioscrobbler.net/ Audioscrobbler] VLC Plug-in for the social music network [http://www.last.fm Last.Fm]<br>

Plugin is finished, now part of vlc 0.9.0 (development version). Done by [[User:Funman|funman]]

== DVB support for Windows / BDA Drivers ==

DVB is the norm for :

*Digital Terrestrial TV (aka DVB-T)
*Digital Cable TV (aka DVB-C)
*Digital Satellite TV (aka DVB-S)

Several DVB input cards exist. We support these on Linux, but not on Windows. For Windows, we need to support so-called BDA drivers.

The problem is that we don't have both the time and the required hardware on Windows comps.

This project is probably not terribly complex, but you need the hardware.

Plugin is done and availabe in the current Git version. Code by kenS

== DBus Integration ==

[[DBus]] is a communication mechanism for Linux (mainly).

We would like VLC to be able to use it so that other programs can interact with vlc (start/stop, know what is being played, ...)

Work is well advanced, see [[DBus]], by funman and Mr_Mirsal

Contact: [[User:Xtophe|Xtophe]], [[User:Funman|funman]]

== V4L2 support ==

VLC currently has a pvr module and a v4l (video for linux) module. However

*some cards are only supported in the new v4l2 API
*The linux kernel will soon drop v4l support

So if someone could update VLC's current modules to work with V4L2 and the new ivtv api, this would be a welcome addition. This is not a very difficult project, but you will need to have the hardware to test against. The code has been began, so it should not be too difficult.

Plugin is done and available in the current Git version. Code by Richard Hosking, [[User:Dionoea|dionoea]] and Dennis Lou.

== RTCP support ==

Our RTSP implementation (for broadcasting and video on demand) does not support the RTCP protocol. This is a must to have a real support for RTSP. Some work has already been started, but there is still much to do.

Contact: [[User:JPSaman|JPSaman]]

== Windows port ==

Finish port libcddb and libcdio for Windows.

Port libzvbi for Windows

Contact [[User:J-b|jb]]

== Improvements to the X11 video output ==

Fullscreen support to improve .

[[Category:Coding]] [[Category:Activities]]

== Subtitles improvements ==

{{VLC}} does not support all the styles for a lot of subtitles type. Take a look at [http://trac.videolan.org/vlc/browser/trunk/modules/codec/subtitles/subsdec.c here] to start coding.

Contact bitmap

== Direct2D video output ==

Direct2D is a new API introduced in Windows 7. VLC could use a a Direct2D vout.

Contact: [[User:Geal|Geal]]
== Interaction with online services ==
Hello, I would like to present their concept idea, it involves interaction with online services and some changes in the user interface of VLC Media Player.

On the first tab (Movie) is very straightforward, a user inserts a DVD, HD-DVD or BlyRay selects the desired slot and begin viewing.
In the future it will be possible to implement view of the disk image.

The second tab (Video), makes it possible to watch media files directly from the HDD.
Setting up a profile can be all sorted by category (Films, TV shows, etc.), the category of Films on (Action, Horror, Camedy), the category of TV show on (Lost, House M. D, X-Files), etc.
After watching a movie or TV show, you can not closing VLC media player immediately to share impressions with your friends on Twitter, MySpace, Facebook.

The third tab (Music), provides an opportunity to listen to music as a straight line from the HDD.
Similar to the previous tab, everything can be sorted into categories (Hip-Hop, R'n'B, Dance, Rock).

Another idea is to tab Online TV, where you can make a small internet browser tied to popular online Servas (YouTube) and send links to interesting videos to friends directly from the VLC Player.

Contact: [[User_talk:Jack.LJ|Jack.LJ]]

=Discussions on projects=

==Proposals==

* [[Newplaylist|Playlist improvement]]<br/>
* [[Newsoundslider|Soundslider improevment]]

VLC Dev Projects

2010-12-16T12:02:27Z

Jpsaman: VideoLAN Subtitle Editor

This is a list of small independent improvements to {{VLC}} for which we are looking for interested developers, because we simply don't have enough time.

These do not require advanced knowledge of VLC internals but they can still vastly improve many parts of VLC

'''For each project''', we list a '''contact''' person, who knows the subject best and who will be able to assist you if you are interested in working on these. We generally are very often present on irc.videolan.org, chan #videolan, so please don't hesitate to drop by or to send a mail if you are interested in a given problem (our mail adresses are generally <nick>@videolan.org).

'''Be careful, some projects may be unrelated, or deprecated, because of fast evolving software! Ask before !'''

= Easy projects =

These projects are junior projects, the most easy ones to do, that require minimum knowledge of VLC.

We also have a number of "easy" bugs. You can check them out [http://trac.videolan.org/vlc/query?status=new&status=assigned&status=reopened&difficulty=easy&order=priority` here]

== Code Janitorial ==

It basically means to clean the code, it is helpful for all programmers. It helps to find bugs, and is a good way to learn about VLC's internals.

It is covered in the [[Code Janitorial]] section.

== Video Filters ==

You can do video filters for {{VLC}}.

You can inspire yourself on this [http://movavi.com/enhancemovie/filters.html list of filters] from a commercial product.

You can start the code [http://git.videolan.org/?p=vlc.git;a=tree;f=modules/video_filter here].

== Audio Filters ==

You can do audio filters for {{VLC}}

You can start the code [http://git.videolan.org/?p=vlc.git;a=tree;f=modules/audio_filter here].

== Lua Playlist parsers for websites ==

VLC already supports youtube, dailymotion or other websites using the .lua scripts! Add new sites and new URLs support!

== Close bugs ==

Go to our bugtracker on http://trac.videolan.org/vlc/ and close a bug !

= Normal small projects =

== Windows Media Center (WMC) IR Remote Control ==

Basic Controls work (e.g. Volume, Mute etc), but I would like to get Play/Pause/Stop/DVD Menu etc to work!

Contact: [[User:Some1|some1]]

== DirectX 9 video output ==

DirectX 9 features some improvements that we could use in our video output

Contact: [[User:Geal|Geal]]

== DirectWrite support ==

DirectWrite is another API introduced in Windows 7, used to write nicely shaped characters to screen. Someone should look into it, to see what could be done (like subtitles display).

Contact: [[User:Geal|Geal]]

== Pixel shaders in OpenGL video output ==

It would be nice to have a small proof of concept video output which takes care of chroma conversion using pixel shaders.

Contact: [[User:Dionoea|dionoea]]

== mozila and activex javascript api ==

Add a callback to signal playlist state changes such as item started, item ended, next item started, last item ended, and so on.

Contact: [[User:Jpsaman|jpsaman]]

== Improved Podcast support ==

Our current podcast support is very weak. We can read them, but that's all. We need a real infrastructure to handle them correctly. This will require some changes to the playlist code, so you will need to work closely with existing developers.

Contacts: [[User:Dionoea|Dionoea]] [[User:Zorglub|Zorglub]]

== WTV support ==

We would love to have a .wtv demuxer for the new wtv files from Windows Media center

Contact [[User:J-b|jb]]

== Improved ASX support ==

ASX is a playlist format used by Microsoft stuff. We can read it but we could do much better. More information is available at https://trac.videolan.org/vlc/ticket/20

Contact: [[User:Dnumgis|Dnumgis]]

== Hint MP4/MOV Files ==

Add video and audio hint tracks as the output file is muxed. Resulting files can be streamed from RTSP server with trickplay, like DSS/QTSS. Probably requires use of GPAC libraries.

== LastFM radios ==

http://gabistapler.de/blog/index.php?/archives/268-Play-last.fm-streams-without-the-player.html

Talk to dionoea or funman

== ASM optims ==

If you know how to code in x86 ASM, we have a few tasks for you

Contact [[User:J-b|jb]]

== DVD Audio ==

If you are a coder and fan of DVD-Audio, you can help to improve the support of DVD-Audio playback. Especially decryption.

Contact [[User:J-b|jb]]

== Performant VLC streaming server ==

There are many bottlenecks currently limiting the performance and scalability of VLC as a streaming server:

*The I/O blocks are linear, which implies lots of avoidable memory copying and dynamic memory allocations (particularly in the streaming output).
*mdate() (the timestamping function) is invoked in too many places to count them; but it is not a cheap operation on modern systems and should be avoided on the fast path. Ideally, a single thread would only need to call mdate() at most once per wake-up. In some case, mdate() is only used for debugging purpose which is really inefficient.
*The HTTP/RTSP core is single-threaded. This prevents scaling to SMP systems (which are the norm on server-side nowadays) properly. This also implies not very scalable I/O event polling. Finally, this gets problematic if one HTTP/RTSP client triggers a computationally intensive operation (such as establishing a TLS context if HTTP/SSL is used).
*There are many dynamic memory allocations that could be avoided. Video filters and codecs are very careful about this, but the stream output plugins are not. In many case, a stack-based buffer can be used (stack buffer, has constant time fast lock-less allocation, and needs not be freed explicitly) instead.
*The messaging subsystems might be adding more locking (needs checking); this should be avoided particularly if the message is anyway ignord (e.g. debug message in non-debug mode).

Other improvements that would be particularly benefitial on the server side:

*Memory allocation failure are not always duly handled. In some cases, that could potentially be leveraged by a client to crash a VLC server by causing a very large allocation attempt.
*Rewrite and revive the root wrapper to allow VLC to bind to the RTSP (554) port while not retaining root privileges.

Contact: [[User:Courmisch|Courmisch]]

== VideoLAN Subtitle Editor ==

The "VideoLAN Subtitle Editor" is runs on any OS that is supported by libvlc.

Features:
* Qt4 Interface
* Media playback based on libvlc
* Multiple OS support (Linux, MacOS X, Windows, *BSD, ...)
* Internationalisation of subtitles
* Exporting to many subtitle formats (.srt, .ssa/.ass, .sub, .srt, .ssf, ...).

Examples of subtile editors:
* Subtitle Editor http://home.gna.org/subtitleeditor/
* Open Subtitle Editor http://opensubtitleed.sourceforge.net/
* Subtile formats: http://en.wikipedia.org/wiki/Subtitles

Contact: [[User:jpsaman|jpsaman]]

= Finished projects =

== Audioscrobbler ==

An [http://www.audioscrobbler.net/ Audioscrobbler] VLC Plug-in for the social music network [http://www.last.fm Last.Fm]<br>

Plugin is finished, now part of vlc 0.9.0 (development version). Done by [[User:Funman|funman]]

== DVB support for Windows / BDA Drivers ==

DVB is the norm for :

*Digital Terrestrial TV (aka DVB-T)
*Digital Cable TV (aka DVB-C)
*Digital Satellite TV (aka DVB-S)

Several DVB input cards exist. We support these on Linux, but not on Windows. For Windows, we need to support so-called BDA drivers.

The problem is that we don't have both the time and the required hardware on Windows comps.

This project is probably not terribly complex, but you need the hardware.

Plugin is done and availabe in the current Git version. Code by kenS

== DBus Integration ==

[[DBus]] is a communication mechanism for Linux (mainly).

We would like VLC to be able to use it so that other programs can interact with vlc (start/stop, know what is being played, ...)

Work is well advanced, see [[DBus]], by funman and Mr_Mirsal

Contact: [[User:Xtophe|Xtophe]], [[User:Funman|funman]]

== V4L2 support ==

VLC currently has a pvr module and a v4l (video for linux) module. However

*some cards are only supported in the new v4l2 API
*The linux kernel will soon drop v4l support

So if someone could update VLC's current modules to work with V4L2 and the new ivtv api, this would be a welcome addition. This is not a very difficult project, but you will need to have the hardware to test against. The code has been began, so it should not be too difficult.

Plugin is done and available in the current Git version. Code by Richard Hosking, [[User:Dionoea|dionoea]] and Dennis Lou.

== RTCP support ==

Our RTSP implementation (for broadcasting and video on demand) does not support the RTCP protocol. This is a must to have a real support for RTSP. Some work has already been started, but there is still much to do.

Contact: [[User:JPSaman|JPSaman]]

== Windows port ==

Finish port libcddb and libcdio for Windows.

Port libzvbi for Windows

Contact [[User:J-b|jb]]

== Improvements to the X11 video output ==

Fullscreen support to improve .

[[Category:Coding]] [[Category:Activities]]

== Subtitles improvements ==

{{VLC}} does not support all the styles for a lot of subtitles type. Take a look at [http://trac.videolan.org/vlc/browser/trunk/modules/codec/subtitles/subsdec.c here] to start coding.

Contact bitmap

== Direct2D video output ==

Direct2D is a new API introduced in Windows 7. VLC could use a a Direct2D vout.

Contact: [[User:Geal|Geal]]
== Interaction with online services ==
Hello, I would like to present their concept idea, it involves interaction with online services and some changes in the user interface of VLC Media Player.

On the first tab (Movie) is very straightforward, a user inserts a DVD, HD-DVD or BlyRay selects the desired slot and begin viewing.
In the future it will be possible to implement view of the disk image.

The second tab (Video), makes it possible to watch media files directly from the HDD.
Setting up a profile can be all sorted by category (Films, TV shows, etc.), the category of Films on (Action, Horror, Camedy), the category of TV show on (Lost, House M. D, X-Files), etc.
After watching a movie or TV show, you can not closing VLC media player immediately to share impressions with your friends on Twitter, MySpace, Facebook.

The third tab (Music), provides an opportunity to listen to music as a straight line from the HDD.
Similar to the previous tab, everything can be sorted into categories (Hip-Hop, R'n'B, Dance, Rock).

Another idea is to tab Online TV, where you can make a small internet browser tied to popular online Servas (YouTube) and send links to interesting videos to friends directly from the VLC Player.

Contact: [[User_talk:Jack.LJ|Jack.LJ]]

=Discussions on projects=

==Proposals==

* [[Newplaylist|Playlist improvement]]<br/>
* [[Newsoundslider|Soundslider improevment]]

Documentation:WebPlugin

2010-09-07T11:24:08Z

Jpsaman: Add new deinterlace modes

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 targeting at all of the major OS out there.

This is only valid for {{VLC}} version 0.8.6 and above.

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.

== 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 asking for vlc.input.length when there is no playlist item playing.

The vlc plugin knows the following objects:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''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).

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as 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.removeEvent(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''': vlc is buffering
*'''MediaPlayerPlaying''': vlc is playing a media
*'''MediaPlayerPaused''': vlc is in paused state
*'''MediaPlayerForward''': vlc is fastforwarding through the media (works only when an input supports forward playback)
*'''MediaPlayerBackward''': vlc is going backwards through the media (works only when an input supports backwards playback)
*'''MediaPlayerEncounteredError''': vlc has encountered an error and is unable to continue
*'''MediaPlayerEndReached''': vlc has reached the end of current playlist
*'''MediaPlayerTimeChanged''': time has changed
*'''MediaPlayerPositionChanged''': media position has changed
*'''MediaPlayerSeekableChanged''': media seekable flag has changed (true means media is seekable, false means it is not)
*'''MediaPlayerPausableChanged''': media pausable flag has changed (true means media is pauseable, false means it is not)

The following code snippit provides easy functions to register and unregister event callbacks on all supported platforms (currently only Linux mozilla based browsers and windows activeX objects for Internet Explorer).

<SCRIPT language="javascript">


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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-07-22T08:23:10Z

Jpsaman: /* API description */ mark log, messages and iterator as vlc <= 1.0.0-rc1 only

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 targeting at all of the major OS out there.

This is only valid for {{VLC}} version 0.8.6 and above.

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.

== 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 asking for vlc.input.length when there is no playlist item playing.

The vlc plugin knows the following objects:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''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).

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as 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.removeEvent(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''': vlc is buffering
*'''MediaPlayerPlaying''': vlc is playing a media
*'''MediaPlayerPaused''': vlc is in paused state
*'''MediaPlayerForward''': vlc is fastforwarding through the media (works only when an input supports forward playback)
*'''MediaPlayerBackward''': vlc is going backwards through the media (works only when an input supports backwards playback)
*'''MediaPlayerEncounteredError''': vlc has encountered an error and is unable to continue
*'''MediaPlayerEndReached''': vlc has reached the end of current playlist
*'''MediaPlayerTimeChanged''': time has changed
*'''MediaPlayerPositionChanged''': media position has changed
*'''MediaPlayerSeekableChanged''': media seekable flag has changed (true means media is seekable, false means it is not)
*'''MediaPlayerPausableChanged''': media pausable flag has changed (true means media is pauseable, false means it is not)

The following code snippit provides easy functions to register and unregister event callbacks on all supported platforms (currently only Linux mozilla based browsers and windows activeX objects for Internet Explorer).

<SCRIPT language="javascript">


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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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" 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.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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-07-22T08:20:48Z

Jpsaman: /* Root object */ Remove event not available in master.git

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 targeting at all of the major OS out there.

This is only valid for {{VLC}} version 0.8.6 and above.

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.

== 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 asking for vlc.input.length when there is no playlist item playing.

The vlc plugin knows the following objects:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as 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.removeEvent(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''': vlc is buffering
*'''MediaPlayerPlaying''': vlc is playing a media
*'''MediaPlayerPaused''': vlc is in paused state
*'''MediaPlayerForward''': vlc is fastforwarding through the media (works only when an input supports forward playback)
*'''MediaPlayerBackward''': vlc is going backwards through the media (works only when an input supports backwards playback)
*'''MediaPlayerEncounteredError''': vlc has encountered an error and is unable to continue
*'''MediaPlayerEndReached''': vlc has reached the end of current playlist
*'''MediaPlayerTimeChanged''': time has changed
*'''MediaPlayerPositionChanged''': media position has changed
*'''MediaPlayerSeekableChanged''': media seekable flag has changed (true means media is seekable, false means it is not)
*'''MediaPlayerPausableChanged''': media pausable flag has changed (true means media is pauseable, false means it is not)

The following code snippit provides easy functions to register and unregister event callbacks on all supported platforms (currently only Linux mozilla based browsers and windows activeX objects for Internet Explorer).

<SCRIPT language="javascript">


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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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" 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.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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-03-03T12:37:28Z

Jpsaman: updated events

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as 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.removeEvent(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''': vlc is buffering
*'''MediaPlayerPlaying''': vlc is playing a media
*'''MediaPlayerPaused''': vlc is in paused state
*'''MediaPlayerForward''': vlc is fastforwarding through the media (works only when an input supports forward playback)
*'''MediaPlayerBackward''': vlc is going backwards through the media (works only when an input supports backwards playback)
*'''MediaPlayerEncounteredError''': vlc has encountered an error and is unable to continue
*'''MediaPlayerEndReached''': vlc has reached the end of current playlist
*'''MediaPlayerTimeChanged''': time has changed
*'''MediaPlayerPositionChanged''': media position has changed
*'''MediaPlayerSeekableChanged''': media seekable flag has changed (true means media is seekable, false means it is not)
*'''MediaPlayerPausableChanged''': media pausable flag has changed (true means media is pausaable, false means it is not)
*'''MediaPlayerMouseGrab''': vlc video filter (eg: logo) detected a object movement in its video window and returns new X and Y coordinates

The following code snippit provides easy functions to register and unregister event callbacks on all supported platforms (currently only Linux mozilla based browsers and windows activeX objects for Internet Explorer).

<SCRIPT language="javascript">


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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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" 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.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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-02-16T22:17:40Z

Jpsaman: Describe arguments values from Mouse events

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as 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.removeEvent(eventname, callback)''': (only for ActiveX) remove listener for mentioned event name, callback expects a function

events
*'''NothingSpecial''': vlc is in idle state doing nothing but waiting for a command to be issued
*'''Opening''': vlc is opening an media resource locator (MRL)
*'''Buffering''': vlc is buffering
*'''Playing''': vlc is playing a media
*'''Paused''': vlc is in paused state
*'''Forward''': vlc is fastforwarding through the media (works only when an input supports forward playback)
*'''Backward''': vlc is going backwards through the media (works only when an input supports backwards playback)
*'''EncounteredError''': vlc has encountered an error and is unable to continue
*'''EndReached''': vlc has reached the end of current playlist
*'''TimeChanged''': time has changed
*'''PositionChanged''': media position has changed
*'''SeekableChanged''': media seekable flag has changed (true means media is seekable, false means it is not)
*'''PausableChanged''': media pausable flag has changed (true means media is pausaable, false means it is not)
*'''MouseMoved''': vlc detected a mouse movement in its video window. It returns x and y coordinates in vlc video output window.
*'''MouseButton''': vlc detected a mouse button event in its video window and returns a boolean for the buttons clicked, in order: mb_left, mb_center, mb_right, mb_wheel_up, mb_wheel_down
*'''MouseClick''': vlc detected a mouse click in its video window
*'''MouseObject''': vlc video filter (eg: logo) detected a object movement in its video window

The following code snippit provides easy functions to register and unregister event callbacks on all supported platforms (currently only Linux mozilla based browsers and windows activeX objects for Internet Explorer).

<SCRIPT language="javascript">


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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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" 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.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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-02-07T16:17:52Z

Jpsaman: /* Root object */ typos

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as 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.removeEvent(eventname, callback)''': (only for ActiveX) remove listener for mentioned event name, callback expects a function

events
*'''NothingSpecial''': vlc is in idle state doing nothing but waiting for a command to be issued
*'''Opening''': vlc is opening an media resource locator (MRL)
*'''Buffering''': vlc is buffering
*'''Playing''': vlc is playing a media
*'''Paused''': vlc is in paused state
*'''Forward''': vlc is fastforwarding through the media (works only when an input supports forward playback)
*'''Backward''': vlc is going backwards through the media (works only when an input supports backwards playback)
*'''EncounteredError''': vlc has encountered an error and is unable to continue
*'''EndReached''': vlc has reached the end of current playlist
*'''TimeChanged''': time has changed
*'''PositionChanged''': media position has changed
*'''SeekableChanged''': media seekable flag has changed (true means media is seekable, false means it is not)
*'''PausableChanged''': media pausable flag has changed (true means media is pausaable, false means it is not)
*'''MouseMoved''': vlc detected a mouse movement in its video window
*'''MouseButton''': vlc detected a mouse button event in its video window
*'''MouseClick''': vlc detected a mouse click in its video window
*'''MouseObject''': vlc filter (eg: logo) detected a object movement in its video window

The following code snippit provides easy functions to register and unregister event callbacks on all supported platforms (currently only Linux mozilla based browsers and windows activeX objects for Internet Explorer).

<SCRIPT language="javascript">


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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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" 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.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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-02-07T16:11:56Z

Jpsaman: /* Root object */ update example

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as 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.removeEvent(eventname, callback)''': ( only for ActiveX) remove listener for mentioned event name, callback expects a function

events
*'''NothingSpecial''': vlc is in idle state doing nothing but waiting for a command to be issued
*'''Opening''': vlc is opening an media resource locator (MRL)
*'''Buffering''': vlc is buffering
*'''Playing''': vlc is playing a media
*'''Paused''': vlc is in paused state
*'''Forward''': vlc is fastforwarding through the media (works only when an input supports forward playback)
*'''Backward''': vlc is going backwards through the media (works only when an input supports backwards playback)
*'''EncounteredError''': vlc has encountered an error and is unable to continue
*'''EndReached''': vlc has reached the end of current playlist
*'''TimeChanged''': time has changed
*'''PositionChanged''': media position has changed
*'''SeekableChanged''': media seekable flag has changed (true means media is seekable, false means it is not)
*'''PausableChanged''': media pausable flag has changed (true means media is pausaable, false means it is not)
*'''MouseMoved''': vlc detected a mouse movement in its video window
*'''MouseButton''': vlc detected a mouse button event in its video window
*'''MouseClick''': vlc detected a mouse click in its video window
*'''MouseObject''': vlc filter (eg: logo) detected a object movement in its video window

The following code snippit provides easy functions to register and unregister event callbacks on all supported platforms (currently only Linux mozilla based browsers and windows activeX objects for Internet Explorer).

<SCRIPT language="javascript">


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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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" 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.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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-02-07T16:09:15Z

Jpsaman: Document mouse JS events

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as 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.removeEvent(eventname, callback)''': ( only for ActiveX) remove listener for mentioned event name, callback expects a function

events
*'''NothingSpecial''': vlc is in idle state doing nothing but waiting for a command to be issued
*'''Opening''': vlc is opening an media resource locator (MRL)
*'''Buffering''': vlc is buffering
*'''Playing''': vlc is playing a media
*'''Paused''': vlc is in paused state
*'''Forward''': vlc is fastforwarding through the media (works only when an input supports forward playback)
*'''Backward''': vlc is going backwards through the media (works only when an input supports backwards playback)
*'''EncounteredError''': vlc has encountered an error and is unable to continue
*'''EndReached''': vlc has reached the end of current playlist
*'''TimeChanged''': time has changed
*'''PositionChanged''': media position has changed
*'''SeekableChanged''': media seekable flag has changed (true means media is seekable, false means it is not)
*'''PausableChanged''': media pausable flag has changed (true means media is pausaable, false means it is not)
*'''MouseMoved''': vlc detected a mouse movement in its video window
*'''MouseButton''': vlc detected a mouse button event in its video window
*'''MouseClick''': vlc detected a mouse click in its video window
*'''MouseObject''': vlc filter (eg: logo) detected a object movement in its video window

The following code snippit provides easy functions to register and unregister event callbacks on all supported platforms (currently only Linux mozilla based browsers and windows activeX objects for Internet Explorer).

<SCRIPT language="javascript">


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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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" 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.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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-02-03T22:44:49Z

Jpsaman: document JS events

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as 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.removeEvent(eventname, callback)''': ( only for ActiveX) remove listener for mentioned event name, callback expects a function

events
*'''Idle''': vlc is in idle state doing nothing but waiting for a command to be issued
*'''Opening''': vlc is opening an media resource locator (MRL)
*'''Playing''': vlc is playing a media
*'''Pausing''': vlc is in paused state
*'''Forward''': vlc is fastforwarding through the media (works only when an input supports forward playback)
*'''Backward''': vlc is going backwards through the media (works only when an input supports backwards playback)
*'''Error''': vlc has encountered an error and is unable to continue
*'''EndReached''': vlc has reached the end of current playlist
*'''TimeChanged''': time has changed
*'''PositionChanged''': media position has changed
*'''SeekableChanged''': media seekable flag has changed (true means media is seekable, false means it is not)
*'''PausableChanged''': media pausable flag has changed (true means media is pausaable, false means it is not)

The following code snippit provides easy functions to register and unregister event callbacks on all supported platforms (currently only Linux mozilla based browsers and windows activeX objects for Internet Explorer).

<SCRIPT language="javascript">


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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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" 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.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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-02-03T22:42:37Z

Jpsaman: document JS events

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as 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.removeEvent(eventname, callback)```: ( only for ActiveX) remove listener for mentioned event name, callback expects a function

events
*```Idle```: vlc is in idle state doing nothing but waiting for a command to be issued
*```Opening```: vlc is opening an media resource locator (MRL)
*```Playing```: vlc is playing a media
*```Pausing```: vlc is in paused state
*```Forward```: vlc is fastforwarding through the media (works only when an input supports forward playback)
*```Backward```: vlc is going backwards through the media (works only when an input supports backwards playback)
*```Error```: vlc has encountered an error and is unable to continue
*```EndReached```: vlc has reached the end of current playlist
*```TimeChanged```: time has changed
*```PositionChanged```: media position has changed
*```SeekableChanged```: media seekable flag has changed (true means media is seekable, false means it is not)
*```PausableChanged```: media pausable flag has changed (true means media is pausaable, false means it is not)

The following code snippit provides easy functions to register and unregister event callbacks on all supported platforms (currently only Linux mozilla based browsers and windows activeX objects for Internet Explorer).

<SCRIPT language="javascript">


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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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" 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.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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-01-31T08:40:13Z

Jpsaman: Document vlc.video.deinterlace.enabledisable change

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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.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
*'''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

=====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" 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.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) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-01-22T10:33:21Z

Jpsaman: Note removal of Log, Messages and Messages Iterator object

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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

readonly properties

* ''none''

read/write properties

*'''vlc.video.marquee.text''': (supported in vlc version >= 1.1.0) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====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 nore than 256 entries) and can easily overflow, therefore messages should be read and cleared as often as possible.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

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

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

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

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use. They no longer work on recent VLC version (> 0.8.5), either it being the ActiveX (Internet Explorer)/ Safari or Mozilla based browsers.

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-01-22T09:55:24Z

Jpsaman: /* Logo Object */ remove 'events' section

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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

readonly properties

* ''none''

read/write properties

*'''vlc.video.marquee.text''': (supported in vlc version >= 1.1.0) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

====Log object====
: '''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.

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-01-22T09:54:47Z

Jpsaman: /* Marquee Object */ update documentation to match current code

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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

readonly properties

* ''none''

read/write properties

*'''vlc.video.marquee.text''': (supported in vlc version >= 1.1.0) 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=0, LEFT=1, RIGHT=2, TOP=4, TOP-LEFT=5, TOP-RIGHT=6, BOTTOM=8, BOTTOM-LEFT=9, BOTTOM_RIGHT=10).
*'''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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

events

* ''none''

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.

====Log object====
: '''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.

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-01-19T10:11:18Z

Jpsaman: /* Logo Object */ fix typo

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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

readonly properties

* ''none''

read/write properties

* ''none''

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.
*'''vlc.video.marquee.text("my text")''': (supported in vlc version >= 1.1.0) display my text on the screen.
*'''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.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.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.refresh(int val)''': (supported in vlc version >= 1.1.0) change the marquee refresh period.
*'''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.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 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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

events

* ''none''

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.

====Log object====
: '''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.

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-01-19T10:10:55Z

Jpsaman: /* Logo Object */ reflect reality

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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

readonly properties

* ''none''

read/write properties

* ''none''

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.
*'''vlc.video.marquee.text("my text")''': (supported in vlc version >= 1.1.0) display my text on the screen.
*'''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.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.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.refresh(int val)''': (supported in vlc version >= 1.1.0) change the marquee refresh period.
*'''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.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 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.

=====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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

events

* ''none''

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.

====Log object====
: '''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.

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-01-18T09:20:38Z

Jpsaman: /* Logo Object */ cleanup vlc.video.logo API

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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

readonly properties

* ''none''

read/write properties

* ''none''

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.
*'''vlc.video.marquee.text("my text")''': (supported in vlc version >= 1.1.0) display my text on the screen.
*'''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.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.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.refresh(int val)''': (supported in vlc version >= 1.1.0) change the marquee refresh period.
*'''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.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 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.

=====Logo Object=====

readonly properties

* ''none''

read/write properties
*'''vlc.video.logo.transparency''': (supported in vlc version >= 1.1.0) change the picture opacity, val is defined from 0 (completely opaque) to 255 (completely transparent).
*'''vlc.video.logo.position''': (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.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.
*'''vlc.video.logo.width''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height''': (supported in vlc version >= 1.1.0) change the picture height.

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.

events

* ''none''

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.

====Log object====
: '''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.

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

Documentation:WebPlugin

2010-01-18T09:02:36Z

Jpsaman: /* API description */ vlc.video.logo

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari ==

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 is only valid for {{VLC}} version 0.8.6 and above.

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.

== API description ==
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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''subtitle''': Access subtitle properties.
*'''video''': Access video properties.
*'''video.marquee''': Access marquee video filter properties.
*'''video.logo''': Access logo video filter properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

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

Audio Channel:
<SELECT readonly 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 language="javascript">


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.

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====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. If set to a value outside the current subtitle tracks range, then it will return -1 and display an error message.

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

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

readonly properties

* ''none''

read/write properties

* ''none''

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.
*'''vlc.video.marquee.text("my text")''': (supported in vlc version >= 1.1.0) display my text on the screen.
*'''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.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.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.refresh(int val)''': (supported in vlc version >= 1.1.0) change the marquee refresh period.
*'''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.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 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.

=====Logo Object=====

readonly properties

* ''none''

read/write properties

* ''none''

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.
*'''vlc.video.logo.transparency(int val)''': (supported in vlc version >= 1.1.0) change the picture opacity, val is defined from 0 (completely opaque) to 255 (completely transparent).
*'''vlc.video.logo.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.logo.delay(int val)''': (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.repeata(int val)''': (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(int val)''': (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(int val)''': (supported in vlc version >= 1.1.0) change the y-offset for displaying the picture counting from top-left on the screen.
*'''vlc.video.logo.width(int val)''': (supported in vlc version >= 1.1.0) change the picture width.
*'''vlc.video.logo.height(int val)''': (supported in vlc version >= 1.1.0) change the picture height.

events

* ''none''

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.

====Log object====
: '''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.

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[#Messages object|Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

==Build HTML pages that use the plugin (VLC version up to 0.8.5)==

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

===Example 1===

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

===Example 2===

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

{{Documentation}}
[[Category:Embedded]]

TS Info

2009-12-21T16:46:51Z

Jpsaman: /* Architecture */

= TS Info =

In the Open Source multimedia field there are various choices for multimedia streaming and playback. However analysing and checking validity of MPEG-TS streams is not really possible. DVBsnoop (http://dvbsnoop.sourceforge.net/) is the only application that is only one that comes near this goal, but it is a commandline utility. This doesn't make it easy to be used.

The goal of TS Info is to be an easy to use MPEG-TS (MPTS/SPTS) analyser with all the information, analysis and validation right under you finger tips.

It should also be possible to insert the TS Analyser/TS Monitor in between the client and the server and monitor the stream for the boundaries configured. If the boundaries (or rules) are crossed, then a trigger will be sent to indicate a deviation from the required settings.

== Features ==

* Input from TS/RTP/UDP or TS/UDP
* Possible extension to use linux-dvb device (maybe use dvblast as input)
* PID list and bandwidths / %age - bargraph
* Bitrates (also audio and video separate)
* Mux distance of audio and video packets
* SI table parsing (NIT, PMT, PAT, EIT, CAT, etc.) / descriptor parsing
* Detect scrambled content (check scrambling bits 11, 10, optional 01/00)
* I-frame gap
* Determine GOP length
* Detect Open/Closed GOP
* Teletext/closed captioning detection
* CRC errors
* I-frame decoding
* Discontinuity indication
* Subtitle decoding
* EPG grid
* PID selection and forwarding to VLC (via UDP stream?)
* Triggers on deviation from set boundaries (mux distance < 500ms, if not then sent trigger eg: sms/e-mail)
* Mention conformance to which standard and link to it if online source is available

== Architecture ==

proposal:
TS Analyser GUI - user interface to browse the MPEG-TS stream content (information gathered is similar to DVBsnoop)
TS Analyser - real-time MPEG-TS analyser that informs the GUI/TS Monitor of features discovered and various measurements
TS Monitor - real-time MPEG-TS monitor that triggers on deviations of preferred features in the MPEG-TS stream

TS Analyser GUI
|

MPEG-TS --------> RTP/UDP input ---> TS Analyser --> RTP/UDP output
(MPTS/SPTS) |
TS Monitor --> send trigger if deviation detected

== License ==

TS Analyser GUI : GPLv2
TS Analyser library : LGPLv2.1
TS Monitor daemon : GPLv2

TS Info

2009-12-21T16:46:15Z

Jpsaman: /* Architecture */

= TS Info =

In the Open Source multimedia field there are various choices for multimedia streaming and playback. However analysing and checking validity of MPEG-TS streams is not really possible. DVBsnoop (http://dvbsnoop.sourceforge.net/) is the only application that is only one that comes near this goal, but it is a commandline utility. This doesn't make it easy to be used.

The goal of TS Info is to be an easy to use MPEG-TS (MPTS/SPTS) analyser with all the information, analysis and validation right under you finger tips.

It should also be possible to insert the TS Analyser/TS Monitor in between the client and the server and monitor the stream for the boundaries configured. If the boundaries (or rules) are crossed, then a trigger will be sent to indicate a deviation from the required settings.

== Features ==

* Input from TS/RTP/UDP or TS/UDP
* Possible extension to use linux-dvb device (maybe use dvblast as input)
* PID list and bandwidths / %age - bargraph
* Bitrates (also audio and video separate)
* Mux distance of audio and video packets
* SI table parsing (NIT, PMT, PAT, EIT, CAT, etc.) / descriptor parsing
* Detect scrambled content (check scrambling bits 11, 10, optional 01/00)
* I-frame gap
* Determine GOP length
* Detect Open/Closed GOP
* Teletext/closed captioning detection
* CRC errors
* I-frame decoding
* Discontinuity indication
* Subtitle decoding
* EPG grid
* PID selection and forwarding to VLC (via UDP stream?)
* Triggers on deviation from set boundaries (mux distance < 500ms, if not then sent trigger eg: sms/e-mail)
* Mention conformance to which standard and link to it if online source is available

== Architecture ==

proposal:
TS Analyser GUI - user interface to browse the MPEG-TS stream content (information gathered is similar to DVBsnoop)
TS Analyser - real-time MPEG-TS analyser that informs the GUI/TS Monitor of features discovered and various measurements
TS Monitor - real-time MPEG-TS monitor that triggers on deviations of preferred features in the MPEG-TS stream

{{{
TS Analyser GUI
|

MPEG-TS --------> RTP/UDP input ---> TS Analyser --> RTP/UDP output
(MPTS/SPTS) |
TS Monitor --> send trigger if deviation detected
}}}

== License ==

TS Analyser GUI : GPLv2
TS Analyser library : LGPLv2.1
TS Monitor daemon : GPLv2

TS Info

2009-12-21T15:23:48Z

Jpsaman: TS Info description

Documentation:Advanced Use of VLC

2009-05-05T09:19:29Z

Jpsaman: /* Input object */ use html safe < and >

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast RTP/UDP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@:5004'''

If 5004 is the port to which packets are sent. 1234 is another commonly used port number. you use the default port (1234), '''vlc rtp://''' will do.
For more information, look at the Streaming Howto.

To receive an multicast UDP/RTP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@multicast_address:port'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc rtp://server_address@multicast_address:port'''

This only works on OSs that support SSM (Windows XP and Linux).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--grayscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2009-05-05T09:01:09Z

Jpsaman: /* Input object */ clarify return value for input.length

Documentation:Advanced Use of VLC

2009-05-05T07:46:20Z

Jpsaman: /* Playlist object */ aspect-ratio is with : iso x

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast RTP/UDP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@:5004'''

If 5004 is the port to which packets are sent. 1234 is another commonly used port number. you use the default port (1234), '''vlc rtp://''' will do.
For more information, look at the Streaming Howto.

To receive an multicast UDP/RTP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@multicast_address:port'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc rtp://server_address@multicast_address:port'''

This only works on OSs that support SSM (Windows XP and Linux).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--grayscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2009-05-05T07:41:39Z

Jpsaman: /* Playlist object */ add option array example

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast RTP/UDP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@:5004'''

If 5004 is the port to which packets are sent. 1234 is another commonly used port number. you use the default port (1234), '''vlc rtp://''' will do.
For more information, look at the Streaming Howto.

To receive an multicast UDP/RTP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@multicast_address:port'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc rtp://server_address@multicast_address:port'''

This only works on OSs that support SSM (Windows XP and Linux).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--grayscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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).
var options = new Array(":aspect-ratio=4x3", "--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.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2009-04-27T09:50:49Z

Jpsaman: /* Input object */ Clarify stopping/ended

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast RTP/UDP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@:5004'''

If 5004 is the port to which packets are sent. 1234 is another commonly used port number. you use the default port (1234), '''vlc rtp://''' will do.
For more information, look at the Streaming Howto.

To receive an multicast UDP/RTP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@multicast_address:port'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc rtp://server_address@multicast_address:port'''

This only works on OSs that support SSM (Windows XP and Linux).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--grayscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative 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.
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2009-03-09T16:00:12Z

Jpsaman: /* Input object */ document rate settings

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast RTP/UDP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@:5004'''

If 5004 is the port to which packets are sent. 1234 is another commonly used port number. you use the default port (1234), '''vlc rtp://''' will do.
For more information, look at the Streaming Howto.

To receive an multicast UDP/RTP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@multicast_address:port'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc rtp://server_address@multicast_address:port'''

This only works on OSs that support SSM (Windows XP and Linux).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--grayscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ENDED=6, ERROR=7).
*'''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 : is fastforward
rate > 0 and rate < 1 : is slow motion
rate < 0 : is rewind

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2009-03-09T15:56:29Z

Jpsaman: /* Input object */ remove FORWARD, BACKWARD since it never got used anyway.

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast RTP/UDP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@:5004'''

If 5004 is the port to which packets are sent. 1234 is another commonly used port number. you use the default port (1234), '''vlc rtp://''' will do.
For more information, look at the Streaming Howto.

To receive an multicast UDP/RTP stream (sent by VLC's stream output), start VLC with:

% '''vlc rtp://@multicast_address:port'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc rtp://server_address@multicast_address:port'''

This only works on OSs that support SSM (Windows XP and Linux).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--grayscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP/RTP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="rtp://@239.255.12.42:5004" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ENDED=6, ERROR=7).
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2008-11-20T17:27:57Z

Jpsaman: /* Input object */ reserved -> deprecated

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, FORWARD=6, BACKWARD=7, ENDED=8, ERROR=9). '''Note that FORWARD and BACKWARD states are deprecated and will be removed in version 1.0.'''
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2008-11-20T14:39:04Z

Jpsaman: /* Input object */ flag removal of unused states FORWARD/BACKWARD

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorer/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, FORWARD=6, BACKWARD=7, ENDED=8, ERROR=9). '''Note that FORWARD and BACKWARD states are currently reserved and will be removed in version 1.0.'''
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2008-06-15T12:23:48Z

Jpsaman: /* Input object */ Typo

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorere/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, FORWARD=6, BACKWARD=7, ENDED=8, ERROR=9). '''Note that FORWARD and BACKWARD states are currently reserved and not yet operational.'''
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2008-06-14T20:25:30Z

Jpsaman: /* Input object */ Added ENDED as extra state

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorere/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, FORWARD=6, BACWARD=7, ENDED=8, ERROR=9). '''Note that FORWARD and BACKWARD states are currently reserved and not yet operational.'''
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2008-06-14T12:56:01Z

Jpsaman: /* Input object */ update VLC states

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorere/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, FORWARD=6, BACWARD=7, ERROR=8). '''Note that FORWARD and BACKWARD states are currently reserved and not yet operational.'''
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[#Playlist_items_object| 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 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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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  ('''deprecated''', do not use, see [[#Playlist_items_object| Playlist items]])

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

ActiveX

2008-06-10T12:12:36Z

Jpsaman: Add a note about the old and new interface.

The [[Windows]] build of VLC includes an (optionaly installed) '''ActiveX control'''. The ActiveX control enables VLC to be embedded in web browsers and third-party applications.

==Properties==

The ActiveX control includes the following properties:
{|
|'''''name'''''
|'''''type'''''
|'''''get or set'''''
|'''''description'''''
|-
|Length
|Integer
|get
|Returns length of the current clip.
|-
|playlistCount
|
|get
|Returns the count of items in the playlist
|-
|playlistIndex
|
|get
|Returns the index of the current item in the playlist.
|-
|AutoLoop
|Boolean
|get/set
|Determines if the player should automatically loop when it finishes the current playlist.
|-
|AutoPlay
|Boolean
|get/set
|Determines if the player should start playing a new file/playlist immediately upon being loaded.
|-
|Volume
|Integer
|get/set
|Current volume (scaled from 0 to 100)
|-
|MRL
|String
|get/set
|Presumably returns the MRL of the currently loaded file.
|-
|Time
|Integer
|get/set
|Time elapsed in seconds playing current MRL, 0 for live feed
|-
|showdisplay
|Boolean
|get/set
|show/hide control viewport
|-
|Playing
|Boolean
|get
|Returns whether some MRL is playing
|-
|Position
|'real'
|get/set
|Playback position within current MRL, scaled from 0.0 to 1.0. Live feed returns 0.0
|-
|VersionInfo
|String
|get
|Returns version and build information.
|}
Note: In Visual Basic, type "Long" should be used for properties listed with type "Integer".

==Important==
The API described in this page only reflects VLC ActiveX controls prior to 0.8.5.1 It is not adviced to use this JS API any longer. Please use the VLC ActiveX v2 interface as described in: http://www.videolan.org/doc/play-howto/en/ch04.html#id310965 (Subject: "Build HTML pages that use the plugin (version > 0.8.5.1)") or http://wiki.videolan.org/Documentation:Play_HowTo/Advanced_Use_of_VLC#Building_HTML_pages_for_Mozilla.2FFirefox.2FInternet_Explorere.2FSafari_.28VLC_version_0.8.6_and_above.29

The new JS API interface is exactly the same for Internet Explorer, Mozilla/Firefox and Safari. Thus easing the maintenance and developing of webpages for the VLC browser plugins.

==Methods==
The ActiveX control includes the following methods (functions):
{|
|'''''name'''''
|'''''type'''''
|'''''description'''''
|'''''syntax ([[wikipedia:Visual Basic|VB]])'''''
|-
|setVariable
|method
|Assigns a value to a variable that is defined in libvlc.c
|controlname.setVariable name as String, value
|-
|getVariable
|method
|Returns the contents of a variable that is defined in libvlc.c
|x = controlname.getVariable(name as String)
|-
|pause
|method
|Pauses the currently playing clip
|controlname.pause
|-
|play
|method
|Plays as in the normal player, if a clip is not loaded, does nothing.
|controlname.play
|-
|playFaster
|method
|Makes the currently playing clip play faster.
|controlname.playFaster
|-
|playSlower
|method
|Makes the currently playing clip play slower.
|controlname.playSlower
|-
|stop
|method
|Makes the currently playing clip stop.
|controlname.stop
|-
|shuttle
|method
|Moves the playback position a specified number of seconds in either direction.
|controlname.shuttle(seconds as Long)
|-
|playlistClear
|method
|Clears the playlist
|controlname.playlistClear
|-
|playlistNext
|method
|Goes to next item in the playlist
|controlname.playlistNext
|-
|playlistPrev
|method
|Goes to previous item in the playlist
|controlname.playlistPrev
|-
|addTarget
|method
|Adds a uri to the current playlist or replaces the current playlist with the uri.
|controlname.addTarget(uri as String, options, mode as [[VLCPlaylistMode]], Position as Long)
|-
|toggleMute
|method
|Toggles between the muted/unmuted state of the embedded player.
|controlname.toggleMute
|-
|fullscreen
|method
|Toggles between fullscreen and non-fullscreen modes.
|controlname.fullscreen
|}

==Options==
The <code>addTarget</code> method accepts most of the command line options; including, but not limited to, the following :
*<code>:audio-track=''index''</code>
*<code>:vout-filter=''output-filter''</code> (<code>deinterlace</code> for example)
*<code>:deinterlace-mode=''mode''</code> (<code>linear</code> for example)

==Samples==
*[[ActiveX/Delphi|Delphi Implementation]]

* [[ActiveX/HTML|HTML Implementation]]

==Installing==
===Introduction===

VideoLAN is not a good source for the installation of VLC through an ActiveX control. At some point, Microsoft Internet Explorer stopped allowing the installation of ActiveX controls unless:
* they were signed to associate the software vendor's name with the file containing the ActiveX control, or
* they resided in an "trusted site" (from the user's perspective, running Internet Explorer)
The second option is only feasible where both server and client infrastructure are managed under the same umbrella, i.e. where the server providing the ActiveX control can be declared "trusted". This is not feasible in the open web. In a web configuration, a [http://en.wikipedia.org/wiki/Certificate_authority Certificate Authority] needs to digitally sign the ActiveX control. This comes at a cost which the VideoLAN project is not able to bear. The solution is to create one's own ActiveX control distribution, which in turn can be digitally signed by a Certificate Authority of your choice, if necessary.

===Creating an VLC ActiveX Distribution===
The following requisites are required:
* CABSDK by Microsoft to create a [http://en.wikipedia.org/wiki/Cabinet_%28file_format%29 Cabinet File] (.cab-file) containing the relevant ActiveX control and VLC files. MSDN has [http://msdn2.microsoft.com/en-us/library/aa751974.aspx a good description how to package an ActiveX Control], including a link to the CABSDK download page.
* The .cab-file is a special form of a .zip file, consisting of:
** axvlc.inf - The INF file, which would be called manifest in the modern age
** axvlc.dll - ActiveX DLL which bootstraps the VLC setup file
** vlc-0.8.6e-win32.exe - VLC setup file (refer to your version)

I am using the following code in the INF file:
<pre><nowiki>
; Version number and signature of INF file.
;
[version]
signature="$CHICAGO$"
AdvancedINF=2.0

[Add.Code]
vlc-0.8.6e-win32.exe
axvlc.dll=axvlc.dll

[axvlc.dll]
FileVersion=0,8,6,0
clsid={9BE31822-FDAD-461B-AD51-BE1D1C159921}
RegisterServer=no
hook=nsiinstaller

[vlc-0.8.6e-win32.exe]
FileVersion=0,8,6,0
file-win32-x86=thiscab

[nsiinstaller]
run=%EXTRACT_DIR%\vlc-0.8.6e-win32.exe
</nowiki></pre>
Again, refer to your version of VLC.

You can extract axvlc.dll from the binary distribution of VLC. This is a zip file on VideoLAN's download page, version 0.8.6.e [http://downloads.videolan.org/pub/videolan/vlc/0.8.6e/win32/vlc-0.8.6e-win32.zip here].

The regular VLC setup file is the "featured" download on VideoLAN's main page; a copy resides in the same directory as axvlc.dll, the VLC setup file of version 0.8.6.e [http://downloads.videolan.org/pub/videolan/vlc/0.8.6e/win32/vlc-0.8.6e-win32.exe here].

With CABSDK installed and the three components in place, you can create the .cab-file using the CABARC tool from Microsoft's CABSDK, using the following command from a command prompt:

<pre><nowiki>CABARC.EXE N axvlc.cab axvlc.inf axvlc.dll vlc-0.8.6e-win32.exe</nowiki></pre>
This assumes the [http://en.wikipedia.org/wiki/Path_%28computing%29 PATH] has been set to CABARC.EXE's directory. If you need to sign the .cab-file, you need to use the -s switch to allocate space for your digital certificate.

===.cab-file Integration===
The .cab file is integrated as described in the [http://wiki.videolan.org/ActiveX#Samples samples above], using the <OBJECT> element in the case of HTML, for example. When the ActiveX Control is called for the first time, i.e. prior to VLC installation through any means, the setup program should start up. Unfortunately, users have to click through a few dialogs, "allow blocked contents" or deal with other inconveniences, depending on your configuration and the user's security settings of Internet Explorer. The user must have proper rights to install VLC on the user's computer; identical to a regular installation of VLC as required by the VLC setup program.

==See Also==
*[http://git.videolan.org/?p=vlc.git;a=blob;f=projects/activex/README.TXT Official ReadMe]

[[Category:Embedded]]

Documentation:Advanced Use of VLC

2007-12-18T09:20:19Z

Jpsaman: /* Video object */ not sure about 0 for hiding teletext, needs experimenting

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorere/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ERROR=6)
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[Playlist items object]]

read/write properties
*''none''

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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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 (note: this number isn't the position in the playlist, but the number given by vlc.playlist.add() )

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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
*'''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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2007-12-18T09:18:19Z

Jpsaman: /* Video object */ Limit the range

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorere/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ERROR=6)
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[Playlist items object]]

read/write properties
*''none''

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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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 (note: this number isn't the position in the playlist, but the number given by vlc.playlist.add() )

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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 -1 means hide teletext. On error it will return -1 and display an error message.

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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2007-12-18T08:35:17Z

Jpsaman: /* Video object */ Document teletext transparent overlay method

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorere/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ERROR=6)
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[Playlist items object]]

read/write properties
*''none''

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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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 (note: this number isn't the position in the playlist, but the number given by vlc.playlist.add() )

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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..65535] for indicating the teletext page to view, setting the value to -1 means hide teletext. On error it will return -1 and display an error message.

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

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2007-12-18T08:06:44Z

Jpsaman: /* Video object */ Document teletext feature.

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorere/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ERROR=6)
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[Playlist items object]]

read/write properties
*''none''

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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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 (note: this number isn't the position in the playlist, but the number given by vlc.playlist.add() )

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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.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..65535] for indicating the teletext page to view, setting the value to -1 means hide teletext. On error it will return -1 and display an error message.

methods
*'''vlc.video.toggleFullscreen()''': toggle the fullscreen mode based on the previous setting

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Streaming

2007-12-06T14:13:30Z

Jpsaman: censored spam

VideoLAN in the news

2007-12-03T10:31:10Z

Jpsaman: VLC in the news 2007

{| class="infobox"
| [http://news.google.co.uk/news?as_q=&svnum=10&as_scoring=r&hl=en&tab=wn&ie=UTF-8&btnG=Google+Search&as_epq=&as_oq=VLC+VideoLAN&as_eq=&as_nsrc=&as_nloc=&as_occt=any&as_drrb=q&as_qdr=&as_mind=9&as_minm=9&as_maxd=9&as_maxm=10 Search Google News] for the latest on VLC ([http://news.google.co.uk/news?svnum=10&as_scoring=r&hl=en&tab=wn&ie=UTF-8&as_drrb=q&as_qdr=&as_mind=9&as_minm=9&as_maxd=9&as_maxm=10&q=VLC+OR+VideoLAN&output=rss RSS feed])
|}
List of articles related to VideoLAN / VLC media player. Please add those which are missing.

== 2007 ==

[http://articles.techrepublic.com.com/2415-7343_11-175865.html SolutionBase: Overcome multimedia hurdles in Linux]

== 2006 ==

[http://software.newsforge.com/article.pl?sid=06/04/19/1711245&from=rss "NewsForge, Transcoding and streaming DVD films with VLC media player"]

[http://www.lesechos.fr/journal20061004/lec2_innovation/4475889.htm Les Echos (France), "Le lecteur multimédia français VLC téléchargé 18 millions de fois"]

[http://www.m2x.nl/mambo/index.php?option=content&task=view&id=124&Itemid=27 M2X Article and NLUUG talk (Netherlands) "Streaming networks with VLC"]

== 2005 ==
[http://www.01net.com/article/284013.html 01net.com (France)]

[http://blogs.zdnet.fr/index.php/2005/06/28/vlc-un-lecteur-multimedia-tres-courtise/ ZDNet (France), "VLC: un lecteur multimedia très courtisé"]

[http://solutions.journaldunet.com/0506/050613_videolan.shtml solutions.journaldunet.com (France)]

[http://www.theregister.co.uk/2005/09/02/dvd_jon_mediaplayer/ The Register (UK), "DVD Jon hacks Media Player file encryption"]

[http://www.source21.nl/2005/12/27/linuxworld-videolan-en-vlc Source21.nl (Netherlands), "LinuxWorld: VideoLAN en VLC (Interview with Jean-Paul Saman)"]

[http://www.macplus.net/magplus/chronique-9311-interview-de-christophe-massiot MacPlus (France), "Interview de Christophe Massiot"]

[http://home.planet.nl/~jpsaman/linux/downloads/vlc_open_source_multimedia.sxi LinuxWorld (Netherlands), "Open Source multimedia by Jean-Paul Saman"]

== 2004 ==

[http://builder.com.com/5100-6375-5136135.html Builder.com (USA?), "Open Source Awards 2004: VideoLAN"]

[http://www.streamingmedia.com/article.asp?id=9000&page=1&c= streamingmedia.com (USA?), "VideoLAN's Piece de Resistance"]

[http://home.planet.nl/~jpsaman/linux/downloads/videolan-fosdem-2004.pdf FOSDEM (Belgium) "VideoLAN VLC presentation at FOSDEM by Jean-Paul Saman"]

== 2002 ==

[http://download.videolan.org/images/macworld0-doublepage.jpg Mac World, "Les petits princes du MPEG-2"]

[http://www.mac4ever.com/articles/humeur/336/interview_de_christophe_massiot_de_vlc/ Mac4ever (France), "Interview de Christophe Massiot de VLC"]

[[Category:About VideoLAN]]

Documentation:User Guide

2007-12-01T11:12:54Z

Jpsaman: extra whitespace

{{RightMenu|documentation play howto toc}}

Authors:
* Alexis de Lattre
* Johan Bilien
* Anil Daoud
* Clément Stenac
* Jean-Paul Saman

Copyright (c) 2002-2006 the VideoLAN project

{{GPL}}

'''This document is the complete user guide for the VLC media player.'''

*[[Documentation:Play_HowTo/Introduction to VLC|Introduction]]
**Overview and history of the VideoLAN project.
*[[Documentation:Play_HowTo/Installing VLC|Installation]]
**Installation instructions for a variety of computers.
*[[Documentation:Play_HowTo/Basic Use|Basic Use]]
**How to play audio/video materials with the VLC media player.
*[[Documentation:Play_HowTo/Advanced Use of VLC|Advanced Use]]
**Advanced instruction on streams, filters, plug-ins and more.

==See also==

*[[Documentation:Play_HowTo/Building Pages for the HTTP Interface|Building Pages for the HTTP Interface]]
*[[Documentation:Play_HowTo/Format String|Format String]]
*[[Documentation:Play_HowTo/Building Lua Playlist Scripts|Building Lua Playlist Scripts]]

{{Documentation}}

Copyright © 2002-2007 the VideoLAN project.

Documentation:User Guide

2007-12-01T11:12:28Z

Jpsaman: Add authors

Documentation:User Guide

2007-12-01T11:12:04Z

Jpsaman: /* See also */ oops wrong place

{{RightMenu|documentation play howto toc}}

'''This document is the complete user guide for the VLC media player.'''

*[[Documentation:Play_HowTo/Introduction to VLC|Introduction]]
**Overview and history of the VideoLAN project.
*[[Documentation:Play_HowTo/Installing VLC|Installation]]
**Installation instructions for a variety of computers.
*[[Documentation:Play_HowTo/Basic Use|Basic Use]]
**How to play audio/video materials with the VLC media player.
*[[Documentation:Play_HowTo/Advanced Use of VLC|Advanced Use]]
**Advanced instruction on streams, filters, plug-ins and more.

==See also==

*[[Documentation:Play_HowTo/Building Pages for the HTTP Interface|Building Pages for the HTTP Interface]]
*[[Documentation:Play_HowTo/Format String|Format String]]
*[[Documentation:Play_HowTo/Building Lua Playlist Scripts|Building Lua Playlist Scripts]]

{{Documentation}}

Copyright © 2002-2007 the VideoLAN project.

Documentation:User Guide

2007-12-01T11:11:13Z

Jpsaman: /* See also */ Add original authors.

{{RightMenu|documentation play howto toc}}

'''This document is the complete user guide for the VLC media player.'''

*[[Documentation:Play_HowTo/Introduction to VLC|Introduction]]
**Overview and history of the VideoLAN project.
*[[Documentation:Play_HowTo/Installing VLC|Installation]]
**Installation instructions for a variety of computers.
*[[Documentation:Play_HowTo/Basic Use|Basic Use]]
**How to play audio/video materials with the VLC media player.
*[[Documentation:Play_HowTo/Advanced Use of VLC|Advanced Use]]
**Advanced instruction on streams, filters, plug-ins and more.

==See also==

Authors:
* Alexis de Lattre
* Johan Bilien
* Anil Daoud
* Clément Stenac
* Jean-Paul Saman

Copyright (c) 2002-2006 the VideoLAN project

{{GPL}}

*[[Documentation:Play_HowTo/Building Pages for the HTTP Interface|Building Pages for the HTTP Interface]]
*[[Documentation:Play_HowTo/Format String|Format String]]
*[[Documentation:Play_HowTo/Building Lua Playlist Scripts|Building Lua Playlist Scripts]]

{{Documentation}}

Copyright © 2002-2007 the VideoLAN project.

Documentation:Advanced Use of VLC

2007-07-27T21:34:49Z

Jpsaman: /* Build HTML pages that use the plugin (VLC version 0.8.6 and above) */ Clarify the new JavaScript API

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

==Building HTML pages for Mozilla/Firefox/Internet Explorere/Safari (VLC version 0.8.6 and above)==

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 is only valid for VLC version 0.8.6 and above.

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ERROR=6)
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[Playlist items object]]

read/write properties
*''none''

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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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 (note: this number isn't the position in the playlist, but the number given by vlc.playlist.add() )

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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

methods
*'''vlc.video.toggleFullscreen()''': toggle the fullscreen mode based on the previous setting

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}

Documentation:Advanced Use of VLC

2007-07-27T21:30:47Z

Jpsaman: /* Use the plugin */ Make more clear that this is mozilla only

{{RightMenu|documentation play howto toc}}

==Use the command line==

'''TODO: completely outdated'''

All standard operations of VLC should be available from the GUI. However, some complex operations can only be done from the command line and there are situations in which you don't need or want a GUI. Here is the complete description of VLC's command line and how to use it.

You need to be quite comfortable with command line usage to use this.

Note: Windows users have to use the ''--option-name="value"'' syntax instead of the ''--option-name value'' syntax.

===Getting help===

VLC uses a modular structure. The core mainly manages communication between modules. All the multimedia processing is done by modules. There are input modules, demultiplexers, decoders, video output modules, ...

This chapter will only describe the "general" options, i.e. the core options. Each module adds new options. For example, the HTTP input module will add options for caching, proxy, authentication, ...

By using '''vlc --help''', you will get the basic core options. '''vlc --longhelp''' will give all the basic options (core + modules). Adding '''--advanced''' will give the "advanced options" (for advanced users). So '''vlc --longhelp --advanced''' will give you all options. You can also append '''--help-verbose''' if you want more detailed help.

Also, you might want to get debug informations. To do this, use '''-v''' or '''-vv''' (this will show lower severity messages). If your console supports it, you can add '''--color to get messages in color.

===Opening streams===

The following commands start VLC and start reading the given element(s)

====Opening a file====

Start VLC with:

% '''vlc my_file'''

VLC should be able to recognize the file type. If it does not, you can force demultiplexer and decoder (see below).

A list of all video and audio codecs supported by VLC is available on the [http://www.videolan.org/vlc/features.html VLC features list].

====Opening a DVD or VCD, or an audio CD====

Start VLC with:

For a DVD with menus:
% '''vlc dvd://[device][@raw_device][@[title][:[chapter][:angle]]]'''

In most cases, '''vlc dvd://''' or '''vlc dvd://[device]''' will do. [device] is for example '''/dev/dvd''' on GNU/Linux or '''D:''' on Windows (complete path to your DVD drive).

or

(DVD without menus):

% '''vlc dvdsimple://[device][@raw_device][@[title][:[chapter][:angle]]]'''

or

(VCD):

% '''vlc vcd://[device][@{E|P|E|T|S}[number]]'''

or

(Audio CD):

% '''vlc cdda://[device][@[track]]'''

====Receiving a network stream====

To receive an unicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:[@:server_port]'''

If you use the default port (1234), '''vlc udp:''' will do. For more information, look at the Streaming Howto.

To receive an multicast UDP stream (sent by VLS or VLC's stream output), start VLC with:

% '''vlc udp:@multicast_address[:server_port]'''

To receive a SSM (source specific multicast) stream, you can use:

% '''vlc udp:server_address@multicast_address[:server_port]'''

This only works on OSs that support SSM (Windows XP and recent Linux kernels).

To receive a HTTP stream, start VLC with:

% '''vlc http://www.example.org/your_file.mpg'''

To receive a RTSP stream, start VLC with:</para>

% '''vlc rtsp://www.example.org/your_stream'''

===Modules selection===

VLC always try to select the most appropriate interface, input and output modules, among the ones available on the system, according to the stream it is given to read. However, you may wish to force the use of a specific module with the following options.

*'''--intf <module>''' allows you to select the interface module.
*'''--extraintf <module>''' allows you to select extra interface modules that will be launched in addition to the main one. This is mainly useful for special ''control'' interfaces, like HTTP, RC (Remote Control), ... (see below)
*'''--aout <module>''' allows you to select the audio output module.
*'''--vout <module>''' allows you to select the video output module.
*'''--memcpy <module>''' allows you to choose a memory copy module. You should probably never touch that.

You can get a listing of the available modules by using '''vlc -l'''

===Stream Output===

The Stream output system allows vlc to become a streaming server.

For more details on the stream output system, please have a look at the [[Documentation:Streaming HowTo|Streaming HowTo]].

===Other Options===

====Audio options====

*'''--noaudio''' disables audio output.
*'''--mono''' forces VLC to treat the stream in mono audio.
*'''--volume <integer>''' sets the level of audio output (between 0 and 1024).
*'''--aout-rate <integer>''' sets the audio output frequency (Hz). By default, VLC will try to autodetect this.
*'''--desync <integer>''' compensates desynchronization of audio (ms). (If audio and video streams are not synchronized, use this setting to delay the audio stream)
*'''--audio-filter <string>''' adds audio filters to the processing chain. Available filters are visual (visualizer with spectrum analyzer and oscilloscope), headphone (virtual headphone patialization) and normalizer (volume normalizer)

====Video options====

*'''--novideo''' disables video output.
*'''--greyscale''' turns video output into grayscale mode.
*'''--fullscreen''' ( or '''-f''') sets fullscreen video.
*'''--nooverlay''' disables hardware acceleration for the video output.
*'''--width, --height <integer>''' sets the video window dimensions. By default, the video window size will be adjusted to match the video dimensions.
*'''--zoom <float>''' adds a zoom factor.
*'''--aspect-ratio <mode>''' forces source aspect ratio. Modes are 4x3, 16x9, ...
*'''--spumargin <integer>''' forces SPU subtitles postion.
*'''--filter <string>''' adds video filters to the processing chain. You can add several filters, separated by commas
*'''--sub-filter <string>''' adds video subpictures filter to the processing chain.

====Playlist options====

*'''--random''' plays files randomly forever.
*'''--loop''' loops playlist on end.
*'''--repeat''' repeats current item until another item is forced
*'''--play-and-stop''' stops the playlist after each played item.

====Network options====

*'''--server-port <integer>''' sets server port.
*'''--iface <string>''' specifies the network interface to use.
*'''--iface-addr <string>''' specifies your network interface IP address.
*'''--mtu <integer>''' specifies the MTU of the network interface.
*'''--ipv6''' forces IPv6.
*'''--ipv4''' forces IPv4.

====CPU options====

You should probably not touch these options unless you know what you are doing.

*'''--nommx''' disables the use of MMX CPU extensions.
*'''--no3dn''' disables the use of 3D Now! CPU extensions.
*'''--nommxext''' disables the use of MMX Ext CPU extensions.
*'''--nosse''' disables the use of SSE CPU extensions.
*'''--noaltivec''' disables the use of Altivec CPU extensions.

====Miscellaneous options====

*'''--quiet''' deactivates all console messages.
*'''--color''' displays color messages.
*'''--search-path <string>''' specifies interface default search path.
*'''--plugin-path <string>''' specifies plugin search path.
*'''--no-plugins-cache''' disables the plugin cache (plugins cache speeds up startup)
*'''--dvd <string>''' specifies the default DVD device.
*'''--vcd <string>''' specifies the default VCD device.
*'''--program <integer>''' specifies program (SID) (for streams with several programs, like satellite ones).
*'''--audio-type <integer>''' specifies the default audio type to use with dvds.
*'''--audio-channel <integer>''' specifies the default audio channel to use with dvds.
*'''--spu-channel <integer>''' specifies the default subtitle channel to use with dvds.
*'''--version''' gives you information about the current VLC version.
*'''--module <module> ''' displays help about specified module. (Shortcut: '''-p''')

===Item-specific options===

There are many options that are related to items (like '''--novideo''', '''--codec''', '''--fullscreen''').

For all of these, you have the possibility to make them item-specific, using ":" instead of "--" and putting the option just after the concerned item.

Examples:

% '''vlc file1.mpg :fullscreen file2.mpg'''
will play file1.mpg in fullscreen mode and file2.mpg in the default mode (which is generally no fullscreen), whereas
% '''vlc --fullscreen file1.mpg file2.mpg'''
will play both files in fullscreen mode

% '''vlc --fullscreen file1.mpg :sub-file=file1.srt :no-fullscreen file2.mpg :filter=distort'''
will play file1.mpg in windowed (no-fullscreen) mode with the subtitles file file1.srt and will play file2.mpg with video filter distort enabled in fullscreen mode (item-specific options override global options)

==Advanced use of filters==

===Filters===

These are the old style VLC filters. They only apply to on screen display and thus cannot be streamed.

====Deinterlacing video filter====

Module name: '''deinterlace'''

*'''--deinterlace-mode {discard,blend,mean,bob,linear}''' choose a deinterlacing mode.

====Invert video filter====

Module name: '''invert'''

====Image properties filter====

Module name: '''adjust'''

*'''--contrast <float>''' Image contrast in the 0-2 range.
*'''--brightness <float>''' Image brightness in the 0-2 range.
*'''--hue <integer>''' Image hue in the 0-360 range.
*'''--saturation <float>''' Image saturation in the 0-3 range.
*'''-gamma <float>''' Image gamma in the 0-10 range.

====Wall video filter====

Module name: '''wall'''

This filter splits the output in several windows.

*'''--wall-cols <integer>''' Number of columns.
*'''--wall-rows <integer>''' Number of rows.
*'''--wall-active <string>''' Select the windows you want to display. To select windows 2 and 4 you would write '''--wall-active 2,4'''. When this option isn't specified, all windows are displayed.

====Video transformation filter====

Module name: '''transform'''

*'''--transform-type {90,180,270,hflip,vflip}''' Select rotation angle or symmetry.

====Distort video filter====

Module name: '''distort'''

====Clone video filter====

This filter clones the output window.

Module name: '''clone'''

*'''--clone-count <integer>''' Number of clones.
*'''--clone-vout-list <string>''' Comma separated string of video output modules.

====Crop video filter====

Module name: '''crop'''

*'''--crop-geometry <string>''' Set the geometry of the zone to crop. This is set as <width> x <height> + <left offset> + <top offset>.
*'''--autocrop''' Enable automatic black border cropping.

====Motion blur filter====

Module name: '''motionblur'''

*'''blur-factor <integer>''' Blur factor in the 1-127 range.

====Video pictures blending====

Module name: '''blend'''

====Video scaling filter====

Module name: '''scale'''

===Subpictures Filters===

These are the new VLC filters. They can be streamed.

====Time display sub filter====

Module name: '''time'''

*'''--time-format <string>''' Time format string. You can use the following special characters %Y = year, %m = month, %d = day, %H = hour, %M = minute, %S = second.
*'''--time-x <integer>''' X offset from the left in pixels.
*'''--time-y <integer>''' Y offset from the top in pixels.

====Marquee display sub filter====

Module name: '''marq'''

*'''--marq-marquee <string>''' Marquee text to display.
*'''--marq-x <integer>''' X offset from the left in pixels.
*'''--marq-y <integer>''' Y offset from the top in pixels.
*'''--marq-timeout <timeout>''' Defines the time the marquee must remain displayed in milliseconds. Default value is 0 (remain forever).

====Logo video filter====

Module name: '''logo'''

This filter can be used both as an old style filter or a subpictures filter.

*'''--logo-file <string>''' Full path of the PNG file to use.
*'''--logo-x <integer>''' X offset from the left in pixels.
*'''--logo-y <integer>''' Y offset from the top in pixels.
*'''--logo-transparency <integer>''' You can set the logo transparency value here (from 0 for full transparency to 255 for full opacity).

Note: You can move the logo by left-clicking on it.

==The HTTP interface==

VLC ships with a little HTTP server integrated. It is used both to stream using HTTP, and for the HTTP remote control interface.

To start VLC with the HTTP interface, use:
% '''vlc -I http [--http-src /directory/] [--http-host host:port]'''

If you want to have both the "normal" interface and the HTTP interface, use '''vlc --extraintf http'''.

The HTTP interface will start listening at host:port (<all interfaces>:8080 if omitted), and will reproduce the structure of /directory at http://host:port/ ( vlc_source_path/share/http if omitted ).

Use a browser to go to http://your_host_machine:port. You should be taken to the main page.

VLC is shipped with a set of files that should be enough for generic needs. It is also possible to customize pages. See [[Documentation:Play_HowTo/Building_Pages_for_the_HTTP_Interface]].

Available pages are:
* '''list was obsolete'''

==Other control interfaces==

VLC includes a number of so-called interfaces that are not really interfaces, but means of controlling VLC. Nevertheless, they are enabled by setting them as interface or extra interface, either in the Preferences, in General/Interface, or using '''-I''' or '''--extraintf''' on the command line.

===Hotkeys===

This module allows you to control VLC and playback via hotkeys. It is always enabled by default. You can use hotkeys in the video output window.

Hotkeys can be hacked by:
% '''vlc --key-<function> <code>'''

Code is composed by modifiers keys (Alt, Shift, Ctrl, Meta,Command) separated by a dash (-) and terminated by a key (a...z, +, =, -, ',', +, <, >, `, /, ;, ', \, [, ], *, Left, Right, Up, Down, Space, Enter, F1...F12, Home, End, Menu, Esc, Page Up, Page Down, Tab, Backspace, Mouse Wheel Up and Mouse Wheel Down). Main controls are available from hotkeys, such as : fullscreen, play-pause, faster, slower, next, prev, stop, quit, vol-up, etc. (use the '''--longhelp''' option for full list of functions).
For example, for binding fullscreen to Ctrl-f, run:
% '''vlc --key-fullscreen 'Ctrl-f' '''

===RC and RTCI===

These two interfaces allow you to control VLC from a command shell (possibly using a remote connexion or a Unix socket).

Start VLC with '''-I rc''' or '''--extraintf rc'''. When you get the '''Remote control interface initialized, `h' for help''' message, press h and Enter to get help about available commands.

To be able to remote connect to your VLC using a TCP socket (telnet-like connexion), use '''--rc-host your_host:port'''. Then, by connecting (using telnet or netcat) to the host on the given port, you will get the command shell.

To use a UNIX socket (local socket, this does not work for Windows), use '''--rc-unix /path/to/socket'''. Commands can then be passed using this UNIX socket.

The RTCI interface gives you more advanced options, such as marquee control for the marquee subpicture filter (See filter section).

===Ncurses===

This is a text interface, using ncurses library.

Start VLC with '''-I ncurses''' or '''--extraintf ncurses'''. You will then get something like that:

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-playlist.jpg The ncurses interface

Press h to get the list of all available commands, with a short description.

There is also a filebrowser available for the ncurses interface in order to add playlist items. Press 'B' to use it.

http://www.videolan.org/doc/play-howto/en/images/play-howto/intf-ncurses-filebrowser.jpg The ncurses filebrowser

You can set the filebrowser starting point by launching vlc with the '''--browse-dir''' option:

% '''vlc -I ncurses --browse-dir /filebrowser/starting/point/'''

===Gestures===

Gestures provide a simple mouse gestures control. TODO

==The Mozilla plugin==

VLC can also be embedded in a web browser! The following browsers are supported [http://www.mozilla.org/ Mozilla], [http://www.mozilla.org/products/firefox/ Firefox] and [http://www.apple.com/macosx/features/safari Safari].

===Install the plugin===

====GNU/Linux Debian====

Install the ''mozilla-plugin-vlc'' package:

# '''apt-get update'''
# '''apt-get install mozilla-plugin-vlc'''

====Windows====

Quit Firefox or Mozilla.

Copy the two files in '''VLC_Installation_folder\mozilla''' (usually '''C:\Program Files\VideoLAN\VLC\mozilla''') to your mozilla plugins directory (Usually '''C:\Program Files\Mozilla\plugins''' or '''C:\Program Files\Mozilla
Firefox\plugins''').

Restart Firefox or Mozilla.

====MacOS X====

''The Mozilla/Safari plugin for MacOS X is only available from vlc version 0.8.5.1 and onwards.''

Quit Safari browser.

Download the Mozilla/safari plugin package from [http://www.videolan.org/vlc/download-macosx.html MacOS X download page].

Run the installer from the dmg image.

====Compile the sources yourself====

Please look at the [http://developers.videolan.org developers page] for information on how to do this.

===Use the mozilla plugin===

If you open a link to a video file handled by the VLC plugin (To get the list of handled types, browse to '''about:plugins''') or a page with an embedded video, the plugin should open and read the
video.

===Build HTML pages that use the plugin (VLC version up to 0.8.5)===

'''WARNING:''' the APIs described in this section are '''deprecated''', do not use,

The following API description is only valid uptill version 0.8.5 of the mozilla plugin.

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 supports the following function calls:
*'''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.

Here are a few examples of HTML pages that use the
Mozilla plugin.

====Example 1====

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.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 1</h1>

<embed type="application/x-vlc-plugin"
name="video1"
autoplay="no" loop="yes" width="400" height="300"
target="http://server.example.org/video1.vob" />
<br />
<a href="javascript:;" onclick='document.video1.play()'>Play video1</a>
<a href="javascript:;" onclick='document.video1.pause()'>Pause video1</a>
<a href="javascript:;" onclick='document.video1.stop()'>Stop video1</a>
<a href="javascript:;" onclick='document.video1.fullscreen()'>Fullscreen</a>

</body>
</html>

====Example 2====

In this example, the plugin will read a multicast UDP stream in a dedicated video output window.

<html>
<head><title>Demo of VLC mozilla plugin</title></head>

<body>

<h1>Demo of VLC mozilla plugin - Example 2</h1>

<embed type="application/x-vlc-plugin"
name="video2"
autoplay="no" loop="no" hidden="yes"
target="udp:@239.255.12.42" />
<br />
<a href="javascript:;" onclick='document.video2.play()'>Play video2</a>
<a href="javascript:;" onclick='document.video2.stop()'>Stop video2</a>
<a href="javascript:;" onclick='document.video2.fullscreen()'>Fullscreen</a>

</body>
</html>

===Build HTML pages that use the plugin (VLC version 0.8.6 and above)===

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:

*'''audio''': Access audio properties.
*'''input''': Access input properties.
*'''playlist''': Access playlist properties.
*'''video''': Access video properties.
*'''log''': Access log properties.
*'''messages''': Access to log message properties.
*'''iterator''': Access to log iterator properties.

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.

<html>
<title>VLC Mozilla plugin test page</title>
<body>
<embed type="application/x-vlc-plugin" pluginspage="http://www.videolan.org" version="VideoLAN.VLCPlugin.2"
width="640"
height="480"
id="vlc">
</embed>
<script language="Javascript">

</script>
</body>
</html>

====Root object====

readonly properties
*'''VersionInfo''': returns version information string

read/write properties
*''none''

methods
*'''vlc.versionInfo()''': returns version information string (same as VersionInfo)

====Audio object====

readonly properties
*''none''

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

Audio Channel:
<SELECT readonly 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 language="javascript">


methods
*'''vlc.audio.toggleMute()''': boolean toggle that mutes and unmutes the audio based upon the previous state

====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
*'''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

vlc.input.time = <absolute seek>

vlc.input.time = vlc.input.time + <relative seek>
*'''vlc.input.state''': current state of the input chain given as enumeration (IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ERROR=6)
*'''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.)

methods
*''none''

====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.items''': return the playlist items collection, see [[Playlist items object]]

read/write properties
*''none''

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.play()''': start playing the current playlist item
*'''vlc.playlist.playItem(number)''': start playing the item whose identifier is number
*'''vlc.playlist.togglePause()''': toggle the pause state for the current playlist item
*'''vlc.playlist.stop()''': stop playing the current playlist item
*'''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 (note: this number isn't the position in the playlist, but the number given by vlc.playlist.add() )

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

====Video object====

readonly properties
*'''vlc.video.width''': returns the horizontal size of the video
*'''vlc.video.height''': returns the vertical size of the video

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

methods
*'''vlc.video.toggleFullscreen()''': toggle the fullscreen mode based on the previous setting

====Log object====

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.

readonly properties
*'''vlc.log.messages''': returns the message collection, see [[Messages object]]

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''

====Messages object====

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

====Messages Iterator object====

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]]

====Message object====

*'''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

{{Documentation}}