Getting started

Concepts

VLC is a popular, multiplatform, open-source media player that can read a wide range of media. It comes with a bunch of plugins that allows it to perform many tasks beyond just playing a video.

VLC is an executable file, but all its features are available to application developers thanks to libvlc, a C library.

The goal of this project is to provide a .Net abstraction over libvlc, allowing you to embed (lib)VLC features into your WinForms or WPF applications. In most cases, you want to embed a media player in your app, so that you can play your last summer holidays movie or play a RTSP stream from you network security camera.

Note: Now that you are familiar with those concepts, it is important to remember that when you have any issue when using this library, for example a decoding failure, it is probably not Vlc.DotNet's fault. Before posting any issue on this repository, please check with VLC before, and try upgrading the libvlc you are using.

OK, but how do I create my app?

You will need 2 things:

• The libvlc library, that you will redistribute with your application
• A Vlc.DotNet NuGet package and its dependencies :
  • Vlc.DotNet.Forms : Contains a control to display a media player in a WinForm application. See Vlc.DotNet.Forms.VlcControl
  • Vlc.DotNet.Wpf : Same, but for WPF. For now, the WPF control is using the WinForm control under the hood. See Vlc.DotNet.Wpf.VlcControl
  • Vlc.DotNet.Core : Base dependency, for lower level interactions, such as file conversions, streaming... that doesn't require any control.

Getting libvlc

With NuGet :

Official NuGet packages - See Documentation here

Manually :

You can find all the versions available on The official FTP. Pick a version, win32 or win64 depending on your target (or both!), and download the .zip file or the .7z .

At time of writing (2017-08-08), this library works with 2.1.x versions all the way through 3.0.0 nightly builds.

Tip : you should check your download with a tool like HashMyFile to be sure that your download has not been corrupted.

extract the archive and put these files into a folder (example: libvlc/win-x64) that will be accessible from your application:

• libvlc.dll
• libvlccore.dll
• The plugins folder (you can remove the plugins that you are not using from that folder)

Whichever method you choose, you will need to redistribute that libvlc/win-x64 folder with your application.

Be careful: You will also need to comply to VLC's licence. If I understand it correctly, it means that you must redistribute VLC's source code with your application (only my own interpretation, please refer to someone with more legal knowledge here)

Installing Vlc.DotNet

Create a new project targetting the .net framework. Just install the NuGet package you picked above. The dependencies will automatically be pulled.

Coding with...

Samples projects can be found in the repository!

Vlc.DotNet.Core

If you need to stream a video on the network, or anything more advanced than just displaying a media player in a WinForm or a WPF window, you should use this one.

Here is a console application that downloads a file using a media player (you could also transcode, but that's not the point here).

using System;
using System.IO;
using System.Threading;

namespace ConsoleApp1
{
    class Program
    {
        static void Main(string[] args)
        {
            var libDirectory = new DirectoryInfo(Path.Combine(currentDirectory, "libvlc", IntPtr.Size == 4 ? "win-x86" : "win-x64"));

            var options = new string[]
            {
                // VLC options can be given here. Please refer to the VLC command line documentation.
            };

            var mediaPlayer = new Vlc.DotNet.Core.VlcMediaPlayer(libDirectory);

            var mediaOptions = new string[]
            {
                ":sout=#file{dst="+Path.Combine(Environment.CurrentDirectory, "output.mov")+"}",
                ":sout-keep"
            };

            mediaPlayer.SetMedia(new Uri("http://download.blender.org/peach/bigbuckbunny_movies/big_buck_bunny_480p_h264.mov"), mediaOptions);

            bool playFinished = false;
            mediaPlayer.PositionChanged += (sender, e) =>
            {
                Console.Write("\r" + Math.Floor(e.NewPosition * 100) + "%");
            };

            mediaPlayer.EncounteredError += (sender, e) =>
            {
                Console.Error.Write("An error occurred");
                playFinished = true;
            };

            mediaPlayer.EndReached += (sender, e) => {
                playFinished = true;
            };

            mediaPlayer.Play();

            // Ugly, sorry, that's just an example...
            while(!playFinished)
            {
                Thread.Sleep(TimeSpan.FromMilliseconds(500));
            }
        }
    }
}

Vlc.DotNet.Forms

If you are creating a WinForms app that is displaying a video stream, you should use that.

You have two options when using the WinForms control : Option 1 : Put the control on the form with the designer. For that, right click on an empty space on the toolbox and click choose item .

You can define your media player's options in the designer properties. Handle the VlcLibDirectoryNeeded needed event to choose the directory where to find the library.

Option 2 : After InitializeComponent, you can create your component programmatically, and add it to your form.

this.vlcControl = new Vlc.DotNet.Forms.VlcControl();
this.vlcControl.BeginInit();
this.vlcControl.VlcLibDirectory = /*libvlc's directory*/;
this.vlcControl.VlcMediaplayerOptions = new[] { "-vv" };
this.vlcControl.EndInit();
this.Controls.Add(this.vlcControl);

Vlc.DotNet.Wpf

This package was completely rewritten in 3.0 due to persistent user demand. You should probably not be using it unless you know what you're doing : Hardware accelerated rendering will not be enabled, and a lot of copies will occur, raising the CPU usage.

This is slow, but might be good enough for your use case, for example if you really need a WPF-friendly image.

If you need maximum performances, you can wrap Vlc.DotNet.WinForms in a WindowsFormsHost and use it like that. See this sample for how to use the WinForms control. Be aware that you will experience Airspace issues (see #296) if you need to write over the video.

Now that you are aware of that, here is how you'd use the WPF's VlcControl.

Add the VlcControl in your UserControl/View and give it a name:

<Vlc:VlcControl xmlns:Vlc="clr-namespace:Vlc.DotNet.Wpf;assembly=Vlc.DotNet.Wpf" x:Name="MyControl" />

In your view constructor, after the call to InitializeComponent() :

            var vlcLibDirectory = new DirectoryInfo(Path.Combine(currentDirectory, "libvlc", IntPtr.Size == 4 ? "win-x86" : "win-x64"));

            var options = new string[]
            {
                // VLC options can be given here. Please refer to the VLC command line documentation.
            };

            this.MyControl.SourceProvider.CreatePlayer(vlcLibDirectory, options);

            // Load libvlc libraries and initializes stuff. It is important that the options (if you want to pass any) and lib directory are given before calling this method.
            this.MyControl.SourceProvider.MediaPlayer.Play("http://download.blender.org/peach/bigbuckbunny_movies/big_buck_bunny_480p_h264.mov");

How to debug?

If you have a problem and pulling your hair simply add this as arguments when creating Vlc instance, to enable Vlc log.

 "--file-logging", "-vvv", "--logfile=Logs.log"