Updating docs, getting DoricoRemote with latest websocket client changes

smithkyle · smithkyle · commit 98e24ff3e19a · 2024-12-30T16:08:35.000-08:00
diff --git a/DoricoRemote.js b/DoricoRemote.js
@@ -9,10 +9,16 @@ class DoricoRemote extends WebSocketClient {
         this.handshakeDone = false;
     }
 
-    onOpen() {
+    onOpen(resolve) {
+        let savedMessageQueue = this.messageQueue;
+        this.messageQueue = [];
+
         this._sendHandshake();
 
-        super.onOpen();
+        // this.messageQueue = savedMessageQueue;
+        // savedMessageQueue = []
+        
+        super.onOpen(resolve);
     }
 
     _sendHandshake() {
@@ -26,10 +32,11 @@ class DoricoRemote extends WebSocketClient {
             message.sessionToken = this.sessionToken;
         }
         
-        this.send(message);
+        super.send(message);
     }
 
     _processHandshake(data) {
+        console.log(data);
         if (data.message === 'sessiontoken' && data.sessionToken) {
             this.sessionToken = data.sessionToken;
             console.log(`Received sessiontoken: ${this.sessionToken} - completing handshake`);
@@ -39,7 +46,7 @@ class DoricoRemote extends WebSocketClient {
                 sessionToken: this.sessionToken
             }
 
-            this.send(message);
+            super.send(message);
         }
         else if (data.message === 'response' && data.code === 'kConnected') {
             console.log(`Handshake complete for ${this.appName}`);
@@ -48,17 +55,32 @@ class DoricoRemote extends WebSocketClient {
         }
     }
 
-    onMessage(data) {
+    onMessage(event) {
+        const data = JSON.parse(event.data);
+        
         if (!this.handshakeDone && data.message === 'sessiontoken') {
             this._processHandshake(data);
         }
         
-        super.onMessage(data);
+        super.onMessage(event);
         
         if (this.callbackAddress && this.callbackAddress.length > 0) {
             receive(this.callbackAddress, data)
         }
     }
+
+    async send(message) {
+        if (!this.socket) {
+            this.connect();
+        }
+
+        try {
+            await super.send(message);
+        }
+        catch (e) {
+            console.error('caught error', e)
+        }
+    }
 }
 
 module.exports = DoricoRemote;
diff --git a/README.md b/README.md
@@ -18,30 +18,78 @@ Once the session is running, pressing any of the buttons will initiate the hands
 
 Enjoy!
 
-## Adding Custom Buttons
+## Adding Custom Buttons (Sibelius)
 
 1. Enable the `Editor` by selecting the 3 dots menu > Editor > Enabled (checked) OR by pressing Cmd/Ctrl + E
 2. Add a button by right clicking on the canvas > Add Widget > Basics > add button
-3. Set the following properties for the button:
-   - `button`
-      - `on`: enter one of:
-         - (Sibelius) a comma-separated list of Command IDs
-         - (Sibelius) a plugin name (executing the plugin's default Run() method) **
-         - (Sibelius) a plugin JSON object to execute arbitrary plugin methods **
-         - (Dorico) a Dorico JSON message or an array of Dorico JSON messages
-   - `osc`
-      - `address`: enter one of:
-         - `/SibeliusConnect/command` if sending Command IDs
-         - `/SibeliusConnect/plugin` if invoking a plugin **
-         - `/SibeliusConnect` if sending a raw Sibelius Connect JSON message (per the [Sibelius Manuscript Reference Documentation](https://resources.avid.com/SupportFiles/Sibelius/2024.10/ManuScript_Language_Guide.pdf])) ***
-         - `/DoricoRemote` if sending a request to Dorico
-      - `send`: `localhost:8080`
-
-   _** NOTE: if executing Sibelius plugins, the plugin name **MUST** be added to the SibeliusConnect websocket instance in `customModule.js` BEFORE starting OpenStageControl, i.e.:_
+3. There are a variety of methods for sending commands to Sibelius (assuming `localhost` with default port `8080`):
 
+| Method | `button > on`                       | `osc > address` | `osc > target`   |
+| :-------------: | :---------------------------------- | :-------------: | :------------:   |
+| Command(s) (explicit)  | comma-separated list of Command IDs | `/sibelius/command` | `localhost:8080` |
+| Command(s) (implicit)  | `command:Command1,Command2,etc...` | `/sibelius` | `localhost:8080` |
+| Plugin (explicit - simple)** | PluginName (executes default Run() method) | `/sibelius/plugin` | `localhost:8080` |
+| Plugin (explicit - advanced)** | PluginName,MethodName,arg1,"arg2",... | `/sibelius/plugin` | `localhost:8080` |
+| Plugin (implicit)** | `plugin:PluginName,MethodName,arg1,"Arg 2",...` | `/sibelius` | `localhost:8080` |
+| Plugin (JSON)** | An `InvokePlugin` JSON object (without `message` key)  | `/sibelius` | `localhost:8080` |
+| Command or Plugin (raw JSON) | A raw SibeliusConnect JSON object | `/sibelius` | `localhost:8080` |
+
+   >_** NOTE: if executing Sibelius plugins, the plugin name **MUST** be added to the SibeliusConnect websocket instance in `customModule.js` BEFORE starting OpenStageControl, i.e.:_
    ```javascript
-      global.SibeliusConnect = new SibeliusConnect({ plugins: ['PositionRehearsalMarks'] })
+   global.SibeliusConnect = new SibeliusConnect({ plugins: ['cmdutils'] })
    ```
 
+## Macros
+Macros can be sent via a variety of methods:
+- Commands/plugins can be combined into an array or semicolon-separated string. For example, [Bob Zawalich's **Add Wildcards Title Subtitle Composer Lyricist** macro](https://bobzawalich.com/wp-content/uploads/2021/08/Some-Current-Sibelius-Command-Macros.pdf)
+   - Also set `osc > address: /sibelius` and `osc > target: localhost:8080`
+
+   `button > on` (as an array - can mix implicit command/plugin strings and raw SibeliusConnect JSON objects):
+
+      [
+         "plugin:cmdutils,GoToFirstBar_cu",
+         "plugin:cmdutils,TextStyleDefaultForCommands_cu,\"text.system.page_aligned.title\"",
+         "plugin:cmdutils,Add_Text_cu,\"\\$Title\\\"",
+         "plugin:cmdutils,TextStyleDefaultForCommands_cu,\"text.system.page_aligned.subtitle\"",
+         "plugin:cmdutils,Add_Text_cu,\"\\$Subtitle\\\"",
+         "plugin:cmdutils,TextStyleDefaultForCommands_cu,\"text.system.page_aligned.composer\"",
+         "plugin:cmdutils,Add_Text_cu,\"\\$Composer\\\"",
+         "plugin:cmdutils,TextStyleDefaultForCommands_cu,\"text.system.page_aligned.lyricist\"",
+         "plugin:cmdutils,Add_Text_cu,\"\\$Lyricist\\\"",
+         "command:goto_selection_start",
+         "plugin:cmdutils,MessageBox_cu,\"Please fill in the Score Info fields for the title, subtitle, composer, and lyricist, then click the Ribbon Home tab.\"",
+         "command:score_info"
+      ]
+
+   _NOTE: Some characters need to be escaped due to javascript syntax. Backslashes always need to be escaped (i.e. `\\` will result in `\` when the message is actually sent). Single quoted strings will automatically be converted to double quoted strings (with proper double quote escaping, as above)_
+   
+   `button > on` (as a semicolon-separated string):
+
+      plugin:cmdutils,GoToFirstBar_cu;
+      plugin:cmdutils,TextStyleDefaultForCommands_cu,"text.system.page_aligned.title";
+      plugin:cmdutils,Add_Text_cu,"\$Title\";
+      plugin:cmdutils,TextStyleDefaultForCommands_cu,"text.system.page_aligned.subtitle";
+      plugin:cmdutils,Add_Text_cu,"\$Subtitle\";
+      plugin:cmdutils,TextStyleDefaultForCommands_cu,"text.system.page_aligned.composer";
+      plugin:cmdutils,Add_Text_cu,"\$Composer\";
+      plugin:cmdutils,TextStyleDefaultForCommands_cu,"text.system.page_aligned.lyricist";
+      plugin:cmdutils,Add_Text_cu,"\$Lyricist\";
+      command:goto_selection_start;
+      plugin:cmdutils,MessageBox_cu,"Please fill in the Score Info fields for the title, subtitle, composer, and lyricist, then click the Ribbon Home tab.";
+      command:score_info
+
+- Implicit AND Explicit commands/plugins can also be sent as a macro using the built-in `/SibeliusConnect` macro builder. This is done by setting the widget's:
+
+   `value > linkId: >>sibelius`
+   
+   It has the following benefits:
+   - Negates the need to set the widget's `osc > address` or `osc > target`
+   - Ability to reference other widget's addresses that also send Sibelius Connect command/plugin mesages (i.e. `command:voice3;/filterRests`, where the `filterRests` widget sends its own command/plugin message)
+
 ## Additional Notes
 The `ws` NPM package is bundled with this custom module to negate the need for having NPM installed.
+
+## Roadmap
+- [ ] Cleanup interface
+- [ ] Fix reconnect websocket issues
+- [ ] Allow other OSC apps to send websocket messages via the custom module
diff --git a/SibeliusConnect.js b/SibeliusConnect.js
@@ -55,7 +55,6 @@ class SibeliusConnect extends WebSocketClient {
     }
 
     _processHandshake(data) {
-        console.log(data)
         if (data.sessionToken) {
             this.sessionToken = data.sessionToken;
             console.log('Received sessionToken:', this.sessionToken);
@@ -116,7 +115,7 @@ class SibeliusConnect extends WebSocketClient {
         }
 
         try {
-            super.send(message);
+            await super.send(message);
         }
         catch (e) {
             console.error('caught error', e)
diff --git a/WebSocketClient.js b/WebSocketClient.js
@@ -168,22 +168,26 @@ class WebSocketClient extends EventEmitter {
 
                     if (id) {
                         const responseEvent = `response:${id}`;
-                        const response = await new Promise((resolve, reject) => {
+                        const response = await new Promise((res, rej) => {
                             const timeout = setTimeout(() => {
-                                this.off(responseEvent, resolve);
-                                reject(new Error(`Timeout waiting for response to message id: ${id}`));
+                                this.off(responseEvent, res);
+                                rej(new Error(`Timeout waiting for response to message id: ${id}`));
                             }, this.responseTimeout);
 
                             this.once(responseEvent, (message) => {
                                 clearTimeout(timeout);
-                                resolve(message)
+                                res(message)
                             });
                         })
                         resolve(response)
                     }
                     else {
-                        await new Promise((response) => this.once("message", response));
-                        resolve()
+                        try {
+                            await new Promise((response) => this.once("message", response));
+                            resolve()
+                        } catch(e) {
+                            console.error(e);
+                        }
                     }
                 }
                 catch (error) {
diff --git a/customModule.js b/customModule.js
@@ -24,7 +24,12 @@ module.exports = {
             }
 
             if (address === '/sibelius' || path.dirname(address) === '/sibelius') {
-                args.forEach(arg => {
+                let newArgs = args
+                if (args.length === 1 && args[0].value.indexOf(';') > -1) {
+                    newArgs = args[0].value.split(';').map(v => { return { type: 's', value: v.replace(/^\n|\n$/g, '').trim() } })
+                }
+
+                newArgs.forEach(arg => {
                     let addr = address
                     arg = arg.value
 
@@ -55,6 +60,7 @@ module.exports = {
 
                     global.SibeliusConnect.send(msg)
                 })
+                return;
             }
             else if (address === '/dorico') {
                 args.forEach(arg => {
diff --git a/package.json b/package.json
@@ -1,8 +1,8 @@
 {
-  "name": "osc-sibelius-connect",
-  "version": "1.0.0",
+  "name": "osc-websocket",
+  "version": "0.1.0",
   "description": "",
-  "main": "sibelius-connect.js",
+  "main": "customModule.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
diff --git a/session.json b/session.json
@@ -1310,7 +1310,7 @@
           },
           {
             "type": "button",
-            "top": 470,
+            "top": 550,
             "left": 410,
             "lock": false,
             "id": "button_8",
@@ -1356,7 +1356,7 @@
           },
           {
             "type": "button",
-            "top": 390,
+            "top": 470,
             "left": 410,
             "lock": false,
             "id": "addWildcardsArr",
@@ -1392,6 +1392,7 @@
               "plugin:cmdutils,Add_Text_cu,\"\\$Composer\\\"",
               "plugin:cmdutils,TextStyleDefaultForCommands_cu,\"text.system.page_aligned.lyricist\"",
               "plugin:cmdutils,Add_Text_cu,\"\\$Lyricist\\\"",
+              "plugin:cmdutils,Add_Text_cu,\"$Lyricist\"",
               "command:goto_selection_start",
               "plugin:cmdutils,MessageBox_cu,\"Please fill in the Score Info fields for the title, subtitle, composer, and lyricist, then click the Ribbon Home tab.\"",
               "command:score_info"
@@ -1415,7 +1416,7 @@
           },
           {
             "type": "button",
-            "top": 530,
+            "top": 610,
             "left": 410,
             "lock": false,
             "id": "button_7",
@@ -1458,6 +1459,52 @@
             "bypass": false,
             "onCreate": "",
             "onValue": ""
+          },
+          {
+            "type": "button",
+            "top": 390,
+            "left": 410,
+            "lock": false,
+            "id": "addWildcardsServer",
+            "visible": true,
+            "interaction": true,
+            "comments": "",
+            "width": 130,
+            "height": 80,
+            "expand": "false",
+            "colorText": "auto",
+            "colorWidget": "auto",
+            "colorStroke": "auto",
+            "colorFill": "auto",
+            "alphaStroke": "auto",
+            "alphaFillOff": "auto",
+            "alphaFillOn": "auto",
+            "lineWidth": "auto",
+            "borderRadius": "auto",
+            "padding": "auto",
+            "html": "",
+            "css": "",
+            "colorTextOn": "auto",
+            "label": "Add Wildcards\nTitle, SubTitle\nComposer, Lyricist\n(macro - server)",
+            "vertical": false,
+            "wrap": false,
+            "on": "plugin:cmdutils,GoToFirstBar_cu;\nplugin:cmdutils,TextStyleDefaultForCommands_cu,\"text.system.page_aligned.title\";\nplugin:cmdutils,Add_Text_cu,\"\\$Title\\\";\nplugin:cmdutils,TextStyleDefaultForCommands_cu,\"text.system.page_aligned.subtitle\";\nplugin:cmdutils,Add_Text_cu,\"\\$Subtitle\\\";\nplugin:cmdutils,TextStyleDefaultForCommands_cu,\"text.system.page_aligned.composer\";\nplugin:cmdutils,Add_Text_cu,\"\\$Composer\\\";\nplugin:cmdutils,TextStyleDefaultForCommands_cu,\"text.system.page_aligned.lyricist\";\nplugin:cmdutils,Add_Text_cu,\"\\$Lyricist\\\";\ncommand:goto_selection_start;\nplugin:cmdutils,MessageBox_cu,\"Please fill in the Score Info fields for the title, subtitle, composer, and lyricist, then click the Ribbon Home tab.\";\ncommand:score_info",
+            "off": 0,
+            "mode": "tap",
+            "doubleTap": false,
+            "decoupled": false,
+            "value": "",
+            "default": "",
+            "linkId": "",
+            "address": "/sibelius",
+            "preArgs": "",
+            "typeTags": "",
+            "decimals": 2,
+            "target": "localhost:8080",
+            "ignoreDefaults": false,
+            "bypass": false,
+            "onCreate": "",
+            "onValue": ""
           }
         ],
         "tabs": []

Original file line number	Diff line number	Diff line change
`@@ -9,10 +9,16 @@ class DoricoRemote extends WebSocketClient {`
`9`	`9`	`this.handshakeDone = false;`
`10`	`10`	`}`
`11`	`11`
`12`		`- onOpen() {`
	`12`	`+ onOpen(resolve) {`
	`13`	`+ let savedMessageQueue = this.messageQueue;`
	`14`	`+ this.messageQueue = [];`
	`15`	`+`
`13`	`16`	`this._sendHandshake();`
`14`	`17`
`15`		`- super.onOpen();`
	`18`	`+ // this.messageQueue = savedMessageQueue;`
	`19`	`+ // savedMessageQueue = []`
	`20`	`+`
	`21`	`+ super.onOpen(resolve);`
`16`	`22`	`}`
`17`	`23`
`18`	`24`	`_sendHandshake() {`
`@@ -26,10 +32,11 @@ class DoricoRemote extends WebSocketClient {`
`26`	`32`	`message.sessionToken = this.sessionToken;`
`27`	`33`	`}`
`28`	`34`
`29`		`- this.send(message);`
	`35`	`+ super.send(message);`
`30`	`36`	`}`
`31`	`37`
`32`	`38`	`_processHandshake(data) {`
	`39`	`+ console.log(data);`
`33`	`40`	`if (data.message === 'sessiontoken' && data.sessionToken) {`
`34`	`41`	`this.sessionToken = data.sessionToken;`
`35`	`42`	console.log(`Received sessiontoken: ${this.sessionToken} - completing handshake`);
`@@ -39,7 +46,7 @@ class DoricoRemote extends WebSocketClient {`
`39`	`46`	`sessionToken: this.sessionToken`
`40`	`47`	`}`
`41`	`48`
`42`		`- this.send(message);`
	`49`	`+ super.send(message);`
`43`	`50`	`}`
`44`	`51`	`else if (data.message === 'response' && data.code === 'kConnected') {`
`45`	`52`	console.log(`Handshake complete for ${this.appName}`);
`@@ -48,17 +55,32 @@ class DoricoRemote extends WebSocketClient {`
`48`	`55`	`}`
`49`	`56`	`}`
`50`	`57`
`51`		`- onMessage(data) {`
	`58`	`+ onMessage(event) {`
	`59`	`+ const data = JSON.parse(event.data);`
	`60`	`+`
`52`	`61`	`if (!this.handshakeDone && data.message === 'sessiontoken') {`
`53`	`62`	`this._processHandshake(data);`
`54`	`63`	`}`
`55`	`64`
`56`		`- super.onMessage(data);`
	`65`	`+ super.onMessage(event);`
`57`	`66`
`58`	`67`	`if (this.callbackAddress && this.callbackAddress.length > 0) {`
`59`	`68`	`receive(this.callbackAddress, data)`
`60`	`69`	`}`
`61`	`70`	`}`
	`71`	`+`
	`72`	`+ async send(message) {`
	`73`	`+ if (!this.socket) {`
	`74`	`+ this.connect();`
	`75`	`+ }`
	`76`	`+`
	`77`	`+ try {`
	`78`	`+ await super.send(message);`
	`79`	`+ }`
	`80`	`+ catch (e) {`
	`81`	`+ console.error('caught error', e)`
	`82`	`+ }`
	`83`	`+ }`
`62`	`84`	`}`
`63`	`85`
`64`	`86`	`module.exports = DoricoRemote;`
Original file line number	Diff line number	Diff line change
`@@ -55,7 +55,6 @@ class SibeliusConnect extends WebSocketClient {`
`55`	`55`	`}`
`56`	`56`
`57`	`57`	`_processHandshake(data) {`
`58`		`- console.log(data)`
`59`	`58`	`if (data.sessionToken) {`
`60`	`59`	`this.sessionToken = data.sessionToken;`
`61`	`60`	`console.log('Received sessionToken:', this.sessionToken);`
`@@ -116,7 +115,7 @@ class SibeliusConnect extends WebSocketClient {`
`116`	`115`	`}`
`117`	`116`
`118`	`117`	`try {`
`119`		`- super.send(message);`
	`118`	`+ await super.send(message);`
`120`	`119`	`}`
`121`	`120`	`catch (e) {`
`122`	`121`	`console.error('caught error', e)`