Youtube feed declutter

YouTube Feed Declutter

Overview

One YouTube account with years of mixed subscriptions has a noisy recommendation feed. Fix: build separate single-topic channels (YouTube brand accounts under one Google login), each with its own curated subscriptions and watch history, so each feed stays on-topic.

This skill bundles a small Python CLI (scripts/yt_segmenter) that does the automatable parts — resolving channel names → exact channels, batch-subscribing via the official API, and generating a ranked watch-guide to seed the algorithm. One install drives many channels via a profile env var.

When to use

• "My YouTube feed is a mess / too random / mixes work and entertainment."
• "I want a clean channel just for <topic>."
• Migrating a curated subset of subscriptions onto a fresh channel.

Not for: boosting view counts, automating other people's accounts, or anything at scale — this is personal, single-account curation only.

Two hard facts that shape everything

1. The YouTube Data API can write subscriptions but cannot watch videos or read the recommendation feed (no "mark watched" endpoint; activities?home=true is deprecated). So subscriptions go through the clean API; seeding the feed needs real watching → the optional browser auto-watcher (watch), which is TOS-sensitive and opt-in only.
2. The only manual, human-gated steps are account stuff: creating each brand channel and the OAuth consent (picking the right channel). Never automate logins, passwords, or account creation — hand those to the user.

Prerequisites (one-time, ~15 min)

Google Cloud OAuth client + a brand channel. Full click-by-click walkthrough: see references/SETUP.md (covers the org_internal fix and the client-secret gotcha).

Install

cd scripts
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
playwright install chromium      # only needed for the optional `watch` step

Workflow

Pipeline: setup → auth → resolve → subscribe → seed → watch (status anytime). Resume-safe.

python -m yt_segmenter setup       # checklist + readiness
python -m yt_segmenter auth        # OAuth; USER picks the target channel on the consent screen
python -m yt_segmenter resolve     # seed names → exact channels (edit seeds/<profile>.txt first)
python -m yt_segmenter subscribe   # quota preview, then batch-subscribe (resumable)
python -m yt_segmenter seed        # writes a ranked watch-guide (JSON + markdown)
python -m yt_segmenter watch       # OPTIONAL browser auto-watcher, behind a TOS prompt

Multiple channels (profiles)

YT_SEG_PROFILE isolates each channel's state, seeds, and output. Unset = the film profile.

YT_SEG_PROFILE=study python -m yt_segmenter auth      # study channel, isolated state
YT_SEG_PROFILE=study python -m yt_segmenter subscribe

Recipe: add a new channel

1. User creates the brand channel in YouTube (Settings → "Add or manage your channel(s)" → Create).
2. Write seeds/<profile>.txt as Display Name | @handle-or-UCid lines (see seeds/example.txt).
3. YT_SEG_PROFILE=<profile> python -m yt_segmenter auth — user picks that channel + Allow.
4. resolve, then subscribe, then seed. (Optional) watch.

Tip — finding channels to migrate: the API only sees the logged-in channel's subscriptions. To read a user's full personal subscription list, open youtube.com/feed/channels in their browser and read the DOM (the page loads all subs at once), then curate from there.

Auto-watcher — TOS gate

watch is opt-in, behind a typed "I understand". It drives a real browser playing videos in the user's own logged-in session (no stealth, no scraping) — but YouTube's Terms discourage automated interaction. Keep it gated and honest; treat it as experimental / at-your-own-risk. Watching even the top 1–2 videos per channel by hand seeds the feed with zero TOS exposure.

Gotchas

• Error 403: org_internal at auth → the OAuth consent screen is set to "Internal". Personal Gmail needs External audience + yourself added as a Test user.
• Client secret only shows at creation in Google's console. If the download misbehaves, copy the Client ID + secret from the creation dialog and build ~/.yt_segmenter/config.json by hand (a desktop-app secret is a public client per RFC 8252).
• Occasional channel-name rejections on creation — pick a slight variant.

What's in this skill

• scripts/yt_segmenter/ — the CLI package · scripts/requirements.txt — deps
• scripts/seeds/example.txt — sample seed file (copy to seeds/<profile>.txt)
• references/SETUP.md — Google Cloud + brand-channel setup walkthrough