ProControls — Displays Tutorial

VUMeter

Level Meter

A VUMeter is a vertical bar meter — the kind you see on a mixing console or audio interface. The bar rises and falls to show a signal level in real time. You drive it from your sketch code by setting its value property (0–1 by default) in your draw() loop.

Step 1 Your first VU meter

Create a VUMeter with no options and it appears at a sensible default size. The value property controls how high the bar is — 0 is empty, 1 is full. The example below animates the level using sin() so you can see it move.

editable — changes update the preview

const meter = new VUMeter();

function draw() {
  // Drive it from your sketch — here a sine wave
  meter.value = (sin(frameCount * 0.05) + 1) / 2;
}

Auto-placement: When you leave out x and y, ProControls places the control automatically so it does not overlap others.

Step 2 Customizing the meter

Use label to add a text label, peak to show a hanging peak indicator dot that falls slowly after the signal drops, and segments to split the bar into discrete blocks (like a classic LED meter). Try changing these!

editable — try changing segments or removing peak

const meter = new VUMeter({
  x: 20, y: 20,
  width: 50, height: 220,
  label: 'LEVEL',
  peak: true,      // show a hanging peak dot
  segments: 20,    // split into 20 LED-style blocks
});

function draw() {
  meter.value = (sin(frameCount * 0.04) + 1) / 2;
}

Step 3 Setting the danger zone

Use warnAt to set where the bar turns yellow, and dangerAt to set where it turns red — both as fractions of 0–1. This lets you mark the "safe zone," the "caution zone," and the "clip zone" visually, just like a real mixing board.

editable — try adjusting warnAt and dangerAt

const meter = new VUMeter({
  x: 20, y: 20,
  width: 50, height: 220,
  label: 'GAIN',
  peak: true,
  warnAt:   0.7,   // yellow above 70%
  dangerAt: 0.9,   // red above 90%
});

function draw() {
  // Spike into the red occasionally
  const t = frameCount * 0.03;
  meter.value = abs(sin(t)) * 0.85 + abs(sin(t * 3.7)) * 0.15;
}

Step 4 Stereo meters side by side

Creating two VUMeters next to each other makes a classic stereo pair. Give each one an explicit x and y so they sit side by side. Drive them independently for a true left/right display.

editable — try making the left and right signals different

const L = new VUMeter({
  x: 8, y: 20, width: 30, height: 200,
  label: 'L', peak: true, segments: 16,
});

const R = new VUMeter({
  x: 48, y: 20, width: 30, height: 200,
  label: 'R', peak: true, segments: 16,
});

function draw() {
  L.value = (sin(frameCount * 0.05) + 1) / 2;
  R.value = (cos(frameCount * 0.04) + 1) / 2;
}

VUDial

Circular Meter

A VUDial is a circular level indicator — like the large needle meters on vintage studio gear. An arc sweeps from low to high as the value increases. Set value from your draw() loop just like VUMeter.

Step 1 Your first VU dial

A one-liner creates a circular meter. The arc sweeps around the dial as the value changes. Watch the arc respond to the animated value below.

editable — changes update the preview

const dial = new VUDial();

function draw() {
  dial.value = (sin(frameCount * 0.05) + 1) / 2;
}

Step 2 Customizing the dial

The size option controls the diameter. You can add a label, set warnAt and dangerAt thresholds for color changes, and show a numeric readout with readout: 'raw'.

editable — try changing size, warnAt, or dangerAt

const dial = new VUDial({
  x: 40, y: 25,
  size: 120,
  label: 'OUTPUT',
  readout: 'raw',
  decimals: 2,
  warnAt:   0.7,
  dangerAt: 0.9,
});

function draw() {
  dial.value = (sin(frameCount * 0.04) + 1) / 2;
}

Step 3 Custom min and max

By default the dial goes from 0 to 1, but you can set min and max to any range — for example, decibels from −60 to 0. The readout will show the mapped value, not the raw 0–1 fraction.

editable — try changing min, max, or the value formula

const dbMeter = new VUDial({
  x: 40, y: 25,
  size: 120,
  label: 'dBFS',
  min: -60, max: 0,
  readout: 'raw',
  decimals: 1,
  warnAt:   0.75,   // 75% → −15 dBFS
  dangerAt: 0.92,   // 92% → −5 dBFS
});

function draw() {
  // Animate from −60 to near 0
  dbMeter.value = (sin(frameCount * 0.03) + 1) / 2;
}

Step 4 Updating from audio analysis

In a real project you would drive the meter from audio analysis or a sensor reading. Here we simulate a signal with noise to show how a responsive meter looks. Use smoothing (0–1) to add ballistic lag so the needle does not jump instantly.

editable — try changing the smoothing value

const meter = new VUDial({
  x: 40, y: 25,
  size: 120,
  label: 'SIGNAL',
  warnAt: 0.75, dangerAt: 0.92,
  smoothing: 0.85,   // ballistic lag (0 = instant, 1 = frozen)
});

let target = 0;
function draw() {
  // Random spikes like real audio
  if (random() < 0.05) target = random(0.5, 1.0);
  target *= 0.96;   // decay
  meter.value = target;
}

Tip: smoothing is available on both VUMeter and VUDial. A value around 0.8–0.9 gives the classic "needle ballistics" feel of analog meters.

LEDMeter

LED Bar

A LEDMeter is a horizontal bar of discrete LED segments — the kind of level meter you see on a guitar tuner or effects pedal. Unlike VUMeter, it always displays as distinct blocks and is usually wider than it is tall.

Step 1 Your first LED meter

A one-liner creates a horizontal bar of LED segments. Set value (0–1) from your sketch to light up segments from left to right.

editable — changes update the preview

const bar = new LEDMeter();

function draw() {
  bar.value = (sin(frameCount * 0.05) + 1) / 2;
}

Step 2 Setting segments and size

Use segments to control how many LEDs the bar is divided into. More segments means finer resolution. The width and height options control the overall size of the bar.

editable — try changing segments or the bar size

const bar = new LEDMeter({
  x: 10, y: 35,
  width: 180, height: 22,
  label: 'INPUT',
  segments: 24,    // 24 individual LED blocks
  warnAt:   0.7,   // yellow past 70%
  dangerAt: 0.9,   // red past 90%
});

function draw() {
  bar.value = (sin(frameCount * 0.04) + 1) / 2;
}

Step 3 Multiple meters stacked

Stack several LEDMeters vertically to create a channel strip or a multi-band display. Position them with explicit y values so they line up neatly.

editable — try adding a third bar or changing the speeds

const opts = { x: 10, width: 180, height: 18, segments: 20,
               warnAt: 0.7, dangerAt: 0.9 };

const ch1 = new LEDMeter({ ...opts, y: 18, label: 'CH 1' });
const ch2 = new LEDMeter({ ...opts, y: 54, label: 'CH 2' });

function draw() {
  ch1.value = (sin(frameCount * 0.05) + 1) / 2;
  ch2.value = (cos(frameCount * 0.04) + 1) / 2;
}

Step 4 Driving from a real value

In practice you feed the LEDMeter from a computed number — the amplitude of an audio signal, the speed of a physics object, or anything that changes over time. Here a ConsolePanel shows the raw value alongside the meter.

editable — watch the value in the console as you change the formula

openConsolePanel();

const bar = new LEDMeter({
  x: 10, y: 100, width: 300, height: 20,
  segments: 24, warnAt: 0.7, dangerAt: 0.9,
});

let vel = 0;
function draw() {
  vel += random(-0.05, 0.05);
  vel = constrain(vel, 0, 1);
  bar.value = vel;
  if (frameCount % 15 === 0) console.log(vel.toFixed(3));
}

ADSRDisplay

Envelope Viewer

An ADSRDisplay draws an Attack–Decay–Sustain–Release envelope shape — the classic four-parameter curve used in synthesizers to shape how a sound evolves over time. It is a read-only visual; pair it with four dials or sliders to let the user edit the envelope values.

Step 1 Your first ADSR display

Create an ADSRDisplay with default values and it shows a classic envelope shape. The four properties are attack, decay, sustain, and release — all 0–1 fractions of their maximum time.

editable — changes update the preview

const env = new ADSRDisplay({
  attack:  0.1,
  decay:   0.2,
  sustain: 0.6,
  release: 0.4,
});

Step 2 Sizing and labeling

Set width and height to fit the display in your layout. The label option adds a title. The curve automatically fills the available space.

editable — try changing the ADSR values

const env = new ADSRDisplay({
  x: 10, y: 10,
  width: 240, height: 130,
  label: 'AMP ENV',
  attack:  0.05,  // very fast attack
  decay:   0.3,
  sustain: 0.7,
  release: 0.6,
});

Step 3 Connecting to dials

The classic use case: four dials control the ADSR shape. In the onChange of each dial, update the matching property on the ADSRDisplay. The display redraws automatically.

editable — turn the knobs and watch the envelope update

const env = new ADSRDisplay({
  x: 10, y: 10, width: 300, height: 100,
});

const dials = new MultiDial({
  x: 10, y: 120,
  size: 55,
  min: 0, max: 1, readout: 'raw', decimals: 2,
  dials: {
    'A': { value: 0.1 },
    'D': { value: 0.25 },
    'S': { value: 0.6 },
    'R': { value: 0.4 },
  },
  onChange: v => {
    env.attack  = v.A;
    env.decay   = v.D;
    env.sustain = v.S;
    env.release = v.R;
  },
});

Step 4 Animating the envelope

You can update the ADSR properties from anywhere in your sketch — not just from a dial callback. Here the sustain level pulses slowly to show how the display responds to programmatic changes.

editable — try animating attack or release instead

const env = new ADSRDisplay({
  x: 10, y: 20,
  width: 240, height: 120,
  label: 'ENV',
  attack: 0.1, decay: 0.2, release: 0.5,
});

function draw() {
  // Sustain level breathes slowly
  env.sustain = (sin(frameCount * 0.02) + 1) / 2;
}

Markup

Rich Text Panel

A Markup control displays styled text — paragraphs, bold, italic, links, and separators — rendered on the canvas. Use it for help text, status readouts, or any formatted copy that belongs inside your ProControls layout.

Step 1 Your first markup panel

Pass a string to the text option. Plain text is displayed as-is. The panel auto-sizes to fit its content.

editable — changes update the preview

const info = new Markup({
  text: 'Hello from ProControls!',
});

Step 2 Formatting — bold, italic, and separators

Wrap text in **double asterisks** for bold and *single asterisks* for italic. A line containing only --- becomes a horizontal rule that separates sections.

editable — try adding more bold or italic spans

const info = new Markup({
  x: 10, y: 10,
  width: 260,
  text:
    '**ProControls** for p5.js\n' +
    '*by David Stein*\n' +
    '---\n' +
    'Drag · Scroll wheel · Touch\n' +
    'All controls are **live editable**.',
});

Step 3 Links and click callbacks

Add a link with [label](url) syntax. Clicking a link opens the URL in a new tab by default. You can override this with the onClick(href) callback to handle the link yourself.

editable — try clicking the link in the preview

openConsolePanel();

const info = new Markup({
  x: 10, y: 100, width: 260,
  text:
    '**ProControls** — visit\n' +
    '[the docs](https://procontrols.org)\n' +
    'for the full reference.',
  // intercept link clicks instead of opening a tab:
  onClick: href => console.log('Link clicked: ' + href),
});

Step 4 Updating text dynamically

Set the text property at any time to update what the Markup panel displays. This is useful for status readouts that should update as your sketch runs — for example, showing the current frame rate or a sensor value.

editable — watch the values update in the preview

const status = new Markup({
  x: 10, y: 10,
  width: 260,
  text: 'Loading...',
});

function draw() {
  if (frameCount % 10 === 0) {
    status.text =
      '**Status**\n' +
      'Frame: ' + frameCount + '\n' +
      'FPS: ' + Math.round(frameRate()) + '\n' +
      'Time: ' + (millis() / 1000).toFixed(1) + 's';
  }
}

Tip: For short status lines that change every frame, update text only every few frames (e.g. frameCount % 10 === 0) to avoid unnecessary redraws.

ConsolePanel

Log Output

A ConsolePanel displays text log output directly on the canvas — replacing console.log() output that would otherwise only appear in the browser's developer tools. New lines appear at the bottom and scroll up as the panel fills.

Step 1 Your first console panel

Create a ConsolePanel and then call console.log() anywhere in your sketch. ProControls intercepts the call and shows the output in the panel. You can still see the output in the browser console too.

editable — changes update the preview

openConsolePanel();

console.log('Hello, ConsolePanel!');
console.log('Every console.log appears here.');

Step 2 Sizing and options

Set width and height to control the panel size. The maxLines option caps how many lines are kept before older ones are dropped. You can also set movable: false to lock the panel in place so users cannot drag it around.

editable — try changing maxLines or width

openConsolePanel();

// Log a few lines to fill the panel
for (let i = 1; i <= 6; i++) {
  console.log('Line ' + i + ' — hello from your sketch!');
}

Step 3 Logging from interactions

The most common pattern is to log values in onChange callbacks so you can see what a control is doing as you interact with it. The ConsolePanel gives you that feedback without switching to the browser's developer tools.

editable — drag the slider and watch the log update

openConsolePanel();

const vol = new AnalogSlider({
  x: 30, y: 100,
  label: 'VOL',
  min: 0, max: 100, value: 50,
  readout: 'raw', decimals: 0,
  onChange: v => console.log('Volume: ' + Math.round(v)),
  onRelease: v => console.log('Set to: ' + Math.round(v)),
});

Step 4 Clearing and controlling the log

Call console.clear() to empty the panel, or use log.clear() directly on the ConsolePanel instance. Logging from draw() works, but throttle it (e.g., every 15 frames) so the panel does not scroll too fast to read.

editable — watch the running counter in the panel

openConsolePanel();

function draw() {
  if (frameCount % 20 === 0) {
    console.log(
      'Frame ' + frameCount +
      '  fps=' + Math.round(frameRate())
    );
  }
  // Clear after 100 frames to keep it tidy
  if (frameCount % 100 === 0) console.clear();
}

TimeGraphPanel

Time-Series Graph

A TimeGraphPanel draws a scrolling time-series graph — like an oscilloscope or a heart-rate monitor. Push new data points with push(value) and the graph scrolls left to show the history. You can plot multiple series on the same panel in different colors.

Step 1 Your first time graph

Create a TimeGraphPanel, then call push(value) every frame (or as often as you have new data). The graph auto-scales to fit the values you push.

editable — changes update the preview

let graph;

function setup() {
  createCanvas(360, 200);
  graph = new TimeGraphPanel({
    x: 0, y: 0,
    width: 360, height: 200,
    movable: false, resizable: false, minimizable: false,
  });
}

function draw() {
  proControlBackground();
  graph.push(sin(frameCount * 0.05));
}

Step 2 Customizing the graph

Set min and max to fix the vertical range (instead of auto-scaling). The gridLines option draws horizontal reference lines, and label adds a title to the panel.

editable — try removing min/max to see auto-scaling

let graph;

function setup() {
  createCanvas(360, 200);
  graph = new TimeGraphPanel({
    x: 0, y: 0,
    width: 360, height: 200,
    label: 'Signal',
    min: -1, max: 1,
    movable: false, minimizable: false, resizable: false,
  });
}

function draw() {
  proControlBackground();
  graph.push(sin(frameCount * 0.06) * 0.8 + noise(frameCount * 0.01) * 0.4 - 0.2);
}

Step 3 Multiple series

Push data to named series to plot several lines on the same graph. Pass an object to push() where each key is a series name and the value is the new data point. Each series gets its own color automatically.

editable — try adding a third series

let graph;

function setup() {
  createCanvas(360, 200);
  graph = new TimeGraphPanel({
    x: 0, y: 0,
    width: 360, height: 200,
    label: 'X / Y',
    min: -1, max: 1,
    movable: false, minimizable: false, resizable: false,
  });
}

function draw() {
  proControlBackground();
  graph.push({
    'X': sin(frameCount * 0.05),
    'Y': cos(frameCount * 0.07),
  });
}

Step 4 Graphing control values in real time

A TimeGraphPanel paired with a control lets you visualize how a value changes as the user interacts. Drag the slider below and watch your movements recorded in the graph as a live trace.

editable — drag the slider and watch the graph trace

let graph, slider;

function setup() {
  createCanvas(320, 240);
  graph = new TimeGraphPanel({
    x: 0, y: 0, width: 320, height: 120,
    label: 'Slider value over time',
    min: 0, max: 100,
    movable: false, minimizable: false, resizable: false,
  });

  slider = new AnalogSlider({
    x: 28, y: 130,
    label: 'DRAG ME',
    min: 0, max: 100, value: 50,
    readout: 'raw', decimals: 0,
  });
}

function draw() {
  proControlBackground();
  graph.push(slider.value);
}

Tip: Call graph.clear() to reset all series, or set graph.history (number of data points to keep) to control how far back the graph scrolls.

Step 5 Custom timestamps

By default each push() call is stamped with the current wall-clock time. You can override this by including a time field (in seconds) in the data object. This lets you replay pre-recorded data at the correct positions, graph sporadic events that don't arrive every frame, or synchronize multiple graphs to a shared timeline.

editable — try changing the time values

let graph;

function setup() {
  createCanvas(360, 200);
  graph = new TimeGraphPanel({
    x: 0, y: 0,
    width: 360, height: 200,
    label: 'Logged data',
    min: -1, max: 1,
    movable: false, minimizable: false, resizable: false,
  });

  // Replay pre-recorded samples — gaps appear where time jumps
  const log = [
    {time: 0.0, value:  0.0},
    {time: 0.5, value:  0.8},
    {time: 1.0, value:  0.3},
    {time: 2.5, value: -0.6},
    {time: 3.0, value:  0.9},
    {time: 5.0, value: -0.2},
  ];
  for (const pt of log) graph.push(pt);
}

function draw() {
  proControlBackground();
}

Tip: For live data that doesn't arrive every frame, use { time: millis() / 1000, value: v } so the X axis reflects the actual elapsed time between samples rather than frame count.

StatusPanel

Performance Monitor

A StatusPanel is a real-time performance meter showing frame rate, frame time, control count, and JavaScript heap memory. It's perfect for monitoring your sketch during development — spot performance bottlenecks, watch how many controls you've created, and ensure your draw loop stays responsive at 60 FPS.

Step 1 Your first StatusPanel

Create a StatusPanel with no options — it anchors to the bottom of the canvas by default and shows live FPS, frame time (Δt in milliseconds), active control count, and available heap memory.

editable — panel updates every frame

// Auto-anchors to bottom, resizes with canvas
const status = new StatusPanel();

Step 2 Position it manually

Provide x and y to place the panel anywhere on the canvas. Set width and height to control its size. When you specify position, it no longer auto-resizes with the canvas.

editable — try different x, y, width, height values

const status = new StatusPanel({
  x: 20, y: 20,
  width: 280, height: 24,
});

Step 3 Monitoring sketch performance

The Δt (delta time) metric shows average frame time in milliseconds. For 60 FPS, target is ~16.67ms. If Δt turns red and climbs above that, your draw() loop or event handlers are doing heavy work. Watch the Controls counter — it increments with each control you add.

editable — add more controls and watch the counter

const status = new StatusPanel({
  x: 20, y: 20,
  width: 280,
});

// Every control you create increments the counter
new Dial({     x: 20,  y: 50, size: 40, label: 'Freq' });
new AnalogSlider({ x: 90, y: 50, width: 30, height: 100, label: 'Gain' });
new Switch({   x: 150, y: 80, width: 50, label: 'Power' });
new GridPad({  x: 220, y: 50, cols: 4, rows: 4 });

Step 4 Toggle visibility at runtime

Set status.visible = false to hide the panel without destroying it. Turn it back on with status.visible = true. This is useful for hiding debug overlays in production code or toggling the monitor on demand.

editable — change visible to false to hide it

const status = new StatusPanel();

// You can hide/show it anytime
// status.visible = false;

// Or toggle with a key press in your own code:
// if (key === 's') status.visible = !status.visible;

Tip: StatusPanel is invisible by default and consumes minimal resources when hidden. It's safe to leave in production code and toggle on with status.visible = true for debugging when needed.

ListView

Scrollable List

A ListView displays a scrollable list of strings. Click any item to select it; use the scroll wheel or scrollbar to navigate. The onSelect callback fires when a row is clicked, passing the item and its index.

editable — changes update the preview

const lv = new ListView({
  x: 20, y: 15,
  width: 260, height: 190,
  items: ['Alpha', 'Beta', 'Gamma', 'Delta', 'Epsilon', 'Zeta', 'Eta', 'Theta',
          'Iota', 'Kappa', 'Lambda', 'Mu', 'Nu', 'Xi', 'Omicron'],
  onSelect: ({item, index}) => console.log('selected:', index, item),
});

Tip: Assign a new array to lv.items to update the list. Use lv.selectedIdx to get or set the selection programmatically.

GridView

Scrollable Table

A GridView displays a scrollable table where each row is an object with named fields. Column widths are automatically computed from the header names and cell values. The header row stays fixed at the top (no vertical scroll). Horizontal scrolling is available when columns exceed the panel width. Click a row to select it.

editable — changes update the preview

const gv = new GridView({
  x: 10, y: 10,
  width: 400, height: 200,
  items: [
    { name: 'Alpha',   type: 'sine',   freq: 440, amp: 0.8 },
    { name: 'Beta',    type: 'square', freq: 220, amp: 0.6 },
    { name: 'Gamma',   type: 'saw',    freq: 880, amp: 0.4 },
    { name: 'Delta',   type: 'noise',  freq: 110, amp: 1.0 },
    { name: 'Epsilon', type: 'sine',   freq: 660, amp: 0.5 },
    { name: 'Zeta',    type: 'square', freq: 330, amp: 0.7 },
    { name: 'Eta',     type: 'saw',    freq: 550, amp: 0.3 },
  ],
  onSelect: ({item, index}) => console.log('selected row', index, item.name),
});

Tip: Reassign gv.items with new data to update the grid. Column headers are automatically derived from the object keys. Use gv.scrollX and gv.scrollY to programmatically control scrolling.

HeatMapView

Hierarchical Heatmap

A HeatMapView displays a grid of colored cells representing hierarchical data grouped by multiple dimensions. Each cell's color intensity reflects the magnitude of its aggregated value. Click any cell to drill down one level; use breadcrumbs at the top to jump back to earlier drill levels, or right-click to pop back one level. When you reach the deepest dimension, clicking a cell fires the onSelect callback with the full drill path.

editable — click to drill, right-click to go back

const sampleData = [
  {product:'cars', brand:'ford', trim:'Taurus', quantity:1423},
  {product:'cars', brand:'ford', trim:'F-150', quantity:3200},
  {product:'cars', brand:'honda', trim:'Civic', quantity:2100},
  {product:'cars', brand:'honda', trim:'Accord', quantity:1950},
  {product:'trucks', brand:'chevy', trim:'Silverado', quantity:1800},
  {product:'trucks', brand:'ford', trim:'F-250', quantity:2100},
];

const hm = new HeatMapView({
  x: 20, y: 15,
  width: 360, height: 260,
  fields: ['product', 'brand', 'trim'],
  valueField: 'quantity',
  items: sampleData,
  onSelect: ({path, value, items}) => {
    console.log('Drilled to:', path.join(' > '));
    console.log('Total value:', value);
    console.log('Matching items:', items.length);
  },
});

Tip: The fields array defines the drill-down hierarchy. Start with product, then brand, then trim. The valueField specifies which property to sum at each level. Reassign hm.items with new data to update the heatmap. Use the breadcrumb bar to navigate, or right-click any cell to pop back one level.