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:

npm test

Verifies:

Healthcheck endpoint and database readiness
Starter topics and creators initialization
Zero repeats across successive suggestion generation batches
Watch list persistence across batch regenerations
Algorithm steering: Thumbs Up / Thumbs Down topic weight updates
Big Nope permanent channel and video blacklisting
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.