Electron Native Player

![Platform]()

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

``bash
npm install electron-native-player
`

$3

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

#### Platform-Specific Requirements:

Windows:
- Visual Studio 2017 or later

Linux:
`bash
sudo apt-get install build-essential
`

macOS:
`bash
xcode-select --install
`

🚀 Quick Start

`javascript
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

$3

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:
`javascript
const sab = player.createYuvRingBuffer(1920, 1080, 4)
console.log(sab.byteLength) // Total buffer size
`

$3

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:
`javascript
player.startYuvPlayback(sab, 1920, 1080, 30, './video.yuv')
`

$3

Stops video playback.

Example:
`javascript
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:
`bash
cd example
npm install
npm start
`

🏗️ Architecture

$3

`
┌─────────────────┐
│ 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 │
└─────────────────┘
`

$3

`
Offset 0-63: Control Structure (64 bytes)
- writeIndex: atomic
- readIndex: atomic
- frameSequence: atomic
- frameReady[4]: atomic[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:

`typescript
import player from 'electron-native-player'

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

🔧 Development

$3

`bash
npm install
npm run rebuild
`

$3

`bash
npm test
`

$3

`bash
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!