Electron Native Player

High-performance cross-platform YUV video player for Electron with zero-copy SharedArrayBuffer architecture.

✨ Features

• 🚀 Zero-Copy Architecture: Direct memory access via SharedArrayBuffer
• 🌍 Cross-Platform: Works on Windows, Linux, and macOS
• ⚡ High Performance: Ring buffer with atomic operations for lock-free synchronization
• 🔒 Thread-Safe: Multi-threaded playback without blocking the main thread
• 🎥 WebCodecs Integration: Native VideoFrame support for modern browsers
• 📦 Easy to Use: Simple JavaScript API with TypeScript support

📦 Installation

npm install electron-native-player

Prerequisites

• Node.js >= 14.0.0
• C++17 compatible compiler
• node-gyp build tools

Platform-Specific Requirements:

Windows:

• Visual Studio 2017 or later

Linux:

sudo apt-get install build-essential

macOS:

xcode-select --install

🚀 Quick Start

const player = require('electron-native-player')

// Create a ring buffer for zero-copy data transfer
const sab = player.createYuvRingBuffer(1920, 1080, 4)

// Start playing a YUV420p video file
player.startYuvPlayback(sab, 1920, 1080, 30, '/path/to/video.yuv')

// Stop playback
player.stopPlayback()

📖 API Documentation

createYuvRingBuffer(width, height, ringSize?)

Creates a SharedArrayBuffer ring buffer for YUV playback.

Parameters:

• width (number): Video width in pixels
• height (number): Video height in pixels
• ringSize (number, optional): Ring buffer size, default is 4

Returns: SharedArrayBuffer

Example:

const sab = player.createYuvRingBuffer(1920, 1080, 4)
console.log(sab.byteLength) // Total buffer size

startYuvPlayback(buffer, width, height, fps, yuvPath)

Starts YUV video playback.

Parameters:

• buffer (SharedArrayBuffer | Uint8Array): The ring buffer
• width (number): Video width in pixels
• height (number): Video height in pixels
• fps (number): Frames per second
• yuvPath (string): Path to YUV420p video file

Example:

player.startYuvPlayback(sab, 1920, 1080, 30, './video.yuv')

stopPlayback()

Stops video playback.

Example:

player.stopPlayback()

🎯 Complete Example

See the example directory for a complete Electron application demonstrating:

• SharedArrayBuffer setup
• WebCodecs integration
• Web Worker usage
• Cross-origin isolation configuration

To run the example:

cd example
npm install
npm start

🏗️ Architecture

Zero-Copy Design

┌─────────────────┐
│  YUV File       │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────┐
│  C++ Thread (Native)                │
│  - Reads YUV file                   │
│  - Writes to SharedArrayBuffer      │
└────────┬────────────────────────────┘
         │ Direct Memory Access
         ▼
┌─────────────────────────────────────┐
│  SharedArrayBuffer (Ring Buffer)    │
│  [Control][Frame0][Frame1][Frame2]  │
└────────┬────────────────────────────┘
         │ Zero Copy
         ▼
┌─────────────────────────────────────┐
│  Web Worker (JavaScript)            │
│  - Reads frames                     │
│  - Creates VideoFrame               │
└────────┬────────────────────────────┘
         │
         ▼
┌─────────────────┐
│  Render         │
└─────────────────┘

Ring Buffer Structure

Offset 0-63:     Control Structure (64 bytes)
  - writeIndex:    atomic<uint32_t>
  - readIndex:     atomic<uint32_t>
  - frameSequence: atomic<uint64_t>
  - frameReady[4]: atomic<int32_t>[4]
  - width, height, fps

Offset 64+:      Frame Slots
  - Frame 0
  - Frame 1
  - Frame 2
  - Frame 3

🚀 Performance

• Zero memory copy between C++ and JavaScript
• Lock-free synchronization using atomic operations
• Off-thread rendering via Web Workers
• Supports 4K video at 60fps on modern hardware

🌐 Cross-Platform

Fully tested on:

• ✅ Windows 10/11 (x64)
• ✅ Ubuntu 20.04+ (x64, ARM64)
• ✅ macOS 11+ (x64, Apple Silicon)

See CROSS_PLATFORM.md for build instructions.

📝 TypeScript Support

TypeScript definitions are included:

import player from 'electron-native-player'

const sab: SharedArrayBuffer = player.createYuvRingBuffer(1920, 1080)
player.startYuvPlayback(sab, 1920, 1080, 30, './video.yuv')

🔧 Development

Building from Source

npm install
npm run rebuild

Running Tests

npm test

Cleaning Build Artifacts

npm run clean

📄 License

MIT © ykzou

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📚 Resources

• Example Application
• Cross-Platform Build Guide
• Changelog
• GitHub Repository

⭐ Show Your Support

Give a ⭐️ if this project helped you!