README.md 12.8 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/videolan.libvlcsharp?branchName=master)](https://videolan.visualstudio.com/LibVLCSharp/_build/latest?definitionId=22&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

Jérémy VIGNELLES's avatar
Jérémy VIGNELLES committed
15 16 17 18 19 20 21 22
- [LibVLCSharp](#libvlcsharp)
  - [Features](#features)
  - [Supported platforms](#supported-platforms)
  - [Installation](#installation)
  - [Getting started](#getting-started)
  - [Samples](#samples)
  - [Quick API overview](#quick-api-overview)
  - [Roadmap](#roadmap)
23
  - [Versioning](#versioning)
24
  - [Release Notes](#release-notes)
Jérémy VIGNELLES's avatar
Jérémy VIGNELLES committed
25 26 27 28 29 30 31 32 33 34
  - [Contribute](#contribute)
    - [Pull request](#pull-request)
    - [Gitlab issues](#gitlab-issues)
  - [Communication](#communication)
    - [Forum](#forum)
    - [Issues](#issues)
    - [IRC](#irc)
    - [StackOverflow](#stackoverflow)
  - [Code of Conduct](#code-of-conduct)
  - [License](#license)
Martin Finkel's avatar
Martin Finkel committed
35

Martin Finkel's avatar
Martin Finkel committed
36
## Features
Martin Finkel's avatar
Martin Finkel committed
37

Martin Finkel's avatar
Martin Finkel committed
38
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
39

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

42
- Plays all [formats](https://en.wikipedia.org/wiki/VLC_media_player#Format_support)
Martin Finkel's avatar
Martin Finkel committed
43
- Network browsing for distant filesystems (SMB, FTP, SFTP, NFS...).
Martin Finkel's avatar
Martin Finkel committed
44
- HDMI pass-through for Audio HD codecs, like E-AC3, TrueHD or DTS-HD.
Martin Finkel's avatar
Martin Finkel committed
45 46 47 48
- 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.
49
- Hardware and software decoding on all platforms.
Martin Finkel's avatar
Martin Finkel committed
50
- DVD playback and menu navigation.
Martin Finkel's avatar
Martin Finkel committed
51
- Equalizer support.
Martin Finkel's avatar
Martin Finkel committed
52

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

55 56
## Supported platforms

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

Martin Finkel's avatar
Martin Finkel committed
59 60
- Xamarin.Android
- Xamarin.iOS
61
- Xamarin.tvOS
62
- Xamarin.Mac (Cocoa)
63 64
- Windows Classic (WPF, WinForms, GTK)
- Windows Universal (UWP for Desktop, mobile and Xbox)
65
- Linux (GTK)
Martin Finkel's avatar
Martin Finkel committed
66
- Xamarin.Forms
67
- .NET Standard 1.1 and 2.0
68
- .NET Core (including ASP.NET Core)
Martin Finkel's avatar
Martin Finkel committed
69

Martin Finkel's avatar
Martin Finkel committed
70
## Installation
Martin Finkel's avatar
Martin Finkel committed
71

Jérémy VIGNELLES's avatar
Jérémy VIGNELLES committed
72 73
1. Install **LibVLC** in your platform specific project.

74 75 76
| Platform          | LibVLC Package                      | NuGet                                  | Minimum OS Version |
| ----------------- | ----------------------------------- | -------------------------------------- |--------------------|
| Windows           | VideoLAN.LibVLC.Windows             | [![LibVLCWindowsBadge]][LibVLCWindows] | Windows XP         |
77
| UWP               | VideoLAN.LibVLC.UWP                 | [![LibVLCWin10Badge]][LibVLCWin10]     | Windows 10         |
78 79 80 81 82
| Mac               | VideoLAN.LibVLC.Mac                 | [![LibVLCMacBadge]][LibVLCMac]         | macOS 10.7         |
| Android           | VideoLAN.LibVLC.Android             | [![LibVLCAndroidBadge]][LibVLCAndroid] | Android 2.3        |
| iOS               | VideoLAN.LibVLC.iOS                 | [![LibVLCiOSBadge]][LibVLCiOS]         | iOS 8.4            |
| tvOS              | VideoLAN.LibVLC.tvOS                | [![LibVLCtvOSBadge]][LibVLCtvOS]       | tvOS 10.2          |
| Linux             | [Linux guide](docs/linux-setup.md)  | N/A                                    | N/A                |
Martin Finkel's avatar
Martin Finkel committed
83

84
```cmd
85
dotnet add package VideoLAN.LibVLC.[Windows|UWP|Android|iOS|Mac|tvOS]
86 87 88
```

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
89

Jérémy VIGNELLES's avatar
Jérémy VIGNELLES committed
90 91
2. Install **LibVLCSharp** _or_ **LibVLCSharp.Forms** (if you plan on using Xamarin.Forms)

92 93 94 95 96 97 98
| Platform          | LibVLCSharp Package                             | NuGet                                             |
| ----------------- | ----------------------------------------------- | ------------------------------------------------- |
| .NET Standard     | [LibVLCSharp](LibVLCSharp/README.md)            | [![LibVLCSharpBadge]][LibVLCSharp]                |
| Xamarin.Android   | [LibVLCSharp](LibVLCSharp/README.md)            | [![LibVLCSharpBadge]][LibVLCSharp]                |
| Xamarin.iOS       | [LibVLCSharp](LibVLCSharp/README.md)            | [![LibVLCSharpBadge]][LibVLCSharp]                |
| Xamarin.tvOS      | [LibVLCSharp](LibVLCSharp/README.md)            | [![LibVLCSharpBadge]][LibVLCSharp]                |
| Xamarin.Mac       | [LibVLCSharp](LibVLCSharp/README.md)            | [![LibVLCSharpBadge]][LibVLCSharp]                |
99
| UWP               | [LibVLCSharp](LibVLCSharp/README.md)            | [![LibVLCSharpBadge]][LibVLCSharp]                |
100 101 102 103 104 105
| Xamarin.Forms     | [LibVLCSharp.Forms](LibVLCSharp.Forms/README.md)| [![LibVLCSharpFormsBadge]][LibVLCSharpForms]      |
| WPF               | LibVLCSharp.WPF                                 | [![LibVLCSharpWPFBadge]][LibVLCSharpWPF]          |
| Xamarin.Forms.WPF | [LibVLCSharp.Forms.WPF][RLibVLCSharpFormsWPF]    | [![LibVLCSharpFormsWPFBadge]][LibVLCSharpFormsWPF]|
| GTK               | [LibVLCSharp.GTK](LibVLCSharp.GTK/README.md)    | [![LibVLCSharpGTKBadge]][LibVLCSharpGTK]          |
| Xamarin.Forms.GTK | [LibVLCSharp.Forms.GTK][RLibVLCSharpFormsGTK]    | [![LibVLCSharpFormsGTKBadge]][LibVLCSharpFormsGTK]|
| Windows Forms     | LibVLCSharp.WinForms                            | [![LibVLCSharpWinFormsBadge]][LibVLCSharpWinForms]|
106

Jérémy VIGNELLES's avatar
Jérémy VIGNELLES committed
107
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
108

109 110 111
[RLibVLCSharpFormsWPF]: LibVLCSharp.Forms.Platforms.WPF/README.md
[RLibVLCSharpFormsGTK]: LibVLCSharp.Forms.Platforms.GTK/README.md

Jérémy VIGNELLES's avatar
Jérémy VIGNELLES committed
112 113 114
[LibVLCWindowsBadge]: https://img.shields.io/nuget/v/VideoLAN.LibVLC.Windows.svg
[LibVLCWindows]: https://www.nuget.org/packages/VideoLAN.LibVLC.Windows/

115 116
[LibVLCWin10Badge]: https://img.shields.io/nuget/v/VideoLAN.LibVLC.UWP.svg
[LibVLCWin10]: https://www.nuget.org/packages/VideoLAN.LibVLC.UWP/
117

Jérémy VIGNELLES's avatar
Jérémy VIGNELLES committed
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
[LibVLCMac]: https://www.nuget.org/packages/VideoLAN.LibVLC.Mac/
[LibVLCMacBadge]: https://img.shields.io/nuget/v/VideoLAN.LibVLC.Mac.svg

[LibVLCAndroid]: https://www.nuget.org/packages/VideoLAN.LibVLC.Android/
[LibVLCAndroidBadge]: https://img.shields.io/nuget/v/VideoLAN.LibVLC.Android.svg

[LibVLCiOS]: https://www.nuget.org/packages/VideoLAN.LibVLC.iOS/
[LibVLCiOSBadge]: https://img.shields.io/nuget/v/VideoLAN.LibVLC.iOS.svg

[LibVLCtvOS]: https://www.nuget.org/packages/VideoLAN.LibVLC.tvOS/
[LibVLCtvOSBadge]: https://img.shields.io/nuget/v/VideoLAN.LibVLC.tvOS.svg

[LibVLCSharp]: https://www.nuget.org/packages/LibVLCSharp/
[LibVLCSharpBadge]: https://img.shields.io/nuget/v/LibVLCSharp.svg

[LibVLCSharpForms]: https://www.nuget.org/packages/LibVLCSharp.Forms/
[LibVLCSharpFormsBadge]: https://img.shields.io/nuget/v/LibVLCSharp.Forms.svg

[LibVLCSharpWPF]: https://www.nuget.org/packages/LibVLCSharp.WPF/
[LibVLCSharpWPFBadge]: https://img.shields.io/nuget/v/LibVLCSharp.WPF.svg

[LibVLCSharpFormsWPF]: https://www.nuget.org/packages/LibVLCSharp.Forms.WPF/
[LibVLCSharpFormsWPFBadge]: https://img.shields.io/nuget/v/LibVLCSharp.Forms.WPF.svg

[LibVLCSharpGTK]: https://www.nuget.org/packages/LibVLCSharp.GTK/
[LibVLCSharpGTKBadge]: https://img.shields.io/nuget/v/LibVLCSharp.GTK.svg

[LibVLCSharpFormsGTK]: https://www.nuget.org/packages/LibVLCSharp.Forms.GTK/
[LibVLCSharpFormsGTKBadge]: https://img.shields.io/nuget/v/LibVLCSharp.Forms.GTK.svg

[LibVLCSharpWinForms]: https://www.nuget.org/packages/LibVLCSharp.WinForms/
[LibVLCSharpWinFormsBadge]: https://img.shields.io/nuget/v/LibVLCSharp.WinForms.svg

Martin Finkel's avatar
Martin Finkel committed
151 152
## Getting started

153
Follow the [Getting started guide](GETTING-STARTED.md). Make sure you read it since it contains platform-specific caveats
Martin Finkel's avatar
Martin Finkel committed
154

155 156 157 158
## 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
159 160
- [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.
161
- [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).
162
- [PulseMusic UX](https://code.videolan.org/mfkl/libvlcsharp-samples/tree/master/PulseMusic): A stylish music player UX example using Skia on iOS and Android.
163
- [Gestures sample](https://code.videolan.org/mfkl/libvlcsharp-samples/tree/master/Gestures/Gestures): Cross-platform touch gestures and 360 videos on iOS and Android.
164 165 166

Feel free to suggest and contribute new samples.

Martin Finkel's avatar
Martin Finkel committed
167
## Quick API overview
Martin Finkel's avatar
Martin Finkel committed
168

Martin Finkel's avatar
Martin Finkel committed
169 170
- [`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
171 172
- [`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.
173 174 175
- [`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
176

Martin Finkel's avatar
Martin Finkel committed
177
## Roadmap
178

Martin Finkel's avatar
Martin Finkel committed
179
- MediaPlayerElement control
Martin Finkel's avatar
Martin Finkel committed
180
- Game engines (Unity, Unreal, Godot)
Martin Finkel's avatar
Martin Finkel committed
181

182 183
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).

184 185 186 187
## Versioning

As this is a libvlc binding, we try to follow the libvlc versioning scheme as much as possible. The versioning strategy is explained in the [VERSIONING](VERSIONING.md) document.

188 189 190 191
## Release Notes

Check out the [NEWS](NEWS) file for details about each release.

Martin Finkel's avatar
Martin Finkel committed
192 193 194 195
## Contribute

### Pull request

196
Pull requests are more than welcome! If you do submit one, please make sure to read the [contributing guidelines](CONTRIBUTING.md) first.
Martin Finkel's avatar
Martin Finkel committed
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223

### 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
224 225
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)

226 227 228 229
### 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
230 231 232 233 234 235
## Code of Conduct

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

## License

236 237 238
LibVLCSharp is under the LGPLv2.1.

Note: the .NET4.0 LibVLCSharp build references a nuget package that may indicate its license as the .NET Library license but it's actually [opensource](https://github.com/Microsoft/referencesource/commit/6952d2c3923d30a4d88bf57120688b9532bbe1d8) under MIT.