@stinkycomputing/sesame-api-client 1.5.0-alpha.1 → 1.5.0-alpha.2

package/README.md

@@ -1,137 +1,422 @@
-# @stinkycomputing/sesame-api-client
-
-TypeScript client library for the Sesame video production server. Provides type-safe protobuf definitions, a WebSocket RPC client with reconnection, and helpers for building command lists.
-
-All websocket traffic uses protobuf wire framing — see [Wire Protocol](#wire-protocol).
-
-## Install
-
-```bash
-npm install @stinkycomputing/sesame-api-client
-```
-
-## Quick Start
-
-```typescript
-import { SesameClient, CommandList } from '@stinkycomputing/sesame-api-client';
-
-const client = new SesameClient(9000);
-
-const cl = new CommandList();
-cl.sourceAdd('my-source', { type: 'file', path: '/path/to/video.mp4' });
-cl.compositorAdd('main', 1920, 1080, false);
-
-await client.execute(cl);
-```
-
-Works in the browser too — the browser entry point bundles `events` and other Node built-ins so `SesameClient`, `RPCClient`, and `WireProtocol` all work without polyfills.
-
-## Protobuf Modules
-
-Types are generated from `.proto` files under `sesame.v1.*`:
-
-```typescript
-import { sesame } from '@stinkycomputing/sesame-api-client';
-```
-
-| Module | Contents |
-|--------|----------|
-| `sesame.v1.wire` | Wire framing (FrameHeader, FrameType, MediaCodecData) |
-| `sesame.v1.common` | Shared types (Empty, Vec4, PropValue, EventTopic) |
-| `sesame.v1.sources` | Source config and transport |
-| `sesame.v1.outputs` | Output config and encoder settings |
-| `sesame.v1.compositor` | Scene graph, nodes, properties, animations |
-| `sesame.v1.audio` | Audio mixer and channels |
-| `sesame.v1.recorder` | Recorder, clips, playlists |
-| `sesame.v1.jobs` | Background export/import jobs |
-| `sesame.v1.status` | Status polling and event subscriptions |
-| `sesame.v1.commands` | Command list items |
-| `sesame.v1.rpc` | RPC message envelope (Request/Response/Event) |
-
-For the complete type reference with every enum value, message field, and property name, see **[Protocol Reference](docs/protocol-reference.md)**.
-
-## Wire Protocol
-
-Every websocket message is framed as:
-
-```
-[4-byte LE header_size][FrameHeader protobuf][payload bytes]
-```
-
-`WireProtocol.serialize` / `WireProtocol.parse` handle this:
-
-```typescript
-import { WireProtocol, sesame } from '@stinkycomputing/sesame-api-client';
-
-// serialize
-const frame = WireProtocol.serialize(
-  { type: sesame.v1.wire.FrameType.FRAME_TYPE_RPC },
-  rpcPayload,
-);
-
-// parse
-const parsed = WireProtocol.parse(incoming);
-if (parsed.valid) {
-  // parsed.header.type, parsed.payload
-}
-```
-
-Frame types: `FRAME_TYPE_RPC`, `FRAME_TYPE_VIDEO`, `FRAME_TYPE_AUDIO`, `FRAME_TYPE_MUXED`, `FRAME_TYPE_DECODER_DATA`, `FRAME_TYPE_DATA`.
-
-## Command List
-
-`CommandList` builds a batch of operations to send in one `execute` call:
-
-```typescript
-const cl = new CommandList();
-
-cl.sourceAdd('cam1', { type: 'decklink', deviceIndex: 0 });
-cl.compositorAdd('main', 1920, 1080, false);
-cl.nodeAdd('main', 'cam1-node', 'source', { sourceId: 'cam1' });
-
-cl.propertySet(
-  { compositor: 'main', node: 'cam1-node' },
-  'transform', 'position',
-  { vecValue: { r: 100, g: 100 } },
-);
-
-cl.transportCommand('cam1', { type: 'play' });
-
-await client.execute(cl);
-```
-
-### Animations
-
-```typescript
-import { CommandList, keyframe, EaseKind, sesame } from '@stinkycomputing/sesame-api-client';
-
-const cl = new CommandList();
-cl.propertyAnimate(
-  { compositor: 'main', node: 'cam1-node' },
-  'cam1-node', 'opacity',
-  sesame.v1.compositor.AnimationChannelEvaluationMode.HOLD,
-  sesame.v1.compositor.AnimationChannelEvaluationMode.HOLD,
-  [
-    keyframe(0,       { floatValue: 0.0 }),
-    keyframe(500000,  { floatValue: 1.0 }, EaseKind.QUADRATIC_INOUT),
-    keyframe(1000000, { floatValue: 0.5 }, EaseKind.CUBIC_IN, EaseKind.CUBIC_OUT),
-  ],
-);
-```
-
-`keyframe(timeUs, value, easingIn?, easingOut?)` — time in microseconds, value is a `PropValue`, easing uses `EaseKind`.
-
-## Bundling
-
-All dependencies (`events`, `long`, `protobufjs`) are pure JS — no native modules. The package bundles cleanly with esbuild or similar without any special `external` config.
-
-## Publishing
-
-1. Bump version in `package.json`
-2. `npm run build`
-3. `npm publish --access public` (or `--tag alpha` for prereleases)
-4. `git tag api-client-vX.Y.Z && git push origin api-client-vX.Y.Z`
-
-## License
-
-MIT
+# @stinkycomputing/sesame-api-client
+
+TypeScript client library for the Sesame video production server. Provides type-safe protobuf definitions, a WebSocket RPC client with automatic reconnection, and helpers for building command lists, parsing data frames, and sending remote control messages.
+
+## Install
+
+```bash
+npm install @stinkycomputing/sesame-api-client
+```
+
+Works in Node.js and the browser. The browser entry point bundles `events` and other Node built-ins — no polyfills needed.
+
+---
+
+## Quick Start
+
+```typescript
+import { SesameClient, CommandList } from '@stinkycomputing/sesame-api-client';
+
+const client = new SesameClient(9000); // port, or a full ws:// URL
+
+const cl = new CommandList();
+cl.sourceAdd('cam1', { file: { url: '/path/to/video.mp4' } });
+cl.compositorAdd('main', 1920, 1080, false);
+cl.nodeAdd('cam1-node', {
+  compositorId: 'main',
+  parentAddress: '',
+  nodeType: 'source',
+});
+
+await client.execute(cl);
+```
+
+---
+
+## SesameClient
+
+```typescript
+const client = new SesameClient(9000);
+// or with a custom URL:
+const client = new SesameClient('ws://192.168.1.10:9000/api');
+```
+
+The client auto-connects and auto-reconnects. Listen for connection state changes:
+
+```typescript
+client.on('connected',    () => console.log('ready'));
+client.on('disconnected', () => console.log('lost connection'));
+```
+
+| Member | Description |
+|--------|-------------|
+| `client.execute(cl)` | Send a `CommandList` to the server |
+| `client.isConnected()` | Current connection state |
+| `client.disconnect()` | Close the connection |
+| `client.status` | [`StatusApi`](#statusapi) instance |
+| `client.recorder` | [`RecorderApi`](#recorderapi) instance |
+| `client.jobs` | `JobsApi` instance |
+
+---
+
+## Command List
+
+`CommandList` builds a batch of operations sent in a single `execute` call. All methods are chainable and accept an optional `timeOffsetMs` to schedule commands relative to the current frame.
+
+### Sources
+
+```typescript
+const cl = new CommandList();
+
+// File source
+cl.sourceAdd('clip1', { file: { url: '/clips/a.mp4' } });
+
+// Decklink capture
+cl.sourceAdd('sdi-in', { decklink: { deviceIndex: 0, videoFormat: DecklinkVideoFormat.HD_1080i_50 } });
+
+// WebSocket ingest
+cl.sourceAdd('ws-in', { websocket: { channel: 'my-channel' } });
+
+// MoQ ingest
+cl.sourceAdd('moq-in', { moq: { url: 'https://relay.example', broadcast: 'feed', key: '' } });
+
+cl.sourceRemove('clip1');
+```
+
+### Compositor
+
+```typescript
+cl.compositorAdd('main', 1920, 1080, false);
+
+cl.nodeAdd('bg', { compositorId: 'main', parentAddress: '', nodeType: 'source' });
+cl.nodeAdd('fg', { compositorId: 'main', parentAddress: '', nodeType: 'source' });
+
+cl.nodeRemove('main', 'fg');
+cl.compositorRemove('main');
+```
+
+### Outputs
+
+```typescript
+cl.outputAdd('stream', {
+  encoder: { width: 1920, height: 1080, fps: 50, preset: 0, bitrateKbps: 8000 },
+  websocket: { channel: 'live-out' },
+});
+
+cl.outputUpdate('stream', { /* updated config */ });
+cl.outputRemove('stream');
+```
+
+### Audio Mixers
+
+```typescript
+import { sesame } from '@stinkycomputing/sesame-api-client';
+const { AUDIO_MIXER_CHANNEL_TYPE_STEREO } = sesame.v1.audio.AudioMixerChannelType;
+
+cl.audioMixerAdd('mix1', {
+  outputType: AUDIO_MIXER_CHANNEL_TYPE_STEREO,
+  order: 0,
+  channels: [
+    { id: 'ch1', sourceId: 'cam1', channelType: AUDIO_MIXER_CHANNEL_TYPE_STEREO,
+      sourceChannels: [0, 1], level: 1.0, pan: 0.0, plugins: [] },
+  ],
+});
+
+cl.audioMixerChannelAdd('mix1', { id: 'ch2', sourceId: 'cam2', /* ... */ });
+cl.audioMixerChannelRemove('mix1', 'ch2');
+cl.audioMixerRemove('mix1');
+```
+
+### Properties
+
+Property names are type-checked against a generated registry — TypeScript will autocomplete valid names and value shapes.
+
+```typescript
+// Compositor property (typed)
+cl.propertySet({ compositorId: 'main' }, 'cam1-node', 'transform/position', { vecValue: { r: 100, g: 200 } });
+
+// Audio mixer property
+cl.propertySet({ audioMixerId: 'mix1' }, 'ch1', 'level', { floatValue: 0.8 });
+
+// Source property
+cl.propertySet({ sourceId: 'cam1' }, '', 'decoder/buffer_frames', { intValue: 4 });
+```
+
+### Transport Commands
+
+```typescript
+cl.transportCommand('cam1', { type: 'play' });
+cl.transportCommand('cam1', { type: 'pause' });
+cl.transportCommand('cam1', { type: 'seek', value: 5_000_000 }); // microseconds
+cl.transportCommand('cam1', { type: 'next_playlist_clip' });
+```
+
+Available types: `play`, `pause`, `stop`, `seek`, `seek_usertime`, `jog`, `live`, `set_recorder`, `load_playlist`, `eject_playlist`, `load_clip`, `set_metadata`, `take`, `pre_roll`, `post_roll`, `next_playlist_clip`, `skip_next_playlist_clip`, `transitions_disabled`, `set_scrubbing`.
+
+### Playlists
+
+```typescript
+cl.playlistLoad('cam1', {
+  id: 'my-playlist',
+  duration: 0,
+  clips: [
+    { id: 1, recorderId: 'recorder1', speed: 1, transitionTimeUs: 0,
+      startTimeUs: 0, endTimeUs: 10_000_000, audioRouting: [] },
+  ],
+});
+
+cl.playlistEject('cam1');
+```
+
+### Animations
+
+```typescript
+import { CommandList, keyframe, EaseKind, sesame } from '@stinkycomputing/sesame-api-client';
+const { HOLD } = sesame.v1.compositor.AnimationChannelEvaluationMode;
+
+cl.propertyAnimate(
+  { compositorId: 'main' }, 'cam1-node', 'opacity', HOLD, HOLD,
+  [
+    keyframe(0,         { floatValue: 0.0 }),
+    keyframe(500_000,   { floatValue: 1.0 }, EaseKind.QUADRATIC_INOUT),
+    keyframe(1_000_000, { floatValue: 0.5 }, EaseKind.CUBIC_IN, EaseKind.CUBIC_OUT),
+  ],
+);
+```
+
+`keyframe(timeUs, value, easingIn?, easingOut?)` — time in microseconds.
+
+### Metadata Bindings
+
+Wire output tracks to node capabilities for remote state / control. See [Data Frames](#data-frames) for the other side.
+
+```typescript
+cl.setMetadataBindings([
+  // Push AudioMixerStatus from 'mix1' out on the 'audio-state' track of output 'ws-out'
+  { sourceNodeId: 'mix1', metadataId: 'audio-state', outputId: 'ws-out', trackName: 'audio-state' },
+  // Route incoming 'audio-ctrl' track on source 'ws-in' → mixer 'mix1'
+  { sourceId: 'ws-in', trackName: 'audio-ctrl', targetNodeId: 'mix1', metadataId: 'audio-control' },
+]);
+```
+
+---
+
+## Data Frames
+
+`FRAME_TYPE_DATA` frames carry typed protobuf payloads over output WebSocket/MoQ tracks. Use `parseDataFrame` to decode incoming frames without manually inspecting `data_type`.
+
+### Receiving (output stream → client)
+
+```typescript
+import { WireProtocol, parseDataFrame } from '@stinkycomputing/sesame-api-client';
+
+ws.addEventListener('message', async (evt) => {
+  const bytes = new Uint8Array(await evt.data.arrayBuffer());
+  const frame = WireProtocol.parse(bytes);
+  const data  = parseDataFrame(frame);
+  if (!data) return; // not a DATA frame
+
+  switch (data.dataType) {
+    case 'audio-state':
+      // data.status: sesame.v1.audio.AudioMixerStatus
+      console.log(data.trackName, data.status.id, data.status.vu);
+      break;
+    case 'transport-status':
+      // data.event: sesame.v1.status.TransportEvent
+      console.log(data.event.state, data.event.positionUs);
+      break;
+    case 'json':
+      console.log(data.json); // parsed JS object
+      break;
+  }
+});
+```
+
+| `dataType` | Payload type | Direction |
+|------------|-------------|-----------|
+| `'json'` | `unknown` (parsed JSON) | server → client |
+| `'transport-status'` | `sesame.v1.status.TransportEvent` | server → client |
+| `'audio-state'` | `sesame.v1.audio.AudioMixerStatus` | server → client |
+| `'transport-control'` | `sesame.v1.sources.TransportControlRequest` | client → server |
+| `'audio-control'` | `sesame.v1.audio.AudioControlRequest` | client → server |
+
+### Sending Remote Control (source stream → server)
+
+Send control frames over a WebSocket **source** connection (inbound to the server). The server resolves the target node from the metadata binding — no ID is needed in the payload.
+
+```typescript
+import { buildAudioControlFrame, buildTransportControlFrame, sesame } from '@stinkycomputing/sesame-api-client';
+
+// Adjust a mixer channel level and pan
+ws.send(buildAudioControlFrame('audio-ctrl', {
+  channels: [
+    { channelId: 'ch1', level: 0.8, pan: -0.2 },
+  ],
+}));
+
+// Adjust a plugin parameter on a channel
+ws.send(buildAudioControlFrame('audio-ctrl', {
+  channels: [{
+    channelId: 'ch1',
+    plugins: [{ pluginId: 'eq1', params: [{ id: 3, floatValue: 200.0 }] }],
+  }],
+}));
+
+// Queue a transport command on a bound source
+ws.send(buildTransportControlFrame('transport-ctrl', {
+  cmdType: sesame.v1.sources.SourceTransportCommandType.SOURCE_TRANSPORT_CMD_PLAY,
+}));
+```
+
+`buildAudioControlFrame(trackName, request)` and `buildTransportControlFrame(trackName, request)` both return a ready-to-send `Uint8Array`.
+
+---
+
+## StatusApi
+
+Accessed via `client.status`.
+
+```typescript
+const status = await client.status.getStatus();
+// status: sesame.v1.status.Status — full server state snapshot
+
+const devices = await client.status.getIODevices();
+// devices.devices: list of available capture/output hardware
+```
+
+---
+
+## RecorderApi
+
+Accessed via `client.recorder`.
+
+```typescript
+// Add a clip to a recorder
+await client.recorder.addClip('recorder1', {
+  id: 1, path: '/recordings/clip1.mp4', durationUs: 30_000_000,
+});
+
+// Copy, remove, clear
+await client.recorder.copyClip('recorder1', 1, 2);
+await client.recorder.removeClip('recorder1', 1);
+await client.recorder.removeAllClips('recorder1');
+
+// Fetch all clips
+const clips = await client.recorder.getClips('recorder1');
+
+// Verify clip files on disk (returns list of error strings)
+const errors = await client.recorder.verifyClips('recorder1');
+
+// Set clip metadata
+await client.recorder.setMetadata('recorder1', { /* ITransportMetadata */ });
+```
+
+---
+
+## Event Subscriptions
+
+Subscribe to server-pushed event topics via `addSubscription`:
+
+```typescript
+import { sesame } from '@stinkycomputing/sesame-api-client';
+const { EVENT_TOPIC_TRANSPORT, EVENT_TOPIC_ERROR } = sesame.v1.common.EventTopic;
+
+client.addSubscription(EVENT_TOPIC_TRANSPORT, (topic, event) => {
+  const transport = event.transportEvent;
+  console.log(transport?.state, transport?.positionUs);
+});
+
+client.addSubscription(EVENT_TOPIC_ERROR, (topic, event) => {
+  console.error(event.errorEvent?.message);
+});
+
+// Unsubscribe when done
+client.removeSubscription(EVENT_TOPIC_TRANSPORT, myCallback);
+```
+
+Available topics: `EVENT_TOPIC_TRANSPORT`, `EVENT_TOPIC_ERROR`, `EVENT_TOPIC_CALLBACK`, `EVENT_TOPIC_JOB`, `EVENT_TOPIC_RECORDER`, `EVENT_TOPIC_METADATA`.
+
+---
+
+## Wire Protocol
+
+Every WebSocket message is framed as:
+
+```
+[4-byte LE header_size][FrameHeader protobuf][payload bytes]
+```
+
+`WireProtocol.serialize` / `WireProtocol.parse` handle the framing layer:
+
+```typescript
+import { WireProtocol, FrameType, sesame } from '@stinkycomputing/sesame-api-client';
+
+// Build a frame manually
+const bytes = WireProtocol.serialize(
+  { type: FrameType.FRAME_TYPE_RPC },
+  rpcPayload,
+);
+
+// Parse an incoming frame
+const { valid, header, payload } = WireProtocol.parse(incoming);
+if (valid && header.type === FrameType.FRAME_TYPE_DATA) {
+  // use parseDataFrame() instead — see Data Frames above
+}
+```
+
+Frame types: `FRAME_TYPE_RPC`, `FRAME_TYPE_VIDEO`, `FRAME_TYPE_AUDIO`, `FRAME_TYPE_MUXED`, `FRAME_TYPE_DECODER_DATA`, `FRAME_TYPE_DATA`.
+
+---
+
+## Protobuf Modules
+
+All protobuf types are accessible via the `sesame` namespace:
+
+```typescript
+import { sesame } from '@stinkycomputing/sesame-api-client';
+```
+
+| Module | Key contents |
+|--------|-------------|
+| `sesame.v1.wire` | `FrameHeader`, `FrameType`, `DataType`, `MediaCodecData` |
+| `sesame.v1.common` | `Empty`, `Vec4`, `PropValue`, `EventTopic`, `PropertyDomain` |
+| `sesame.v1.sources` | Source configs, `SourceTransportCommand`, `TransportControlRequest` |
+| `sesame.v1.outputs` | Output configs, `EncoderConfig` |
+| `sesame.v1.compositor` | Scene graph, nodes, properties, animations, `KeyFrame` |
+| `sesame.v1.audio` | `AudioMixerConfig`, `AudioMixerStatus`, `AudioControlRequest` |
+| `sesame.v1.recorder` | `RecorderClip`, `PlaylistItem`, `TransitionType` |
+| `sesame.v1.jobs` | Background export/import jobs |
+| `sesame.v1.status` | `Status`, `Event`, `TransportEvent`, `SubscriptionRequest` |
+| `sesame.v1.commands` | `CommandList`, `CommandListItem`, `MetadataBinding` |
+| `sesame.v1.rpc` | `Message`, `Request`, `Response`, `Event` envelope |
+
+For the complete field and enum reference see **[Protocol Reference](docs/protocol-reference.md)**.
+
+---
+
+## Bundling
+
+All dependencies (`events`, `long`, `protobufjs`) are pure JS — no native modules. Bundles cleanly with esbuild, Vite, webpack, or similar without any special `external` config.
+
+---
+
+## Publishing
+
+```bash
+# Bump version in package.json, then:
+pnpm run publish:api-client        # stable
+pnpm run publish:api-client:alpha  # pre-release (--tag alpha)
+```
+
+Or from this package directly:
+
+```bash
+npm run build
+npm publish --access public [--tag alpha]
+```
+
+---
+
+## License
+
+MIT

package/dist/index.browser.mjs

@@ -24301,9 +24301,74 @@ var import_events2 = __toESM(require_events());
 
 // src/sesame-wire-protocol.ts
 var FrameType = sesame.v1.wire.FrameType;
+var DataType = sesame.v1.wire.DataType;
 var FrameHeader = sesame.v1.wire.FrameHeader;
 var MediaCodecData = sesame.v1.wire.MediaCodecData;
 var CodecType = sesame.v1.common.CodecType;
+function parseDataFrame(frame) {
+  if (!frame.valid || !frame.header || !frame.payload) return null;
+  if (frame.header.type !== sesame.v1.wire.FrameType.FRAME_TYPE_DATA) return null;
+  const d = frame.header.data;
+  if (!d) return null;
+  const trackName = d.trackName ?? "";
+  const payload = frame.payload;
+  try {
+    switch (d.dataType) {
+      case sesame.v1.wire.DataType.DATA_TYPE_JSON: {
+        const text = new TextDecoder().decode(payload);
+        return { dataType: "json", trackName, json: JSON.parse(text) };
+      }
+      case sesame.v1.wire.DataType.DATA_TYPE_TRANSPORT_STATUS:
+        return {
+          dataType: "transport-status",
+          trackName,
+          event: sesame.v1.status.TransportEvent.decode(payload)
+        };
+      case sesame.v1.wire.DataType.DATA_TYPE_AUDIO_STATE:
+        return {
+          dataType: "audio-state",
+          trackName,
+          status: sesame.v1.audio.AudioMixerStatus.decode(payload)
+        };
+      case sesame.v1.wire.DataType.DATA_TYPE_TRANSPORT_CONTROL:
+        return {
+          dataType: "transport-control",
+          trackName,
+          request: sesame.v1.sources.TransportControlRequest.decode(payload)
+        };
+      case sesame.v1.wire.DataType.DATA_TYPE_AUDIO_CONTROL:
+        return {
+          dataType: "audio-control",
+          trackName,
+          request: sesame.v1.audio.AudioControlRequest.decode(payload)
+        };
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+function buildAudioControlFrame(trackName, request) {
+  const payload = sesame.v1.audio.AudioControlRequest.encode(request).finish();
+  return WireProtocol.serialize(
+    {
+      type: sesame.v1.wire.FrameType.FRAME_TYPE_DATA,
+      data: { dataType: sesame.v1.wire.DataType.DATA_TYPE_AUDIO_CONTROL, trackName }
+    },
+    payload
+  );
+}
+function buildTransportControlFrame(trackName, request) {
+  const payload = sesame.v1.sources.TransportControlRequest.encode(request).finish();
+  return WireProtocol.serialize(
+    {
+      type: sesame.v1.wire.FrameType.FRAME_TYPE_DATA,
+      data: { dataType: sesame.v1.wire.DataType.DATA_TYPE_TRANSPORT_CONTROL, trackName }
+    },
+    payload
+  );
+}
 var PREFIX_SIZE = 4;
 var WireProtocol = class {
   /**
@@ -24784,6 +24849,7 @@ export {
   CodecType,
   CommandList,
   ConnectionState,
+  DataType,
   EaseKind,
   Event,
   FrameHeader,
@@ -24798,8 +24864,11 @@ export {
   SesameConnection,
   StatusApi,
   WireProtocol,
+  buildAudioControlFrame,
+  buildTransportControlFrame,
   getLogger,
   log,
+  parseDataFrame,
   sesame,
   setLogger,
   waitForEvent