VS 1 Help

Thank you for your interest in VS - Visual Synthesizer.

VS provides an easy and intuitive way to create reactive visuals from your musical projects and compositions. It consists of a collection of customisable materials which can be blended together to create personalised visual compositions.

VS - Visual Synthesizer is much more than just a traditional music visualisation tool. It is designed to help you express your musical creativity graphically, by giving you the power of control and customisation using both audio and MIDI. It takes a synthesizer approach to the world of audio visualisation, making creation of visuals much more accessible to musicians than it has been till now.

Don't hesitate to contact us if you any questions, comments or other inquiries.

Contents

• Overview
• Layer Manager
• Layer Controls
• Layer Modulations
• Settings

Overview

VS is an additive synthesizer in which oscillators do not produce sound, but visuals. These oscillators are called materials. Just like an audio oscillator will produce a distinct sound, a material produces a unique visual output. A material can have one or more parameters that can alter its characteristics. Materials are loaded into layers.

A layer is a polyphonic synthesis engine which means that the same material can be played by multiple voices. Different voices have different characteristics and this could affect particularites of a material assigned to a layer, resulting in increased expressiveness. Layers play an important role in VS, as you can stack them in order to create your visual composition. In VS there are 8 layers. Additionally there is a background layer with special characteristics.

User Interface

VS’s interface consists of the following elements:

1. Help - This launches a set of quickstart tool tips to guide you through your first steps of navigating the VS interface
2. Frame Rate Counter - This is useful for you to see if you are achieving your target frame rate. If your frame rate is too low, you can try reducing the quality to achieve better performance
3. Undo/Redo - allows you to undo / redo changes
4. Layer manager - view, select, edit and reorder your layers here
5. Expand window - resizes the render area to fit the entire window and hides all overlays and controls, for a performance mode experience. To return to the interface mode, double click anywhere inside the window
6. Launch external display - this opens an additional separate render area window, containing no overlays and controls, which can be toggled fullscreen with the ‘F’ key. This mode is suitable for live performance and VJ use, to generate a clean feed of the render output for projection or video capture, while being able to use VS controls on another screen. This option is only available in the desktop version of VS.
7. Record button - records VS' render output to disk as a video file. Press once to start recording, then press again to stop recording. The file will be saved to your VS 'Recordings' Folder. (note: check the 'Recording Quality' option in the settings menu, prior to recording)
8. Layer Controls - access the current layer’s parameter controls
9. Layer Modulations - edit LFOs, envelope generators and audio modulators here
10. Show/hide Layer Modulations - increases size of render area by collapsing the modulation section

The status bar across the top of VS' window includes the following labelled elements:

• MIDI Learn - Assign VS parameter control to a MIDI controller. Select to toggle on/off. Once on, press the desired parameter to make the mapping
• Clock source - select timing/tempo source
• Tempo - shows VS current tempo BPM (this value is editable using the + and - buttons which appear when tempo is selected, if clock source is set to ‘Internal’ or ‘Link’
• Patch - show/hide VS patch manager

The status bar also contains four icon buttons (from left to right):

• Disk icon - save current patch state
• Revert icon - revert current patch to its last saved/original state
• Up arrow - select the current bank’s previous patch
• Down arrow - select the current bank’s next patch

Layer Manager

The Layer Manager allows you to select layers, load materials via the material browser and set the Z index (stacking order) of the layers.

There are 8 numbered material layers, plus one background layer, ‘B’. The background layer can use either a video or image file; it cannot load materials. Background layer honours selected color when no media is loaded. By default the background layer color is black.

Each layer item has a live preview of its current material. If the layer is disabled, the preview changes to black. (Animated thumbnails can be toggled in settings menu)

Layers are rendered in a stack; the leftmost layer is top, and the very bottom layer is the background layer on the right. To reorder the layers, click and drag each layer to the new desired position.

Clicking and holding a layer will open its additional options:

• Materials - open the material browser
• Copy - copy the layer that is in the selected slot to memory
• Paste - paste the layer that is in memory into the selected slot
• Reset - open the reset layer form

The reset layer form has three options:

• Material - resets the layer to the default 'plain color' material
• Reset Material Parameters - resets the layer's material parameters to their default values
• Reset Modulation Matrix - resets the layer's modulation matrix values

Clicking and holding the background layer opens the following options:

• Files - Open a document picker where you can select an image or video
• Photos - Open the iOS photo picker (iOS only)
• Reset - resets background media

The layer manager has four other buttons; to the left of the layers is the circle icon, which opens and closes the color panel, and to the right of the layers there are three buttons to access the modulation section, the modulation matrix, and the audio/MIDI file loader.

Audio/MIDI file loader

The Audio/MIDI file loader lets you load and playback both audio and MIDI files, for VS to use as modulation sources to create visuals from. To load a file, click the directory icon on the right of the panel, then select a compatible filetype. (.MID .Wav .Aiff). Once the file has loaded, you can control playback with the three transport buttons located on the left of the panel, 'play', 'stop' and 'toggle looped playback' respectively. You can also click any part of the audio waveform to play from that position.

VS comes loaded with a number of demo tracks, which contain both audio and MIDI parts. These can be accessed and loaded when the Audio/MIDI file is open, by selecting Banks > Demo at the top left.

Color Panel

On top you can choose the blend mode that will be applied. Normal is the default option. There are also the following modes: Screen, Hard Light, Soft Light, Overlay, Difference, Exclusion and Subtract (these are explained below).

Clicking inside the color wheel sets a layer’s main color by altering hue and saturation values, alternatively you can manually enter a specific hex color value, and also change the layer's brightness setting with the slider.

Blend modes alter how a stack of layers is rendered by changing the way that layers interact based on different operations on color information from the layers.

• Normal - The default mode is ‘Normal’ - where pixels are drawn ‘on top of each other’, effectively covering up the pixels of any layers below
• Screen - Looks at each channel’s color information and multiplies the inverse of the blend and base colors. The effect is similar to projecting multiple photographic slides on top of each other
• Hard Light - Multiplies or screens the colors, depending on the blend color. This is useful for adding shadows to an image
• Soft Light - Darkens or lightens the colors, depending on the blend color
• Overlay - a gentle multiplication of colors, both layers preserve details
• Difference - a kind of psychedelic 70’s effect, with high contrast, inverted colors
• Exclusion - similar to difference, but desaturated/washed out colors
• Subtract - creates a darker image by subtracting brightness

Material Browser

To open the material browser, double click any numbered layer.

Materials are presented in a scrollable grid, with an animated preview for each material.

At the top of the material browser window you can choose which bank of materials to view. By default, 'FACTORY' bank is selected. There is also a 'USER MATERIALS' bank where you can browse, manage and edit custom materials.

The currently loaded material is indicated by a yellow outline. Click any material to load it into the selected layer. When a new material is loaded, the layer’s color property does not change, the new material will use the layer’s currently selected color.

Each material contains an info button, and an options button which displays the available actions:

• Edit - Opens the material editor
• Clone - Creates a copy of the material with a unique identifier
• Export - Exports the material
• Delete - Deletes the material
• Rename - Renames the material

Material Editor

Materials are programs that run on the GPU (Graphics Processing Unit). These programs are written in GLSL shader programming language and are commonly called fragment shaders.

VS materials follow a structure similar to ISF (Interactive Shader Format) but the two formats are not identical/compatible with each other. This means that if you import an ISF shader as a new material into VS, it will not work.

Each material's source code starts with a manifest (commented JSON block) which declares the material's properties/parameters. Here is an example:

/*
{
    "author": "",
    "color": "white",
    "movement": true,
    "parameters": [
        {
            "default": 0.5,
            "name": "x"
        },
        {
            "default": 0.5,
            "name": "y"
        },
        {
            "default": 0.75,
            "name": "spread",
            "min" : 0.1,
            "max" : 5,
        }
    ],
    "url": "",
    "uuid": "babfc75f-178c-44e3-9ef5-89208122f156"
}
*/

Every material manifest must have the following properties:

• uuid - a unique identifier (you can create new uuids at https://www.uuidgenerator.net/). When a material is cloned, a new uuid is automatically generated.
• color - a default color (it could be an SVG (Scalable Vector Graphics) named color or a hex string starting with #, eg: #ff0000)
• movement - (either 'true' or 'false') if set to true, this will enable the speed layer parameter
• parameters (optional) - an array of JSON objects with name, default, min (optional), max (optional) properties
• url (optional) - an url to material's author/source
• author (optional) - the author of the material

The example material above declares three parameters: 'x', 'y' and 'spread', which automatically become available as variables for use in the code.

There are some specific pre-declared environment variables to be aware of, these variables are:

• time - highp float variable that is linked with the speed parameter of VS
• opacity - highp float variable that is linked with the brightness of the layer color
• alpha - highp float variable that is linked with the layer alpha parameter
• color - highp vec4 variable that is linked with the layer color
• resolution - highp vec2 variable that has the viewport resolution
• texCoord - highp vec2 variable that has the texture coordinates normalized between 0 and 1

Cloning materials from the 'FACTORY' bank is the best way of learning how a VS material works and create new ones. You can also import materials using the import button, located in the top bar of the material browser. VS only accepts files which have .frag extension.

VS built-in material editor consists of a text editor, with a live preview window and a set of knobs representing the standard and custom material parameters.

When you clone a material, it will automatically open the editor window. If you want to edit a material, choose the 'USER MATERIALS' bank, click on the options button of the desired material and then choose 'Edit'.

Everytime you make a change in the code, the material will be updated. If there are no errors and if the code is right, you will see something happening in the preview window.

The preview window can be moved by dragging it, and can be made full screen by clicking the full screen button inside of it. To close the full screen preview, double click on the preview area.

It is beyond the scope of this documentation to teach you how to write GLSL fragment shaders, as this is an highly complex topic that requires a good background understanding of computer graphics, as well as a deep knowledge of mathematics. (Something that we are by no means masters of!).

Still, if you are brave enough to take on this challenge yourself, we recommend reading 'The Book of Shaders' as a starting point. It is an incredible online resource about how to write your own shaders, written by Patricio Gonzales Vivo.

However we do feel that it is important to mention some of the most basic caveats of converting a typical GLSL fragment shader code to be compatible with VS.

Let's take as an example the circle shader code that is on The Book of Shaders.

If you paste the following code into VS material editor after the manifest, it will only show green and it will display an error as u_resolution is not a declared variable.

float circle(in vec2 _st, in float _radius)
{
    vec2 dist = _st-vec2(0.5);
	return 1.-smoothstep(_radius-(_radius*0.01), _radius+(_radius*0.01), dot(dist,dist)*4.0);
}

void main()
{
	vec2 st = gl_FragCoord.xy/u_resolution.xy;
	vec3 color = vec3(circle(st,0.9));

	gl_FragColor = vec4( color, 1.0 );
}

If we replace u_resolution for resolution, a variable that is automatically declared by VS' render engine, no more errors will be displayed and the preview will turn black. But why can't we see anything happening yet?

If you drag the window to the top-left side of the editor window, you will see a deformed white circle being drawn.

In order to paint inside the preview window, let's take advantage of the 'texCoord' variable that holds the normalized texture coordinates. In order to do this, replace the line:

vec2 st = gl_FragCoord.xy/u_resolution.xy;

with

vec2 st = texCoord;

Now, the circle is positioned withing the bounds of the preview window. But we can't really call this a circle, can we?

Since texCoord holds normalized positions, it doesn't take into account that the display window might have a different aspect ratio than a square therefore, we need to calculate the ratio ourselves. This is actually something we do a lot in the factory provided materials. If you replace:

vec2 st = texCoord;

with

float div = resolution.y/resolution.x;
vec2 aspect = vec2(1.,div);
vec2 st = texCoord*aspect;

You will see that the circle now has the right proportions, but it is going outside of the window bounds. With some other minor tweaks we end up with the following code:

float circle(in vec2 _st, in float _radius)
{
    vec2 dist = _st;
	return 1.-smoothstep(_radius-(_radius*0.01),
                         _radius+(_radius*0.01),
                         dot(dist,dist)*4.0);
}

void main()
{
	float div = resolution.y/resolution.x;
    vec2 aspect = vec2(1.,div);
	vec2 st = texCoord*aspect-vec2(0.5, 0.5*div);

	vec3 color = vec3(circle(st, 0.3));

	gl_FragColor = vec4( color, 1.0 );
}

So now that we have a centered circle drawn in the preview, let's take advantage of the built-in variables, so we can control alpha, color, and brightness. Then add parameters to control the circle's x, y position and radius.

/*
{
    "author": "",
    "color": "violet",
    "movement": true,
    "parameters": [
        {
            "default": 0.5,
            "name": "x"
        },
        {
            "default": 0.5,
            "name": "y"
        },
        {
            "default": 0.1,
            "name": "radius",
			"min": 0.1,
			"max": 2
        }
    ],
    "url": "",
    "uuid": "1823757c-871c-4057-baee-8c69a8ff1ff8"
}
*/

#ifdef GL_ES
precision highp float;
#endif

float circle(in vec2 _st, in float _radius)
{
    vec2 dist = _st;
	return 1.-smoothstep(_radius-(_radius*0.01),
                         _radius+(_radius*0.01),
                         dot(dist,dist)*4.0);
}

void main()
{
	float div = resolution.y/resolution.x;
    vec2 aspect = vec2(1.,div);
	vec2 st = texCoord*aspect-vec2(x, y*div);

	vec3 c = vec3(circle(st, abs(sin(time))*0.4+radius));

	gl_FragColor = vec4( color.rgb*c*opacity, alpha);
}

And there you have it, a really basic new material. The circle is complete.

To exit the material browser without loading a new material, click the ‘CLOSE’ button located at the top right of the screen.

Media browser

To open the background image/video media browser, double click or long press the background layer ‘B’. You can then navigate your local filesystem for supported file types.

Select any file to display a preview, then choose to either load the selection into the background layer, or cancel the operation using the close button.

You can also choose to reset the layer to a blank background.

Layer Controls

The layer control panel provides access to the parameters of the currently selected layer.

The number of controls that appear for each layer varies depending on the layer’s active material, specifically the amount of custom parameters the material contains. When a layer is selected, the available controls automatically change.

All material layers have the following common controls:

• Enabled - Turns the layer on/off
• Solo - Turns off all other layers and displays only this layer
• Alpha - alpha (aka transparency) controls the transparency of black (absence of color). This allows a material that only paints a certain area of the screen (with everything else black), to be perfectly blended with the layer below, without compromising its brightness
• Brightness - controls the brightness component of the layer’s color. It is the same as the slider present in the color panel
• Speed - Controls the movement speed of the layer material. Value can be positive, negative or zero (static)
• Mono - restricts the layer to a single visual voice
• Trigger - when set to ‘MIDI’, the layer will be triggered on and off by MIDI note data. Multiple simultaneous notes will generate a layer of polyphonic visual voices. When this mode is active, it is important to ensure that brightness is being modulated by the EG, the default behaviour
• Trigger Channel - specifies the MIDI channel that will trigger this layer. This can be useful to have different layers reacting to different MIDI voices
• Glide - This works like a portamento. When glide is greater than zero and KBD (notes pitch) is being used as a modulation source in the modulation matrix, the frequency of these notes will be interpolated (only available in MIDI mode)

Each material can have up to 8 parameters that are specific to it. The layer control knobs placed between SPEED and MONO parameters are specific to the material. Their label will adjust according to the material. If a material does not make use of certain parameters, its label will be N/A and the knob will be disabled.

Background Layer

The background layer has its own set of parameters, since it deals with image and video. The background layer honours the color panel selection if no image or video is set.

• Enabled - Turn the layer on/off
• Alpha - Controls the transparency
• Scale - Resizes the media
• Rotate - Rotates the media
• X - Changes the horizontal position of the media
• Y - Changes the vertical position of the media
• Rate - Defines playback speed (video only)
• Mode - Defines the playback mode of the video (video only)
• Loop - In this mode video playback continuously repeats
• Still - In this mode the video remains paused on a single frame
• Position - Select the frame used for still mode. This parameter is only enabled when mode is STILL (video only)
• End - Defines the end point of the video (video only)
• Fill Mode - Defines how media fill mode:
• Fit - The media will fit in the screen without being cropped. Can lead to empty or black spaces
• Crop - Media will occupy all the available display area. Cropping can occur

Layer Modulations

This panel is divided into three sections: LFOs, envelopes and audio modulation.

These are audio related terms that we chose to adopt so people using this software with their audio compositions can feel at home in the visual world also.

However, if you’re new to these terms we will happily explain them right now.

Modulation Sources

LFO

This is an acronym for Low Frequency Oscillator. LFOs are signals with very low frequencies, whose output can be used to modulate audio signals (like frequency, volume, etc). We took this concept and applied it to the materials/layers parameters. You can, for instance, take the x position of a given material, and modulate it with an LFO, so its position is changed over time.

On the left of the panel is the LFOs section. There are 4 independent LFOs, accessed using the numbered buttons, and each LFO consists of the following parameters:

• Waveform - Click to cycle through these available types:

• SINE - Sinusoidal
• SQR - Square
• SAW - Sawtooth
• TRI - Triangle
• S&H - Sample and hold (this will give you jumps between random values for modulation)
• FS&H - Filtered sample and hold (the same as sample and hold but there will be a ramp between values, causing smooth glides between random values rather than jumps)

• Rate - Define the speed of the LFO. This will set the frequency of the oscillation that will determine how fast the values are changed

• Sync - When active, the speed of the LFO can be set to various increments of the tempo of the VS project, so you can have your modulations in sync with the tempo of your session

• Phase - You can choose between FREE and KEY. In key mode, the LFO will always start from the 0 value anytime a MIDI ‘note on’ event is received. This is useful to have expected results every time you receive a trigger note, i.e. the modulation effect will always start from the same position. In free mode the LFO will run freely.

• Key - (only enabled when phase is set to 'key') This allows you to specify a particular MIDI channel to listen for 'note on' events, or to listen for 'note on' events on all MIDI channels by setting it to 'Any'.

A visual representation of the waveform is shown to the left of the controls.

EG

EG is an acronym for envelope generator. In audio terms, the envelope generator shapes the sound amplitude over time.

Envelope generators usually have four stages: Attack, decay, sustain and release, also known as ‘ADSR’. VS streamlines the envelope generator process by requiring just the attack and release parameters.

In audio terms, the attack stage is how long it takes for a sound to reach its sustain value from the moment it is triggered, and the release is the amount of time the sound will take to reach silence, once the note has been released. In simplified terms, you can think of attack as fade in, and release as fade out. Then you have two parameters to control in the EG:

• Attack - controls the amount of time the brightness will take from zero to its layer defined value once a trigger on event (note on) is received

• Release - controls the amount of time the brightness will take from its sustain value to zero once a trigger off event (note off) is received

We provide you two independent EGs to choose from.

Audio Modulators

Finally, on the right of the modulators panel there is the audio modulator panel. Here it’s possible to use the input audio as a modulation source, just like the LFOs and EGs.

There are four independent audio modulators, with two modes of operation:

• GATE - in this mode audio input will serve as a modulator only if its amplitude is above a specific level, defined by the THRESHOLD parameter. There is a visual analyser, so it is possible to see the amplitude range of the input and adjust the threshold accordingly. When the audio signal passes the defined threshold, it will work as an envelope follower. In order words, the amount of modulation will be linked to the ‘strength’ of the signal. The greater the amplitude, the greater the value of the modulation.

• SPCTRM (Spectrum) - This mode is very similar to the gate mode, but with the advantage of the audio being “divided” into frequency bands. Instead of reading the amplitude of the signal as a whole, you can choose a specific band of frequencies to serve as a modulation source. You can, for instance, try to capture a kick, or a snare, or maybe a specific high or low sound from your input, and use it as a modulator. The threshold is equally applied in this mode.

Remember that each audio modulator is independent, so you can have different audio modulators capturing different bands with different thresholds, or combining gate ones with spectrum ones. Again, remember that like the LFOs or EG2, playing with these will produce no effect unless they have been assigned to something in the Modulation Matrix, discussed below.

Audio modulator parameters:

• Numbered boxes - select the desired audio modulator

Mode - Select the mode of the current audio modulator (Gate or Spectrum)

• Threshold - Define the limit where the input will start to be used as modulation
• Gain - This serves as a multiplier of the resulting modulation values. It can be useful to amplify quieter signals or to reduce strong ones
• Attack - As explained above, the attack is related to the amount of time a given signal takes to reach the maximum value as soon as there is an on trigger. In this case, we consider the signal passing the threshold as the trigger, and its current value as the target. So what attack will do is to make a kind of ramp between values. The greater the amount of attack, the slower it will change the output of the modulator. In other words, longer attacks will cause slower onset of modulations
• Release - This is triggered when the signal passes below the threshold, and defines the time the output modulation will take to reach the zero value. In other words, longer release values will cause modulations to fade more slowly

Modulation Matrix

The modulation matrix panel lets you assign modulation sources to specific layer parameters, arranged in a two dimensional grid of cells, with modulation sources on the x axis (top) and parameters on the y axis (left). Clicking a cell value and then dragging either up/down or left/right will decrease or increase the amount of modulation effect that the source will have on the parameter. This value can range from -1 to +1, with the default setting zero representing no modulation effect. To aid visual clarity, each cell shows a white horizontal line under the value, if the value is greater than or less than zero. The origin point of the line is centered, so positive values draw to the right and negative to the left.

The matrix is split into three tabs, with a thin yellow bar highlighting the currently displayed tab, click each yellow tab line to access the different pages of each layer’s parameters. You can also click and hold layer parameter rotary knobs to quickly navigate to its corresponding matrix cell (for this to work, the layer parameter must exist in the matrix).

In addition to the LFO, EG and AM (audio modulator) modulation sources, a further two sources are available for MIDI note data trigger based modulation:

• KBD (Keyboard) - the amount of modulation determined by the pitch of the note on events. The MIDI pitch 60 corresponds to the zero point of the modulation. Pitches higher will act as increasing positive modulation and pitches lower will act as decreasing negative modulation
• VEL (Velocity) - the amount of modulation determined by the velocity of the MIDI note on events

Settings

• Profile - Login to Imaginando account
• MIDI - configure MIDI input and output ports
• Settings
• • Input audio device - Select your desired input device to be used as an audio modulation source
  • Output audio device - Select your desired output device for playback of VS’ demos
  • Sample rate - Select the sample rate to be used in VS audio engine
  • Buffer size - Select the buffer size to be used in VS audio engine
• Render Output - Enable NDI, Spout (Windows) or Syphon (Mac) video output
• Frame rate - The target refresh rate of VS render output (frames per second). Currently two options are available, 30 and 60 fps. For a smoother output try the 60 option
• Output Resolution - The resolution at which each layer is rendered. The lower the value, the smoother the visual output. For a more detailed visual output try a higher resolution
• Render Quality - choose between 'high performance' (more consistent framerate) or 'high resolution' (best quality)
• Recording Quality - the level of quality/detail of VS' video recordings. The higher the setting, the larger the file size
• Voices - the number of simultaneous polyphonic visual voices per layer. e.g. with 4 polyphonic voices, each layer can display 4 simultaneous instances of its material at once
• Animated layer thumbnails - choose whether layer thumbnails are animated or not

Updated on: 12/03/2026