cto-legends · module overview · studio · MIT
legends-youtube: YouTube Data API v3, Analytics v2 & Studio Packaging CLI
Operate YouTube channels over Data API v3 and Analytics API v2 with ETag-guarded lossless metadata updates, zero-quota public readbacks, Perfect Video Score idea radar, Shorts Related-video guards, Studio chapter and quiz validators, and an 18-file Empire knowledge pack.
GitHub Repository (https://github.com/avalonreset/legends-youtube)
Improvised agent scripts and generic YouTube wrappers break production channels in predictable ways: calling PUT /youtube/v3/videos?part=snippet without merging existing snippet fields wipes your description, tags, and language settings; calling search.list to list a channel's videos burns 100 quota units per page and hits the 2026-06-01 granular cap of 100 calls per day; and unguarded upload scripts risk publishing unreviewed drafts publicly.
legends-youtube gives your coding agent a zero-dependency Python 3.11+ standard-library CLI to operate, audit, and grow YouTube channels safely. It inventories channels via the uploads playlist for 2 quota units per 50 videos, calculates daily write waves via quota-plan before any batch, verifies live public video metadata for 0 quota units and 0 credentials via public-readback, and locks metadata updates behind SHA-256 plan hashes, If-Match ETag concurrency headers, full snippet field preservation merges, pre-write rollback snapshots, and post-write readback checks.
For content strategy and Studio packaging, the module scores candidate topics before recording using the Perfect Video Score equation and Goldilocks Timing Rule (score-idea), benchmarks CTR and retention against official YouTube Help thresholds (analytics-audit, packaging-audit), correlates retention drops with exact spoken sentences (retention-xray), validates description chapters, Studio Video Quizzes, custom thumbnails, and Shorts-to-Longform Related Video batches, uploads SHA-256 frozen drafts strictly as private, and ships an attachable 18-file YouTube Operations Vault for legends-empire.
Deterministic Execution Boundary
Why Raw Prompts and Generic YouTube Scripts Wipe Metadata and Burn Quota
An unguided AI coding agent sends partial snippet payloads to videos.update that erase existing tags and descriptions, uses search.list for channel inventory at 50x the quota cost, or uploads unverified video files without private-draft locks.
- Lossless Snippet Merge & If-Match ETag Concurrency: Fetches the current video resource, verifies expectedCurrent field expectations, merges all mutable snippet fields (title, description, tags, categoryId, defaultLanguage, defaultAudioLanguage), saves a rollback snapshot, sends If-Match ETag headers, and verifies the live readback.
- 2-Unit per 50 Videos Inventory & Zero-Quota Public Readback: Inventories channels through contentDetails.relatedPlaylists.uploads (playlistItems.list + 50-ID batched videos.list) instead of 100-unit search.list calls, plans multi-day write waves against the 10,000-unit pool, and verifies public videos for 0 quota units via ytInitialPlayerResponse and oEmbed.
- Pre-Recording Perfect Video Score & Retention X-Ray: Evaluates video ideas before recording across Trend Timing, Search Surface, Audience Pain, Channel DNA Fit, Proof Advantage, and Packaging Strength divided by Production Drag, Platform Risk, and Hype Saturation, and maps elapsedVideoTimeRatio retention cliffs to exact transcript sentences.
- Shorts Related-Video Isolation Guards & Private-Draft Lock: Enforces fail-closed confirmation phrases (SET_RELATED and LINK_RELATED_BATCH) on Shorts-to-Longform funnel links, validates chapters, 80-character Studio Video Quizzes, and 2 MB thumbnails offline, and hard-locks all resumable uploads to privacyStatus=private.
CLI Subcommands & Capability Surface
- ETag-Guarded Lossless Metadata Planner & Applier: Previews exact title, description, tag, and category diffs against live video state, locks the mutation plan with a SHA-256 digest, preserves omitted snippet fields automatically, writes a rollback snapshot, and enforces If-Match ETag concurrency.
- Low-Quota Channel Inventory, Quota Planner & 0-Quota Readback: Inventories full channel catalogs at 2 quota units per 50 videos via the uploads playlist, models exact daily unit costs and 2026-06-01 granular caps (100 search.list/day, 100 videos.insert/day), and verifies public videos live with zero API quota or credentials.
- Pre-Recording Idea Radar, Outlier Scout & Retention X-Ray: Scores candidate video topics with the Perfect Video Score formula, Goldilocks Timing window (Day 4-30 Prime vs Day 31-180 Evergreen), and 9-Point Fit Filter; scouts breakout outlier videos on public channels for 0 quota units; and aligns retention curves with spoken transcript lines.
- Sourced Channel Health Scorecard & Packaging A/B Diagnostics: Audits Studio exports or live YouTube Analytics API v2 reports against official YouTube Help thresholds (2%-10% CTR band, 50% APV retention target, 8:00 mid-roll eligibility) and ranks high-impression below-median-CTR videos for Test & Compare thumbnail/title experiments.
- Chapters, Studio Video Quizzes, Link Sweeps & Shorts Funnel Guards: Validates description chapters (00:00 start, >= 3 chapters, >= 10s step), Studio Video Quizzes (<= 10 quizzes, <= 80 char options, 60-75 char balanced decoys, MM:SS:FF frames), channel-wide description links and CTA migrations, and Shorts Related-video batches.
- SHA-256 Frozen Private-Draft Upload & 18-File Empire Knowledge Pack: Freezes video, title, description, and custom thumbnail assets into a SHA-256 verified manifest, executes resumable uploads strictly locked to privacyStatus=private behind explicit confirmation phrases, and verifies the 18-file YouTube Operations Vault for legends-empire.
Raw Frontier LLM vs. legends-youtube Execution Matrix
- Video Metadata Updates (videos.update): Standard AI Chat (Sends partial snippet payloads that wipe existing tags, descriptions, or language settings and overwrites concurrent Studio edits.) vs. With legends-youtube (Merges all mutable snippet fields, checks expectedCurrent values, writes pre-mutation rollback JSON, and attaches If-Match ETag headers.) · SHA-256 plan verification before write, HTTP ETag match, and post-write field-by-field readback receipt.
- Channel Inventory & Public Verification Quota: Standard AI Chat (Uses search.list at 100 units per page to list videos and burns authenticated API quota just to check public titles or descriptions.) vs. With legends-youtube (Reads contentDetails.relatedPlaylists.uploads at 2 units per 50 videos and runs anonymous public-readback + RSS outlier scouting at 0 quota units.) · Deterministic quota-plan wave ledger and zero-credential public-readback JSON verification.
- Video Idea Selection & Packaging QA: Standard AI Chat (Brainstorms generic video titles from intuition and guesses chapter or Studio quiz formats that fail YouTube Studio validation.) vs. With legends-youtube (Applies the Perfect Video Score formula, Goldilocks timing rules, and mechanical validators for chapters, 80-char quizzes, thumbnails, and house title style.) · Structured score-idea tier receipts and zero-error chapters-lint, quiz-lint, thumbnail-check, and house-style-lint outputs.
- Upload Privacy & Credential Hygiene: Standard AI Chat (Uploads videos with unverified public visibility or leaks OAuth client secrets and refresh tokens into terminal logs.) vs. With legends-youtube (Locks all resumable uploads to privacyStatus=private with SHA-256 asset verification and scrubs OAuth tokens and API keys from every output.) · Mandatory UPLOAD_PRIVATE_DRAFT confirmation phrase, SSRF-guarded Google API hosts, and secret-scrubbed receipts.
Explicit Safety Boundaries & Exclusions
- Never uploads videos as public or unlisted: every draft-upload operation is hard-locked to privacyStatus=private and requires a SHA-256 frozen manifest plus explicit confirmation phrase.
- Never executes videos.update mutations without a full snippet merge, pre-write rollback snapshot, and matching --expected-plan-sha256 digest.
- Never reads browser cookie databases, system keyrings, or credential stores outside explicit environment variables, --dotenv, or --token-file.
- Never sends OAuth Bearer tokens to non-Google hosts or follows cross-host redirects during authenticated API calls.
Operator FAQ
- Why does calling YouTube's videos.update API directly often delete a video's tags or description?
- YouTube Data API v3's PUT /youtube/v3/videos?part=snippet endpoint replaces the entire snippet object. Any mutable field omitted from your request payload - such as tags, description, defaultLanguage, or defaultAudioLanguage - is wiped or reset by YouTube. legends-youtube prevents this by fetching the live snippet first, verifying expectedCurrent values, merging your changes into the complete existing object, saving a rollback file, and attaching an If-Match ETag header.
- How does legends-youtube inventory a channel and verify public videos without exhausting the 10,000-unit daily quota?
- Calling search.list costs 100 quota units per page and is subject to Google's 2026-06-01 granular cap of 100 calls per day. Instead, legends-youtube resolves the channel's contentDetails.relatedPlaylists.uploads playlist and batches 50 video IDs per videos.list call, costing just 2 quota units per 50 videos. For public checks, public-readback and channel-outliers inspect public watch metadata, oEmbed, and RSS feeds for 0 quota units and 0 credentials.
- How does the Perfect Video Score idea radar evaluate a topic before recording?
- The score-idea command multiplies six upside dimensions (Trend Timing, Search Surface, Audience Pain, Channel DNA Fit, Proof Advantage, and Packaging Strength) and divides by three friction dimensions (Production Drag, Platform Risk, and Hype Saturation), paired with the Goldilocks Timing Rule (Day 4-30 Prime window vs Day 31-180 Workflow Evergreen) and a 9-Point Fit Filter so you never waste studio days on low-leverage topics.
- Can an AI agent accidentally publish a draft video publicly using legends-youtube?
- No. The upload pipeline is split into draft-freeze (which hashes the video binary, title, description, and verified <= 2 MB thumbnail into an immutable manifest) and draft-upload, which hard-codes privacyStatus to private in the YouTube Data API payload and requires both --apply and an exact UPLOAD_PRIVATE_DRAFT <channel_id> confirmation phrase.
All 22 cto-legends Packages (1 Router + 21 Modules)
cto-legends · GitHub: The single local CLI router for Claude Code, Codex, and Cursor: reads one compact startup index and loads 21 isolated Python tools on demand with zero context bloat.legends-empire · GitHub: Govern your local Obsidian and Markdown vault with SHA-256 file integrity locks, crash-safe write transactions, immutable evidence staging, and read-only stewardship audits.legends-astro · GitHub: Migrate WordPress, Next.js, or legacy HTML sites to Astro v7 with a pre-build route and SEO parity contract, offline documentation, and post-build verification.legends-hetzner · GitHub: Scan live European and US Hetzner Cloud stock, compare cost-optimized x86 and ARM64 sizing, and enforce 10-check preflight plans before provisioning any server.legends-coolify · GitHub: Audit your self-hosted Coolify servers, Docker container states, deployment queues, environment variable keys, and database backup schedules over read-only HTTPS with zero secret exposure.legends-cloudflare · GitHub: Execute preview-first Cloudflare DNS updates and cutovers that preserve orange-cloud proxy states, guard multi-record hostnames, and verify every change via live API readback.legends-stripe · GitHub: Audit Stripe .env price IDs, sync Test and Live price ladders, reconcile fixed-fee drag and net retained cash to the cent, and verify raw-body HMAC webhooks with zero dependencies.legends-gohighlevel · GitHub: Operate GoHighLevel sub-accounts, batch-clone V2 snapshots with headless PIT minting, X-ray and rebrand internal workflow steps, and enforce 5-layer agency permissions and 4-store SaaS rebilling markups.legends-buzz · GitHub: Operate self-hosted Block Buzz Nostr relays, route all 26 Buzz MCP domains through token-compact CLI calls, diagnose NIP-29 and NIP-FI membership 403s, reconstruct reply threads, and audit attachments with zero dependencies.legends-github · GitHub: Audit GitHub repository health, package verified releases, align your 20 repo topics with live search demand, and verify 1280x640 Open Graph social preview cards pixel for pixel.legends-jev · GitHub: Local Python OCR and visual verification for UI screenshots, exact original-image pixel coordinates, and Google Street View storefront signage audits.legends-geogrid · GitHub: Run circular-lattice Google Maps rank studies up to 30 positions deep at wholesale DataForSEO rates, complete with Street View signage dossiers and 18-page vector PDF briefings.legends-dataforseo · GitHub: Query Google organic SERPs, Google Maps, and keyword volume over the DataForSEO API with offline cost previews, zero-dependency Python execution, and SHA-256 local evidence banking.legends-firecrawl · GitHub: Convert JavaScript-heavy websites into clean Markdown and run preview-gated Firecrawl site maps, bounded crawls, and Alexandria catalog queries with SHA-256 local evidence banking.legends-grant · GitHub: Search federal, state, and foundation grants across 56 US jurisdictions, verify verbatim eligibility rules against your private company facts, and check proposal budgets to the cent.legends-obs · GitHub: Automate OBS Studio over its local WebSocket server with profile backups, window-aware scene switching, hardware encoder checks, and canary test-clip verification.legends-captions · GitHub: Repair misheard technical terms, lock letter-by-letter acronym timing, and render frame-accurate word-by-word subtitles for 4K60 vertical and widescreen video.legends-yt-dlp · GitHub: Paced yt-dlp video, audio, and YouTube transcript pipeline with resumable batch ledgers, local GPU word alignment, and frame-accurate FFmpeg clip cuts.legends-stable-audio-3 · GitHub: Generate custom instrumental tracks on your local GPU with Stable Audio 3 and crossfade multi-hour background mixes with automated silence trimming.legends-hyperyap · GitHub: Push-to-talk local GPU voice dictation for Windows, macOS, and Linux: transcribe speech offline with NVIDIA Parakeet and paste straight into your active editor or terminal.legends-ambient-intelligence · GitHub: Offline voice memo and meeting transcription pipeline: archive USB voice recorders with SHA-256 deduplication, run local Whisper or Parakeet, and distill Obsidian notes.legends-youtube · GitHub: Operate YouTube channels over Data API v3 and Analytics API v2 with ETag-guarded lossless metadata updates, zero-quota public readbacks, Perfect Video Score idea radar, Shorts Related-video guards, Studio chapter and quiz validators, and an 18-file Empire knowledge pack.