@clockworkdog/cogs-client 1.5.5 → 2.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Clockwork Dog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -30,10 +30,61 @@ yarn add @clockworkdog/cogs-client
 
 ## Usage
 
-### Create a `cogs-plugin-manifest.json` file
+### Create a `cogs-plugin-manifest.js` file
 
 See [PluginManifestJson](https://clockwork-dog.github.io/cogs-client-lib/interfaces/PluginManifestJson.html) for details of what to include.
 
+If using Typescript set `"allowJs": true` in your `tsconfig.json`.
+
+Use the `@type {const}` JSDoc annotation to allow the manifest to be imported as a literal type and `@satisfies {import("@clockworkdog/cogs-client").PluginManifestJson}` to allow your editor to check the validity of the manifest.
+
+e.g.
+
+```js
+module.exports =
+  /**
+   * @type {const}
+   * @satisfies {import("@clockworkdog/cogs-client").PluginManifestJsonReadonly}
+   */
+  ({
+    name: 'Big Button',
+    icon: 'bullseye-pointer',
+    description: 'A big, colorful touchscreen button',
+    version: '1',
+    config: [
+      {
+        name: 'Color',
+        value: { type: 'string', default: 'red' },
+      },
+    ],
+    state: [
+      {
+        name: 'Enabled',
+        value: { type: 'boolean', default: false },
+        writableFromCogs: true,
+      },
+    ],
+    events: {
+      toCogs: [
+        {
+          name: 'Pressed',
+          value: { type: 'boolean' },
+        },
+      ],
+      fromCogs: [
+        {
+          name: 'Explosion',
+        },
+      ],
+    },
+    media: {
+      audio: true,
+      video: true,
+      images: true,
+    },
+  });
+```
+
 ### Import the library
 
 #### Browser
@@ -48,7 +99,7 @@ const { CogsConnection, CogsAudioPlayer } = COGS;
 const { CogsConnection, CogsAudioPlayer } = require('@clockworkdog/cogs-client');
 ```
 
-#### Typesript / ES6
+#### Typescript / ES6
 
 ```ts
 import { CogsConnection, CogsAudioPlayer } from '@clockworkdog/cogs-client';
@@ -56,35 +107,35 @@ import { CogsConnection, CogsAudioPlayer } from '@clockworkdog/cogs-client';
 
 ### Connect to COGS
 
+Initialize a [CogsConnection](https://clockwork-dog.github.io/cogs-client-lib/interfaces/CogsConnection.html) with the manifest you created above.
+
 ```ts
 let connected = false;
 
-const cogsConnection = new CogsConnection();
+import manifest from './cogs-plugin-manifest.js'; // Requires `"allowJs": true` in `tsconfig.json`
+
+const cogsConnection = new CogsConnection(manifest);
 cogsConnection.addEventListener('open', () => {
   connected = true;
 });
 cogsConnection.addEventListener('close', () => {
   connected = false;
 });
-cogsConnection.addEventListener('config', (event) => {
-  const config = event.detail;
-  // Handle new config.
-  // `config` is of type `{ [configKey: string]: number | string | boolean }`
+cogsConnection.addEventListener('config', ({ config }) => {
+  // Handle new config
+  // `config` is of type `{ [name: string]: number | string | boolean }`
 });
-cogsConnection.addEventListener('updates', (event) => {
-  const updates = event.detail;
-  // Handle input port updates.
-  // `updates` is of type `{ [portName: string]: number | string | boolean }`
+cogsConnection.addEventListener('state', ({ state }) => {
+  // Handle state updates
+  // `state` is of type `{ [name: string]: number | string | boolean }`
 });
-cogsConnection.addEventListener('event', (event) => {
-  const { key, value } = event.detail;
-  // Handle event. See 'types/Callback.ts`
-  // `key` is the event name.
-  // `value` is the type defined in COGS, one of `number | string | boolean | undefined`
+cogsConnection.addEventListener('event', ({ name, value }) => {
+  // Handle events from COGS
+  // `name` is the event name.
+  // `value` is of the type defined in manifest, one of `number | string | boolean | undefined`.
 });
-cogsConnection.addEventListener('message', (event) => {
-  const message = event.detail;
-  // Handle message. See `types/CogsClientMessage.ts`
+cogsConnection.addEventListener('message', ({ message }) => {
+  // Handle low-level COGS messages. See `types/CogsClientMessage.ts`
 });
 
 function sendEventToCogs() {
@@ -92,12 +143,30 @@ function sendEventToCogs() {
 }
 
 function sendPortUpdateToCogs() {
-  cogsConnection.setOutputPortValues({ port1: 100 });
+  cogsConnection.setState({ port1: 100 });
+}
+```
+
+### Support audio actions
+
+Add `audio` to `cogs-plugin-manifest.js`:
+
+```js
+{
+  media: {
+    audio: true;
+  }
 }
+```
+
+Add [CogsAudioPlayer](https://clockwork-dog.github.io/cogs-client-lib/classes/CogsAudioPlayer.html) to your page:
 
+```ts
 const audioPlayer = new CogsAudioPlayer(cogsConnection);
+
+// Optional
 audioPlayer.addEventListener('state', (audioState) => {
-  // Handle audio state. See `types/AudioState.ts`
+  // Handle audio state changes. See `types/AudioState.ts`
 });
 ```
 

package/dist/AudioPlayer.d.ts

@@ -1,7 +1,7 @@
 import CogsConnection from './CogsConnection';
 import { AudioState } from './types/AudioState';
 import MediaClipStateMessage from './types/MediaClipStateMessage';
-declare type EventTypes = {
+type EventTypes = {
     state: AudioState;
     audioClipState: MediaClipStateMessage;
 };
@@ -10,7 +10,7 @@ export default class AudioPlayer {
     private globalVolume;
     private audioClipPlayers;
     private sinkId;
-    constructor(cogsConnection: CogsConnection);
+    constructor(cogsConnection: CogsConnection<any>);
     setGlobalVolume(volume: number): void;
     playAudioClip(path: string, { playId, volume, fade, loop }: {
         playId: string;

package/dist/AudioPlayer.js

@@ -16,8 +16,7 @@ class AudioPlayer {
             cogsConnection.sendMediaClipState(detail);
         });
         // Listen for audio control messages
-        cogsConnection.addEventListener('message', (event) => {
-            const message = event.detail;
+        cogsConnection.addEventListener('message', ({ message }) => {
             switch (message.type) {
                 case 'media_config_update':
                     if (this.globalVolume !== message.globalVolume) {
@@ -95,7 +94,7 @@ class AudioPlayer {
                 .filter(([, { state }]) => state.type === 'pausing')
                 .map(([id]) => parseInt(id));
             pausedSoundIds.forEach((soundId) => {
-                log('Resuming paused clip', { soundId });
+                log('Resuming paused clip', soundId);
                 clipPlayer.player.play(soundId);
             });
             // Clips with pause requested no longer need to pause, they can continue playing now
@@ -106,7 +105,7 @@ class AudioPlayer {
             const newSoundIds = pausedSoundIds.length > 0 || pausingSoundIds.length > 0 || pauseRequestedSoundIds.length > 0 ? [] : [clipPlayer.player.play()];
             // Pausing clips are technically currently playing as far as Howler is concerned
             pausingSoundIds.forEach((soundId) => {
-                log('Stopping fade and resuming pausing clip', { soundId });
+                log('Stopping fade and resuming pausing clip', soundId);
                 // Stop the fade callback
                 clipPlayer.player.off('fade', undefined, soundId);
                 // Set loop property
@@ -135,7 +134,6 @@ class AudioPlayer {
                 // Non-preloaded clips don't yet have an HTML audio node
                 // so we need to set the audio output when it's playing
                 clipPlayer.player.once('play', () => {
-                    log('play() callback - setPlayerSinkId', { soundId });
                     setPlayerSinkId(clipPlayer.player, this.sinkId);
                 });
                 clipPlayer.player.once('stop', () => this.handleStoppedClip(path, playId, soundId), soundId);
@@ -152,12 +150,11 @@ class AudioPlayer {
                     loop,
                     volume,
                 };
-                log('CLIP -> play_requested');
+                log('CLIP -> play_requested', soundId);
                 // Once clip starts, check if it should actually be paused or stopped
                 // If not, then update state to 'playing'
                 clipPlayer.player.once('play', () => {
                     var _a;
-                    log('play() callback - update state', { soundId });
                     const clipState = (_a = clipPlayer.activeClips[soundId]) === null || _a === void 0 ? void 0 : _a.state;
                     if ((clipState === null || clipState === void 0 ? void 0 : clipState.type) === 'pause_requested') {
                         log('Clip started playing but should be paused', { path, soundId });
@@ -168,7 +165,7 @@ class AudioPlayer {
                         this.stopAudioClip(path, { fade: clipState.fade }, soundId, true);
                     }
                     else {
-                        log('CLIP -> playing');
+                        log('CLIP -> playing', soundId);
                         this.updateActiveAudioClip(path, soundId, (clip) => ({ ...clip, state: { type: 'playing' } }));
                     }
                 }, soundId);
@@ -178,7 +175,6 @@ class AudioPlayer {
                     clipPlayer.player.volume(0, soundId);
                     clipPlayer.player.mute(false, soundId);
                     clipPlayer.player.once('play', () => {
-                        log('play() callback - fade volume', { soundId });
                         fadeAudioPlayerVolume(clipPlayer.player, volume, fade * 1000, soundId);
                     }, soundId);
                 }
@@ -208,25 +204,25 @@ class AudioPlayer {
                             // Fade then pause
                             clipPlayer.player.once('fade', (soundId) => {
                                 clipPlayer.player.pause(soundId);
-                                log('CLIP -> paused (after fade)');
+                                log('CLIP -> paused (after fade)', soundId);
                                 this.updateActiveAudioClip(path, soundId, (clip) => ({ ...clip, state: { type: 'paused' } }));
                                 this.notifyClipStateListeners(clip.playId, path, 'paused');
                             }, soundId);
                             fadeAudioPlayerVolume(clipPlayer.player, 0, fade * 1000, soundId);
-                            log('CLIP -> pausing');
+                            log('CLIP -> pausing', soundId);
                             clip.state = { type: 'pausing' };
                         }
                         else {
                             // Pause now
                             clipPlayer.player.pause(soundId);
-                            log('CLIP -> paused');
+                            log('CLIP -> paused', soundId);
                             clip.state = { type: 'paused' };
                             this.notifyClipStateListeners(clip.playId, path, 'paused');
                         }
                     }
                     // Clip hasn't started playing yet, or has already had pause_requested (but fade may have changed so update here)
                     else if (clip.state.type === 'play_requested' || clip.state.type === 'pause_requested') {
-                        log('CLIP -> pause_requested');
+                        log('CLIP -> pause_requested', soundId);
                         clip.state = { type: 'pause_requested', fade };
                     }
                 }
@@ -236,9 +232,10 @@ class AudioPlayer {
         });
     }
     stopAudioClip(path, { fade }, onlySoundId, allowIfStopRequested) {
-        var _a, _b;
+        var _a, _b, _c;
+        log('Stop audio clip', { activeClips: (_a = this.audioClipPlayers[path]) === null || _a === void 0 ? void 0 : _a.activeClips });
         // No active clips to stop
-        if (Object.keys((_b = (_a = this.audioClipPlayers[path]) === null || _a === void 0 ? void 0 : _a.activeClips) !== null && _b !== void 0 ? _b : {}).length === 0) {
+        if (Object.keys((_c = (_b = this.audioClipPlayers[path]) === null || _b === void 0 ? void 0 : _b.activeClips) !== null && _c !== void 0 ? _c : {}).length === 0) {
             return;
         }
         this.updateAudioClipPlayer(path, (clipPlayer) => {
@@ -257,11 +254,16 @@ class AudioPlayer {
                             clipPlayer.player.off('fade', soundId);
                             fadeAudioPlayerVolume(clipPlayer.player, 0, fade * 1000, soundId);
                             // Set callback after starting new fade, otherwise it will fire straight away as the previous fade is cancelled
-                            clipPlayer.player.once('fade', (soundId) => clipPlayer.player.stop(soundId), soundId);
-                            log('CLIP -> stopping');
+                            clipPlayer.player.once('fade', (soundId) => {
+                                clipPlayer.player.loop(false, soundId);
+                                clipPlayer.player.stop(soundId), soundId;
+                            });
+                            log('CLIP -> stopping', soundId);
                             clip.state = { type: 'stopping' };
                         }
                         else {
+                            log('Stop clip', soundId);
+                            clipPlayer.player.loop(false, soundId);
                             clipPlayer.player.stop(soundId);
                         }
                     }
@@ -269,7 +271,7 @@ class AudioPlayer {
                     // or has pause_requested, but stop takes precedence
                     else if (clip.state.type === 'play_requested' || clip.state.type === 'pause_requested' || clip.state.type === 'stop_requested') {
                         log("Trying to stop clip which hasn't started playing yet", { path, soundId });
-                        log('CLIP -> stop_requested');
+                        log('CLIP -> stop_requested', soundId);
                         clip.state = { type: 'stop_requested', fade };
                     }
                 }
@@ -405,7 +407,7 @@ class AudioPlayer {
     }
     createPlayer(path, config) {
         const player = new howler_1.Howl({
-            src: urls_1.assetUrl(path),
+            src: (0, urls_1.assetUrl)(path),
             autoplay: false,
             loop: false,
             volume: 1,
@@ -471,9 +473,8 @@ function setAudioPlayerVolume(howl, volume, soundId) {
 /**
  * Fade to audio volume
  *
- * This doesn't work on iOS (volume is read-only) so at least mute it if the volume is zero
+ * Note: This doesn't work on iOS (volume is read-only)
  */
 function fadeAudioPlayerVolume(howl, volume, fade, soundId) {
-    howl.mute(false, soundId);
     howl.fade(howl.volume(soundId), volume, fade, soundId);
 }

package/dist/CogsConnection.d.ts

@@ -1,57 +1,18 @@
-import { ConfigValue, EventKeyValue, EventValue, PortValue, ShowPhase } from './types/valueTypes';
+import ShowPhase from './types/ShowPhase';
 import CogsClientMessage from './types/CogsClientMessage';
 import MediaClipStateMessage from './types/MediaClipStateMessage';
 import AllMediaClipStatesMessage from './types/AllMediaClipStatesMessage';
-interface ConnectionEventListeners<CustomTypes extends {
-    config?: {
-        [configKey: string]: ConfigValue;
-    };
-    inputPorts?: {
-        [port: string]: PortValue;
-    };
-    inputEvents?: {
-        [key: string]: EventValue | null;
-    };
-}> {
-    open: undefined;
-    close: undefined;
-    message: CogsClientMessage;
-    config: CustomTypes['config'];
-    updates: Partial<CustomTypes['inputPorts']>;
-    event: CustomTypes['inputEvents'] extends {
-        [key: string]: EventValue | null;
-    } ? EventKeyValue<CustomTypes['inputEvents']> : Record<string, never>;
-}
-export declare type TimerState = Omit<Extract<CogsClientMessage, {
-    type: 'adjustable_timer_update';
-}>, 'type'> & {
-    startedAt: number;
-};
-export default class CogsConnection<CustomTypes extends {
-    config?: {
-        [configKey: string]: ConfigValue;
-    };
-    inputPorts?: {
-        [port: string]: PortValue;
-    };
-    outputPorts?: {
-        [port: string]: PortValue;
-    };
-    inputEvents?: {
-        [key: string]: EventValue | null;
-    };
-    outputEvents?: {
-        [key: string]: EventValue | null;
-    };
-} = Record<never, never>> {
+import { PluginManifestEventJson } from './types/PluginManifestJson';
+import * as ManifestTypes from './types/ManifestTypes';
+import { DeepReadonly } from './types/utils';
+export default class CogsConnection<Manifest extends ManifestTypes.PluginManifest> {
+    readonly manifest: Manifest;
     private websocket;
     private eventTarget;
     private currentConfig;
-    get config(): CustomTypes['config'];
-    private currentInputPortValues;
-    get inputPortValues(): CustomTypes['inputPorts'];
-    private currentOutputPortValues;
-    get outputPortValues(): CustomTypes['outputPorts'];
+    get config(): ManifestTypes.ConfigAsObject<Manifest>;
+    private currentState;
+    get state(): ManifestTypes.StateAsObject<Manifest>;
     private _showPhase;
     get showPhase(): ShowPhase;
     private _timerState;
@@ -62,14 +23,18 @@ export default class CogsConnection<CustomTypes extends {
     private audioOutputs;
     private _selectedAudioOutput;
     get selectedAudioOutput(): string;
-    constructor({ hostname, port }?: {
+    constructor(manifest: Manifest, { hostname, port }?: {
         hostname?: string;
         port?: number;
-    }, outputPortValues?: CustomTypes['outputPorts']);
+    }, initialClientState?: Partial<ManifestTypes.StateAsObject<Manifest, {
+        writableFromClient: true;
+    }>> | undefined);
     get isConnected(): boolean;
     close(): void;
-    sendEvent<EventName extends keyof CustomTypes['outputEvents']>(eventName: EventName, ...[eventValue]: CustomTypes['outputEvents'][EventName] extends null ? [] : [CustomTypes['outputEvents'][EventName]]): void;
-    setOutputPortValues(values: Partial<CustomTypes['outputPorts']>): void;
+    sendEvent<EventName extends ManifestTypes.EventToCogsKey<Manifest>>(eventName: EventName, ...[eventValue]: ManifestTypes.EventToCogsAsObject<Manifest>[EventName] extends undefined ? [] : [ManifestTypes.EventToCogsAsObject<Manifest>[EventName]]): void;
+    setState(values: Partial<ManifestTypes.StateAsObject<Manifest, {
+        writableFromClient: true;
+    }>>): void;
     getAudioSinkId(audioOutput: string): string | undefined;
     sendInitialMediaClipStates(allMediaClipStates: AllMediaClipStatesMessage): void;
     sendMediaClipState(mediaClipState: MediaClipStateMessage): void;
@@ -80,8 +45,50 @@ export default class CogsConnection<CustomTypes extends {
      * This is only relevant for plugins, not for Media Master content.
      */
     setPluginWindowVisible(visible: boolean): void;
-    addEventListener<EventName extends keyof ConnectionEventListeners<CustomTypes>, EventValue extends ConnectionEventListeners<CustomTypes>[EventName]>(type: EventName, listener: (ev: CustomEvent<EventValue>) => void, options?: boolean | AddEventListenerOptions): void;
-    removeEventListener<EventName extends keyof ConnectionEventListeners<CustomTypes>, EventValue extends ConnectionEventListeners<CustomTypes>[EventName]>(type: EventName, listener: (ev: CustomEvent<EventValue>) => void, options?: boolean | EventListenerOptions): void;
+    addEventListener<EventType extends CogsConnectionEvent<Manifest>['type']>(type: EventType, listener: (event: CogsConnectionEvent<Manifest> & {
+        type: EventType;
+    }) => void, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<EventType extends CogsConnectionEvent<Manifest>['type']>(type: EventType, listener: (event: Extract<CogsConnectionEvent<Manifest>, {
+        type: EventType;
+    }>) => void, options?: boolean | EventListenerOptions): void;
     private dispatchEvent;
 }
-export {};
+export type TimerState = Omit<Extract<CogsClientMessage, {
+    type: 'adjustable_timer_update';
+}>, 'type'> & {
+    startedAt: number;
+};
+export declare class CogsConnectionOpenEvent extends Event {
+    readonly type = "open";
+    constructor();
+}
+export declare class CogsConnectionCloseEvent extends Event {
+    readonly type = "close";
+    constructor();
+}
+export declare class CogsMessageEvent extends Event {
+    readonly message: CogsClientMessage;
+    readonly type = "message";
+    constructor(message: CogsClientMessage);
+}
+export declare class CogsConfigChangedEvent<CogsConfig> extends Event {
+    readonly config: CogsConfig;
+    readonly type = "config";
+    constructor(config: CogsConfig);
+}
+export declare class CogsStateChangedEvent<CogsState> extends Event {
+    readonly state: CogsState;
+    readonly type = "state";
+    constructor(state: CogsState);
+}
+export declare class CogsIncomingEvent<CogsEvent extends DeepReadonly<PluginManifestEventJson> | PluginManifestEventJson> extends Event {
+    readonly name: CogsEvent['name'];
+    readonly value: ManifestTypes.TypeFromCogsValueType<CogsEvent['value']>;
+    readonly type = "event";
+    constructor(name: CogsEvent['name'], value: ManifestTypes.TypeFromCogsValueType<CogsEvent['value']>);
+}
+/**
+ * Allows CogsIncomingEvent of each supported value type
+ */
+export type CogsIncomingEventTypes<CogsEvent extends DeepReadonly<PluginManifestEventJson> | PluginManifestEventJson> = CogsEvent extends unknown ? CogsIncomingEvent<CogsEvent> : never;
+export type CogsConnectionEvent<Manifest extends ManifestTypes.PluginManifest> = CogsConnectionOpenEvent | CogsConnectionCloseEvent | CogsMessageEvent | CogsConfigChangedEvent<ManifestTypes.ConfigAsObject<Manifest>> | CogsStateChangedEvent<Partial<ManifestTypes.StateAsObject<Manifest>>> | CogsIncomingEventTypes<ManifestTypes.EventsFromCogs<Manifest>>;