Stream Alerts
Relevant source files
The following files were used as context for generating this wiki page:
Stream Alerts enable the bot to monitor external streaming platforms and notify Discord communities when broadcasters go live. This module supports Twitch, YouTube, Picarto, and Kick. The system utilizes a background polling architecture to maintain real-time status updates across multiple guilds.
Sources: README.md:61, redbot/cogs/streams/streams.py:44-50
System Architecture
The Streams cog operates via a centralized task loop that manages API interactions and alert distribution. It integrates with the core bot configuration to handle shared API tokens for various services.
Core Components
- Polling Loop: The
_stream_alertsfunction runs indefinitely while the bot is active. It executes status checks at intervals defined by therefresh_timer. - Token Management: The system retrieves credentials from the bot's shared API storage. It automatically requests OAuth2 bearer tokens for Twitch and Kick when client secrets are provided.
- Persistence: Stream metadata, including monitored channel IDs and target Discord channels, are stored in the bot's global configuration.
Sources: redbot/cogs/streams/streams.py:101-105, redbot/cogs/streams/streams.py:720-724
Polling Logic Flow
The following diagram illustrates the background polling cycle for stream status updates:
Configuration
The system provides separate configuration scopes for global behavior and guild-specific notification preferences.
Global Settings
| Setting | Default | Description |
|---|---|---|
refresh_timer | 300s | Seconds between platform status checks. |
tokens | {} | Storage for legacy API keys. |
streams | [] | List of all monitored stream objects globally. |
Sources: redbot/cogs/streams/streams.py:53-59
Guild Settings
| Setting | Default | Description |
|---|---|---|
autodelete | False | Deletes the alert message when a stream ends. |
mention_everyone | False | Toggles @everyone mention in alerts. |
mention_here | False | Toggles @here mention in alerts. |
ignore_reruns | False | Suppresses alerts for Twitch reruns. |
use_buttons | False | Adds "Watch Stream" buttons to alert embeds. |
Sources: redbot/cogs/streams/streams.py:61-70
Notification Management
Alerts are dispatched as Discord embeds containing stream metadata such as the title, game, and viewer count.
Mention Logic
The bot handles complex mention requirements by checking permissions and role settings. If a configured role is not mentionable, the bot momentarily enables the mentionable property, sends the alert, and then disables it.
Custom Alert Messages
Users can customize notification content using placeholders. This allows guilds to maintain unique branding for their automated alerts.
{stream}: The channel or username of the streamer.{stream.display_name}: The display name (specific to Twitch).{mention}: The calculated mention string (@everyone, @here, or role).
Sources: redbot/cogs/streams/streams.py:507-526
Platform Specific Implementation
Each platform has unique behaviors within the polling loop:
- YouTube: Distinguishes between active streams and scheduled events. Guilds can use
[p]streamset ignorescheduleto filter upcoming events. - Twitch: Supports rerun detection. The bot uses a bearer token cache (
ttv_bearer_cache) to reduce OAuth2 requests. - Kick: Requires an OAuth2 flow similar to Twitch. It uses the
kick_bearer_cachefor authentication. - Picarto: Uses standard public API polling without complex OAuth2 requirements for basic status checks.
Sources: redbot/cogs/streams/streams.py:165-200, redbot/cogs/streams/streams.py:741-760, redbot/cogs/streams/streams.py:623-640
Command Interface
The streamalert group provides the primary interface for managing monitored channels.
| Command | Usage | Result |
|---|---|---|
[p]streamalert twitch | [p]streamalert twitch <name> | Toggles Twitch alerts for a channel. |
[p]streamalert youtube | [p]streamalert youtube <id_or_name> | Toggles YouTube alerts for a channel. |
[p]streamalert list | [p]streamalert list | Lists all active alerts in the current guild. |
[p]streamalert stop | [p]streamalert stop [all] | Disables alerts in the channel or entire server. |
Sources: redbot/cogs/streams/streams.py:348-420, redbot/core/commands/help.py:350-380
The Stream Alerts system provides a robust solution for automated content notifications, leveraging Red's modular architecture to handle multi-platform monitoring efficiently. Guild owners maintain full control over notification styles, mention levels, and content filtering.
Sources: redbot/cogs/streams/streams.py:44-50, redbot/cogs/streams/streams.py:900-910