NvNmos Daemon gRPC API

<thing>_id is a stable NMOS resource UUID derived from the Node seed.
<thing>_handle is an opaque, daemon-local token used only by this API.
name is chosen by the client. A resource name is unique per Node and per side, so a Sender and Receiver may share a name.
IS-08 channel mappings use a separate handle namespace and activation subscription from Senders and Receivers.

After OpenSession, call SubscribeActivations before adding resources and keep the stream open. When session GC is enabled, failure to subscribe within NVNMOSD_SESSION_SUBSCRIBE_TIMEOUT_SEC or resubscribe within NVNMOSD_SESSION_RESUBSCRIBE_TIMEOUT_SEC implicitly closes the session.

A Sender or Receiver transport_file is SDP for TRANSPORT_RTP or MXL flow_def JSON for TRANSPORT_MXL. It must contain the resource name as a=x-nvnmos-name or urn:x-nvnmos:tag:name, respectively.

rpc `AddNode`

Request:

nvnmos.daemon.v1.AddNodeRequest

Response:

nvnmos.daemon.v1.AddNodeResponse

Creates a persistent Node that remains until RemoveNode. Returns ALREADY_EXISTS if the seed or requested HTTP port is already in use, INVALID_ARGUMENT for invalid configuration, or FAILED_PRECONDITION when the requested HTTP port cannot be bound.

rpc `RemoveNode`

Request:

nvnmos.daemon.v1.RemoveNodeRequest

Response:

nvnmos.daemon.v1.Empty

Removes a persistent Node. Returns NOT_FOUND for an unknown seed or FAILED_PRECONDITION for a session-refcounted Node or while sessions remain attached.

rpc `OpenSession`

Request:

nvnmos.daemon.v1.OpenSessionRequest

Response:

nvnmos.daemon.v1.OpenSessionResponse

Opens a session on the Node identified by node_config.seed, creating a session-refcounted Node when the seed is new. Returns INVALID_ARGUMENT for invalid creation configuration, ALREADY_EXISTS when a requested HTTP port belongs to another Node, or FAILED_PRECONDITION when that port cannot be bound.

rpc `CloseSession`

Request:

nvnmos.daemon.v1.CloseSessionRequest

Response:

nvnmos.daemon.v1.Empty

Closes a session and removes its resources. The backing Node is also removed when this was its last session and it is session-refcounted. Returns NOT_FOUND for an unknown or implicitly closed session.

rpc `AddSender`

Request:

nvnmos.daemon.v1.AddSenderRequest

Response:

nvnmos.daemon.v1.AddSenderResponse

Adds a Sender owned by the session. Requires an active activation subscription. Returns FAILED_PRECONDITION without one and INVALID_ARGUMENT for invalid or inconsistent resource configuration. Returns NOT_FOUND for an unknown session and ALREADY_EXISTS for a duplicate Sender name on the Node.

rpc `AddReceiver`

Request:

nvnmos.daemon.v1.AddReceiverRequest

Response:

nvnmos.daemon.v1.AddReceiverResponse

Adds a Receiver owned by the session. Requires an active activation subscription. Returns FAILED_PRECONDITION without one and INVALID_ARGUMENT for invalid or inconsistent resource configuration. Returns NOT_FOUND for an unknown session and ALREADY_EXISTS for a duplicate Receiver name on the Node.

rpc `RemoveResource`

Request:

nvnmos.daemon.v1.RemoveResourceRequest

Response:

nvnmos.daemon.v1.Empty

Removes a Sender or Receiver owned by the session. Returns NOT_FOUND if the session is unknown or does not own the resource handle.

rpc `SubscribeActivations`

Request:

nvnmos.daemon.v1.SubscribeActivationsRequest

Response:

nvnmos.daemon.v1.ActivationEvent

Streams pending IS-05 activations for resources owned by the session. Keep one stream open for the session lifetime and acknowledge every event; for an immediate activation, the controller request remains pending until AckActivation. A scheduled activation occurs after that request has already completed. Returns NOT_FOUND for an unknown session or ALREADY_EXISTS if a stream is already active.

rpc `AckActivation`

Request:

nvnmos.daemon.v1.AckActivationRequest

Response:

nvnmos.daemon.v1.Empty

Completes a pending IS-05 activation and, on success, updates the NMOS state. For an immediate activation, the result is returned to the IS-05 controller; a scheduled activation occurs after the controller request has already completed. Returns NOT_FOUND unless the activation is pending for this session.

rpc `SyncResourceState`

Request:

nvnmos.daemon.v1.SyncResourceStateRequest

Response:

nvnmos.daemon.v1.Empty

Updates NMOS state after a client-originated data-plane change. A present transport_file activates the resource; absence deactivates it. Returns NOT_FOUND if the session does not own the resource or INVALID_ARGUMENT if the state change is invalid.

rpc `AddChannelMapping`

Request:

nvnmos.daemon.v1.AddChannelMappingRequest

Response:

nvnmos.daemon.v1.AddChannelMappingResponse

Adds an audio channel mapping owned by the session. Requires an active channel-mapping activation subscription; otherwise FAILED_PRECONDITION. Returns NOT_FOUND for an unknown session, ALREADY_EXISTS for a duplicate name, or INVALID_ARGUMENT for invalid geometry.

rpc `RemoveChannelMapping`

Request:

nvnmos.daemon.v1.RemoveChannelMappingRequest

Response:

nvnmos.daemon.v1.Empty

Removes an audio channel mapping owned by the session. Returns NOT_FOUND if the session is unknown or does not own the channel-mapping handle.

rpc `SyncChannelMappingState`

Request:

nvnmos.daemon.v1.SyncChannelMappingStateRequest

Response:

nvnmos.daemon.v1.Empty

Updates one output after a client-originated channel-mapping change. Returns NOT_FOUND if the session does not own the channel mapping or INVALID_ARGUMENT if the active map is invalid.

rpc `SubscribeChannelMappingActivations`

Request:

nvnmos.daemon.v1.SubscribeChannelMappingActivationsRequest

Response:

nvnmos.daemon.v1.ChannelMappingActivationEvent

Streams pending IS-08 activations for channel mappings owned by the session. Returns NOT_FOUND for an unknown session or ALREADY_EXISTS if a stream is already active.

rpc `AckChannelMappingActivation`

Request:

nvnmos.daemon.v1.AckChannelMappingActivationRequest

Response:

nvnmos.daemon.v1.Empty

Completes a pending IS-08 activation. Returns NOT_FOUND unless the activation is pending for this session.

message Empty nvnmosd.proto

Empty response for RPCs that return no data.

	Field	Type	Description

message NodeConfig nvnmosd.proto

Configuration used when creating a Node. Unset fields use daemon defaults.

	Field	Type	Description
1	seed	`string`	Seed used to derive stable NMOS UUIDs. Must be non-empty.
2	host_name	`string`	NMOS host name. Empty asks libnvnmos to autodetect it.
3	host_addresses	`repeated string`	NMOS host addresses. Empty asks libnvnmos to autodetect them.
4	http_port	`uint32`	TCP port for libnvnmos's NMOS HTTP APIs. `0` (the default) asks the daemon to allocate from `NVNMOSD_HTTP_PORT_MIN`..`NVNMOSD_HTTP_PORT_MAX`. Non-zero selects an explicit port; the daemon rejects the create when the port is already assigned to another Node or not bindable on the host. Honoured only when this RPC creates the Node; ignored when attaching to an existing Node (same `seed`).
5	label	`string`	Label for the Node. Empty falls back to a libnvnmos-synthesised value, using `asset_tags` when present.
6	description	`string`	Description for the Node. Empty falls back to a libnvnmos-synthesised value, using `asset_tags` when present.
7	asset_tags	`nvnmos.daemon.v1.AssetConfig`	Optional BCP-002-02 Asset Distinguishing Information. See `AssetConfig` for partial-fill semantics.
8	network_services	`nvnmos.daemon.v1.NetworkServicesConfig`	Optional network-services overrides. Unset means "use DNS-SD based on `host_name`".

message AssetConfig nvnmosd.proto

BCP-002-02 Asset Distinguishing Information. Either supply all four fields (with functions non-empty) or omit the whole submessage — the daemon rejects a partially-filled AssetConfig with INVALID_ARGUMENT. An entirely-default AssetConfig (all strings empty, no functions) is treated as absent.

	Field	Type	Description
1	manufacturer	`string`	Asset manufacturer.
2	product	`string`	Asset product name.
3	instance_id	`string`	Asset instance identifier.
4	functions	`repeated string`	Functions performed by this asset. Must be non-empty when configured.

message NetworkServicesConfig nvnmosd.proto

Overrides for NMOS discovery and fixed Registration or System APIs.

	Field	Type	Description
1	domain	`string`	DNS domain; use "local" to force mDNS. Empty for automatic.
2	registration_address	`string`	Host name or IP of a fixed IS-04 Registration API. When set, DNS-SD is disabled and the Registration API below is used directly. Empty falls back to DNS-SD discovery.
3	registration_port	`uint32`	Port for the fixed IS-04 Registration API. 0 selects the protocol default (80 for HTTP).
4	registration_version	`string`	Version of the fixed IS-04 Registration API. Empty selects the Node's default (`v1.3`).
5	system_address	`string`	Host name or IP of a fixed IS-09 System API. Honoured only when `registration_address` is also set. Empty disables IS-09.
6	system_port	`uint32`	Port for the fixed IS-09 System API. 0 selects the protocol default (80 for HTTP).
7	system_version	`string`	Version of the fixed IS-09 System API. Empty selects the Node's default (`v1.0`).

message AddNodeRequest nvnmosd.proto

Request to create a persistent Node.

	Field	Type	Description
1	node_config	`nvnmos.daemon.v1.NodeConfig`	Identity and configuration of the persistent Node.

message AddNodeResponse nvnmosd.proto

Result of creating a persistent Node.

	Field	Type	Description
1	node_id	`string`	NMOS `/self` `id`. Informational; requests identify the Node by seed.
2	http_port	`uint32`	Effective HTTP API port the Node is listening on (after daemon allocation when `node_config.http_port` was `0`).
3	device_id	`string`	Deterministic NMOS Device `id` derived from the Node seed. Informational; requests identify the Node by seed.

message RemoveNodeRequest nvnmosd.proto

Request to remove a persistent Node.

	Field	Type	Description
1	node_seed	`string`	Seed of the persistent Node to remove.

message OpenSessionRequest nvnmosd.proto

Request to attach a new session to a Node.

	Field	Type	Description
1	node_config	`nvnmos.daemon.v1.NodeConfig`	Identifies the Node by seed and configures it if this call creates it. Other fields are ignored when attaching to an existing Node.

message OpenSessionResponse nvnmosd.proto

Session and Node identifiers returned after opening a session.

	Field	Type	Description
1	session_handle	`string`	Opaque handle for subsequent calls in this session.
2	node_id	`string`	NMOS `/self` `id`. Informational; requests identify the Node by seed.
3	created_node	`bool`	Whether this call created a new session-refcounted Node.
4	http_port	`uint32`	Effective HTTP API port of the Node this session is attached to (after daemon allocation when the creating call used `http_port = 0`).

message CloseSessionRequest nvnmosd.proto

Request to close a session and remove everything it owns.

	Field	Type	Description
1	session_handle	`string`	Session to close.

message AddSenderRequest nvnmosd.proto

Request to add a Sender to a session.

	Field	Type	Description
1	session_handle	`string`	Session that will own the Sender.
2	name	`string`	Caller-chosen Sender name. Must be non-empty and match `transport_file`.
3	transport	`nvnmos.daemon.v1.Transport`	Transport family of `transport_file`.
4	transport_file	`string`	Initial configuring transport file: SDP for RTP or `flow_def` JSON for MXL. Its embedded resource name must match `name`.

message AddReceiverRequest nvnmosd.proto

Request to add a Receiver to a session.

	Field	Type	Description
1	session_handle	`string`	Session that will own the Receiver.
2	name	`string`	Caller-chosen Receiver name. Must be non-empty and match `transport_file`.
3	transport	`nvnmos.daemon.v1.Transport`	Transport family of `transport_file`.
4	transport_file	`string`	Initial configuring transport file: SDP for RTP or `flow_def` JSON for MXL. Its embedded resource name must match `name`.

message AddSenderResponse nvnmosd.proto

Identifiers returned after adding a Sender.

	Field	Type	Description
1	resource_handle	`string`	Opaque handle for subsequent calls concerning this Sender.
2	source_id	`string`	Deterministic NMOS Source `id` paired with this Sender. Informational; subsequent RPCs use the handle.
3	flow_id	`string`	Deterministic NMOS Flow `id` paired with this Sender. This is the IS-04 Flow resource `id`, not the MXL `mxl_flow_id` transport parameter. Informational; subsequent RPCs use the handle.
4	sender_id	`string`	Deterministic NMOS Sender `id` derived from the Node seed and name. Informational; subsequent RPCs use the handle.

message AddReceiverResponse nvnmosd.proto

Identifiers returned after adding a Receiver.

	Field	Type	Description
1	resource_handle	`string`	Opaque handle for subsequent calls concerning this Receiver.
2	receiver_id	`string`	Deterministic NMOS Receiver `id` derived from the Node seed and name. Informational; subsequent RPCs use the handle.

message RemoveResourceRequest nvnmosd.proto

Request to remove a Sender or Receiver owned by a session.

	Field	Type	Description
1	session_handle	`string`	Session that owns the resource.
2	resource_handle	`string`	Opaque handle of the resource to remove.

message SubscribeActivationsRequest nvnmosd.proto

Request to open the session's IS-05 activation stream.

	Field	Type	Description
1	session_handle	`string`	Session whose activations to stream.

message ActivationEvent nvnmosd.proto

Pending IS-05 activation or deactivation for one resource.

	Field	Type	Description
1	resource_handle	`string`	Opaque handle of the affected resource.
2	activation_handle	`string`	Opaque activation handle to return in `AckActivation`.
3	transport_file	`optional string`	Effective transport file in the resource's configured format. Absence means deactivation. Symmetric with `SyncResourceStateRequest.transport_file`.
4	side	`nvnmos.daemon.v1.Side`	Whether the affected resource is a Sender or Receiver.

message AckActivationRequest nvnmosd.proto

Result of applying a pending IS-05 activation.

	Field	Type	Description
1	session_handle	`string`	Session that owns the affected resource.
2	activation_handle	`string`	Opaque activation handle from `ActivationEvent`.
3	success	`bool`	Whether the client applied the activation successfully.
4	failure_reason	`string`	Free-form failure reason, surfaced to the IS-05 controller. Set only when `success` is false.

message SyncResourceStateRequest nvnmosd.proto

Client-originated active state for a Sender or Receiver.

	Field	Type	Description
1	session_handle	`string`	Session that owns the resource.
2	resource_handle	`string`	Opaque handle of the affected resource.
3	transport_file	`optional string`	Effective transport file in the resource's configured format. Absence means deactivation. Symmetric with `ActivationEvent.transport_file`.

message AddChannelMappingRequest nvnmosd.proto

Request to add IS-08 Inputs and Outputs as one channel mapping.

	Field	Type	Description
1	session_handle	`string`	Session that will own the channel mapping.
2	name	`string`	Caller-chosen channel-mapping name, unique within the Node. This is not an IS-08 Input or Output ID.
3	inputs	`repeated nvnmos.daemon.v1.ChannelMappingInput`	IS-08 Inputs to add.
4	outputs	`repeated nvnmos.daemon.v1.ChannelMappingOutput`	IS-08 Outputs to add.

message AddChannelMappingResponse nvnmosd.proto

Handle and effective IS-08 IDs returned after adding a channel mapping.

	Field	Type	Description
1	channelmapping_handle	`string`	Opaque handle for subsequent calls concerning this channel mapping.
2	input_ids	`repeated string`	Effective IS-08 input IDs after assigning defaults for empty IDs.
3	output_ids	`repeated string`	Effective IS-08 output IDs after assigning defaults for empty IDs.

message RemoveChannelMappingRequest nvnmosd.proto

Request to remove a channel mapping owned by a session.

	Field	Type	Description
1	session_handle	`string`	Session that owns the channel mapping.
2	channelmapping_handle	`string`	Opaque handle of the channel mapping to remove.

message ChannelMappingInput nvnmosd.proto

IS-08 Input geometry.

	Field	Type	Description
1	id	`string`	IS-08 input ID. Empty requests an assigned default.
2	name	`string`	IS-08 `/properties` name, independent of the channel-mapping name.
3	description	`string`	IS-08 `/properties` description.
4	channel_labels	`repeated string`	IS-08 channel labels. Must be non-empty.
5	parent_name	`string`	Caller-chosen Receiver name when `parent_type` is `RECEIVER`, or Sender name whose derived Source is used when it is `SOURCE`. Empty produces a null `/parent`.
6	parent_type	`nvnmos.daemon.v1.ChannelMappingParentType`	Parent resource type. Ignored when `parent_name` is empty.
7	reordering	`bool`	Reordering capability. Ignored when `block_size` is zero.
8	block_size	`uint32`	Block size. Zero selects a block size of one with reordering enabled.

message ChannelMappingOutput nvnmosd.proto

IS-08 Output geometry.

	Field	Type	Description
1	id	`string`	IS-08 output ID. Empty requests an assigned default.
2	name	`string`	IS-08 `/properties` name, independent of the channel-mapping name.
3	description	`string`	IS-08 `/properties` description.
4	channel_labels	`repeated string`	IS-08 channel labels. Must be non-empty.
5	sender_name	`string`	Caller-chosen Sender name used for IS-04 linkage. Empty produces a null `/sourceid`.
6	routable_inputs	`repeated string`	IS-08 output `/caps/routable_inputs`. Empty is unrestricted; an empty string entry permits an unrouted channel.

message ActiveMapEntry nvnmosd.proto

Route for one output channel in a dense IS-08 active map. Entry index i describes output channel i.

	Field	Type	Description
1	input_id	`optional string`	IS-08 Input ID. Absence means the output channel is unrouted.
2	input_channel	`optional uint32`	Input channel index. Defaults to zero when routed and is ignored when `input_id` is absent.

message SyncChannelMappingStateRequest nvnmosd.proto

Client-originated active map for one IS-08 Output.

	Field	Type	Description
1	session_handle	`string`	Session that owns the channel mapping.
2	channelmapping_handle	`string`	Opaque handle of the channel mapping.
3	output_id	`string`	IS-08 Output ID being updated.
4	active_map	`repeated nvnmos.daemon.v1.ActiveMapEntry`	Dense active map with one entry per output channel.

message SubscribeChannelMappingActivationsRequest nvnmosd.proto

Request to open the session's IS-08 activation stream.

	Field	Type	Description
1	session_handle	`string`	Session whose channel-mapping activations to stream.

message ChannelMappingActivationEvent nvnmosd.proto

Pending IS-08 activation for one Output.

	Field	Type	Description
1	channelmapping_handle	`string`	Opaque handle of the affected channel mapping.
2	activation_handle	`string`	Opaque activation handle to return in `AckChannelMappingActivation`.
3	output_id	`string`	IS-08 Output ID being activated.
4	active_map	`repeated nvnmos.daemon.v1.ActiveMapEntry`	Dense active map with one entry per output channel.

message AckChannelMappingActivationRequest nvnmosd.proto

Result of applying a pending IS-08 activation.

	Field	Type	Description
1	session_handle	`string`	Session that owns the affected channel mapping.
2	activation_handle	`string`	Opaque activation handle from `ChannelMappingActivationEvent`.
3	success	`bool`	Whether the client applied the activation successfully.
4	failure_reason	`string`	Free-form failure reason returned to the IS-08 controller. Set only when `success` is false.

enum Transport nvnmosd.proto

Transport family carried by a resource's transport_file. UNSPECIFIED is the proto3 zero value and is an error from a client.

Name	Number	Description
`TRANSPORT_UNSPECIFIED`	0	No transport selected. Invalid in client requests.
`TRANSPORT_RTP`	1	RTP/UDP transport described by SDP.
`TRANSPORT_MXL`	2	MXL transport described by `flow_def` JSON.

enum Side nvnmosd.proto

Identifies a resource as either a Sender or a Receiver. Used on ActivationEvent so the client knows which side of the connection the activation applies to without having to consult its own resource_handle table; the daemon already has the information. UNSPECIFIED is the proto3 zero value and is never sent by the daemon.

Name	Number	Description
`SIDE_UNSPECIFIED`	0	No resource side selected. Never emitted by the daemon.
`SIDE_SENDER`	1	NMOS Sender.
`SIDE_RECEIVER`	2	NMOS Receiver.

enum ChannelMappingParentType nvnmosd.proto

Type of the IS-04 resource linked from an IS-08 Input /parent.

Name	Number	Description
`CHANNEL_MAPPING_PARENT_TYPE_RECEIVER`	0	Link the Input to an NMOS Receiver.
`CHANNEL_MAPPING_PARENT_TYPE_SOURCE`	1	Link the Input to an NMOS Source.

Package nvnmos.daemon.v1

Services

Messages

Enums

Package `nvnmos.daemon.v1`