scrapebadger-cli 0.2.1__py3-none-any.whl

scrapebadger_cli/commands/youtube.py

@@ -0,0 +1,625 @@
+"""YouTube scraper commands."""
+
+import typer
+
+from scrapebadger_cli.client import api_get, api_post
+from scrapebadger_cli.output import render
+
+app = typer.Typer(no_args_is_help=True)
+
+FMT = typer.Option("json", "--output", "-o", help="Output format: json, csv, table, markdown")
+FIELDS = typer.Option(None, "--fields", "-f", help="Comma-separated fields to include")
+GL = typer.Option(None, "--gl", help="Content region (US, GB, DE, BR, JP, ...)")
+HL = typer.Option(None, "--hl", help="UI language (en, es, fr, ...)")
+CONT = typer.Option(None, "--continuation", "-c", help="Pagination continuation token")
+
+
+# ---------------------------------------------------------------------------
+# Search & autocomplete
+# ---------------------------------------------------------------------------
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search keywords"),
+    type: str | None = typer.Option(None, "--type", "-t", help="video|channel|playlist|movie|all"),
+    sort_by: str | None = typer.Option(None, "--sort-by", help="relevance|date|views|rating"),
+    upload_date: str | None = typer.Option(
+        None, "--upload-date", help="hour|today|week|month|year"
+    ),
+    duration: str | None = typer.Option(None, "--duration", help="short|medium|long"),
+    features: str | None = typer.Option(None, "--features", help="Comma-separated (hd,4k,cc,...)"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Search YouTube videos, channels and playlists."""
+    data = api_get(
+        "/v1/youtube/search",
+        {
+            "query": query,
+            "type": type,
+            "sort_by": sort_by,
+            "upload_date": upload_date,
+            "duration": duration,
+            "features": features,
+            "gl": gl,
+            "hl": hl,
+            "continuation": continuation,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def autocomplete(
+    query: str = typer.Argument(..., help="Partial query prefix"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get YouTube search autocomplete suggestions."""
+    data = api_get("/v1/youtube/autocomplete", {"query": query, "gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Videos
+# ---------------------------------------------------------------------------
+@app.command()
+def video(
+    video_id: str = typer.Argument(..., help="YouTube video ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get full video detail (player + next merged)."""
+    data = api_get(f"/v1/youtube/videos/{video_id}", {"gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+@app.command()
+def batch(
+    video_ids: str = typer.Argument(..., help="Comma-separated video IDs (max 50)"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get details for many videos in one call (billed per video)."""
+    ids = [v.strip() for v in video_ids.split(",") if v.strip()]
+    data = api_post("/v1/youtube/videos/batch", {"video_ids": ids, "gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+@app.command()
+def related(
+    video_id: str = typer.Argument(..., help="YouTube video ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get related videos for a video."""
+    data = api_get(
+        f"/v1/youtube/videos/{video_id}/related",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def comments(
+    video_id: str = typer.Argument(..., help="YouTube video ID"),
+    sort_by: str = typer.Option("top", "--sort-by", help="top|newest"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get top-level comments on a video."""
+    data = api_get(
+        f"/v1/youtube/videos/{video_id}/comments",
+        {"sort_by": sort_by, "gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def replies(
+    video_id: str = typer.Argument(..., help="YouTube video ID"),
+    comment_id: str = typer.Argument(..., help="Parent comment ID"),
+    continuation: str = typer.Option(
+        ..., "--continuation", "-c", help="Replies continuation token (from a comment)"
+    ),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get replies to a comment."""
+    data = api_get(
+        f"/v1/youtube/videos/{video_id}/comments/{comment_id}/replies",
+        {"continuation": continuation, "gl": gl, "hl": hl},
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def transcript(
+    video_id: str = typer.Argument(..., help="YouTube video ID"),
+    language: str | None = typer.Option(None, "--language", "-l", help="BCP-47 language code"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get the transcript / timed captions for a video."""
+    data = api_get(
+        f"/v1/youtube/videos/{video_id}/transcript",
+        {"language": language, "gl": gl, "hl": hl},
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def captions(
+    video_id: str = typer.Argument(..., help="YouTube video ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """List the available caption tracks for a video."""
+    data = api_get(f"/v1/youtube/videos/{video_id}/captions", {"gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+@app.command()
+def streams(
+    video_id: str = typer.Argument(..., help="YouTube video ID"),
+    client: str = typer.Option("IOS", "--client", help="IOS|ANDROID|WEB"),
+    gl: str | None = GL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get downloadable stream formats for a video (best-effort)."""
+    data = api_get(f"/v1/youtube/videos/{video_id}/streams", {"client": client, "gl": gl})
+    render(data, fmt, fields)
+
+
+@app.command(name="live-chat")
+def live_chat(
+    video_id: str = typer.Argument(..., help="YouTube video ID"),
+    replay: bool = typer.Option(False, "--replay", help="Fetch chat replay for a finished stream"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get live chat messages for a stream."""
+    data = api_get(
+        f"/v1/youtube/videos/{video_id}/live_chat",
+        {"replay": replay, "gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Channels
+# ---------------------------------------------------------------------------
+@app.command()
+def channel(
+    channel_id: str = typer.Argument(..., help="Channel ID, @handle or custom URL"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get a channel's profile (about + header)."""
+    data = api_get(f"/v1/youtube/channels/{channel_id}", {"gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+@app.command(name="channel-videos")
+def channel_videos(
+    channel_id: str = typer.Argument(..., help="Channel ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get a channel's uploaded videos."""
+    data = api_get(
+        f"/v1/youtube/channels/{channel_id}/videos",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="channel-shorts")
+def channel_shorts(
+    channel_id: str = typer.Argument(..., help="Channel ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get a channel's Shorts."""
+    data = api_get(
+        f"/v1/youtube/channels/{channel_id}/shorts",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="channel-streams")
+def channel_streams(
+    channel_id: str = typer.Argument(..., help="Channel ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get a channel's live streams / past broadcasts."""
+    data = api_get(
+        f"/v1/youtube/channels/{channel_id}/streams",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="channel-playlists")
+def channel_playlists(
+    channel_id: str = typer.Argument(..., help="Channel ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get a channel's playlists."""
+    data = api_get(
+        f"/v1/youtube/channels/{channel_id}/playlists",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="channel-community")
+def channel_community(
+    channel_id: str = typer.Argument(..., help="Channel ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get a channel's community / posts feed."""
+    data = api_get(
+        f"/v1/youtube/channels/{channel_id}/community",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="channel-about")
+def channel_about(
+    channel_id: str = typer.Argument(..., help="Channel ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get a channel's About tab (links, stats, joined date, country)."""
+    data = api_get(f"/v1/youtube/channels/{channel_id}/about", {"gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+@app.command(name="subscriber-count")
+def subscriber_count(
+    channel_id: str = typer.Argument(..., help="Channel ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get a channel's subscriber count (fast path)."""
+    data = api_get(f"/v1/youtube/channels/{channel_id}/subscriber_count", {"gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+@app.command(name="channel-search")
+def channel_search(
+    channel_id: str = typer.Argument(..., help="Channel ID"),
+    query: str = typer.Argument(..., help="Search keywords"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Search within a channel's content."""
+    data = api_get(
+        f"/v1/youtube/channels/{channel_id}/search",
+        {"query": query, "gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def resolve(
+    handle: str | None = typer.Option(None, "--handle", help="@handle or custom name"),
+    url: str | None = typer.Option(None, "--url", help="Full channel/video/playlist URL"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Resolve a @handle or URL to a channel ID."""
+    data = api_get(
+        "/v1/youtube/channels/resolve",
+        {"handle": handle, "url": url, "gl": gl, "hl": hl},
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Playlists & mixes
+# ---------------------------------------------------------------------------
+@app.command()
+def playlist(
+    playlist_id: str = typer.Argument(..., help="Playlist ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get playlist metadata (+ first item page)."""
+    data = api_get(f"/v1/youtube/playlists/{playlist_id}", {"gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+@app.command(name="playlist-items")
+def playlist_items(
+    playlist_id: str = typer.Argument(..., help="Playlist ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get the items in a playlist (paginated)."""
+    data = api_get(
+        f"/v1/youtube/playlists/{playlist_id}/items",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def mix(
+    playlist_id: str = typer.Argument(..., help="Mix / radio playlist ID (RD...)"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get a YouTube mix / radio playlist."""
+    data = api_get(f"/v1/youtube/mixes/{playlist_id}", {"gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Trending, hashtags & home
+# ---------------------------------------------------------------------------
+@app.command()
+def trending(
+    type: str = typer.Option("now", "--type", "-t", help="now|music|gaming|movies"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get the trending feed for a region."""
+    data = api_get(
+        "/v1/youtube/trending",
+        {"type": type, "gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="trending-shorts")
+def trending_shorts(
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get the trending Shorts shelf for a region."""
+    data = api_get(
+        "/v1/youtube/trending/shorts",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def hashtag(
+    tag: str = typer.Argument(..., help="Hashtag (without #)"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get the feed for a hashtag."""
+    data = api_get(
+        f"/v1/youtube/hashtags/{tag}",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def home(
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get the guest home feed."""
+    data = api_get("/v1/youtube/home", {"gl": gl, "hl": hl, "continuation": continuation})
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Shorts
+# ---------------------------------------------------------------------------
+@app.command()
+def short(
+    video_id: str = typer.Argument(..., help="Short video ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get full metadata for a Short."""
+    data = api_get(f"/v1/youtube/shorts/{video_id}", {"gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+@app.command(name="shorts-by-sound")
+def shorts_by_sound(
+    sound_id: str = typer.Argument(..., help="Sound / music ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get Shorts that use a given sound."""
+    data = api_get(
+        f"/v1/youtube/shorts/by_sound/{sound_id}",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Community posts
+# ---------------------------------------------------------------------------
+@app.command()
+def post(
+    post_id: str = typer.Argument(..., help="Community post ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get a community post detail."""
+    data = api_get(f"/v1/youtube/posts/{post_id}", {"gl": gl, "hl": hl})
+    render(data, fmt, fields)
+
+
+@app.command(name="post-comments")
+def post_comments(
+    post_id: str = typer.Argument(..., help="Community post ID"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get comments on a community post."""
+    data = api_get(
+        f"/v1/youtube/posts/{post_id}/comments",
+        {"gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Music & oEmbed
+# ---------------------------------------------------------------------------
+@app.command(name="music-search")
+def music_search(
+    query: str = typer.Argument(..., help="Search keywords"),
+    gl: str | None = GL,
+    hl: str | None = HL,
+    continuation: str | None = CONT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Search YouTube Music."""
+    data = api_get(
+        "/v1/youtube/music/search",
+        {"query": query, "gl": gl, "hl": hl, "continuation": continuation},
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def oembed(
+    url: str = typer.Argument(..., help="A YouTube video/playlist/channel URL"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Get cheap unauthenticated oEmbed metadata for a URL."""
+    data = api_get("/v1/youtube/oembed", {"url": url})
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Reference (zero-credit)
+# ---------------------------------------------------------------------------
+@app.command()
+def categories(
+    gl: str | None = GL,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """List YouTube video categories."""
+    data = api_get("/v1/youtube/categories", {"gl": gl})
+    render(data, fmt, fields)
+
+
+@app.command()
+def languages(
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """List supported UI languages (hl)."""
+    data = api_get("/v1/youtube/languages")
+    render(data, fmt, fields)
+
+
+@app.command()
+def regions(
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """List supported content regions (gl)."""
+    data = api_get("/v1/youtube/regions")
+    render(data, fmt, fields)
+
+
+@app.command()
+def markets(
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """List all supported YouTube markets."""
+    data = api_get("/v1/youtube/markets")
+    render(data, fmt, fields)