This guide is being broken up into a full wiki found here.[egglyberts.live] At time of writing, Concept / Troubleshooting / Gallery are all finished, and I strongly advise using the Concept pages to gain a deeper understanding of Keysight!

[Guide written using Keysight version 1.4.1, and is quite outdated]

Welcome! This guide aims to provide some orientation to new users who are (very understandably) quite overwhelmed with Keysight as a piece of software. We're going to cover: the broad concept of how Keysight works; what all the elements are; and what you can do with them



This guide is going to have a lot of text, so feel free to ignore the "spicy advanced stuff" headings if you just want the basics! And make sure to use the headings on the right if you're just looking for a specific thing. This is meant to be more of a reference sheet than a guide you read from start to finish!

Keysight is the most option-rich, configurable pre-packaged keyboard visualiser out there! However, it is not a simple, user-friendly fire-and-forget solution. Keysight is a tool, and as a tool it requires someone to actually use it in order for it to do something. I'm saying this because I've run into a lot of "I don't want to learn how to use it, I just want it to work" and, quite frankly, Keysight is simply not the right tool for delivering that experience... Although if you play with the randomizer enough you never need to touch a single option.

To go a little deeper into what Keysight is: a good way of thinking about it is that Keysight is a game, but the inputs are midi rather than mouse/keyboard/controller and the "gameplay" is generating effects. Keysight is built in Unreal Engine 4 (a game engine) in order to achieve beautiful real-time graphics, and as such a lot of the same "rules" that apply to pretty-looking games apply to Keysight. Depending on your settings, you may need a beefy computer!

Keysight is built in 3D, but with 2D visualisation in mind. By default, there is a camera a really long way away from the scene and zoomed really close in, positioned above the centre of the active visual area in order to "fake" a simple 2D scene. However, this 3D-ness can be exploited for some really cool effects, and the camera is freely position-able! (Controller is recommended for this)


Orange icon indicates the position of the camera when viewing Keysight 'normally' (not to scale. In IRL terms the 'orthographic' camera location is around 13m away from the piano). This screenshot was taken in-engine using the freecam, and using the Rainbow default preset

Keysight is a huge sprawling labyrinth of options, I know. I'm sorry, UX is really hard and it's just me making this thing! I would like to present some methods for overcoming the steep initial learning curve though

• Keysight has tooltips! Hover over any element to see what it does. Variable titles hold information relating to what that variable actually does
  
  
• Have patience! Keysight can be very difficult to use effectively. Part of this is my fault, but a lot of this is due to it simply being a complex tool. Treat Keysight like learning a new software; try to understand the logic behind how things fit together and you will quickly be able to build your own excellent custom visuals!
  
  
• "Is it possible to..?" Yep. Probably. With custom textures, GIF support and 600+ options, if you can imagine it it's probably possible to make it, but it may need some compromises/custom resources/a lot of patience

Red highlights the element in question

Dynamic effects are the above visual elements that spawn when notes happen! No notes = none of these things, and basically no Keysight

These are the moving geometry representing notes, and is the most fundamental representation of actual note events over time

They have a configurable shape, and an optional narrow or wide border that shows an independent material to the main body of the note object


All note object types with a plain white material, with a glowing wide border on rounded shape in the bottom right

• The shape of note objects can drastically affect the appearance of reflected note lighting
  
  
• A glowing border can really aid in legibility of notes in busy presets
  
  
• Note objects are optional! If you want to just have on-key-press effects on a preset, that's totally a thing

• Note objects can have velocity-driven dynamic size, and lock to only use white or black key shape variants. By locking to white-key-only and using dynamic size, note objects themselves can begin to reflect the intensity of music being played
  
  
• Notes can use dynamic speed with velocity too. This is accessible via the advanced Core menu, but it only really affects note objects and lights. This dynamic speed can allow you to make max-velocity notes suddenly snap to 5x speed, or something goofy like that! (Very niche effect, ruins the readability of notes but it's good for blowing some minds)
  
  
• Textures applied to notes can have their panning behaviour very finely controlled, including removing the "intuitive" effect of textures panning with note motion. This allows note objects to "reveal" an image as the image is static while the note object moves. These controls are found under the Material tab
  
  
• Specific note Z-heights and Z-offsets for layering purposes can be controlled, alongside the amount of "geometry influence" on reflections within the scene. This allows notes to be collapsed into 2D surfaces and re-arranged in terms of layering with other objects, and allows the "rounded" mode (for example) to become a simple circular flat surface outline once geometry influence is disabled
  
  
• Note objects will always scale to a minimum 1:1 "aspect ratio" size. If a note is released instantly, the note object will not have a 0.00 vertical size as this would be, well, stupid. The exact minimum size is configurable if you want notes to be allowed to be shorter (very useful on the Flat shape). Additionally, new notes occuring on the same channel within this minimum-scale time will force the old note to truncate in order to leave room for the new note, but this behaviour can be disabled if you wish for notes to bleed together (pretty cool with Rounded shape)

These are invisible rectangular light sources sitting above note objects, and provide the lighting both on and around note objects as they move through the scene

They can be moved further towards or away from their note object using "concentration", which alters their (you guessed it) lighting concentration around note objects


Three note lights with no note objects, with the same brightness but 0.5 / 0.75 / 1.0 concentration on a concrete backdrop. Shiny / metallic backdrops will often make concentration seem higher than shown here due to not as diffusely reflecting the note light

• As a light source, these are quite performance expensive. Anything below the Ultra graphics preset removes these lights and instead causes note objects to be "self-emissive" in order to be visible
  
  
• Being a light source, the colour of note lights is crucial to the appearance of other elements in the scene that do not have their own lighting (so, typically note objects and the backdrop). If note lights are red, and note objects are blue, note objects will *appear* black. Be very cautious when altering the colour of note lights independently from other objects
  
  
• Note lights are invisible to the camera directly, but they can be reflected by other objects in the scene and therefore viewed indirectly. This is usually desirable, as it illuminates note objects better, but with non-standard 3D camera angles, this may cause note lights to appear "de-synced" from their note object due to being reflected in a shiny backdrop. Think of it like moving an object away or towards a mirror, looking at it from an angle, and seeing the apparent "depth" of the object inside the mirror!

• The entire Keysight scene is split into three lighting channels: "Backdrop", "Notes" and "Piano". Note lights can be configured to only broadcast over specific channels. By disabling the "Notes" channel, note objects will appear black as they are non-illuminated, but the backdrop around them can still be illuminated. Looks especially good if Impact Lights are set to shine on the Notes channel, as then the bottom edges of note objects are illuminated by the impact lights alone when they are near the piano but are dark otherwise
  
  
• Setting note lights to be pure white and then setting the colour of *other elements* to the desired colour can be a powerful and highly controllable way of having very different colours between, eg, the backdrop and note objects while keeping dynamic illumination from note lights

Keypresses overlay the virtual piano in Keysight to clearly show which keys are currently being held

They are very simple, but have a configurable fade-out animation and time to avoid uncomfortable visual "snapping" when notes are released


A scene with only green glowing keypress indicators. They don't do much on their own, and are purely utility!

• If you're playing really fast stuff, consider reducing the default fade-out time on keypresses to keep the best visual clarity
  
  
• The alternate animation modes are kind of gimmicky; opacity fading is the nicest option for fade-out

• Honestly not a lot! They're very basic objects. The only thing that springs to mind is foregoing the brightly-glowing typical keypresses and instead set them to be a golden material or something, so any notes you're holding turn the piano gold..?

These are light sources that spawn above the virtual piano to indicate when keys are being pressed

The brightness of impact lights is directly tied to the simulation of the "note activity" for that key, so these lights will fade out over time faster at the upper end of the keyboard under default simulation settings

Impact lights are the only source of dynamic shadows in Keysight


Same preset with three different impact lights: standard / higher Z-height for less angled shadows / shadows disabled with smaller radius for faster rendering

• Shadow casting can be quite performance expensive. The larger the radius of influence, the harsher the performance penalty
  
  
• Impact lights can flicker their brightness and/or position over time for a pleasing candle-like effect! This is fully configurable in the Advanced menu
  
  
• By default, as sustain pedalling extends the duration of impact lighting as note activity is extended. This can be disabled under Advanced Core > Simulation if you want impact lights to snap out of existence once keys stop being held

• Since impact lights are tied to the way Keysight simulates note activity after a note-on event, editing the piano simulation values under Advanced Core > Simulation changes the die-off behaviour of impact lights. You can use this to make impact lights die off faster / slower / identically across the keyboard!
  
  
• Impact lights can also modify their height based on simulated note activity. This tends to work best with a strong positive curve to give it a nice animation, set to broadcast on the backdrop lighting channel, with note objects + lights disabled. This gives impact lights an alternate function to be kind of bouncy balloon lights showing note activity and is an entirely different visualisation style! The "RGB" default preset on Ultra and High uses this lighting mode
  
  
• Even without dynamic positioning, shifting the position of impact lights up or down slightly in the Y and Z axes can give different-looking shadows and reflected highlights. This, alongside configurable time to blend from inactive to the target active brightness, can result in very finely controlled impact lighting "texture"

This is the most flexible element in Keysight. Pulses are a single plane with a configurable size, rotation, position and opacity animation that spawn when a note is played

Pulses take stencil images (aka masks / cut-outs) to change their shape to any outline you want, and also support sprite sheets (so, GIFs, but combined into a single image)


Different pulse implementations. From left-to-right, top-bottom: Keysight default preset with standard circles; Ghostly preset with mist; Honey preset with rising hexagons and mist; Steampunk preset with mist and rotating squares; Candy preset with overlaying huge expanding circles; custom import of a baby metroid sprite (it is animated in-engine)

• Pulses are fairly cheap to render on the GPU, but with many pulse slots, CPU performance may suffer due to needing to calculate a lot of animation curves
  
  
• Pulses are fantastic at giving note events some extra impact and "visual texture". Having a faint semi-transparent "Fade" pulse can provide the appearance of haze above the keyboard as many notes are played, for example
  
  
• The randomizer will generate new pulses, but will not really showcase any of the really cool stuff they can do. Highly recommended to dig into options yourself to really make use of pulses!
  
  
• The default pulse origin is the centre of the pulse plane, but this can be changed to be the bottom edge of the plane to better show an image stencil if desired

Oh jeez. So much stuff.

• Pulses can abandon their usual colour struct and use only the colour of the stencil file used. By importing your own texture file of an image and then setting the pulse to "only use stencil colour" in Appearance, you can have pulses flash images on note events
  
  
• Pulses support a "random pool" mode, allowing a preset to have, eg, 5 pulse slots but each note picks a random pulse from that set of 5 and spawns only that pulse. By building a nice pulse, duplicating it a bunch, changing the stencil used on duplicates, and then enabling random pool mode you can have varied pulse stencils within a single preset
  
  
• Pulses also support velocity-based activation, so only note events with a velocity inside the allowed window will trigger the pulse to spawn. This can stack with random pool mode (random pool first evaluates which pulses *can* spawn based on velocity activation, and then picks one from that list). Velocity is derived from the simulation-mapped velocity-to-note-activity sliders
  
  
• Pulses can move over time, allowing them to float upwards!
  
  
• Pulses can be time-offset in their spawning, which is particularly useful in top-down visualisation mode. This could allow combo pulses like a pulse that spawns 1 second "early", collapses over the course of its 1 second lifetime, and then a second expanding pulse spawns at the normal time to give an implosion-explosion effect. Careful tuning of time offsets and position over time can also allow you to "bind" a pulse to an approaching note in top-down mode
  
  
• Pulse stencils support sprite sheets with configurable sprite animation speed. Keysight expects sprites to be horizontal sets of square images, and these can be generated using GIFs and ezgif[ezgif.com]. Just take a moment to conceptualise how incredibly powerful this is; to be able to import your own animations and move/rotate/scale/fade them based on midi triggers! Obviously it takes a lot of custom work to make this happen, but the possibilities are endless

These are probably the immediately exciting element in Keysight! Particles are tiny planes showing a stencil that are typically spawned in huge numbers with complex motion

Particles come in "systems" and "templates". A "template" is a collection of "systems" that have been configured and locked down; a "system" is one set of path animation / particle behaviour / colour settings. For example, the "Plasma" template contains two systems: "Plasma (low)" and "Plasma (high)" in order to generate two different streams of plasma. Loading the Plasma template loads both contained systems automatically. Keysight comes with many pre-configured particle templates which can be further tweaked in the Advanced > Effects > Particles menu.

Systems can be fully configured by the user by enabling "full template editor mode", and then exported to a shareable, re-useable template! All templates in Keysight were made within Keysight in this way; there is only actually one "particle system" object that Keysight uses!


Just a few of the built in particle templates. From left-right, top-bottom: Aurora, Jets, Plasma, Rising Haze, Steam, Sparks

• Particle GPU rendering cost goes up sharply with the number of pixels that particles take up on screen, and this includes overlaid particles. A large number of large particles will run slower than an even larger number of smaller particles. There is a loose performance metric given under Information for each particle system in the Advanced menu
  
  
• Particle CPU processing cost goes up quite substantially by using the "use dynamic velocity" mode, but this allows particle systems to change over time as note activity dies away based on piano simulation settings
  
  
• Particles can often dominate a preset, be careful to tune particle brightness and amount to keep notes legible! (Or, you know, double down and just have crazy particle counts. It's pretty fun)
  
  
• Some particle templates react to "note force", which is a sort of simulated gravity force generated by note activity that can blow around particles dynamically. This note force response can be tuned in the Advanced Core > Simulation menu

• Like pulses, particle systems can have a minimum or maximum velocity required to spawn at all. This allows specific particle systems to only kick in for the loudest notes, for example. When doing this, the min/max note activity is remapped within the particle system using their min/max spawning velocity (with 0.2 min note activity to spawn a system, a note activity of 0.6 is treated as 0.5 within that spawned particle system as it is halfway between 0.2 and 1.0)
  
  
• This dynamic activation at the higher end works well when combined with "use dynamic velocity over time" and a minimum particle spawn count of 0 particles. This allows strong notes to spawn a system that quickly fades out as the note fades out, stopping it from dominating a preset quite so much
  
  
• As with every element, particles can use custom textures! Larger particles using the translucent blend mode and a custom texture benefit from lower spawn counts, and this lets you have something like, I don't know, emote explosions!
  
  
• Again, similar to pulses, particles have a "random pool" mode. This allows a random single system to be picked from any allowable systems in the preset to be spawned with a note event, rather than all of them. By duplicating your target system, changing the texture used in each duplicate and using random pool mode, you can give notes a random image texture to use for their particles
  
  
• If you're brave enough to dig into building your own particle systems/templates from scratch, playing with accelerations over time can give incredibly complex emergent particle pathing. It is recommended to keep note-activity-based particle behaviour to a minimum and instead rely on note-activity-based path stretching and simulation speed. This allows you to have very fine control over the particle behaviour and then modulate it "at the end", reducing likely-unwanted emergent behaviour as note activity changes

Red highlights the element in question. Using not-recommended ambient lighting to show the scene clearly with no dynamic lighting active

The Keysight scene is not completely empty when no note activity is happening! Think of these static elements as your canvas on which to paint dynamic effects. As such, these non-reactive elements can still have a huge impact on the feel of a preset

This is a plane that sits behind all other elements in the Keysight scene that is illuminated over the "backdrop" lighting channel. While simple in concept, the material settings for the backdrop have a huge determining factor on how a preset looks, and backdrops are a great place to import custom screenshots!


Same preset, different backdrops. Take a look at the huge variance in apparent note light brightness around the note just by changing the material

• Becoming familiar with the material editor will allow you to unlock the full potential of custom backdrops, see the section below!
  
  
• The human eye enjoys subtle detail, even if it doesn't consciously observe it. Even if you want a plain backdrop, experiment with having just a low-strength normal map enabled to give it some bumpiness
  
  
• Be very careful when using a flat colour for the base colour of the backdrop. The backdrop is usually only seen via other light sources, so if both light source and backdrop are coloured you may have unwanted / unexpected visuals from the colours "multiplying" together

• Backdrop textures support panning over time. This allows you to do some weird trippy effects with a "moving background"!
  
  
• As seen in the example screenshot, importing of custom textures allows for themed, beautiful presets. If you look closely, the note light seems to be "saturating" the backdrop as it moves through the scene. This is achieved via having a de-saturated image as the emissive-colour of the backdrop (so, it is always shown, but dimly) and then the base-colour being the saturated version. Lights illuminate the base colour, revealing the base colour "through" the emissive colour!
  
  
• Backdrops are optional, and can be disabled entirely in the Advanced Scene menu if you just want to show the "void colour" (that is, the colour set under Scene > Lighting which shows when there is nothing to render). This is not particularly recommended, since one can simply disable note lights and impact lights from shining over the "backdrop" channel to stop the backdrop showing
  
  
• With a very reflective (ie low roughness on the material, see below) backdrop and a default "2D" camera angle, note lights themselves can become sharply-reflected enough to accurately show notes. The "Toxic" default preset showcases this effect

The overlay is a secondary backdrop, with a configurable height and locked material set. It is a plane that fills the active area the same as the backdrop, but has configurable lighting channel response. This allows for a mask to sit on top of other elements in the scene, or to augment the backdrop appearance

• Be careful with layering! By default, pulses and particles sit at 0.025 height and the overlay is at 0.01, so it should be behind everything. Maybe double check this is the case, if this is what you want!
  
  
• Using the *almost* the same material for the overlay as the backdrop, and then using an opacity mask, will provide a pseudo-blended material for the backdrop. This can be useful for, say, adding a scratched gold filigree onto a concrete background without having to manually make those textures
  
  
• Lighting channels are controllable for the overlay, combined with the above idea this means by setting impact lights to broadcast over the Notes channel, and setting overlay to Backdrop+Notes, the overlay can shine with impact lighting while the actual backdrop does not

If I need to explain what a piano key is and what it looks like, I have serious concerns as to why you're reading a guide for Keysight...

So, skipping past that: piano keys have a velocity-based animation, and an attached "damper" visualisation that shows sustain and sostenuto pedalling (for all 7 people in the world who do that). They also have configurable materials and length

• At 1.0 size, piano keys are accurate to the dimensions of a Roland FP-30's keys. However, this looks kinda goofy and too-long from the top-down default angle, so it is recommended to use a shorter length for a pleasing visual composition
  
  
• At significantly smaller sizes, dynamic shadows may stop rendering due to too-small a height difference between black keys and white keys
  
  
• Animation speed for keys is configurable, this is found under Core > Visual layout
  
  
• Using different materials / colours for piano keys and the felt strip can really tie a preset together! Check out "Rainbow" default preset and note the colour matching of the felt strip across the default presets
  
  
• For seriously advanced users, the entire piano portion can be "disconnected" from the active visualisation area and rotated / positioned. This allows for weird "upright piano" style visualisation or an angled keyboard. Potentially useful for AR implementations where you want notes coming up from a piano rather than "out"

Keysight attempts to show as much musical information as possible, and part of this is sustain/sostenuto pedal display in the form of "dampers". These are small curved blocks of geometry with a triangle of felt intended to represent the physical dampers inside a piano, and each piano key has its respective damper. Dampers are not uniform width in order for everything to fit together nicely (piano key spacing is weird, ok)

• These are optional, and can be disabled under Advanced Scene > Damper visualisation (the tab toggle). Just in case you don't want to show your pedalling to the world, or you find the raising and lowering damper bar distracting
  
  
• Dampers have a configurable animation distance, and toggleable visibility and colour on the damper felt to control their overall presence in the preset
  
  
• Dampers are modelled to have a "believable" proportion at 1.00 Y/Z-scale (it's hard to say realistic because the whole design is made-up). However, by default they are squashed down almost flat so as to layer with other components in the scene better. They sit at 0.1cm above the backdrop by default too, putting them below notes but above typical pulses and particles
  
  
• Dampers also have a configurable material, and respond over the backdrop lighting channel

These are small strips of geometry sitting just above the backdrop at each border between B and C keys. They have a configurable material, and typically are slightly self-emissive with a grey colour to mimic the look of other visualisers out there

• Octave lines sit at just above the backdrop, and cannot be moved
  
  
• Giving these a glowing material can look... weird, and kind of cool?
  
  
• Theoretically, one could make a mask with "marker" lines to apply to the octave material, and match this with the speed of notes and the tempo of the piece to show, like, one measure of music's worth of not displacement? I don't know, these aren't a rich source of configuration like the other elements

This is the border around the active area of Keysight. The virtual piano holder portion of the frame is loosely modelled on a Roland FP-30, and it has a non-configurable dark plastic kind of material. It exists solely to show something if you use a non-default camera angle, and is not particularly configurable

The only thing to note here is that the frame is optional, and can be disabled under Scene > Frame and Piano. This is useful for mask-mode implementations where you do not want the border to show (as the frame is treated as fully-opaque)

If using the niche "extend backdrop bounds horizontally" for canvas-style Keysight effects, the sides of the frame will be automatically hidden

There are a few very important menu modules which can be found across a preset. Understanding how these modules function will really help when performing advanced preset creation!

These menu modules are found across Keysight, and are used to describe how one variable changes against another variable.

Graphical editors allow you to quickly give tons of elements a dynamic response to things like note activity, leading to presets that show what is happening musically with greater clarity!

Graphical editors encompass 8 points of data: the min/max effect strength; the start/stop point for min/max effect response; min/max graph bounds; curvature; and whether or not this is a flat value. If a graphical editor is "flat", it uses only the max effect strength value.



Here is a breakdown of what all the buttons do! To edit a value, simply click and drag the handle


Just to explain "response curve" a little more: this allows the variable response to be non-linear, which is incredibly useful for nice-looking animations where you are doing things like size-over-lifetime. At maximum curvature, the response is essentially a "quarter circle" up or down

• All values can be typed manually, and snapping can be temporarily disabled by holding down the alt key while dragging a handle
  
  
• Hovering over the title of a variable will show you information about what it does within Keysight
  
  
• As shown graphically, the effect is clamped to the minimum and maximum values given. Dragging handles "inwards" in the X axis means, for example, the maximum effect will stop changing above this point in the response curve
  
  
• When provided two graphical editors for one variable (eg pulse size over lifetime), these are multiplied together, and enable two-stage variable response (so, growing larger and then smaller). When manipulating pairs of graphical editors, think about how your given values multiply against each other at each point in the response curve

In basic menu mode, all dynamic objects in Keysight use a single set of colour settings (or more accurately, the Basic menu mode edits the Note Light colour settings and then duplicated that to all objects). In advanced mode, each dynamic object has its own set of colour settings

Colour settings allow you to use colour to represent various things that are happening musically! You can have up to 12 colour slots, and there are 8 different modes


Same preset, same R/G/B colours, 6 different colour modes

From left/right, top/bottom:

Each new note-on event causes the colour settings to use the next colour slot, before wrapping around to the beginning once slots are exhausted. With any significant volume of notes, this gives notes a functionally-random colour, but with the benefit of an even distribution with fewer notes

Note activity is used as a value to blend between the given colour slots. With red/green/blue, a note activity of 0.25 gives a colour halfway between red and green. An activity of 0.75 gives a colour halfway between green and blue. Blending is performed in the hue / saturation / value colour space, so be careful when blending between two "distant" colours on a colour wheel (like purple and yellow)!

The note position on the keyboard is used as a 0.0-1.0 blending factor between the given colour slots, giving a smooth colour gradient along the keyboard.

The note position is used as the slot-lookup within the given slots (and wraps around once it exceeds the number of available colour slots). This means that each note has a specific, deterministic colour. With 12 slots, wrapping occurs once per octave, giving each note a specific colour slot!

Colours blend through given slots over time with a given beats-per-minute speed. Blending is performed in H/S/V space. Difficult to show in static image form, but great for high energy presets! Worth noting is that pure blue looks visually darker to the human eye than other colours, so be careful when blending through blue rapidly as this can appear to cause a kind of pulsing brightness.

The current notes per second is used alongside sensitivity under Advanced Core > Simulation, and min/max notes-per-second, to generate a 0.0-1.0 blending factor between the given colour slots. This allows a preset to change colour as the music gets faster, but it may need to be dialled in to the specific piece of music

Very similar to the above mode, but the current total note activity is used to generate the 0.0-1.0 value instead of simple notes per second. This means that sustain pedalling lots of ringing notes can drastically alter colour even if playing speed is consistent, or the same notes played louder and louder can change colour. However, this is usually inferior to "velocity" mode

A new colour is randomly selected from the available colour slot every single frame. Be very very cautious using this on anything other than particles! On particles, this locks in the particle colour to functionally a random colour from the slots given, which can be useful for having a specific spread of colours within one particle system

A bunch of elements in Keysight have a configurable material. Material editing can range from very simple to very complex, depending on the mode used and the desired effect! I'm a 3D artist by trade, so the material editor sticks to your usual physically-based-rendering sorts of ideas. For more information about those, have a read of this[docs.unrealengine.com]


From left/right, top/bottom: Advanced mode with rusted metal textures; semi-transparent body with a glowing border; blended mode with circuit mask, one half emissive, one half metal, with glowing border; blended mode with one half metal, one half plastic, black border; simple plastic; simple metal

• Basic - uses a flat base / emissive colour, with one value for metalness / roughness / specularity. Simplest looking and simplest to use material mode
  
  
• Advanced - has switches to use either a texture file or a value for base colour / emissive colour / metalness / roughness / specularity. Also supports mask-based binary transparency (so, opaque or fully transparent), and normal mapping. This is the mode used for realistic fully-textured materials, but by mixing and matching textures and flat values all sorts of custom materials can be built!
  
  
• Blended - this is essentially two basic materials glued together. It has two sets of colour information and two flat values for metalness / roughness / specularity. Has a lot of potential for making clean but patterned materials, having a glowing pattern, or having two sets of dynamic colours
  
  
• Transparent - this material does not accept any lighting from the scene at all, but is the only material mode to support semi-transparency. It uses emissive colour only, with optional transparency mask and a flat value for opacity. Flat value is multiplied against the mask value for transparency

I'd like to quickly take some time to talk about performance and making sure Keysight looks as good as possible in your setup. Please do not just skip over this thinking "it's fine", because if it isn't fine, people are not going to want to watch your stuff! (Seriously, I've seen a lot of disaster setups that could have been solved with 5 minutes of tuning before going live with it...)

Keysight has a handy "turbo note testing mode" which can provide a reasonable worst-case-scenario framerate for your current visualisation settings. It will spawn a new note in a random location, with a random velocity, for a random duration every 0.1 seconds. This is accessible by pressing shift+Q, which toggles the mode on or off. A built-in framerate counter is also toggle-able with the C key, and I would recommend disabling v-sync to unlock the framerate under Graphics > Framerate (if you leave v-sync on, you could be just about managing 62 fps or you could be hitting 200+, but both will lock and show 60 which may impact your decision making).

This type of testing is useful for getting a quick baseline, but the smooth flow of notes is not always representative of how real pieces will perform. The built-in Chopin midi file in the Midi menu provides an alternate, loop-able test that plays some sharp, repeated chords. Finally, running your hands along the keys for glissandos provides the ultimate worst-case for Keysight!

Running the Chopin midi with "Fire" default preset at 720p, with 200% resolution scale (so 1440p effective render resolution), on an RTX 2060 super + Ryzen 3900X with the framerate counter enabled on the right

The more things that are on-screen, the slower Keysight will run. Especially lights! So a glissando with the pedal down will spawn a ton of notes and note lights, and a ton of impact lights which stick around for a while. Aim for comfortably maintaining 60fps (so, preferably running at 80+) while providing a reasonable worst-case-scenario for the music you're likely to be playing!

Another thing to consider carefully is how Keysight is actually integrated into your scene. It is rare to want Keysight as just a fullscreen 16:9 window, and it is far better to configure Keysight to be the shape you want than to squash/stretch/crop externally!

For example: do you only need 60% of the height of Keysight running in a normal 16:9 aspect ratio? Consider lowering the frame height under Core > Behaviour settings, and optionally moving the camera in the Y axis under Core > 3D camera. Having a shorter frame height will reduce the duration of notes on screen, leading to better performance and smoothly shrinking notes at the top of the screen versus leaving it default and cropping it later! The vertical scale of the virtual keyboard can also be controlled under Core > visual layout


Do you use Keysight as a picture-in-picture small section of your stream/video? Consider lowering the resolution scale or the resolution of Keysight! For example, if you stream at 720p, there is no reason to run Keysight at 1080p with 100% resolution scale. Either make Keysight windowed at your target resolution, or reduce resolution scale under Graphics > Resolution to vastly cut down on GPU resource cost!

Finally, as a heads up: "top-down" note direction under Core > Behaviour can be used live to achieve a "live synthesia tutorial" kind of effect, blowing minds everywhere. Refer to this guide for more information!

Now, the last thing I want is for you to accidentally lose a bunch of hard work, so let's talk about data handling. Keysight has two primary places it loads and saves data:

• The install directory - this is typically under Steam / steamapps / common / Keysight. Default Keysight content like the default textures, presets and particles are stored here, along with midi files
  
• The "Saved" directory - this typically under Users / [you] / Appdata / Local / Keysight / Saved. Any data you generate through using Keysight is saved here, such as presets, graphics config, etc.

Saving can be performed with Ctrl+S to save everything to their respective files, or by using the buttons in the bottom left corner of the menu, or by selecting "Save and quit" when exiting Keysight

Every preset slot has an associated preset JSON file containing its data. This file can be opened and read in any text editor, although it is an un-formatted JSON so you may want Notepad++ or something to make it a little more readable! These files are found under /Saved/Presets. Any time a preset is saved, the old version is moved to Saved/Presets (backup) and any corresponding file there is deleted, in order to give one level of safety in the event of accidental data loss through overwriting

The preset bar at the top of the Keysight menu is the place to manipulate save data


Small thing to note is that re-ordering presets required any moved presets to be re-saved, as the order index is saved per-preset into the preset itself. So moving a preset left and saving it will give it the same order index as the preset to the right, until that preset is also saved with its new order index

Along with preset data, there's all sorts of important stuff that needs to be saved, such as your chosen midi device / graphics preset etc. This is saved to a non-readable file called SystemStruct.sav under Saved/SaveGames. System settings also contains the "global core" used by presets in this (default) mode. This can be saved individually without saving anything else with the button at the bottom right of the screen

Other non-critical and non-preset information typically has its own .sav file under Saved/SaveGames too. This includes: randomizer configuration; menu styling (this is broken out from system settings so that it is shareable); hotkey configuration; defaults configuration (to allow the default preset to be changed); and stats to track your notes! These can all be saved individually without saving anything else with the button at the bottom right of the screen (except stats, which autosaves whenever there is a break in note activity and notes have been played)

Custom textures can be imported for different purposes under Saved/Textures/[subfolder]. For more information about actually using custom textures, check out this guide! Once placed into their respective folders, textures will not appear in Keysight until they have been re-imported. This can be done next to pretty much every texture dropdown menu, or by re-launching Keysight

This Saved/Textures folder does not add these textures into the randomizer, since often textures are intended for a specific purpose in a specific preset and do not work well outside of it. However, if you want to add your own custom particle stencils or masks and have them show up in the randomizer, drop them into Saved/Textures (randomizer enabled)/[subfolder] instead!

If you're brave enough to build your own particle templates, these are saved as JSON files under Saved/Particles. This location is also where I would recommend you import any shared particle templates, just make sure to hit the reload button in Advanced Effects > Particles

The default preset loadouts are found under Keysight/Default presets/[graphics preset]. When re-importing default presets, Keysight checks for any active preset slots with the name of each default preset. If it finds an existing preset slot with a matching name, the existing slot is overwritten with the default preset. Otherwise the default preset is imported as a new slot. When importing / re-importing default presets, the default preset called "Plain (default)" is applied to the Defaults.sav file as the preset used by the randomizer as the baseline, and as the "add new preset" button's preset.

The words "preset" and "default" now do not sound like words to me D: sorry

Every texture used in Keysight is included as a separate file under Keysight/Default textures/[subfolder]. This allows you to use these files elsewhere, if you like! (Textures, unless hand-made by me, were taken from ambientCG with CC0 licensing so you're free to do whatever with 'em!)

You can add or remove entire texture sets from the Default textures location. By deleting "Cushion.jpg" from Colour/Metal/Normal/Roughness/Specular, this will stop Cushion from showing up as a possible texture inside the randomizer. By adding a file with the same name to all 4 folders, this file is treated as a "complete texture set" by the randomizer and will show up as a possible material! This is pretty advanced, niche stuff but this allows you to add your own custom material sets to Keysight

These are identical to any particle templates created and saved in the Saved directory, but are ones that I have made for you myself and packaged with Keysight under Keysight/Particles. The only thing to note here is that by editing the file of a default particle template and changing "useInRandomizer=true" to "useInRandomizer=false" will stop this template from ever being picked by the randomizer. Useful if you hate a specific template showing up but don't want to outright delete it, or a template is causing performance issues when picked

These are stored under Keysight/Midi, with one file included by default. As the end-user, you are intended to import your own midi files in this location too (rather than the Saved directory). After importing, files will automatically appear in the dropdown menu (or more accurately, it re-scans for midi files upon opening the dropdown)