Spaces:
Running
Running
| # 🗂️ 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: | |
| ```text | |
| 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. | |