sergebulaev/youtube-skills / .codex-marketplace/youtube-skills
youtube-marketing
VerifiedPlan, write, and publish for YouTube and YouTube Shorts. Use when the user wants high-CTR video titles, an SEO description with chapters and links, a first-30-seconds retention script (or a 3-second Shorts hook), a designer-ready thumbnail brief, a community-tab post or poll, or a weekly upload plan. The user supplies the video; the skills produce the title, description, hook, and thumbnail brief, then on approval upload and schedule via the Publora API.
lib/youtube_client.py
View on GitHub"""YouTube Data API v3 read client for the YouTube Skills project.
The read layer: given a video or channel, pull commenters, top comments,
video/channel stats, and what is trending in a niche. Unlike scraped social
platforms, YouTube exposes this through a free, first-party, stable API, so no
proxies, no cookies, no scraping.
Auth: YOUTUBE_API_KEY env var (or constructor arg). Get one free at
https://console.cloud.google.com -> enable "YouTube Data API v3" -> Create
credentials -> API key. Free quota is 10,000 units/day (a comment or stats call
is 1 unit; search is 100 units), which is ~100,000 comments/day at no cost.
What YouTube does NOT expose (by design): the list of who LIKED a video. Only
aggregate likeCount is public. So the engagement signal here is COMMENTERS, not
likers. That is a platform wall, not a client limitation.
Methods:
- fetch_video_comments(video, max_results, order) -> top-level comments with
author, channel URL, text, like count, reply count, timestamp.
- fetch_video_stats(video) -> title, channel, views/likes/comments.
- fetch_channel_stats(channel) -> subscribers, video count, total views.
- fetch_trending(region_code, category_id, max_results) -> most-popular videos
(1 unit; no search quota cost) for "what is working in my niche".
Caching: in-process LRU (256 entries, 6h TTL). Pass force_refresh=True to
bypass. Retries on transient 429/5xx (3 attempts, exponential backoff + jitter).
"""
from __future__ import annotations
import os
import random
import time
from collections import OrderedDict
from typing import Any, Optional
import requests
from ._env import load_env
API_BASE = "https://www.googleapis.com/youtube/v3"
RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
CACHE_MAX_ENTRIES = 256
CACHE_TTL_SECONDS = 6 * 60 * 60
SIGNUP_URL = "https://console.cloud.google.com/apis/library/youtube.googleapis.com"
class YouTubeError(RuntimeError):
pass
class YouTubeAuthError(YouTubeError):
"""Raised when no API key is configured. Message explains the free path."""
def _retry(attempts: int = 3, base_delay: float = 0.6):
def decorator(fn):
def wrapper(*args, **kwargs):
last: Optional[Exception] = None
for i in range(attempts):
try:
return fn(*args, **kwargs)
except YouTubeError as e:
status = getattr(e, "status", None)
if status not in RETRYABLE_STATUSES or i == attempts - 1:
raise
last = e
time.sleep(base_delay * (2 ** i) + random.uniform(0, 0.3))
if last:
raise last
return wrapper
return decorator
def _extract_video_id(video: str) -> str:
"""Accept a video id, a watch URL, a youtu.be URL, or a shorts URL."""
v = video.strip()
if "watch?v=" in v:
return v.split("watch?v=")[1].split("&")[0]
if "youtu.be/" in v:
return v.split("youtu.be/")[1].split("?")[0].split("/")[0]
if "/shorts/" in v:
return v.split("/shorts/")[1].split("?")[0].split("/")[0]
return v # assume it is already an id
class YouTubeClient:
def __init__(self, api_key: Optional[str] = None, timeout: int = 20):
load_env()
self.api_key = api_key or os.environ.get("YOUTUBE_API_KEY")
self.timeout = timeout
self._cache: "OrderedDict[str, tuple[float, Any]]" = OrderedDict()
# ---- internal ----
def _require_key(self) -> str:
if not self.api_key:
raise YouTubeAuthError(
"No YOUTUBE_API_KEY set. Get one free: enable 'YouTube Data API v3' "
f"at {SIGNUP_URL}, create an API key, and set YOUTUBE_API_KEY. "
"Or paste the comments/stats you already have and the skill will "
"work from that."
)
return self.api_key
def _cache_get(self, key: str):
hit = self._cache.get(key)
if hit and (time.time() - hit[0]) < CACHE_TTL_SECONDS:
self._cache.move_to_end(key)
return hit[1]
return None
def _cache_put(self, key: str, val: Any):
self._cache[key] = (time.time(), val)
self._cache.move_to_end(key)
while len(self._cache) > CACHE_MAX_ENTRIES:
self._cache.popitem(last=False)
@_retry()
def _get(self, endpoint: str, params: dict) -> dict:
params = {**params, "key": self._require_key()}
try:
r = requests.get(f"{API_BASE}/{endpoint}", params=params, allow_redirects=False, timeout=self.timeout)
except requests.RequestException as e:
err = YouTubeError(f"network error calling {endpoint}: {e}")
err.status = 503
raise err
if r.status_code == 403 and "quota" in r.text.lower():
raise YouTubeError("YouTube API daily quota exceeded (resets midnight PT).")
if r.status_code >= 400:
err = YouTubeError(f"{endpoint} returned {r.status_code}: {r.text[:200]}")
err.status = r.status_code
raise err
return r.json()
# ---- public read methods ----
def fetch_video_comments(self, video: str, max_results: int = 100,
order: str = "relevance", force_refresh: bool = False) -> list[dict]:
"""Top-level comments on a video. order: 'relevance' or 'time'.
Returns author, author_channel_url, text, like_count, reply_count, published_at."""
vid = _extract_video_id(video)
ck = f"comments:{vid}:{max_results}:{order}"
if not force_refresh and (c := self._cache_get(ck)) is not None:
return c
out: list[dict] = []
page_token = None
while len(out) < max_results:
data = self._get("commentThreads", {
"part": "snippet", "videoId": vid,
"maxResults": min(100, max_results - len(out)),
"order": order, **({"pageToken": page_token} if page_token else {}),
})
for it in data.get("items", []):
s = it["snippet"]["topLevelComment"]["snippet"]
out.append({
"author": s.get("authorDisplayName"),
"author_channel_url": s.get("authorChannelUrl"),
"text": s.get("textDisplay"),
"like_count": s.get("likeCount", 0),
"reply_count": it["snippet"].get("totalReplyCount", 0),
"published_at": s.get("publishedAt"),
})
page_token = data.get("nextPageToken")
if not page_token:
break
self._cache_put(ck, out)
return out
def fetch_video_stats(self, video: str, force_refresh: bool = False) -> dict:
vid = _extract_video_id(video)
ck = f"vstats:{vid}"
if not force_refresh and (c := self._cache_get(ck)) is not None:
return c
data = self._get("videos", {"part": "snippet,statistics", "id": vid})
items = data.get("items", [])
if not items:
raise YouTubeError(f"video not found: {vid}")
it = items[0]
st = it.get("statistics", {})
res = {
"video_id": vid,
"title": it["snippet"].get("title"),
"channel_title": it["snippet"].get("channelTitle"),
"views": int(st.get("viewCount", 0)),
"likes": int(st.get("likeCount", 0)) if "likeCount" in st else None,
"comments": int(st.get("commentCount", 0)) if "commentCount" in st else None,
"published_at": it["snippet"].get("publishedAt"),
}
self._cache_put(ck, res)
return res
def fetch_channel_stats(self, channel: str, force_refresh: bool = False) -> dict:
"""Accept a channel id (UC...), an @handle, or a handle string."""
ch = channel.strip()
ck = f"cstats:{ch}"
if not force_refresh and (c := self._cache_get(ck)) is not None:
return c
params = {"part": "snippet,statistics"}
if ch.startswith("UC") and len(ch) > 20:
params["id"] = ch
else:
params["forHandle"] = ch.lstrip("@")
data = self._get("channels", params)
items = data.get("items", [])
if not items:
raise YouTubeError(f"channel not found: {channel}")
it = items[0]
st = it.get("statistics", {})
res = {
"channel_id": it.get("id"),
"title": it["snippet"].get("title"),
"subscribers": int(st.get("subscriberCount", 0)) if not st.get("hiddenSubscriberCount") else None,
"videos": int(st.get("videoCount", 0)),
"total_views": int(st.get("viewCount", 0)),
}
self._cache_put(ck, res)
return res
def fetch_trending(self, region_code: str = "US", category_id: Optional[str] = None,
max_results: int = 25, force_refresh: bool = False) -> list[dict]:
"""Most-popular videos (1 unit, no search cost). category_id filters to a niche."""
max_results = min(50, max_results) # API hard-caps mostPopular at 50; keep cache key honest
ck = f"trending:{region_code}:{category_id}:{max_results}"
if not force_refresh and (c := self._cache_get(ck)) is not None:
return c
params = {"part": "snippet,statistics", "chart": "mostPopular",
"regionCode": region_code, "maxResults": min(50, max_results)}
if category_id:
params["videoCategoryId"] = str(category_id)
data = self._get("videos", params)
out = []
for it in data.get("items", []):
st = it.get("statistics", {})
out.append({
"video_id": it.get("id"),
"title": it["snippet"].get("title"),
"channel_title": it["snippet"].get("channelTitle"),
"views": int(st.get("viewCount", 0)),
"likes": int(st.get("likeCount", 0)) if "likeCount" in st else None,
"comments": int(st.get("commentCount", 0)) if "commentCount" in st else None,
})
self._cache_put(ck, out)
return out
if __name__ == "__main__":
import json as _json
c = YouTubeClient()
print(_json.dumps(c.fetch_video_stats("https://www.youtube.com/watch?v=dQw4w9WgXcQ"), indent=2))
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |