README.md 7.72 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

Martin Finkel's avatar
Martin Finkel committed
7
LibVLCSharp are .NET/Mono bindings for `libvlc`, the multimedia framework powering the VLC applications.
Martin Finkel's avatar
Martin Finkel committed
8

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

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

## Goal

30 31 32 33
LibVLCSharp's goal is to support all .NET runtimes (Xamarin/Mono, .NET Core and .NET Framework) on most operating systems by targeting .NET Standard 2.0.

We also aim to provide you with a custom video control integrated with the OS native UI toolkit. That means integration with UWP, Cocoa (Xamarin.Mac), GTK# and game engines with Mono support (Unity, Unreal, Godot). For a current status, see [Supported platforms](#supported-platforms) and [Roadmap](#roadmap).

Martin Finkel's avatar
Martin Finkel committed
34 35 36 37
`libvlc` is a complete, opensource and crossplatform multimedia framework written in C. On the other hand, Xamarin allows true crossplatform .NET code on all platforms and provides an efficient way to build crossplatform UIs with Xamarin.Forms.

LibVLCSharp is designed to be the connecting layer in between `libvlc` and Xamarin.

Martin Finkel's avatar
Martin Finkel committed
38
Using LibVLCSharp means you can take advantage of all `libvlc` features from shared managed code (C#/F#), in a true crossplatform way. You may use the features described below on all [supported platforms](#supported-platforms) by LibVLCSharp.
Martin Finkel's avatar
Martin Finkel committed
39

Martin Finkel's avatar
Martin Finkel committed
40
## Features
Martin Finkel's avatar
Martin Finkel committed
41

Martin Finkel's avatar
Martin Finkel committed
42
Check out [libvlc-nuget](https://github.com/mfkl/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
43

Martin Finkel's avatar
Martin Finkel committed
44
Some of the features include:
Martin Finkel's avatar
Martin Finkel committed
45

Martin Finkel's avatar
Martin Finkel committed
46 47 48 49 50 51 52 53
- Network browsing for distant filesystems (SMB, FTP, SFTP, NFS...).
- HDMI passthrough for Audio HD codecs, like E-AC3, TrueHD or DTS-HD.
- 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
54

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

57 58
## Supported platforms

Martin Finkel's avatar
Martin Finkel committed
59 60
- Xamarin.Android
- Xamarin.iOS
Martin Finkel's avatar
Martin Finkel committed
61
- Xamarin.Mac
Martin Finkel's avatar
Martin Finkel committed
62
- Windows (WPF/WinForms)
Martin Finkel's avatar
Martin Finkel committed
63
- Xamarin.Forms
Martin Finkel's avatar
Martin Finkel committed
64 65
    - iOS
    - Android
66
    - Mac
Martin Finkel's avatar
Martin Finkel committed
67 68 69
    - WPF
- Unity
    - Android
Martin Finkel's avatar
Martin Finkel committed
70

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

Martin Finkel's avatar
Martin Finkel committed
73
You need to install 2 packages to get started.
Martin Finkel's avatar
Martin Finkel committed
74

Martin Finkel's avatar
Martin Finkel committed
75
The first is `libvlc`, which is the actual VLC engine written mostly in C/C++ and compiled for your target platform. You can find information about it and how to download it on NuGet [here](https://github.com/mfkl/libvlc-nuget).
Martin Finkel's avatar
Martin Finkel committed
76

Martin Finkel's avatar
Martin Finkel committed
77 78 79
The second package you need is LibVLCSharp, the .NET wrapper that consumes `libvlc` and allows you to interact with native code from C#/F#. 

```cmd
Martin Finkel's avatar
Martin Finkel committed
80
dotnet add package LibVLCSharp
Martin Finkel's avatar
Martin Finkel committed
81 82 83 84 85 86 87
```

https://www.nuget.org/packages/LibVLCSharp

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 91
```

https://www.nuget.org/packages/LibVLCSharp.Forms/
Martin Finkel's avatar
Martin Finkel committed
92 93 94

## Getting started

95
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
96 97 98 99 100

Basically, you need to instantiate a `VideoView` and add it to your View. It handles the required `libvlc` initialization for you on each platform, and offers a `MediaPlayer` .NET object on which you can call `Play`, `Pause`, set a new media or listen for `libvlc` events.

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
101
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
102 103
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.

104 105 106 107 108 109 110 111 112
## Samples

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

- Chromecast sample: Discover chromecasts on your local network and select one for playback in 100% shared code (Xamarin.Forms, iOS/Android).
- Record HLS sample: Simple .NET Core CLI app which shows how to record an HLS stream to the filesystem.

Feel free to suggest and contribute new samples.

Martin Finkel's avatar
Martin Finkel committed
113
## Quick API overview
Martin Finkel's avatar
Martin Finkel committed
114

Martin Finkel's avatar
Martin Finkel committed
115
- `VideoView.cs`: Custom view which holds a `LibVLC` object and a `MediaPlayer` object.
116 117 118 119 120 121
- [`LibVLC.cs`](https://github.com/videolan/libvlcsharp/blob/master/LibVLCSharp/Shared/LibVLC.cs): Main object pointing to a native `libvlc` instance in native code. Accessible from `VideoView`.
- [`MediaPlayer.cs`](https://github.com/videolan/libvlcsharp/blob/master/LibVLCSharp/Shared/MediaPlayer.cs): Manages playback, offers event listeners and more. Accessible from `VideoView`.
- [`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.
- [`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.
- [`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
122

Martin Finkel's avatar
Martin Finkel committed
123
## Roadmap
124

Martin Finkel's avatar
Martin Finkel committed
125
- macOS (using GTK)
Martin Finkel's avatar
Martin Finkel committed
126
- tvOS
127 128
- Linux (using GTK)
- Windows 10 (using UWP, GTK)
Martin Finkel's avatar
Martin Finkel committed
129 130 131
- Xamarin.Forms
    - GTK
    - UWP
Martin Finkel's avatar
Martin Finkel committed
132
- Game engines (Unity, Unreal, Godot)
Martin Finkel's avatar
Martin Finkel committed
133

134 135
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
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
## 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/).

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