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

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

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

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

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

Martin Finkel's avatar
Martin Finkel committed
97
Basically, you need to instantiate a `VideoView` and add it to your 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. The `MediaPlayer` 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
98
99
100

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
## 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
108
109
- [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.
110
- [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).
111
112
113

Feel free to suggest and contribute new samples.

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

Martin Finkel's avatar
Martin Finkel committed
116
117
118
- `VideoView.cs`: Custom view which holds a `MediaPlayer` object.
- [`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.
119
120
121
122
- [`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
123

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

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

Martin Finkel's avatar
Martin Finkel committed
135
136
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
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
175
## 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.