78 lines
3.8 KiB
Markdown
78 lines
3.8 KiB
Markdown
# Spectra — A YouTube Suggest Engine
|
|
|
|
> Better YouTube recommendations: zero repeats, steerable topics & creators, recency-biased suggestions, and a preserved watch list.
|
|
|
|
|
|
|
|
## 💡 Elevator Pitch
|
|
YouTube does a terrible job of suggesting videos based on what it knows about you. Spectra creates a balanced series of suggested videos with **no repeats** over topics and creators you actually care about. Timing-wise, suggestions tend toward newer releases. You can click to add items to a **preserved Watch List** that persists across suggestion regenerations, and steer the algorithm with **Thumbs Up**, **Thumbs Down**, or **Big Nope** exclusions.
|
|
|
|
---
|
|
|
|
## ⚡ Core Features
|
|
|
|
- **Strict Zero-Repeat Guarantee**: Spectra tracks every suggested video ID in persistent SQLite storage (`seen_videos`). Once a video has been suggested in any batch, it will never repeat unless you explicitly choose to reset seen history.
|
|
- **Steerable Algorithm**:
|
|
- **👍 Thumbs Up**: Increases affinity weight for the creator (+affinity) and topic.
|
|
- **👎 Thumbs Down**: Reduces affinity weight for the creator and topic.
|
|
- **🚫 Big Nope**: Instantly removes video, blocks the creator/channel permanently, and excludes them from all future queries. (Includes 5-second undo toast).
|
|
- **Timing Tendency (Recency Bias)**:
|
|
- Exponential decay multiplier prioritizing newer videos:
|
|
- ⚡ **Ultra Fresh**: Past 48 hours
|
|
- 📅 **Recent**: Past 30 days (default)
|
|
- 🌐 **Broad**: All-time high-affinity catalog
|
|
- **Preserved Watch List**:
|
|
- One-click "Watch Later" saves videos into a persistent list that remains completely preserved even when suggestion batches are regenerated.
|
|
- Track watched vs unwatched status, launch embedded player or open directly in YouTube.
|
|
- **Series of Topics & People**:
|
|
- Curated starter streams matching maker passions: Vintage Screenprint & Apparel, Specialty Espresso, ESP32 & E-Ink telemetry, Self-Hosted Homelabs, Alpine Skiing, Lateral Thinking, Vinyl Audio, and Maker Fast Builds.
|
|
- Add custom topics or YouTube creator handles on the fly.
|
|
- **Embedded Theater Player**:
|
|
- Clean preview player using privacy-enhanced `youtube-nocookie.com`.
|
|
- Full feedback steering controls inside the player modal.
|
|
|
|
---
|
|
|
|
## 🏗️ Architecture & Tech Stack
|
|
|
|
- **Runtime**: Node.js 22 LTS (Alpine)
|
|
- **Database**: Native `node:sqlite` (zero npm C++ compilation overhead, blazing fast synchronous queries)
|
|
- **YouTube Retrieval**: Live YouTube search scraper (`ytInitialData`), YouTube Channel RSS feeds (`/feeds/videos.xml?channel_id=...`), and offline seed catalog fallback
|
|
- **Frontend**: Pure modern ES modules, CSS Grid, Glassmorphism, and responsive design (no heavy client bundlers needed)
|
|
- **Deployment**: Docker Compose on `vloser` homelab, Traefik reverse proxy, Homepage dashboard integration
|
|
|
|
---
|
|
|
|
## 🧪 Automated Verification Suite
|
|
|
|
Run the unit and integration test suite:
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
Verifies:
|
|
1. Healthcheck endpoint and database readiness
|
|
2. Starter topics and creators initialization
|
|
3. Zero repeats across successive suggestion generation batches
|
|
4. Watch list persistence across batch regenerations
|
|
5. Algorithm steering: Thumbs Up / Thumbs Down topic weight updates
|
|
6. Big Nope permanent channel and video blacklisting
|
|
7. Seen history reset and telemetry reporting
|
|
|
|
---
|
|
|
|
## 🚀 Homelab Deployment (vloser.us)
|
|
|
|
### 1. Repository
|
|
Hosted on Gitea: `https://gitea.vloser.us/chrisf/spectra`
|
|
|
|
### 2. Traefik Dynamic Routing
|
|
Configured in `/home/chrisf/docker/appdata/traefik3/rules/app-spectra-a-youtube-suggest-engine.yml`:
|
|
- Public URL: `https://spectra-a-youtube-suggest-engine.vloser.us`
|
|
- API Passthrough: `chain-no-auth`
|
|
- Web UI: `chain-oauth` (Authentik SSO)
|
|
|
|
### 3. Homepage Entry
|
|
Configured in `/home/chrisf/docker/appdata/homepage/services.yaml` under Media & Discovery with custom SVG icon `/icons/spectra.svg`.
|