Use Companion's native Gauge element for level displays

Companion 5.1 marks image-buffer feedbacks as deprecated, and its layered buttons have a Gauge element that follows a number directly. So: - New numeric value feedbacks for gauges: fader/level position 0-100 for inputs, busses, matrix outputs, control groups, aux sends and matrix sends (one shared fader taper: 0 dB at 75 %, -inf at 0), raw pan 0..1 for a symmetric gauge, GEQ band dB, and input meter position. - Every knob and meter preset is now a layered preset: background box, channel name, live dB text and a Gauge bound to $(local:pos); on/off and mute tint the background. Meters use a vertical green/amber/red gauge. Text uses size 100 with shrink-to-fit (14 rendered tiny on 5.1) and the level gauge is white so it stays visible on a green background. - The old image-bar feedbacks keep working and are labelled "(legacy image)"; HELP.md explains how to add a gauge to your own button. - A sleeping iPad no longer logs a relay send error every few seconds: one warning per iPad per 10 minutes. Checked on the booth Companion 5.1: the layered knob previews show live names, levels and gauge fills. npm test: 392 checks pass. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 09:50:31 -04:00
parent 90dee14444
commit 9f64d20a24
6 changed files with 374 additions and 111 deletions
@@ -4,7 +4,19 @@ import { COLORS } from './feedbacks.js'
 export const MAX_PRESETS = 3000
 export const MAX_PRESET_BYTES = 4 * 1024 * 1024

-const { white: WHITE, dark: DARK, red: RED, green: GREEN, amber: AMBER, bar: BAR } = COLORS
+const { white: WHITE, dark: DARK, red: RED, green: GREEN, amber: AMBER } = COLORS
+
+// Layered presets (native gauges). Colours are 0xRRGGBB numbers.
+const BLACK = 0x000000
+const TEXT = 0xffffff
+const GAUGE_GREEN = 0x00b050
+/** Level gauge fill: white, so it stays visible on a green (send on) or red (muted) background. */
+const GAUGE_LEVEL = 0xffffff
+const METER_AMBER = 0xf0a000
+const METER_RED = 0xe00000
+const ON_GREEN = 0x00a050 // a send is on / an input is assigned
+const MUTED_RED = 0xb01010 // muted, peak
+const SIGNAL_BG = 0x00501e // signal present on a meter button

 const fb = (feedbackId, options, bg, color = WHITE) => ({ feedbackId, options, style: { bgcolor: bg, color } })
 const act = (actionId, options) => ({ actionId, options })
@@ -29,21 +41,82 @@ function build(inst, { grMeters = true, sendKnobs: withSendKnobs = true } = {})
 		feedbacks,
 		...extra,
 	})
-	/** Rotary preset: press = `press`, turning = `adjust` with ∓1 (the action's delta option). */
-	const knob = (name, text, press, adjustActionId, adjustOptions, localVariables, feedbacks) => ({
-		type: 'simple',
+	/** A rotary step: press = `press`, turning = `adjust` with the action's delta option set to -1 / +1. */
+	const knobSteps = (press, adjustActionId, adjustOptions) => [
+		{
+			down: press,
+			up: [],
+			rotate_left: [act(adjustActionId, { ...adjustOptions, delta: -1 })],
+			rotate_right: [act(adjustActionId, { ...adjustOptions, delta: 1 })],
+		},
+	]
+	const text = (id, x, y, width, height, value) => ({ type: 'text', id, x, y, width, height, text: value, fontsize: 100, fontsizeAllowShrink: true, color: TEXT, halign: 'center', valign: 'center' })
+	/** Boolean feedback on a layered preset: it colours the background box. */
+	const tint = (feedbackId, options, color) => ({ feedbackId, options, styleOverrides: [{ elementId: 'bg', elementProperty: 'color', override: color }] })
+	/**
+	 * Layered rotary preset with a native Companion gauge along the bottom: black background, the entity name on top, the
+	 * dB text below it, and a gauge fed by the `pos` local variable. `level` and `pos` are the text and the numeric value
+	 * feedbacks for the same thing.
+	 */
+	const layeredKnob = ({ name, title, press, adjust: [adjustActionId, adjustOptions], level: [levelId, levelOptions], pos: [posId, posOptions], feedbacks }) => ({
+		type: 'layered',
 		name,
-		style: { text, size: 'auto', color: WHITE, bgcolor: DARK },
-		steps: [
+		elements: [
+			{ type: 'box', id: 'bg', x: 0, y: 0, width: 100, height: 100, color: BLACK },
+			text('title', 0, 0, 100, 55, title),
+			text('level', 0, 52, 100, 32, '$(local:level) dB'),
 			{
-				down: press,
-				up: [],
-				rotate_left: [act(adjustActionId, { ...adjustOptions, delta: -1 })],
-				rotate_right: [act(adjustActionId, { ...adjustOptions, delta: 1 })],
+				type: 'gauge',
+				id: 'gauge',
+				x: 0,
+				y: 84,
+				width: 100,
+				height: 16,
+				value: { isExpression: true, value: '$(local:pos)' },
+				min: 0,
+				max: 100,
+				orientation: 'horizontal',
+				trackStyle: 'dimmed',
+				fillEnabled: true,
+				multiColour: false,
+				stops: [{ value: 0, color: GAUGE_LEVEL, gradient: false }],
 			},
 		],
+		steps: knobSteps(press, adjustActionId, adjustOptions),
 		feedbacks,
-		localVariables,
+		localVariables: [localFeedback('level', levelId, levelOptions), localFeedback('pos', posId, posOptions)],
+	})
+	/** Layered input meter: name on the left, a vertical gauge (green / amber / red zones) at the right edge. */
+	const layeredMeter = ({ name, title, options }) => ({
+		type: 'layered',
+		name,
+		elements: [
+			{ type: 'box', id: 'bg', x: 0, y: 0, width: 100, height: 100, color: BLACK },
+			text('title', 0, 0, 86, 100, title),
+			{
+				type: 'gauge',
+				id: 'gauge',
+				x: 86,
+				y: 0,
+				width: 14,
+				height: 100,
+				value: { isExpression: true, value: '$(local:pos)' },
+				min: 0,
+				max: 100,
+				orientation: 'vertical',
+				trackStyle: 'dimmed',
+				fillEnabled: true,
+				multiColour: true,
+				stops: [
+					{ value: 0, color: GAUGE_GREEN, gradient: false },
+					{ value: 70, color: METER_AMBER, gradient: false },
+					{ value: 90, color: METER_RED, gradient: false },
+				],
+			},
+		],
+		steps: [{ down: [], up: [] }],
+		feedbacks: [tint('input_signal', { ...options, threshold: 5 }, SIGNAL_BG), tint('input_peak', { ...options, hold: 2 }, MUTED_RED)],
+		localVariables: [localFeedback('pos', 'input_meter_pos', options)],
 	})
 	const group = (id, name, ids) => ({ id, type: 'simple', name, presets: ids })

@@ -57,15 +130,15 @@ function build(inst, { grMeters = true, sendKnobs: withSendKnobs = true } = {})
 			const name = s.displayName('input', n)
 			const tag = `${n} · ${name}`
 			presets[`input_mute_${n}`] = simple(`Mute: ${tag}`, nameVar('input', n), [act('input_mute', { channels: [n], state: 'toggle' })], [fb('input_muted', { channel: n }, RED)])
-			presets[`input_knob_${n}`] = knob(
-				`Fader knob: ${tag}`,
-				`${nameVar('input', n)}\\n$(local:level) dB`,
-				[act('input_mute', { channels: [n], state: 'toggle' })],
-				'input_fader_adjust',
-				{ channel: n },
-				[localFeedback('level', 'input_fader_value', { channel: n })],
-				[fb('input_muted', { channel: n }, RED), { feedbackId: 'input_fader_bar', options: { channel: n, color: BAR } }],
-			)
+			presets[`input_knob_${n}`] = layeredKnob({
+				name: `Fader knob: ${tag}`,
+				title: nameVar('input', n),
+				press: [act('input_mute', { channels: [n], state: 'toggle' })],
+				adjust: ['input_fader_adjust', { channel: n }],
+				level: ['input_fader_value', { channel: n }],
+				pos: ['input_fader_pos', { channel: n }],
+				feedbacks: [tint('input_muted', { channel: n }, MUTED_RED)],
+			})
 			presets[`input_solo_${n}`] = simple(`Solo: ${tag}`, `${nameVar('input', n)}\\nSOLO`, [act('input_solo', { channels: [n], state: 'toggle' })], [fb('input_solo', { channel: n }, AMBER, COLORS.black)])
 			for (const [meter, prefix, label] of [
 				['level', 'input_meter', 'Meter'],
@@ -73,16 +146,7 @@ function build(inst, { grMeters = true, sendKnobs: withSendKnobs = true } = {})
 				['comp', 'input_comp_gr', 'Compressor reduction'],
 			]) {
 				if (meter !== 'level' && !grMeters) continue
-				presets[`${prefix}_${n}`] = simple(
-					`${label}: ${tag}`,
-					nameVar('input', n),
-					[],
-					[
-						{ feedbackId: 'input_meter_bar', options: { channel: n, meter } },
-						fb('input_signal', { channel: n, meter, threshold: 5 }, GREEN),
-						fb('input_peak', { channel: n, meter, hold: 2 }, RED),
-					],
-				)
+				presets[`${prefix}_${n}`] = layeredMeter({ name: `${label}: ${tag}`, title: nameVar('input', n), options: { channel: n, meter } })
 				meterIds[meter].push(`${prefix}_${n}`)
 			}
 			muteIds.push(`input_mute_${n}`)
@@ -114,15 +178,15 @@ function build(inst, { grMeters = true, sendKnobs: withSendKnobs = true } = {})
 		for (const n of s.named('buss')) {
 			const tag = `${n} · ${s.displayName('buss', n)} (${s.bussMode(n)})`
 			presets[`buss_mute_${n}`] = simple(`Master mute: ${tag}`, nameVar('buss', n), [act('buss_mute', { busses: [n], state: 'toggle' })], [fb('buss_muted', { buss: n }, RED)])
-			presets[`buss_knob_${n}`] = knob(
-				`Master fader (knob): ${tag}`,
-				`${nameVar('buss', n)}\\n$(local:level) dB`,
-				[act('buss_mute', { busses: [n], state: 'toggle' })],
-				'buss_fader_adjust',
-				{ buss: n },
-				[localFeedback('level', 'buss_fader_value', { buss: n })],
-				[fb('buss_muted', { buss: n }, RED), { feedbackId: 'buss_fader_bar', options: { buss: n, color: BAR } }],
-			)
+			presets[`buss_knob_${n}`] = layeredKnob({
+				name: `Master fader (knob): ${tag}`,
+				title: nameVar('buss', n),
+				press: [act('buss_mute', { busses: [n], state: 'toggle' })],
+				adjust: ['buss_fader_adjust', { buss: n }],
+				level: ['buss_fader_value', { buss: n }],
+				pos: ['buss_fader_pos', { buss: n }],
+				feedbacks: [tint('buss_muted', { buss: n }, MUTED_RED)],
+			})
 			muteIds.push(`buss_mute_${n}`)
 			knobIds.push(`buss_knob_${n}`)
 		}
@@ -145,15 +209,15 @@ function build(inst, { grMeters = true, sendKnobs: withSendKnobs = true } = {})
 			presets[`send_on_${ch}_${b}`] = simple(`Send on/off: ${tag}`, text, [act('send_on', { channel: ch, buss: b, state: 'toggle' })], [fb('send_on', { channel: ch, buss: b }, GREEN)], { localVariables: lv })
 			onIds.push(`send_on_${ch}_${b}`)
 			if (withSendKnobs) {
-				presets[`send_knob_${ch}_${b}`] = knob(
-					`Send level (knob): ${tag}`,
-					text,
-					[act('send_on', { channel: ch, buss: b, state: 'toggle' })],
-					'send_level_adjust',
-					{ channel: ch, buss: b },
-					lv,
-					[fb('send_on', { channel: ch, buss: b }, GREEN), { feedbackId: 'send_level_bar', options: { channel: ch, buss: b, color: BAR } }],
-				)
+				presets[`send_knob_${ch}_${b}`] = layeredKnob({
+					name: `Send level (knob): ${tag}`,
+					title: nameVar('input', ch),
+					press: [act('send_on', { channel: ch, buss: b, state: 'toggle' })],
+					adjust: ['send_level_adjust', { channel: ch, buss: b }],
+					level: ['send_level_value', { channel: ch, buss: b }],
+					pos: ['send_level_pos', { channel: ch, buss: b }],
+					feedbacks: [tint('send_on', { channel: ch, buss: b }, ON_GREEN)],
+				})
 				knobIds.push(`send_knob_${ch}_${b}`)
 			}
 		}
@@ -185,15 +249,15 @@ function build(inst, { grMeters = true, sendKnobs: withSendKnobs = true } = {})
 		for (const n of s.named('matrix')) {
 			const tag = `${n} · ${s.displayName('matrix', n)}`
 			presets[`matrix_mute_${n}`] = simple(`Mute: ${tag}`, nameVar('matrix', n), [act('matrix_mute', { matrix: n, state: 'toggle' })], [fb('matrix_muted', { matrix: n }, RED)])
-			presets[`matrix_knob_${n}`] = knob(
-				`Fader (knob): ${tag}`,
-				`${nameVar('matrix', n)}\\n$(local:level) dB`,
-				[act('matrix_mute', { matrix: n, state: 'toggle' })],
-				'matrix_fader_adjust',
-				{ matrix: n },
-				[localFeedback('level', 'matrix_fader_value', { matrix: n })],
-				[fb('matrix_muted', { matrix: n }, RED)],
-			)
+			presets[`matrix_knob_${n}`] = layeredKnob({
+				name: `Fader (knob): ${tag}`,
+				title: nameVar('matrix', n),
+				press: [act('matrix_mute', { matrix: n, state: 'toggle' })],
+				adjust: ['matrix_fader_adjust', { matrix: n }],
+				level: ['matrix_fader_value', { matrix: n }],
+				pos: ['matrix_fader_pos', { matrix: n }],
+				feedbacks: [tint('matrix_muted', { matrix: n }, MUTED_RED)],
+			})
 			muteIds.push(`matrix_mute_${n}`)
 			knobIds.push(`matrix_knob_${n}`)
 		}
@@ -205,15 +269,15 @@ function build(inst, { grMeters = true, sendKnobs: withSendKnobs = true } = {})
 		for (const n of s.named('cg')) {
 			const tag = `${n} · ${s.displayName('cg', n)}`
 			presets[`cg_mute_${n}`] = simple(`Mute: ${tag}`, nameVar('cg', n), [act('cg_mute', { cg: n, state: 'toggle' })], [fb('cg_muted', { cg: n }, RED)])
-			presets[`cg_knob_${n}`] = knob(
-				`Fader (knob): ${tag}`,
-				`${nameVar('cg', n)}\\n$(local:level) dB`,
-				[act('cg_mute', { cg: n, state: 'toggle' })],
-				'cg_fader_adjust',
-				{ cg: n },
-				[localFeedback('level', 'cg_fader_value', { cg: n })],
-				[fb('cg_muted', { cg: n }, RED)],
-			)
+			presets[`cg_knob_${n}`] = layeredKnob({
+				name: `Fader (knob): ${tag}`,
+				title: nameVar('cg', n),
+				press: [act('cg_mute', { cg: n, state: 'toggle' })],
+				adjust: ['cg_fader_adjust', { cg: n }],
+				level: ['cg_fader_value', { cg: n }],
+				pos: ['cg_fader_pos', { cg: n }],
+				feedbacks: [tint('cg_muted', { cg: n }, MUTED_RED)],
+			})
 			muteIds.push(`cg_mute_${n}`)
 			knobIds.push(`cg_knob_${n}`)
 		}
@@ -231,15 +295,15 @@ function build(inst, { grMeters = true, sendKnobs: withSendKnobs = true } = {})
 			const options = { matrixIn: inN, matrixOut: out }
 			const lv = [localFeedback('level', 'matrix_send_level_value', options)]
 			presets[`msend_on_${inN}_${out}`] = simple(`Matrix send on/off: ${tag}`, text, [act('matrix_send_on', { ...options, state: 'toggle' })], [fb('matrix_send_on', options, GREEN)], { localVariables: lv })
-			presets[`msend_knob_${inN}_${out}`] = knob(
-				`Matrix send level (knob): ${tag}`,
-				text,
-				[act('matrix_send_on', { ...options, state: 'toggle' })],
-				'matrix_send_level_adjust',
-				options,
-				lv,
-				[fb('matrix_send_on', options, GREEN), { feedbackId: 'matrix_send_level_bar', options: { ...options, color: BAR } }],
-			)
+			presets[`msend_knob_${inN}_${out}`] = layeredKnob({
+				name: `Matrix send level (knob): ${tag}`,
+				title: `Matrix In ${inN}`,
+				press: [act('matrix_send_on', { ...options, state: 'toggle' })],
+				adjust: ['matrix_send_level_adjust', options],
+				level: ['matrix_send_level_value', options],
+				pos: ['matrix_send_level_pos', options],
+				feedbacks: [tint('matrix_send_on', options, ON_GREEN)],
+			})
 			onIds.push(`msend_on_${inN}_${out}`)
 			knobIds.push(`msend_knob_${inN}_${out}`)
 		}