vlc-android: two of the five documented folders are not in the tree

Two of the five project folders are missing from a fresh clone

The project structure section names five folders. `application` is the Android application source code organised by modules, `buildsystem` holds the build scripts, CI and maven publication configuration, `medialibrary` is a gradle module, `libvlc` is described as the LibVLC gradle module with the note that VLC source code will be cloned into `vlc/` at root level, and `extension-api` is the application extensions SDK with a parenthetical that it is not released yet.

A fresh clone has three of them. The top level holds `application/`, `buildsystem/` and `medialibrary/`, alongside `build.gradle`, `settings.gradle`, `gradle.properties`, `COPYING`, `NEWS`, a `.mailmap`, a `.tx/` directory for translations and a `.gitlab/` directory, and there is no `libvlc/` and no `extension-api/`.

The `libvlc` case has a stated reason, since the module is a wrapper that expects the engine source to be cloned in separately. The `extension-api` case does not: it is described as not released yet and it is simply absent, which is the same information twice. So the folder list in the README is a picture of the intended layout rather than of what you get, and the two differ in a way that matters if you are scripting a build.

The description promises Android TV and ChromeOS, the README says Android

The repository description reads VLC for Android, Android TV and ChromeOS. The README opens by calling itself the official Android port of VLC and then never mentions either platform again. There is no section on TV, no section on ChromeOS, and nothing in the project structure that is obviously aimed at either.

The closest thing is the `extension-api` module, an extensions SDK for the application that the README marks as not released yet, which is the kind of surface a leaner form factor would need. That is an inference rather than a statement in the file, and the file does not make it.

What the README does describe is the media side: the port plays the same files as the classical version of VLC, and it ships a media database for audio and video files and streams, which is the `medialibrary` module in the tree. So a reader arriving from the description is told about three platforms and given documentation for one, plus a database and an extension point that is not there yet.

GPLv2 for the app, LGPLv2 for the engine, and a note about the difference

The licence section is two paragraphs and the second one is the interesting one. VLC for Android is licensed under GPLv2 or later, with the file named. The VLC engine, LibVLC for Android, is licensed under LGPLv2, with its own licence file inside `libvlc/`. And between them the README inserts a sentence that is really a legal note: Android libraries make this, de facto, a GPLv3 application.

That sentence explains why the application licence is not simply the one you would read off the COPYING file. Linking against the Android platform libraries pulls in terms that the GPLv2 grant cannot satisfy on its own, so the effective terms of the distributed application become GPLv3, whether or not the file says so.

For anyone embedding the player rather than shipping the app, the split matters more than the note. The engine is the LGPLv2 half, it is published as a `.aar` under the `org.videolan.android` group with the artifact named `libvlc-all`, and sample code for driving it lives on the project's own server. So the LGPL path is the supported route for building your own Android media player on the VLC engine.

The cheapest build path depends on a host named once

Three build routes are offered and they differ in how much they compile. You can build the application and take the native libraries as gradle dependencies, which the README notes is a JVM build only. You can build the whole app, meaning LibVLC, the medialibrary and the application. Or you can build LibVLC alone and end up with an `.aar` package.

The route that does the least work depends on prebuilt artifacts, and the sentence introducing it names one host: native libraries are published on bintray, and the Release and Debug gradle modes fetch LibVLC and the medialibrary from there, compiling only the application source. `SignedRelease` does the same and additionally lets you sign the application APK with a local keystore. `Dev` is the mode that builds LibVLC and the medialibrary locally and then links the application against those binaries, through the build scripts.

So the trade is explicit: three gradle modes for people who want the app, one for people who need signed output, and one that does the native work. What the repository does not do is name a second host for those prebuilt libraries, and whether that one is still serving them is not something the README addresses, which is worth confirming before you plan a release around it.

The engine build still asks for openjdk-8

Building the engine is a different exercise from building the app, and the README is candid about the platform: you need a recent Linux distribution, and it should work with Windows 10 and macOS, but there is no official support for either.

The dependency list for Debian and Ubuntu is one long line, and the entry that dates it is the JDK:

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

Autotools, cmake, ragel and a protobuf compiler sit comfortably alongside a JDK 8 package, and a JDK that old is the one item in the list a current distribution is unlikely to hand you without a repository of its own. The rest of the setup is two environment variables, `ANDROID_SDK` and `ANDROID_NDK`, pointed at your SDK and NDK directories.

The build itself is a single script, `buildsystem/compile.sh -l -a <ABI>`, where the ABI is one of `arm`, `arm64`, `x86`, `x86_64` or `all` for a multi-ABI build. Adding `-r` gives a library release build, and building the medialibrary instead is the same script with `-ml` in place of `-l`.

Pull requests go to GitLab, translations go to Transifex

The contribution path is not where the repository is mirrored. Pull requests must be proposed on the project's own gitlab server, which means creating an account there, forking vlc-android, and proposing merge requests from the fork. The repository's own top level reflects that, holding a `.gitlab/` directory and no `.github/` one.

Translations are the single exception to the rule about forks. They are contributed on the transifex vlc project instead, and the merge requests are then generated from that work, so a translator never touches the gitlab server. Contributions of UI or new features are expected to start with an issue so there can be a discussion before code exists.

The issue rules are stated just as firmly. The bugtracker is on the same gitlab server, a template is provided and should be used, and a report should carry the VLC app version, the device and the Android version. The last line is the one to note: issues without relevant information will be ignored.

Support is a mailing list, an IRC channel and a form in the app

Usage questions are routed away from the issue tracker by design. The in-app feedback option in the About screen is the first destination, then the Android mailing list at [email protected], then the bugtracker, then IRC on the `#videolan` channel on libera, then the VideoLAN forum. That is five channels for a project whose tracker is explicitly for bugs rather than for help.

The engine's capability list explains why a user would end up there with a question rather than a report. It covers every media format, codec and streaming protocol, hardware decoding up to 8K, network browsing of remote filesystems such as SMB, FTP, SFTP and NFS and of servers speaking UPnP and DLNA, Audio CD, DVD and Blu-ray with menu navigation, HDR including tonemapping for SDR streams, audio passthrough over SPDIF and HDMI for the HD audio codecs, video and audio filters, 360 video and 3D audio including Ambisonics, and casting to distant renderers such as Chromecast and UPnP devices.

The list ends with the two words and more, so it is a selection rather than a specification, and the reader is left with the documentation site and the forum for the rest.

Editorial conclusion

Use the LibVLC artifact if you are embedding a player, since that is the supported path and the engine is LGPLv2, and read the licence note before you combine it with anything: the application is GPLv2 or later, and the file itself explains that Android libraries make that de facto GPLv3. For building, decide early whether you want the prebuilt libraries from the remote host the README names, because the alternative is a native toolchain that still expects a JDK 8 era package list. And check the folder list against your clone before you plan around it, because two of the five directories the README describes are not there until a clone step runs.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. videolan/vlc-android on GitHub