🎬 Unified Headless Video Playback Core

Cross-platform video playback logic engine - Same code, same behavior, all platforms.

🎯 What is This?

A Rust library that manages video playback logic (state management, quality decisions, events) without performing video decoding or rendering. It works seamlessly with native video players on each platform (ExoPlayer on Android, AVPlayer on iOS, video_player on Flutter, react-native-video on React Native, HTML5 Video on Web).

Core Principle: Core makes decisions → Platform adapters execute them.

Why Use This?

Traditional video playback solutions require maintaining separate codebases for each platform, leading to:

• ❌ Inconsistent behavior across platforms
• ❌ Different bugs on different platforms
• ❌ High maintenance costs
• ❌ Duplicated logic

Unified Headless Video Playback Core solves this by providing:

• ✅ One Core for all platforms
• ✅ Consistent behavior everywhere
• ✅ Single source of truth for playback logic
• ✅ Reduced maintenance - fix bugs once, benefit everywhere

✨ Key Features

Format Support (9 Formats)

• Container Formats: MP4, WebM, MKV, FLV
• Adaptive Streaming: HLS, DASH, Smooth Streaming
• Streaming Protocols: RTMP, RTSP

Platform Support (5 Platforms)

• Web - WASM bindings for HTML5 Video
• Android - Kotlin/JNI bindings for ExoPlayer
• iOS - Swift bindings for AVPlayer
• Flutter - Dart/FFI bindings for video_player
• React Native - TypeScript bindings for react-native-video

Core Capabilities

• ✅ State Machine - Deterministic playback state management
• ✅ Adaptive Bitrate (ABR) - Built-in ABR engine with 3 strategies
• ✅ Playback Speed - Control speed from 0.25x to 4.0x
• ✅ Chapters - Full chapter management & navigation
• ✅ Subtitle Detection - Automatic format detection (SRT, VTT, TTML)
• ✅ Dynamic Quality - Request quality targets with downscaling support
• ✅ Live Streaming - Full support for live & VOD streams
• ✅ Plugin System - Extensible for analytics, ads, and more
• ✅ DRM Policy - DRM policy handling and decisions
• ✅ Enhanced Metadata Extraction - Advanced parsing for all formats

🚀 Quick Start

⚡ Fast Install? See QUICK_INSTALL.md for one-command installation on any platform.

Installation

Option 1: From Git (Development/Unpublished Versions)

For development or unpublished versions, install from Git:

[dependencies]
unified-headless-video-core = { git = "https://github.com/4iShmmri/unified-headless-video-core", tag = "v0.3.0" }

Or use the latest commit:

[dependencies]
unified-headless-video-core = { git = "https://github.com/4iShmmri/unified-headless-video-core" }

Option 2: From crates.io (Recommended)

Install directly from crates.io:

[dependencies]
unified-headless-video-core = "0.3.0"

Or use the latest version:

[dependencies]
unified-headless-video-core = "0.3"

Option 3: Build from Source

Clone the repository and add as a local dependency:

git clone https://github.com/4iShmmri/unified-headless-video-core.git
cd unified-headless-video-core

Then in your Cargo.toml:

[dependencies]
unified-headless-video-core = { path = "../unified-headless-video-core" }

Platform-Specific Installation

For platform-specific integrations (Android, iOS, Flutter, React Native, Web), see:

• Android Installation
• iOS Installation
• Flutter Installation
• React Native Installation
• Web/WASM Installation

Basic Usage (Rust)

use core::core::*;

fn main() -> Result<()> {
    // Create player
    let mut player = CorePlayer::new(Config::default())?;
    
    // Load video
    player.load("https://example.com/video.mp4")?;
    
    // Play
    player.play()?;
    
    // Control playback
    player.set_speed(1.5)?;  // 1.5x speed
    player.seek(30.0)?;      // Seek to 30 seconds
    
    // Handle events
    player.on_event(Box::new(|event| {
        match event {
            Event::Play => println!("Playing"),
            Event::QualityChanged(q) => println!("Quality: {}", q),
            Event::Error(msg) => eprintln!("Error: {}", msg),
            _ => {}
        }
    }));
    
    Ok(())
}

Platform Adapters

See platform-specific documentation:

• Android
• iOS
• Flutter
• React Native
• Web/WASM

💡 Why Choose This Over Other Solutions?

Comparison with Platform-Specific Players

❌ Without Core (Traditional Approach)

Android (ExoPlayer):

// Different code for each platform
val exoPlayer = ExoPlayer.Builder(context).build()
exoPlayer.setMediaItem(MediaItem.fromUri(url))
exoPlayer.prepare()
exoPlayer.play()

// Different ABR logic
// Different state management
// Different event handling

iOS (AVPlayer):

// Completely different code
let player = AVPlayer(url: URL(string: url)!)
player.play()

// Different ABR logic
// Different state management  
// Different event handling

Problems:

• 🔴 Different behavior on each platform
• 🔴 Bugs appear on one platform but not others
• 🔴 Need to maintain 5+ codebases
• 🔴 Inconsistent user experience

✅ With Core (Unified Approach)

All Platforms:

// Same code everywhere!
let mut player = CorePlayer::new(Config::default())?;
player.load(url)?;
player.play()?;

// Same ABR logic everywhere
// Same state management everywhere
// Same event handling everywhere

Benefits:

• ✅ Consistent behavior across all platforms
• ✅ Single codebase for playback logic
• ✅ Fix bugs once, benefit everywhere
• ✅ Unified user experience

Comparison Table

📚 Documentation

• API Reference - Complete API documentation
• Platform Adapter Interface - How to integrate with platform adapters
• Troubleshooting - Common issues and solutions

🎮 Examples

See the examples directory for complete examples:

• basic_usage.rs - Basic playback
• webm_example.rs - WebM format with enhanced metadata
• mkv_example.rs - MKV format with subtitle support
• flv_example.rs - FLV format with metadata extraction
• rtmp_example.rs - RTMP streaming
• rtsp_example.rs - RTSP streaming
• smooth_streaming_example.rs - Smooth Streaming with fragment URLs
• advanced_usage.rs - Advanced features

🧪 Testing

The project includes comprehensive testing:

• 52+ Unit Tests - Core functionality
• Integration Tests - Format support and enhanced features
• Stress Tests - Performance under load
• Performance Benchmarks - Parser and operation benchmarks

Run tests:

cargo test
cargo test -- --ignored  # Run stress tests
cargo bench              # Run benchmarks

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│  (Your App: Android/iOS/Flutter/React Native/Web)           │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│              Platform Adapter Layer                         │
│  (Thin Wrappers: Kotlin/Swift/Dart/TypeScript/WASM)        │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                  FFI Bridge Layer                           │
│  (C API / WASM API)                                          │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                  Rust Core Layer                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ State Machine│  │  ABR Engine  │  │   Parsers    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Event System │  │ Plugin System│  │ DRM Handler  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│              Native Player Layer                             │
│  (ExoPlayer / AVPlayer / video_player / HTML5 Video)        │
└─────────────────────────────────────────────────────────────┘

🔧 Building

Prerequisites

• Rust 1.70+
• Cargo

Build Commands

cargo build            # Debug build
cargo build --release  # Release build
cargo test            # Run tests
cargo fmt             # Format code
cargo clippy          # Lint code

Platform-Specific Builds

See platform-specific READMEs for build instructions:

• Android
• iOS
• Flutter

📊 Project Status

Status: ✅ Production Ready
Version: 0.2.0
Test Coverage: 52+ tests

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

🤝 Contributing

Contributions are welcome! Please see our contributing guidelines.

🔗 Links

• GitHub: https://github.com/4iShmmri/unified-headless-video-core
• Issues: https://github.com/4iShmmri/unified-headless-video-core/issues
• Documentation: See docs/ directory

Built with ❤️ using Rust