Caprica Software

vlcj 3.x Tutorial


Building on previous tutorials, we will now show you how to play YouTube video.

This tutorial is covering YouTube, but the mechanism described here is actually common to many streaming services, e.g. internet radio stations likely work in the same way.

Background Information

VLC can play YouTube videos just fine, so that means a vlcj media player can too.

However there is a little bit more to consider...

The way it works in VLC is that you 'play' a YouTube 'watch' URL, like this:

This is not a direct streaming URL that can just start playing, it is a URL to a web-page on the YouTube web-site. The actual streaming URL is contained somewhere inside the HTML mark-up on that web-page.

This URL becomes the current media, and when played VLC recognises that you are trying to play a YouTube URL so it launches a LUA script (included with VLC) that loads the web-page at the URL and 'scrapes' it to find the streaming URL.

When the streaming URL is found, it does not actually start playing. Instead, VLC creates a 'sub-item' which it attaches to the current media. If you want to play the stream you must explicitly play this sub-item.

This 'screen-scraping' of the YouTube web page is brittle - if YouTube change the structure of their web-pages then VLC will sometimes fail to find the streaming URL, when this happens you have to wait for a developer to provide a new LUA script and wait for a new version of VLC to be released.

Let's Get Started

You should now already have a basic template for how to create a vlcj application, so this tutorial will no longer duplicate all of the code each time - instead we'll just show the new code fragments.

The Easy Way

For the vast majority of applications, the easiest way to play YouTube media using vlcj is to configure the media player to automatically play sub-items.

If you configure the media player this way, when you play a URL if the media player detects sub-items have been created it will automatically play the first such sub-item. Usually this is exactly what you want to happen.


It really is as simple as that.

If you are using media player event handlers you need to be aware that when sub-items are involved you will receive more events - for example you will receive a playing event and a finished (or error) event when you play the watch URL, and you will receive a further playing event when the sub-item is played and the video starts streaming. When the stream ends you will receive a further finished event.

The Other Way

Auotmatically playing sub-items is the recommended way - but if having the media player automatically play sub-items does not work for you, vlcj provides an API where you can work with the sub-items directly.

You can query the number of sub-items, get the MRLs for each sub-item and choose a particular sub-item to play. You can event get meta data for each sub-item.

If you want to do it this way, you must use slightly more complex media player event handlers.

In particular you may need to implement mediaSubItemAdded and/or mediaSubItemTreeAdded to track when sub-items get created. You also need to track finished and error events - when you receive finished it means that the YouTube page has been parsed and the sub-item for the streaming URL has been created and is ready to be played.

Basically you end up implementing the in-built automatic sub-item handling yourself, but in a slightly more flexible way - the automatic handling will aways play the first sub-item, if you do it yourself you could present a list of sub-items to your user and they could then pick the one they wanted.

Please consult the Javadoc for more information on sub-item handling.