yt_live_scraper package

Submodules

yt_live_scraper.cli module

CLI entry point for yt-live-scraper.

yt_live_scraper.cli.main(argv=None)

Run the yt-live-scraper command-line interface.

Parameters:: argv (list[str] | None) – Argument list to parse. Defaults to sys.argv[1:].
Return type:: None

yt_live_scraper.scraper module

Scrape YouTube channel pages for live and upcoming stream events.

class yt_live_scraper.scraper.ChannelInfo(name, channel_id, thumbnail_url)

Bases: object

Basic metadata for a YouTube channel.

Parameters:

name (str) – Channel display name.
channel_id (str) – YouTube channel ID.
thumbnail_url (str) – URL of the channel’s avatar image.

channel_id: str

name: str

thumbnail_url: str

class yt_live_scraper.scraper.StreamLiveStatus(is_live, actual_start=None)

Bases: object

Result of checking whether a stream is live.

Parameters:

is_live (bool) – True if the stream is currently live.
actual_start (datetime | None) – The actual broadcast start time in UTC, extracted from liveBroadcastDetails.startTimestamp. None when the timestamp is unavailable or the stream is not live.

actual_start: datetime | None = None

is_live: bool

class yt_live_scraper.scraper.UpcomingStream(channel, channel_id, channel_thumbnail_url, video_id, title, scheduled_start, url, thumbnail_url, live)

Bases: object

A YouTube live or upcoming stream.

Parameters:

channel (str) – Channel display name.
channel_id (str) – YouTube channel ID.
channel_thumbnail_url (str) – URL of the channel’s avatar image.
video_id (str) – YouTube video ID.
title (str) – Stream title.
scheduled_start (datetime) – Scheduled start time in UTC.
url (str) – Full YouTube watch URL.
thumbnail_url (str) – URL of the stream’s thumbnail image.
live (bool) – True if the stream is currently live.

channel: str

channel_id: str

channel_thumbnail_url: str

static exists(channel_handle, *, timeout=10)

Check if a YouTube channel handle exists.

Parameters:

channel_handle (str) – Channel handle (with or without leading @).
timeout (float) – HTTP request timeout in seconds.

Return type:

bool

Returns:

True if the channel exists, False otherwise.

live: bool

scheduled_start: datetime

thumbnail_url: str

title: str

url: str

video_id: str

yt_live_scraper.scraper.clear_caches()

Clear the module’s internal caches (resolved start times).

Return type:: None

yt_live_scraper.scraper.get_channel(channel_handle, *, timeout=10)

Get the display name of a YouTube channel from its handle.

Parameters:

channel_handle (str) – Channel handle (with or without leading @).
timeout (float) – HTTP request timeout in seconds.

Return type:

str | None

Returns:

The channel’s display name, or None if it does not exist.

yt_live_scraper.scraper.get_channel_info(channel_handle, *, timeout=10)

Get basic metadata for a YouTube channel from its handle.

Parameters:

channel_handle (str) – Channel handle (with or without leading @).
timeout (float) – HTTP request timeout in seconds.

Return type:

ChannelInfo | None

Returns:

A ChannelInfo with the channel’s name, ID and avatar thumbnail URL, or None if the channel does not exist.

yt_live_scraper.scraper.get_upcoming_streams(channels, *, from_date=None, timeout=15)

Fetch upcoming live streams for a list of YouTube channel handles.

Parameters:

channels (list[str]) – Channel handles (with or without leading @).
from_date (date | None) – Only include streams on or after this date. Defaults to today (UTC).
timeout (float) – HTTP request timeout in seconds.

Return type:

list[UpcomingStream]

Returns:

List of UpcomingStream objects sorted by scheduled start time.

yt_live_scraper.scraper.is_stream_live(video_id, *, timeout=10)

Check whether a YouTube stream is currently live.

Fetches the video page and inspects the player response for the isLive flag inside videoDetails. When the stream is live, the actual broadcast start time is extracted from liveBroadcastDetails.startTimestamp if available.

Parameters:

video_id (str) – YouTube video ID to check.
timeout (float) – HTTP request timeout in seconds.

Return type:

StreamLiveStatus

Returns:

A StreamLiveStatus with the live flag and, when available, the actual start time. On network or parse errors the status defaults to not-live with no start time.

Module contents

class yt_live_scraper.ChannelInfo(name, channel_id, thumbnail_url)

Bases: object

Basic metadata for a YouTube channel.

Parameters:

name (str) – Channel display name.
channel_id (str) – YouTube channel ID.
thumbnail_url (str) – URL of the channel’s avatar image.

channel_id: str

name: str

thumbnail_url: str

class yt_live_scraper.StreamLiveStatus(is_live, actual_start=None)

Bases: object

Result of checking whether a stream is live.

Parameters:

is_live (bool) – True if the stream is currently live.
actual_start (datetime | None) – The actual broadcast start time in UTC, extracted from liveBroadcastDetails.startTimestamp. None when the timestamp is unavailable or the stream is not live.

actual_start: datetime | None = None

is_live: bool

class yt_live_scraper.UpcomingStream(channel, channel_id, channel_thumbnail_url, video_id, title, scheduled_start, url, thumbnail_url, live)

Bases: object

A YouTube live or upcoming stream.

Parameters:

channel (str) – Channel display name.
channel_id (str) – YouTube channel ID.
channel_thumbnail_url (str) – URL of the channel’s avatar image.
video_id (str) – YouTube video ID.
title (str) – Stream title.
scheduled_start (datetime) – Scheduled start time in UTC.
url (str) – Full YouTube watch URL.
thumbnail_url (str) – URL of the stream’s thumbnail image.
live (bool) – True if the stream is currently live.

channel: str

channel_id: str

channel_thumbnail_url: str

static exists(channel_handle, *, timeout=10)

Check if a YouTube channel handle exists.

Parameters:

channel_handle (str) – Channel handle (with or without leading @).
timeout (float) – HTTP request timeout in seconds.

Return type:

bool

Returns:

True if the channel exists, False otherwise.

live: bool

scheduled_start: datetime

thumbnail_url: str

title: str

url: str

video_id: str

yt_live_scraper.get_channel(channel_handle, *, timeout=10)

Get the display name of a YouTube channel from its handle.

Parameters:

channel_handle (str) – Channel handle (with or without leading @).
timeout (float) – HTTP request timeout in seconds.

Return type:

str | None

Returns:

The channel’s display name, or None if it does not exist.

yt_live_scraper.get_channel_info(channel_handle, *, timeout=10)

Get basic metadata for a YouTube channel from its handle.

Parameters:

channel_handle (str) – Channel handle (with or without leading @).
timeout (float) – HTTP request timeout in seconds.

Return type:

ChannelInfo | None

Returns:

A ChannelInfo with the channel’s name, ID and avatar thumbnail URL, or None if the channel does not exist.

yt_live_scraper.get_upcoming_streams(channels, *, from_date=None, timeout=15)

Fetch upcoming live streams for a list of YouTube channel handles.

Parameters:

channels (list[str]) – Channel handles (with or without leading @).
from_date (date | None) – Only include streams on or after this date. Defaults to today (UTC).
timeout (float) – HTTP request timeout in seconds.

Return type:

list[UpcomingStream]

Returns:

List of UpcomingStream objects sorted by scheduled start time.

yt_live_scraper.is_stream_live(video_id, *, timeout=10)

Check whether a YouTube stream is currently live.

Fetches the video page and inspects the player response for the isLive flag inside videoDetails. When the stream is live, the actual broadcast start time is extracted from liveBroadcastDetails.startTimestamp if available.

Parameters:

video_id (str) – YouTube video ID to check.
timeout (float) – HTTP request timeout in seconds.

Return type:

StreamLiveStatus

Returns:

A StreamLiveStatus with the live flag and, when available, the actual start time. On network or parse errors the status defaults to not-live with no start time.