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

Martin Finkel's avatar
Martin Finkel committed
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)
Martin Finkel's avatar
Martin Finkel committed
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
26
27
  - [Forum](#forum)
  - [Issues](#issues)
  - [IRC](#irc)
Martin Finkel's avatar
Martin Finkel committed
28
29
30
- [Code of Conduct](#code-of-conduct)
- [License](#license)

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

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

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

Martin Finkel's avatar
Martin Finkel committed
37
- Network browsing for distant filesystems (SMB, FTP, SFTP, NFS...).
Martin Finkel's avatar
Martin Finkel committed
38
- HDMI pass-through for Audio HD codecs, like E-AC3, TrueHD or DTS-HD.
Martin Finkel's avatar
Martin Finkel committed
39
40
41
42
43
44
- 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
45
- Equalizer support.
Martin Finkel's avatar
Martin Finkel committed
46

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

Martin Finkel's avatar
Martin Finkel committed
49
50
## Supported platforms

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

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

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

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

Martin Finkel's avatar
Martin Finkel committed
67
The __first__ is `libvlc`, which is the actual VLC engine written mostly in C/C++ and compiled for your target platform. It's named `VideoLAN.LibVLC.[Platform]`. You can find information about it and how to download it on NuGet [here](https://code.videolan.org/videolan/libvlc-nuget).
Martin Finkel's avatar
Martin Finkel committed
68

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

```cmd
Martin Finkel's avatar
Martin Finkel committed
72
dotnet add package LibVLCSharp
Martin Finkel's avatar
Martin Finkel committed
73
74
```

Martin Finkel's avatar
Martin Finkel committed
75
76
[![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
77
78
79
80

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
81
dotnet add package LibVLCSharp.Forms
Martin Finkel's avatar
Martin Finkel committed
82
83
```

Martin Finkel's avatar
Martin Finkel committed
84
85
[![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
86
87
88

## Getting started

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

Martin Finkel's avatar
Martin Finkel committed
91
92
93
- 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
94
95
96

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
97
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
98
99
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.

100
101
102
103
## 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
104
105
- [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.
106
- [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).
Martin Finkel's avatar
Martin Finkel committed
107
- [PulseMusic UX](https://code.videolan.org/mfkl/libvlcsharp-samples/tree/master/PulseMusic): A stylish music player UX example using Skia on iOS and Android.
108
109
110

Feel free to suggest and contribute new samples.

Martin Finkel's avatar
Martin Finkel committed
111
## Quick API overview
Martin Finkel's avatar
Martin Finkel committed
112

Martin Finkel's avatar
Martin Finkel committed
113
114
- [`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
115
116
- [`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.
117
118
119
- [`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
120

Martin Finkel's avatar
Martin Finkel committed
121
## Roadmap
Martin Finkel's avatar
Martin Finkel committed
122

Martin Finkel's avatar
Martin Finkel committed
123
- Game engines (Unity, Unreal, Godot)
124
- UWP
Martin Finkel's avatar
Martin Finkel committed
125

Martin Finkel's avatar
Martin Finkel committed
126
127
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
## 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
160
161
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)

Martin Finkel's avatar
Martin Finkel committed
162
163
164
165
166
167
168
## 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.