Advanced Uses

This page details how to take advantage of various advanced uses and features of Firebot.

Table Of Contents

• Overlay Instances
  • Enabling Overlay Instances
  • Creating An Instance
  • Getting The New URL
  • Updating Effects
  • Things To Note
• Advanced Replace Variables
  • readApi
• Custom Variable effect
  • JSON Handling
    • Objects
    • Arrays

Overlay Instances

By default, all effects that use the overlay (videos, images, etc) show up in the same overlay. However there are some cases where you might want to have certain effects go to separate overlays.

The biggest use for this is if you have some videos that require a chroma key (greenscreen) filter in your broadcasting software, but you don't want to also apply that filter to everything else that shows up in the overlay. In this case, it would be useful to have a second instance of the overlay that only the chroma key videos would be sent to. This way you could apply the chroma key filter to just that overlay and leave the other one untouched.

Enabling Overlay Instances

To enable overlay instances, in Firebot go to Settings > Overlay > and set Overlay Instances to On.

Creating An Instance

Once overlay instances are enabled, an Edit Instances button will appear next to the setting dropdown. Clicking on that button will open the Edit Instances screen.

To add a new instance, click the Create Instance button, enter a name for the new instance, and then click Create.

Getting The New URL

Now that you've created an instance, you will see your new instance listed along with a View URL button. This button will show you the updated url for the new instance that you will need to use in your broadcasting software. Remember not to replace your current overlay in your broadcasting software, instead create a new browser source for the new instance.

Note

Due to how the url for these instances is generated, some broadcasting software wont let you select the overlay as a "local file". Instead have the broadcasting software treat the filepath to the overlay as a regular URL. If you are using OBS and do this, you must set Overlay Compatibility to Other in Firebot. Make sure to do this for both the default overlay and any extra instances you create.

Updating Effects

Now that you have created and set up your instance, you can now direct specific effects to that instance. The three effects that support instances are: Play Video, Show Image, and Show HTML.

Simply click Edit on any button that has an effect that you want to update, expand the effect, and look for the new Overlay Instance dropdown (typically towards the bottom). Select the instance that you want to use and click Save.

Now when this button is triggered, that effect will only show up on that specific overlay instance.

Things To Note

If you turn off Overlay Instances in the settings, all effects will be sent to the default overlay again automatically. If you re-enable the feature, any effects that were previously sent to a different instance will resume being sent there.

If you delete an instance, all effects that were using that instance will automatically be sent to the default one again.

Advanced Replace Variables

readApi

The $readApi[url] replace variable allows you to call out to an api and put the response in a Chat Effect, Write-to-File effect, etc. If the response is plain text, the variable will get replaced with the returned text. If the response is JSON, you can tell Firebot how to navigate through the JSON to get to the property you want (requires a basic understanding of JSON objects).

It's easiest to show in an example. Let's say you wanted to get the sparks for a user using Mixer's API.
First, insert the URL in the variable:
$readApi[https://mixer.com/api/v1/channels/ebiggz]
Then you can drill down to the "sparks" property in the "user" object like so:
$readApi[https://mixer.com/api/v1/channels/ebiggz, user.sparks]
Or make a chat effect that shows your follower number in a Follow Event:
$user just followed the channel, current follower count: $readApi[https://mixer.com/api/v1/channels/$streamer, numFollowers]

Custom Variable effect

The custom variable effect allows you to store data and reference it multiple times or reference it outside of the context of the originating effect list.

JSON handling

If the data provided for the custom variable is a valid JSON string, it will parse be parsed into an object/array before being stored (instead of just being stored as a string of text like before).

Objects

Say you have a custom variable named ebiggzinfo with the data set to:

$readApi[https://mixer.com/api/v1/channels/ebiggz]

That would store the JSON response object from the Mixer API call. You could then access various properties in that object like so:

$customVariable[ebiggzinfo, numFollowers] // gets the number of followers
$customVariable[ebiggzinfo, user.sparks] // gets spark count

Note that you can use dot notation to traverse an object. You can also use numbers to represent indexes in an array. We refer to this as the Property Path.

In the Custom Variable effect, you can use the Property Path field to update a specific property within an object. Say you have a custom variable called example with data previously set to:

{ 
   "name": "ebiggz",
   "active": true
}

You could update the active property by setting the Property Path field to "active" and the Data field to "false". Doing so would make the custom variable look like this:

{ 
   "name": "ebiggz",
   "active": false
}

Arrays

There is some special logic arrays that enables you manipulate them in various ways. Here are some examples details various array manipulation you can do:

Initialize empty array:

Data	Property Path
[]	n/a

Initialize array from string of text:

Data	Property Path
$splitText["test,foo,bar", ","]	n/a

Push new item to an existing array:

Data	Property Path
anything (except for "null" or another array)	n/a

Remove item from existing array:

Data	Property Path
null	indexNumber (ie 0, 1, 2, etc)

Replace existing array with another array:

Data	Property Path
anotherArray	n/a

Get element in array:
$customVariable[example, indexNumber]

Get arrays length:
$arrayLength[$customVariable[example]]