Supported versions

| Platform | Version | | -------------------- | ------- | | React Native | 0.83 | | Android / Android TV | 7+ | | iOS / Apple TV | 15.1+ |

Installation

Add the package to your npm dependencies.

npm install expo-libvlc-player

Bare React Native projects

For bare React Native projects, you must ensure that you have installed and configured the expo package.

Configure for Android

No additional configuration necessary.

Configure for iOS

Run npx pod-install after installing the npm package.

Configure for TV

Set the EXPO_TV environment variable, and run prebuild to make the TV modifications to the project.

EXPO_TV=1 npx expo prebuild --clean

Configuration in app config

You can configure expo-libvlc-player using its built-in config plugin if you use config plugins in your project.

Example app.json with config plugin

{
  "expo": {
    "plugins": [
      [
        "expo-libvlc-player",
        {
          "localNetworkPermission": "Allow $(PRODUCT_NAME) to access your local network",
          "supportsPictureInPicture": true
        }
      ]
    ]
  }
}

Configurable properties

| Name | Description | Default | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | localNetworkPermission | A string to set the NSLocalNetworkUsageDescription permission message on iOS | "Allow $(PRODUCT_NAME) to access your local network" | | supportsPictureInPicture | A boolean value to enable Picture-in-Picture (PiP) on Android and iOS. If true, it adds the android:supportsPictureInPicture property on Android and the audio key to the UIBackgroundModes array in the Info.plist file on iOS. If false, it removes the property on Android and the key on iOS. When undefined, the configuration is not modified | undefined |

Usage

import { LibVlcPlayerView } from "expo-libvlc-player";

const BIG_BUCK_BUNNY =
  "https://download.blender.org/peach/bigbuckbunny_movies/big_buck_bunny_720p_h264.mov";

return <LibVlcPlayerView source={BIG_BUCK_BUNNY} />;

Trigger the local network privacy alert on iOS:

import LibVlcPlayerModule from "expo-libvlc-player";

await LibVlcPlayerModule.triggerNetworkAlert();

Check for Picture-in-Picture (PiP) support:

import LibVlcPlayerModule from "expo-libvlc-player";

LibVlcPlayerModule.isPictureInPictureSupported();

See the Example App for additional usage.

Module methods

| Method | Description | Returns | | ------------------------------- | ----------------------------------------------------------- | --------------- | | triggerNetworkAlert() | Attempts to trigger the local network privacy alert on iOS | Promise<void> | | isPictureInPictureSupported() | Checks whether the device supports Picture-in-Picture (PiP) | boolean |

View methods

| Method | Description | Returns | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------- | | play() | Starts playback of the current player | Promise<void> | | pause() | Pauses playback of the current player | Promise<void> | | stop() | Stops playback of the current player | Promise<void> | | seek(value: number, type?: "time" \| "position") | Sets the time or position of the current player. Must be a number equal or greater than 0, type defaults to "time" | Promise<void> | | record(path?: string) | Starts or stops recording the current media. Must be a valid directory path string or undefined to stop recording | Promise<void> | | snapshot(path: string) | Takes a snapshot of the current media. Must be a valid directory path string | Promise<void> | | postAction(action: number) | Posts an answer to a Dialog. Must be an integer of 1 or 2 | Promise<void> | | dismiss() | Dismisses a Dialog | Promise<void> | | startPictureInPicture() | Enters Picture-in-Picture (PiP) mode. Config plugin has to be configured for Picture-in-Picture (PiP) to work | Promise<void> | | stopPictureInPicture() | Exits Picture-in-Picture (PiP) mode on iOS | Promise<void> |

View props

The LibVlcPlayerView extends React Native ViewProps and implements the following:

| Prop | Description | Default | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ----------- | | source | Sets the source of the media to be played. Set to null to release the player | | | options | Sets the VLC options to initialize the player with. See the VLC Wiki for more | [] | | tracks | Sets the player audio, video and subtitle tracks object. See Tracks for more | undefined | | slaves | Sets the player audio and subtitle slaves array. See Slave for more | [] | | scale | Sets the player scaling factor. Must be a float equal or greater than 0 | 0 | | aspectRatio | Sets the container aspect ratio. Must be a valid ratio string, number or "auto" | undefined | | contentFit | Sets how the video should be scaled to fit in the container | "contain" | | rate | Sets the player rate. Must be a float equal or greater than 1 | 1 | | time | Sets the initial player time. Must be an integer in milliseconds | 0 | | volume | Sets the player volume. Must be an integer between 0 and 100 | 100 | | mute | Sets the player volume to 0 when true. Previous value is set when false | false | | audioMixingMode | Determines how the player will interact with other audio in the system | "auto" | | repeat | Determines whether the media should repeat once ended | false | | autoplay | Determines whether the media should autoplay once created | true | | pictureInPicture | Determines whether the player should allow Picture-in-Picture (PiP) mode | false |

Callbacks

| Prop | Description | Payload | | ------------------------- | ------------------------------------------------------------ | ----------------------------- | | onBuffering | Called after the Buffering player event | | | onPlaying | Called after the Playing player event | | | onPaused | Called after the Paused player event | | | onStopped | Called after the Stopped player event | | | onEncounteredError | Called after the EncounteredError player event | { error: string } | | onDialogDisplay | Called after a Dialog needs to be displayed | Dialog | | onTimeChanged | Called after the TimeChanged player event | { time: number } | | onPositionChanged | Called after the PositionChanged player event | { position: number } | | onESAdded | Called after the ESAdded player event | MediaTracks | | onRecordChanged | Called after the RecordChanged player event | Recording | | onSnapshotTaken | Called after a media snapshot is taken | { path: string } | | onFirstPlay | Called after the player first playing event | MediaInfo | | onForeground | Called after the player enters the foreground | | | onBackground | Called after the player enters the background | | | onPictureInPictureStart | Called after the player enters Picture-in-Picture (PiP) mode | | | onPictureInPictureStop | Called after the player exits Picture-in-Picture (PiP) mode | |

Types

Tracks

{
  audio?: number;
  video?: number;
  subtitle?: number;
}

Slave

{
  source: string | number;
  type: "audio" | "subtitle";
  selected?: boolean;
}

Dialog

{
  title: string;
  text: string;
  cancelText?: string;
  action1Text?: string;
  action2Text?: string;
}

Recording

{
  path: string | null;
  isRecording: boolean;
}

Track

{
  id: number;
  name: string;
}

MediaTracks

{
  audio: Track[];
  video: Track[];
  subtitle: Track[];
}

MediaInfo

{
  width: number;
  height: number;
  length: number;
  seekable: boolean;
}

Known issues

Black screen

On Android, the libvlcjni player detaches from the View when its surface is destroyed after switching screens.

The current workaround attaches the View once a surface is created but this causes a brief black screen.

https://code.videolan.org/videolan/vlc-android/-/issues/1495

On iOS, the VLCKit player deallocates from the UIView when closing the Picture-in-Picture (PiP) window.

The current workaround exclusively selects the current video track but this causes a brief black screen.

https://code.videolan.org/videolan/VLCKit/-/issues/743

Audio delay

On iOS, the VLCKit player experiences a small audio delay when resuming or muting media playback.

This might be related to the internal clock used by the library core causing inaccurate time values.

https://code.videolan.org/videolan/VLCKit/-/issues/233

Local network

On iOS, the VLCKit player seems to interact with the local network when playing media from external sources.

A clear message must be provided to the NSLocalNetworkUsageDescription key in the Info.plist file.

https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy

Disclaimer

This project is not affiliated with, endorsed by, or officially supported by VideoLAN. The VLC icon is trademark of VideoLAN and is used here solely to indicate compatibility with the following LibVLC bindings:

• libvlcjni for Android / Android TV
• VLCKit for iOS / Apple TV

For official VLC products and support, please visit videolan.org.

Credits

This library is inspired by existing projects such as expo-video and react-native-vlc-media-player.

Contributing

Contributions are always welcome. Please raise any issues and/or fix them by creating a pull request.