vlc-ios is a mirror, not the source of truth, and the real work happens in VLCKit

A mirror, and the distinction changes how you contribute

This is the official mirror repository of the VLC for iOS and tvOS application, and the README is unambiguous about the source of truth. You can find the official repository at code.videolan.org under videolan/vlc-ios.

That single sentence changes how you should treat everything else in the repository. A mirror is published for convenience and for people who are already on GitHub, and it is not where changes are accepted. So if you want to contribute, the GitHub copy is the wrong destination, and the contribution section in this README, which invites pull requests, is describing the process for the canonical repository rather than for the copy you are reading.

The application is written in Objective-C and Swift and uses VLCKit, which is a libvlc wrapper. That is the key structural fact. The player itself is the front end, and the media engine, the part that actually decodes, demuxes and plays every format VLC supports, comes from libvlc through VLCKit.

The repository layout follows that split. There is `Sources/` for the application code, `Resources/` for the assets, `Buildsystem/` for the build configuration, `Documentation/` which includes the coding style guide, `MediaLibraryWidget/` and its extension, and `MediaLibraryWidgetExtensionDebug.entitlements` for the widget extension's entitlements.

The project files are there too, with `VLC.xcodeproj/`, `VLC.xcworkspace/`, a `Podfile` and a `Podfile.lock`, and an `AUTHORS` file and a `COPYING` file with the licence details.

The last push to the repository was on 2026-10-14, the default branch is `master`, and the repository is not archived, so the mirror is being kept current. There are no GitHub releases, so the version history is on the VideoLAN GitLab.

Building the app is four steps and a workspace

The requirements are short. Xcode 11.0 or newer, macOS 10.12 or newer, and Cocoapods 1.4 or newer.

Then five steps to build VLC-iOS.

First, clone the repository.

git clone https://code.videolan.org/videolan/vlc-ios.git

Second, install Cocoapods with `[sudo] gem install cocoapods`, and on Apple Silicon devices also run `[sudo] arch -x86_64 gem install ffi`. Third, run `pod install`, or `arch -x86_64 pod install` on Apple Silicon devices. Fourth, open `VLC.xcworkspace`. Fifth, hit Build and Run.

Two details in there are worth understanding rather than copying.

The `arch -x86_64` prefix is the Rosetta translation trick, and it is needed because the ffi gem that CocoaPods depends on is not always available as a native Apple Silicon build at the time. On Apple Silicon, the `pod install` step also runs under `arch -x86_64`. That is the friction of a project that grew up before the toolchain was ready.

The `pod install` step is what fetches VLCKit as a dependency, and the reason you open the workspace rather than the project is that CocoaPods generates an xcworkspace that references both. Opening `VLC.xcodeproj` instead of `VLC.xcworkspace` is the single most common reason a CocoaPods based project fails to build, and the README steps around it by naming the workspace explicitly.

There is a beginner's guide for when that does not work, linked from the README, and the guidance is to submit an issue if the problem is not there. The issues live on the VideoLAN GitLab, and there is a beginner friendly label for people who do not know where to start.

Custom VLCKit is a framework swap, not a config option

The custom VLCKit section is described as mostly for debugging or advanced users, and it is the most revealing part of the README.

The steps are to clone VLCKit, run the build script inside that folder, and then replace the framework in the app.

./compileAndBuildVLCKit.sh -a ${MYARCH}

`MYARCH` can be `x86_64` or `aarch64`. The `-d` flag gives a debug build with valid stack traces and asserts, and the `-n` flag lets you use your own VLC repository for VLCKit.

Then the replacement is a filesystem operation rather than a package operation, which is the striking detail.

cd Pods/VLCKit

rm -rf VLCKit.xcframework

ln -s ${VLCKit}/build/VLCKit.xcframework

So you delete the xcframework that CocoaPods downloaded and put a symbolic link in its place pointing at your locally built one. The instruction to do this after a `pod update` implies that the swap is not persistent, since updating the pods will bring the downloaded framework back and undo the link.

That tells you something important about the architecture. The media engine is distributed as a prebuilt binary framework, not built from source as part of the app build. That is why the normal build is a `pod install` and a click, and why debugging the engine itself needs a separate build, a separate script and a manual swap.

For a developer who wants to change something in libvlc and see the effect in the iOS app, this is the whole procedure, and the README is unusually complete about it. The `-n` flag closes the loop by letting you point at a fork of the VLC repository itself, so the chain from a change in the decoder to the running app is three steps long.

The commit format and the issue templates are specified, not left to taste

The contribution guidance is specific enough to be worth following exactly, and the two parts are a commit format and an issue hygiene rule.

Pull requests are more than welcome, and the ask is a descriptive title and description. For commits, the project tries to follow a simple set of rules outlined in a linked guide, and additionally requires that commit messages contain all the information needed to understand the commit easily.

Subject: Brief description

Description in detail if needed.

ticket related action

And the example given is a real one.

UPnP: Remove iOS 7 compatibility code

Closes #166

The format is the conventional one, a subject line, a body, and a reference to the ticket. The `Closes` form rather than a plain mention is the detail that matters, because it is what lets the tracker close the issue automatically.

The issue guidance has a rule that is easy to skip and useful to follow. You can look through the issues on the VideoLAN GitLab, and before creating an issue or ticket you should double check for duplicates. Two templates are provided, one for reporting an issue and one for requesting a feature, and each section of the template should contain at least one meaningful sentence in order to guarantee a proper understanding of the ticket.

That last requirement is a small piece of project hygiene with a real effect. A tracker full of one word reports is a tracker nobody can triage, and asking for a meaningful sentence per section is the cheapest way to keep it usable.

For support questions that are not bugs, the README points at the VideoLAN forum rather than the issue tracker, and says to visit it if you are not sure it is actually an issue. The code of conduct is the VideoLAN one from the project wiki.

The licensing is a dual grant, and the file names differ from the usual

VLC-iOS is under the GPLv2 or later and the MPLv2 license, and the README points at the COPYING file for more license info.

That is worth pausing on, because a dual GPL and MPL arrangement is a deliberate choice rather than an accident. The MPL is a file-level copyleft, so it lets you use the library files in a larger proprietary work as long as the modifications to those files are published, while the GPL covers the rest. The combination is the standard way to say: the application as a whole is copyleft, and the reusable pieces are not.

If you are reading this to reuse code rather than to build the app, that distinction is the whole question, and the COPYING file is the place to read it. The file name is worth noting, because COPYING is a GNU convention rather than the usual LICENSE, and the repository metadata reports the licence as one that GitHub could not classify, so the file is the authoritative source.

The project also carries an `AUTHORS` file and a `.mailmap` at the root, which is the mechanism for mapping the many identities in the commit history to one canonical address, so the right person is credited for a change.

The remaining top level entries are the ones you would expect from a native Apple application. There is the Xcode project and workspace, the Podfile and its lock, the Sources directory, Resources, the Buildsystem directory, the MediaLibraryWidget and its extension with the debug entitlements, and the VLC-iOS debug entitlements and the no-watch debug variant.

For everything else, the README points at the VideoLAN wiki and the support page, and closes with a line that is unusual in a project readme: we are happy to help.

Editorial conclusion

Adopt this repository as the place to read how a mature native media player is put together on Apple platforms, and to track where the app code lives. Do not treat it as the canonical source, because the README states the official repository is on VideoLAN's own GitLab and this is a mirror, so a pull request here is not the path to a merged change. Verify first that you are working against the GitLab repository, that your Xcode and CocoaPods versions satisfy the stated requirements, and that you understand the licensing split before reusing code, since the project is under both GPLv2 or later and MPLv2.

Frequently asked questions

Official sources

1. Issues
2. README
3. videolan/vlc-ios on GitHub