Faster Twitch Alerts

What is "Faster Twitch Alerts"?

Faster Twitch Alerts is a highly customizable, lightning-fast alternative to Twitch's slow mobile notification system. Faster Twitch Alerts currently supports two notification platforms: Discord and Pushover.

The program can notify you when:

• A streamer goes live
• A streamer goes offline
• A streamer gets banned
• A streamer is unbanned
• A streamer updates their title and/or game
  
  

Disclaimer: This program is not associated in any way with Twitch, Discord, or Pushover

Getting Started

1. Clone the repository
2. Install the Python 3 and the Python requests library
3. Set your notification preferences in the config.json File
4. Run Main.py
   • If the program terminates unexpectedly, check the log file for more information
   • You can terminate the program at any time using 'ctrl+c'

Config Fields Explained

Primary Fields

For more detailed explanations of each field, follow the links

Twitch Settings

This is where we store overall program settings and settings related to the Twitch API

Example Twitch Settings Object:

"Twitch Settings" : {
	"Client ID" : "YOUR CLIENT ID",
	"Secret" : "YOUR SECRET",
	"Reconnect Attempts" : 10,
	"Reconnect Cooldown" : 60,
	"Refresh Rate" : 1
}

Twitch Settings Fields:

Footnotes:

• ¹ Setting Up a Twitch Developer Application
• ² Negative values signal infinite reconnect attempts
• ³ There is a hard cap on the refresh rate imposed by Twitch API rate limits. You can calculate the refresh rate using the following formula: 20 / (3 * ceil( [# of streamers] / 100 ))
  
  

Logger Settings

Settings related to the log file

Example Logger Settings Object:

"Logger Settings" : {
	"Log Level" : "INFO",
	"Log Filepath" : "logs/twitch_alerts.log",
	"Message Text" : "ALERT!"
}

Logger Settings Fields:

Footnotes:

• ¹ More Info on Log Levels:
  • DEBUG: Shows minor network errors
  • INFO: Info about streamer activity, and general program info
  • WARNING: Info about non-fatal errors
  • ERROR: Info about fatal errors
• ² A warning will be displayed if field is incomplete and log level is either DEBUG or INFO
  
  

Streamers

The JSON object containing settings for all of the streamers we wish to monitor

Example Streamers Object:

"Streamers" : {
	"streamer-username-1" : {
		"Ban Status" : false,
		"User ID" : "123456789"
	},
	"streamer-username-2" : {
		"Ban Status" : true,
		"User ID" : "987654321"
	}
}

Streamer Object Fields:

Footnotes:

• ¹ A streamer's user ID can only be viewed using API calls, it is recommended that you use the set_config.py program in Utils/ to generate the "Streamers" field
• ² The "Soon Cooldown" field can only exist in global settings
  
  

Sidenote: Global vs. Streamer-Specific Settings

We refer to Discord/Pushover settings within the streamer object as "streamer-specific settings." These settings take precedence over "global settings" in either Discord Settings or Pushover settings. In this way, we can create global settings that will apply to all streamers, and also make fine-grain adjustments to individual streamers' settings.

Discord Settings

Global settings for Discord alerts

Example Discord Settings Object:

"Discord Settings" : {
	"Soon Cooldown" : 300,
	"Alerts" : "all",
	"Webhook URL" : "SOME WEBHOOK URL",
	"Bot Username" : "Faster Twitch Alerts",
	"Avatar URL" :   "Link to Avatar Image",
	"Discord ID" :   "Some Discord ID",
	"Message Text" : "DISCORD ALERT!"
}

Example Discord Settings Fields:

Footnotes:

• ¹ These fields must be defined for all active alert types in either global settings or streamer-specific settings otherwise the program will terminate
• ² You can find user/role ID's by activating "Developer Mode" on Discord
  
  

Discord Message Tips:

Mentions:

Users: "<@discord_id>"
Roles: "<@&discord_id>"

Using a Custom Server Emoji:

Normal:    "<:emoji_alias:emoji_id>"
Animated: "
    
     "

    

Pushover Settings

Global settings for Pushover alerts

Example Pushover Settings Object:

"Pushover Settings" : {
	"Soon Cooldown" : 300,
	"Alerts" : "all",
	"API Token" : "YOUR API TOKEN",
	"Group Key" : "YOUR GROUP KEY",
	"Devices" : "Some Devices",
	"Priority" : 1,
	"Embed URL" : "https://www.twitch.tv/{name.lower()}",
	"URL Title" : "Go To Stream",
	"Sound" : "Some Sound",
	"Message Title" : "Faster Twitch Alerts",
	"Message Text" : {
		"live" : "{name} is Live Right Now! \ud83d\udce1",
		"title" : "{name} Might Be Going Live Soon! \u231b",
		"game" : "{name} Might Be Going Live Soon! \u231b",
		"offline" : "{name} Just Went Offline \ud83d\ude14",
		"ban" : "{name} Just Got Banned \u2696\ufe0f",
		"unban" : "{name} has Been Unbanned! \ud83c\udf89"
	}
}

Example Pushover Settings Fields:

Footnotes:

• ¹ More information about Pushover alert fields
• ² These fields must be defined for all active alert types in either global settings or streamer-specific settings otherwise the program will terminate

Alert-Specific Settings

For certain fields, we may want to change our preferences based on the type of alert being triggered. This is fairly easy to do, we can simply create a JSON object of alert-type keywords and specify different parameters for each keyword.

Alert-Specific Settings Example:

Without Alert-Specific Settings:

"Message Text" : "Some Alert Message"

With Alert-Specific Settings:

"Message Text" : {
	"live"    : "Some 'Live' Message",
	"offline" : "Some 'Offline' Message",
	"ban"     : "Some 'Ban' Message",
	"unban"   : "Some 'Unban' Message",
	"title"   : "Some 'Title Change' Message",
	"game"    : "Some 'Game Change' Message"
}

Alert Types

Faster Twitch Alerts can send alerts for many types of events. Below are the keywords describing each alert type

Keyword Mapping

For the sake of efficiency, we've provided additional keywords that specify multiple alert fields. Below you can see the keywords and which alert types they map to.

Footnotes:

• ¹ Only valid for the "Alerts" field
  
  

Alerts Field

The Alerts field is used to toggle certain alert types on and off.

Valid "Alerts" Formats:

Boolean Keyword Dictionary:

"Alerts" : {
	"live"    : true
	"offline" : true,
	"ban"     : true,
	"unban"   : true,
	"title"   : true,
	"game"    : true
}

Comma-Separated Keywords in String Format:

"Alerts" : "live, offline, ban, unban, title, game"

Negation Operator:

'!' Can be used in front of a keyword to negate that keyword

Note that keywords are parsed in order, for example

• "all, !live" -> Alerts for everything except "live"
• "!live, all" -> Alerts for everything, even "live"

Special Formatting

Sometimes we want more customization beyond what a normal string can offer. For this reason we've created a special formatting system for certain fields.

Here's how it works:

Every statement in curly braces will be evaluated by the formatter. The formatter understands Python and expects a string to be returned by whatever is contained in the braces.

There are a few local variables we can use as well. These fields will change depending on the alert type and the streamer.

Due to the way Python interprets strings, we may need alternate ways to specify escape characters. Below are the currently available alternatives

Examples:

Basic Example:

"Message Text" : {
	"ban" : "{name} Was Just Banned",
	"unban" : "{name} Was Just Unbanned",
	"live" : "{name} Just Went Live",
	"offline" : "{name} Just Went Offline",
	"title" : "{name} Changed Their Title to \"{title}\"",
	"game" : "{name} Changed Their Game to \"{game}\""
}

String Formatting Example:

"Bot Username" : "{name.capitalize()} - {message.capitalize()}"

If/Else Statement Example:

"Message Text" : {
	"bans" : "{name} Was Just {'Ban' if message=='ban' else 'Unban'}ned"
}