SHABBA PRO

VISUALIZER  /  v4.8.0

User Guide

An offline audio visualizer for DJ sets and music videos. It listens to rekordbox, your audio interface, Ableton, a microphone or a track you load, and turns it into blended, beat-aware visuals you can project, record or render to MP4.

It is one file. Open shabba-visualizer-pro.html in Google Chrome. Nothing to install, no internet needed, nothing is uploaded.

1. 1Before you start
2. 2Quick start (60 seconds)
3. 3Choose your audio source
4. 4The screen at a glance
5. 5Scenes and engines
6. 6Blends: how scenes change
7. 7The Originals Lab
8. 8Look and FX
9. 9Auto-Director and music videos
10. 10Recording and export
11. 11Visuals only, and titles
12. 12Input panel
13. 13MIDI
14. 14Your own shaders
15. 15Keyboard cheat sheet
16. 16Troubleshooting
17. 17What has been tested, and the limits
18. 18Live set: queue, pads, two screens
19. 19Library, timeline cards and batch render
20. 20Your pictures, videos and the Ableton bridge
21. 21Interface, effects and projection
22. 22New in 4.8.0
23. 23Credits and licences

1Before you start

2Quick start (60 seconds)

1. Open the file. Right-click shabba-visualizer-pro.html → Open With → Google Chrome (or drag it onto a Chrome window). You will see the start screen in Figure 1.
2. Click “Play a 2-Minute Demo”. You should immediately see visuals moving to a generated 124 BPM track. If you do, everything works.
3. Press P to open the drawer where scenes, looks and the Auto-Director live. Press V for a clean full-screen view with nothing but visuals; Esc brings the controls back.
4. To use it live, press 4 (or the power button) to return to the start screen and choose a source from section 3.

3Choose your audio source

The start screen shows the eight engines on a curved wall of live screens, with the number of scenes in each, and below them a booth with seven cards, one per sound source. Point at a card (or move to it with Tab) and it lifts up; its full how-to appears under the booth. You can change source at any time with 4. The links along the bottom open the Reference drawer (routing rekordbox on a Mac, connecting Ableton, making a music video, the shortcuts) and Open a .shabba Session (section 22).

1. Your Own Track (the record). Drop an audio file on it, or click to browse. It is analysed first, which is what makes the Auto-Director possible (section 9). Recent sessions are listed under it.
2. Demo Track (the cassette). Play a 2-Minute Demo: a generated track with an intro, build, two drops and a breakdown. Use it to learn the controls.
3. System Audio (the monitor). The easiest live route for rekordbox. Click Capture System Audio, choose Entire Screen and tick “Also share system audio”.
4. Tab or Stream (the browser window). Paste a link and click Open Link to open it in a new tab, press play there, then click Capture Tab Audio and pick that tab.
5. Interface (the rack plate). Choose a device (BlackHole, Loopback or a real interface) and click Use Input. Devices marked ✓ are virtual loopbacks. This gives the cleanest digital feed.
6. Ableton Live (the clip grid). Connect to Ableton finds your loopback device; Listen for MIDI Clock locks the beat to Live; Connect Track Bridge is the optional per-track focus.
7. Microphone (the grille). Use Microphone. Tick Auto-Gain for a quiet room and Noise Filter if the room is noisy.

Using it with rekordbox while DJing (Mac)

1. Easiest: the System Audio card, Capture System Audio, share the entire screen with audio. Nothing to install.
2. Most reliable: install BlackHole 2ch. In Audio MIDI Setup create a Multi-Output Device containing your interface and BlackHole 2ch. In rekordbox set Preferences → Audio → Output to that device. Then pick BlackHole 2ch in the Interface card.
3. Hardware mixer: send the booth or record out into an audio-interface input, then select that interface in the Interface card.
4. Two screens: put the visuals on the second display and press O for a clean output window. The controls stay on your laptop and the output is never throttled.

Live sources never play through the browser’s own speakers, so you will not hear a double signal. The volume slider only affects tracks you load.

Using it with Ableton Live

1. Full mix: install BlackHole 2ch and route Live’s master to it alongside your speakers, then click Connect to Ableton. This remains the normal audio-analysis path.
2. Optional track focus: unzip Shabba-Ableton-Track-Bridge-v4.7.0.zip. Double-click Start Bridge.command on macOS or start-bridge.bat on Windows, then use the Shabba page it opens. The optional helper needs Node.js 18 or newer.
3. In Live, add Shabba Track Meter.amxd to the audio-effect area of each track to monitor. In Shabba, click Connect Track Bridge, choose a track and enable Focus visuals. The device passes audio through unchanged and sends track name, level and frequency bands to the local helper.
4. For beat lock, enable the macOS IAC Driver and set Live’s MIDI Output to IAC with Sync enabled, or use the existing audio beat detector. The bridge does not provide transport clock or the full-mix waveform.

The bridge listens on this computer only. It does not solo, mute, route or control tracks. A Max for Live device and Node.js helper are required; the standalone visualizer still runs without them.

Using it with Ableton Live

1. Full mix: install BlackHole 2ch and route Live’s master to it alongside your speakers, then click Connect to Ableton. This remains the normal audio-analysis path.
2. Optional track focus: unzip Shabba-Ableton-Track-Bridge-v4.7.0.zip. Double-click Start Bridge.command on macOS or start-bridge.bat on Windows, then use the Shabba page it opens. The optional helper needs Node.js 18 or newer.
3. In Live, add Shabba Track Meter.amxd to the audio-effect area of each track to monitor. In Shabba, click Connect Track Bridge, open the Live tab, choose a track and enable Focus GPU visuals. This steers GLSL, Scope and Particle scenes; MilkDrop keeps following the full audio input.
4. For beat lock, enable the macOS IAC Driver and set Live’s MIDI Output to IAC with Sync enabled, or use the existing audio beat detector. The bridge does not provide transport clock or the full-mix waveform.

The bridge listens on this computer only. It does not solo, mute, route or control tracks. A Max for Live device and Node.js helper are required; the standalone visualizer still runs without them.

Using it with YouTube or Spotify

Shabba cannot read a streaming service directly, but it can listen to a browser tab that is playing one. That is the Tab or Stream card.

1. Paste the playlist or video link into the Tab or Stream card and press Open Link (or just open it yourself). It opens in a new tab.
2. Press play in that tab.
3. Come back and press Capture Tab Audio. In Chrome’s picker choose the tab that is playing and tick Also share tab audio.

The visuals now follow that tab. It works with YouTube, YouTube Music, Spotify’s web player, SoundCloud and most other sites. Some protected streams may stay silent, and a tab that plays an advert will show the advert in the visuals too. Tab audio is live, so the Auto-Director cannot plan ahead the way it does for a loaded file.

Using it with Ableton Live

1. Audio: install BlackHole 2ch. In Live, Preferences → Audio → Output Device = a Multi-Output Device (your interface + BlackHole 2ch), or route the Master to an Ext. Out that feeds BlackHole. Click Connect to Ableton. You still hear everything.
2. Tempo (optional, exact): in Audio MIDI Setup → MIDI Studio enable the IAC Driver. In Live: Preferences → Link, Tempo & MIDI, set MIDI Output: IAC Driver with Sync on. Beat lock then follows Live’s transport.
3. Scene changes from Live: map any MIDI note or CC to Next / Random / Engine in the MIDI panel (N, section 13). A MIDI clip in Live can then switch scenes on cue.

Your own track

Drop the file on the Your Own Track card. Any format Chrome can play works (MP3, WAV, FLAC, AAC/M4A, OGG). The whole track is analysed first, which takes a few seconds, and gives you the timeline strip (Figure 4) and a plan for the Auto-Director.

4The screen at a glance

1. Now playing. The source or track name. This label is on screen only; it is never recorded.
2. Engine, beat and BPM. Shows the active engine, a beat dot, the tempo, and LOCK when beat lock is on.
3. Preset name. A ★ in front means you have starred it.
4. Input panel (I): level meter, gain and the fade-to-black setting. See section 12.
5. Timeline. Seek bar for tracks; on an analysed track it is coloured by section (Figure 4).
6. Control bar. Every button has a keyboard shortcut; Figure 3 lists them.

1. Play / pause Space
2. Loop L
3. Previous scene ←
4. Random scene R
5. Next scene →
6. Switch engine Tab
7. Beat lock K
8. Auto-switch on drops 1
9. Auto-Director J
10. Favourite this scene B
11. Bin this scene X
12. Playback volume (loaded tracks only)
13. Record C
14. Clean output window O
15. MIDI N
16. Input panel I
17. Drawer P
18. Change source 4
19. Visuals only V
20. Fullscreen F

1. Timeline strip. Colours mark intro, build, drop, breakdown, main and outro as detected by the analyser. Click anywhere to jump.
2. Time. Elapsed / total.

Press H to hide the HUD yourself. The cursor and HUD also hide after 3 seconds of stillness.

5Scenes and engines

There are eight engines. Tab steps through all of them; 5 6 7 8 jump to the first four, and the engine row at the top of the Scenes tab picks any.

That is 418 scenes in all. Every engine has its own list in the Scenes tab, and they all blend into each other, work with the Director, the pads and the queue, and can be tagged, put in collections and given preview pictures.

Figure 5. The four engines, captured in visuals-only mode.

Hyperreal scenes

Nine scenes in 4.8.0 are lit and shaded like real materials. They sit in their engines’ lists under the category Hyperreal, and all react to the kick and the bass:

• GLSL: Oil Slick (liquid chrome with rainbow film; each kick drops a ring into it), Sun Glitter (a sun setting on a level sea: the bass lifts the swell, the mids the chop, the highs the sparkle, and the kick flares the glitter), Oil on Wet Tar (oil drips on wet asphalt bloom into rainbow film, thin out and fade clear again; the kick adds a drip).
• Prism 3D: Lattice Wave (a grid of cubes; each kick sends a shock wave out from the centre), Glass Orb (a liquid glass orb that splits neon light into its colours and ripples on the kick), Silk Ribbons (lit satin ribbons spiralling through space; a wave rolls along them on the kick).
• Particles: Mycelium and Filament Sphere (ink strands with real depth of field; the kick whips them outward and flips black and white, a soft dip instead in Safe mode), Point Terrain (a landscape of glowing points; the music rolls out from the centre to the edges, and each kick sends a ring).

Sun Glitter and Point Terrain keep their horizon level: Evolve’s slow roll leaves them alone, and Sun Glitter also keeps its real sunset colours (your own hue setting still works).

Retired scenes. Eight older scenes that newer ones replaced (two GLSL, three Particles, three Scope) are hidden from the lists, the gallery, random picks and the Director. Saved plans and sessions that use them still open. Look → Interface → Show retired scenes lists them again after a reload.

The Scenes tab

1. Tabs. Scenes, Live, Director, Look, FX, Titles, Export. P opens and closes the drawer.
2. Engine switch. MilkDrop, GLSL, Scope, Particles, Ink, Loom, Fractal and 3D.
3. Filter chips. All; ★ the ones you starred; Unrated every preset you have not starred or binned yet; ⛔ the binned ones.
4. Search by name.
5. ★ Favourite. Nothing is starred when you start. Starred presets are what the Auto-Director’s Favourites pool uses and what the ★ chip shows.
6. ø Bin. Takes a preset out of rotation (recoverable under ⛔).
7. Footer. Export list / Import list save and load your ratings as a file (use this to back up or share). ✦ Lab opens the Originals Lab. Reset ★ clears every star and empties the bin.

Tip Press T to triage: presets play one after another and you press B to keep or X to bin. It is the fastest way to work through everything under Unrated.

1. Engine switch set to GLSL.
2. Scene list. Each scene has a short note on how it behaves and a mood tag.
3. + Shader / Edit. Add your own shader or edit one you added (section 14).
4. Export / Import. Save or load your added shaders as a file.

6Blends: how scenes change

Every scene change blends; nothing cuts abruptly. Blends are 2.5 seconds by default. Change the style in Look → Scene changes (Figure 10), or press U to cycle styles and [ ] to shorten or lengthen the blend.

Mixed picks a different style each time. The Auto-Director starts blends slightly early so they finish exactly on the bar line.

Fade to black. When the music stops, or a loaded track ends, the visuals ebb away to black and return when sound resumes. Turn it off in the Input panel (section 12).

7The Originals Lab

The Lab makes brand-new MilkDrop presets from parts written for this project. Every one is compiled, checked for life and measured against everything you already have, so a batch is clearly different from itself. Open it with the ✦ Lab button at the bottom of the Scenes tab. Anything you keep joins your preset list and can be used by the Auto-Director like the rest.

1. How many. Batch size.
2. Seed. The same seed always makes the same batch. The dice button picks a random one.
3. Generate originals. Takes a few seconds per preset while it screens them.
4. Status line. How many were screened and passed, how many are clearly different, and the closest pair.
5. Results. Thumbnail, name, family and parts, and a score for how different it is from what you already own. ★ keeps it, ø bins it, ≈ breeds more like it.
6. Export / Import originals. Save kept originals as a small recipe file; importing rebuilds them from the recipe.

8Look and FX

Look tab

1. Colour look. Natural, Neon, Ember, Glacier, Vapor, Acid, Mono, Sunset duo, Ocean duo. Changes fade in rather than snapping.
2. Bloom. The glow around bright areas.
3. Hue shift. Rotates every colour. Q A change it from the keyboard.
4. Scene changes. The eight blend styles plus Mixed.
5. Blend time. 0.4 to 8 seconds.

Also here: Exposure, Contrast, Saturation, Vignette, Film grain and Chromatic edge. Press 0 to reset the look.

FX tab

1. Evolve. Slow hue drift, breathing zoom, rotation and kaleidoscope changes riding the bar grid, so even one scene never sits still. Cycle length sets how many bars one cycle takes.
2. Kaleidoscope. Off, 3 to 16 segments, or Auto. Spin sets rotation.
3. Reacts to the music. How hard kicks punch the zoom and split the colour, snares flash and pixelate, hats glitch, and how much the camera shakes.
4. Drop FX / Build tension. Hits on every detected drop, and a rising tension during builds.
5. Safe mode. Removes flashing and strobing. Turn it on for audiences or venues where that matters.
6. Trigger pads. Punch, Flash, Glitch, RGB split, Pixelate, Invert, Shake, Kaleido, on Shift+1 to 8. Play them like instruments. The Auto-Director can fire these same effects for you (section 9).

9Auto-Director and music videos

Using one scene for a whole track gets monotonous. The Auto-Director analyses a loaded track (tempo, beat grid, bars, sections, drops) and writes a plan: which preset or scene plays in each section, how it blends, how colour, kaleidoscope, bloom and Evolve change, and when the effects from the FX tab hit. Builds ramp up, drops land with a hit, breakdowns calm down.

1. Auto-Director switch (J). Off means you drive; on means the plan drives.
2. Analysis summary. Tempo, bars, sections and drops found.
3. Style. Calm, Balanced or Wild: how restless the plan is.
4. Pick scenes from. Favourites (the ones you starred), All presets, GPU scenes, or Everything. With nothing starred, Favourites falls back to all presets.
5. Transitions. Smooth blends, Mixed or Punchy.
6. Variety. How often it changes scene inside a section.
7. FX hits. Off, Light, Medium (the default) or Heavy: how many effects the Director adds. Off keeps only the hit on each drop and the punch on a scene change.
8. May use. Tap an effect to allow or forbid it. Invert is off until you switch it on.
9. Re-roll plan, Shuffle FX, Save plan, Load plan. Re-roll writes a whole new plan. Shuffle FX redraws only the effects and leaves every scene alone. Save writes the plan to a file; load brings it back. Plans are also remembered per track.
10. Timeline. One row per section, with the effects it got (for example “Punch ×2 · Glitch · Shake”). ↻ re-rolls that section’s scene and effects; use assigns the scene currently on screen.
11. Render music video… records the whole track with your Export settings (section 10).

Editing the timeline by hand

Press Edit timeline… in the Director tab to see the whole plan as a picture. Coloured blocks are the segments (intro, build, drop, breakdown, main, outro), the red line is the playhead, and the FX lane underneath shows every effect hit as a coloured pill. Click a block to edit it in the panel below: its role, its scene (any preset or scene), its own FX level and which effects it may use; ↺ clears its overrides and ✕ deletes it, so its time joins the neighbour. Drag the handle between two blocks to move the boundary (it snaps to bars). In the FX lane, pick an effect and strength under Place, then click the lane to put a hit at that moment; drag a hit to move it and press Delete to remove the selected one. Split at playhead cuts a segment where the music is, Zoom makes the timeline wider, and clicking the ruler jumps there. Hits snap to the beat unless you untick the box. Anything you place by hand (purple outline) is never moved or deleted when the automatic effects are redrawn, and everything is saved with the plan.

Making it quicker. Right-click anything for a menu: a block (split here, play it, make it a big drop, calm it down, build up, copy and paste its FX, delete), a hit (delete, duplicate on the next beat, copy, set strength) or the FX lane (place any effect right there). Hover the timeline to see the bar, beat and time under the cursor, and a ghost marker where a click will place a hit. Drag a box in the FX lane to select several hits, hold Alt/Option while dragging to leave copies behind, and use the arrow keys to nudge the selection by a beat (Shift: a bar). The faint shape behind the blocks is the track’s energy, so you can see where the drops are. Play, Play segment and Loop segment let you hear a change straight away, and Dock / float moves the editor into a strip under the visuals so you can watch while you work. Keys: Space play, S split, 1–8 choose the effect, [ ] previous or next block, Delete remove, and ⌘/Ctrl C V Z copy, paste and undo. The panel under the timeline is grouped into Scene, Effects for this segment, Quick actions and Hits; its FX level reads “Auto (Medium)” so you can see what it follows.

How the FX hits are placed

The effects are the ones on the FX tab’s trigger pads (Punch, Flash, Glitch, RGB split, Pixelate, Invert, Shake, Kaleido). The Director fires them on the analysed bar grid, so they land on the beat, and what it does depends on where it is in the track:

On the 2-minute demo that is about 18 hits at Light, about 40 at Medium and about 60 at Heavy. To keep it musical and safe, hits are never closer than a third of a second, never on top of a scene change, at most one Flash or Invert every 2 seconds, never the same effect three times in a row, and none during the fade in or fade out. With Safe mode on (FX tab) the Director never plans a Flash, Glitch or Invert. If you set a kaleidoscope yourself, the Director leaves it alone. Hits are part of the plan, so they are saved with it and appear in a rendered music video.

Making a music video, step by step

1. Load your track (the Your Own Track card) and wait for the analysis.
2. Open the drawer (P) → Director. Pick a Style and what to pick scenes from. Press Re-roll until the timeline looks right, and fix single sections with ↻ or use.
3. Choose the FX hits level and which effects it may use. Shuffle FX until you like the rhythm of them.
4. Check Look and FX. Turn on Safe mode if the video will be posted publicly.
5. Export tab: choose the frame (16:9, 9:16, 1:1, 4:5), resolution and frame rate.
6. Press Render music video…. It records in real time (a 4-minute track takes 4 minutes) with a fade in and out, then saves an MP4 where Chrome allows.

The analyser is validated on a generated track at several sample rates. Very slow tracks can be read at double tempo (for example 70 BPM as 140). The visuals still lock to the beat; if the bar boundaries feel doubled, press K for beat lock or feed MIDI clock.

10Recording and export

1. Frame. Window (what you see), 16:9, 9:16 (vertical), 1:1, 4:5.
2. Resolution of the long edge: 720p, 1080p, 1440p, 4K.
3. Frame rate. 30 or 60.
4. Fade in / Fade out. Used by Render music video.
5. Output summary. Exact pixel size, frame rate, format, bitrate and megabytes per minute, so you know what a long take costs on disk.
6. Record, Screenshot, Output window. Record (C) starts and stops a take; Screenshot saves a still; Output window opens a clean pop-out for a second display.
7. Render music video… One-click whole-track render (section 9).

Tip Recordings contain only the visuals: no controls, labels or titles. Where the browser allows, a take streams straight to disk so a long set does not fill memory. Files are MP4 (H.264) where Chrome supports it.

1. Title. Rendering status.
2. Progress. Elapsed over total, the output size and the running file size.
3. Stop & save what we have. Ends early and still saves a valid file.

11Visuals only, and titles

Press V (the eye button) to hide everything and go fullscreen: no HUD, no drawer, no cursor, no text. Press V or Esc to bring it back. This is the mode for projecting a clean image.

Titles

You can add a name card or a logo, for example for a stream or a lower-third. It is off by default, only appears on screen, and is hidden while recording. If you want a title in a video, switch on Include in recordings.

1. Text and an optional artist or subtitle line.
2. Show. Off, Intro, Intro + end, or Always.
3. Animation. Fade, Rise, Pop, Glitch. Position (Centre, Lower third, Top), font, size, intro length and colour are below.
4. Logo / image. Choose an image; set its size beneath.
5. Include in recordings. Off by default. Leave it off for a clean file.

12Input panel

Open it with I or the meter button. It shows what the app is hearing and holds the settings that decide how it reacts.

1. Level meter. The bar and the peak marker. Aim for the bar around two-thirds on the loudest part of the track.
2. Input gain. Boost a quiet source up to 8×. Raise it for a quiet room or a quiet loopback.
3. Band emphasis. Flat, Bass (bass drives the visuals harder) or Air (highs drive them).
4. Drop sensitivity. Low, Med or High. Switches scene on the energy jump out of a breakdown. Needs auto-switch (1) on. The panel also shows the current frame rate.
5. Fade to black. On silence & end (default) or Never.
6. Recording target. The format, size and disk use of a recording with the current Export settings.

13MIDI

Open the MIDI panel with N. Chrome asks for permission the first time. Any USB or Bluetooth controller works, and so does a virtual port such as the IAC Driver.

1. Enable MIDI. Grants Chrome’s MIDI permission.
2. Knobs. Click Learn next to a control (Hue shift, Feedback, Density, Bloom, Evolve amount, Blend time, Input gain) and move a knob on your controller. × clears it. Knobs use soft takeover, so nothing jumps when you first touch them.
3. Buttons. Learn a note or CC for Next, Previous or Random scene, the scene queue’s Go, scene pads 1–8, Cycle engine, Beat lock, Auto-switch, Auto-Director, Next colour look, Next transition style, Visuals only, Record, and engine jumps.

MIDI clock. If your mixer, Ableton or a controller sends a clock, beat lock follows it instead of listening to the audio. The panel shows when a clock is detected.

Any slider: follow the music, or a knob

Right-click any slider in the drawer (or press the small ♪ that appears beside its name) to open its window. There you can make the slider react to the audio, bind it to a MIDI knob, or both.

1. React to audio. Choose Kick, Snare, Hat, Beat, Bar line, Bass, Mid, Treble, Loudness or Wobble (a slow sine on the beat). Off ends it.
2. Amount. −100% to +100% of the slider's whole span. Negative values move it the opposite way.
3. Smoothing. How quickly it settles after a hit. More smoothing is calmer; a drum can be almost instant.
4. MIDI → Learn. Press it, move a knob, done. The knob uses soft takeover, so nothing jumps. Clear removes it. Everything you bound shows in the MIDI panel as “Slider: …”.

The slider keeps your value as the middle of the movement. Drag it any time to move that middle; what is saved is always your value, never a moving one. Mapped sliders show a badge such as ♪ Kick ◉ CC 21. The bar in the window shows what the chosen source is doing right now. Bass, mid, treble, hats and the rest are measured against that signal's own range in this track, so 100% means its full swing and a loud master does not pin it.

Everything you map is listed in one place: open the MIDI panel (N) and press All mappings…. Each row lets you change what a slider follows, its amount and smoothing, and its knob. Pop out puts the list in its own window for a second screen.

Not every slider can follow the music: Variety, Blend time, fades, the cycle length and the title sizes would jump or redraw every frame, so they accept MIDI only. A scene's own Hue / Feedback / Density bars and the Media tab sliders are not part of this yet; the Media tab has its own MIDI target (Media FX strength).

14Your own shaders

Switch to the GLSL engine and press + Shader. Paste any Shadertoy shader (anything with a mainImage function) and press Compile & save. It joins the GLSL list and can be used by the Auto-Director like any other scene. Export saves your shaders as a file you can share.

1. Name.
2. Code. Standard Shadertoy inputs are provided: iResolution, iTime, iTimeDelta, iFrame, iMouse, iDate, and iChannel0 (512×2 audio: row 0 is the spectrum, row 1 the waveform). iChannel1 to iChannel3 are noise textures.
3. Compile & save. Extra audio-reactive values are available too: uBeat uKick uSnare uHat uPhase uBar uBeatTime uLock uBass uMid uTreb uLevel uHue uFb uDen.

15Keyboard cheat sheet

16Troubleshooting

17What has been tested, and the limits

If something behaves differently on your setup, please tell the person who gave you this file: it is exactly the information needed to fix it.

18Live set: queue, pads and two screens

The Live tab in the drawer (P) is for performing. It adds a scene queue, scene pads, pad behaviour modes and a one-click second screen, so you can run a set from the laptop while a clean picture goes to the projector.

1. Add a scene. Pick any scene and when it should go live: on the next bar, on the next beat, on the next drop or when I press Go. + Add to queue adds it; + Current scene queues what is on screen.
2. The queue. The first scene (highlighted) waits for its trigger, blends in, and the next one is armed. The line above it says what it is waiting for. Change a scene’s trigger, move it up or down, or remove it. Go (Enter, or a MIDI button) fires the waiting scene right now.
3. Scene pads. Eight slots you play with Alt+1–8 or a click. The pencil stores the scene that is on screen in that pad; ✕ clears it.
4. Pad behaviour. Choose Tap, Hold or Latch separately for FX pads and scene pads, and whether a press fires now, on the next beat or on the next bar.
5. Two screens. Opens the clean output on the other display, with a preview of the next scene below it.

How the triggers behave

The FX pads on the FX tab, Shift+1–8 and MIDI pad notes all follow these modes. Timed triggers use the beat grid when there is one (a loaded track, MIDI clock, or a confident BPM). Without a grid they fire straight away, so nothing ever sticks waiting. A queued scene always blends in like any other scene change, and a performance take records it.

Two screens

1. Plug in the projector and set it to extend your desktop.
2. Press Open the output on the other screen. The output opens as a clean window with no controls; in Chrome it is moved to the other display for you after you allow “window management” once. If your browser doesn’t offer that, drag the window to the projector yourself.
3. Double-click the output window (or press F in it) for fullscreen.
4. The laptop keeps the controls. Under the button, the preview shows the scene at the top of the queue (or the one you just picked) before it goes live: MilkDrop scenes show a live moving preview; GPU scenes (GLSL, Scope, Particles) show a card with their name until picture thumbnails arrive in a later version.

Setup check and the tour

Check my setup (the Live tab, or the link on the start screen) tests the things a gig depends on and says what to fix: browser, graphics (WebGL2 and the GPU), current frame rate, audio engine, system-audio capture, whether sound is arriving, MIDI (Test MIDI asks Chrome for access and lists your controllers), recording format, saving long takes, second-screen support and saved settings. Copy report puts the results on your clipboard. The short tour appears the first time you open the app and can be replayed from the Live tab.

19Library, timeline cards and batch render

Four things for people who make music videos and keep a big scene library: previews and tags to find a scene fast, Look & camera lanes and title / lyric cards on the Director's timeline, and batch render to export several picture shapes in one go.

Previews, tags and collections

1. Previews. Every scene gets a small picture. They draw themselves once, in about half a minute, when the app opens on the start screen (Make previews does it on demand, Redraw all starts again). They are kept in the browser, so later visits are instant. Grid shows them big.
2. Tags. Every scene has automatic tags: its engine, its family or category, and a mood read from how it actually looks (calm, intense, dark, bright, colourful, mono). Click a chip to show only those; click again or All to clear. Open the Tags line to see them.
3. Your own tags. Type a word in + tag and press Enter to tag the scene that is playing. Click a tag with a cross to remove it. The search box finds tags as well as names.
4. Collections. Make a named set from any engine: Add to collection… puts the playing scene in one (or starts a new one). Choosing a collection in the first menu shows only its scenes, and next / previous walk only those. In the Auto-Director, Pick scenes from → Collection plans a track using only that set.

The timeline editor, step by step

Open Director → Edit timeline. The editor opens docked under the visuals, so you see the picture while you edit; Expand makes it fill the screen (it remembers your choice) and the grey bar above it makes it taller or shorter. The first time, a short hint explains the three steps, and ? opens plain tips and shortcuts at any time.

Look & camera lanes

In the timeline editor, open More tracks (top right of the timeline). Under the FX lane are five lanes: Look (colour grade), Kaleido, Hue, Zoom and Spin (camera roll); the lane below them, Image FX, is for pictures and video. Click a lane to place a change, drag it to move it, and set its value in the Camera and title card controls fold-out at the bottom. A change holds until the next one on the same lane, and eases in rather than jumping. Auto hands the lane back to the Director from that point. They belong to the track's plan, so undo, save and load cover them, and a re-plan keeps them.

Title and lyric cards

Cards are timed words over the picture: lyrics, a song name, credits, a closing line. They are the green Cards lane, also under More tracks. Click the lane to add one, type its words in the panel (Enter makes a second line), drag it to move it and drag its right edge to make it longer. Selecting a card jumps the playhead to it so you can see it.

To fill the lane quickly, use the Titles tab, Lyric & title cards:

Cards use the font, size, colour, position and animation set on the Titles tab. Like every title they are on the screen only: hidden in visuals-only mode and kept out of recordings unless Include in recordings is on. Show cards turns them all off at once without deleting them.

Batch render

1. Load a track and open the Export tab. Under Render several sizes tick the shapes: 16:9 (YouTube), 9:16 (Shorts, Reels, TikTok), 1:1 or 4:5.
2. Press Choose a folder… once. Every file is then saved straight into it, with no dialog per file. (Without a folder, the files download one by one.)
3. Press Render all. The track plays and records once per shape, one after another, each file named after the track and its shape (for example My-Track-9x16-….mp4). The long edge is the resolution you set above.
4. Stop after this one lets the render in progress finish and skips the rest. Your own frame setting comes back when the queue ends.

Each render is real time, so three shapes of a 4-minute track take about 12 minutes; the estimate under the buttons shows the total. Keep the page open and visible. The Director plan, Look & camera lanes and cards are identical in every pass; only the frame changes.

20Your pictures, videos and the Ableton bridge

Pictures and videos as scenes

Any picture or video can be a scene. Open the Media tab and press Choose photo / video, or simply drop files anywhere on the window. Capture (on the main toolbar) snips part of a screen or window instead. The file stays in this browser, nothing is uploaded, and a media scene behaves like any other: it blends, the Director and the queue can use it, and the pads, looks, kaleidoscope, titles and recording all work on it. Double-click a media scene in the Scenes list to reopen its settings.

The effect strength can change while a track plays: map Media FX strength to a MIDI knob (section 13), or use the Image FX lane in the timeline editor (under More tracks).

The Ableton Track Bridge (optional)

The studio hears Ableton Live through a loopback device (the Ableton Live card). The optional Track Bridge adds one thing: it lets the visuals follow one chosen track in your set, for example only the bass, instead of the whole mix. It is a separate download, a small helper that runs on your computer and talks only to the studio page on that same computer.

1. Unzip the bridge download. On a Mac double-click Start Bridge.command, on Windows start-bridge.bat (Node.js 18 or newer is needed for this helper). It opens the studio.
2. In Live, drag Shabba Track Meter.amxd onto each track you want to follow. It passes the sound through unchanged and reports that track's level, bass, mid and treble.
3. In the studio open the Live tab, press Connect Track Bridge, choose a track and tick Focus GPU visuals. Untick it to go back to the normal mix.

21Interface, effects and projection

A glass interface that stays out of the way

The drawer is now a rounded, see-through card, so the picture shows around and through it. On the Look tab, under Interface, choose:

Click a number beside a slider to type an exact value (it is kept inside the slider's range; Esc cancels). Click a group heading to fold it; it stays folded next time. Press / to open the drawer and filter the controls of the open tab by name.

1. Saved looks. Seven starters (Neon club, VHS tape, Dream haze, Arcade, Pop print, Glitch city, Aurora night) and your own. Apply glides to a look; Copy code gives a code you can send to a friend.
2. Save current stores everything below as a look you name.
3. Glide time and Easing decide how a look takes over: 0 seconds snaps at once; Smooth, Even, Slow start, Slow end or Overshoot shape the move.
4. Paste a code adds a friend's look to your list.

Saved looks

A look is the visual treatment only: colour look, grade (bloom, exposure, contrast, saturation, hue, vignette, grain, chromatic edge), kaleidoscope and Evolve, the FX strengths, the effects rack, the palette and the backdrop. It never changes the scene, the titles or the Director.

When you apply one, every number glides to its new value over the glide time. An effect that comes on fades in from nothing, and one that goes away fades out before it switches off. A slider that is mapped to the music glides its middle value. A look code starts with SVL1.; anything pasted is checked, unknown parts are ignored and every number is kept inside its slider. A link can carry one too: …/app/?look=SVL1.… applies it, and …/app/?scene=gl|tunnel opens on that scene (the part before the bar is the engine: bc MilkDrop, gl GLSL, sc Scope, px Particles, ink, loom, fr, mesh).

The Effects tab

1. Background. A backdrop (Starfield, Plasma, Dust, Aurora, Sky, Glow, Gradient) blended with the scene by Screen, Add, Lighten, Overlay, Luma key (the scene shows where it is bright) or Behind (the backdrop shows where the scene is dark).
2. Scene layer. Any GPU scene as a second layer on top of the main one, with a blend mode and an amount. MilkDrop scenes can't be layers yet. It runs beside the main scene, so it costs frames on a slow graphics card.
3. Effects rack. Switch effects on and use ▲ ▼ to change their order; they run from the top down. Up to eight can be on at once. Each has its own settings and an Opacity.

The titles and lyric cards are drawn after the effects, so a CRT or ASCII effect never distorts your words. While scene previews are being made the effects are skipped, so no preview is baked with them. An effect that cannot start on a graphics card switches itself off and says so.

Audio shaping

1. Noise gate. Pulls quiet readings toward zero so room noise stops moving the visuals.
2. Floor and Ceiling. What counts as quiet and loud for the level reading (default −52 and −12 dB).
3. Bass cut. Calms a boomy source.
4. Before / After. Two small bars: the level as heard and as shaped.
5. Calibrate listens for five seconds (play the loudest and quietest parts) and sets the floor and ceiling to fit; Reset puts everything back.

Shaping changes the bass, mid, treble and level readings that steer the scenes. It does not touch beat or drop detection, and the Ableton Track Bridge's per-track readings are not shaped. With the defaults nothing changes.

Projection mapping

On the Live tab, Corner pin the output fits the picture to a wall, a screen seen at an angle or a shape. Press Edit corners, drag the four numbered pins, and use Soft edge to feather the borders. The output window and visuals-only mode follow. The warp is applied by the browser when it shows the picture, so recordings, renders and captures of the canvas are never warped. The pins are kept for next time; Reset puts them back.

More

• Picture-in-picture. The button beside the output button floats the visuals in a small window above other apps. It hides itself in a browser that can't do it.
• Spectrum scenes. Eight classics in the GLSL list: Spectrum Bars, Mirror Bars, Circle Bars, Waveform Line, Mirror Wave, Dot Matrix, Spectrum Rings and Glow Bars. They blend, take the look and the effects rack, and work with the Director like any scene.

22New in 4.8.0

Everything below is new since version 4.7.0. The start screen is in section 3 and the Hyperreal scenes in section 5.

Gallery and remix

• Gallery (G): every scene of every engine as large pictures, full screen. Click one to blend to it, Shift-click to put it in the Live queue (it fires on the next bar), and B / X rate the one under the pointer. The Colours view holds the colour looks, the palettes and your saved looks.
• Remix (Z): a new treatment for the scene that is playing: one colour idea, sometimes a kaleidoscope, at most two rack effects at moderate amounts. It never changes the scene, Safe mode or the titles, and it glides in like a saved look. Shift+Z steps back through the last ten.

Kaleidoscope centre

The kaleidoscope used to mirror the middle of the picture, so scenes with little happening at the centre came out empty. While a kaleidoscope is on (Look tab, or the kaleido pad), drag on the picture to choose the part it mirrors: the pattern stays centred on screen and is built from that spot. Double-click the picture to centre it again. Your point is saved with your settings. When no kaleidoscope is showing, dragging bends the picture as before (pointer play, below).

Pointer play

Hold the mouse (or a finger) on the picture to twist and pull it around the pointer, on every engine. Drag right for a clockwise swirl, left for the other way; a quick flick throws harder. Let go and it eases back. Look → Pointer play switches it off or sets its strength; Safe mode halves it.

Motion lanes

Right-click a drawer slider (or press its ♪) and choose Draw on timeline: the slider gets its own lane in the timeline editor, where you draw how it moves over the track. Points snap to the beat grid when Snap is on, and Alt-drag bends the stretch between two points. To record instead of draw, arm the lane (●), play, and move the slider or its MIDI knob. If the slider also follows the music, that movement rides on top of the curve. Lanes save with the plan and play whenever a planned track plays, Director on or off.

Studio render and the safety net

Export → Render mode now offers Studio (frame by frame) next to Live take (real time). Studio renders the loaded track without playing it, the way a music program bounces a mix: a slow graphics card makes the render take longer, never choppier, and a light scene renders faster than real time. The sound in the file is the track itself.

Every piece of a render or live recording is also kept in the browser until the file is safely saved. If the page closes or crashes mid-take, the next start offers to recover what was written.

Sessions and .shabba files

Tracks you plan are kept on this computer with their plan, motion lanes, look and slider mappings, so the start screen lists your recent sessions and one click reopens everything. Nothing is uploaded; a track over 300 MB is not kept.

Director → Save session… writes all of it to one .shabba file you can move to another computer, with the track inside if you tick that. Open it with Open session…, the Open a .shabba Session link on the start screen, or by dropping the file on the window.

Logo and text inside the visuals

Titles → Blend sets how the title card sits in the picture: On top (as before), Inside the visuals (the logo and text are fed into the scene, so its trails and tunnels smear them and they pulse with the kick) or Made of the visuals (the picture shows only inside the logo and letters). MilkDrop and Prism 3D scenes show Inside as On top.

Auto-light, Eco and steady frame pacing

• Auto-light (Look tab) slowly keeps the brightness in a good range: it pulls a scene down when feedback and glow wash it out, and lifts a muddy one a little on a loud track. It is much slower than the music, so a drop still hits and a breakdown still goes dark. It never moves your Exposure slider.
• Eco when idle (Look → Interface): with nothing playing the visuals run at half speed, and not at all while the tab is hidden, so a laptop stays cool. Recording is never slowed.
• Steady frame pacing (Look → Interface): when a heavy scene can’t keep up with a fast screen, every frame is held for the same time (a steady 60 or 40 on a 120 Hz display) instead of stuttering between rates. It never drops below about 40 fps.

A palette from a photo

In the Effects tab the Custom palette takes its five colours from From photo… (a picture you pick), From media scene (the picture or clip playing) or From this frame (the visuals on screen).

Preview pictures and the flashing-lights notice

• Every scene’s preview picture now comes with the app, so nothing is drawn when it first opens. Previews show the scene on its own, without your look or effects, and dark scenes are evened out so none is a black box.
• The first time a source starts, a short notice explains that the visuals can flash, with a one-click start in Safe mode. ⚠ Flashing Lights on the start screen opens it again.

23Credits and licences

• Butterchurn (the engine that plays MilkDrop-format presets), copyright © 2013–2018 Jordan Berg, MIT licence.
• mp4-muxer (writes the MP4 files of Studio render), copyright © 2023 Vanilagy, MIT licence.
• Hanken Grotesk (copyright 2021 The Hanken Grotesk Project Authors) and Instrument Serif (copyright 2022 The Instrument Serif Project Authors), SIL Open Font License 1.1.
• MilkDrop was created by Ryan Geiss; the preset format and the idea are his.
• Everything else was written for this project: the original presets and the Lab that makes more, the GLSL, Scope, Particle, Living Ink, Light Loom, Fractal Bloom, Prism 3D and Hyperreal scenes, the Auto-Director and its effects, the audio and track analysis, and the interface. The file contains no presets by other authors. The full licence texts are in CREDITS.txt.