@lumiastream/lumia-types 3.9.0 → 3.9.1

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

@@ -69,4 +69,67 @@ These are the built-in `type` values for each system 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.
 
+### Common `lumia` action examples
+
+Most `lumia` actions have a dedicated helper already (`chatbot`, `tts`, `playAudio`, `setVariable`, etc.) — prefer those. Reach for `actions()` for the engagement / system features that have no helper. The `value` fields are not uniform across types, so if you need a type not shown here, set that action up once in the normal action editor to read off its fields. Verified examples:
+
+```js
+async function() {
+    // Song requests
+    await actions([{ base: "lumia", type: "addSongRequest", value: { value: "never gonna give you up" } }]); // a search term or url
+    await actions([{ base: "lumia", type: "skipSongRequest" }]);
+
+    // Raffle (ends_after is in seconds; raffleStop / raffleEnd take no value)
+    await actions([{ base: "lumia", type: "raffleStart", value: { title: "My Raffle", auto_end: true, ends_after: 120 } }]);
+
+    // Viewer queue
+    await actions([{ base: "lumia", type: "viewerQueueEntry", value: { value: "{{username}}" } }]);
+
+    // Stream mode and connections
+    await actions([{ base: "lumia", type: "setStreamMode", value: { on: true } }]);
+    await actions([{ base: "lumia", type: "setConnection", value: { value: "obs", on: true } }]); // on:true enables, false disables
+
+    // Counter (operator is one of + - * /)
+    await actions([{ base: "lumia", type: "updateCounter", value: { value: "deaths", message: "1", operator: "+" } }]);
+    done();
+}
+```
+
+### OBS (v5) actions
+
+OBS has a dedicated helper, so you do **not** need `actions()` for it: pass any OBS websocket v5 request to `sendRawObsJson({ "request-type": "...", ...params })` (see `helper-functions.md`). The `request-type` and fields are exactly the same ones Lumia's OBS action editor uses. Common ones:
+
+```js
+async function() {
+    // Scenes
+    sendRawObsJson({ "request-type": "SetCurrentProgramScene", "sceneName": "My Scene" });
+    sendRawObsJson({ "request-type": "SetCurrentPreviewScene", "sceneName": "My Scene" });
+
+    // Source visibility (by name — Lumia resolves the scene item id for you)
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": "My Scene", "inputName": "My Source", "sceneItemEnabled": true });
+    sendRawObsJson({ "request-type": "SetSourceFilterEnabled", "sourceName": "My Source", "filterName": "My Filter", "filterEnabled": true });
+
+    // Audio
+    sendRawObsJson({ "request-type": "SetInputMute", "inputName": "Mic/Aux", "inputMuted": true });
+    sendRawObsJson({ "request-type": "ToggleInputMute", "inputName": "Mic/Aux" });
+    sendRawObsJson({ "request-type": "SetInputVolume", "inputName": "Mic/Aux", "inputVolumeMul": 1 });
+
+    // Source settings (url / text / file / image / media)
+    sendRawObsJson({ "request-type": "SetInputSettings", "inputName": "Browser", "inputSettings": { "url": "https://lumiastream.com" } });
+
+    // Media, transitions, screenshot
+    sendRawObsJson({ "request-type": "TriggerMediaInputAction", "inputName": "My Video", "mediaAction": "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_RESTART" });
+    sendRawObsJson({ "request-type": "SetCurrentSceneTransition", "transitionName": "Fade" });
+
+    // Recording / streaming / replay buffer / virtual cam (no params)
+    sendRawObsJson({ "request-type": "StartRecord" });
+    sendRawObsJson({ "request-type": "ToggleStream" });
+    sendRawObsJson({ "request-type": "SaveReplayBuffer" });
+    sendRawObsJson({ "request-type": "StartVirtualCam" });
+    done();
+}
+```
+
+Other available request-types include `SetCurrentProfile`, `SetCurrentSceneCollection`, `CreateInput`, `RemoveInput`, `SetSceneItemTransform`, `SetSceneItemBlendMode`, `SetInputAudioMonitorType`, `TriggerHotkeyByName`, `SetStudioModeEnabled`, `SendStreamCaption`, and the `Start/Stop/Toggle` variants for recording, streaming, replay buffer and virtual cam — the same list as the OBS action editor.
+
 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-code/examples/roll-dice.md

@@ -27,3 +27,31 @@ async function() {
 **code blocks** like the one above 👆 have a copy button on the **top right corner** click it then paste in Lumia stream
 
 :::
+
+## Show an OBS source and play a sound
+
+You can drive OBS and audio straight from the code with the built-in helpers — there is no need to make a separate command and call it by an id. This rolls a dice, shows the matching `Dice1`–`Dice6` source in your scene, plays a sound on a 6, then hides the source again.
+
+```js
+async function() {
+    const roll = Math.ceil(Math.random() * 6);
+    const sceneName = "IN-GAME ACTION";
+    const sourceName = "Dice" + roll;
+
+    chatbot({ message: "{{username}} rolled a " + roll + "!" });
+
+    // Show the matching dice source. Lumia finds the source's id from its name for you
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": sceneName, "inputName": sourceName, "sceneItemEnabled": true });
+
+    // Play a celebration sound only on a 6
+    if (roll === 6) {
+        playAudio({ path: "C:\\sounds\\gold.mp3", volume: 100 });
+    }
+
+    // Leave it on screen for 6 seconds, then hide it again
+    await delay(6000);
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": sceneName, "inputName": sourceName, "sceneItemEnabled": false });
+
+    done();
+}
+```

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

@@ -41,6 +41,16 @@ You generate **Lumia Stream Custom Code**: JavaScript snippets that a streamer p
 8. For `callAlert`, the `name` must be a valid alert key from the list in `helper-functions.md` (e.g. `twitch-subscriber`, `kick-follower`, `kofi-donation`). Do not guess keys that aren't on that list.
 9. If a capability is not documented, say so clearly and offer a documented alternative rather than fabricating an API.
 
+## Use built-in helpers directly — never command IDs
+
+Run actions straight from the code with the documented helpers. Do **not** tell the streamer to first build a separate Lumia Command/Alert and then call it by an ID, and never output placeholder IDs like `REPLACE_WITH_..._COMMAND_ID`. There is **no** `executeCommand` global. `callCommand`, `callChatbotCommand` and `callAlert` take a **name** and only trigger something the streamer has *already* created — they are not a way to change scenes or play sounds.
+
+- **OBS scene change:** `sendRawObsJson({ "request-type": "SetCurrentProgramScene", "sceneName": "My Scene" })`
+- **OBS show/hide a source (by name):** `sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": "My Scene", "inputName": "My Source", "sceneItemEnabled": true })` — set `sceneItemEnabled: false` to hide. Lumia looks up the source's id from the name for you, so you never need a numeric `sceneItemId`.
+- **Any other OBS request:** the same pattern through `sendRawObsJson` (for example `SetInputMute`, `TriggerMediaInputAction`, `SetCurrentSceneTransition`).
+- **Play audio:** `playAudio({ path: "C:\\sounds\\gold.mp3", volume: 100 })` — a URL works too and `playSound` is an alias. Use `await playAudio({ ..., waitForAudioToStop: true })` to wait for it to finish.
+- For an integration action that has no dedicated helper, use `actions([...])` (see `custom-actions.md`).
+
 ## Quality checklist before returning code
 
 - Wrapped in `async function() { ... }` and calls `done()` once.

package/dist/custom-code/helper-functions.md

@@ -456,16 +456,21 @@ async function() {
 
 ### Send Raw OBS JSON
 
-`sendRawObsJson(value: { request-type: string; sceneName?: string; sceneItemId?: number; [key: string]: any })`: You can send raw JSON to OBS that will automatically handle the context id. Just send end the request type and your other parameters and Lumia Stream will take care of the rest
+`sendRawObsJson(value: { request-type: string; sceneName?: string; inputName?: string; sceneItemId?: number; [key: string]: any })`: You can send raw JSON to OBS that will automatically handle the context id. Just send the request type and your other parameters and Lumia Stream will take care of the rest. This is the simplest way to drive OBS from custom code — you do not need to build a separate OBS command or alert and call it by id.
 
 ```js
 async function() {
-    sendRawObsJson({
-        "request-type": "SetSceneItemEnabled",
-        "sceneItemEnabled": true,
-        "sceneItemId": 1,
-        "sceneName": "Scene 1"
-    });
+    // Change the active scene
+    sendRawObsJson({ "request-type": "SetCurrentProgramScene", "sceneName": "My Scene" });
+
+    // Show a source by its name. Lumia resolves the scene item id from the name for you, so no numeric id is needed
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": "My Scene", "inputName": "My Source", "sceneItemEnabled": true });
+
+    // Hide that same source again by passing false
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": "My Scene", "inputName": "My Source", "sceneItemEnabled": false });
+
+    // You can still target a source by its numeric sceneItemId if you already know it
+    sendRawObsJson({ "request-type": "SetSceneItemEnabled", "sceneName": "Scene 1", "sceneItemId": 1, "sceneItemEnabled": true });
 }
 ```
 

package/package.json

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