MSTREAM

A Modern, Fast, and Fluid Cinema Streaming Experience

Explore Live Demo »
Key Features • Architecture • Getting Started • Deployment • Ad-Free Setup • Documentation

📽️ Overview

MSTREAM is an open-source, cinema-grade movie and TV show streaming web application powered by The Movie Database (TMDB) API and modern React 19. Designed with an ultra-clean OLED Cinema Dark aesthetic, MSTREAM delivers instantaneous catalog browsing, zero-lag page transitions, multi-provider playback options, and an account-free persistent library that stays in sync across your browser tabs.

Built specifically for high-speed delivery, it deploys seamlessly to Cloudflare Pages with an edge caching proxy and full Progressive Web App (PWA) offline precaching.

Note

Ad Disclosure & Self-Hosting: The official hosted demo at https://mstream.eu.cc includes an ad-network popunder script in index.html to help offset domain and hosting infrastructure costs. If you are self-hosting or deploying your own instance, you can make MSTREAM completely ad-free simply by deleting this script from index.html (see Running an Ad-Free Self-Hosted Instance). Please note that external, third-party video iframe embeds may still serve their own player ads, so an ad-blocking browser (like Brave) or extension (such as uBlock Origin) is strongly recommended for video streaming.

✨ Key Features

🎬 Cinema-Grade Interface: Immersive OLED dark theme (#07070a), glassmorphic overlays, fluid hover micro-interactions, and responsive layout perfected for both desktop monitors and mobile touchscreens.
💾 Account-Free Persistent Library:
- Save movies and TV shows to your personal library with one click.
- Zero registration or login required — persists automatically in localStorage.
- Live Cross-Tab Sync: Add a title in one tab, and all other open tabs reflect the change instantly via storage event synchronization.
- Dedicated /library view with instant search filtering, category tabs, and live navbar badges.
⚡ Multi-Tiered Performance Caching:
- Tier 1 (Memory): 0ms instantaneous lookup for catalog lists, genres, and page transitions.
- Tier 2 (sessionStorage): Keeps loaded content instant across browser refreshes.
- In-Flight Deduplication: Simultaneous components requesting the same TMDB endpoint share a single network Promise.
- Cloudflare Edge Cache: Edge proxy (functions/api/[[path]].js) caches upstream TMDB JSON responses with X-Cache-Status headers.
🛡️ Client Rate Limiting & Debounce:
- Built-in token-bucket algorithm (max 12 req/sec) with automatic exponential backoff on 429 responses.
- 280ms search query debouncing prevents unnecessary API spam while typing.
📺 Multi-Server Streaming Player:
- 7+ independent embed streaming servers with quick-switching failover.
- Interactive season and episode pickers for TV series.
- Clean cinema playback mode and sandbox security controls.
📱 Installable Progressive Web App (PWA):
- Installable on iOS, Android, macOS, and Windows.
- Workbox service worker precaching for static assets and offline shell loading.
🔍 Advanced Discovery & Filtering:
- Filter by release year, genre, certification, sort order, and keyword search.
- Dynamic segmented switch for "This Week" vs. "Today" trending items.

🏗️ System Architecture

flowchart TD
    subgraph Client["MSTREAM Client (Browser)"]
        UI["React 19 UI Components<br/>(Home, Catalog, Watch, Library)"]
        Context["LibraryContext & useTMDB"]
        MemoryCache[("Tier 1: Memory Cache<br/>(0ms In-Memory Map)")]
        SessionCache[("Tier 2: sessionStorage<br/>(TTL: 5m - 24h)")]
        LocalStore[("localStorage<br/>(Library & Session ID)")]
        RateLimiter["Token-Bucket Rate Limiter<br/>(12 req/s + Backoff)"]
    end

    subgraph Edge["Cloudflare Edge Network"]
        CFProxy["Cloudflare Pages Function<br/>(/api/[[path]])"]
        EdgeCache[("Tier 3: Cloudflare Cache API<br/>(1h Edge TTL)")]
    end

    subgraph Upstream["Upstream APIs & Streams"]
        TMDB["The Movie Database (TMDB) API"]
        Streams["Multi-Server Video Embeds"]
    end

    UI --> Context
    Context --> MemoryCache
    MemoryCache -- "Cache Miss" --> SessionCache
    SessionCache -- "Cache Miss" --> RateLimiter
    Context <--> LocalStore

    RateLimiter --> CFProxy
    CFProxy --> EdgeCache
    EdgeCache -- "Edge Miss" --> TMDB
    UI -. "Stream Selection" .-> Streams

🛠️ Technology Stack

Layer	Technologies
Frontend Framework	React 19, React DOM 19
Routing	React Router v7
Build Tool & Bundler	Vite 7
Package Manager	pnpm
Edge & Hosting	Cloudflare Pages, Wrangler
PWA & Offline	vite-plugin-pwa, Workbox
Styling & Design	Modern CSS3 Variables, Glassmorphism, Responsive Grid/Flexbox
Data Source	The Movie Database (TMDB) API v3

🚀 Getting Started

Prerequisites

Node.js (version 18.0.0 or higher)
pnpm (version 9.x or higher)
A free API Read Access Token from The Movie Database (TMDB)

1. Clone the Repository

git clone https://github.com/cd-Crypton/mstream.git
cd mstream

2. Install Dependencies

Always use pnpm for package installation:

pnpm install

3. Configure Environment Variables

Copy the sample environment file to .env:

cp .env.example .env

Open .env and fill in your TMDB Read Access Token:

# TMDB API Read Access Token (from https://www.themoviedb.org/settings/api)
VITE_TMDB_READ_ACCESS_TOKEN=your_tmdb_read_access_token_here

# TMDB Base URL and Image CDN Endpoints
VITE_TMDB_BASE_URL=https://api.themoviedb.org/3
VITE_BACKDROP_URL=https://image.tmdb.org/t/p/w500
VITE_POSTER_URL=https://image.tmdb.org/t/p/w1280

4. Start the Local Development Server

pnpm run dev

Open http://localhost:5173 in your browser to start exploring.

📜 Available Scripts

All scripts must be executed using pnpm:

Command	Description
`pnpm run dev`	Starts the Vite development server with Hot Module Replacement (HMR).
`pnpm run build`	Compiles production bundle to `/dist` and generates the PWA service worker.
`pnpm run preview`	Builds the project and starts a local Cloudflare Pages runtime with Wrangler.
`pnpm run deploy`	Builds and deploys the project directly to Cloudflare Pages via Wrangler.
`pnpm run lint`	Runs ESLint to verify code quality and style.
`pnpm run format:check`	Checks source code formatting with Prettier.
`pnpm run format:fix`	Automatically formats all JS, JSX, and CSS files with Prettier.

☁️ Deployment

Option 1: Cloudflare Pages (Git Integration — Recommended)

Push your code or fork this repository to GitHub/GitLab.
Log into the Cloudflare Dashboard and navigate to Workers & Pages > Create Application > Pages > Connect to Git.
Select the mstream repository.
Configure your build settings:
- Framework preset: None
- Build command: pnpm run build
- Build output directory: dist
- Root directory: / (or left blank)
Under Environment variables, add:
- VITE_TMDB_READ_ACCESS_TOKEN: (Your TMDB Read Access Token)
- VITE_TMDB_BASE_URL: https://api.themoviedb.org/3
- VITE_BACKDROP_URL: https://image.tmdb.org/t/p/w500
- VITE_POSTER_URL: https://image.tmdb.org/t/p/w1280
Click Save and Deploy. Cloudflare Pages will automatically execute the edge worker in functions/api/[[path]].js to proxy and cache TMDB requests.

Option 2: CLI Deployment with Wrangler

# Authenticate with Cloudflare
pnpm wrangler login

# Build and deploy
pnpm run deploy

🚫 Running an Ad-Free Self-Hosted Instance

The public hosted demo instance includes an ad script in index.html to help support server and domain expenses. If you are deploying or self-hosting MSTREAM yourself, you can run a completely clean, ad-free application by simply removing the following script block from index.html (lines ~263–311):

    <script type="text/javascript" data-cfasync="false">
      /*<![CDATA[/* */
      (function () {
        var g = window,
          h = "e94f3803a2dc20c3edf2e73823934889",
          f = [
            ["siteId", 824 - 860 * 253 - 930 - 6 + 5502765],
            ["minBid", 0],
            ["popundersPerIP", "0"],
            ["delayBetween", 0],
            ["default", false],
            ["defaultPerDay", 0],
            ["topmostLayer", "auto"],
          ],
          l = [
            "d3d3LmludGVsbGlwb3B1cC5jb20vYk9yZ0NoYXJ0Lm1pbi5jc3M=",
            "ZDNtcjd5MTU0ZDJxZzUuY2xvdWRmcm9udC5uZXQvd3V4a1ZBL3dqcy5jb29raWUubWluLmpz",
          ],
          i = -1,
          z,
          e,
          r = function () {
            clearTimeout(e);
            i++;
            if (l[i] && !(1815583359000 < new Date().getTime() && 1 < i)) {
              z = g.document.createElement("script");
              z.type = "text/javascript";
              z.async = !0;
              var d = g.document.getElementsByTagName("script")[0];
              z.src = "https://" + atob(l[i]);
              z.crossOrigin = "anonymous";
              z.onerror = r;
              z.onload = function () {
                clearTimeout(e);
                g[h.slice(0, 16) + h.slice(0, 16)] || r();
              };
              e = setTimeout(r, 5e3);
              d.parentNode.insertBefore(z, d);
            }
          };
        if (!g[h]) {
          try {
            Object.freeze((g[h] = f));
          } catch (e) {}
          r();
        }
      })();
      /*]]>/* */
    </script>

Tip

Deleting this block removes all website popunder and display ads. However, third-party video iframe embeds (hosted by separate external streaming providers) may still inject their own player ads. For the cleanest viewing experience, we recommend pairing your browser with Brave Browser or the uBlock Origin extension.

📂 Project Structure

mstream/
├── .agents/                 # AI Assistant skills & agent toolkits
├── docs/                    # Architectural & in-depth technical documentation
│   └── ARCHITECTURE.md      # Tiered cache, rate limiting, and session design
├── functions/
│   └── api/
│       └── [[path]].js      # Cloudflare Pages edge proxy with Cache API
├── public/                  # Static assets, web manifest, and logos
├── src/
│   ├── assets/              # Branding images and icons
│   ├── components/          # Reusable UI components
│   │   ├── BannerSlider.jsx # Hero carousel with video backdrop
│   │   ├── Icons.jsx        # Lightweight inline SVG icon set
│   │   ├── Modal.jsx        # Item detail modal dialog
│   │   ├── MovieCard.jsx    # Poster card with bookmark & hover states
│   │   ├── MovieRow.jsx     # Horizontal/grid category row
│   │   ├── Navbar.jsx       # Responsive navigation with live Library counter
│   │   └── SearchModal.jsx  # Fullscreen search modal
│   ├── context/
│   │   └── LibraryContext.jsx # Reactive library state with cross-tab sync
│   ├── hooks/
│   │   └── useTMDB.js       # TMDB API hook with deduplication & caching
│   ├── pages/               # Main route views
│   │   ├── Home.jsx         # Trending hero, segmented window toggle
│   │   ├── Movies.jsx       # Filterable movies catalog
│   │   ├── TVShows.jsx      # Filterable TV shows catalog
│   │   ├── Popular.jsx      # Popular titles catalog
│   │   ├── Library.jsx      # Personal saved titles with instant filter
│   │   └── Watch.jsx        # Multi-server streaming player & episodes
│   ├── services/            # Core business logic & performance services
│   │   ├── apiCache.js      # Memory + sessionStorage multi-tier cache
│   │   ├── rateLimiter.js   # Token bucket limiter & exponential backoff
│   │   └── sessionManager.js# Anonymous device ID & preference manager
│   ├── styles/              # Global cinema styles & variables
│   │   ├── design-tokens.css# Colors, spacing, radii, blur tokens
│   │   ├── components.css   # Reusable component classes
│   │   └── pages.css        # Page layout styles
│   ├── App.jsx              # Main routing & provider composition
│   └── main.jsx             # React DOM entry point & PWA registration
├── index.html               # HTML entry with metadata & SEO tags
├── package.json             # Scripts & dependencies
├── vite.config.js           # Vite configuration with PWA plugin
└── wrangler.jsonc           # Cloudflare Pages configuration

📚 Additional Documentation

System Architecture & Caching Deep Dive: Comprehensive breakdown of the caching tiers, token-bucket rate limiter, cross-tab synchronization, and edge worker implementation.
Contributing Guide: Standards for PRs, conventional commits, and code formatting.

🤝 Contributing

Contributions are welcomed! Whether it is a bug fix, new server integration, or UI polish:

Fork the repository.
Create your feature branch (git checkout -b feat/amazing-feature).
Commit your changes using Conventional Commits (git commit -m 'feat: add amazing feature').
Ensure code adheres to standards:
```
pnpm run lint
pnpm run format:check
```
Push to your branch (git push origin feat/amazing-feature).
Open a Pull Request.

⚖️ License & Disclaimer

This project is licensed under the MIT License.

Disclaimer: MSTREAM does not host, store, or stream any media files directly on its servers. All streaming links and metadata are retrieved via third-party iframe embeds and public APIs (such as The Movie Database). MSTREAM operates solely as an open-source indexing client.

Navigation Menu

Repository navigation

About

Repository files navigation

MSTREAM

📽️ Overview

✨ Key Features

🏗️ System Architecture

🛠️ Technology Stack

🚀 Getting Started

Prerequisites

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Start the Local Development Server

📜 Available Scripts

☁️ Deployment

Option 1: Cloudflare Pages (Git Integration — Recommended)

Option 2: CLI Deployment with Wrangler

🚫 Running an Ad-Free Self-Hosted Instance

📂 Project Structure

📚 Additional Documentation

🤝 Contributing

⚖️ License & Disclaimer

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
docs		docs
functions/api		functions/api
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
index.html		index.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
vite.config.js		vite.config.js
wrangler.jsonc		wrangler.jsonc

Latest commit

History

Folders and files

Repository files navigation

MSTREAM

📽️ Overview

✨ Key Features

🏗️ System Architecture

🛠️ Technology Stack

🚀 Getting Started

Prerequisites

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Start the Local Development Server

📜 Available Scripts

☁️ Deployment

Option 1: Cloudflare Pages (Git Integration — Recommended)

Option 2: CLI Deployment with Wrangler

🚫 Running an Ad-Free Self-Hosted Instance

📂 Project Structure

📚 Additional Documentation

🤝 Contributing

⚖️ License & Disclaimer

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages