godot-vlc

VLC extension for Godot. Supports Godot 4.3 and newer. Supports Windows, Linux and Android.

How to use

Put media files into res:// and they will be loaded as VLCMedia. Then you can play them with VLCMediaPlayer node.

You can also use VLCMedia.load_from_file() to load media from disk or VLCMedia.load_from_mrl() to load media from a media resource locator.

There are some other features, such as subtitles and chapters, can be accessed through scripts. For more information, see the in-editor documentation.

Supported platforms

Nothing has to be installed on the user's machine: the addon ships its own LibVLC and does not use a system VLC. The Linux requirement above comes from how the extension is built, not from a choice in the code; the bound is recorded in build/vlc/glibc-baseline.txt and enforced by scripts/check_glibc_floor.ps1.

The Android runtime differs from the two desktop ones in ways that are visible from a game: it is a single monolithic libvlc.so with every module linked into it, because Android will not load a plugin tree out of an application's assets, so there is no libvlccore.so and no plugins/ directory to go with it. Video reaches Godot through the software vmem output -- frames are decoded to memory and uploaded to a texture -- because LibVLC 4 has no Android engine for the output-callbacks API the Windows GPU path uses. Everything under res:// is handed to LibVLC as an in-memory buffer, so no media is ever unpacked to disk.

Known limitations

• The runtime ships every plugin VLC builds, including video outputs and screen capture this extension never uses. Pruning them is not done yet; they are what the X11 entries in scripts/host-provided-libs.txt are for.
• The Linux extension and the bundled LibVLC runtime are both built on ubuntu 22.04, so both require glibc 2.35. build/vlc/glibc-baseline.txt records the bound and scripts/check_glibc_floor.ps1 enforces it across the whole runtime.
• The Android runtime is monolithic, so a module cannot be added or removed without rebuilding it. That is also why the build has to intervene on libvlcjni's module blacklist: the vmem output this extension renders through needs the dummy vout window module, and the access module behind imem:// is what lets media inside res:// be played at all.
• Android video goes through the software vmem output only. LibVLC 4 offers no Android engine for the output-callbacks API, so there is no zero-copy path to compare with the Windows D3D11 one; frames are copied to memory and uploaded.
• Android is built for arm64-v8a alone. armeabi-v7a and x86_64 are not built, so an x86_64 emulator cannot run the addon.
• The Android runtime and the extension are both built for 16 KB memory pages, which Android 15 and later require; a runtime built elsewhere may not be.
• The bundled runtimes are stripped of debug information. VLC is built with -g and nothing removed the result, so the addon used to ship it: 666 MB of the Linux runtime's 798 MB of shared objects and 827 MB of the Windows runtime's 1026 MB were .debug_* sections, and the packed Linux runtime was 307 MB where the same tree stripped is 53 MB. The trade is that a crash inside LibVLC has no symbols here; build/vlc/postprocess.ps1 records the reasoning.
• macOS, Linux arm64 and Windows arm64 are not supported.

Licensing

This library is LGPL-2.1-or-later; see LICENSE.

The bundled LibVLC runtime is built with contrib/bootstrap --disable-gpl --disable-gnuv3 --enable-ad-clauses. VideoLAN's own Apple, Android and wasm builds use the same set, and contrib/bootstrap reports the resulting licence as "Lesser GPL version 2.1, with advertisement clauses" — so this is LGPL with advertisement clauses, not plain LGPLv2.1.

That is deliberate. VLC's plugin tree is licence-heterogeneous, and bundling GPL-licensed modules such as x264 would mean answering licensing questions for every project that uses this extension in a commercial game. What the flags exclude is encoders and DVD access; H.264, VP9 and AV1 decoding go through avcodec and dav1d and are unaffected. --enable-ad-clauses is what admits freetype, VLC's subtitle and OSD text renderer, so it is not optional.