@stinkycomputing/sesame-api-client 1.8.0 → 1.9.0-alpha.1

package/dist/sesame-wire-protocol.d.ts

@@ -12,6 +12,11 @@ export declare const FrameHeader: typeof sesame.v1.wire.FrameHeader;
 export type IMediaCodecData = sesame.v1.wire.IMediaCodecData;
 export declare const MediaCodecData: typeof sesame.v1.wire.MediaCodecData;
 export declare const CodecType: typeof sesame.v1.common.CodecType;
+export type ISideData = sesame.v1.sidedata.ISideData;
+export type ISideDataSet = sesame.v1.sidedata.ISideDataSet;
+export type IAtlasLayout = sesame.v1.sidedata.IAtlasLayout;
+export type IAtlasEntry = sesame.v1.sidedata.IAtlasEntry;
+export declare const SideData: typeof sesame.v1.sidedata.SideData;
 export interface ParsedFrame {
     valid: boolean;
     header: sesame.v1.wire.FrameHeader | null;
@@ -59,6 +64,35 @@ export type ParsedDataFrame = {
  * ```
  */
 export declare function parseDataFrame(frame: ParsedFrame): ParsedDataFrame | null;
+/**
+ * Side data carried by a media frame, or `null` when the frame carries none,
+ * meaning the set is unchanged since the last frame that carried one. An empty
+ * array means every entry was removed. The set is present on key frames and on
+ * the frame where it changes, so a receiver that starts at a key frame is
+ * always complete.
+ */
+export declare function getSideData(frame: ParsedFrame): ISideData[] | null;
+/**
+ * Tracks the side data set in effect across a media stream.
+ *
+ * @example
+ * ```ts
+ * const tracker = new SideDataTracker();
+ * client.onMediaPacket = (id, frame) => {
+ *   if (tracker.update(frame)) {
+ *     const atlas = tracker.get('sesame.atlas.v1')?.atlas;
+ *     // atlas.entries: [{ sourceId, x, y, width, height }, ...] in atlas.width x atlas.height space
+ *   }
+ * };
+ * ```
+ */
+export declare class SideDataTracker {
+    private entries;
+    /** Feed every media frame in order; returns true when the set changed. */
+    update(frame: ParsedFrame): boolean;
+    get(id: string): ISideData | undefined;
+    all(): ISideData[];
+}
 /**
  * Build a ready-to-send wire frame carrying an `AudioControlRequest`.
  *

package/dist/sesame-wire-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sesame-wire-protocol.d.ts","sourceRoot":"","sources":["../src/sesame-wire-protocol.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,eAAO,MAAM,SAAS,iCAA2B,CAAC;AAClD,eAAO,MAAM,QAAQ,gCAA0B,CAAC;AAChD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC;AACvD,eAAO,MAAM,WAAW,mCAA6B,CAAC;AACtD,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC;AAC7D,eAAO,MAAM,cAAc,sCAAgC,CAAC;AAC5D,eAAO,MAAM,SAAS,mCAA6B,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1C,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;CAC5B;AAMD,+EAA+E;AAC/E,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAe,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACpE;IAAE,QAAQ,EAAE,kBAAkB,CAAC;IAAG,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,cAAc,CAAA;CAAE,GAC7F;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAQ,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAA;CAAE,GAC/F;IAAE,QAAQ,EAAE,mBAAmB,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,uBAAuB,CAAA;CAAE,GACzG;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAM,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,mBAAmB,CAAA;CAAE,GACnG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAa,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAE5E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,CAoCzE;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,oBAAoB,GAC5C,UAAU,CAOZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,wBAAwB,GAClD,UAAU,CAOZ;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GAClB,UAAU,CAMZ;AAID,qBAAa,YAAY;IACvB;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,GAAG,UAAU;IAqB9F;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW;CAqB5C"}
+{"version":3,"file":"sesame-wire-protocol.d.ts","sourceRoot":"","sources":["../src/sesame-wire-protocol.ts"],"names":[],"mappings":"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"}

package/docs/protocol-reference.md

@@ -23,6 +23,7 @@ import { sesame } from '@stinkycomputing/sesame-api-client';
 - [sesame/v1/recorder/recorder.proto](#sesame_v1_recorder_recorder-proto)
 - [sesame/v1/rpc/rpc.proto](#sesame_v1_rpc_rpc-proto)
 - [sesame/v1/rpc/service.proto](#sesame_v1_rpc_service-proto)
+- [sesame/v1/sidedata/side_data.proto](#sesame_v1_sidedata_side_data-proto)
 - [sesame/v1/sources/source.proto](#sesame_v1_sources_source-proto)
 - [sesame/v1/status/statistics.proto](#sesame_v1_status_statistics-proto)
 - [sesame/v1/status/status.proto](#sesame_v1_status_status-proto)
@@ -369,6 +370,9 @@ Each item represents a single command to execute at a specific time offset.
 | `update_encoder` |  sesame.v1.outputs.EncoderUpdateRequest |  |
 | `remove_encoder` |  sesame.v1.outputs.EncoderRemoveRequest |  |
 | `take_playlist` |  sesame.v1.sources.TakePlaylistRequest | Recorder direct take commands |
+| `output_control` |  sesame.v1.outputs.OutputControlRequest | Runtime output stream control (manual SRT outputs) |
+| `set_side_data` |  sesame.v1.compositor.SideDataSetRequest | Compositor side data (per-frame metadata on encoded outputs) |
+| `remove_side_data` |  sesame.v1.compositor.SideDataRemoveRequest |  |
 | `transaction_id` | optional uint32 | Transaction ID for grouping |
 | `transaction_deps` | repeated uint32 | Transaction dependencies |
 
@@ -453,6 +457,7 @@ Used by source/output status models across the API.
 | 4 | `CONNECTION_STATE_DEGRADED` | Running with reduced health |
 | 5 | `CONNECTION_STATE_OFFLINE` | Stopped or unavailable |
 | 6 | `CONNECTION_STATE_ERROR` | Failed with error |
+| 7 | `CONNECTION_STATE_DISABLED` | Intentionally stopped (by config or operator); not an error |
 
 
 ### EventTopic
@@ -706,6 +711,30 @@ Request to set a property value.
 | `value` |  sesame.v1.common.PropValue | Property value |
 
 
+### SideDataRemoveRequest
+
+Request to remove one side data entry from a compositor.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `compositor_id` |  string | Compositor ID |
+| `id` |  string | Side data entry ID |
+
+
+### SideDataSetRequest
+
+Request to attach side data to a compositor's frames.
+Replaces the entry with the same id. Takes effect on the frame the command
+executes on, so batching it with node changes keeps both in sync.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `compositor_id` |  string | Compositor ID |
+| `side_data` |  sesame.v1.sidedata.SideData | Entry to attach |
+
+
 ---
 
 
@@ -987,6 +1016,17 @@ Type of encoder resource.
 | 1 | `ENCODER_TYPE_VIDEO` | Video encoder |
 
 
+### OutputControlAction
+
+Runtime start/stop action for a manually controlled output stream.
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0 | `OUTPUT_CONTROL_ACTION_UNSPECIFIED` | Unspecified (invalid) |
+| 1 | `OUTPUT_CONTROL_ACTION_START` | Start sending |
+| 2 | `OUTPUT_CONTROL_ACTION_STOP` | Stop sending |
+
+
 ### OutputType
 
 Type of output.
@@ -1014,6 +1054,17 @@ Recorder type.
 | 2 | `RECORDER_TYPE_CLIPS` | Clip recorder; not continuously recording, only ingested frames are persisted |
 
 
+### SrtStreamControl
+
+Who starts and stops an SRT output stream.
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0 | `SRT_STREAM_CONTROL_UNSPECIFIED` | Treated as STARTED |
+| 1 | `SRT_STREAM_CONTROL_STARTED` | Streams whenever the engine runs; enforced on every config apply |
+| 2 | `SRT_STREAM_CONTROL_MANUAL` | Operator start/stop via OutputControlRequest; stopped after engine start |
+
+
 ### TimecodeMode
 
 Timecode embedding mode for encoded streams (SEI/metadata OBU).
@@ -1076,6 +1127,7 @@ Decklink output configuration.
 |-------|------|-------------|
 | `url` |  string | SRT URL |
 | `encoder_id` |  string | Shared encoder ID |
+| `control` |  SrtStreamControl | Stream control mode (unset = STARTED) |
 
 
 ### EncodedSuperSlowMoRecorderOutputConfig
@@ -1231,6 +1283,21 @@ Request to add a new output.
 | `system_audio` |  SystemAudioOutputConfig |  |
 
 
+### OutputControlRequest
+
+Runtime start/stop of an output stream. Only valid for SRT outputs configured
+with SRT_STREAM_CONTROL_MANUAL; rejected otherwise.
+When received over the wire protocol (DATA_TYPE_OUTPUT_CONTROL) the target
+output is resolved from the track's metadata binding and `id` is ignored, so
+a remote client can only control the output its track is bound to.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` |  string | Output ID (command API only; ignored on bound wire tracks) |
+| `action` |  OutputControlAction | Action to perform |
+
+
 ### OutputRemoveRequest
 
 Request to remove an output.
@@ -1256,6 +1323,7 @@ Output status information.
 | `buffer_size` |  uint32 | Buffer size (frames) |
 | `srt_stats` | optional sesame.v1.status.SRTSendStatistics | SRT stats (if SRT output) |
 | `encoder_id` |  string | Shared encoder ID used by this output, if any |
+| `control` |  SrtStreamControl | Stream control mode (SRT outputs; UNSPECIFIED elsewhere) |
 
 
 ### OutputUpdateRequest
@@ -1654,6 +1722,71 @@ Main Sesame API service.
 ---
 
 
+## sesame/v1/sidedata/side_data.proto
+
+`sesame.v1.sidedata`
+
+
+
+
+### AtlasEntry
+
+Placement of one source inside an atlas, in output pixels.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `source_id` |  string | Source rendered at this rectangle |
+| `x` |  uint32 | Left edge |
+| `y` |  uint32 | Top edge |
+| `width` |  uint32 | Rectangle width |
+| `height` |  uint32 | Rectangle height |
+| `source_width` |  uint32 | Native picture size of the source before scaling into the rectangle. Filled by the engine; 0 while unknown. May change without a version bump. |
+| `source_height` |  uint32 |  |
+
+
+### AtlasLayout
+
+Where each source sits in an atlas frame. Entries are expressed in the
+width x height coordinate space, normally the compositor size; receivers
+scale by decoded size over layout size when the encoder rescales.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `width` |  uint32 | Coordinate space width |
+| `height` |  uint32 | Coordinate space height |
+| `entries` | repeated AtlasEntry |  |
+
+
+### SideData
+
+One side data entry. Entries are keyed by id so independent producers can
+attach data to the same compositor without touching each other's entries.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` |  string | Namespaced key, e.g. "sesame.atlas.v1" |
+| `version` |  uint64 | Producer-assigned; increases when the entry changes |
+| `atlas` |  AtlasLayout |  |
+| `json` |  string | UTF-8 JSON, application-defined schema |
+| `binary` |  bytes | Opaque bytes |
+
+
+### SideDataSet
+
+Complete set of side data entries in effect for a frame.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `entries` | repeated SideData |  |
+
+
+---
+
+
 ## sesame/v1/sources/source.proto
 
 `sesame.v1.sources`
@@ -2415,6 +2548,9 @@ type, or raw UTF-8 JSON for DATA_TYPE_JSON.
 | 4 | `DATA_TYPE_TRANSPORT_CONTROL` | payload: sesame.v1.sources.TransportControlRequest (transport → source) |
 | 5 | `DATA_TYPE_AUDIO_CONTROL` | payload: sesame.v1.audio.AudioControlRequest (transport → mixer) |
 | 6 | `DATA_TYPE_BINARY` | payload: raw binary bytes (opaque to the wire layer) |
+| 7 | `DATA_TYPE_OUTPUT_STATUS` | payload: sesame.v1.outputs.OutputStatus (output → transport) |
+| 8 | `DATA_TYPE_OUTPUT_CONTROL` | payload: sesame.v1.outputs.OutputControlRequest (transport → output) |
+| 9 | `DATA_TYPE_ENGINE_STATUS` | payload: sesame.v1.status.Status (engine → transport; full monitor status) |
 
 
 ### FrameType
@@ -2486,6 +2622,7 @@ Media-specific fields for VIDEO, AUDIO, MUXED, and DECODER_DATA frames.
 | `pts` |  uint64 | Presentation timestamp in codec_data timebase units |
 | `keyframe` |  bool | True for video key frames |
 | `codec_data` |  MediaCodecData | Codec parameters (may be present on first frame or key frames) |
+| `side_data` |  sesame.v1.sidedata.SideDataSet | Complete side data set in effect from this frame on. Present on key frames and on the frame where the set changes; absent means unchanged since the last frame that carried it. An empty set clears all entries. |
 
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stinkycomputing/sesame-api-client",
-  "version": "1.8.0",
+  "version": "1.9.0-alpha.1",
   "description": "Sesame API client library with protobuf definitions and command list helpers",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",