How to Play MKV, x265 and Other Unsupported Video Formats in React Native with VLC

React Native's built-in video support relies on the platform player underneath. On iOS that means AVPlayer, on Android the system MediaPlayer. Both are limited to the codecs your device supports out of the box. If your app needs to play an MKV file, an x265 (HEVC) encode, a VP9 video, a lossless FLAC track, or an RTSP security camera stream, you'll quickly hit "format not supported".

The common fix is to wrap a real media engine, and the most battle-tested one is VLC. This post covers @lunarr/vlc-player 2.0.0, a React Native VLC player rebuilt on the new architecture that you can add with a single dependency.

Why VLC for React Native

• Plays almost every format: MKV, Xvid, x265/HEVC, VP9, FLAC, Opus, and many more.
• Handles network protocols the platform players don't, including RTSP and HLS.
• Lets apps control audio tracks, subtitle tracks, playback rate, equalizer and more.
• Open source (MIT licensed), used in production apps for years.

A VLC player built on the React Native New Architecture

v2.0.0 of @lunarr/vlc-player is a complete rewrite. Instead of the legacy bridge, it uses a Fabric native component plus a TurboModule, both generated by codegen. That means better performance and no deprecated bridge code. It requires React Native 0.82 or newer.

Native engine versions used:

Installation

npm install @lunarr/vlc-player

After installing, reinstall the iOS pods so the codegen bindings link. You also need to disable Bitcode in the iOS build settings.

For Android no extra Maven repository is required, since libvlc-all resolves from Maven Central.

Expo users: the library works with the bare or prebuild workflow, but because it is a native module it cannot run inside Expo Go.

Playing a video in a few lines

import { useRef } from "react";
import Video, { type VLCPlayerRef } from "@lunarr/vlc-player";

export default function Player() {
  const ref = useRef<VLCPlayerRef>(null);

  return (
    <Video
      ref={ref}
      source={{ uri: "https://example.com/video.mkv" }}
      style={{ flex: 1 }}
      autoplay
      onProgress={({ currentTime, duration }) =>
        console.log(currentTime, duration)
      }
      onEnd={() => console.log("ended")}
      onError={(e) => console.warn(e)}
    />
  );
}

Supported platforms

The player runs on iOS, Android, Android TV and Apple TV. On tvOS you use the react-native-tvos fork of React Native, and the same podspec automatically selects TVVLCKit.

Playback controls and audio features

On top of basic play, pause and seek, the player supports media playback features your users expect on mobile:

• Background audio and OS media controls (lock screen, Control Center, Android notification), with now playing metadata for title, artist, album and artwork.
• Audio and subtitle track selection, including external subtitle files.
• An equalizer with presets and per-band gain.
• Playback speed control while keeping audio pitch.
• Hardware decoding control, including an automatic mode that enables hardware decode when available.

Solving subtitles

You can load external .srt or .vtt files at runtime with setSubtitleFile, or hide subtitles entirely with selectSubtitleTrack(-1). For per-source control, pass media options such as :sub-language=none to stop VLC from auto-selecting a subtitle track.

Streaming and network options

VLC's engine accepts libvlc media options directly. Useful examples:

• network-caching=3000 to reduce rebuffering on slow connections.
• rtsp-tcp for camera streams where UDP is blocked.
• http-user-agent when a server rejects the default user agent.
• input-repeat=-1 to loop the current media.

Upgrading from version 1.x

v2.0.0 is a breaking release. Options such as mediaOptions and hwDecoderEnabled moved into the source object, and imperative methods now go through a ref. A migration guide is available for existing users.

Resources

• Repository: https://github.com/lunarr-app/vlc-player
• Migration guide: https://github.com/lunarr-app/vlc-player/blob/main/MIGRATING_TO_V2.md
• Package: @lunarr/vlc-player

Conclusion

If your React Native app needs to play formats the system player rejects, a VLC-based player is the reliable route. v2.0.0 brings the engine up to date on the React Native New Architecture, with background audio, subtitle support, an equalizer and TV support across iOS, Android, tvOS and Android TV.