Tribulations on adding custom Twitch alerts to Streamlabs

UPDATE 09/29/18: I’ve added a GitHub gist with all the source code from this post. I added a few comments here and there to try and explain some of my decisions. It’s pretty messy but hopefully a useful starting point for anyone looking to do this themselves. If you end up using any of the code to make something yourself please share it! I’d love to see what you come up with. If you have any questions on the source code just ask :)

On a whim I decided to create some custom Twitch alerts on Streamlabs. I'm personally not a fan of the default alert profiles that come with Streamlabs - they look boring and unprofessional. Completely custom alerts though can be expensive depending on how far the branding integration goes - so my goal was to make something that looks better than the default, but not too specific such that anyone can use them and find a way to fit the alert into their branding needs.

I'll often look to games for sources of inspiration (or more accurately - something I can replicate). Right now I've been playing and watching Dragon Ball FighterZ which has some pretty cool UI design. I particularly liked the pop-ups that announced when a round starts or a character is knocked out. With that in mind I decided to try and recreate something like this:

An average alert from Twitch has a few pieces of information in it:

• The type of alert it is (a new follower, a new subscription)
• The person triggering an alert (username)
• A short message from that person
• The donation amount or subscription duration (a number usually)

With that in mind I created this alert:

I'm a web developer, so my tools of choice are almost always HTML/CSS and JavaScript. I also used the time spent as an excuse to learn something new — the GreenSock library. It provides a powerful framework for defining complicated animations that I couldn't get just right with CSS animations alone. It provides a clear and simple syntax for defining states in an animation (going from A to B) and provides a flexible easing utilities for getting your animations to perform just so. Their documentation is really detailed and they provide plenty of examples to build from. Plus it seems pretty widely used so your average Google search should return some StackOverflow results or something. I could've built my animations using CSS alone I'm sure, but it would've been far more tedious and time-consuming. These days I'm happy to use a library that provides what I need already and learn the syntax of the library instead.

Armed with my source code, I turned to Streamlabs to insert my new alert. Thankfully Streamlabs provides custom HTML/CSS/JS for each alert type they support. Before I dove in I decided to see if they had any documentation or tutorials to help me figure this all out, which leads into my first big issue with Streamlabs' custom alert system:

There is no documentation

Streamlabs provides some pretty robust API documentation, but as far as custom alerts go there is nothing but what the default source code provides. What I'm looking for here is what kind of variables I have access to, and what kind of options I can customize. I'm forced to poke around and see what works through trial-and-error, which is pretty bad in my opinion. It would be great if Streamlabs could provide a basic set of variables that every alert has access to (the usual suspects like name, donation amount, message, etc). Thankfully from the default source code it's easy to guess the basics, but there might be more advanced things I want to tweak (like alert duration) and as far as I could tell there is no way to access these options from the HTML/CSS/JS.

Still, I was undeterred so I pasted my code into the custom HTML/CSS/JS fields and customized the Message Template field. After testing the alert I was greeted with this:

Well that's no good. The alert text font is all wrong, it's off-center, and the image isn't showing. Time to dig into the source and see what Streamlabs is up to. Before I could even do that though I realized that Streamlabs is injecting the custom code on demand, and then removing it when the alert is finished. That ends up working out for my JS code, but would personally prefer it if the custom code was always in the alertbox and shown when its needed. A JS callback would enable the custom JS code to run when its needed as well, which would eliminate the need for all the code to be injected on demand. This would also help with preloading resources, as they would already be in the DOM. As it stands, resources need to be loaded on demand which can lead to jittery animations or empty images.

I hacked my JS up and set the alert duration to a really high number so I could keep it on the screen for a while. Then it was debugging time. First order of business was figuring out why my alert was off-center. I looked to the container for the alert:

So the #alert-box container is spanning the whole page width, but not the height. That's easy enough to fix. Let's dig down the DOM tree until we can find out alert HTML.

Ah-ha! Here's our problem. Here .wrapper is where my custom HTML starts. So the container for that - #wrap - isn't spanning the whole container width and height. Got it. I'll fix that up quickly:

#alert-box {
 display: block!important;
 width: 100%;
 height: 100%;
}
#wrap {
 display: flex!important;
 align-items: center;
 justify-content: center;
 
 width: 100%;
 height: 100%;
}

I added the display: block!important because Streamlabs likes to use display: table and display: table-cell (tables in 2018? CmonBruh), so I wanted to make sure it was never applied to my alert. I also applied some flexbox properties to #wrap because that's how I centered my alert in my original concept.

Applying those CSS updates and refreshing the alertbox gives me:

Getting there. Let's look into the fonts next.

In the Font Settings configuration, Streamlabs provides a large variety of fonts (which looks to be the library of fonts provided by Google Fonts):

It just so happens the two fonts I used in my alert were "Open Sans Condensed" and "Bangers" - both of which were in that font list. I assumed they were provided in the alertbox in some way and I was good to go. Nope. The fonts used by Streamlabs are only loading the fonts used in the Font Settings config. Thinking on it after the fact - loading 800+ fonts would be pretty ridiculous, so this isn't actually that much of an issue. The annoying part though is that there isn't a way to tell Streamlabs to load a font you need outside of the Font Setting options. So what I ended up doing was adding the fonts I need to my HTML templates like so:

<link href=”https://fonts.googleapis.com/css?family=Open+Sans+Condensed:700|Bangers" rel=”stylesheet”>

Save and refresh, and I get this:

Getting warmer, but the "New follow" text is still off. Weird, because I included the font. It should be rendering it correctly now. Back to the code!

I highlighted the block that contains the "New follow" text. You can see my source for the .alert-type class on the right is being overridden by Streamlabs. Normal behavior I suppose, but... what the?! I set the Font Setting configuration to "Open Sans Condensed", but it's still loading "Open Sans"? That's not right. This might be a bug from Streamlabs' end. It's also overriding my font size and weight. In the future I'd prefer to let those be configurable, but for now I decided to just straight-up override them with every web developer's favorite CSS keyword: !important! I ended up doing this to most of my font definitions just to be safe.

.alert-type {
 font-family: ‘Open Sans Condensed’!important;
 font-weight: 700!important;
 font-size: 0.8em!important;
 text-shadow: 2px 2px 1px black;
}

Another save and refresh later:

Okay. Fonts are looking good now! Time to figure out why our image isn't showing. Diving back into the code again:

What the heck? Why is it being set to a 1x1 size? If you look at the above container (.alert-image) - it's being set as the background-image instead. Well that was unexpected to say the least. Gee, if only there was some documentation to tell me that huh?

Well, rather than try and make my alert work with a background image, I figure it'd be easier to just try and override whatever Streamlabs is doing and make it work my way. Enter our favorite keyword !important again!

.alert-image {
 background-image: none!important;
}
.alert-image img {
 width: 100%!important;
 height: 100%!important;
 opacity: 1.0!important;
 max-height: 325px;
 transform: translateY(6rem);
}
img[src=”https://streamlabs.com/alert-box/v3/null"] {
 display: none!important;
}

That last selector is for when the image isn't set. For some reason Streamlabs decided to include an image even if it isn't set and just set the path to something that doesn't exist. So when that happens I make sure that the image isn't rendered (otherwise it shows up as a broken image icon). Also made sure to hide the background-image that Streamlabs inserts.

Another another save and refresh again, and we get this:

Nice! This is looking pretty good now. I also discovered that the alert text (for things like subscriber/donator messages) also needed my earlier font changes. Now I think we can move onto the other alert categories and apply the custom HTML/CSS/JS to them. This leads me into another gripe I have with the custom alerts in Streamlabs:

There are no general templates for all alerts to use

This isn't the worst offender, but I'd still classify it as an pretty big annoyance. I think in general most streamers will use a single template for all of their alerts, and will customize the text and image to fit the type of alert that it is. All the underlying HTML/CSS/JS is all the same, its just some text and images being swapped around. As it stands right now I have to copy each individual part of the template to each alert type that Streamlabs supports, which leads to a heck of a lot of code duplication and tedious maintenance. If I want to tweak an animation or some positioning - I have to update potentially 5-7 different code blocks for a simple one-line change. This could be easily solved by having a general template that each alert implements.

So off I went copy/pasting my code in the same spots for all the different alert types. A few tedious minutes later I had everything set up. All that was left was to customize the text and image that appears in each alert.

All I really needed was a few different variables for things like donation amounts and usernames, and Streamlabs does provide them, but with a catch...

There aren't many plaintext variables

Another issue I ran into was that I couldn't figure out a way to access the plaintext versions of variables it does provide. For example, the {name}variable outputs the username that triggered the alert - but its wrapped by some default HTML that I can't remove (although I guess if I felt like it I could do that with some JS, but the fact I have to do that shouldn't be required).

Because there is no documentation, it's not clear which variables and configuration options I have access to and which I don't.

I could reliably access the following variables:

• {name} - alert username
• {messageTemplate} - the Message Template field in the config
• {amount} - the donation amount or bit cheer amount
• {count} - host view total or raid viewer total
• {img} - image from the Image field in the config

Most of those variables also insert some default HTML that can't be removed from the Streamlabs alert configuration. Streamlabs does include some configuration options called Font Settings which can override a few things, but still I think that there should be a way to access everything in just plaintext form.

I incorrectly assumed that every option in the alert configuration from Streamlabs would be accessible using a similar syntax (for example, the Alert Duration field), but I couldn't figure out how to access it. It would be great if Streamlabs could provide access to each of those variables so that the alert animations can be adjusted around the configuration options provided.

The way I coded my alerts it was a simple matter of changing a variable to change how long the alert stays on screen, but since I wanted that to be customizable I was expecting to be able to pull from the Alert Duration field’s value and use it there. What I ended up doing to get around this was use the Custom Fields that Streamlabs allows you to set up (thank goodness for that), and all the custom fields are parsed when using the {} syntax. So I created a new field like this:

{
    "alertDuration": {
        "label": "Alert Duration",
        "type": "slider",
        "name": "",
        "value": "7",
        "max": 100,
        "min": 1,
        "steps": 1
    }
}

This let me access the Alert Duration in a sort of roundabout way. It does mean though that there are two Alert Duration fields (one in the default configuration, and one in the custom fields configuration), and they must both be the same value or some unintended value occurs. This is a real pain for the end user since they’ll have to manage two fields for something simple as changing how long an alert stays on the screen. I really hope I missed something and there is a way to access the default Alert Duration field.

After applying all my custom field settings and font updates to each alert (gee, really would love it if I only had to update one template…), I was all done.

An hour or two later I was rewarded with my finished alert:

Ah... Feels good man. My plan going forward now is to give this to some streamers for them to try out (because I haven't actually tried it myself yet - guess I should start streaming huh?) and go from there. I want to make some more alerts for streamers to use.

It's my hope and dream that a team member from Streamlabs reads this post and passes it along to the team for review. I believe having a few more options would really empower other web developers to create notifications like these and get everyone out of the basic text-wiggle alert that is plaguing Twitch these days. What I hope we could see is:

• More documentation on how the alert system works and some of the configurable options available
• A full list of all the variables and fields we have access to using the curly braces, with plaintext options
• The ability to use a general template for all alerts to follow - while still keeping the option for an alert type to completely override the HTML/CSS/JS

There's totally a potential for an App Store-like model where other developers can submit their alerts for sale on a "Streamlabs Store". Providing all or even some of these suggestions would really made some strides toward it being a reality!

If you actually made it this far - thanks for reading my post! I'm planning on making more alerts and hopefully writing about those too. I’m sure I missed something while I was developing — so if you know any solutions to the problems I highlighted please let me know! If you wanna hit me up for some questions or anything, add me on Discord: Devo#0765.