From 534ced53fe95416910eed0a205c489e52e2ea8c8 Mon Sep 17 00:00:00 2001
From: Jeff Walden <jwalden@mit.edu>
Date: Sun, 17 Nov 2024 16:15:10 -0800
Subject: [PATCH] feat: Implement a `sceneRecalledTrigger` variable whose value
 changes every time a scene is recalled, enabling it to be used in a
 scene-recalled trigger.  (#69)

---
 companion/HELP.md   | 16 ++++++++++++++++
 src/instance.js     |  6 ++++--
 src/midi/session.ts |  7 ++++++-
 src/variables.ts    | 28 ++++++++++++++++++++++------
 4 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/companion/HELP.md b/companion/HELP.md
index 1217e079..88ca3f8f 100644
--- a/companion/HELP.md
+++ b/companion/HELP.md
@@ -23,6 +23,22 @@ Controls the Allen & Heath SQ.
 - Talkback macro
 - Scene step increment
 
+New in v.2.1.0
+
+- Fix scene recalling if the mixer MIDI channel isn't 1
+- Add Step +/-0.1dB choices for setting signal levels
+- Permit setting signal levels between -85dB and -40dB
+- Make assigning the LR mix to matrixes work correctly
+- Allow setting the pan/balance of matrix 3 used as an output
+- Add an action to make active/inactive an FX return in LR/mixes
+- Define pan/balance variables on-demand as pan/balance change messages are sent by the mixer
+- Restart module instances in response to configuration changes only if absolutely required
+- Add a `sceneRecalledTrigger` variable whose value changes every time a scene is recalled, suitable for use in user-defined triggers
+
+New in v.2.0.0 (not released)
+
+- Convert to Companion v3 format
+
 New in v.1.1.0
 
 - Add listener for MIDI inbound data
diff --git a/src/instance.js b/src/instance.js
index 174c39e3..70139d9e 100644
--- a/src/instance.js
+++ b/src/instance.js
@@ -8,7 +8,7 @@ import { getFeedbacks } from './feedbacks/feedbacks.js'
 import { Mixer } from './mixer/mixer.js'
 import { canUpdateOptionsWithoutRestarting, noConnectionOptions, optionsFromConfig } from './options.js'
 import { getPresets } from './presets.js'
-import { getVariables } from './variables.js'
+import { CurrentSceneId, getVariables, SceneRecalledTriggerId } from './variables.js'
 
 import api from './api.js'
 
@@ -97,10 +97,12 @@ export class sqInstance extends InstanceBase {
 		this.setVariableDefinitions(getVariables(this, model))
 
 		this.setVariableValues({
+			[SceneRecalledTriggerId]: 0,
+
 			// This value may very well be wrong, but there's no defined way to
 			// query what the current scene is, nor to be updated if it changes
 			// and this module didn't do it.
-			currentScene: 1,
+			[CurrentSceneId]: 1,
 		})
 	}
 
diff --git a/src/midi/session.ts b/src/midi/session.ts
index db9b23d4..100e92f8 100644
--- a/src/midi/session.ts
+++ b/src/midi/session.ts
@@ -8,6 +8,7 @@ import { MixerMessageParser } from './parse/parse.js'
 import { MidiTokenizer } from './tokenize/tokenize.js'
 import { prettyByte, prettyBytes } from '../utils/pretty.js'
 import { asyncSleep, sleep } from '../utils/sleep.js'
+import { CurrentSceneId, SceneRecalledTriggerId } from '../variables.js'
 
 /**
  * The port number used for MIDI-over-TCP connections to SQ mixers.
@@ -147,10 +148,14 @@ export class MidiSession {
 			verboseLog(`Scene changed: ${newScene}`)
 
 			mixer.currentScene = newScene
+
+			const sceneRecalledTrigger = Number(instance.getVariableValue(SceneRecalledTriggerId)!)
 			instance.setVariableValues({
+				[SceneRecalledTriggerId]: sceneRecalledTrigger + 1,
+
 				// The currentScene variable is 1-indexed, consistent with how
 				// the current scene is displayed to users in mixer UI.
-				currentScene: newScene + 1,
+				[CurrentSceneId]: newScene + 1,
 			})
 		})
 		mixerChannelParser.on('mute', (msb: number, lsb: number, vf: number) => {
diff --git a/src/variables.ts b/src/variables.ts
index 5cb97058..a447165e 100644
--- a/src/variables.ts
+++ b/src/variables.ts
@@ -2,13 +2,29 @@ import type { CompanionVariableDefinition } from '@companion-module/base'
 import type { SQInstanceInterface as sqInstance } from './instance-interface.js'
 import type { Model } from './mixer/model.js'
 
-export function getVariables(instance: sqInstance, model: Model): CompanionVariableDefinition[] {
-	const variables: CompanionVariableDefinition[] = []
+/**
+ * The variable ID for the variable containing the last recalled scene
+ * (1-indexed).
+ */
+export const CurrentSceneId = 'currentScene'
+
+/**
+ * The variable ID for the variable updated every time a scene is recalled
+ * intended for use in triggers.
+ */
+export const SceneRecalledTriggerId = 'sceneRecalledTrigger'
 
-	variables.push({
-		name: 'Scene - Current',
-		variableId: 'currentScene',
-	})
+export function getVariables(instance: sqInstance, model: Model): CompanionVariableDefinition[] {
+	const variables: CompanionVariableDefinition[] = [
+		{
+			name: 'Scene - Scene Recalled',
+			variableId: SceneRecalledTriggerId,
+		},
+		{
+			name: 'Scene - Current',
+			variableId: CurrentSceneId,
+		},
+	]
 
 	model.forEachInputChannel((channel, channelLabel) => {
 		model.forEachMixAndLR((mix, _mixLabel, mixDesc) => {