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. You can also build your own plugins.

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

1. Clone the repository
2. Install Python (≥3.7) and the aiohttp 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'

For more detailed explanations of each field, follow the links

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

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

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 ))
  
  

Settings related to the log file

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

Footnotes:

• ¹ More Info on Log Levels:
  • DEBUG: Shows minor network errors
  • ALERT: Info about streamer activity
  • INFO: 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 ALERT
  
  

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

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

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
  
  

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.

Global settings for Discord alerts

"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",
	"Embeds" : [
		{
			"title" : "Some Title",
			"description" : "Some Description"
		}
	],
	"Message Text" : "DISCORD ALERT!"
}

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 Embed Documentation
  
  

Discord Message Tips:

Mentions:

Everyone, Here: @everyone, @here
Users: "<@discord_user_id>"
Roles: "<@&discord_role_id>"

Using a Custom Server Emoji:

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

Global settings for Pushover alerts

"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"
	}
}

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

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.

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"
}

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

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
  
  

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"

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:

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"
}

• Start by creating a python file containing a class with the name of your plugin
• You may want to store your plugin in the 'Plugins' folder for convenience
• There is an example file called 'Template.py' in the 'Plugins' folder

• In Main.py, import your module
• Add your plugin to the list of enabled plugins (Config.enabled_modules in Main.py)

• If you add your plugin's settings to config.json, you should to add a member variable called 'SETTINGS_KEY' to your module to mark the field
• There are four special functions that the main program will automatically try to use to interact with your plugin:
  1. validate()
     • This function is called before module initialization
     • Used to check that the settings for your module have been correctly specified
     • Optionally, you can return a list of 'warning' strings if you find any non-fatal issues
     • Validate.py contains some helpful functions for validation
  2. init(streamer_dict: dict)
     • This function is used to initialize your module
     • The full dictionary of streamer information is always passed to this function
     • Read Streamer.py to see what information comes with the streamer dictionary
  3. alert(streamer_obj: dict, message: str)
     • Called every time an alert is triggered for a streamer
     • A streamer's dictionary entry and the type of alert are always passed to this function
  4. terminate()
     • A 'destructor' for your plugin
     • Called immediately before the program exits
     • All exceptions that occur inside this function will be ignored
• You aren't limited to just these functions, but they're there to make your life easier
• These functions can be defined as either synchronous or asynchronous