@stinkycomputing/sesame-api-client 1.5.1 → 1.5.7

package/README.md

@@ -1,433 +1,433 @@
-# @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'
-  { sourceId: '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', targetId: '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`.
-
-### Sending Binary Data
-
-Send opaque binary payloads on a named metadata track:
-
-```typescript
-import { buildBinaryDataFrame } from '@stinkycomputing/sesame-api-client';
-
-const payload = new Uint8Array([0xF0, 0x15, 0x31, /* ... */ 0xF7]);
-ws.send(buildBinaryDataFrame('my-binary-track', payload));
-```
-
----
-
-## 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
+# @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'
+  { sourceId: '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', targetId: '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`.
+
+### Sending Binary Data
+
+Send opaque binary payloads on a named metadata track:
+
+```typescript
+import { buildBinaryDataFrame } from '@stinkycomputing/sesame-api-client';
+
+const payload = new Uint8Array([0xF0, 0x15, 0x31, /* ... */ 0xF7]);
+ws.send(buildBinaryDataFrame('my-binary-track', payload));
+```
+
+---
+
+## 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