feat(PrompterView): customizable shuttle webhid buttons (Sofie-Automation#1610)

* feat(EAV-372): customizable shuttle webhid buttons

an array of keyIndex:actionId can be provided in shuttleWebHid_buttonMap

* feat(EAV-372): execute actions also on shuttle button release

* chore(EAV-372): improve log message

Author: ianshade

meteor/server/api/userActions.ts

@@ -399,9 +399,9 @@ class ServerUserActionAPI
 		userEvent: string,
 		eventTime: Time,
 		rundownPlaylistId: RundownPlaylistId,
-		actionDocId: AdLibActionId | RundownBaselineAdLibActionId | BucketAdLibActionId,
+		actionDocId: AdLibActionId | RundownBaselineAdLibActionId | BucketAdLibActionId | null,
 		actionId: string,
-		userData: ActionUserData,
+		userData: ActionUserData | null,
 		triggerMode: string | null
 	) {
 		return ServerClientAPI.runUserActionInLogForPlaylistOnWorker(
@@ -411,7 +411,7 @@ class ServerUserActionAPI
 			rundownPlaylistId,
 			() => {
 				check(rundownPlaylistId, String)
-				check(actionDocId, String)
+				check(actionDocId, Match.Maybe(String))
 				check(actionId, String)
 				check(userData, Match.Any)
 				check(triggerMode, Match.Maybe(String))

packages/corelib/src/worker/studio.ts

@@ -266,9 +266,9 @@ export interface QueueNextSegmentProps extends RundownPlayoutPropsBase {
 }
 export type QueueNextSegmentResult = { nextPartId: PartId } | { queuedSegmentId: SegmentId | null }
 export interface ExecuteActionProps extends RundownPlayoutPropsBase {
-	actionDocId: AdLibActionId | RundownBaselineAdLibActionId | BucketAdLibActionId
+	actionDocId: AdLibActionId | RundownBaselineAdLibActionId | BucketAdLibActionId | null
 	actionId: string
-	userData: any
+	userData: any | null
 	triggerMode?: string
 	actionOptions?: { [key: string]: any }
 }

packages/documentation/docs/user-guide/features/prompter.md

@@ -104,6 +104,21 @@ When opening the Prompter View for the first time, it is necessary to press the
 
 ![Contour ShuttleXpress input mapping](/img/docs/main/features/contour-shuttle-webhid.jpg)
 
+**Customizable Button Mapping:**
+
+By default, the ShuttleXpress buttons execute built-in prompter actions. However, you can customize button behavior by mapping buttons to global adlib actions using the `shuttleWebHid_buttonMap` query parameter.
+
+| Query parameter | Type | Description |
+| :--- | :--- | :--- |
+| `shuttleWebHid_buttonMap` | Comma-separated strings | Maps ShuttleXpress buttons to global adlib actions. Each entry should be in the format `buttonIndex:actionId`, where `buttonIndex` is the button number (0-indexed) and `actionId` is the ID of a global adlib action defined in your blueprints. Each custom action is triggered once on button press (trigger mode: `pressed`) and once on button release (trigger mode: `released`). Multiple mappings are comma-separated. |
+
+**Example:**
+```
+?mode=shuttlewebhid&shuttleWebHid_buttonMap=0:toggle_control_room_mics,1:make_coffee
+```
+
+Buttons without a custom mapping will use their default behavior.
+
 ####
 
 #### Control using midi input \(_?mode=pedal_\)

packages/job-worker/src/playout/adlibAction.ts

@@ -76,21 +76,7 @@ export async function executeAdlibActionAndSaveModel(
 		throw UserError.create(UserErrorMessage.ActionsNotSupported)
 	}
 
-	const [adLibAction, baselineAdLibAction, bucketAdLibAction] = await Promise.all([
-		context.directCollections.AdLibActions.findOne(data.actionDocId as AdLibActionId, {
-			projection: { _id: 1, privateData: 1, publicData: 1 },
-		}),
-		context.directCollections.RundownBaselineAdLibActions.findOne(
-			data.actionDocId as RundownBaselineAdLibActionId,
-			{
-				projection: { _id: 1, privateData: 1, publicData: 1 },
-			}
-		),
-		context.directCollections.BucketAdLibActions.findOne(data.actionDocId as BucketAdLibActionId, {
-			projection: { _id: 1, privateData: 1, publicData: 1 },
-		}),
-	])
-	const adLibActionDoc = adLibAction ?? baselineAdLibAction ?? bucketAdLibAction
+	const adLibActionDoc = await findActionDoc(context, data)
 
 	if (adLibActionDoc && adLibActionDoc.invalid)
 		throw UserError.from(
@@ -202,6 +188,26 @@ export interface ExecuteActionParameters {
 	triggerMode: string | undefined
 }
 
+async function findActionDoc(context: JobContext, data: ExecuteActionProps) {
+	if (data.actionDocId === null) return undefined
+
+	const [adLibAction, baselineAdLibAction, bucketAdLibAction] = await Promise.all([
+		context.directCollections.AdLibActions.findOne(data.actionDocId as AdLibActionId, {
+			projection: { _id: 1, privateData: 1, publicData: 1 },
+		}),
+		context.directCollections.RundownBaselineAdLibActions.findOne(
+			data.actionDocId as RundownBaselineAdLibActionId,
+			{
+				projection: { _id: 1, privateData: 1, publicData: 1 },
+			}
+		),
+		context.directCollections.BucketAdLibActions.findOne(data.actionDocId as BucketAdLibActionId, {
+			projection: { _id: 1, privateData: 1, publicData: 1 },
+		}),
+	])
+	return adLibAction ?? baselineAdLibAction ?? bucketAdLibAction
+}
+
 export async function executeActionInner(
 	context: JobContext,
 	playoutModel: PlayoutModel,

packages/meteor-lib/src/api/userActions.ts

@@ -121,9 +121,9 @@ export interface NewUserActionAPI {
 		userEvent: string,
 		eventTime: Time,
 		rundownPlaylistId: RundownPlaylistId,
-		actionDocId: AdLibActionId | RundownBaselineAdLibActionId | BucketAdLibActionId,
+		actionDocId: AdLibActionId | RundownBaselineAdLibActionId | BucketAdLibActionId | null,
 		actionId: string,
-		userData: ActionUserData,
+		userData: ActionUserData | null,
 		triggerMode?: string
 	): Promise<ClientAPI.ClientResponse<ExecuteActionResult>>
 	segmentAdLibPieceStart(

packages/webui/src/client/ui/Prompter/PrompterView.tsx

@@ -66,6 +66,7 @@ interface PrompterConfig {
 	xbox_speedMap?: number[]
 	xbox_reverseSpeedMap?: number[]
 	xbox_triggerDeadZone?: number
+	shuttleWebHid_buttonMap?: string[]
 	marker?: 'center' | 'top' | 'bottom' | 'hide'
 	showMarker: boolean
 	showScroll: boolean
@@ -192,6 +193,7 @@ export class PrompterViewContent extends React.Component<Translated<IProps & ITr
 				const val = Number.parseFloat(firstIfArray(queryParams['xbox_triggerDeadZone']) as string)
 				return Number.isNaN(val) ? undefined : val
 			})(),
+			shuttleWebHid_buttonMap: asArray(queryParams['shuttleWebHid_buttonMap']),
 			marker: (firstIfArray(queryParams['marker']) as any) || undefined,
 			showMarker: queryParams['showmarker'] === undefined ? true : queryParams['showmarker'] === '1',
 			showScroll: queryParams['showscroll'] === undefined ? true : queryParams['showscroll'] === '1',
@@ -422,6 +424,19 @@ export class PrompterViewContent extends React.Component<Translated<IProps & ITr
 			MeteorCall.userAction.take(e, ts, playlist._id, playlist.currentPartInfo?.partInstanceId ?? null)
 		)
 	}
+
+	executeAction(e: Event | string, actionId: string, triggerMode?: string): void {
+		const { t } = this.props
+		if (!this.props.rundownPlaylist) {
+			logger.error('No active Rundown Playlist to execute the action in')
+			return
+		}
+		const playlist = this.props.rundownPlaylist
+		doUserAction(t, e, UserAction.START_GLOBAL_ADLIB, (e, ts) =>
+			MeteorCall.userAction.executeAction(e, ts, playlist._id, null, actionId, null, triggerMode)
+		)
+	}
+
 	private onWindowScroll = () => {
 		this.triggerCheckCurrentTakeMarkers()
 	}

packages/webui/src/client/ui/Prompter/controller/customizable-shuttle-webhid-device.ts

@@ -0,0 +1,38 @@
+import { PrompterViewContent } from '../PrompterView'
+import { ShuttleWebHidController } from './shuttle-webhid-device'
+
+enum ShuttleButtonTriggerMode {
+	PRESSED = 'pressed',
+	RELEASED = 'released',
+}
+
+export class CustomizableShuttleWebHidController extends ShuttleWebHidController {
+	private actionMap: Record<number, string> = {}
+
+	constructor(view: PrompterViewContent) {
+		super(view)
+		view.configOptions.shuttleWebHid_buttonMap?.forEach((entry) => {
+			const substrings = entry.split(':')
+			if (substrings.length !== 2) return
+			this.actionMap[parseInt(substrings[0], 10)] = substrings[1]
+		})
+	}
+
+	protected onButtonPressed(keyIndex: number): void {
+		const actionId = this.actionMap[keyIndex]
+		if (actionId === undefined) return super.onButtonPressed(keyIndex)
+
+		this.prompterView.executeAction(`Shuttle button ${keyIndex} press`, actionId, ShuttleButtonTriggerMode.PRESSED)
+	}
+
+	protected onButtonReleased(keyIndex: number): void {
+		const actionId = this.actionMap[keyIndex]
+		if (actionId === undefined) return super.onButtonReleased(keyIndex)
+
+		this.prompterView.executeAction(
+			`Shuttle button ${keyIndex} release`,
+			actionId,
+			ShuttleButtonTriggerMode.RELEASED
+		)
+	}
+}

packages/webui/src/client/ui/Prompter/controller/manager.ts

@@ -5,8 +5,8 @@ import { ControllerAbstract } from './lib.js'
 import { JoyConController } from './joycon-device.js'
 import { KeyboardController } from './keyboard-device.js'
 import { ShuttleKeyboardController } from './shuttle-keyboard-device.js'
-import { ShuttleWebHidController } from './shuttle-webhid-device.js'
 import { XboxController } from './xbox-controller-device.js'
+import { CustomizableShuttleWebHidController } from './customizable-shuttle-webhid-device.js'
 
 export class PrompterControlManager {
 	private _view: PrompterViewContent
@@ -38,7 +38,7 @@ export class PrompterControlManager {
 				this._controllers.push(new JoyConController(this._view))
 			}
 			if (this._view.configOptions.mode.includes(PrompterConfigMode.SHUTTLEWEBHID)) {
-				this._controllers.push(new ShuttleWebHidController(this._view))
+				this._controllers.push(new CustomizableShuttleWebHidController(this._view))
 			}
 			if (this._view.configOptions.mode.includes(PrompterConfigMode.XBOX)) {
 				this._controllers.push(new XboxController(this._view))

packages/webui/src/client/ui/Prompter/controller/shuttle-webhid-device.ts

@@ -8,7 +8,7 @@ import { logger } from '../../../lib/logging.js'
  * This class handles control of the prompter using Contour Shuttle / Multimedia Controller line of devices
  */
 export class ShuttleWebHidController extends ControllerAbstract {
-	private prompterView: PrompterViewContent
+	protected prompterView: PrompterViewContent
 
 	private speedMap = [0, 1, 2, 3, 5, 7, 9, 30]
 
@@ -87,6 +87,7 @@ export class ShuttleWebHidController extends ControllerAbstract {
 			logger.debug(`Button ${keyIndex} down`)
 		})
 		shuttle.on('up', (keyIndex: number) => {
+			this.onButtonReleased(keyIndex)
 			logger.debug(`Button ${keyIndex} up`)
 		})
 		shuttle.on('jog', (delta, value) => {
@@ -142,6 +143,10 @@ export class ShuttleWebHidController extends ControllerAbstract {
 		}
 	}
 
+	protected onButtonReleased(_keyIndex: number): void {
+		// no-op
+	}
+
 	protected onJog(delta: number): void {
 		if (Math.abs(delta) > 1) return // this is a hack because sometimes, right after connecting to the device, the delta would be larger than 1 or -1