README.md 9.9 KB
Newer Older
Martin Finkel's avatar
Martin Finkel committed
1 2 3 4
<h3 align="center">
    <img src="Assets/banner.png"/>
</h3>

Martin Finkel's avatar
Martin Finkel committed
5 6
# LibVLCSharp

7
[![Build Status](https://videolan.visualstudio.com/LibVLCSharp/_apis/build/status/LibVLCSharp-GitLab?branchName=master)](https://videolan.visualstudio.com/LibVLCSharp/_build/latest?definitionId=10?branchName=master)
Martin Finkel's avatar
Martin Finkel committed
8 9
[![Join the chat at https://gitter.im/libvlcsharp/Lobby](https://badges.gitter.im/libvlcsharp/Lobby.svg)](https://gitter.im/libvlcsharp/Lobby)

Martin Finkel's avatar
Martin Finkel committed
10 11
LibVLCSharp is a cross-platform audio and video API for .NET platforms based on VideoLAN's LibVLC Library.
It provides a comprehensive multimedia API that can be used across mobile, server and desktop to render video and output audio as well as encode and stream.
Martin Finkel's avatar
Martin Finkel committed
12

13
_The official repository URL for this repo is https://code.videolan.org/videolan/LibVLCSharp._
Martin Finkel's avatar
Martin Finkel committed
14

Martin Finkel's avatar
Martin Finkel committed
15
- [Features](#features)
16
- [Supported platforms](#supported-platforms)
Martin Finkel's avatar
Martin Finkel committed
17 18
- [Installation](#installation)
- [Getting started](#getting-started)
19
- [Samples](#samples)
Martin Finkel's avatar
Martin Finkel committed
20 21
- [Quick API overview](#quick-api-overview)
- [Roadmap](#roadmap)
Martin Finkel's avatar
Martin Finkel committed
22
- [Versioning](VERSIONING.md)
Martin Finkel's avatar
Martin Finkel committed
23 24
- [Contribute](#contribute)
- [Communication](#communication)
25
  - [Forum](#forum)
26
  - [GitLab Issues](#issues)
27
  - [IRC](#irc)
28
  - [StackOverflow](#stackoverflow)
Martin Finkel's avatar
Martin Finkel committed
29 30 31
- [Code of Conduct](#code-of-conduct)
- [License](#license)

Martin Finkel's avatar
Martin Finkel committed
32
## Features
Martin Finkel's avatar
Martin Finkel committed
33

Martin Finkel's avatar
Martin Finkel committed
34
Check out [libvlc-nuget](https://code.videolan.org/videolan/libvlc-nuget) to get a basic understanding of how `libvlc` works, what it can offer and how to install it with NuGet. 
Martin Finkel's avatar
Martin Finkel committed
35

Martin Finkel's avatar
Martin Finkel committed
36
Some of the [features](https://www.videolan.org/vlc/features.html) include:
Martin Finkel's avatar
Martin Finkel committed
37

Martin Finkel's avatar
Martin Finkel committed
38
- Network browsing for distant filesystems (SMB, FTP, SFTP, NFS...).
Martin Finkel's avatar
Martin Finkel committed
39
- HDMI pass-through for Audio HD codecs, like E-AC3, TrueHD or DTS-HD.
Martin Finkel's avatar
Martin Finkel committed
40 41 42 43 44 45
- Stream to distant renderers, like Chromecast.
- 360 video and 3D audio playback with viewpoint change.
- Support for Ambisonics audio and more than 8 audio channels.
- Subtitles size modification live.
- Hardware decoding and display on all platforms.
- DVD playback and menu navigation.
Martin Finkel's avatar
Martin Finkel committed
46
- Equalizer support.
Martin Finkel's avatar
Martin Finkel committed
47

Martin Finkel's avatar
Martin Finkel committed
48
Most things you can achieve with the regular VLC desktop app, you can also achieve using `libvlc`.
Martin Finkel's avatar
Martin Finkel committed
49

50 51
## Supported platforms

Martin Finkel's avatar
Martin Finkel committed
52 53
Mono, .NET Framework and .NET Core runtimes are supported.

Martin Finkel's avatar
Martin Finkel committed
54 55
- Xamarin.Android
- Xamarin.iOS
56
- Xamarin.tvOS
57
- Xamarin.Mac (Cocoa)
58
- Windows (WPF, WinForms, GTK)
59
- Linux (GTK)
Martin Finkel's avatar
Martin Finkel committed
60
- Xamarin.Forms
Martin Finkel's avatar
Martin Finkel committed
61
- .NET Standard 1.1
62
- .NET Core (including ASP.NET Core)
Martin Finkel's avatar
Martin Finkel committed
63

Martin Finkel's avatar
Martin Finkel committed
64
## Installation
Martin Finkel's avatar
Martin Finkel committed
65

66
1. Install LibVLC in your platform specific project.
Martin Finkel's avatar
Martin Finkel committed
67

68 69 70 71 72
```cmd
dotnet add package VideoLAN.LibVLC.[Windows|Android|iOS|Mac|tvOS]
```

LibVLC is the actual VLC engine written mostly in C/C++ and compiled for your target platform. More information [here](https://code.videolan.org/videolan/libvlc-nuget).
Martin Finkel's avatar
Martin Finkel committed
73

74 75 76
2. Install LibVLCSharp _or_ LibVLCSharp.Forms (if you plan on using Xamarin.Forms)

LibVLCSharp is the .NET wrapper that consumes `LibVLC` and allows you to interact with native code from C#/F#.
Martin Finkel's avatar
Martin Finkel committed
77 78

```cmd
Martin Finkel's avatar
Martin Finkel committed
79
dotnet add package LibVLCSharp
Martin Finkel's avatar
Martin Finkel committed
80 81
```

Martin Finkel's avatar
Martin Finkel committed
82 83
[![NuGet Stats](https://img.shields.io/nuget/v/LibVLCSharp.svg)](https://www.nuget.org/packages/LibVLCSharp)
[![NuGet Stats](https://img.shields.io/nuget/dt/LibVLCSharp.svg)](https://www.nuget.org/packages/LibVLCSharp)
Martin Finkel's avatar
Martin Finkel committed
84 85 86 87

If you plan to use LibVLCSharp with Xamarin.Forms, you need to install LibVLCSharp.Forms instead (which references LibVLCSharp).

```cmd
Martin Finkel's avatar
Martin Finkel committed
88
dotnet add package LibVLCSharp.Forms
Martin Finkel's avatar
Martin Finkel committed
89 90
```

Martin Finkel's avatar
Martin Finkel committed
91 92
[![NuGet Stats](https://img.shields.io/nuget/v/LibVLCSharp.Forms.svg)](https://www.nuget.org/packages/LibVLCSharp.Forms)
[![NuGet Stats](https://img.shields.io/nuget/dt/LibVLCSharp.Forms.svg)](https://www.nuget.org/packages/LibVLCSharp.Forms)
Martin Finkel's avatar
Martin Finkel committed
93

94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
The LibVLCSharp package contains platform specific View integrations (i.e. `VideoView`) for Android, iOS, Mac and tvOS.

3. A few additional GUI toolkits have been integrated to LibVLCSharp. Those _optional_ packages aim to make the process of using LibVLC in your app as easy and fast as possible by providing a LibVLCSharp `VideoView`.

For __WPF__ on Windows with or without Xamarin.Forms
[![NuGet Stats](https://img.shields.io/nuget/v/LibVLCSharp.WPF.svg)](https://www.nuget.org/packages/LibVLCSharp.WPF)

```cmd
dotnet add package LibVLCSharp.WPF
```

or

```cmd
dotnet add package LibVLCSharp.Forms.WPF
```

For __WinForms__ on Windows [![NuGet Stats](https://img.shields.io/nuget/v/LibVLCSharp.WinForms.svg)](https://www.nuget.org/packages/LibVLCSharp.WinForms)

```cmd
dotnet add package LibVLCSharp.WinForms
```

If you're using __GTK__ (with or without Xamarin.Forms support) on Linux and/or Windows [![NuGet Stats](https://img.shields.io/nuget/v/LibVLCSharp.GTK.svg)](https://www.nuget.org/packages/LibVLCSharp.GTK)

```cmd
dotnet add package LibVLCSharp.GTK
```

Martin Finkel's avatar
Martin Finkel committed
123 124
## Getting started

Martin Finkel's avatar
Martin Finkel committed
125
Feel free to check out the simple sample projects for [iOS](https://github.com/videolan/libvlcsharp/tree/master/Samples/LibVLCSharp.iOS.Sample) and [Android](https://github.com/videolan/libvlcsharp/tree/master/Samples/LibVLCSharp.Android.Sample) to get started.
Martin Finkel's avatar
Martin Finkel committed
126

Martin Finkel's avatar
Martin Finkel committed
127 128 129
- You need to instantiate a `VideoView` and add it to your main View. 
- You may need to call `Core.Initialize()` to load the `libvlc` native libraries, depending on your host platform. 
- The `VideoView` offers a `MediaPlayer` object (with data-binding support) which allows you to control playback with APIs such as `Play`, `Pause`, set a new media or listen for `libvlc` events.
Martin Finkel's avatar
Martin Finkel committed
130 131 132

For usage of the API, you should check out the `libvlc` [C API documentation](https://www.videolan.org/developers/vlc/doc/doxygen/html/group__libvlc.html) which this wrapper follows closely.

Martin Finkel's avatar
Martin Finkel committed
133
Regarding LibVLCSharp.Forms, check out the sample for [Forms](https://github.com/videolan/libvlcsharp/tree/master/Samples/Forms) to get started.
Martin Finkel's avatar
Martin Finkel committed
134 135
Notably, make sure to call `LibVLCSharpFormsRenderer.Init()` in your platform specific project [*before*](https://forums.xamarin.com/discussion/comment/57605/#Comment_57605) `Xamarin.Forms.Forms.Init` is called.

136 137 138 139
## Samples

For more advanced samples, have a look at [libvlcsharp-samples](https://code.videolan.org/mfkl/libvlcsharp-samples). It currently includes:

Martin Finkel's avatar
Martin Finkel committed
140 141
- [Chromecast sample](https://code.videolan.org/mfkl/libvlcsharp-samples/tree/master/Chromecast): Discover chromecasts on your local network and select one for playback in 100% shared code (Xamarin.Forms, iOS/Android).
- [Record HLS sample](https://code.videolan.org/mfkl/libvlcsharp-samples/tree/master/RecordHLS): Simple .NET Core CLI app which shows how to record an HLS stream to the filesystem.
142
- [RTSP Mosaic](https://code.videolan.org/mfkl/libvlcsharp-samples/tree/master/VideoMosaic): Cross-platform RTSP player sample with 4 views mosaic (Xamarin.Forms, iOS/Android).
143
- [PulseMusic UX](https://code.videolan.org/mfkl/libvlcsharp-samples/tree/master/PulseMusic): A stylish music player UX example using Skia on iOS and Android.
144
- [Gestures sample](https://code.videolan.org/mfkl/libvlcsharp-samples/tree/master/Gestures/Gestures): Cross-platform touch gestures and 360 videos on iOS and Android.
145 146 147

Feel free to suggest and contribute new samples.

Martin Finkel's avatar
Martin Finkel committed
148
## Quick API overview
Martin Finkel's avatar
Martin Finkel committed
149

Martin Finkel's avatar
Martin Finkel committed
150 151
- [`LibVLC.cs`](https://github.com/videolan/libvlcsharp/blob/master/LibVLCSharp/Shared/LibVLC.cs): Main object pointing to a native `libvlc` instance in native code.
- [`MediaPlayer.cs`](https://github.com/videolan/libvlcsharp/blob/master/LibVLCSharp/Shared/MediaPlayer.cs): Manages playback, offers event listeners and more. Accessible from `VideoView` with data-binding support.
Martin Finkel's avatar
Martin Finkel committed
152 153
- [`Media.cs`](https://github.com/videolan/libvlcsharp/blob/master/LibVLCSharp/Shared/Media.cs): Class representing and providing information about a media such as a video or audio file or stream.
- `VideoView.cs`: Custom native view which holds a `MediaPlayer` object.
154 155 156
- [`MediaDiscoverer.cs`](https://github.com/videolan/libvlcsharp/blob/master/LibVLCSharp/Shared/MediaDiscoverer.cs): This object should be used to find media on NAS and any SMB/UPnP-enabled device on your local network.
- [`RendererDiscoverer.cs`](https://github.com/videolan/libvlcsharp/blob/master/LibVLCSharp/Shared/RendererDiscoverer.cs): Use this to find and use a Chromecast or other distant renderers.
- [`Dialog.cs`](https://github.com/videolan/libvlcsharp/blob/master/LibVLCSharp/Shared/Dialog.cs): Dialogs can be raised from the `libvlc` engine in some cases. Register callbacks with this object.
Martin Finkel's avatar
Martin Finkel committed
157

Martin Finkel's avatar
Martin Finkel committed
158
## Roadmap
159

Martin Finkel's avatar
Martin Finkel committed
160
- Game engines (Unity, Unreal, Godot)
161
- UWP
Martin Finkel's avatar
Martin Finkel committed
162

163 164
If you have a request or question regarding the roadmap, feel free to open an [issue](https://code.videolan.org/videolan/LibVLCSharp/issues) or [PR](https://github.com/videolan/libvlcsharp/pulls).

Martin Finkel's avatar
Martin Finkel committed
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196
## Contribute

### Pull request

Pull requests are more than welcome! If you do submit one, please make sure to use a descriptive title and description.

### Gitlab issues

You can look through issues we currently have on the [VideoLAN Gitlab](https://code.videolan.org/videolan/LibVLCSharp).

## Communication

### Forum

If you have any question or if you're not sure it's actually an issue, please visit our [forum](https://forum.videolan.org/).

### Issues

You have encountered an issue and wish to report it to the VLC dev team?

You can create one on our [Gitlab](https://code.videolan.org/videolan/LibVLCSharp/issues) or on our [bug tracker](https://trac.videolan.org/vlc/).

Before creating an issue or ticket, please double check for duplicates!

### IRC

Want to quickly get in touch with us for a question, or even just to talk?

You will always find someone from the VLC team on IRC, __#videolan__ channel on the freenode network.

If you don't have an IRC client, you can always use the [freenode webchat](https://webchat.freenode.net/).

Martin Finkel's avatar
Martin Finkel committed
197 198
We are also on Gitter [![Join the chat at https://gitter.im/libvlcsharp/Lobby](https://badges.gitter.im/libvlcsharp/Lobby.svg)](https://gitter.im/libvlcsharp/Lobby)

199 200 201 202
### StackOverflow

We regularly monitor the `libvlcsharp` tag on [![stackoverflow](https://img.shields.io/stackexchange/stackoverflow/t/libvlcsharp.svg?label=stackoverflow&style=flat)](https://stackoverflow.com/questions/tagged/libvlcsharp)

Martin Finkel's avatar
Martin Finkel committed
203 204 205 206 207 208 209
## Code of Conduct

Please read and follow the [VideoLAN CoC](https://wiki.videolan.org/Code_of_Conduct/) license.

## License

LibVLCSharp is under the LGPLv2.1.