README.md 5.27 KB
Newer Older
Geoffrey Métais's avatar
Geoffrey Métais committed
1
# VLC for Android
Martin Finkel's avatar
Martin Finkel committed
2

Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
3
4
5
6
This is the official **Android** port of [VLC](https://videolan.org/vlc/).

VLC on Android plays all the same files as the classical version of VLC, and features a media database
for Audio and Video files and stream.
Geoffrey Métais's avatar
Geoffrey Métais committed
7

Geoffrey Métais's avatar
Geoffrey Métais committed
8
9
- [Project Structure](#project-structure)
- [LibVLC](#libvlc)
10
- [License](#license)
Geoffrey Métais's avatar
Geoffrey Métais committed
11
12
13
14
15
16
17
18
19
20
21
22
- [Build](#build)
  - [Build Application](#build-application)
  - [Build LibVLC](#build-libvlc)
- [Contribute](#contribute)
  - [Pull requests](#pull-requests)
  - [Translations](#translations)
- [Issues and feature requests](#issues-and-feature-requests)
- [Support](#support)

## Project Structure

Here are the current folders of vlc-android project:
Martin Finkel's avatar
Martin Finkel committed
23

24
- extension-api : Application extensions SDK (not released yet)
Geoffrey Métais's avatar
Geoffrey Métais committed
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
- application : Android application source code, organized by modules.
- buildsystem : Build scripts, CI and maven publication configuration
- libvlc : LibVLC gradle module, VLC source code will be cloned in `vlc/` at root level.
- medialibrary : Medialibrary gradle module

## LibVLC

LibVLC is the Android library embedding VLC engine, which provides a lot of multimedia features, like:

- Play every media file formats, every codec and every streaming protocols
- Hardware and efficient decoding on every platform, up to 8K
- Network browsing for distant filesystems (SMB, FTP, SFTP, NFS...) and servers (UPnP, DLNA)
- Playback of Audio CD, DVD and Bluray with menu navigation
- Support for HDR, including tonemapping for SDR streams
- Audio passthrough with SPDIF and HDMI, including for Audio HD codecs, like DD+, TrueHD or DTS-HD
- Support for video and audio filters
- Support for 360 video and 3D audio playback, including Ambisonics
- Ability to cast and stream to distant renderers, like Chromecast and UPnP renderers.
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
43

Geoffrey Métais's avatar
Geoffrey Métais committed
44
45
46
47
48
And more.

![LibVLC stack](https://images.videolan.org/images/libvlc_stack.png)

You can use our LibVLC module to power your own Android media player.
Martin Finkel's avatar
Martin Finkel committed
49
50
51
Download the `.aar` directly from [Maven](https://search.maven.org/artifact/org.videolan.android/libvlc-all) or build from source.

Have a look at our [sample codes](https://code.videolan.org/videolan/libvlc-android-samples).
Geoffrey Métais's avatar
Geoffrey Métais committed
52

53
## License
Martin Finkel's avatar
Martin Finkel committed
54

55
56
57
58
VLC for Android is licensed under [GPLv2 (or later)](COPYING). Android libraries make this, de facto, a GPLv3 application.

VLC engine *(LibVLC)* for Android is licensed under [LGPLv2](libvlc/COPYING.LIB).

Geoffrey Métais's avatar
Geoffrey Métais committed
59
60
## Build

Geoffrey Métais's avatar
Geoffrey Métais committed
61
Native libraries are published on bintray. So you can:
Martin Finkel's avatar
Martin Finkel committed
62

Geoffrey Métais's avatar
Geoffrey Métais committed
63
64
65
66
67
68
69
- Build the application and get libraries via gradle dependencies (JVM build only)
- Build the whole app (LibVLC + Medialibrary + Application)
- Build LibVLC only, and get an .aar package

### Build Application

VLC-Android build relies on gradle build modes :
Martin Finkel's avatar
Martin Finkel committed
70

Geoffrey Métais's avatar
Geoffrey Métais committed
71
72
73
74
75
76
- `Release` & `Debug` will get LibVLC and Medialibrary from Bintray, and build application source code only.
- `SignedRelease` also, but it will allow you to sign application apk with a local keystore.
- `Dev` will build build LibVLC, Medialibrary, and then build the application with these binaries. (via build scripts only)

### Build LibVLC

Geoffrey Métais's avatar
Geoffrey Métais committed
77
You will need a recent Linux distribution to build VLC.
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
78
It should work with Windows 10, and macOS, but there is no official support for this.
Geoffrey Métais's avatar
Geoffrey Métais committed
79

Geoffrey Métais's avatar
Geoffrey Métais committed
80
81
82
83
84
85
86
#### Setup

Check our [AndroidCompile wiki page](https://wiki.videolan.org/AndroidCompile/), especially for build dependencies.

Here are the essential points:

On Debian/Ubuntu, install the required dependencies:
Martin Finkel's avatar
Martin Finkel committed
87
```bash
Geoffrey Métais's avatar
Geoffrey Métais committed
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
sudo apt install automake ant autopoint cmake build-essential libtool-bin \
    patch pkg-config protobuf-compiler ragel subversion unzip git \
    openjdk-8-jre openjdk-8-jdk flex python wget
```

Setup the build environment:
Set `$ANDROID_SDK` to point to your Android SDK directory
`export ANDROID_SDK=/path/to/android-sdk`

Set `$ANDROID_NDK` to point to your Android NDK directory
`export ANDROID_NDK=/path/to/android-ndk`

Then, you are ready to build!

#### Build

`buildsystem/compile.sh -l -a <ABI>`

ABI can be `arm`, `arm64`, `x86`, `x86_64` or `all` for a multi-abis build

You can do a library release build with `-r` argument

#### Medialibrary

Build Medialibrary with `-ml` instead of `-l`
Geoffrey Métais's avatar
Geoffrey Métais committed
113
114
115
116
117

## Contribute

VLC is a libre and open source project, we welcome all contributions.

Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
118
119
Just respect our [Code of Conduct](https://wiki.videolan.org/CoC/).

Geoffrey Métais's avatar
Geoffrey Métais committed
120
121
### Pull requests

Geoffrey Métais's avatar
Geoffrey Métais committed
122
123
124
125
Pull requests must be proposed on our [gitlab server](https://code.videolan.org/videolan/vlc-android/).

So you must create an account, fork vlc-android project, and propose your merge requests from it.

Martin Finkel's avatar
Martin Finkel committed
126
**Except for translations**, see the section below.
Geoffrey Métais's avatar
Geoffrey Métais committed
127

Geoffrey Métais's avatar
Geoffrey Métais committed
128
129
130
### Translations

You can help improving translations too by joining the [transifex vlc project](https://www.transifex.com/yaron/vlc-trans/dashboard/)
Geoffrey Métais's avatar
Geoffrey Métais committed
131

Geoffrey Métais's avatar
Geoffrey Métais committed
132
Translations merge requests are then generated from transifex work.
Geoffrey Métais's avatar
Geoffrey Métais committed
133

Geoffrey Métais's avatar
Geoffrey Métais committed
134
135
## Issues and feature requests

Geoffrey Métais's avatar
Geoffrey Métais committed
136
137
VLC for Android bugtracker is hosted on [VideoLAN gitlab](https://code.videolan.org/videolan/vlc-android/issues)  
Please look for existing issues and provide as much useful details as you can (e.g. vlc app version, device and Android version).
Geoffrey Métais's avatar
Geoffrey Métais committed
138

Geoffrey Métais's avatar
Geoffrey Métais committed
139
A template is provided, please use it!
Geoffrey Métais's avatar
Geoffrey Métais committed
140

Martin Finkel's avatar
Martin Finkel committed
141
Issues without relevant information will be ignored, we cannot help in this case.
Geoffrey Métais's avatar
Geoffrey Métais committed
142

Geoffrey Métais's avatar
Geoffrey Métais committed
143
## Support
Geoffrey Métais's avatar
Geoffrey Métais committed
144
145

- Android mailing list: android@videolan.org
146
- bugtracker: https://code.videolan.org/videolan/vlc-android/issues
Geoffrey Métais's avatar
Geoffrey Métais committed
147
- IRC: *#videolan* channel on [freenode](http://freenode.net/)
Martin Finkel's avatar
Martin Finkel committed
148
- VideoLAN forum: https://forum.videolan.org/