react-native-video-desktop

A video component for React Native desktop platforms (macOS, Windows, Linux) with a react-native-video compatible API.

Overview

react-native-video-desktop provides native video playback capabilities for React Native desktop applications. It's designed to be a drop-in replacement for react-native-video on desktop platforms, offering a familiar API while leveraging native video frameworks.

Platform Support

Platform	Status	Framework
macOS	✅ Implemented	AVKit
Windows	🚧 Planned	Media Foundation
Linux	🚧 Planned	GStreamer

Features

• ✅ Native video playback using platform-specific frameworks
• ✅ Compatible with react-native-video API
• ✅ Support for local and remote video files
• ✅ Playback controls (play, pause, seek)
• ✅ Video styling (resize modes)
• ✅ Event callbacks (onLoad, onProgress, onEnd, etc.)
• ✅ TypeScript support

Installation

npm install @jdboivin/react-native-video-desktop
# or
yarn add @jdboivin/react-native-video-desktop
# or
pnpm add @jdboivin/react-native-video-desktop

macOS

After installing the package, you need to install the CocoaPods dependencies:

cd macos && pod install

Then rebuild your app:

npm run macos
# or
react-native run-macos

Windows

Coming soon

Linux

Coming soon

Usage

import React from "react"
import { View, StyleSheet } from "react-native"
import Video from "@jdboivin/react-native-video-desktop"

function App() {
  return (
    <View style={styles.container}>
      <Video
        source={{ uri: "https://example.com/video.mp4" }}
        style={styles.video}
        controls={true}
        resizeMode="contain"
        repeat={true}
        onLoad={(data) => console.log("Video loaded", data)}
        onProgress={(data) => console.log("Progress", data)}
        onEnd={() => console.log("Video ended")}
      />
    </View>
  )
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  video: {
    width: "100%",
    height: 400,
  },
})

export default App

Props

Video Source

source: {
  uri: string;           // URL or local file path
  headers?: object;      // HTTP headers (for remote videos)
}

Playback Control

Prop	Type	Default	Description
paused	boolean	false	Controls whether the media is paused
repeat	boolean	false	Repeat the video when it ends
rate	number	1.0	Playback rate (0.5 = half speed, 2.0 = double speed)
volume	number	1.0	Volume level (0.0 to 1.0)
muted	boolean	false	Mutes the audio
controls	boolean	false	Show native playback controls
seek	number	-	Seek to specified time in seconds

Display

Prop	Type	Default	Description
resizeMode	'contain' | 'cover' | 'stretch'	'contain'	How the video fits in the container
style	ViewStyle	-	Style for the video container
poster	string	-	Image to show before video loads

Events

Callback	Description
onLoad(data)	Called when video loads successfully
onProgress(data)	Called periodically during playback
onEnd()	Called when video reaches the end
onError(error)	Called when an error occurs
onBuffer(isBuffering)	Called when buffering state changes
onReadyForDisplay()	Called when video is ready to be displayed

Event Data Structures

onLoad:

{
  duration: number // Video duration in seconds
  currentTime: number // Current playback position
  naturalSize: {
    width: number
    height: number
  }
}

onProgress:

{
  currentTime: number // Current playback position
  playableDuration: number
  seekableDuration: number
}

Sample App

A complete sample macOS app is available in the sample directory. This demonstrates all features and serves as a reference implementation.

To run the sample app:

cd sample
npm install
npm run pods:macos
npm run macos

The sample app includes:

• Video playback with event logging
• All event handlers demonstrated
• Seek functionality
• Production build scripts (unsigned and signed)

See sample/README.md for more details.

API Compatibility

This library aims to maintain API compatibility with react-native-video. However, some features may not be available on all platforms. The following table shows the current implementation status:

Feature	macOS	Windows	Linux
Basic playback	✅	🚧	🚧
Controls	✅	🚧	🚧
Seeking	✅	🚧	🚧
Volume control	✅	🚧	🚧
Playback rate	✅	🚧	🚧
Resize modes	✅	🚧	🚧
Subtitles	⏳	🚧	🚧
DRM	⏳	🚧	🚧
Picture-in-Picture	⏳	🚧	🚧

Legend: ✅ Implemented | 🚧 Planned | ⏳ Under consideration

Building and Code Signing

Building the Sample App

The sample app uses Fastlane for building and code signing:

Unsigned Build (for testing):

cd sample
bundle install
bundle exec fastlane mac test_build

Signed Build with Fastlane Match (for distribution):

cd sample
bundle install
bundle exec fastlane mac release

Code Signing with Fastlane Match

This project uses Fastlane Match for code signing, which:

• ✅ Stores certificates in a git repository
• ✅ Syncs across team members and CI/CD
• ✅ Eliminates manual certificate management

See docs/CODE_SIGNING_FASTLANE.md for complete setup instructions.

CI/CD

The GitHub Actions workflow automatically builds and signs the sample app on every release:

1. Set up Fastlane Match following docs/CODE_SIGNING_FASTLANE.md
2. Configure GitHub secrets (Match repo URL, SSH key, passwords)
3. Push to main - workflow automatically uses signed builds if Match is configured

Development

Prerequisites

• Node.js 18+
• React Native development environment set up for your target platform
• For macOS: Xcode and CocoaPods

Building

git clone https://github.com/starburst997/react-native-video-desktop.git
cd react-native-video-desktop
npm install
npm run prepare

Running the Example

cd example
npm install
npm run macos

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

See CONTRIBUTING.md for more details.

Help Wanted

We're especially looking for contributors to help with:

• Windows implementation using Media Foundation
• Linux implementation using GStreamer
• Additional features (subtitles, DRM, etc.)
• Bug fixes and testing

License

MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by react-native-video
• Built for the react-native-macos community

Related Projects

• react-native-video - The original React Native video component for iOS and Android
• react-native-macos - React Native for macOS
• react-native-windows - React Native for Windows

Support

• Issue Tracker
• Discussions