# ๐ฌ Retflix
**A self-hosted, Netflix-style streaming app for your IPTV line โ on web, mobile, and Samsung Smart TV.**
Connect your **Xtream Codes** provider or any **M3U / M3U8** playlist, and enjoy a premium streaming experience with a Netflix-grade interface. Browse & watch movies, series, and live TV on your computer, phone, or Samsung Smart TV with a native Tizen app.
> [!IMPORTANT]
> **Bring your own legal IPTV subscription.** Retflix ships with **no** content, channels, or credentials โ it's only a player for an [Xtream Codes](https://en.wikipedia.org/wiki/Xtream_Codes) line or M3U/M3U8 playlist **you** already pay for. Not affiliated with Netflix. For personal use on your own network.
---
## ๐ธ Screenshots
> Demo data โ placeholder titles & artwork, no real content.
| Home | Browse | Search |
|:---:|:---:|:---:|
|  |  |  |
---
## ๐ Table of contents
- [Features](#-features)
- [Quick start (Docker)](#-quick-start-docker)
- [Manual install](#%EF%B8%8F-manual-install-without-docker)
- [Samsung TV app](#-samsung-tv-app)
- [Multilingual metadata (TMDB)](#-multilingual-metadata-tmdb)
- [Configuration](#%EF%B8%8F-configuration)
- [How it works](#-how-it-works)
- [Project structure](#-project-structure)
- [FAQ & limitations](#-faq--limitations)
- [License](#-license)
---
## โจ Features
### Library
- **Two provider types** at setup:
- **Xtream Codes** โ server URL + username + password, validated on connect.
- **M3U / M3U8** โ any playlist URL; channels auto-categorized from group tags.
- Full catalog synced into a local **SQLite** database (web mode) or **localStorage** (TV standalone mode).
- **Two sync modes** (Xtream), both incremental and resumable:
- **Update library** โ provider details (plot, cast, director, episodes). Fast.
- **Download everything** โ adds IMDb cast photos + pre-cached artwork.
- On-disk **image cache** (posters, backdrops, episode stills, actor photos).
- **Adult content filter** โ automatically hides XXX/adult categories and content.
### Discovery
- Netflix-style **home**: hero banner (web) or quick navigation grid (TV), *Continue Watching*, *My List* (favorites), and recommendation rows.
- **Browse** movies / series / live with category picker and sorting.
- **Global search** across titles and actors, with suggestions, typo-tolerant *"did you mean"*, and TV-optimized debounced search.
- Rich **detail page** (TV) or **modal** (web): synopsis, cast with photos, year, rating, genre, director, trailer, seasons & episodes.
- **Favorites / My List** โ add titles to your personal list, persisted in localStorage.
- **Top 10** row with numbered cards for the most popular titles.
- **"NUOVO" badge** on recently added content.
### Player
- **Continuous, Netflix-style buffering**: stall watchdog with auto-recovery, transparent reconnect, next-episode prefetch, debounced spinner.
- Plays **MP4** natively; **MKV / AVI** through on-the-fly **ffmpeg โ HLS** (web) or native HLS (TV).
- **Multi-audio language switching** and **subtitles** (WebVTT, Netflix-styled).
- Hardware video encoding on macOS (`h264_videotoolbox`); `libx264` elsewhere.
- Resume playback, *Continue Watching*, auto next-episode, full keyboard/remote shortcuts.
### Samsung Smart TV App
- **Native Tizen app** (`.wgt`) โ installs from Tizen Studio, appears in the TV's app launcher.
- **Fully standalone** โ connects directly to the Xtream Codes provider like IPTV Smarters. No server required for streaming.
- **D-pad spatial navigation** โ full remote control support (arrows, OK, Back).
- **10-foot UI** โ large text (24px+), big cards, visible focus rings, designed for viewing from 5 meters.
- **Netflix-style splash screen** with animated loading bar.
- **Category picker** โ browse Film, Serie TV, Live TV with category grid selection.
- **Live TV channel list** โ text-based grid for quick channel selection.
- **Player with seek** โ skip ยฑ10s with arrows, play/pause, volume, stall watchdog with auto-reconnect.
- **Page state persistence** โ Back button always returns to where you were (scroll position + focused element).
- Compatible with **Samsung TVs 2017+** (Tizen 3.0, Chrome 47) โ all CSS/JS transpiled for legacy browsers.
### Languages
- Full **multilingual UI** โ ๐ฎ๐น Italiano ยท ๐ฌ๐ง English ยท ๐ช๐ธ Espaรฑol ยท ๐ซ๐ท Franรงais ยท ๐ฉ๐ช Deutsch ยท ๐ต๐น Portuguรชs.
- Optional **multilingual content** via [TMDB](#-multilingual-metadata-tmdb).
---
## ๐ Quick start (Docker)
```bash
git clone https://github.com//retflix.git
cd retflix
./run.sh
```
Open **http://localhost:3000**, connect your provider, and run a sync.
On a phone or TV browser, use the network URL printed by `run.sh` (e.g. `http://192.168.1.50:3000`).
```bash
docker compose up -d --build # build + start
docker compose logs -f # follow logs
docker compose down # stop
```
Your library and credentials live in `./data` on the host โ **never** baked into the image.
---
## ๐ ๏ธ Manual install (without Docker)
Requires **Node.js โฅ 18** and **ffmpeg** on your `PATH`.
```bash
git clone https://github.com//retflix.git
cd retflix
npm install
npm run build
npm start # production โ http://localhost:3000
```
Development (hot-reload):
```bash
npm run dev # or ./start.sh
```
---
## ๐บ Samsung TV App
Retflix includes a standalone Samsung Tizen app that connects directly to your IPTV provider โ no server needed for streaming.
### Prerequisites
- Samsung TV (2017 or newer, Tizen 3.0+)
- [Tizen Studio](https://developer.tizen.org/development/tizen-studio/download) installed on your computer
- TV in **Developer Mode** (Apps โ press 1-2-3-4-5 โ enable โ set your PC's IP โ restart TV)
### Build & Install
```bash
# Build the .wgt package
./build-tizen.sh
# Connect to your TV
sdb connect
# Sign the package (use your Tizen certificate profile)
tizen package -t wgt -s -- tizen-build/
# Install & launch
tizen install -n tizen-build/Retflix.wgt -t
tizen run -p sVPRCHljlj.Retlix -t
```
### Configuration
The TV app stores Xtream Codes credentials in localStorage. On first launch, configure your provider in **Settings** or pre-configure in `build-tizen.sh`:
```bash
# In build-tizen.sh, edit the provider line:
localStorage.setItem("retflix-provider", JSON.stringify({
url: "http://your-provider.com",
username: "your_username",
password: "your_password"
}))
```
### How it works on TV
```
Samsung TV (Tizen 3.0)
โโ Retflix.wgt (standalone web app)
โโ React UI (legacy ES5 bundle for Chrome 47)
โโ Xtream Codes API client (direct HTTP to provider)
โโ Native HLS player (no hls.js needed)
โโ D-pad spatial navigation engine
โโ localStorage (library cache, favorites, progress)
โ
โผ
IPTV Provider (Xtream Codes API)
โโ player_api.php โ catalog, categories, details
โโ /movie/user/pass/id.mp4 โ direct movie stream
โโ /series/user/pass/id.mp4 โ direct episode stream
โโ /live/user/pass/id.m3u8 โ direct live stream
```
No proxy, no intermediate server โ the TV connects directly to the provider like IPTV Smarters.
---
## ๐ Multilingual metadata (TMDB)
To show **plots & genres in your chosen language**, add a free [TMDB](https://www.themoviedb.org/) API key:
1. Create a free account โ **Settings โ API** โ copy the **API Key (v3 auth)**.
2. In Retflix: **Settings โ Language โ TMDB** โ paste the key โ **Save**.
3. Pick a language and open a title โ translated content is cached locally.
---
## โ๏ธ Configuration
| Variable | Default | Description |
|-----------------|-----------|---------------------------------------------------|
| `PORT` | `3000` | HTTP port |
| `HOST` | `0.0.0.0` | Bind address (default exposes it on the LAN) |
| `TMDB_API_KEY` | โ | Optional; multilingual plots/genres (or set in UI)|
The SQLite DB + image cache live in **`data/`** (gitignored). To start fresh, delete it or use **Settings โ Disconnect**.
---
## ๐ง How it works
### Web / Desktop mode
```
Xtream / M3U โโโโโโโถ Express backend โโโถ SQLite (local library + cache)
โ โ
TMDB / IMDb โโโโโโโโโโโโโโค enrichment (plots, genres, cast photos, i18n)
โ
browser โโโ React UI โโโค streams & images PROXIED through backend
(hls.js / mpegts.js) โ (credentials never reach the browser)
โโ ffmpeg โ on-the-fly HLS for MKV/AVI
```
### Samsung TV mode
```
Samsung TV โโโ Retflix.wgt โโโถ IPTV Provider (Xtream Codes)
โ โ
โโ player_api.php โโโโโโค catalog + details
โโ /movie/ โโโโโโโโโโโโโค direct MP4 stream
โโ /live/ โโโโโโโโโโโโโโค direct HLS stream
โโ localStorage โโโโโโโโ library cache + progress
```
---
## ๐ Project structure
```
server/ Express API, sync, stream proxy, M3U parser, ffmpeg, TMDB
src/ React app โ pages, components, player, i18n, TV hooks
โโ pages/
โ โโ Home.jsx Home with hero (web) or quick nav (TV)
โ โโ Browse.jsx Browse with category picker (TV) or chips (web)
โ โโ Search.jsx Search with on-screen keyboard (web) or IME (TV)
โ โโ Watch.jsx Player (web โ hls.js + mpegts.js)
โ โโ WatchTV.jsx Player (TV โ native HLS, no JS libraries)
โ โโ DetailTV.jsx Full-page detail (TV โ replaces modal)
โ โโ Settings.jsx Settings (TV has simplified standalone view)
โโ hooks/
โ โโ useTv.js TV detection, spatial navigation, back handling
โ โโ pageState.js Save/restore scroll + focus for Back navigation
โโ apiTV.js Standalone Xtream API client (runs in browser)
โโ xtreamTV.js Xtream Codes URL builders + credential storage
โโ api.js API router (server mode or standalone TV mode)
tizen/ Samsung Tizen app config + icons
build-tizen.sh Build script for the .wgt Samsung TV package
data/ SQLite DB + image cache (runtime, never committed)
Dockerfile Multi-stage build (Node + ffmpeg)
docker-compose.yml
run.sh One-command Docker launcher
start.sh Dev mode launcher
stop.sh Port cleanup
```
---
## โ FAQ & limitations
- **MKV/AVI need ffmpeg** โ included in Docker; install manually otherwise.
- **Samsung TV** requires Tizen 3.0+ (2017 models or newer) and Developer Mode for sideloading.
- **TV app is standalone** โ no server needed for streaming. The server is only needed for the web version (enrichment, transcoding, image caching).
- **Adult content** is automatically filtered from the TV app home, search, and category listings.
- **IMDb cast photos** are rate-limited; they fill in gradually.
- **Single provider, single user, no app login** โ run it on a network you trust.
- **localStorage limit** (~5MB) โ the TV caches the library in a compact array format to fit.
---
## ๐ License
[MIT](LICENSE) โ provided as-is. You are responsible for the legality of the IPTV source you connect.