Spark AR: How to add instructions to an Instagram Filter

Using the Patch Editor to control Instructions within your experience

Luke Hurd
Luke Hurd
Jun 25, 2019 · 7 min read

Instagram filters have experienced an explosion of popularity lately, and it’s becoming increasingly important to have the best experience possible for your users. One of the key ways to ensuring your effect is enjoyed by as many people as possible is to include a set of instructions within your filter.

Spark AR, the development tool for Instagram and Facebook filters, makes adding instructions a breeze — if you understand how to do it.

First, you need to need to create a new/open an existing project and add the Instructions capability to your filter. You do this by going to Project in the menubar and selecting Edit Properties.

Once the Properties dialog window is open, select Capabilities. At the bottom of the window, click the [+] button and type “Instructions” and then highlight the Instructions capability and click “Add”.

You can also choose which platforms you would like to publish to under the “Platforms” section.

Next, we need to choose which instructions we need for our filter.

I have some bad news — you can’t just make whatever instructions you want. You have to select them from a list and the list isn’t extensive. The reason for the lack of instructions is because they need to be reliably translated for various countries around the world.

Hopefully at some point we’ll have instructions for all available gestures (blink, swipe left/right, etc) but for now we have a short list to choose from and we need to make the best of it. If you want to see more instructions added to this list, please request them in the Spark AR Community with the hashtag #featurerequest (use this!). Make sure it’s something that everyone can benefit from and not just for your own filter.

To see what what is available, highlight the Capabilities area in the Properties window and expand Instructions. The first thing you need to do is uncheck Automatic Instructions and check Custom Instructions, then expand it and click the [+] button:

This is the list of all available instructions you can add to your filter.

You’ll notice a few repeats in there (“Open your mouth” vs “Open your mouth!”) and you’ll notice the lack of a few obvious ones (“Blink your eyes”). This software is still in beta, as is the platform itself — so just keep that in mind and try to be as creative as you can to help users figure out the other interactions that might not be listed here.

For this example, I am going to use “Face a face!” and “Open your mouth”. When you add one, you just need to click the [+] again to add the next one. Note the name of the token that is displayed for each instruction — these will be important later on.

find_face and open_your_mouth are the tokens for these instructions.

Once you have added the instructions you wish to use, close the Properties window and return to Spark AR.

First, let’s understand how we can add “automatic” instructions to our filter. By “automatic” I mean that I want a set of instructions to display immediately when the filter is started for a period of time — lets say five seconds — and then disappear. The good news is, Spark AR already has this ready for you.

First click on Device under the Scene view. On the right hand side, your Inspector should show the options for your Device. Click the + button by “Actions” and choose “Instructions On Opening”.

This will create a patch for your filter in the Patch Editor.

Let’s breakdown how this works.

Each one of these boxes (two gray, one blue) is called a “patch”. When you connect the patches together, they are called a “graph”.

The logic of this graph is “if the Runtime value is less than 5, uncheck this box, which disables the instructions”.

In other words, “hide the instructions after 5 seconds”.

The first patch is called Runtime. This is an always-running stopwatch in your filter.

Next, the Less Than patch is connected to Runtime, and the value is “5”. On the right side of the patch, you can see a checkbox. This checkbox starts out already checked and after five seconds, is unchecked.

The last step is to connect the checkbox on the Less Than patch to the “enabled” checkbox on the Instructions patch.

After 5 seconds, the box unchecks and the instructions are disabled.

Pretty easy to understand, right? Now, let’s change what the instructions say.

If you look in the example screenshots, in the Instructions patch you’ll see a value called Token. This is where our tokens come into play from our instructions that we added up above. In this example I have find_face as the instructions that are being displayed when the filter opens, but I want to change them to open_your_mouth.

Just double-click the Token field and change it to open_your_mouth.

Change the value then restart the filter to see the new instruction.

We could stop here if that’s all you really need for your filter.

Or, we could make the instructions a little smarter. It all depends on how your effect works and what you feel like explaining.

For the sake of this example, we’re going to assume that I am making an effect that requires someone‘s face. I could use a timer, but I’d rather make this a little smarter. Instead, how about we show the “Find a Face” Instruction until it detects a face, regardless of time?

Nothing to it!

First, remove all the other patches from the graph until you just have the Instructions patch. Change the Token back to find_face.

Next, right-click in the patch editor and add the Face Finder patch to your graph. This patch will give you a count of the faces in the scene — even if you don’t have a facetracker in the scene.

Once that is added, add the Less Than patch and change the value to “1”, since we want to detect when there is less than one face in the scene to show the instruction.

Connect it all together like in the screenshot above, reset the filter, and then you’re all done. To test, you can toggle back and forth in between the video with a face and the plane scene:

We could stop here if that’s all you really need for your filter.

Or, we could make the instructions a little more explanatory. It all depends on how your effect works and what you feel like explaining.

For the sake of this example, we’re going to assume I need a user to open their mouth. When I detect a face, I want the instruction to say “Open your mouth” — but I only want that instruction to appear once a face is in the scene. If the face ever leaves the scene, the instructions should return to “Find a face!”.

Here is the complete graph. The patch is extremely similar to the previous example, but we’ve added an If Then Else and an Option Picker patch in between the Less Than and Instructions patches.

On the If Then Else patch, the Then value is 0 and the Else value is 1— this means the underlying logic is “if this condition is met, then pick option 0, otherwise pick option 1”.

The reason we have 0 and 1 — not 1 and 2 — is a programming thing called a “zero index” — we don’t need to go into that right now, but just understand that the Option Picker’s first option is 0, the second is 1, the third is 2, and so on.

Speaking of the Option Picker, let’s add that patch to the scene so that we actually have options to pick from! The Option Picker usually doesn’t come set up correctly by default. You’ll need to change it to a “text” type in order to pass the token names. Click the Option Picker patch to highlight it, right click, and select Type>Text.

Now, you can type all of the tokens of the instructions you’ve added to your project into the available option slots of the Option Picker patch. Just double click each slot and type in the tokens you want to display. In this example, you can see that I have already added find_face and open_your_mouth to the options.

Connect everything together, restart your effect and test it out!

Find a face! with no faces, Open you mouth! with a face detected

Using logic and the option picker is the key to being able to use multiple instructions for your effect.

From this point, you could add a “if mouth is open hide the instructions patch” logic and add yet one more step in the finesse of how the instructions work within your filter. If you’re curious, that looks a little something like this:

Again, it all depends on how you want your filter to work.

Instagram: @lukehurd
Facebook: Luke Hurd
YouTube: Luke Hurd

Luke Hurd

Written by

Luke Hurd

Digital Immersion Director @ Signal Theory

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade