---
title: NovaStream
emoji: 🚀
colorFrom: purple
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
short_description: A powerful, offline-capable browser media player with cinema
---

<div align="center">

  <h1>NovaStream</h1>

  <p align="center">
    <strong>A powerful, offline-capable browser media player with cinematic glassmorphism design.</strong>
  </p>

  <p align="center">
    Stream direct URLs, play large local MKV files with advanced HEVC hardware decoding, and convert subtitles on the fly with a sleek, theater-grade interface.
  </p>

  <div align="center">
    <img src="https://img.shields.io/badge/Node.js-Express-68a063?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js" />
    <img src="https://img.shields.io/badge/React-Vite-61dafb?style=for-the-badge&logo=react&logoColor=black" alt="React" />
    <img src="https://img.shields.io/badge/License-GPL%203.0-blue?style=for-the-badge&logo=open-source-initiative&logoColor=white" alt="GPL 3.0" />
    <img src="https://img.shields.io/badge/FFmpeg-Transmuxing-ff4f00?style=for-the-badge&logo=ffmpeg&logoColor=white" alt="FFmpeg" />
  </div>
</div>

<hr />

## ✨ Features

- **Direct MKV Proxy Streaming**: Seamlessly stream remote MKV files right within the browser without having to download them completely.
- **Zero-Latency HEVC/H.264 Handling**: Native support for high-efficiency video coding. Hardware decoding for crisp, lag-free playback.
- **Offline Capability**: Directly stream large local files from your server or through the browser sandbox.
- **On-the-fly Transmuxing**: Real-time conversion of MKV containers using FFmpeg backend integration. Supports real-time HEVC to H.264 transcoding fallback.
- **Subtitle Parsing & Track Switching**: Automatically converts standard SRT subtitle files to WebVTT on the fly. Switch between multiple embedded audio tracks effortlessly.
- **Cinematic Theater Mode**: An immersive, auto-hiding UI wrapped in a premium Glassmorphism design language.
- **Real-Time Telemetry**: Monitor bandwidth speed and buffer health instantly with the built-in speedometer.

---

## 🛠️ Tech Stack & Architecture

- **Frontend**: React 19, Vite, Lucide Icons. Pure custom CSS for dynamic cinematic and glassmorphic aesthetics.
- **Backend**: Node.js, Express.js. Handles URL probing, CORS bypassing, direct stream proxying, and spawns FFmpeg processes for real-time transmuxing.
- **Transmuxer Engine**: FFmpeg is utilized to map video and audio streams seamlessly to browser-compatible fragmented MP4.

Check out our [STRUCTURE.md](STRUCTURE.md) for a detailed breakdown of the codebase and file structure.

---

## 🚀 Deployment & Installation

NovaStream can be deployed natively using Node.js or easily containerized with Docker.

### Prerequisites
- Node.js (v18+)
- FFmpeg installed and available in the system PATH.

### Standard Node.js Setup

1. **Clone the repository:**
   ```bash
   git clone https://github.com/urstark/NovaStream.git
   cd NovaStream
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```
   *(Note: For development, use `npm run dev` to start concurrently)*

3. **Build the Frontend:**
   ```bash
   npm run build
   ```

4. **Start the Server:**
   ```bash
   npm start
   ```

The application will be running on port `7860` (or `process.env.PORT`).

### Docker Setup

```bash
docker build -t novastream .
docker run -p 7860:7860 novastream
```

---

## 👨‍💻 Developer Credits

- **Developer:** [urstarkz](https://github.com/urstark)
- **Website:** [urstark.is-a.dev](https://urstark.is-a.dev)
- **Telegram:** [t.me/urstarkz](https://t.me/urstarkz)
- **Instagram:** [@urstarkz](https://instagram.com/urstarkz)

---

## ⚖️ License

NovaStream is open-source software licensed under the **GPL-3.0 License**. See the [LICENSE](LICENSE) file for more details.