Skip to content

README.md

Latest commit

 

History

History
314 lines (209 loc) · 6.68 KB

README.md

File metadata and controls

314 lines (209 loc) · 6.68 KB

🎬 Vorlaxen's Web Player

Enterprise-grade, modular, event-driven video player engine built with TypeScript + React + Vite.

Designed to compete with production-level platforms such as Netflix, YouTube, Disney+, and Udemy — with a clean architecture, plugin extensibility, and long-term scalability in mind.

🚀 Vision

V-Player is built with a simple philosophy:

Keep the core minimal. Everything else is a plugin.

The system is engineered to deliver:

  • High performance playback
  • Seamless quality & audio switching
  • Strong type-safety with full TypeScript coverage
  • Event-driven extensibility
  • Future-ready architecture (WebCodecs, AV1, adaptive pipelines)

🧠 Architecture Overview

The project follows a Core + Plugin Architecture.

Player Core
 ├── EventBus (Strict Typed)
 ├── Engine Layer (Media + Audio)
 ├── Plugin Manager
 └── Public API

Plugins
 ├── Format Plugins (MP4, HLS, DASH)
 ├── Audio Processing
 ├── Metadata Providers
 ├── Ads / Analytics
 └── Debug / DevTools

Core Principles

  • Core never depends on plugins.
  • Plugins extend behavior via lifecycle hooks.
  • All communication is event-driven.
  • Every event is strictly typed.

⚙️ Technology Stack

  • React (SPA Architecture)
  • TypeScript (Strict Mode)
  • Vite (Bundler)
  • Web Audio API
  • Modular Plugin System

🧩 Plugin System

All plugins must extend the abstract BasePlugin class.

Lifecycle

  • init(core)
  • destroy()
  • onEvent() (optional)

Plugins are:

  • Initialized by the core
  • Event-driven
  • Isolated from each other
  • Fully typed

Example Plugin Categories

Plugin Purpose
MP4Plugin Native MP4 playback
HLSPlugin Adaptive streaming via HLS
MetadataPlugin Platform-specific metadata integration
AudioPlugin Advanced audio pipeline & processing layer
SleepTimerPlugin Playback auto-stop scheduling system
ADSPlugin Advertisement system
IframeBridgePlugin Cross-window / embedded player communication

🔊 AudioPlugin

AudioPlugin replaces the old AudioBoost-specific design and provides a more extensible audio processing layer.

Capabilities:

  • Volume normalization
  • Dynamic gain control
  • Custom audio graph injection
  • Toggleable enhancement pipeline
  • Future support for spatial audio or advanced DSP modules

Built on top of the Web Audio API with a controlled and isolated audio graph.

The design allows stacking multiple audio processors internally without leaking implementation details to the core.

⏳ SleepTimerPlugin

The SleepTimerPlugin enables timed playback shutdown.

Features:

  • Set timer (e.g., 10 / 30 / 60 minutes)
  • Emits scheduled stop events
  • Graceful pause instead of hard stop
  • Fully event-driven

Ideal for long-form content platforms (courses, podcasts, series playback).

The timer logic is isolated and does not directly control media — it only emits typed events.

🪟 IframeBridgePlugin

The IframeBridgePlugin enables secure communication between:

  • Embedded players
  • Parent windows
  • Cross-origin iframe integrations

Built on top of postMessage with strict message typing.

Capabilities:

  • Parent → Player control (play, pause, seek)
  • Player → Parent analytics events
  • Strict origin validation
  • Typed message contracts

This makes the engine embeddable in LMS systems, SaaS dashboards, or third-party platforms without modifying the core.

🔁 Event-Driven System

All interactions flow through a strictly typed EventBus.

Example Events

  • play
  • pause
  • seek
  • qualityChange
  • audioChange
  • metadataLoaded
  • sleepTimerTriggered
  • iframeMessageReceived

Each event:

  • Must exist in PlayerEventMapType
  • Cannot be emitted if not typed
  • Is fully compile-time validated

This prevents runtime inconsistencies and ensures predictable plugin behavior.

🎥 Multi-Format Support

Supported formats via plugins:

  • MP4
  • HLS
  • DASH (planned via plugin abstraction)

The core interacts only through the plugin interface — never directly with format libraries.

🔄 Seamless Switching

Quality Switching

  • No playback interruption
  • Buffered data preserved
  • Adaptive switching supported

Audio Track / Dubbing Switching

  • No playback pause
  • Event-driven change
  • Independent from quality pipeline

Both systems are designed to be reusable across plugins.

🛡 Stability & Performance

  • Minimal core footprint
  • Strict listener cleanup
  • Memory leak prevention strategy
  • Defensive event handling
  • Controlled plugin lifecycle

Designed for long-running sessions.

🧪 Development Mode

UI is intentionally minimal.

The project includes:

  • Basic DOM test controls
  • Simple test buttons
  • Debug-ready structure

The architecture is fully UI-ready but UI implementation is intentionally separated from core logic.

📁 Project Structure

src/
 ├── core/
 │   ├── engine/
 │   ├── events/
 │   └── constants/
 │
 ├── plugins/
 │   ├── MP4Plugin/
 │   ├── HLSPlugin/
 │   ├── MetadataPlugin/
 │   ├── AudioPlugin/
 │   ├── SleepTimerPlugin/
 │   └── IframeBridgePlugin/
 │
 ├── components/
 ├── hooks/
 ├── types/
 └── utils/

Clear separation between:

  • Engine logic
  • Plugin layer
  • UI layer
  • Context layer

🧱 Type System

Strict TypeScript usage across the project:

  • PlayerEventMapType
  • PluginEventMap
  • EngineTypes
  • Plugin lifecycle types

No untyped event emission allowed.

🔮 Future Roadmap

  • WebCodecs integration
  • AV1 support
  • MediaCapabilities API integration
  • Analytics plugin
  • DRM abstraction layer
  • Adaptive bitrate intelligence plugin

The architecture is intentionally future-proof.

🛠 Installation

pnpm install
pnpm dev

📄 License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0).

🛡️ Commercial Use is Strictly Prohibited. If you intend to use this engine for a commercial product, please contact the author for a separate commercial license.

View License Summary

✨ Final Note

V-Player is not a UI experiment. It is an engine-first, architecture-driven system designed for production-scale streaming platforms.

The UI is replaceable. The core is permanent.