@lumiastream/lumia-types 3.9.3 → 3.9.4

package/dist/custom-code/custom-actions.md

@@ -25,7 +25,7 @@ Let's get started:
 **System bases** (built into Lumia):
 `delay, lumia, overlay, api, commandRunner, inputEvents`
 
-> Note: `lumia` and `overlay` also accept the aliases `lumiaActions` and `overlayActions`, and the input base is `inputEvents` (plural).
+> Note: the canonical system bases are `lumia` and `overlay`. The older spellings `lumiaActions` and `overlayActions` still run but are **deprecated** — prefer `lumia` / `overlay`. The input base is `inputEvents` (plural).
 
 **Integration bases** — every connected integration is also a valid base. These include (and more are added over time):
 `twitch, youtube, facebook, tiktok, kick, discord, obs, slobs, meld, spotify, youtubemusic, nowplaying, vlc, voicemod, streamerbot, vtubestudio, midi, osc, artnet, mqtt, serial, websocket, broadlink, hue, lifx, nanoleaf, govee, wled, wiz, tplink, tuya, yeelight, elgato, streamdeck, touchportal, loupedeck, homeassistant, switchbot` plus any installed plugin (use the plugin's id as the base).
@@ -36,7 +36,27 @@ Let's get started:
 
 `variables`: allows you to send in different variables for each action. But do note that the variables that are already on the command/alert will also be spread on to this variables object. Variables are not required
 
-There are more fields that are sometimes used in actions. `delay` (a number in milliseconds) can be added to any action to wait before running it.
+To pause between actions, insert a dedicated **delay step**: an entry whose `type` is `"delay"` with the milliseconds in `delay` (e.g. `{ type: "delay", delay: 1000 }`). It can carry any `base` and runs in order with the rest of the list. (An inline `delay` on a non-delay action is **not** applied by the runner — use a delay step.)
+
+#### Where actions live: the unified `actions` lane
+
+Inside a Lumia **command** or **alert**, every action — whatever its `base` (a `lumia` system action, an `overlay` action, a `twitch` action, an integration, a plugin) — lives together in one ordered list on the command:
+
+```json
+{
+  "actions": {
+    "before": [{ "base": "lumia", "type": "tts", "value": { "message": "Hi" } }],
+    "after": [{ "base": "twitch", "type": "clip", "value": { "title": "Clutch!", "duration": 30 } }],
+    "waitForActions": true
+  }
+}
+```
+
+- **`before`** runs before the command/alert's main effect (its light / overlay reaction); **`after`** runs after it.
+- **`waitForActions`** (optional): when `true`, each action is awaited so the list runs in strict order before the command continues; when omitted or `false`, the list fires without waiting.
+- Every entry is one action object of the shape `{ base, type, value?, delay?, args? }` — the same object you pass to the custom-code `actions()` helper. `delay` holds the milliseconds for a `type: "delay"` step; `args` carries the extra payload used by imported Streamer.bot actions.
+
+This unified `actions` lane is the current model, and the one the AI action creator and the Streamer.bot / Mix It Up importers target. It **replaces** the older per-source command fields (`lumiaActions`, `overlayActions`, `api`, `commandRunner`, `inputEvents`) and the per-integration lanes (`command.<integration>.before/after` — e.g. `command.wavelink`, `command.streamfog`, whose entries have no `base`), all of which are **deprecated** — within the unified lane the source is simply each entry's `base`.
 
 ### Passing an array of actions
 
@@ -63,9 +83,11 @@ These are the built-in `type` values for each system base.
 
 **`base: "commandRunner"`** — `app/file, shell command, delay`
 
-**`base: "inputEvents"`** — `keyboard, mouse, delay`
+**`base: "inputEvents"`** — `keyboard, mouse, delay`. The key/mouse data is **flat on the action**, not under `value`:
+> - `keyboard`: `{ base: "inputEvents", type: "keyboard", keyboardValue: { value: "ctrl+j", valueType: "combination" } }` — `valueType` is `combination` (a hotkey like `ctrl+shift+f5`) or `input` (type the literal `value` as text); optional `longPress`, `cpm`.
+> - `mouse`: `{ base: "inputEvents", type: "mouse", mouseValue: { x: 0, y: 100, clickEvent: "left", moveType: "set" } }` — `clickEvent` is `left` / `right` / `none`; optional `x1`, `y1`, `doubleClick`, `mouseSpeed`.
 
-**`base: "delay"`** — no `type`; pass the millisecond delay directly as the value, e.g. `{ base: "delay", value: 1000 }`.
+**delay step** — an entry with `type: "delay"` pauses the list; put the milliseconds in `delay` (e.g. `{ type: "delay", delay: 1000 }`). `duration` is accepted in place of `delay`, and the step runs under any `base`.
 
 > Tip: most of the `lumia` and `overlay` actions already have dedicated helper functions (`tts`, `chatbot`, `overlaySetTextContent`, etc.) in `helper-functions.md`. Reach for `actions()` mainly when you need an integration action that does not have a helper yet.
 
@@ -460,6 +482,8 @@ async function() {
 }
 ```
 
+> MIDI device targeting: `port` (the device's port number) is the simplest selector and is required. On a multi-device setup — where ports can shift between sessions — also pass the optional `deviceId` and/or `deviceName`; Lumia resolves the target by `deviceId`, then `deviceName`, then `port`. `type` is `note-on`, `note-off`, or `delay` (a `delay` entry just waits its `delay` ms).
+
 #### Twitch (`base: "twitch"`)
 
 Twitch actions take a `value` object. Most string inputs — usernames, message ids, comma-separated option lists — go in `value.message`. Each action needs the matching Twitch permission to be granted on your connection.
@@ -569,7 +593,23 @@ async function() {
 }
 ```
 
-Convenience source types (Lumia builds the `inputSettings` for you): `SetSourceText` (`{ inputName, text }`), `SetGenericUrlSource` / `SetSourceUrl` (`{ inputName, url }`), `SetGenericFileSource` / `SetImageFileSource` / `SetMediaFileSource` (`{ inputName, file }`). All other request-types match the OBS v5 API exactly.
+Common direct request-types (flat fields, verified against real setups):
+
+| `request-type` | fields |
+| --- | --- |
+| `SetCurrentProgramScene` | `{ sceneName }` |
+| `SetSceneItemEnabled` | `{ sceneName, inputName, sceneItemEnabled }` — Lumia resolves `inputName` → the scene-item id |
+| `SetSourceFilterEnabled` | `{ sourceName, filterName, filterEnabled }` |
+| `SaveSourceScreenshot` | `{ sourceName, imageFormat, imageFilePath }` |
+| `StartStream` / `StopStream` / `StartRecord` / `StopRecord` | no extra fields |
+
+Convenience source types let you set a source's content without hand-building `inputSettings`, but they only work if you **also** pass `lumiaOrigin: "SetInputSettings"` — Lumia rewrites the request into a real `SetInputSettings` call using it. Without `lumiaOrigin` the alias is sent verbatim and OBS rejects it. The aliases: `SetSourceText` (`{ inputName, text }`), `SetGenericUrlSource` / `SetSourceUrl` (`{ inputName, url }`), `SetGenericFileSource` / `SetImageFileSource` / `SetMediaFileSource` (`{ inputName, file }`):
+
+```js
+{ base: "obs", "request-type": "SetMediaFileSource", lumiaOrigin: "SetInputSettings", inputName: "Replay", file: "{{get_latest_file_from_folder=G:/Replays}}" }
+```
+
+For custom code it's usually simpler to skip the alias and call `sendRawObsJson({ "request-type": "SetInputSettings", inputName: "Replay", inputSettings: { local_file: "..." } })` directly. All other request-types match the OBS v5 API exactly.
 
 #### Streamlabs Desktop (`base: "slobs"`)
 
@@ -657,20 +697,20 @@ These read their fields **flat** on the action object (no `value` wrapper).
 
 ```js
 async function() {
-    // MQTT: publish to a topic on a configured broker (host = the broker's host)
-    await actions([{ base: "mqtt", type: "send", host: "192.168.1.50", topic: "home/light", value: "ON" }]);
+    // MQTT: publish to a topic. host is the broker URL — mqtt://<host>:<port>
+    await actions([{ base: "mqtt", type: "send", host: "mqtt://192.168.1.50:1883", topic: "home/light", value: "ON" }]);
 
-    // WebSocket: send to one connection by its id
+    // WebSocket: send to one configured connection by its id
     await actions([{ base: "websocket", type: "data", device: "<websocketId>", value: "hello" }]);
 
-    // Serial: write raw data to a port (9600 baud)
+    // Serial: write raw data to a port (COM3 on Windows, /dev/tty.* on macOS)
     await actions([{ base: "serial", type: "write", port: "COM3", value: "L1\n" }]);
 
-    // Art-Net: set DMX channels on a universe (values 0-255; no template tokens here)
-    await actions([{ base: "artnet", type: "artnet", universe: 0, values: [{ channel: 1, value: 255 }, { channel: 2, value: 128 }] }]);
+    // Art-Net: set DMX channels on a universe (channel 1-512, value 0-255). universe is a string
+    await actions([{ base: "artnet", type: "artnet", universe: "0", values: [{ channel: 1, value: 255 }, { channel: 2, value: 128 }] }]);
 
-    // Broadlink: send a learned IR/RF code by its library id or name to a device
-    await actions([{ base: "broadlink", type: "ir", device: "<deviceId>", value: "TV Power" }]);
+    // Broadlink: send a learned IR/RF code by its library id to a device
+    await actions([{ base: "broadlink", type: "ir", device: "<deviceId>", value: "<codeId>" }]);
     done();
 }
 ```
@@ -682,11 +722,35 @@ All take a `value` object.
 | base | type | `value` | notes |
 | --- | --- | --- | --- |
 | `switchbot` | `turnOn` / `turnOff` / `toggle` | `{ deviceId: "<id>" }` | |
+| `wavelink` | `FILTER_SET` | `{ filterId: "<uuid>", isEnabled: true, inputId: "Wave Link Mic In 1" }` | enable/disable an input's filter; `filterId: "ALL_EFFECTS"` targets every effect on that input |
 | `wavelink` | `SET_INPUT_VOLUME` | `{ inputId: "<id>", volume: 50, mixerID: "com.elgato.mix.local" }` | volume 0–100; mixer `local`/`stream`/`all` |
 | `wavelink` | `MUTE_INPUT` | `{ inputId: "<id>", muted: true, mixerID: "com.elgato.mix.local" }` | |
 | `wavelink` | `SET_OUTPUT_VOLUME` / `MUTE_OUTPUT` | `{ volume: 50, mixerID: "com.elgato.mix.local" }` | |
 | `wavelink3` | same types as `wavelink` | same shapes | Wave Link 3.0 uses base `wavelink3`; some legacy filter/mic types are unsupported on v3 |
-| `camerahub` | `SET_WEBCAM_PROPERTY` | `{ propertyID: "Brightness", propertyValue: 60 }` | also `SELECT_DEVICE`, `SET_NVIDIA_VIDEO_EFFECT`, `SET_LUT_EFFECT`, `SET_PROMPTER_PROPERTY` |
+| `camerahub` | `SET_WEBCAM_PROPERTY` | `{ propertyID: "Brightness", propertyValue: 60 }` | all camerahub types share one property-bag `value` (`deviceID, propertyID, propertyValue, intensity, isEnabled, …`) — set only the fields the type uses. Also `SELECT_DEVICE`, `SET_NVIDIA_VIDEO_EFFECT`, `SET_LUT_EFFECT` (`intensity`), `SET_PROMPTER_PROPERTY` |
 | `streamfog` | `activateLens` | `{ lensId: "<id or name>", duration: 10 }` | `lensId: "random"` picks one; also `activateOutfit` (`{ outfit, duration }`) and `disableLens` (`{}`) |
 
+#### Plugin actions (`base: "<pluginId>"`)
+
+Every installed plugin is also a valid base — use the plugin's id as the `base`, plus the plugin's own action `type` and a `value` object of that plugin's fields. The exact `type` and `value` come from the plugin's manifest, so the reliable way to discover them is to add the action once in the editor and read it back; the shape is always `{ base: "<pluginId>", type: "<action type>", value: { ...plugin fields } }`. Verified examples:
+
+```js
+async function() {
+    // Tapo smart plug — target is the device IP, or "IP|deviceId"
+    await actions([{ base: "tapo_plugin", type: "tapo_turn_on", value: { target: "192.168.50.169" } }]);
+
+    // Steam — look up a game
+    await actions([{ base: "steam", type: "fetch_game", value: { game: "Sonic" } }]);
+
+    // ClickUp — create a task (assigneeId is comma-separated)
+    await actions([{ base: "clickup", type: "create_task", value: { name: "{{message}}", assigneeId: "14928785,14928776" } }]);
+
+    // ElevenLabs TTS
+    await actions([{ base: "elevenlabs_tts", type: "speak", value: { message: "{{message}}", voiceId: "hpp4J3VqNfWAUOO0d1Us", modelId: "eleven_multilingual_v2", volume: 100 } }]);
+    done();
+}
+```
+
+A plugin action is silently skipped unless its plugin is installed, connected, and enabled.
+
 This documentation can get extremely broad for every integration, so if you get stuck please visit our [**Discord**](https://discord.gg/R8rCaKb) to ask us any questions.

package/dist/custom-overlays/custom-overlays-cheatsheet.md

@@ -110,12 +110,27 @@ Include these two helper aliases in your embeddings so the model can quickly map
 				"min": { "type": "number" },
 				"max": { "type": "number" },
 				"visibleIf": {
-					"type": "object",
-					"required": ["key", "equals"],
-					"properties": {
-						"key": { "type": "string" },
-						"equals": {}
-					}
+					"oneOf": [
+						{
+							"type": "object",
+							"required": ["key", "equals"],
+							"properties": {
+								"key": { "type": "string" },
+								"equals": {}
+							}
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "object",
+								"required": ["key", "equals"],
+								"properties": {
+									"key": { "type": "string" },
+									"equals": {}
+								}
+							}
+						}
+					]
 				},
 				"hidden": { "type": "boolean" }
 			},

package/dist/custom-overlays/custom-overlays-documentation.md

@@ -399,7 +399,7 @@ A field object can now contain these properties:
 | **`value`**     | ❌       | Default value that appears the first time the user opens the overlay (also pre populates `Overlay.data`). Omit it to leave the field blank/unchecked on first load.                                                                                                                                | `"value": 18`                                                     |
 | **`options`**   | ☑️\*     | Key value map of selectable choices. Required **only** for `dropdown`, `multiselect` and `slider`; ignored for other types. For `slider`, `options` supports `step`, `min`, `max`, `prefix`, `suffix`.                                                                                             | `"options": { "step": 5, "min": 0, "max": 100 }`                  |
 | **`order`**     | ❌       | **Display order priority**. Fields with lower numbers appear first. Fields without `order` appear after ordered fields, sorted alphabetically by key.                                                                                                                                              | `"order": 1`                                                      |
-| **`visibleIf`** | ❌       | **Conditional render rule**. Field is shown **only if** `Overlay.data[visibleIf.key]` strictly equals one of the values in `visibleIf.equals`.                                                                                                                                                     | `"visibleIf": { "key": "targetKey", "equals": ["yes", "maybe"] }` |
+| **`visibleIf`** | ❌       | **Conditional render rule**. Field is shown **only if** `Overlay.data[visibleIf.key]` strictly equals one of the values in `visibleIf.equals`. Pass an **array of rules** to require that **every** rule matches (AND across keys).                                                                 | `"visibleIf": [{ "key": "targetKey", "equals": ["yes", "maybe"] }, { "key": "mode", "equals": "advanced" }]` |
 | **`hidden`**    | ❌       | **Hard-hide rule.** When set to `true`, the field is **never displayed** in the Configs sidebar, preventing end users from altering it. The value still flows into `Overlay.data`, so the overlay can rely on it internally.<br>Useful for locking event subscriptions or other advanced settings. | `"hidden": true`                                                  |
 
 Additional properties for text fields (`type: "input"` and `type: "textarea"`):
@@ -761,10 +761,13 @@ In this example, the fields would appear in this order:
 ### Visible If Conditional Fields
 
 The `visibleIf` field is a conditional statement that determines whether a field should be visible or not based on a condition.
-The `visibleIf` field is a JSON object with two keys: `key` and `equals`.
+The `visibleIf` field can be **either**:
+
+- a single rule object with two keys, `key` and `equals`, or
+- an **array of rule objects**, in which case the field is shown only when **every** rule matches (logical AND). Use the array form to gate a field on more than one key at once.
 
 The `key` key is a string that represents the name of the field whose value should be used in the conditional statement.
-The `equals` key is a string, number, boolean, or an array that represents the value of the field whose value should be used in the conditional statement.
+The `equals` key is a string, number, boolean, or an array that represents the value(s) of that field that make the condition match. When `equals` is an array, the rule matches if the field's value is one of the listed values (and for `multiselect` fields, if any selected value is in the list).
 
 #### Single Primitive Equals Example
 
@@ -804,6 +807,35 @@ The `equals` key is a string, number, boolean, or an array that represents the v
 }
 ```
 
+#### Multiple Keys (Array of Rules) Example
+
+Pass an array of rule objects to require that **every** rule matches before the
+field shows. Here `subcolor` only appears when **both** `color` and `alerts`
+are set to one of `red`, `blue`, or `green`:
+
+```json
+{
+	"color": {
+		"type": "input",
+		"label": "Colors"
+	},
+	"subcolor": {
+		"type": "input",
+		"label": "Subcolors",
+		"visibleIf": [
+			{
+				"key": "color",
+				"equals": ["red", "blue", "green"]
+			},
+			{
+				"key": "alerts",
+				"equals": ["red", "blue", "green"]
+			}
+		]
+	}
+}
+```
+
 ---
 
 ## 📊 Data Tab

package/dist/custom-overlays/custom-overlays.d.ts

@@ -53,7 +53,7 @@ export enum ConfigsFieldType {
 }
 
 /**
- * Conditional render rule for a config field.
+ * A single conditional render rule for a config field.
  * The field is shown only when `Overlay.data[key]` strictly equals one of `equals`
  * (scalar) or intersects with `equals` (when either side is an array).
  *
@@ -68,6 +68,23 @@ export interface ConfigVisibleIf {
 	equals: string | number | boolean | Array<string | number | boolean>;
 }
 
+/**
+ * Conditional render rule, or a list of rules. When an array is supplied, the
+ * field is shown only when **every** rule matches (logical AND), letting you
+ * gate a field on several keys at once.
+ *
+ * @example
+ * // single key
+ * { key: 'mode', equals: 'advanced' }
+ * @example
+ * // multiple keys — all must match
+ * [
+ *   { key: 'color', equals: ['red', 'blue', 'green'] },
+ *   { key: 'alerts', equals: ['red', 'blue', 'green'] },
+ * ]
+ */
+export type ConfigVisibleIfRule = ConfigVisibleIf | ConfigVisibleIf[];
+
 /** Properties common to every config field, regardless of `type`. */
 export interface BaseConfigField {
 	/** Human-readable name shown next to the control in the Configs sidebar. */
@@ -79,9 +96,10 @@ export interface BaseConfigField {
 	order?: number;
 	/**
 	 * Conditional render rule. When set, the field renders only when
-	 * `Overlay.data[visibleIf.key]` matches `visibleIf.equals`.
+	 * `Overlay.data[visibleIf.key]` matches `visibleIf.equals`. Pass an array of
+	 * rules to require that **every** rule matches (logical AND across keys).
 	 */
-	visibleIf?: ConfigVisibleIf;
+	visibleIf?: ConfigVisibleIfRule;
 	/**
 	 * Hard-hide rule. When `true`, the field is never displayed in the Configs
 	 * sidebar, but its `value` still flows into `Overlay.data` for internal use.

package/dist/custom-overlays/gpt-instructions.md

@@ -35,7 +35,7 @@ Source of truth (in order): this file > `gpt-instructions-extended.md` (long-for
 - **HTML**: body content only. Stable IDs/classes. No inline `<script>` or `<style>`.
 - **CSS**: stylesheet only. Unquoted CSS variables for colors/sizes/numbers. Quoted only where CSS requires a string (`font-family: "{{font}}";`).
 - **JS**: top-level JS. Use `Overlay.data` for Data values. Use `textContent`/`createElement`/`appendChild` for any chat, alert, or user-generated text — never `innerHTML` with user input. `fetch` is allowed.
-- **Configs**: field types: `input`, `textarea`, `number`, `checkbox`, `dropdown`, `multiselect`, `colorpicker`, `fontpicker`, `slider`, `imageupload`, `soundupload`, `videoupload`, `actionbutton`. Required: `type`, `label`. Use `value` for defaults. `dropdown`/`multiselect` need `options`. `slider` needs `options.min`/`max` (usually `step`/`prefix`/`suffix`). `imageupload`/`soundupload`/`videoupload` accept an `accept` MIME hint. `actionbutton` has no `value` — bind it via `Overlay.on('configAction', ({ key }) => …)`. Use `order` to control sidebar order. Use `visibleIf` for conditional fields. Keys must be machine-friendly (no spaces).
+- **Configs**: field types: `input`, `textarea`, `number`, `checkbox`, `dropdown`, `multiselect`, `colorpicker`, `fontpicker`, `slider`, `imageupload`, `soundupload`, `videoupload`, `actionbutton`. Required: `type`, `label`. Use `value` for defaults. `dropdown`/`multiselect` need `options`. `slider` needs `options.min`/`max` (usually `step`/`prefix`/`suffix`). `imageupload`/`soundupload`/`videoupload` accept an `accept` MIME hint. `actionbutton` has no `value` — bind it via `Overlay.on('configAction', ({ key }) => …)`. Use `order` to control sidebar order. Use `visibleIf` for conditional fields — either a single `{ key, equals }` rule or an array of rules (the field shows only when every rule matches). Keys must be machine-friendly (no spaces).
 - **Data**: every Configs key must have a matching Data key with a matching default. Data can hold internal values that aren't in Configs (rare).
 
 ## Variables

package/dist/custom-overlays.d.ts

@@ -53,7 +53,7 @@ export enum ConfigsFieldType {
 }
 
 /**
- * Conditional render rule for a config field.
+ * A single conditional render rule for a config field.
  * The field is shown only when `Overlay.data[key]` strictly equals one of `equals`
  * (scalar) or intersects with `equals` (when either side is an array).
  *
@@ -68,6 +68,23 @@ export interface ConfigVisibleIf {
 	equals: string | number | boolean | Array<string | number | boolean>;
 }
 
+/**
+ * Conditional render rule, or a list of rules. When an array is supplied, the
+ * field is shown only when **every** rule matches (logical AND), letting you
+ * gate a field on several keys at once.
+ *
+ * @example
+ * // single key
+ * { key: 'mode', equals: 'advanced' }
+ * @example
+ * // multiple keys — all must match
+ * [
+ *   { key: 'color', equals: ['red', 'blue', 'green'] },
+ *   { key: 'alerts', equals: ['red', 'blue', 'green'] },
+ * ]
+ */
+export type ConfigVisibleIfRule = ConfigVisibleIf | ConfigVisibleIf[];
+
 /** Properties common to every config field, regardless of `type`. */
 export interface BaseConfigField {
 	/** Human-readable name shown next to the control in the Configs sidebar. */
@@ -79,9 +96,10 @@ export interface BaseConfigField {
 	order?: number;
 	/**
 	 * Conditional render rule. When set, the field renders only when
-	 * `Overlay.data[visibleIf.key]` matches `visibleIf.equals`.
+	 * `Overlay.data[visibleIf.key]` matches `visibleIf.equals`. Pass an array of
+	 * rules to require that **every** rule matches (logical AND across keys).
 	 */
-	visibleIf?: ConfigVisibleIf;
+	visibleIf?: ConfigVisibleIfRule;
 	/**
 	 * Hard-hide rule. When `true`, the field is never displayed in the Configs
 	 * sidebar, but its `value` still flows into `Overlay.data` for internal use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumiastream/lumia-types",
-  "version": "3.9.3",
+  "version": "3.9.4",
   "description": "",
   "main": "./dist/index.js",
   "module": "./dist/esm/index.js",