LoopTV
Product: tv.significanthobbies.com
TV-like app that plays random YouTube videos from curated channels, nonstop. Pick a station, hit play, and lean back.
Zero API keys needed for playback or forks using the checked-in catalog. Maintained catalog refreshes use a cache-first YouTube Data API path with yt-dlp fallback; free-AI tagging runs only for new, untagged videos.
Fork it, edit stations.json with your own YouTube channels, and deploy. That's it.
Playback qualification — 2026-09-07
Station pages now omit the portfolio strip so it cannot cover the full-viewport
player. Browsing pages retain it. Next pressed while the YouTube iframe starts
now loads the latest selection once ready, keeping the video and title aligned.
The delayed-player browser regression reproduces
the old failure and passes with the fix.
pnpm quality passes (233 tests). Built-browser checks at 1280×800, 390×844 and
844×390 found no horizontal overflow, all controls in bounds and working search
open/close. A fresh desktop public video after immediate Next showed a matching
iframe/control title and advancing playback; screenshot.
This is a representative local check, not qualification of all upstream videos.
The repair was deployed through Actions 34125220328 and passed hosted desktop/mobile acceptance.
See the hosted receipt for actual
YouTube playback, ready/startup Next, search, controls and separately controlled
embed-error checks. Issue #51
is complete. The product remains inactive; catalog-wide availability, long-session
playback and physical-device behavior are outside this representative check.
Deployment & External Services
| Concern | Service |
|---|
| Hosting | Cloudflare Pages (looptv, tv.significanthobbies.com) — static Astro output, deployed via wrangler pages deploy |
| Database | None — static public/catalog.json served at runtime; watched history in browser localStorage |
| Analytics | PostHog via local posthog-js wrapper |
| AI / tagging | Free-AI LLM gateway in CI (multi-model fan-out) for untagged videos; local HuggingFace NER retained as an offline fallback, not run in CI |
| CI/CD | GitHub Actions — Pages deploys plus cache-first catalog refreshes on the 1st and 15th |
Stats
- 16 stations, 122 YouTube channels, 8,760 currently shipped videos (see
public/catalog-summary.json for the live count)
- Topic tagging via a free-AI LLM gateway (multi-model fan-out) in CI; HuggingFace
dslim/bert-base-NER retained as a local offline fallback only
- Quality filters: per-source minDuration/maxDuration, global 10K views minimum, per-source top-view percentile cap + 200-video default cap
- Watched tracking with localStorage
Configuration
stations.json is the single config file. Each station groups one or more YouTube channels:
{
"id": "comedy",
"name": "Comedy",
"description": "Stand-up and sketches",
"sources": [
{ "name": "Comedy Central", "handle": "@ComedyCentral", "minDuration": 60, "maxDuration": 1800 }
]
}
Setup
pnpm install
pnpm dev
Build Catalog
For a reliable refresh, set YOUTUBE_API_KEY. Without it, the fetcher falls back to yt-dlp:
brew install yt-dlp # or pip install yt-dlp
bash scripts/fetch-sources.sh
bash scripts/build-catalog.sh --process-only
Incremental AI tagging runs automatically in GitHub Actions only when new videos need tags. Local NER remains available:
pip install -r requirements-ner.txt
python3 scripts/extract-tags.py
How It Works
stations.json <- Add YouTube channels here
|
fetch-sources.sh <- recent cache, then bounded Data API fetch; yt-dlp fallback
|
process-catalog.mjs <- Merges with existing catalog, preserves existing tags for known videos
|
tag-videos.mjs <- free-AI LLM gateway tags only new/untagged videos in CI
catalog.json <- Committed to repo, served as static JSON
|
Astro + React islands <- Picks random videos, plays via YouTube IFrame API
Scripts
| Script | Description |
|---|
scripts/build-catalog.sh | Process cached sources into the static catalog |
scripts/fetch-sources.sh | Cache-first Data API fetch with yt-dlp fallback |
scripts/process-catalog.mjs | Merge raw JSONL into catalog.json, preserve existing tags |
scripts/tag-videos.mjs | Free-AI LLM gateway topic tagging for untagged videos (CI tagger) |
scripts/extract-tags.py | Local HuggingFace NER tagging fallback (not run in CI) |
scripts/fetch-all-sources.sh | Compatibility wrapper for fetching all sources |
Controls
| Key | Action |
|---|
| Space | Play / Pause |
| N / Right | Next random video |
| P / Left | Previous video |
| M | Mute / Unmute |
| F | Fullscreen |
| W | Hide watched videos |
| / | Search |
| 1-9 | Jump to station by number |
| Esc | Close search |
Playback edge cases
- Embed errors 101 / 150. When a channel disables embedding for a
specific video (geo-block, copyright claim, owner setting), the YouTube
IFrame Player fires
onError with code 101 or 150. Player.tsx treats
both as auto-skip: the video is added to a session skip set and the next
random pick fires immediately. There's no user-visible error and no
toast — by design, so the "TV channel" feel never breaks.
- No /catalog.json. Catalog fetches retry twice with backoff before
giving up. If they still fail, the landing page renders an offline
fallback banner above the channel grid (sample channels stay visible
because
stations.json is bundled) with a Retry button that re-runs the
fetch without a page reload. Dev builds show the build-catalog hint
instead.
Local stats
watched.ts keeps everything client-side in localStorage:
looptv_watched — set of video IDs seen ≥ 50% through.looptv_stats — counts by station + source, total seconds watched.looptv_blocked_sources — sources you opted out of.looptv_watch_later — bookmarked video IDs.looptv_smart_mix_profile — Smart Mix preference weights.looptv_prefs — default station, autoplay/mute on load, hide-watched toggle.
Clearing site data wipes all of it; nothing leaves the browser.
GitHub Actions
The source workflow runs on the 1st and 15th. Complete source caches younger than 13 days make zero YouTube requests. Stale or missing sources scan at most 250 recent uploads, stop when known IDs are reached, request video metadata in batches of 50, and hard-stop at 20 requests per source. The chained build audits coverage and replacement churn before calling AI, tags only untagged additions, retries only still-pending tags once, and commits only a passing catalog.
For an occasional complete quality rebaseline, pnpm audit:catalog:full scans full upload histories at five requests per second with a 4,500-request global ceiling and per-source checkpoints. It is never scheduled. The July 12 baseline used 3,467 requests for all 122 sources; an immediate rerun used zero. See docs/operations/catalog-quality-audit.md.
Deployment
Deployed on Cloudflare Pages as a static site: tv.significanthobbies.com.
pnpm build
wrangler pages deploy dist --project-name=looptv
Stack
- Astro static pages + React islands + Tailwind CSS v4
- YouTube IFrame Player API (free, no key)
- YouTube Data API for maintained catalog refreshes; yt-dlp fallback
- Free-AI LLM gateway (multi-model fan-out) for CI topic tagging; HuggingFace Transformers (
dslim/bert-base-NER) retained as a local offline fallback
License
MIT
Active AI Task Log
This section is maintained by the SaaS Maker Active-AI product/design loop so future agents do not reopen duplicate UI tasks.
- Business lane: P2 Watch / maintenance
- Rule: do not create another broad "improve the UI" task unless the acceptance criteria differ materially from the tasks listed here.
- Source of truth for task status: SaaS Maker task board. README entries are durable context only.
| Task | Status | Priority | Last known note |
|---|
4a5a6c8c [fleet-smoke] looptv/web React hydration error | done | medium | 2026-05-25 18:55:41 |
fcdbf330 looptv: add clear offline catalog fallback | done | low | 2026-05-26 — landing-page banner with sample channels + Retry when /catalog.json fetch fails |
