# Spectra — A YouTube Suggest Engine

> Better YouTube recommendations: zero repeats, steerable topics & creators, recency-biased suggestions, and a preserved watch list.

![Spectra UI](public/icon.svg)

## 💡 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`.