@ircam/comote-helpers 0.1.0 → 0.3.0

package/.github/workflows/main.yml

@@ -0,0 +1,45 @@
+# Zip and release Max package on new version
+
+name: CI
+
+# Controls when the action will run.
+on:
+  # Triggers the workflow on push or pull request events but only for the master branch
+  push:
+    # Sequence of patterns matched against refs/tags
+    tags:
+      - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Upload Release Asset
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+      - name: Build project # This would actually build your project, using zip for an example artifact
+        run: |
+          (cd max && zip -r - comote) > comote-for-max.zip
+      - name: Create Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+          draft: false
+          prerelease: false
+      - name: Upload Release Asset
+        id: upload-release-asset
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }} # This pulls from the CREATE RELEASE step above, referencing it's ID to get its outputs object, which include a `upload_url`. See this blog post for more info: https://jasonet.co/posts/new-features-of-github-actions/#passing-data-to-future-steps
+          asset_path: ./comote-for-max.zip
+          asset_name: comote-for-max.zip
+          asset_content_type: application/zip

package/README.md

@@ -3,37 +3,54 @@
 > Javascript and Max/MSP utilities to create applications compatible with iPhone 
 > and Android `CoMo.te` application.
 
+
+The CoMo.te application (iOS and Android) allows for streaming motion data (accelerometer, gyroscope) from the smartphone to desktop applications using either the OSC or Websockets protocols. The network's setup is facilitated by the use of a QR code generated by the targeted remote application receiving the motion sensor data.
+    
+CoMo.te is especially designed for the CoMo applications family that enables real-time interaction between gestures/movements and sounds. Nevertheless, the CoMo.te application can be used with any software that makes use of the OSC protocol.
+
+Among the CoMo applications that make use of CoMo.te are CoMo-Vox to learn and train conducting gestures, and CoMo-Elements to interact collectively thought body movements with recorded sounds.
+
+CoMo.te and the CoMo applications are software designed and developed by IRCAM in the Sound-Music-Movement-Interaction team (UMR STMS).
+
+This repository provides utilities to help to generate the QRCode in the target application both for Max/MSP and Node.js
+
 ## Table of Contents
 
 <!-- toc -->
 
-- [Install](#install)
-- [API](#api)
-  * [Classes](#classes)
-  * [Functions](#functions)
-  * [Typedefs](#typedefs)
-  * [getWifiInfos() ⇒ WiFiInfos \| null](#getwifiinfos-%E2%87%92-wifiinfos--null)
-  * [rawLink()](#rawlink)
-  * [terminal(config)](#terminalconfig)
-  * [dataURL(config)](#dataurlconfig)
-  * [WifiInfos : Object](#wifiinfos--object)
-  * [CoMoteConfig : Object](#comoteconfig--object)
-  * [CoMoteTarget : Object](#comotetarget--object)
+- [Max/MSP](#maxmsp)
+- [JS](#js)
+  * [Node.js](#nodejs)
+  * [API](#api)
 - [License](#license)
 
 <!-- tocstop -->
 
-## Install
+## Max/MSP
+
+Download the Max abstraction (SoundworksAPI.zip) from the releases page: https://github.com/ircam-ismm/comote-helpers/releases
+Unzip the package and copy the resulting directory in `~/Documents/Max 8/Packages`
+
+For now, the package only provide abstraction `[comote.connect]` that allows you to generate a QRCode that can be 
+flashed within the CoMo.te application to configure the OSC stream.
+
+You can find more informations in the Helper patch: `~/Document/Max 8/Packages/CoMo.te/extras/CoMo.te.maxpat`
+
+This version requires Max 7.1 or higher.
+
+## JS
+
+### Node.js
 
 ```sh
 npm install --save @ircam/comote-helpers
 ```
 
-## JS API
+### API
 
 <!-- api -->
 
-### Classes
+#### Classes
 
 <dl>
 <dt><a href="#Server">Server</a></dt>
@@ -41,13 +58,9 @@ npm install --save @ircam/comote-helpers
 </dd>
 </dl>
 
-### Functions
+#### Functions
 
 <dl>
-<dt><a href="#getWifiInfos">getWifiInfos()</a> ⇒ <code>WiFiInfos</code> | <code>null</code></dt>
-<dd><p>Retrieve the SSID and related IP of the first WiFi connection found, return
-<code>null</code> if no WiFi connection found.</p>
-</dd>
 <dt><a href="#rawLink">rawLink()</a></dt>
 <dd><p>Return the link to be encoded in the QRCode accroding to given <code>CoMoteConfig</code></p>
 </dd>
@@ -59,33 +72,24 @@ npm install --save @ircam/comote-helpers
 </dd>
 </dl>
 
-### Typedefs
+#### Typedefs
 
 <dl>
-<dt><a href="#WifiInfos">WifiInfos</a> : <code>Object</code></dt>
-<dd></dd>
 <dt><a href="#CoMoteConfig">CoMoteConfig</a> : <code>Object</code></dt>
 <dd></dd>
 <dt><a href="#CoMoteTarget">CoMoteTarget</a> : <code>Object</code></dt>
 <dd></dd>
 </dl>
 
-<a name="getWifiInfos"></a>
-
-### getWifiInfos() ⇒ <code>WiFiInfos</code> \| <code>null</code>
-Retrieve the SSID and related IP of the first WiFi connection found, return
-`null` if no WiFi connection found.
-
-**Kind**: global function  
 <a name="rawLink"></a>
 
-### rawLink()
+#### rawLink()
 Return the link to be encoded in the QRCode accroding to given `CoMoteConfig`
 
 **Kind**: global function  
 <a name="terminal"></a>
 
-### terminal(config)
+#### terminal(config)
 Create a qrcode to be logged in terminal according to given `CoMoteConfig``
 
 **Kind**: global function  
@@ -96,11 +100,11 @@ Create a qrcode to be logged in terminal according to given `CoMoteConfig``
 
 **Example**  
 ```js
-console(CoMoteQRCode.terminal(config));
+console(await CoMoteQRCode.terminal(config));
 ```
 <a name="dataURL"></a>
 
-### dataURL(config)
+#### dataURL(config)
 Create a qrcode to be used as in Image source according to given `CoMoteConfig``
 
 **Kind**: global function  
@@ -111,22 +115,13 @@ Create a qrcode to be used as in Image source according to given `CoMoteConfig``
 
 **Example**  
 ```js
-<img src="${CoMoteQRCode.dataURL(config))}" />
-```
-<a name="WifiInfos"></a>
-
-### WifiInfos : <code>Object</code>
-**Kind**: global typedef  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| ssid | <code>number</code> | SSID of the WiFi connection |
-| ip | <code>number</code> | Related IP (IPV4) |
+const qrCode = await CoMoteQRCode.dataURL(config));
 
+<img src="${qrCode}" />
+```
 <a name="CoMoteConfig"></a>
 
-### CoMoteConfig : <code>Object</code>
+#### CoMoteConfig : <code>Object</code>
 **Kind**: global typedef  
 **Properties**
 
@@ -139,7 +134,7 @@ Create a qrcode to be used as in Image source according to given `CoMoteConfig``
 
 <a name="CoMoteTarget"></a>
 
-### CoMoteTarget : <code>Object</code>
+#### CoMoteTarget : <code>Object</code>
 **Kind**: global typedef  
 **Properties**
 
@@ -152,6 +147,12 @@ Create a qrcode to be used as in Image source according to given `CoMoteConfig``
 
 <!-- apistop -->
 
+## Credits
+
+CoMo.te is developed by Ircam and the Music and Sound Science and Technology Joint Research Unit (STMS), supported by Ircam, CNRS, the French Ministry of Culture and Sorbonne University.
+
+Produced with the support of the French Ministry of Education, Youth and Sports (Edu-up system), the National Research Agency (ELEMENT project), and in partnership with Radio France.
+
 ## License
 
 BSD-3-Clause

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ircam/comote-helpers",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Server component & utilities for the CoMo.te application",
   "authors": [
     "Benjamin.Matuszewski@ircam.fr",
@@ -15,7 +15,7 @@
     "access": "public"
   },
   "scripts": {
-    "api": "jsdoc-to-readme --src src/server.js src/qrcode.js",
+    "api": "jsdoc-to-readme --src src/server.js src/qrcode.js --heading-depth 4",
     "build": "npm run clean && babel src --out-dir .",
     "clean": "rm -f server.js qrcode.js",
     "dev": "npm run build && chokidar src -c \"npm run build\"",

package/qrcode.js

@@ -15,7 +15,7 @@ function formatConfigToLink(config) {
   let link = `comote://settings?`;
   const query = [];
 
-  if (Number.isFinite(config.id) && config.id >= 0) {
+  if ('id' in config) {
     query.push(`id=${config.id}`);
   }
 
@@ -25,15 +25,30 @@ function formatConfigToLink(config) {
 
   if (config.ws) {
     const {
+      protocol,
       hostname,
-      port
-    } = config.ws;
+      port,
+      pathname
+    } = config.ws; // build valid url
+    // only hostname is required
 
-    if (!hostname || !Number.isInteger(port)) {
+    if (!hostname) {
       throw new Error(`Invalid WebSocket config: ${config.ws}`);
     }
 
-    query.push(`ws-url=ws://${hostname}:${port}`);
+    let url = `ws-url=`;
+    url += protocol == 'ws' || protocol == 'wss' ? `${protocol}://` : `ws://`;
+    url += hostname;
+
+    if (port) {
+      url += `:${port}`;
+    }
+
+    if (pathname) {
+      url += pathname;
+    }
+
+    query.push(url); // autostart
 
     if (config.ws.autostart === true) {
       query.push(`ws-enable=1`);