Auragen docs
Auragen docs

Getting Started

OverviewInterfaceNode GraphParameters and Controls

Operators

3D PreviewperformMODE
PresetsCustom GLSL ShadersKeyboard ShortcutsTips
Reference

Custom GLSL Shaders

Reference for the Custom GLSL node - built-in uniforms per shader format, parameter annotations, audio uniforms, and SSF scenes.

Reference for shaders that run in the Custom GLSL node.

  • Formats — plain GLSL, Shadertoy-style code, ISF files, and SSF scenes
  • Built-in uniforms — what each format gets without declaring it
  • Parameters — every uniform you declare becomes a control
  • Pointer uniforms — mouse position and buttons, in every format
  • Audio uniforms — live audio values, available by name, plus four audio inputs you wire yourself
  • SSF scenes — load a .synScene folder as one node

Formats

The node detects the format from the source.

FormatDetected byEntry point
Plain GLSLdefaultvoid main() writing gl_FragColor
Shadertoy-stylemainImage, iTime or iResolution in the sourcevoid mainImage(out vec4 fragColor, in vec2 fragCoord)
ISFa /*{ … }*/ JSON header with INPUTS, DESCRIPTION, PASSES or ISFVSN at the top of the sourcevoid main() writing gl_FragColor
SSF scenevec4 renderMain(void) in the source, or a loaded .synScenevec4 renderMain(void)

Drop a .glsl, .frag, .fs or .isf file onto the node graph to create a Custom GLSL node from it.

Built-in uniforms

Do not declare these. The compiler injects them.

Plain GLSL

UniformTypeValue
uTimefloatAnimation time in seconds
uResolutionvec2Output size in pixels
uMousevec2Mouse position, 0–1
uTexturesampler2DThe texture wired into the Texture in input
uTexture2, uTexture3 …sampler2DThe textures wired into the added Texture in 2, 3 … inputs

Shadertoy-style

NameTypeValue
iTimefloatAnimation time in seconds
iResolutionvec3Output size in pixels (z = 1)
iMousevec4Mouse position and last click, in pixels
iFrameintFrame counter
iChannel0sampler2DThe texture wired into the Texture in input
iChannel1sampler2DThe texture wired into the added Texture in 2 input

iChannel2 and iChannel3 read Texture in 3 and Texture in 4. A channel whose input the node does not have, or that has nothing wired, reads Texture in. Add texture inputs with + Texture in in the node's parameters.

ISF

NameValue
TIMEAnimation time in seconds
RENDERSIZEOutput size in pixels
isf_FragNormCoordPixel position, 0–1
FRAMEINDEXFrame counter
TIMEDELTAFixed at 1/60
IMG_NORM_PIXEL(tex, uv), IMG_PIXEL(tex, px), IMG_THIS_NORM_PIXEL(uv), IMG_THIS_PIXEL(px), IMG_SIZE(tex)Texture lookups

The first image input reads the Texture in input, the second Texture in 2, and so on. An audio or audioFFT input reads the audio spectrum texture. The shader renders in one pass; PASSINDEX is always 0.

SSF scene

NameTypeValue
TIMEfloatAnimation time in seconds
RENDERSIZEvec2Size in pixels of the pass being rendered
FRAMECOUNTfloatFrames rendered since the shader compiled
PASSINDEXintIndex of the pass being rendered
_xyvec2Pixel position
_uvvec2Pixel position, 0–1
_uvcvec2Aspect-corrected position, (0,0) at the center
PIfloat3.14159265359
_mouse, _click, _muv, _muvcThe pointer uniforms
syn_Mediasampler2DThe texture wired into the Texture in input
syn_MediaTypefloat1 when the Texture in input is wired, 0 otherwise
uTexture2, uTexture3 …sampler2DThe textures wired into the added Texture in inputs; iChannel1 to iChannel3 read them too
syn_FinalPasssampler2DThe scene's previous output frame

Every pass TARGET and every image NAME from scene.json is a sampler2D of that name.

Pointer uniforms

Every format has these. Name one in the shader and it is declared for you.

NameTypeValue
_mousevec4xy is the pointer position in pixels, origin at the bottom left. zw is the position where the button went down; both are negative while no button is held
_clickvec3Left, right and middle button in x, y, z: 1 while held, 0 otherwise
_muvvec2Pointer position, 0–1
_muvcvec2Pointer position, aspect-corrected with (0,0) at the center, the same space as _uvc
  • The pointer is read over the viewport, in the Node graph and in performMODE
  • uTexture2, uTexture3 … read the node's added texture inputs; one the node does not have, or with nothing wired, reads Texture in

Parameters

Each uniform you declare becomes a control in Shader Parameters, stored on the node as uniform_<name>.

uniform float speed;      // @range 0 5 @default 1 @label "Speed"
uniform int   mode;       // @options "Soft" "Hard"
uniform bool  invert;
uniform vec2  center;     // @range -1 1
uniform vec3  tint;       // @color @default 1 0.5 0.2
DeclarationControl
float, intSlider, with the per-parameter animation bar
int with @optionsDropdown; the value is the option index
boolSwitch
vec2X and Y sliders
vec3 / vec4 with @colorColor swatch (vec4 adds an alpha slider)

Annotations go in a // comment on the same line as the declaration.

  • @range <min> <max> — slider bounds. Without it a float runs -2 to 2 and an int 0 to 100
  • @default <value> — starting value; give one number per component for vectors
  • @label "Name" — display name
  • @step <n> — slider step
  • @color — show a vec3 or vec4 as a color
  • @options "A" "B" … — show an int as a dropdown

A vec3 or vec4 without @color compiles and works but gets no control.

Use the Expose button on a control to promote the uniform to a Base, a driver port, and the performMODE deck. Sliders can be animated, mapped to audio, and mapped to MIDI like any other parameter. See Parameters and Controls.

Each declaration must start a line, one uniform per line. mat and sampler2D declarations are not turned into controls.

Audio uniforms

Name an audio uniform in the shader and it is declared for you and updated every frame. No wiring is needed.

void main() {
  vec2 uv = gl_FragCoord.xy / uResolution;
  float spectrum = texture(audio_Spectrum, uv.x).g;
  gl_FragColor = vec4(vec3(spectrum * audio_BassLevel), 1.0);
}

The prefix is audio_ in plain GLSL, Shadertoy-style and ISF shaders. Inside an SSF scene the same names use syn_.

The Audio row appears in the editor once the shader names an audio uniform. It selects the source: the timeline's audio when a song is loaded, otherwise the input device, or a specific clip or file.

UniformValue
audio_Level, audio_BassLevel, audio_MidLevel, audio_MidHighLevel, audio_HighLevelSmoothed loudness of the whole spectrum and of each band, 0–1
audio_Hits, audio_BassHits, audio_MidHits, audio_MidHighHits, audio_HighHitsTransients: rises fast on an isolated hit, falls back quickly, 0–1
audio_Presence, audio_BassPresence, audio_MidPresence, audio_MidHighPresence, audio_HighPresenceSlow rise and fall with the energy in the band, 0–1
audio_Time, audio_BassTime, audio_MidTime, audio_MidHighTime, audio_HighTimeClocks that advance with loudness. Not normalised
audio_CurvedTimeA clock that accelerates strongly with loudness
audio_FadeInOutRises to 1 when sound starts, falls to 0 when it stops
audio_IntensityBuilds toward 1 during loud passages, sinks in quiet ones
audio_Spectrumsampler2D, 512 × 1. .r raw FFT, .g conditioned FFT on a log frequency scale, .b the same at lower resolution, .a waveform (0.5 is silence)
audio_LevelTrailsampler2D, 256 × 1 history with the newest sample at x = 1. .r level, .g bass, .b mid, .a high

Bands: Bass 30–250 Hz, Mid 250–2000 Hz, MidHigh 2–6 kHz, High 6–16 kHz.

Sample the two textures with a float or a vec2: texture(audio_Spectrum, 0.25) and texture(audio_Spectrum, vec2(0.25, 0.5)) read the same texel.

Audio inputs

Click + Audio in in the node's parameters to add an audio input. Audio in 1 is read as audio_In1, Audio in 2 as audio_In2, and so on (syn_In1 … in an SSF scene). Add as many as you need.

  • The Sound node sets the frequency range and the response, so each input is an audio uniform of your own design
  • Any modifier can drive an input, not only a Sound node
  • An input with nothing wired, or a name the node has no input for, reads 0
  • The × next to an input removes it; the others keep their numbers
  • #define kick audio_In1 gives an input a name in the shader
#define kick audio_In1
void main() {
    vec2 uv = gl_FragCoord.xy / uResolution;
    gl_FragColor = vec4(vec3(step(length(uv - 0.5), 0.1 + 0.3 * kick)), 1.0);
}

Beat uniforms

audio_BPM, audio_BPMConfidence, audio_OnBeat, audio_ToggleOnBeat, audio_RandomOnBeat, audio_BeatTime, audio_BPMTwitcher, audio_BPMSin, audio_BPMSin2, audio_BPMSin4, audio_BPMSin8, audio_BPMTri, audio_BPMTri2, audio_BPMTri4, audio_BPMTri8.

Beat detection is not implemented yet. The beat uniforms run from a fixed 120 BPM clock and audio_BPMConfidence reads 0.

Behaviour under pause

The level, hit and presence values and both textures keep following the audio while the app is paused. The time clocks and the beat clock hold until playback resumes.

An unknown name such as audio_Bass fails the compile and the error lists the valid names.

SSF scenes

An SSF scene is a folder ending in .synScene that holds main.glsl, scene.json, and optionally script.js and an images folder.

  • Drop the folder, or a .zip of it, onto the node graph
  • The scene loads as one Custom GLSL node named after the scene's TITLE
  • Controls, passes, images, the script and the audio uniforms are set up from the scene's files

Controls

Each entry in CONTROLS becomes a control and a uniform of the same name.

Control TYPEUniformControl
slider, knobfloatSlider with MIN, MAX, DEFAULT
togglefloatSwitch (0 or 1)
bangfloatButton; 1 for the frame it is pressed
bang counterfloatButton; counts presses
xyvec2X and Y sliders
colorvec3Color swatch (DEF_COLOR)
dropdownfloatDropdown from LABELS and VALUES
  • A smooth variant eases toward the set value at the rate in PARAMS
  • A speed variant adds the set value to the uniform every second and holds while the app is paused
  • A traveler variant is a speed control whose rate eases toward the set value at the rate in PARAMS
  • A control with no TYPE is a slider
  • UI_GROUP puts controls under a group header
  • HARD_TRANSITIONS and SMOOTH_TRANSITIONS entries become sliders in a Transitions group

scene.json can contain comments, trailing commas and numbers written as 1. or .5. A control or image listed twice is used once.

Passes

PASSES render in order before the final pass. renderMain runs once per pass with PASSINDEX set to the pass index; the final pass has the index after the last entry.

  • WIDTH / HEIGHT — pass size; the node's output size when omitted
  • FLOAT — 32-bit float target (half float when the GPU cannot render to float)
  • FILTER — linear, nearest or mipmap; WRAP — repeat, clamp or mirror

A pass that samples its own TARGET reads its previous frame, so feedback works with or without DOUBLE_BUFFER. Passes and syn_FinalPass hold while the app is paused.

Images

IMAGES entries load from the scene's folder and bind to their NAME. The desktop app stores them in the resources vault; the browser build embeds them in the patch.

Scripts

script.js runs once per frame before the shader.

  • setup() runs once; update(dt) runs every frame
  • Every uniform is a global: TIME, the audio values, the control names, and the pointer (_muvc.x, _click.x)
  • setUniform(name, …) creates a shader uniform; setControl(name, value) writes a control
  • uniforms.name = value also creates a uniform. An object assigned this way is read again every frame, so uniforms.cam = cam follows later changes to cam
  • A uniform the script sets from a variable takes its size from the shader: cam.z in main.glsl makes cam a vec3
  • onChange, onOffToOn, onOnToOff, whileOn, whileOff register handlers
  • print(…) writes to the script log shown under the code box

Edit script.js on the Script tab of the code box, which appears while an SSF scene is loaded. Click Run, or press Ctrl+Enter, to restart the script with the new text. Open in editor opens it in your own code editor instead, and each save there restarts the script. The shader compiles again at the same time, because the uniforms the script sets are part of the shader.

The script runs in an isolated sandbox with no network or file access. A script that does not return within 100 ms is stopped and the status row shows timed out; Reload script restarts it.

A scene's script starts once the node is rendering, that is once it is wired toward the Output node.

Helper functions

Scenes can call the scene library without declaring it: _rotate, _toPolar, _toRect, _hsv2rgb, _rgb2hsv, _noise, _fbm, _rand, the _hash family, _pulse, _mix3 to _mix5, _map, _mirror, _palette, _loadMedia, _textureMedia, _loadImage, _edgeDetect, _edgeDetectSobel, _hBlurTiltShift, _vBlurTiltShift, and the rest of the standard set. A function the scene defines itself replaces the library's.

Includes

#include reads from the bundled libraries:

#include "lygia/generative/snoise.glsl"
#include "hg_sdf.glsl"
  • lygia/… — the lygia shader library
  • hg_sdf.glsl — signed distance functions
  • dome_header.glsl — fulldome coordinate helpers

Scenes written for desktop GLSL

Auragen compiles a scene as GLSL ES 3.00. Scene code written for desktop GLSL is adapted when it compiles, and main.glsl in the editor stays as you wrote it.

  • An integer in a float expression is converted: float x = 1;, TIME * 2, pow(x, 2), uv *= 2;
  • An integer vector passed as a float vector is converted: vec2 size = textureSize(tex, 0);
  • A global variable set from a uniform (vec2 U = _xy;) gets its value at the start of each frame
  • Default parameter values (float f(float a, float b = 1.0)) become overloads
  • A name that GLSL ES reserves (sample, or a name with two underscores) is renamed
  • FRAMECOUNT works where an integer is necessary: int i = min(0, FRAMECOUNT), FRAMECOUNT % 2
  • texelFetch(syn_Spectrum, index, 0) works with one integer index

The status row under the editor shows how many expressions were adapted. An error line number refers to main.glsl, or names the included file.

A name the shader reads and no file declares becomes a uniform that the script can set, when the scene has a script. It reads 0 until the script sets it.

Limits

  • One shader can read 16 textures on most GPUs, counting images, passes, the media input and the audio textures. A scene that reads more does not compile
  • CUBEMAPS sample black
  • textureFinalPass in a script returns black
  • The beat uniforms use the fixed clock described under Beat uniforms
  • The scene-wide color and media adjustments (_Brightness, _Contrast, _Media_Scale, …) stay at their neutral values; use the node's own parameters and effect nodes instead

Editor

  • ▾ next to the tabs — hide or show the code box, to show only the parameters
  • Auto — recompile 500 ms after you stop typing; Compile or Ctrl+Enter compiles now
  • Reset — restore the default shader
  • Tab inserts four spaces
  • GLSL and Script tabs — switch the code box between the shader and, with an SSF scene loaded, the scene's script.js. Run, on the Script tab, applies an edit to the script
  • Open in editor — opens the code on the active tab in the app your computer uses for that file type, for example your code editor. Each save there updates the node. Desktop app only

Under the parameters, Built-in uniforms, Audio uniforms and SSF scenes open these reference sections, and Guide shows the shader authoring guide. An AI assistant connected to Auragen reads the same guide on its own, through the MCP server's getShaderGuide tool, so there is nothing to paste into it.

A compile error shows under the editor with its line. A node whose saved shader does not compile shows an error badge in the graph.

Presets

Save, load, and manage compositions as JSON preset files.

Keyboard Shortcuts

Every keyboard shortcut for modes, playback, files, the node graph, and previewing.

On this page

FormatsBuilt-in uniformsPlain GLSLShadertoy-styleISFSSF scenePointer uniformsParametersAudio uniformsAudio inputsBeat uniformsBehaviour under pauseSSF scenesControlsPassesImagesScriptsHelper functionsIncludesScenes written for desktop GLSLLimitsEditor