README.md 8.33 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
8
[![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
9
LibVLCSharp are .NET/Mono bindings for `libvlc`, the multimedia framework powering the VLC applications.
Martin Finkel's avatar
Martin Finkel committed
10

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

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

## Goal

Martin Finkel's avatar
Martin Finkel committed
32
33
34
35
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
36
37
38
39
`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
40
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
41

Martin Finkel's avatar
Martin Finkel committed
42
## Features
Martin Finkel's avatar
Martin Finkel committed
43

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

Martin Finkel's avatar
Martin Finkel committed
46
Some of the features include:
Martin Finkel's avatar
Martin Finkel committed
47

Martin Finkel's avatar
Martin Finkel committed
48
49
50
51
52
53
54
55
- 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
56

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

Martin Finkel's avatar
Martin Finkel committed
59
60
## Supported platforms

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

Martin Finkel's avatar
Martin Finkel committed
73
## Installation
Martin Finkel's avatar
Martin Finkel committed
74

Martin Finkel's avatar
typo    
Martin Finkel committed
75
You need to install 2 packages to get started.
Martin Finkel's avatar
Martin Finkel committed
76

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

Martin Finkel's avatar
Martin Finkel committed
79
80
81
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
82
dotnet add package LibVLCSharp
Martin Finkel's avatar
Martin Finkel committed
83
84
85
86
87
88
89
```

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
90
dotnet add package LibVLCSharp.Forms
Martin Finkel's avatar
Martin Finkel committed
91
92
93
```

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

## Getting started

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

Martin Finkel's avatar
Martin Finkel committed
99
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
100
101
102

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
103
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
104
105
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.

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

Feel free to suggest and contribute new samples.

Martin Finkel's avatar
Martin Finkel committed
116
## Quick API overview
Martin Finkel's avatar
Martin Finkel committed
117

Martin Finkel's avatar
Martin Finkel committed
118
119
120
- `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.
121
122
123
124
- [`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
125

Martin Finkel's avatar
Martin Finkel committed
126
## Roadmap
Martin Finkel's avatar
Martin Finkel committed
127

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

Martin Finkel's avatar
Martin Finkel committed
137
138
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
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
176
177
## 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.