Full overhaul of the repo please see changelog

2026-10-22 09:35:11 +00:00 · 2025-09-16 18:54:12 +01:00
parent 2119398460
commit e0ad35d2b1
115 changed files with 26066 additions and 6426 deletions
@@ -1,82 +1,329 @@
-# 🍿🎥✮⋆˙ TMDB Embed API! 🍿🎥✮⋆˙
+# 🍿 TMDB Embed API

-Hello! I'm Inside4ndroid, a passionate Software Developer.
+> Modern, configurable streaming metadata + source aggregation API with a secure admin panel and multi-key TMDB rotation.

- 🐛 Bugs will be found and squashed as soon as possible please report any isues.
- 🌱 Currently in a state that works and is recieving updates.
+<p align="center">
+  <img src="https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat" />
+  <img src="https://img.shields.io/badge/Status-Active-success?style=flat" />
+  <img src="https://img.shields.io/badge/License-MIT-blue?style=flat" />
+  <img src="https://img.shields.io/badge/Version-1.0.0-informational?style=flat" />
+  <img src="https://img.shields.io/docker/pulls/inside4ndroid/tmdb-embed-api?label=Docker%20Pulls&style=flat" />
+</p>

 ---

-## ℹ️ Current Embed Providers ℹ️
+## 📸 Screenshots
+<p align="center">
+  <img src="screenshots/Screenshot 2025-09-16 174931.png" width="46%" />
+  <img src="screenshots/Screenshot 2025-09-16 175002.png" width="46%" />
+</p>
+<p align="center">
+  <img src="screenshots/Screenshot 2025-09-16 175008.png" width="46%" />
+  <img src="screenshots/Screenshot 2025-09-16 175013.png" width="46%" />
+</p>
+<p align="center">
+  <img src="screenshots/Screenshot 2025-09-16 175020.png" width="46%" />
+  <img src="screenshots/Screenshot 2025-09-16 175026.png" width="46%" />
+</p>
+<p align="center">
+  <img src="screenshots/Screenshot 2025-09-16 175033.png" width="46%" />
+  <img src="screenshots/Screenshot 2025-09-16 175040.png" width="46%" />
+</p>

-1. embedsu
-2. 2embed
-3. autoembed
-4. vidsrcsu
+---

-## 🤝 Sponsorship / Donations 🤝
+## ✨ Features
+- **Multi‑TMDB Key Rotation** – Supply multiple API keys; one is chosen randomly per request.
+- **Provider Aggregation** – Pluggable providers (Showbox, 4khdhub, MoviesMod, MP4Hydra, VidZee, Vixsrc, Xprime) with per‑provider enable toggles + default selection.
+- **Dynamic Filtering** – Minimum quality presets, custom JSON quality map, codec exclusion rules (presets + JSON).
+- **Runtime Overrides UI** – Fully interactive web admin at `/` (login protected) writing to `utils/user-config.json`.
+- **Session Auth + Rate Limiting** – Login system with brute‑force lockouts, logout, password change.
+- **Status & Health Panel** – Live metrics, provider status, endpoint list, functional provider checks.
+- **Config Propagation** – Overrides mirrored to `process.env` for legacy compatibility (no `.env` required after first save).
+- **Back‑Navigation Safe** – Cache-control + visibility/session revalidation.
+- **Extensible** – Simple provider registry pattern.

-Your sponsorship is vital in helping me achieve this mission. With your support, I can:
+---

-Dedicate more time to developing and improving my projects
-Cover costs for essential tools, services and premium hosting to run public projects
-Provide detailed documentation and support for users
-Every contribution, no matter the size, makes a significant impact.
+## 📦 Quick Start
+```bash
+# 1. Install dependencies
+npm install

-[Sponsor Me!](https://github.com/sponsors/Inside4ndroid)
+# 2. (Optional) Copy example env if you want an initial TMDB key
+cp .env.example .env   # then edit TMDB_API_KEY=

-Thank you for considering supporting my work!
+# 3. Start API (production style)
+node apiServer.js

-### ✨ Usage ✨
+# Or with automatic restarts (if you add a dev script)
+# npm run dev:api

-This is an api for id's provided at [TMDB](https://www.themoviedb.org/).
+# 4. Open the Admin UI (login page) in browser
+http://localhost:8787/

-you must use the ID from the tmdb url like this :
-
-```
-🎬 MOVIES:
-
-single provider - localhost:PORT/movie/{PROVIDER}/{TMDBID}
-all providers - localhost:PORT/movie/{TMDBID}
-
-📺 TV SHOWS:
-
-single provider - localhost:PORT/tv/{PROVIDER}/{TMDBID}?s={SEASON}&e={EPISODE}
-all providers - localhost:PORT/tv/{TMDBID}?s={SEASON}&e={EPISODE}
+# 5. Health check
+curl http://localhost:8787/api/health
 ```

-## 📋 Providers 📋
+---

-The providers are currently :
+## 🐳 Docker Usage

-```
-embedsu
-2embed
-autoembed
-vidsrcsu
+### Pull & Run (Fastest)
+If you just want to run it (no building):
+```bash
+docker pull inside4ndroid/tmdb-embed-api:latest
+docker run --name tmdb-embed-api -p 8787:8787 \ 
+  -e TMDB_API_KEY=YOUR_TMDB_KEY \
+  inside4ndroid/tmdb-embed-api:latest
 ```

-## 🚀 Deployment 🚀
+Persist overrides (Windows PowerShell example) by mounting a local file:
+```powershell
+New-Item -ItemType File -Path .\utils\user-config.json -Force | Out-Null
+docker run --name tmdb-embed-api -p 8787:8787 `
+  -e TMDB_API_KEY=YOUR_TMDB_KEY `
+  -v ${PWD}/utils/user-config.json:/app/utils/user-config.json `
+  inside4ndroid/tmdb-embed-api:latest
+```

-You can self host by doing the following :
+### Build Locally
+```bash
+docker build -t tmdb-embed-api .
+docker run --name tmdb-embed -p 8787:8787 \
+  -e TMDB_API_KEY=YOUR_TMDB_KEY \
+  -v "$(pwd)/utils/user-config.json:/app/utils/user-config.json" \
+  tmdb-embed-api
+```

-1. `git clone https://github.com/Inside4ndroid/TMDB-Embed-API.git`
-2. `cd TMDB-Embed-API`
-3. `rename .env_example to .env`
-4. `edit .env and insert your preferred port and your tmdb api key`  
-5. `npm install`
-6. `npm run start`
+After first login + save, the UI writes overrides into the mounted `user-config.json` so they persist across container restarts.

-## Contribute
+### docker-compose
+An example `docker-compose.yml` is included. Start with:
+```bash
+docker compose up -d --build
+```
+Environment variables can be supplied via a `.env` file in the same directory (Compose automatically loads it). Example `.env`:
+```
+TMDB_API_KEY=first_key
+FEBBOX_COOKIES=cookie1,cookie2
+```

-If you know how to code then please dont hesitate to conribute to this project by forking and making pull requests with your new providers or edits etc.
+To stop & remove:
+```bash
+docker compose down
+```

-## <span style="color:red">⚠️ WARNING ⚠️</span>
+### Switching to Multiple TMDB Keys
+Either set `TMDB_API_KEYS` to a JSON array string:
+```bash
+docker run -p 8787:8787 \
+  -e TMDB_API_KEYS='["KEY1","KEY2","KEY3"]' \
+  tmdb-embed-api
+```
+or add / remove keys inside the Admin UI (Keys panel) and save.

-Using this without a proxy may lead to your server ip being banned there are 3 ways to get around this :
+### Key Environment Variables
+| Variable | Purpose | Notes |
+|----------|---------|-------|
+| `API_PORT` | Port the server listens on | Defaults to 8787 |
+| `TMDB_API_KEY` | Single TMDB key (legacy) | Use if you only have one key |
+| `TMDB_API_KEYS` | JSON array of keys | Overrides single key when present |
+| `FEBBOX_COOKIES` | Comma separated FebBox cookies | Enables Showbox provider immediately |
+| `PASSWORD_HASH` | Pre-seed admin password hash | Optional (UI can set) |
+| `ADMIN_USERNAME` | Override default username | Default: `admin` |

-1. Use a proxy : [Find One Here](https://github.com/search?q=m3u8+proxy&type=repositories).
-2. Get a server with rotating ip addresses or dynamic ip adresses and use the ips at random.
-3. use a cloudflare proxy worker.
+If both `TMDB_API_KEY` and `TMDB_API_KEYS` are provided, rotation uses the array. Clearing the array in the UI also clears the legacy key.

-Some providers need cloudflare resolving and i am working on a method for this. but using correct headers etc in your network request when playing the media urls should suffice for now.
+---
+
+### Updating the Image
+```bash
+docker compose pull   # if using an external registry (future)
+docker compose up -d --build
+```
+
+### Healthcheck
+Container health relies on `GET /api/health`. If you disable or modify that route, adjust the Dockerfile / compose healthcheck accordingly.
+
+---
+
+## �🔐 Authentication
+The root (`/`) serves the login page. After successful login a session cookie (`session`) is issued (HttpOnly; 12h lifetime). All admin pages (e.g. `config.html`) require an active session.
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/auth/login` | POST | Authenticate (JSON: `{ username, password }`) |
+| `/auth/logout` | POST | Destroy session |
+| `/auth/session` | GET | Check session status |
+| `/auth/change-password` | POST | Update password (requires session) |
+
+Repeated failed logins trigger exponential lockouts (Retry-After header emitted).
+
+---
+
+## 🛠 Configuration Model
+All runtime state collapses into a *merged* object displayed in the UI (Live Config panel). Source order:
+1. Initial environment variables / optional `.env`
+2. JSON overrides: `utils/user-config.json`
+
+Saving in the UI writes only changed keys. Setting a field to empty removes the override (reverting to env/default). Removing all TMDB keys (and saving) clears `tmdbApiKeys` and the legacy `tmdbApiKey`.
+
+**Override File:** `utils/user-config.json`
+```json
+{
+  "defaultProviders": ["showbox","4khdhub"],
+  "tmdbApiKeys": ["KEY_A","KEY_B"],
+  "enableShowboxProvider": true
+}
+```
+
+---
+
+## 🎛 Admin UI Sections
+| Panel | Summary |
+|-------|---------|
+| Core | Port, default providers, default region |
+| Quality / Filters | Min quality presets & codec exclusion JSON |
+| Keys | Add/remove TMDB API keys (rotated randomly) |
+| FebBox / PStream | Manage FebBox cookies powering Showbox provider |
+| Advanced | Provider toggles, cache & validation flags, proxy paths |
+| Server Status | Live metrics, provider functional checks |
+| Live Config | View merged + override JSON snapshots |
+
+Session is revalidated on visibility and back/forward navigation to prevent stale access.
+
+---
+
+## 🔌 Providers
+Current built‑in providers:
+- `showbox`
+- `4khdhub`
+- `moviesmod`
+- `mp4hydra`
+- `vidzee`
+- `vixsrc`
+- `xprime`
+
+You can enable/disable and mark defaults via the Provider Matrix in the UI. If **no defaults** are selected, all enabled providers participate in aggregation.
+
+### Adding a New Provider (Outline)
+1. Create `providers/myprovider.js` exporting an async fetch function (see existing files for patterns).
+2. Lazy‑load it in `providers/registry.js` similar to others.
+3. Add a config flag (`enableMyproviderProvider`) if you want toggle support.
+4. Update the provider matrix arrays in `public/index.js`.
+
+---
+
+## 📡 Key Endpoints
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/health` | Basic heartbeat |
+| `GET /api/metrics` | Runtime counters & summary |
+| `GET /api/status` | Metrics + providers + endpoints list |
+| `GET /api/providers` | Enabled providers summary |
+| `GET /api/providers/:name` | Single provider status |
+| `GET /api/streams/:type/:tmdbId` | Aggregate streams (`type` = movie|series) |
+| `GET /api/streams/:provider/:type/:tmdbId` | Provider-specific streams |
+| `GET /api/config` | `{ merged, override }` |
+| `POST /api/config` | Apply override patch |
+
+Aggregate endpoint auto-resolves IMDb when needed and merges provider output before filtering.
+
+---
+
+## 🧪 Stream Object Shape (Typical)
+```json
+{
+  "title": "Example Title",
+  "url": "https://...",
+  "quality": "1080p",
+  "provider": "showbox",
+  "size": null,
+  "languages": ["en"],
+  "subtitles": [],
+  "codecs": ["H264"],
+  "headers": { "Referer": "..." }
+}
+```
+
+Filtering passes through `applyFilters` to enforce min quality + codec exclusions.
+
+---
+
+## 🧩 Quality & Codec Filtering
+- Presets: `all`, `480p`, `720p`, `1080p`, `1440p`, `2160p`.
+- Custom quality JSON example:
+```json
+{ "default": "900p", "showbox": "1080p" }
+```
+- Codec exclusion JSON example:
+```json
+{ "excludeDV": true, "excludeHDR": false }
+```
+
+---
+
+## 🔐 Security Notes
+- Admin UI requires login; session cookie is HttpOnly.
+- Cache-control headers disable storing sensitive pages.
+- Login is rate limited with escalating lockouts.
+- Password change endpoint enforces minimum length.
+
+---
+
+## 🚀 Deployment Tips
+| Aspect | Recommendation |
+|--------|---------------|
+| Node Version | 18+ LTS |
+| Reverse Proxy | Terminate TLS (e.g., Nginx) and forward to API port |
+| Persistent Config | Mount / persist `utils/user-config.json` |
+| Logs | Pipe stdout to centralized logger |
+| Scaling | Use a single instance unless providers are CPU bound |
+
+For ephemeral platforms (e.g., Vercel) note that some providers use temporary directories; avoid enabling disk-heavy cache directories.
+
+---
+
+## 💡 Troubleshooting
+| Symptom | Cause / Fix |
+|---------|------------|
+| No streams from Showbox | Missing FebBox cookies |
+| TMDB quota issues | Add more keys under Keys panel |
+| Provider missing in matrix | Ensure its enable flag exists & UI updated |
+| Empty merged config after restart | `user-config.json` deleted or unreadable |
+| Streams low quality | Adjust min quality preset or custom JSON |
+
+---
+
+## 🤝 Contributing
+PRs welcome. Keep changes focused and avoid unrelated formatting churn. For new providers include:
+- A short rationale
+- Retry / timeout safeguards
+- Respect for existing filtering structure
+
+---
+
+## ❤️ Sponsorship
+If this project helps you, consider sponsoring to support continued development & maintenance:
+
+➡️ **GitHub Sponsors:** https://github.com/sponsors/Inside4ndroid
+
+Every contribution accelerates feature delivery & sustainability.
+
+---
+
+## 📜 License
+MIT. See `LICENSE`.
+
+---
+
+## 🙏 Acknowledgements
+Inspired by community scraping/stream aggregation efforts. Credits also to the original NuvioStreamsAddon work for earlier concepts.
+
+---
+
+> *Happy streaming & hacking!* ✨
+
+---