From a5908fb69756db42fd89868e3271281afa51fd1c Mon Sep 17 00:00:00 2001 From: Justin James Date: Sun, 19 Jan 2025 09:38:25 -0700 Subject: [PATCH 1/2] add: clear selected outputs and fix outputRouting feedback --- src/actions/action-zoomiso-actions.ts | 10 ++++++++++ src/osc.ts | 12 +----------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/actions/action-zoomiso-actions.ts b/src/actions/action-zoomiso-actions.ts index d094c0c..014b205 100644 --- a/src/actions/action-zoomiso-actions.ts +++ b/src/actions/action-zoomiso-actions.ts @@ -6,6 +6,7 @@ import { sendActionCommand, PreviousSelectedCallersSave } from './action-utils.j export enum ActionIdZoomISOActions { selectOutput = 'select_Output', + clearSelectOutput = 'clear_Select_Output', selectAudioChannel = 'select_Audio_Channel', applyOutput = 'apply_Output', applyChannel = 'apply_Channel', @@ -67,6 +68,15 @@ export function GetActionsZoomISOActions(instance: InstanceBaseExt): instance.checkFeedbacks(FeedbackId.output) }, }, + [ActionIdZoomISOActions.clearSelectOutput]: { + name: 'Clear Select Output', + options: [], + callback: () => { + instance.ZoomClientDataObj.selectedOutputs = [] + // instance.log('debug', `outputNumber: ${outputNumber} selectedOutputs: ${JSON.stringify(instance.ZoomClientDataObj.selectedOutputs)}`) + instance.checkFeedbacks(FeedbackId.output) + }, + }, [ActionIdZoomISOActions.selectAudioChannel]: { name: 'Select audio channel', options: [outputAudioOption], diff --git a/src/osc.ts b/src/osc.ts index 15ffa7d..2dd3270 100644 --- a/src/osc.ts +++ b/src/osc.ts @@ -987,17 +987,7 @@ export class OSC { const variables: CompanionVariableValues = {} updateZoomIsoOutputVariables(this.instance, variables) this.instance.setVariableValues(variables) - this.instance.checkFeedbacks( - FeedbackId.userNameBased, - FeedbackId.userNameBasedAdvanced, - FeedbackId.indexBased, - FeedbackId.indexBasedAdvanced, - FeedbackId.galleryBased, - FeedbackId.galleryBasedAdvanced, - FeedbackId.groupBased, - FeedbackId.groupBasedAdvanced, - FeedbackId.output, - ) + this.instance.checkFeedbacks(FeedbackId.output) break } default: From b12d4ba62d091323dbd55c04458168ad8a8658a1 Mon Sep 17 00:00:00 2001 From: Justin James Date: Sun, 19 Jan 2025 10:52:08 -0700 Subject: [PATCH 2/2] update: help and config description --- README.md | 37 -------- companion/HELP.md | 212 +++++++++++++++++++++++++++------------------- package.json | 2 +- src/config.ts | 39 ++++----- 4 files changed, 146 insertions(+), 144 deletions(-) diff --git a/README.md b/README.md index 813f740..cac3f04 100644 --- a/README.md +++ b/README.md @@ -80,14 +80,6 @@ The module respects the order of selections, so when acting on multiple particip There are several variables and actions to help you manage the selection process available in the module. For example, since actions do not automatically deselect the participants acted upon, you can add a “Clear Selections” action to deselect them. -### Groups - -One of the most powerful features of this module is the ability to place participants into groups. Just like participants, groups are referenceable and selectable. You can index into groups with variables to display their members. In fact buttons with these properties are automatically available in the Presets area under “Manage Selections and Groups” by automatically generating new buttons based on the number of groups specified in the module setup. - -Groups can have a variety of purposes. For example, you might make a group called “Favorites” that contains the subset of users in your meeting that you will actually need to interact with. Then, you could have a page that shows who is in the Favorites group so you can select them and act upon them individually or together. Alternatively, you could have several groups representing the members of different panel conversations. Once the users are placed in the different panelist groups, you can select all members of a panel at once simply by selecting the corresponding group itself, and applying an action like Add Spotlight to the entire group. - -There is a default group called “Hosts” created and managed by the module itself. Its members are the host and co-host(s) of the meeting. This membership is automatically managed, so you cannot add or remove members (unless you change who the host and co-host(s) are) or change the group properties. - ## Variables and Feedback This module supports many variables and feedback properties. These are helpful for automatically changing key properties like the name and color of a button. Variables can also be used for basic automation systems in the Triggers workflow within Companion. Most preset buttons already contain the necessary feedback and variable mapping for dynamic buttons, but advanced users may wish to read deeper into the module to build customized buttons and workflows. @@ -99,32 +91,3 @@ When joining flow is 1 = Connecting, 8 = Audio Ready, 3 = Connected. When leaving flow is 4 = Disconnected, 7 = Ended. > Note: If module is restarted while in a meeting 0 = Not In meeting and 1 = In Meeting - -### Social Stream Ninja Integration - -One of the configuration options, is to send chat messages to Social Stream Ninja. In order for this to work, you need to provide your social stream ninja session id in the module configuration. - -Once the integration is turned on, you will need to update the urls you are using for your Social Stream Ninja browser source within OBS or other streaming software. - -The &server parameter in the url is the key to making it work as it tells it to listen to incoming API messages. - -Here is how to use it in OBS. - -1. Create a Custom Browser Dock and replace XXXXXXXX with your social stream id - - - `https://socialstream.ninja/dock.html?session=XXXXXXXXX&server&server2&sync&label=main&limit=300` - -2. Create a browser source on a scene and use the following url and replace XXXXXXXX with your social stream id - - - `https://socialstream.ninja/index.html?session=XXXXXXXXX&aligntop&server&server2` - - Width: 1200 - - Height: 300 - - Shutdown source when not visible - -## Support and Thanks - -The ZoomOSC/ISO Companion Module is not an official Zoom product. It is a community-driven project that utilizes the Open Sound Control public APIs of ZoomOSC and ZoomISO. While Zoom (and formerly Liminal) have designed its behavior, they hold no liability for this module or its upkeep. Ultimately it is managed by and the responsibility of the open-source Companion community, BitFocus, and its users. - -For support on this module, please utilize the GitHub and Slack for BitFocus Companion. If you have questions on ZoomOSC or ZoomISO, you can email [info@liminalet.com](mailto:info@liminalet.com) for Zoom’s official support of those products. - -This module is the result of several years of effort from multiple individuals and teams. The initial version of the v3 version of the module was created by Jeffrey Davidsz and designed by Andy Carluccio and Jonathan Kokotajlo from Zoom, the former co-founders of Liminal. The team is grateful for the work of several contributors to previous iterations of the module including Ash Green, Richard Williamson, Benjamin Antupit, and Johnny Estilles. The team would also like to thank the power users and beta testers whose contributions to the module have helped shape it over the years, with special recognition to Jeff Widgren, David Paskin, and Justin James. diff --git a/companion/HELP.md b/companion/HELP.md index ef5f209..6847d8b 100644 --- a/companion/HELP.md +++ b/companion/HELP.md @@ -13,138 +13,178 @@ This module gives you deep control of Zoom through controllers like the StreamDe ## ZoomOSC/ISO Configuration +You will need to configure these settings in ZoomOSC/ZoomISO UI + 1. **Transmission IP:** IP of Companion computer (or `127.0.0.1` if on the same computer). -2. **Transmission Port:** Available port for Companion. -3. **Receiving Port:** Port for ZoomOSC/ISO to receive commands. -4. **OSC Output Rate:** Set to "Fastest Possible." -5. **Gallery Tracking Mode:** Set to "Zoom ID." +1. **Transmission Port:** Available port for Companion. +1. **Receiving Port:** Port for ZoomOSC/ISO to receive commands. +1. **OSC Output Rate:** Set to "Fastest Possible." +1. **Gallery Tracking Mode:** Set to "Zoom ID." ## Companion Module Configuration -1. **Target Host:** IP of ZoomOSC/ISO computer. -2. **Sending/Receiving Ports:** Match ZoomOSC/ISO settings. -3. **Default Selection:** Choose single or multi-participant selection. +There are a number of configuration options for the module that allow you to configure how to communicate with ZoomISO/ZoomOSC, how many internal groups to track, Participant Multi-State feedback, Social Stream Ninja integration, and advanced performance tweaks. ---- +1. **ZoomISO/ZoomOSC Transmission IP (e.g. Target Host):** Match ZoomISO/ZoomOSC Transmission IP. +1. **ZoomISO/ZoomOSC Receiving Port:** Match ZoomISO/ZoomOSC Recieving Port. +1. **ZoomISO/ZoomOSC Transmission Port:** Match ZoomISO/ZoomOSC Transmission Port +1. **Default Selection:** Select one participant at a time or Select multiple participants simultaneously. +1. **Number of selectable groups:** -## Basic Workflow + One of the most powerful features of this module is the ability to place participants into groups. Just like participants, groups are referenceable and selectable. You can index into groups with variables to display their members. Buttons with these properties are automatically available in the Presets area under _Manage Selections and Groups_, where new buttons are generated based on the number of groups specified during setup. -Select user(s), then apply action(s). + - **Default Groups** -## ZoomISO Control + There are two default groups. These groups are automatically managed by the module, so you cannot add or remove members manually or change the group properties: -- Route participants to video/audio outputs. -- Configure outputs and engine settings directly from the module. + 1. _Hosts:_ Includes the host and all co-host(s) of the meeting. + 1. _Spotlights:_ Includes all attendees currently spotlighted. -## Selections + - **Group Management** -- **Dynamic Participant Display:** Names automatically appear for quick selection. -- **Selection Types:** - - **From Participants:** Static list of participants. - - **From Gallery:** Dynamic list matching Zoom’s Gallery View. -- **Single vs. Multi-Selection Mode:** - - **Single:** Select one participant at a time. - - **Multi:** Select multiple participants simultaneously. + - _Add Participants to Groups:_ The primary way to manage groups is by selecting one or more participants and adding or removing them from a group. + - _Save and Load Groups:_ + - Load participants into a group by their Zoom Name from a file. + - Save the current group configuration to a file (note: When loading a group from a file, only participants currently in the meeting will be added to the group) -## Groups + - **Group Use Cases** -One of the most powerful features of this module is the ability to place participants into groups. Just like participants, groups are referenceable and selectable. You can index into groups with variables to display their members. Buttons with these properties are automatically available in the Presets area under **Manage Selections and Groups**, where new buttons are generated based on the number of groups specified during setup. + - _Speakers:_ Create a subset of users that will be coming up to stage and are not co-host + - _Panelists:_ Organize participants into different panel conversations. -### Default Groups + Once users are assigned to groups, you can easily select a group (e.g., "Panelists") and apply actions like _Add Spotlight_ to the entire group. -There are two default groups. These groups are automatically managed by the module, so you cannot add or remove members manually or change the group properties: +1. **Sync iso configuration time in sections (only for ZoomISO):** How often to update the ZoomISO audioLevels, outputRouting, audioRouting, and engineState. The default is 1 second. -1. **Hosts:** Includes the host and all co-host(s) of the meeting. -2. **Spotlights:** Includes all attendees currently spotlighted. +1. _Participant Multi-State Feedback_ -### Group Management + This module supports various _dynamic feedback options_ to enhance your workflow and button functionality. One key feature is _multi-state feedback_ for participants, providing real-time status updates for their camera, mic, and hand raise. Each status has an icon with both "on" and "off" states for easy visualization. -- **Add Participants to Groups:** The primary way to manage groups is by selecting one or more participants and adding or removing them from a group. -- **Save and Load Groups:** - - Load participants into a group by their Zoom Name from a file. - - Save the current group configuration to a file (note: When loading a group from a file, only participants currently in the meeting will be added to the group) + 1. **Disable (Not recommended unless you don’t need feedback indicators.)** -### Group Use Cases + - Turns off multi-state feedback. + - Reverts to single feedback where you must manually add individual feedback for the camera, mic, and hand raise. -Groups can have a variety of purposes, such as: + 1. **Bottom (On and Off for Mic/Camera, Only On for Hand Raise)** -- **Speakers:** Create a subset of users that will be coming up to stage and are not co-host -- **Panelists:** Organize participants into different panel conversations. + - Always shows mic and camera status (on/off). + - Hand raise icon appears only when the hand is raised. -Once users are assigned to groups, you can easily select a group (e.g., "Panelists") and apply actions like **Add Spotlight** to the entire group. + 1. **Bottom (Only Active States)** ---- + - Displays icons only when: + - Mic is unmuted. + - Camera is on. + - Hand is raised. -## Variables and Feedback + 1. **Bottom (On and Off Active States)** + - Always displays icons: + - Bright for active states (e.g., camera on). + - Dim for inactive states (e.g., mic muted). -This module supports various **dynamic feedback options** to enhance your workflow and button functionality. One key feature is **multi-state feedback** for participants, providing real-time status updates for their camera, mic, and hand raise. Each status has an icon with both "on" and "off" states for easy visualization. + These configurations provide flexibility to tailor feedback based on your needs. The default presets use multi-state feedback to ensure a seamless experience, but advanced users can adjust settings as required. -### Multi-State Feedback Configuration Options +1. **Send Zoom Chat to Social Stream Ninja** -1. **Disable** (_Not recommended unless you don’t need feedback indicators._) + One of the configuration options, is to send chat messages to Social Stream Ninja. In order for this to work, you need to provide your social stream ninja session id in the module configuration. - - Turns off multi-state feedback. - - Reverts to single feedback where you must manually add individual feedback for the camera, mic, and hand raise. + Once the integration is turned on, you will need to update the urls you are using for your Social Stream Ninja browser source within OBS or other streaming software. -2. **Bottom (On and Off for Mic/Camera, Only On for Hand Raise)** + - **Install Social Stream Ninja Configuration** - - Always shows mic and camera status (on/off). - - Hand raise icon appears only when the hand is raised. + You can install Social Stream Ninja at [https://socialstream.ninja/landing#manually-install-extension](https://socialstream.ninja/landing#manually-install-extension). We suggest manually installing the extension as that is the most update to date version. -3. **Bottom (Only Active States)** + - **Social Stream Ninja Configuration** - - Displays icons only when: - - Mic is unmuted. - - Camera is on. - - Hand is raised. + You need to configuration Social Stream Ninja so that it will allow you to make API calls to it and to get your Session Id -4. **Bottom (On and Off Active States)** - - Always displays icons: - - Bright for active states (e.g., camera on). - - Dim for inactive states (e.g., mic muted). + 1. Enable API Control + - Open Social Stream Ninja + - Go to Global settings and tools > Mechanics + - Enable Enable remote API control of extension + 1. Get Your Session ID: + - Navigate to Global settings and tools > Session Options + - Copy your Session ID + - Alternatively, find it in your URL after ?session= -These configurations provide flexibility to tailor feedback based on your needs. The default presets use multi-state feedback to ensure a seamless experience, but advanced users can adjust settings as required. + - **Social Stream Ninja Dock** ---- + Social Stream Ninja includes a web page to see all of the message using the url below (replace XXXXXXXX with your social stream id) + + - `https://socialstream.ninja/dock.html?session=XXXXXXXXX&server&server2&sync&label=main&limit=300` + + If using OBS, you can make this url a custom browser dock. + + - **Lower 3rd** + + Social Stream Ninja has a built-in lower 3rd that you can reference by using + + `https://socialstream.ninja/index.html?session=XXXXXXXXX&aligntop&server&server2` + + If you are using OBS, you can create a browser source on a scene and use url above (replace XXXXXXXX with your social stream id) and set the following properties + + - Width: 1200 + - Height: 300 + - Shutdown source when not visible + +1. **Advanced - Optional Performance Tweaks** -## Social Stream Ninja Integration + _IMPORTANT NOTE:_ The advanced optional performance tweaks is for power users that would like to tweak the module performance. -One of the configuration options, is to send chat messages to Social Stream Ninja. In order for this to work, you need to provide your social stream ninja session id in the module configuration. + Depending on your usage of ZoomOSC and ZoomISO, there may be things going on behind the scenes that you may not be using and can disable to try to get even better performance from this module. -Once the integration is turned on, you will need to update the urls you are using for your Social Stream Ninja browser source within OBS or other streaming software. + - **Enable Variable for Each User (variables that are the ZoomId for each participant)** -### Social Stream Ninja Configuration + The module tracks a variable for each user based on their ZoomId but the ZoomId changes every time they enter the meeting, so within the module we do not use these variables for anything but for legacy purposes, we have not removed them. -You need to configuration Social Stream Ninja so that it will allow you to make API calls to it and to get your Session Id + It is suggested to turn this setting off. -1. Enable API Control - - Open Social Stream Ninja - - Go to Global settings and tools > Mechanics - - Enable Enable remote API control of extension -1. Get Your Session ID: - - Navigate to Global settings and tools > Session Options - - Copy your Session ID - - Alternatively, find it in your URL after ?session= + - **Enable Variable for Participants (e.g. Participant001 to Participant999)** -### Social Stream Ninja Dock + This impacts the participant presets, participant buttons, and participant variables. For many shows, these buttons are not used as it is the list of all participants in the order that they joined and for large meetings, it is typically quicker to find a person using the Zoom participant list and manually taking action on them. -Social Stream Ninja includes a web page to see all of the message using the url below (replace XXXXXXXX with your social stream id) + Most people use the Gallery buttons over the participant buttons as it is way easier to find people in the Gallery since you can sort the gallery by first name. -- `https://socialstream.ninja/dock.html?session=XXXXXXXXX&server&server2&sync&label=main&limit=300` + If you want to keep previous behavior of keeping these variables updated, set to true keep the behavior of previous versions. -If using OBS, you can make this url a custom browser dock. + - **Sync Action/Presets/Feedbacks** -### Lower 3rd + As participants, groups, and zISO are updated behind the scenes, it is: -Social Stream Ninja has a built-in lower 3rd that you can reference by using + 1. Keeping the option dropdown for the actions updated with the participant names, group names, zISO output/ audio names, zISO audio levels + 1. Keeping the presets updated for the number of participant names, group names, zISO output / audio names + 1. Keeping the feedbacks option dropdowns updated with the participant and group names. -`https://socialstream.ninja/index.html?session=XXXXXXXXX&aligntop&server&server2` + Keeping all these in sync is important and needed when setting up your button layout but when you are running the show you are typically not updating the design of your buttons, so you do not need to pull in new presets, adding / removing groups, or picking a different options from the option dropdowns. -If you are using OBS, you can create a browser source on a scene and use url above (replace XXXXXXXX with your social stream id) and set the following properties + Set to true keep the behavior of previous versions. -- Width: 1200 -- Height: 300 -- Shutdown source when not visible + If you do need to sync the values manually, there is a new action called "Update Actions/Feedbacks/Presets with current Zoom Data". + +--- + +## Basic Workflow + +Select user(s), then apply action(s). + +## ZoomISO Control + +- Route participants to video/audio outputs. +- Configure outputs and engine settings directly from the module. + +## Selections + +- **Dynamic Participant Display:** Names automatically appear for quick selection. +- **Selection Types:** + - **From Participants:** Static list of participants. + - **From Gallery:** Dynamic list matching Zoom’s Gallery View. +- **Single vs. Multi-Selection Mode:** + - **Single:** Select one participant at a time. + - **Multi:** Select multiple participants simultaneously. + +## More Workflows + +See more workflows at Module Readme --- @@ -152,9 +192,7 @@ If you are using OBS, you can create a browser source on a scene and use url abo This is a community-driven project utilizing the open APIs of ZoomOSC/ISO. While Zoom (and formerly Liminal) have designed its behavior, they hold no liability for this module or its upkeep. Ultimately, it is managed by and the responsibility of the open-source Companion community, Bitfocus, and its users. -### Support - -- **Module:** Known Issues -- **ZoomOSC/ISO:** `info@liminalet.com` +- **Module Support:** Known Issues +- **ZoomOSC/ISO Support:** `info@liminalet.com` -Special thanks to contributors like Jeffrey Davidsz, Andy Carluccio, and the Companion community for their efforts in creating and improving this module. +Special thanks to contributors Jeffrey Davidsz, Andy Carluccio, Jonathan Kokotajlo, and the Companion community for their efforts in creating and improving this module. diff --git a/package.json b/package.json index d9da639..27f3f15 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "zoom-osc-iso", - "version": "4.4.3", + "version": "4.5.0", "main": "dist/index.js", "repository": { "type": "git", diff --git a/src/config.ts b/src/config.ts index 54b3a11..53307a4 100644 --- a/src/config.ts +++ b/src/config.ts @@ -40,7 +40,7 @@ export const GetConfigFields = (): SomeCompanionConfigField[] => { { type: 'textinput', id: 'host', - label: 'Target host', + label: 'ZoomISO/ZoomOSC Transmission IP (e.g. Target host)', width: 6, default: '127.0.0.1', regex: Regex.IP, @@ -48,7 +48,7 @@ export const GetConfigFields = (): SomeCompanionConfigField[] => { { type: 'number', id: 'tx_port', - label: 'Sending port', + label: 'ZoomISO/ZoomOSC Receiving Port', width: 6, default: 9090, min: 1, @@ -58,7 +58,7 @@ export const GetConfigFields = (): SomeCompanionConfigField[] => { { type: 'number', id: 'rx_port', - label: 'Receive port', + label: 'ZoomISO/ZoomOSC Transmission Port', width: 6, default: 1234, min: 1, @@ -76,41 +76,42 @@ export const GetConfigFields = (): SomeCompanionConfigField[] => { default: 1, width: 6, }, + { + type: 'number', + id: 'numberOfGroups', + label: 'Number of selectable groups', + min: 0, + max: 100, + default: 3, + width: 6, + }, { type: 'dropdown', id: 'pulling', label: 'Sync iso configuration time in seconds (only for ZoomISO)', + tooltip: 'How often to update the ZoomISO audioLevels, outputRouting, audioRouting, and engineState', choices: [ - { id: 1000, label: 'Fast (1 second)' }, + { id: 1000, label: 'Fast (1 second) - Recommended' }, { id: 2500, label: 'Medium (2.5 seconds)' }, { id: 5000, label: 'Slow (5 seconds)' }, { id: 10000, label: 'Extra Slow (10 seconds)' }, ], default: 1000, - width: 6, - }, - { - type: 'number', - id: 'numberOfGroups', - label: 'Number of selectable groups', - min: 0, - max: 100, - default: 3, - width: 6, + width: 12, }, { type: 'dropdown', id: 'feedbackImagesWithIcons', - label: 'Participant Multi-State Feedback Design', - tooltip: 'Adds icons to button for camera, mic, and hand raised state', + label: 'Participant Multi-State Feedback', + tooltip: 'If enabled, adds icons to bottom of button for camera, mic, and hand raised state', choices: [ - { id: 0, label: 'Bottom (On and Off For Mic/Camera, Only on for Hand Raise)' }, + { id: 0, label: 'Bottom (On and Off For Mic/Camera, Only on for Hand Raise) - Recommended' }, { id: 2, label: 'Bottom (Only Active States)' }, { id: 3, label: 'Bottom (On and Off States)' }, - { id: 4, label: 'Disable' }, + { id: 4, label: 'Disable - Only If You Do Not Need To See Camera, Mic, and Hand Raised State' }, ], default: 0, - width: 6, + width: 12, }, { type: 'static-text',