[Guide written using Keysight 1.6.1]

Welcome! This guide will explain how you can use GIFs inside Keysight via the Pulse object. This requires:

• A basic understanding of Pulses
  
• A square GIF you would like to display (preferably with transparency)

Here is the GIF we will be using within Keysight for the purposes of this guide

There is a limit on GIF size for this. The maximum resolution of a texture in Keysight is 16,384 pixels in any direction, and we're going to convert a GIF to be a horizontal sprite sheet of frames. This means if your GIF resolution multiplied by the number of frames is greater than 16,384: you will need to resize your GIF or cut down on the frames somehow (but it's honestly pretty difficult to exceed this limit with normal GIFs).

Keysight does not support displaying GIFs "natively". We need to turn it into a .png, and somehow keep the animation. Cue the concept of a "sprite sheet". Here's an example, rather than wasting words on them

• Head to https://ezgif.com/gif-to-sprite (this site deserves a f***ing Nobel prize, I love this site so much)
  
• Upload your GIF
  
• Select the following options: stack horizontally, 0 pixel margin, auto tile size, output format png. (Only "stack horizontally" should actually need clicking)
  
• Click "Convert to Sprite Sheet"
  
• Either click "save" and then rename it something useful, or right click on the resulting image strip and save it somewhere with your desired name

And here is the strip! Kinda doesn't display well in a Steam guide due to having 60 frames, but trust me, this is exactly what we're after

• Follow this guide as if adding a custom image to pulses
  
• Go back to the Appearance tab
  
• Configure framerate to your desired speed (once in sprite-sheet form, there is no data informing Keysight as to the intended playback speed of the GIF)

Done! (I promise this potato is animated)

While simple, sprite-sheet Pulses can be incredibly powerful. Let's run through the options available to you inside that Appearance tab and explain them in sequence first

"Use note position as static frame"

• This option actually stops the sprite sheet being animated at all. Instead, just a single frame is displayed using the note's position to determine that frame. So in the instance of our 4-frame metroid sheet from earlier: it would display frame 0, 1, 2, 3, 0, 1, 2, 3, 0, 1, 2, 3, etc. as you played notes in order. Having a specific image per note allows for doing things like note name labels! There is a Hall of Fame preset in the Discord[discord.gg] demonstrating this.

"Loop sprite animation"

• When disabled, the animation freezes on the final frame rather than playing from the beginning again. Quite a niche thing, just saves you having to add padding frames if you want an animation to play once but then fade out on the last frame a little bit.

"Start at random sprite frame"

• Adds a random offset to the frame display over time. Useful for breaking up uniformity of animation when playing chords if you have a nicely looping GIF. Do not use with "loop sprite animation" disabled.

"Randomize sprite playback direction"

• Similar to the above option, this really helps break up uniformity without needing extra GIF pulses and then using "pick from random pool" mode. Requires a looping GIF which works in both directions of course.

Setting sprite framerate to 0.00 and then enabling "start at random sprite frame" allows you to use a single pulse to display multiple different, random images by simply building a sprite sheet out of those images.

Using dynamic sprite framerate by velocity can give the same animation a different flavour with note velocity. The metroid and rotato used here as examples wiggling extra fast at high velocity is especially fun.

You can use ezgif.com to inspect the pacing of frames in a GIF if you're not sure what the framerate "should" be and don't wanna just eyeball it. The maximum framerate of a GIF is ~30fps though (so any time you go over this in Keysight, you're definitely going faster than your source GIF).

Sprite sheet pulses allow you to "bake" a complex animation generated in another piece of software into something Keysight can easily display. The "Flare" default Pulse template does this; the flare itself was generated in Blender first.

• Convert your GIF to a horizontal sprite sheet using: https://ezgif.com/gif-to-sprite
  
• Import as custom image to a Pulse, configure pulse to desired appearance
  
• Configure framerate