@stinkycomputing/sesame-api-client 1.5.0 → 1.5.2

package/dist/proto/api.d.ts

@@ -3299,7 +3299,8 @@ export namespace sesame {
                 SOURCE_TRANSPORT_CMD_NEXT = 12,
                 SOURCE_TRANSPORT_CMD_SKIP_NEXT = 13,
                 SOURCE_TRANSPORT_CMD_TRANSITIONS_DISABLED = 14,
-                SOURCE_TRANSPORT_CMD_SET_SCRUBBING = 15
+                SOURCE_TRANSPORT_CMD_SET_SCRUBBING = 15,
+                SOURCE_TRANSPORT_CMD_SET_END_NOTIFICATION = 16
             }
 
             /** SourceTextureSize enum. */
@@ -9442,6 +9443,9 @@ export namespace sesame {
 
                 /** TransportEvent metadata */
                 metadata?: (sesame.v1.common.ITransportMetadata|null);
+
+                /** TransportEvent nearEnd */
+                nearEnd?: (boolean|null);
             }
 
             /** Represents a TransportEvent. */
@@ -9507,6 +9511,9 @@ export namespace sesame {
                 /** TransportEvent metadata. */
                 public metadata?: (sesame.v1.common.ITransportMetadata|null);
 
+                /** TransportEvent nearEnd. */
+                public nearEnd: boolean;
+
                 /**
                  * Creates a new TransportEvent instance using the specified properties.
                  * @param [properties] Properties to set

package/dist/proto/api.js

@@ -8685,6 +8685,7 @@ export const sesame = $root.sesame = (() => {
              * @property {number} SOURCE_TRANSPORT_CMD_SKIP_NEXT=13 SOURCE_TRANSPORT_CMD_SKIP_NEXT value
              * @property {number} SOURCE_TRANSPORT_CMD_TRANSITIONS_DISABLED=14 SOURCE_TRANSPORT_CMD_TRANSITIONS_DISABLED value
              * @property {number} SOURCE_TRANSPORT_CMD_SET_SCRUBBING=15 SOURCE_TRANSPORT_CMD_SET_SCRUBBING value
+             * @property {number} SOURCE_TRANSPORT_CMD_SET_END_NOTIFICATION=16 SOURCE_TRANSPORT_CMD_SET_END_NOTIFICATION value
              */
             sources.SourceTransportCommandType = (function() {
                 const valuesById = {}, values = Object.create(valuesById);
@@ -8704,6 +8705,7 @@ export const sesame = $root.sesame = (() => {
                 values[valuesById[13] = "SOURCE_TRANSPORT_CMD_SKIP_NEXT"] = 13;
                 values[valuesById[14] = "SOURCE_TRANSPORT_CMD_TRANSITIONS_DISABLED"] = 14;
                 values[valuesById[15] = "SOURCE_TRANSPORT_CMD_SET_SCRUBBING"] = 15;
+                values[valuesById[16] = "SOURCE_TRANSPORT_CMD_SET_END_NOTIFICATION"] = 16;
                 return values;
             })();
 
@@ -15099,6 +15101,7 @@ export const sesame = $root.sesame = (() => {
                         case 13:
                         case 14:
                         case 15:
+                        case 16:
                             break;
                         }
                     if (message.value != null && message.hasOwnProperty("value")) {
@@ -15194,6 +15197,10 @@ export const sesame = $root.sesame = (() => {
                     case 15:
                         message.cmdType = 15;
                         break;
+                    case "SOURCE_TRANSPORT_CMD_SET_END_NOTIFICATION":
+                    case 16:
+                        message.cmdType = 16;
+                        break;
                     }
                     if (object.value != null) {
                         if (typeof object.value !== "object")
@@ -16039,6 +16046,7 @@ export const sesame = $root.sesame = (() => {
                         case 13:
                         case 14:
                         case 15:
+                        case 16:
                             break;
                         }
                     if (message.value != null && message.hasOwnProperty("value")) {
@@ -16132,6 +16140,10 @@ export const sesame = $root.sesame = (() => {
                     case 15:
                         message.cmdType = 15;
                         break;
+                    case "SOURCE_TRANSPORT_CMD_SET_END_NOTIFICATION":
+                    case 16:
+                        message.cmdType = 16;
+                        break;
                     }
                     if (object.value != null) {
                         if (typeof object.value !== "object")
@@ -25149,6 +25161,7 @@ export const sesame = $root.sesame = (() => {
                  * @property {number|null} [preroll] TransportEvent preroll
                  * @property {number|null} [postroll] TransportEvent postroll
                  * @property {sesame.v1.common.ITransportMetadata|null} [metadata] TransportEvent metadata
+                 * @property {boolean|null} [nearEnd] TransportEvent nearEnd
                  */
 
                 /**
@@ -25310,6 +25323,14 @@ export const sesame = $root.sesame = (() => {
                  */
                 TransportEvent.prototype.metadata = null;
 
+                /**
+                 * TransportEvent nearEnd.
+                 * @member {boolean} nearEnd
+                 * @memberof sesame.v1.status.TransportEvent
+                 * @instance
+                 */
+                TransportEvent.prototype.nearEnd = false;
+
                 /**
                  * Creates a new TransportEvent instance using the specified properties.
                  * @function create
@@ -25370,6 +25391,8 @@ export const sesame = $root.sesame = (() => {
                         writer.uint32(/* id 17, wireType 0 =*/136).uint32(message.postroll);
                     if (message.metadata != null && Object.hasOwnProperty.call(message, "metadata"))
                         $root.sesame.v1.common.TransportMetadata.encode(message.metadata, writer.uint32(/* id 18, wireType 2 =*/146).fork()).ldelim();
+                    if (message.nearEnd != null && Object.hasOwnProperty.call(message, "nearEnd"))
+                        writer.uint32(/* id 19, wireType 0 =*/152).bool(message.nearEnd);
                     return writer;
                 };
 
@@ -25478,6 +25501,10 @@ export const sesame = $root.sesame = (() => {
                                 message.metadata = $root.sesame.v1.common.TransportMetadata.decode(reader, reader.uint32());
                                 break;
                             }
+                        case 19: {
+                                message.nearEnd = reader.bool();
+                                break;
+                            }
                         default:
                             reader.skipType(tag & 7);
                             break;
@@ -25577,6 +25604,9 @@ export const sesame = $root.sesame = (() => {
                         if (error)
                             return "metadata." + error;
                     }
+                    if (message.nearEnd != null && message.hasOwnProperty("nearEnd"))
+                        if (typeof message.nearEnd !== "boolean")
+                            return "nearEnd: boolean expected";
                     return null;
                 };
 
@@ -25706,6 +25736,8 @@ export const sesame = $root.sesame = (() => {
                             throw TypeError(".sesame.v1.status.TransportEvent.metadata: object expected");
                         message.metadata = $root.sesame.v1.common.TransportMetadata.fromObject(object.metadata);
                     }
+                    if (object.nearEnd != null)
+                        message.nearEnd = Boolean(object.nearEnd);
                     return message;
                 };
 
@@ -25769,6 +25801,7 @@ export const sesame = $root.sesame = (() => {
                         object.preroll = 0;
                         object.postroll = 0;
                         object.metadata = null;
+                        object.nearEnd = false;
                     }
                     if (message.sourceId != null && message.hasOwnProperty("sourceId"))
                         object.sourceId = message.sourceId;
@@ -25827,6 +25860,8 @@ export const sesame = $root.sesame = (() => {
                         object.postroll = message.postroll;
                     if (message.metadata != null && message.hasOwnProperty("metadata"))
                         object.metadata = $root.sesame.v1.common.TransportMetadata.toObject(message.metadata, options);
+                    if (message.nearEnd != null && message.hasOwnProperty("nearEnd"))
+                        object.nearEnd = message.nearEnd;
                     return object;
                 };
 

package/docs/protocol-reference.md

@@ -62,6 +62,19 @@ Request to add a channel to an audio mixer.
 | `channel_config` |  AudioMixerChannel |   |
 
 
+### AudioChannelControlRequest
+
+Per-channel property updates. Absent optional fields are left unchanged.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `channel_id` |  string |   |
+| `level` | optional float |   |
+| `pan` | optional float |   |
+| `plugins` | repeated AudioPluginControlRequest |   |
+
+
 ### AudioChannelPluginStatus
 
 Audio channel plugin status.
@@ -102,6 +115,23 @@ Audio channel status.
 | `plugins` | repeated AudioChannelPluginStatus |   |
 
 
+### AudioControlRequest
+
+Payload for DATA_TYPE_AUDIO_CONTROL frames (transport → server).
+
+The target mixer ID is NOT included here — it is resolved server-side from
+the MetadataRouter binding configured for this source track. This mirrors
+AudioMixerStatus: to build a control message, take an AudioMixerStatus,
+pick the channels you want to change, copy their `id` into `channel_id`,
+and set the desired `level`/`pan`/plugin params. Omit fields you don't
+want to change (optional fields that are absent are left unchanged).
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `channels` | repeated AudioChannelControlRequest |   |
+
+
 ### AudioMixerAddRequest
 
 Request to add a new audio mixer.
@@ -188,6 +218,17 @@ Audio plugin instance.
 | `aux_input_mix_ids` | repeated string |   |
 
 
+### AudioPluginControlRequest
+
+Plugin parameter update within an AudioChannelControlRequest.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `plugin_id` |  string |   |
+| `params` | repeated AudioPluginParam |   |
+
+
 ### AudioPluginParam
 
 Audio plugin parameter.
@@ -272,10 +313,46 @@ Each item represents a single command to execute at a specific time offset.
 | `eject_playlist` |  sesame.v1.sources.EjectPlaylistRequest |   |
 | `callback` |  sesame.v1.common.Callback |   |
 | `set_source_metadata` |  sesame.v1.sources.SourceMetadataSetRequest |   |
+| `set_metadata_bindings` |  SetMetadataBindingsRequest |   |
 | `transaction_id` | optional uint32 |   |
 | `transaction_deps` | repeated uint32 |   |
 
 
+### MetadataBinding
+
+Routes metadata between producers and consumers across transport boundaries.
+
+Outbound route:
+  source_id + metadata_id -> output_id + track_name
+
+Inbound route:
+  source_id + track_name -> target_id + metadata_id
+
+Exactly one route direction should be specified per binding:
+  - outbound: output_id is set, target_id is empty
+  - inbound:  target_id is set, output_id is empty
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `source_id` |  string |   |
+| `metadata_id` |  string |   |
+| `output_id` |  string |   |
+| `track_name` |  string |   |
+| `target_id` |  string |   |
+
+
+### SetMetadataBindingsRequest
+
+Replaces the full metadata routing table.
+Send once after all sources/outputs are configured.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `bindings` | repeated MetadataBinding |   |
+
+
 ---
 
 
@@ -335,6 +412,7 @@ Replaces stringly-typed topic names with compile-time checked values.
 | 2 | `EVENT_TOPIC_TRANSPORT` | Source transport/playback state changes |
 | 3 | `EVENT_TOPIC_CALLBACK` | Client callback events |
 | 4 | `EVENT_TOPIC_JOB` | Job events (export, import, etc.) |
+| 5 | `EVENT_TOPIC_METADATA` | JSON metadata track events (inbound data frames routed to apps) |
 | 6 | `EVENT_TOPIC_RECORDER` | Recorder events |
 
 
@@ -394,7 +472,7 @@ Only one field should be set at a time.
 | `vec4_value` |  Vec4 |   |
 | `string_value` |  string |   |
 | `bool_value` |  bool |   |
-| `int_value` |  int32 |   |
+| `int_value` |  int64 |   |
 
 
 ### PropertyDomain
@@ -849,6 +927,7 @@ Decklink output configuration.
 | `url` |  string |   |
 | `broadcast` |  string |   |
 | `key` |  string |   |
+| `metadata_tracks` | repeated string |   |
 
 
 ### EncodedRecorderOutputConfig
@@ -903,6 +982,7 @@ Type-specific output payloads
 |-------|------|-------------|
 | `channel` |  string |   |
 | `encoder` |  EncoderConfig |   |
+| `metadata_tracks` | repeated string |   |
 
 
 ### EncoderConfig
@@ -1324,6 +1404,20 @@ Error handling:
 
 
 
+### PublishMetadataRequest
+
+Request to publish a metadata payload from an app to all output transports
+that have a binding from this node+metadataId.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `node_id` |  string |   |
+| `metadata_id` |  string |   |
+| `payload` |  bytes |   |
+| `data_type` |  sesame.v1.wire.DataType |   |
+
+
 ### SesameAPIService
 
 Main Sesame API service.
@@ -1342,6 +1436,7 @@ Main Sesame API service.
 | `ListJobs` | .sesame.v1.jobs.JobListRequest | .sesame.v1.jobs.JobList | List jobs. |
 | `RequestKeyframe` | .sesame.v1.outputs.KeyframeRequest | .sesame.v1.common.Empty | Request keyframe from encoder. |
 | `RequestIODeviceList` | .sesame.v1.common.Empty | .sesame.v1.status.IODeviceListResponse | Get list of I/O devices. |
+| `PublishMetadata` | PublishMetadataRequest | .sesame.v1.common.Empty | Publish a JSON metadata payload to all output transports bound to this node+metadataId. Used by apps (e.g. Snigel) to emit state that should be forwarded on MoQ/WebSocket outputs. |
 
 
 ---
@@ -1411,6 +1506,7 @@ Source transport command type.
 | 13 | `SOURCE_TRANSPORT_CMD_SKIP_NEXT` | Skip to next |
 | 14 | `SOURCE_TRANSPORT_CMD_TRANSITIONS_DISABLED` | Disable transitions |
 | 15 | `SOURCE_TRANSPORT_CMD_SET_SCRUBBING` | Set scrubbing mode |
+| 16 | `SOURCE_TRANSPORT_CMD_SET_END_NOTIFICATION` | Set near-end callback threshold (int64 µs before end; 0 = disabled) |
 
 
 ### SourceTransportState
@@ -1515,6 +1611,7 @@ Request to load a playlist into a recorder source.
 | `broadcast` |  string |   |
 | `key` |  string |   |
 | `decode_buffer_frames` |  uint32 |   |
+| `incoming_metadata_tracks` | repeated string |   |
 
 
 ### RTTSourceConfig
@@ -1702,6 +1799,23 @@ Request to update an existing source.
 | `device_name` |  string |   |
 
 
+### TransportControlRequest
+
+Payload for DATA_TYPE_TRANSPORT_CONTROL frames (transport → server).
+
+The target source ID is NOT included here — it is resolved server-side from
+the MetadataRouter binding configured for this source track. This mirrors
+TransportEvent: to build a control message, copy cmd_type and value from
+the desired SourceTransportCommandType. The server will only apply commands
+to the source the track is bound to; it cannot control arbitrary sources.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cmd_type` |  SourceTransportCommandType |   |
+| `value` |  sesame.v1.common.PropValue |   |
+
+
 ### VideoProcessor
 
 Video processor instance configuration.
@@ -1734,6 +1848,7 @@ Video processor parameter (mirrors AudioPluginParam).
 |-------|------|-------------|
 | `channel` |  string |   |
 | `decode_buffer_frames` |  uint32 |   |
+| `incoming_metadata_tracks` | repeated string |   |
 
 
 ---
@@ -1897,6 +2012,7 @@ Event message wrapper.
 | `transport_event` |  TransportEvent |   |
 | `callback_event` |  sesame.v1.common.Callback |   |
 | `job_event` |  sesame.v1.jobs.Job |   |
+| `metadata_event` |  MetadataEvent |   |
 | `recorder_event` |  sesame.v1.recorder.RecorderEvent |   |
 
 
@@ -1922,6 +2038,21 @@ I/O device list response.
 | `devices` | repeated IODeviceItem |   |
 
 
+### MetadataEvent
+
+Fired when a metadata DATA frame arrives on a streaming source and is
+routed to an app consumer via the metadata binding table.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `source_node_id` |  string |   |
+| `track_name` |  string |   |
+| `target_node_id` |  string |   |
+| `metadata_id` |  string |   |
+| `payload` |  bytes |   |
+
+
 ### Status
 
 Overall system status.
@@ -1975,6 +2106,7 @@ Transport event (source playback state change).
 | `preroll` |  uint32 |   |
 | `postroll` |  uint32 |   |
 | `metadata` |  sesame.v1.common.TransportMetadata |   |
+| `near_end` |  bool | True in the single event fired when the end-notification threshold is crossed |
 
 
 ---
@@ -1987,6 +2119,23 @@ Transport event (source playback state change).
 
 
 
+### DataType
+
+Payload type carried in a FRAME_TYPE_DATA frame.
+The frame payload bytes are a serialized protobuf message of the indicated
+type, or raw UTF-8 JSON for DATA_TYPE_JSON.
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0 | `DATA_TYPE_UNSPECIFIED` |  |
+| 1 | `DATA_TYPE_JSON` |  |
+| 2 | `DATA_TYPE_TRANSPORT_STATUS` | payload: sesame.v1.status.TransportEvent (source → transport) |
+| 3 | `DATA_TYPE_AUDIO_STATE` | payload: sesame.v1.audio.AudioMixerStatus (mixer → transport) |
+| 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) |
+
+
 ### FrameType
 
 Type of frame carried on the wire.
@@ -2002,6 +2151,17 @@ Type of frame carried on the wire.
 | 6 | `FRAME_TYPE_DATA` |  |
 
 
+### DataFrameData
+
+Header data for FRAME_TYPE_DATA frames.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `data_type` |  DataType |   |
+| `track_name` |  string |   |
+
+
 ### FrameHeader
 
 Header for every websocket / MoQ frame.
@@ -2013,6 +2173,7 @@ Serialized with a 4-byte little-endian size prefix on the wire.
 | `type` |  FrameType |   |
 | `routing_metadata` |  string |   |
 | `media` |  MediaFrameData |   |
+| `data` |  DataFrameData |   |
 
 
 ### MediaCodecData
@@ -2156,7 +2317,12 @@ Properties are set via `PropertySetRequest` or animated via `PropertyAnimateRequ
 
 ### Audio Mixer Domain (`domain.audio_mixer_id`)
 
-Address format: `channel_id` for channel properties, `channel_id/plugin_id` for plugin parameters.
+**Address field** identifies the target within the mixer:
+
+- Channel property — set `address` to the channel ID (e.g. `"video-1"` or `"snigel1-pgm1/audio_mixer_0"`).
+- Plugin parameter — set `address` to `"<channel_id>::<plugin_id>"` and `property` to the numeric param ID as a string (e.g. `"0"`, `"3"`).
+
+The server disambiguates these two cases by whether `address` contains the `::` delimiter: if it does, the address is split into channel ID and plugin ID, and `property` is parsed as a numeric param ID; otherwise the full `address` string is used as the channel ID for a named channel property.
 
 | Property | Type | Description |
 |----------|------|-------------|
@@ -2165,7 +2331,9 @@ Address format: `channel_id` for channel properties, `channel_id/plugin_id` for
 | `mute` | bool | Mute channel |
 | `source_channels` | vec4 | Source channel routing |
 | `source_id` | string | Source ID |
-| `<param_id>` | float | Plugin parameter (numeric ID as string) |
+| `<param_id>` | float | Plugin parameter — `address` must be `channel_id::plugin_id`, `property` is the numeric param ID |
+
+**Level animation:** use `propertyAnimate` with `ANIM_MODE_STATE_FROM` to fade from the current level. For an instant cut (no transition), `propertySet` is preferred — a zero-duration `propertyAnimate` is clamped to 1 ms by the server rather than producing an instant cut.
 
 ### Source Domain (`domain.source_id`)
 
@@ -2192,7 +2360,7 @@ client.addSubscription(sesame.v1.common.EventTopic.EVENT_TOPIC_JOB, callback);
 | Topic | Event type | When fired |
 |-------|-----------|------------|
 | `EVENT_TOPIC_ERROR` | ErrorEvent | Engine error |
-| `EVENT_TOPIC_TRANSPORT` | TransportEvent | Source playback state change |
+| `EVENT_TOPIC_TRANSPORT` | TransportEvent | Source playback state change; also fired once per playback run with `near_end=true` when the end-notification threshold is crossed |
 | `EVENT_TOPIC_CALLBACK` | Callback | Client callback command echoed |
 | `EVENT_TOPIC_JOB` | Job | Job lifecycle change + progress (~2 Hz) |
 | `EVENT_TOPIC_RECORDER` | RecorderEvent | Recorder online/offline |

package/package.json

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