STRUCTURE.md

🗂️ Project Structure

NovaStream is built on a hybrid architecture, combining a highly interactive React frontend with a robust Node.js streaming proxy backend.

Below is an overview of the core file structure and components:

NovaStream/
├── server.cjs                 # Core Node.js Express server
│                              # Handles /api/metadata, /api/stream, FFmpeg transmuxing, and file probing
├── package.json               # Project dependencies and npm scripts
├── vite.config.js             # Vite configuration for building the React frontend
├── eslint.config.js           # Linter configuration
├── index.html                 # Entry point for the frontend application
├── Dockerfile                 # Configuration for containerizing the application
├── LICENSE                    # GPL-3.0 Open Source License
├── README.md                  # Project overview, features, and setup guide
│
├── public/                    # Static assets
│
└── src/                       # React Frontend Source Code
    ├── App.jsx                # Main Application component (UI, Player Logic, State Management)
    ├── App.css                # Glassmorphism & Cinematic styling, animations
    └── main.jsx               # React DOM rendering entry point

⚙️ Backend Architecture (server.cjs)

The backend is responsible for bypassing cross-origin restrictions (CORS) and handling unsupported browser video formats (like MKV) through real-time processing.

Key Endpoints:

• GET /api/metadata: Probes the provided video URL using HTTP HEAD requests or ffprobe. Detects file size, duration, container type, and extracts internal audio track metadata.
• GET /api/stream: The core streaming engine.
  • If the file is a standard MP4/WebM, it acts as a direct byte-range proxy.
  • If the file is an MKV or requires transcoding, it spawns an ffmpeg child process. It pipes fragmented MP4 directly to the Express response, supporting real-time seeking, audio track switching, and optional HEVC-to-H.264 transcoding.

🎨 Frontend Architecture (src/App.jsx)

The frontend is a monolithic yet organized React component that manages the entire lifecycle of the media player.

Key Capabilities:

• State Management: Handles player states (Play/Pause, Volume, Fullscreen), stream metadata, bookmarks, history, and buffering telemetry.
• Subtitle Processing: The srtToVtt utility function converts uploaded SRT subtitle files into WebVTT format entirely on the client side.
• Speedometer & Telemetry: Uses video buffering API (video.buffered) to calculate download speeds and buffer health in real-time.
• Sandbox Player: Utilizes URL.createObjectURL to allow users to play large local files securely without uploading them to the server.