High-performance cross-platform YUV video player for Electron with zero-copy SharedArrayBuffer
npm install electron-native-playerbash
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
``