Connection API documentation

Connection API documentation version v1.1

http://api.example.com/x-nmos/connection/{version}

version: required(v1.1)

Overview

The Connection API is exposed by NMOS Devices as a standard control interface for management of inter-device connnections.

The Connection API URL for an NMOS Device is advertised in the list of controls for that device in the Node API using type: "urn:x-nmos:control:sr-ctrl/{version}". This information is populated into the NMOS registry via the standard registration mechanism, so it is discoverable through the Query API (see NMOS Discovery and Registration specification).

API Structure

The API presents two distinct interfaces. A "bulk" interface for controlling multiple senders/receivers, and a "single" interface to control single devices.

Base

/ get

get

List of modes available from this API - single and bulk. Both are compulsory parts of the spec.

Response

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes the Connection API base resource",
  "title": "Connection API base resource",
  "items": {
    "type": "string",
    "enum": [
      "bulk/",
      "single/"
    ]
  },
  "minItems": 2,
  "maxItems": 2,
  "uniqueItems": true
}

Example:

[
  "bulk/",
  "single/"
]

Bulk control interface

/bulk get

get

Senders / receivers options

Response

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes the Connection API /bulk base resource",
  "title": "Connection API /bulk base resource",
  "items": {
    "type": "string",
    "enum": [
      "senders/",
      "receivers/"
    ]
  },
  "minItems": 2,
  "maxItems": 2,
  "uniqueItems": true
}

Example:

[
  "senders/",
  "receivers/"
]

/bulk/senders get options post

Target for bulk staging of transport parameters.

get

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

post

Allows staging and activation of multiple sender parameters at the same time in a single request.

Request
Response

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes a bulk sender update resource",
  "title": "Bulk sender resource",
  "items": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "id",
      "params"
    ],
    "properties": {
      "id": {
        "description": "ID of the target sender to apply parameters to",
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
      },
      "params": {
        "$ref": "sender-stage-schema.json"
      }
    }
  }
}

Example:

[{
    "id": "0a174530-e3cf-11e6-bf01-fe55135034f3",
    "params": {
      "master_enable": true,
      "activation": {
        "mode": "activate_scheduled_absolute",
        "requested_time": "1496759200:0"
      },
      "transport_params": [{
        "fec_enabled": true,
        "rtcp_enabled": true,
        "rtp_enabled": true
      }, {
        "fec_enabled": true,
        "rtcp_enabled": true,
        "rtp_enabled": true
      }]
    }
  },
  {
    "id": "7a3ebebe-0405-11e7-93ae-92361f002671",
    "params": {
      "master_enable": true,
      "activation": {
        "mode": "activate_scheduled_relative",
        "requested_time": "2:0"
      },
      "transport_params": [{
        "fec_enabled": true
      }, {
        "fec_enabled": true
      }]
    }
  }
]

HTTP status code 200

Gives the status of each of the individual senders after the staging. Will be returned even if individual params did not validate. The response object provides the HTTP status code that would have been returned by each sender had the request been carried out individually.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Describes a response to a bulk activation request",
  "title": "Bulk activation response",
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "id",
      "code"
    ],
    "properties": {
      "id": {
        "description": "ID of a device to be activated",
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
      },
      "code": {
        "description": "HTTP status code that would have resulted from an individual activation on this device",
        "type": "integer",
        "anyOf": [
          { "minimum": 200, "maximum": 299 },
          { "minimum": 400, "maximum": 599 }
        ]
      },
      "error": {
        "description": "Human readable message which is suitable for user interface display, and helpful to the user. Only included if 'code' indicates an error state",
        "type": "string"
      },
      "debug": {
        "description": "Debug information which may assist a programmer working with the API. Only included if 'code' indicates an error state",
        "type": ["null", "string"]
      }
    }
  }
}

Example:

[{
    "id": "0a174530-e3cf-11e6-bf01-fe55135034f3",
    "code": 200
  },
  {
    "id": "7a3ebebe-0405-11e7-93ae-92361f002671",
    "code": 200
  },
  {
    "id": "7a3ec21a-0405-11e7-93ae-92361f002671",
    "code": 200
  },
  {
    "id": "7a3ec3b4-0405-11e7-93ae-92361f002671",
    "code": 400,
    "error": "Un-recognised parameter 'frc_enabled'",
    "debug": "<stack trace>"
  }
]

HTTP status code 400

The body of the request did not validate against the schema (ignoring the content of the params field - these are validated individually by each sender and failures are recorded in the response object for a 200 return).

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

Example:

{
  "code": 400,
  "error": "Request contained invalid JSON",
  "debug": "<stack trace>"
}

/bulk/receivers get options post

Target for bulk uploads of transport parameters.

get

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

post

Allows staging and activation of a subset of multiple receiver parameters at the same time in a single request.

Request
Response

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes a bulk receiver update resource",
  "title": "Bulk receiver resource",
  "items": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "id",
      "params"
    ],
    "properties": {
      "id": {
        "description": "ID of the target receiver to apply parameters to",
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
      },
      "params": {
        "$ref": "receiver-stage-schema.json"
      }
    }
  }
}

Example:

[{
    "id": "0a174530-e3cf-11e6-bf01-fe55135034f3",
    "params": {
      "master_enable": true,
      "activation": {
        "mode": "activate_scheduled_absolute",
        "requested_time": "1496759200:0"
      },
      "transport_params": [{
        "rtp_enabled": true
      }, {
        "rtp_enabled": true
      }],
      "transport_file": {
        "data": "v=0\r\no=- 1496222842 1496222842 IN IP4 172.29.226.25\r\ns=IP Studio Stream\r\nt=0 0\r\nm=video 5010 RTP/AVP 103\r\nc=IN IP4 232.250.98.80/32\r\na=source-filter: incl IN IP4 232.250.98.80 172.29.226.25\r\na=rtpmap:103 raw/90000\r\na=fmtp:103 sampling=YCbCr-4:2:2; width=1920; height=1080; depth=10; interlace; exactframerate=25; colorimetry=BT709; PM=2110GPM; SSN=ST2110-20:2017; TP=2110TPW; \r\na=mediaclk:direct=1876655126 rate=90000\r\na=extmap:1 urn:x-nmos:rtp-hdrext:origin-timestamp\r\na=extmap:2 urn:ietf:params:rtp-hdrext:smpte-tc 3600@90000/25\r\na=extmap:3 urn:x-nmos:rtp-hdrext:flow-id\r\na=extmap:4 urn:x-nmos:rtp-hdrext:source-id\r\na=extmap:5 urn:x-nmos:rtp-hdrext:grain-flags\r\na=extmap:7 urn:x-nmos:rtp-hdrext:sync-timestamp\r\na=extmap:9 urn:x-nmos:rtp-hdrext:grain-duration\r\na=ts-refclk:ptp=IEEE1588-2008:08-00-11-FF-FE-21-E1-B0:0\r\n",
        "type": "application/sdp"
      }
    }
  },
  {
    "id": "7a3ebebe-0405-11e7-93ae-92361f002671",
    "params": {
      "master_enable": true,
      "activation": {
        "mode": "activate_scheduled_relative",
        "requested_time": "2:0"
      },
      "transport_params": [{
        "rtp_enabled": true
      }, {
        "rtp_enabled": true
      }]
    }
  }
]

HTTP status code 200

Gives the status of each of the individual receivers after the staging. Will be returned even if individual parameters in params did not validate. The response object provides the HTTP status code that would have been returned by each receiver had the request been carried out individually.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Describes a response to a bulk activation request",
  "title": "Bulk activation response",
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "id",
      "code"
    ],
    "properties": {
      "id": {
        "description": "ID of a device to be activated",
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
      },
      "code": {
        "description": "HTTP status code that would have resulted from an individual activation on this device",
        "type": "integer",
        "anyOf": [
          { "minimum": 200, "maximum": 299 },
          { "minimum": 400, "maximum": 599 }
        ]
      },
      "error": {
        "description": "Human readable message which is suitable for user interface display, and helpful to the user. Only included if 'code' indicates an error state",
        "type": "string"
      },
      "debug": {
        "description": "Debug information which may assist a programmer working with the API. Only included if 'code' indicates an error state",
        "type": ["null", "string"]
      }
    }
  }
}

Example:

[{
    "id": "0a174530-e3cf-11e6-bf01-fe55135034f3",
    "code": 200
  },
  {
    "id": "7a3ebebe-0405-11e7-93ae-92361f002671",
    "code": 200
  },
  {
    "id": "7a3ec21a-0405-11e7-93ae-92361f002671",
    "code": 200
  },
  {
    "id": "7a3ec3b4-0405-11e7-93ae-92361f002671",
    "code": 400,
    "error": "Un-recognised parameter 'frc_enabled'",
    "debug": "<stack trace>"
  }
]

HTTP status code 400

The body of the request did not validate against the schema (ignoring the content of the params field - these are validated individually by each receiver and failures are recorded in the response object for a 200 return).

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

Example:

{
  "code": 400,
  "error": "Request contained invalid JSON",
  "debug": "<stack trace>"
}

Single control interface

/single get

get

Response

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes the Connection API /single base resource",
  "title": "Connection API /single base resource",
  "items": {
    "type": "string",
    "enum": [
      "senders/",
      "receivers/"
    ]
  },
  "minItems": 2,
  "maxItems": 2,
  "uniqueItems": true
}

Example:

[
  "senders/",
  "receivers/"
]

/single/senders get

get

Sender root

Response

HTTP status code 200

List Available Senders. All UUIDs are appended with / to indicate the ID forms part of the URL for the next layer down.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes the Connection API sender/receiver base resource",
  "title": "Connection API sender/receiver base resource",
  "items": {
    "type": "string",
    "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/$"
  },
  "uniqueItems": true
}

Example:

[
  "c72cca5b-01db-47aa-bb00-03893defbfae/",
  "171d5c80-7fff-4c23-9383-46503eb1c63e/",
  "a2655c48-8a46-4c82-b9bc-98760d59d7f8/"
]

/single/senders/{senderId} get

get

List all the API endpoints for a single sender.

Request
Response

URI Parameters

senderId: required(string)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes the Connection API /single/senders/{senderId} base resource",
  "title": "Connection API /single/senders/{senderId} base resource",
  "items": {
    "type": "string",
    "enum": [
      "constraints/",
      "staged/",
      "active/",
      "transportfile/",
      "transporttype/"
    ]
  },
  "minItems": 5,
  "maxItems": 5,
  "uniqueItems": true
}

Example:

[
  "constraints/",
  "staged/",
  "active/",
  "transportfile/",
  "transporttype/"
]

HTTP status code 404

Returned when the requested Sender ID does not exist.

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/senders/3b8be755-08ff-452b-b217-c9151eb21193

/single/senders/{senderId}/constraints get

get

Lists the constraints for each transport parameter (e.g max/min value, enumerated values etc.) using a very limited subset of JSON schema. Every transport parameter in the staged resource must be represented here. Any minimum/maximum constraints listed here must not allow a wider range of values than those allowed by the core schema. Any enum defined on this endpoint must only contain a subset of the values allowed for that parameter in the core schema. Similarly, pattern constraints must only narrow the allowed values. If the sender does not constrain parameters beyond what is specified in the core schema then the constraints in the core schema should not be duplicated on this endpoint. Where an "auto" mode is allowed in the core schema this mode must always be supported by the sender if the parameter is exposed. If SMPTE 2022-7 is in use, two entries are in the outer array of the resource. The first entry is the constraints for the primary leg. If SMPTE 2022-7 is not in use only one entry should be present in the outer array.

Request
Response

URI Parameters

senderId: required(string)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Used to express the dynamic constraints on transport parameters. These constraints may be set and changed at run time. Parameters must also conform with constraints inferred from the specification. Every transport parameter must have an entry, even if it is only an empty object.",
  "title": "Constraints",
  "anyOf": [
    {
      "type": "array",
      "items": {
        "$ref": "constraints-schema-rtp.json"
      }
    },
    {
      "type": "array",
      "items": {
        "$ref": "constraints-schema-websocket.json"
      }
    },
    {
      "type": "array",
      "items": {
        "$ref": "constraints-schema-mqtt.json"
      }
    },
    {
      "type": "array",
      "items": {
        "description": "Constraints on transport parameters for another transport defined in Transports register of the NMOS Parameter Registers",
        "type": "object",
        "patternProperties": {
          "^[a-zA-Z0-9_]+$": {
            "$ref": "constraint-schema.json#/definitions/constraint"
          }
        }
      }
    }
  ]
}

Examples:

SMPTE2022-7:

[
  {
    "source_ip": {
      "enum": [
        "192.168.7.2",
        "192.168.8.5",
        "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
        "2001:0db8:85a3:0000:0000:8a2e:0370:a24b"
      ]
    },
    "destination_ip": {},
    "source_port": {
      "minimum": 1025,
      "maximum": 65535
    },
    "destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "fec_enabled": {},
    "fec_destination_ip": {},
    "fec_type": {
      "enum": [
        "XOR",
        "Reed-Solomon"
      ]
    },
    "fec_mode": {
      "enum": [
        "1D",
        "2D"
      ]
    },
    "fec_block_width": {
      "minimum": 4,
      "maximum": 200
    },
    "fec_block_height": {
      "minimum": 4,
      "maximum": 200
    },
    "fec1D_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "fec2D_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "fec1D_source_port": {
      "minimum": 1025,
      "maximum": 65535
    },
    "fec2D_source_port": {
      "minimum": 1025,
      "maximum": 65535
    },
    "rtcp_enabled": {},
    "rtcp_destination_ip": {},
    "rtcp_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "rtcp_source_port": {
      "minimum": 1025,
      "maximum": 65535
    },
    "rtp_enabled": {}
  },
  {
    "source_ip": {
      "enum": [
        "192.168.9.2",
        "192.168.10.5",
        "2001:0db8:85a3:0000:0000:8a2e:0370:2bb4",
        "2001:0db8:85a3:0000:0000:8a2e:0370:433f"
      ]
    },
    "destination_ip": {},
    "source_port": {
      "minimum": 1025,
      "maximum": 65535
    },
    "destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "fec_enabled": {},
    "fec_destination_ip": {},
    "fec_type": {
      "enum": [
        "XOR",
        "Reed-Solomon"
      ]
    },
    "fec_mode": {
      "enum": [
        "1D",
        "2D"
      ]
    },
    "fec_block_width": {
      "minimum": 4,
      "maximum": 200
    },
    "fec_block_height": {
      "minimum": 4,
      "maximum": 200
    },
    "fec1D_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "fec2D_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "fec1D_source_port": {
      "minimum": 1025,
      "maximum": 65535
    },
    "fec2D_source_port": {
      "minimum": 1025,
      "maximum": 65535
    },
    "rtcp_enabled": {},
    "rtcp_destination_ip": {},
    "rtcp_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "rtcp_source_port": {
      "minimum": 1025,
      "maximum": 65535
    },
    "rtp_enabled": {}
  }
]

RTPNo2022-7:

[{
  "source_ip": {
    "enum": [
      "192.168.7.2",
      "192.168.8.5",
      "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
      "2001:0db8:85a3:0000:0000:8a2e:0370:a24b"
    ]
  },
  "destination_ip": {},
  "source_port": {
    "minimum": 1025,
    "maximum": 65535
  },
  "destination_port": {
    "minimum": 5000,
    "maximum": 49150
  },
  "fec_enabled": {},
  "fec_destination_ip": {},
  "fec_type": {
    "enum": [
      "XOR",
      "Reed-Solomon"
    ]
  },
  "fec_mode": {
    "enum": [
      "1D",
      "2D"
    ]
  },
  "fec_block_width": {
    "minimum": 4,
    "maximum": 200
  },
  "fec_block_height": {
    "minimum": 4,
    "maximum": 200
  },
  "fec1D_destination_port": {
    "minimum": 5000,
    "maximum": 49150
  },
  "fec2D_destination_port": {
    "minimum": 5000,
    "maximum": 49150
  },
  "fec1D_source_port": {
    "minimum": 1025,
    "maximum": 65535
  },
  "fec2D_source_port": {
    "minimum": 1025,
    "maximum": 65535
  },
  "rtcp_enabled": {},
  "rtcp_destination_ip": {},
  "rtcp_destination_port": {
    "minimum": 5000,
    "maximum": 49150
  },
  "rtcp_source_port": {
    "minimum": 1025,
    "maximum": 65535
  },
  "rtp_enabled": {}
}]

MQTT:

[{
  "destination_host": {},
  "destination_port": {
    "enum": [
      1833,
      8883
    ]
  },
  "broker_topic": {
    "enum": [
      "fixedTopicName1",
      "fixedTopicName2"
    ]
  },
  "broker_protocol": {},
  "broker_authorization": {},
  "connection_status_broker_topic": {
    "enum": [
      "connStatusTopic"
    ]
  }
}]

WebSocketPlusExt:

[{
  "connection_uri": {
    "enum": [
      "ws://172.29.80.65:5476/websocketServer"
    ]
  },
  "connection_authorization": {
    "enum": [
      false
    ]
  },
  "ext_subscription_data": {
    "enum": [
      "fixedConnectionParameter"
    ]
  }
}]

HTTP status code 404

Returned when the requested resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/senders/3b8be755-08ff-452b-b217-c9151eb21193/constraints

/single/senders/{senderId}/staged get options patch

get

Get staged sender transport parameters object. In SMPTE 2022-7 operation element 0 of the transport_params array shall be the parameters applied to the primary leg, and element 1 the secondary leg. There shall only be one element present in transport_params when SMPTE 2022-7 is not in use.

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

patch

Update staged parameters for sender. Note that for activations the mode parameter will return to null once the activation transaction with the client is completed (i.e the response to the PATCH has been sent by the server). In SMPTE 2022-7 operation element 0 of the transport_params array shall be the parameters applied to the primary leg, and element 1 the secondary leg. There shall only be one element present in transport_params when SMPTE 2022-7 is not in use.

Request
Response

URI Parameters

senderId: required(string)

HTTP status code 200

Additionally constrained by the constraints at /constraints

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a sender",
  "title": "Sender resource",
  "additionalProperties": false,
  "required": [
    "receiver_id",
    "master_enable",
    "activation",
    "transport_params"
  ],
  "properties": {
    "receiver_id": {
      "description": "ID of the target Receiver of this Sender. This will be null if the sender is operating in multicast mode, or has not been assigned a receiver in unicast mode, or is sending to a non-NMOS receiver in unicast mode.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "master_enable": {
      "description": "Master on/off control for sender",
      "type": "boolean"
    },
    "activation": {
      "$ref": "activation-response-schema.json"
    },
    "transport_params": {
      "$ref": "sender_transport_params.json"
    }
  }
}

Examples:

Normal:

{
  "receiver_id": "0a174530-e3cf-11e6-bf01-fe55135034f3",
  "master_enable": true,
  "activation": {
    "mode": null,
    "requested_time": null,
    "activation_time": null
  },
  "transport_params": [{
    "source_ip": "172.29.82.23",
    "destination_ip": "172.29.82.95",
    "source_port": 5000,
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_destination_ip": "auto",
    "fec_type": "XOR",
    "fec_mode": "2D",
    "fec_block_width": 50,
    "fec_block_height": 50,
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "fec1D_source_port": 5010,
    "fec2D_source_port": 5012,
    "rtcp_enabled": true,
    "rtcp_destination_ip": "172.29.82.24",
    "rtcp_destination_port": 5008,
    "rtcp_source_port": 5008,
    "rtp_enabled": true
  }, {
    "source_ip": "172.30.82.23",
    "destination_ip": "172.30.82.95",
    "source_port": 5000,
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_destination_ip": "auto",
    "fec_type": "XOR",
    "fec_mode": "2D",
    "fec_block_width": 50,
    "fec_block_height": 50,
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "fec1D_source_port": 5010,
    "fec2D_source_port": 5012,
    "rtcp_enabled": true,
    "rtcp_destination_ip": "172.30.82.24",
    "rtcp_destination_port": 5008,
    "rtcp_source_port": 5008,
    "rtp_enabled": true
  }]
}

Uninitialised:

{
  "receiver_id": null,
  "master_enable": true,
  "activation": {
    "mode": null,
    "requested_time": null,
    "activation_time": null
  },
  "transport_params": [{
    "source_ip": "auto",
    "destination_ip": "auto",
    "source_port": "auto",
    "destination_port": "auto",
    "fec_enabled": false,
    "fec_destination_ip": "auto",
    "fec_type": "XOR",
    "fec_mode": "1D",
    "fec_block_width": 4,
    "fec_block_height": 4,
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "fec1D_source_port": "auto",
    "fec2D_source_port": "auto",
    "rtcp_enabled": false,
    "rtcp_destination_ip": "auto",
    "rtcp_destination_port": "auto",
    "rtcp_source_port": "auto",
    "rtp_enabled": true
  }]
}

HTTP status code 404

Returned when the requested resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/senders/3b8be755-08ff-452b-b217-c9151eb21193/staged

Request
Response

URI Parameters

senderId: required(string)

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a sender",
  "title": "Sender resource",
  "additionalProperties": false,
  "properties": {
    "receiver_id": {
      "description": "ID of the target Receiver of this Sender. This will be null if the sender is operating in multicast mode, or has not been assigned a receiver in unicast mode, or is sending to a non-NMOS receiver in unicast mode.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "master_enable": {
      "description": "Master on/off control for sender",
      "type": "boolean"
    },
    "activation": {
      "$ref": "activation-schema.json"
    },
    "transport_params": {
      "$ref": "sender_transport_params.json"
    }
  }
}

Examples:

immediate-activation:

{
  "receiver_id": null,
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null
  },
  "transport_params": [{
    "source_ip": "192.168.200.10",
    "destination_ip": "232.105.26.177",
    "source_port": 5000,
    "destination_port": 5000,
    "rtp_enabled": true
  }]
}

relative-scheduled-activation:

{
  "receiver_id": null,
  "master_enable": true,
  "activation": {
    "mode": "activate_scheduled_relative",
    "requested_time": "2:0"
  },
  "transport_params": [{
    "source_ip": "192.168.200.10",
    "destination_ip": "232.105.26.177",
    "source_port": 5000,
    "destination_port": 5000,
    "rtp_enabled": true
  }]
}

absolute-scheduled-activation:

{
  "receiver_id": null,
  "master_enable": true,
  "activation": {
    "mode": "activate_scheduled_absolute",
    "requested_time": "1496759200:0"
  },
  "transport_params": [{
    "source_ip": "192.168.200.10",
    "destination_ip": "232.105.26.177",
    "source_port": 5000,
    "destination_port": 5000,
    "rtp_enabled": true
  }]
}

activation-only:

{
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null
  }
}

redundant-streams:

{
  "receiver_id": null,
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null
  },
  "transport_params": [{
      "source_ip": "192.168.200.10",
      "destination_ip": "232.105.26.177",
      "source_port": 5000,
      "destination_port": 5000,
      "rtp_enabled": true
    },
    {
      "source_ip": "192.168.210.10",
      "destination_ip": "232.3.28.144",
      "source_port": 5000,
      "destination_port": 5000,
      "rtp_enabled": true
    }
  ]
}

unicast:

{
  "receiver_id": "0b174530-e3cf-41e6-bf01-fe55135034f3",
  "master_enable": true,
  "activation": {
    "mode": "activate_scheduled_relative",
    "requested_time": "2:0"
  },
  "transport_params": [{
    "source_ip": "192.168.200.10",
    "destination_ip": "192.168.200.15",
    "source_port": 5000,
    "destination_port": 5000,
    "rtp_enabled": true
  }]
}

HTTP status code 200

A 200 response is returned for PATCH requests where no activation has been scheduled, an activation has been cancelled, or an immediate activation has been requested. The response will always contain the full set of parameters in the response schema, and all supported transport parameters. For a request with an immediate activation the API should only return a response once the new transport parameters have been applied to the underlying sender. Note the presence of the extra activation_time parameter in the response. For immediate activation this should be the time the activation actually occurred as an absolute TAI timestamp. If no activation was requested in the PATCH activation_time will be set null.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a sender",
  "title": "Sender resource",
  "additionalProperties": false,
  "required": [
    "receiver_id",
    "master_enable",
    "activation",
    "transport_params"
  ],
  "properties": {
    "receiver_id": {
      "description": "ID of the target Receiver of this Sender. This will be null if the sender is operating in multicast mode, or has not been assigned a receiver in unicast mode, or is sending to a non-NMOS receiver in unicast mode.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "master_enable": {
      "description": "Master on/off control for sender",
      "type": "boolean"
    },
    "activation": {
      "$ref": "activation-response-schema.json"
    },
    "transport_params": {
      "$ref": "sender_transport_params.json"
    }
  }
}

Examples:

immediate-activation:

{
  "master_enable": true,
  "receiver_id": null,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null,
    "activation_time": null
  },
  "transport_params": [{
    "source_ip": "192.168.200.10",
    "destination_ip": "232.105.26.177",
    "source_port": 5000,
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_type": "XOR",
    "fec_mode": "2D",
    "fec_block_width": 50,
    "fec_block_height": 50,
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "fec1D_source_port": 5010,
    "fec2D_source_port": 5012,
    "rtcp_enabled": true,
    "rtcp_destination_ip": "232.22.4.59",
    "rtcp_destination_port": 5008,
    "rtcp_source_port": 5008,
    "rtp_enabled": true
  }]
}

redundant-streams:

{
  "master_enable": true,
  "receiver_id": null,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null,
    "activation_time": null
  },
  "transport_params": [{
    "source_ip": "192.168.200.10",
    "destination_ip": "232.105.26.177",
    "source_port": 5000,
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_type": "XOR",
    "fec_mode": "2D",
    "fec_block_width": 50,
    "fec_block_height": 50,
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "fec1D_source_port": 5010,
    "fec2D_source_port": 5012,
    "rtcp_enabled": true,
    "rtcp_destination_ip": "232.22.4.59",
    "rtcp_destination_port": 5008,
    "rtcp_source_port": 5008,
    "rtp_enabled": true
  }, {
    "source_ip": "192.168.210.10",
    "destination_ip": "232.3.28.144",
    "source_port": 5000,
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_type": "XOR",
    "fec_mode": "2D",
    "fec_block_width": 50,
    "fec_block_height": 50,
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "fec1D_source_port": 5010,
    "fec2D_source_port": 5012,
    "rtcp_enabled": true,
    "rtcp_destination_ip": "232.79.192.98",
    "rtcp_destination_port": 5008,
    "rtcp_source_port": 5008,
    "rtp_enabled": true
  }]
}

HTTP status code 202

A 202 response is returned when a request for a scheduled activation is accepted, to indicate that while the request itself was acceptable it has not yet been acted upon by the sender. For scheduled activations activation_time should be the absolute TAI time the parameters will actually transition. For absolute scheduled activations should be the same as the requested time, but may differ if the sender is unable to schedule at the requested time. This may be because the transition may only occur, for example, at a frame boundary or end of GOP. In all other ways this response behaves identically to a 200 response.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a sender",
  "title": "Sender resource",
  "additionalProperties": false,
  "required": [
    "receiver_id",
    "master_enable",
    "activation",
    "transport_params"
  ],
  "properties": {
    "receiver_id": {
      "description": "ID of the target Receiver of this Sender. This will be null if the sender is operating in multicast mode, or has not been assigned a receiver in unicast mode, or is sending to a non-NMOS receiver in unicast mode.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "master_enable": {
      "description": "Master on/off control for sender",
      "type": "boolean"
    },
    "activation": {
      "$ref": "activation-response-schema.json"
    },
    "transport_params": {
      "$ref": "sender_transport_params.json"
    }
  }
}

Examples:

relative-scheduled-activation:

{
  "master_enable": true,
  "receiver_id": null,
  "activation": {
    "mode": "activate_scheduled_relative",
    "requested_time": "2:0",
    "activation_time": "1496759200:0"
  },
  "transport_params": [{
    "source_ip": "192.168.200.10",
    "destination_ip": "232.105.26.177",
    "source_port": 5000,
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_type": "XOR",
    "fec_mode": "2D",
    "fec_block_width": 50,
    "fec_block_height": 50,
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "fec1D_source_port": 5010,
    "fec2D_source_port": 5012,
    "rtcp_enabled": true,
    "rtcp_destination_ip": "232.79.192.98",
    "rtcp_destination_port": 5008,
    "rtcp_source_port": 5008,
    "rtp_enabled": true
  }]
}

absolute-scheduled-activation:

{
  "master_enable": true,
  "receiver_id": null,
  "activation": {
    "mode": "activate_scheduled_absolute",
    "requested_time": "1496759200:0",
    "activation_time": "1496759200:5000"
  },
  "transport_params": [{
    "source_ip": "192.168.200.10",
    "destination_ip": "232.105.26.177",
    "source_port": 5000,
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_type": "XOR",
    "fec_mode": "2D",
    "fec_block_width": 50,
    "fec_block_height": 50,
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "fec1D_source_port": 5010,
    "fec2D_source_port": 5012,
    "rtcp_enabled": true,
    "rtcp_destination_ip": "232.22.4.59",
    "rtcp_destination_port": 5008,
    "rtcp_source_port": 5008,
    "rtp_enabled": true
  }]
}

HTTP status code 400

A 400 response is returned when the request did not meet the schema and constraints.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

Example:

{
  "code": 400,
  "error": "`source_ip` must be a valid IPv4 or IPv6 address",
  "debug": null
}

HTTP status code 404

Returned when the requested resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/senders/3b8be755-08ff-452b-b217-c9151eb21193/staged

HTTP status code 423

Returned when the resource is locked because an activation has been scheduled. A resource may be unlocked by setting mode in activation to null, which will cancel the pending activation. This may be done in the same request as a change to other parameters.

HTTP status code 500

A 500 response may be returned if there is some failure which was not caused by a violation of schema or constraints.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

Example:

{
  "code": 500,
  "error": "Could not establish link to hardware",
  "debug": null
}

/single/senders/{senderId}/active get

get

Get active sender parameters. When the master_enable parameter is false senders should not transmit any media streams. For RTP senders the rtp_enabled parameter allows for the individual disabling of SMPTE 2022-7 legs. On activation all instances of auto must be resolved into the actual values that will be used by the sender, unless there is an error condition. For example if a sender has the destination_ip parameter set to auto in /staged then destination_ip in /active should show the multicast IP chosen by the sender. The parameter will remain set to auto in staged, and may be resolved to a different value on each subsequent activation. In cases, such as destination_ip, where the parameter changing unexpectedly at activation through re-resolution may be undesirable, care should be taken in implementation to manage this. If there is an error condition that means auto cannot be resolved, the active transport parameters must not change, and the underlying sender must continue as before.

Request
Response

URI Parameters

senderId: required(string)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a sender",
  "title": "Sender resource",
  "additionalProperties": false,
  "required": [
    "receiver_id",
    "master_enable",
    "activation",
    "transport_params"
  ],
  "properties": {
    "receiver_id": {
      "description": "ID of the target Receiver of this Sender. This will be null if the sender is operating in multicast mode, or has not been assigned a receiver in unicast mode, or is sending to a non-NMOS receiver in unicast mode.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "master_enable": {
      "description": "Master on/off control for sender",
      "type": "boolean"
    },
    "activation": {
      "$ref": "activation-response-schema.json"
    },
    "transport_params": {
      "$ref": "sender_transport_params.json"
    }
  }
}

Examples:

NormalRTP:

{
  "receiver_id": "0a174530-e3cf-11e6-bf01-fe55135034f3",
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": "1496759200:0",
    "activation_time": "1496759200:0"
  },
  "transport_params": [{
    "source_ip": "172.29.82.23",
    "destination_ip": "172.29.82.95",
    "source_port": 5000,
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_destination_ip": "172.29.82.95",
    "fec_type": "XOR",
    "fec_mode": "2D",
    "fec_block_width": 50,
    "fec_block_height": 50,
    "fec1D_destination_port": 5002,
    "fec2D_destination_port": 5004,
    "fec1D_source_port": 5002,
    "fec2D_source_port": 5004,
    "rtcp_enabled": true,
    "rtcp_destination_ip": "172.29.82.24",
    "rtcp_destination_port": 5008,
    "rtcp_source_port": 5008,
    "rtp_enabled": true
  }, {
    "source_ip": "172.30.82.23",
    "destination_ip": "172.30.82.95",
    "source_port": 5000,
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_destination_ip": "172.30.82.95",
    "fec_type": "XOR",
    "fec_mode": "2D",
    "fec_block_width": 50,
    "fec_block_height": 50,
    "fec1D_destination_port": 5002,
    "fec2D_destination_port": 5004,
    "fec1D_source_port": 5002,
    "fec2D_source_port": 5004,
    "rtcp_enabled": true,
    "rtcp_destination_ip": "172.30.82.24",
    "rtcp_destination_port": 5008,
    "rtcp_source_port": 5008,
    "rtp_enabled": true
  }]
}

NormalMQTT:

{
  "receiver_id": "69744dfb-0557-4202-b1f1-4d1a741ee2bb",
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": "1541508905:0",
    "activation_time": "1541508905:0"
  },
  "transport_params": [{
    "destination_host": "broker.example.com",
    "destination_port": 1883,
    "broker_topic": "my_topic_name",
    "broker_protocol": "mqtt",
    "broker_authorization": false,
    "connection_status_broker_topic": "my_status_topic_name"
  }]
}

Uninitialised:

{
  "receiver_id": null,
  "master_enable": true,
  "activation": {
    "mode": null,
    "requested_time": null,
    "activation_time": null
  },
  "transport_params": [{
    "source_ip": "172.29.82.23",
    "destination_ip": "232.21.98.4",
    "source_port": 5004,
    "destination_port": 5004,
    "fec_enabled": false,
    "fec_destination_ip": "172.29.82.23",
    "fec_type": "XOR",
    "fec_mode": "1D",
    "fec_block_width": 4,
    "fec_block_height": 4,
    "fec1D_destination_port": 5006,
    "fec2D_destination_port": 5008,
    "fec1D_source_port": 5006,
    "fec2D_source_port": 5008,
    "rtcp_enabled": false,
    "rtcp_destination_ip": "172.29.82.23",
    "rtcp_destination_port": 5005,
    "rtcp_source_port": 5005,
    "rtp_enabled": false
  }]
}

HTTP status code 404

Returned when the requested resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/senders/3b8be755-08ff-452b-b217-c9151eb21193/active

/single/senders/{senderId}/transportfile get

get

Redirects to the location of the sender's transport file or returns the transport file directly. Check HTTP response code to determine which mode of operation is in use. When returning the transport file directly ensure that the Content-Type entity header is correctly set.

Request
Response

URI Parameters

senderId: required(string)

HTTP status code 200

The transport file itself will be served

HTTP status code 307

A temporary redirect to the transport file

HTTP status code 404

Returned if the resource does not exist, or the transport type does not require a transport file, or if the sender is not currently configured. May also be returned when the master_enable parameter is false in /active, if the sender only maintains a transport file when transmitting.

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/senders/3b8be755-08ff-452b-b217-c9151eb21193/transportfile

/single/senders/{senderId}/transporttype get

get

Returns the URN base for the transport type employed by this sender with any subclassifications or versions removed.

Request
Response

URI Parameters

senderId: required(string)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Transport Type",
  "description": "Transport type URN base used by the Sender or Receiver (i.e. with any subclassifications or versions removed)",
  "type": "string",
  "anyOf": [
    {
      "enum": [
        "urn:x-nmos:transport:rtp",
        "urn:x-nmos:transport:dash",
        "urn:x-nmos:transport:websocket",
        "urn:x-nmos:transport:mqtt"
      ]
    },
    {
      "description": "Any transport type URN base defined by an AMWA specification in the Transports register of the NMOS Parameter Registers",
      "type": "string",
      "pattern": "^urn:x-nmos:transport:[a-zA-Z0-9_]+$"
    },
    {
      "description": "Any manufacturer-specific transport type URN base defined in the Transports register of the NMOS Parameter Registers",
      "not": {
        "pattern": "^urn:x-nmos:"
      }
    }
  ],
  "format": "uri"
}

Example:

"urn:x-nmos:transport:mqtt"

HTTP status code 404

Returned when the resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/senders/3b8be755-08ff-452b-b217-c9151eb21193/transporttype

/single/receivers get

get

List available receivers. All UUIDs are appended with / to indicate the ID forms part of the URL for the next layer down.

Response

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes the Connection API sender/receiver base resource",
  "title": "Connection API sender/receiver base resource",
  "items": {
    "type": "string",
    "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/$"
  },
  "uniqueItems": true
}

Example:

[
  "c72cca5b-01db-47aa-bb00-03893defbfae/",
  "171d5c80-7fff-4c23-9383-46503eb1c63e/",
  "a2655c48-8a46-4c82-b9bc-98760d59d7f8/"
]

/single/receivers/{receiverId} get

get

List API endpoints

Request
Response

URI Parameters

receiverId: required(string)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes the Connection API /single/receivers/{receiverId} base resource",
  "title": "Connection API /single/receivers/{receiverId} base resource",
  "items": {
    "type": "string",
    "enum": [
      "constraints/",
      "staged/",
      "active/",
      "transporttype/"
    ]
  },
  "minItems": 4,
  "maxItems": 4,
  "uniqueItems": true
}

Example:

[
  "constraints/",
  "staged/",
  "active/",
  "transporttype/"
]

HTTP status code 404

Returned when the requested resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/receivers/3b8be755-08ff-452b-b217-c9151eb21193

/single/receivers/{receiverId}/constraints get

get

Lists the constraints for each transport parameter (e.g max/min value, enumerated values etc.) using a very limited subset of JSON schema. Every transport parameter in the staged resource must be represented here. Any minimum/maximum constraints listed here must not allow a wider range of values than those allowed by the core schema. Any enum defined on this endpoint must only contain a subset of the values allowed for that parameter in the core schema. Similarly, pattern constraints must only narrow the allowed values. If the receiver does not constrain parameters beyond what is specified in the core schema then the constraints in the core schema should not be duplicated on this endpoint. Where an "auto" mode is allowed in the core schema this mode must always be supported by the receiver if the parameter is exposed. If SMPTE 2022-7 is in use, two entries are in the outer array of the resource. The first entry is the constraints for the primary leg. If SMPTE 2022-7 is not in use only one entry should be present in the outer array.

Request
Response

URI Parameters

receiverId: required(string)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Used to express the dynamic constraints on transport parameters. These constraints may be set and changed at run time. Parameters must also conform with constraints inferred from the specification. Every transport parameter must have an entry, even if it is only an empty object.",
  "title": "Constraints",
  "anyOf": [
    {
      "type": "array",
      "items": {
        "$ref": "constraints-schema-rtp.json"
      }
    },
    {
      "type": "array",
      "items": {
        "$ref": "constraints-schema-websocket.json"
      }
    },
    {
      "type": "array",
      "items": {
        "$ref": "constraints-schema-mqtt.json"
      }
    },
    {
      "type": "array",
      "items": {
        "description": "Constraints on transport parameters for another transport defined in Transports register of the NMOS Parameter Registers",
        "type": "object",
        "patternProperties": {
          "^[a-zA-Z0-9_]+$": {
            "$ref": "constraint-schema.json#/definitions/constraint"
          }
        }
      }
    }
  ]
}

Examples:

SMPTE2022-7:

[
  {
    "source_ip": {},
    "multicast_ip": {},
    "interface_ip": {
      "enum": [
        "192.168.7.2",
        "192.168.8.5",
        "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
        "2001:0db8:85a3:0000:0000:8a2e:0370:a24b"
      ]
    },
    "destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "fec_enabled": {},
    "fec_destination_ip": {},
    "fec_mode": {
      "enum": [
        "1D",
        "2D"
      ]
    },
    "fec1D_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "fec2D_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "rtcp_enabled": {},
    "rtcp_destination_ip": {},
    "rtcp_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "rtp_enabled": {}
  },
  {
    "source_ip": {},
    "multicast_ip": {},
    "interface_ip": {
      "enum": [
        "192.168.7.2",
        "192.168.8.5",
        "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
        "2001:0db8:85a3:0000:0000:8a2e:0370:a24b"
      ]
    },
    "destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "fec_enabled": {},
    "fec_destination_ip": {},
    "fec_mode": {
      "enum": [
        "1D",
        "2D"
      ]
    },
    "fec_block_width": {
      "minimum": 4,
      "maximum": 200
    },
    "fec_block_height": {
      "minimum": 4,
      "maximum": 200
    },
    "fec1D_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "fec2D_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "rtcp_enabled": {},
    "rtcp_destination_ip": {},
    "rtcp_destination_port": {
      "minimum": 5000,
      "maximum": 49150
    },
    "rtp_enabled": {}
  }
]

RTPNo2022-7:

[{
  "source_ip": {},
  "multicast_ip": {},
  "interface_ip": {
    "enum": [
      "192.168.7.2",
      "192.168.8.5",
      "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
      "2001:0db8:85a3:0000:0000:8a2e:0370:a24b"
    ]
  },
  "destination_port": {
    "minimum": 5000,
    "maximum": 49150
  },
  "fec_enabled": {},
  "fec_destination_ip": {},
  "fec_mode": {
    "enum": [
      "1D",
      "2D"
    ]
  },
  "fec1D_destination_port": {
    "minimum": 5000,
    "maximum": 49150
  },
  "fec2D_destination_port": {
    "minimum": 5000,
    "maximum": 49150
  },
  "rtcp_enabled": {},
  "rtcp_destination_ip": {},
  "rtcp_destination_port": {
    "minimum": 5000,
    "maximum": 49150
  },
  "rtp_enabled": {}
}]

MQTT:

[{
  "source_host": {},
  "source_port": {
    "enum": [
      1833,
      8883
    ]
  },
  "broker_topic": {},
  "broker_protocol": {
    "enum": [
      "mqtt"
    ]
  },
  "broker_authorization": {
    "enum": [
      false
    ]
  },
  "connection_status_broker_topic": {}
}]

WebSocketPlusExt:

[{
  "connection_uri": {},
  "connection_authorization": {},
  "ext_subscription_data": {},
  "ext_retry_timeout": {
    "maximum": 60,
    "minimum": 5
  }
}]

HTTP status code 404

Returned when the requested resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/receivers/3b8be755-08ff-452b-b217-c9151eb21193/constraints

/single/receivers/{receiverId}/staged get options patch

get

Get staged receiver transport parameters object. In SMPTE 2022-7 operation element 0 of the transport_params array shall be the parameters applied to the primary leg, and element 1 the secondary leg. There shall only be one element present in transport_params when SMPTE 2022-7 is not in use.

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

patch

Update staged parameters for receiver. Note that for activations the mode parameter will return to null once the activation transaction with the client is completed (i.e the response to the PATCH has been sent by the server). When a transport file is staged the parameters in that transport file should be propagated to their corresponding transport parameters and the response should show these updated values. On activation the value of the entries in transport_parameters must be used to program the receiver, not those in the transport file directly. However while the transport file is still present (i.e data is not null) media parameters in the transport file should be applied to the receiver. Setting data to null has no impact on the transport_parameters array, or any other property. Where a transport file has been staged the transport parameters in the response will reflect the new values assigned to them by the transport file. The transport parameters should be updated from the transport file in data on every PATCH request that includes the data field. Even if the value of data in the request matches the value of data currently stored in the API the transport parameters are still re-populated. In the case where the transport file and transport parameters are updated in the same PATCH request transport parameters specified in the request object take precedence over those in the transport file. In SMPTE 2022-7 operation element 0 of the transport_params array shall be the parameters applied to the primary leg, and element 1 the secondary leg. There shall only be one element present in transport_params when SMPTE 2022-7 is not in use.

Request
Response

URI Parameters

receiverId: required(string)

HTTP status code 200

Additionally constrained by the constraints at /constraints

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a receiver",
  "title": "Receiver resource",
  "additionalProperties": false,
  "required": [
    "sender_id",
    "master_enable",
    "activation",
    "transport_file",
    "transport_params"
  ],
  "properties": {
    "sender_id": {
      "description": "ID of the Sender subscribed to by this Receiver. This will be null if the receiver has not been configured to receive anything, or if it is receiving from a non-NMOS sender.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "master_enable": {
      "description": "Master on/off control for receiver",
      "type": "boolean"
    },
    "activation": {
      "$ref": "activation-response-schema.json"
    },
    "transport_file": {
      "$ref": "receiver-transport-file.json"
    },
    "transport_params": {
      "$ref": "receiver_transport_params.json"
    }
  }
}

Examples:

Normal:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": null,
    "requested_time": null,
    "activation_time": null
  },
  "transport_file": {
    "data": null,
    "type": null
  },
  "transport_params": [{
    "source_ip": "172.23.19.48",
    "multicast_ip": "232.250.98.80",
    "interface_ip": "172.23.19.110",
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_destination_ip": "auto",
    "fec_mode": "2D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": true,
    "rtcp_destination_ip": "auto",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }, {
    "source_ip": "172.23.20.48",
    "multicast_ip": "232.250.99.80",
    "interface_ip": "172.23.20.110",
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_destination_ip": "auto",
    "fec_mode": "2D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": true,
    "rtcp_destination_ip": "auto",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }]
}

Pending:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_scheduled_relative",
    "requested_time": "5:0",
    "activation_time": "1499333737:0"
  },
  "transport_file": {
    "data": null,
    "type": null
  },
  "transport_params": [{
    "source_ip": "172.23.19.48",
    "multicast_ip": "232.250.98.80",
    "interface_ip": "172.23.19.110",
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_destination_ip": "auto",
    "fec_mode": "2D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": true,
    "rtcp_destination_ip": "auto",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }, {
    "source_ip": "172.23.20.48",
    "multicast_ip": "232.250.99.80",
    "interface_ip": "172.23.20.110",
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_destination_ip": "auto",
    "fec_mode": "2D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": true,
    "rtcp_destination_ip": "auto",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }]
}

Uninitialised:

{
  "sender_id": null,
  "master_enable": true,
  "activation": {
    "mode": null,
    "requested_time": null,
    "activation_time": null
  },
  "transport_file": {
    "data": null,
    "type": null
  },
  "transport_params": [{
    "source_ip": null,
    "multicast_ip": null,
    "interface_ip": "auto",
    "destination_port": "auto",
    "fec_enabled": false,
    "fec_destination_ip": "auto",
    "fec_mode": "1D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": false,
    "rtcp_destination_ip": "auto",
    "rtcp_destination_port": "auto",
    "rtp_enabled": true
  }]
}

HTTP status code 404

Returned when the requested resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/receivers/3b8be755-08ff-452b-b217-c9151eb21193/staged

Request
Response

URI Parameters

receiverId: required(string)

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a receiver",
  "title": "Receiver resource",
  "additionalProperties": false,
  "properties": {
    "sender_id": {
      "description": "ID of the Sender subscribed to by this Receiver. This will be null if the receiver has not been configured to receive anything, or if it is receiving from a non-NMOS sender.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "master_enable": {
      "description": "Master on/off control for receiver",
      "type": "boolean"
    },
    "activation": {
      "$ref": "activation-schema.json"
    },
    "transport_file": {
      "$ref": "receiver-transport-file.json"
    },
    "transport_params": {
      "$ref": "receiver_transport_params.json"
    }
  }
}

Examples:

activate-immediate:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null
  },
  "transport_params": [{
    "interface_ip": "192.168.200.15",
    "multicast_ip": "232.105.26.177",
    "source_ip": "192.168.200.10",
    "destination_port": 5000,
    "rtp_enabled": true
  }]
}

activate-scheduled-relative:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_scheduled_relative",
    "requested_time": "2:0"
  },
  "transport_params": [{
    "interface_ip": "192.168.200.15",
    "multicast_ip": "232.105.26.177",
    "source_ip": "192.168.200.10",
    "destination_port": 5000,
    "rtp_enabled": true
  }]
}

activate-scheduled-absolute:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_scheduled_absolute",
    "requested_time": "1496677550:20"
  },
  "transport_params": [{
    "interface_ip": "192.168.200.15",
    "multicast_ip": "232.105.26.177",
    "source_ip": "192.168.200.10",
    "destination_port": 5000,
    "rtp_enabled": true
  }]
}

activation-only:

{
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null
  }
}

stage-transportfile:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "transport_file": {
    "data": "v=0\r\no=- 1496222842 1496222842 IN IP4 172.29.226.25\r\ns=IP Studio Stream\r\nt=0 0\r\nm=video 5010 RTP/AVP 103\r\nc=IN IP4 232.250.98.80/32\r\na=source-filter: incl IN IP4 232.250.98.80 172.29.226.25\r\na=rtpmap:103 raw/90000\r\na=fmtp:103 sampling=YCbCr-4:2:2; width=1920; height=1080; depth=10; interlace; exactframerate=25; colorimetry=BT709; PM=2110GPM; SSN=ST2110-20:2017; TP=2110TPW; \r\na=mediaclk:direct=1876655126 rate=90000\r\na=extmap:1 urn:x-nmos:rtp-hdrext:origin-timestamp\r\na=extmap:2 urn:ietf:params:rtp-hdrext:smpte-tc 3600@90000/25\r\na=extmap:3 urn:x-nmos:rtp-hdrext:flow-id\r\na=extmap:4 urn:x-nmos:rtp-hdrext:source-id\r\na=extmap:5 urn:x-nmos:rtp-hdrext:grain-flags\r\na=extmap:7 urn:x-nmos:rtp-hdrext:sync-timestamp\r\na=extmap:9 urn:x-nmos:rtp-hdrext:grain-duration\r\na=ts-refclk:ptp=IEEE1588-2008:08-00-11-FF-FE-21-E1-B0:0\r\n",
    "type": "application/sdp"
  }
}

redundant-streams:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null
  },
  "transport_params": [{
      "interface_ip": "192.168.200.15",
      "multicast_ip": "232.105.26.177",
      "source_ip": "192.168.200.10",
      "destination_port": 5000,
      "rtp_enabled": true
    },
    {
      "interface_ip": "192.168.210.15",
      "multicast_ip": "232.3.28.144",
      "source_ip": "192.168.210.10",
      "destination_port": 5000,
      "rtp_enabled": true
    }
  ]
}

unicast:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null
  },
  "transport_params": [{
    "interface_ip": "192.168.200.15",
    "multicast_ip": null,
    "source_ip": "192.168.200.10",
    "destination_port": 5000,
    "rtp_enabled": true
  }]
}

HTTP status code 200

A 200 response is returned for PATCH requests where no activation has been scheduled, an activation has been cancelled, or an immediate activation has been requested. The response will always contain the full set of parameters in the response schema, and all supported transport parameters. For a request involving an immediate activation the API should only return once the transport parameters have been applied to the underlying receiver. Note the presence of the extra activation_time parameter in the response. For immediate activation this should be the time the activation actually occurred as an absolute TAI timestamp. If no activation was requested in the activation_time will be set null.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a receiver",
  "title": "Receiver resource",
  "additionalProperties": false,
  "required": [
    "sender_id",
    "master_enable",
    "activation",
    "transport_file",
    "transport_params"
  ],
  "properties": {
    "sender_id": {
      "description": "ID of the Sender subscribed to by this Receiver. This will be null if the receiver has not been configured to receive anything, or if it is receiving from a non-NMOS sender.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "master_enable": {
      "description": "Master on/off control for receiver",
      "type": "boolean"
    },
    "activation": {
      "$ref": "activation-response-schema.json"
    },
    "transport_file": {
      "$ref": "receiver-transport-file.json"
    },
    "transport_params": {
      "$ref": "receiver_transport_params.json"
    }
  }
}

Examples:

activate-immediate:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null,
    "activation_time": "1496739062:0"
  },
  "transport_file": {
    "data": null,
    "type": null
  },
  "transport_params": [{
    "interface_ip": "192.168.200.15",
    "multicast_ip": "232.105.26.177",
    "source_ip": "192.168.200.10",
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_mode": "2D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": true,
    "rtcp_destination_ip": "232.22.4.59",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }]
}

stage-transportfile:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": null,
    "requested_time": null,
    "activation_time": null
  },
  "transport_file": {
    "data": "v=0\r\no=- 1496222842 1496222842 IN IP4 172.29.226.25\r\ns=IP Studio Stream\r\nt=0 0\r\nm=video 5010 RTP/AVP 103\r\nc=IN IP4 232.250.98.80/32\r\na=source-filter: incl IN IP4 232.250.98.80 172.29.226.25\r\na=rtpmap:103 raw/90000\r\na=fmtp:103 sampling=YCbCr-4:2:2; width=1920; height=1080; depth=10; interlace; exactframerate=25; colorimetry=BT709; PM=2110GPM; SSN=ST2110-20:2017; TP=2110TPW; \r\na=mediaclk:direct=1876655126 rate=90000\r\na=extmap:1 urn:x-nmos:rtp-hdrext:origin-timestamp\r\na=extmap:2 urn:ietf:params:rtp-hdrext:smpte-tc 3600@90000/25\r\na=extmap:3 urn:x-nmos:rtp-hdrext:flow-id\r\na=extmap:4 urn:x-nmos:rtp-hdrext:source-id\r\na=extmap:5 urn:x-nmos:rtp-hdrext:grain-flags\r\na=extmap:7 urn:x-nmos:rtp-hdrext:sync-timestamp\r\na=extmap:9 urn:x-nmos:rtp-hdrext:grain-duration\r\na=ts-refclk:ptp=IEEE1588-2008:08-00-11-FF-FE-21-E1-B0:0\r\n",
    "type": "application/sdp"
  },
  "transport_params": [{
    "source_ip": "172.29.226.25",
    "multicast_ip": "232.250.98.80",
    "interface_ip": "172.23.19.35",
    "destination_port": 5010,
    "fec_enabled": false,
    "fec_mode": "2D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": false,
    "rtcp_destination_ip": "auto",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }]
}

redundant-streams:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": null,
    "activation_time": "1496739062:0"
  },
  "transport_file": {
    "data": null,
    "type": null
  },
  "transport_params": [{
    "interface_ip": "192.168.200.15",
    "multicast_ip": "232.105.26.177",
    "source_ip": "192.168.200.10",
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_mode": "2D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": true,
    "rtcp_destination_ip": "232.22.4.59",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }, {
    "interface_ip": "192.168.200.15",
    "multicast_ip": "232.105.26.177",
    "source_ip": "192.168.200.10",
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_mode": "2D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": true,
    "rtcp_destination_ip": "232.79.192.98",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }]
}

HTTP status code 202

A 202 response is returned when a request for a scheduled activation is accepted, to indicate that while the request itself was acceptable it has not yet been acted upon by the receiver. For scheduled activations activation_time should be the absolute TAI time the parameters will actually transition. For absolute scheduled activations should be the same as the requested time, but may differ if the receiver is unable to schedule at the requested time. This may be because the transition may only occur, for example, at a frame boundary or end of GOP. In all other ways this response behaves identically to a 200 response.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a receiver",
  "title": "Receiver resource",
  "additionalProperties": false,
  "required": [
    "sender_id",
    "master_enable",
    "activation",
    "transport_file",
    "transport_params"
  ],
  "properties": {
    "sender_id": {
      "description": "ID of the Sender subscribed to by this Receiver. This will be null if the receiver has not been configured to receive anything, or if it is receiving from a non-NMOS sender.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "master_enable": {
      "description": "Master on/off control for receiver",
      "type": "boolean"
    },
    "activation": {
      "$ref": "activation-response-schema.json"
    },
    "transport_file": {
      "$ref": "receiver-transport-file.json"
    },
    "transport_params": {
      "$ref": "receiver_transport_params.json"
    }
  }
}

Examples:

activate-scheduled-relative:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_scheduled_relative",
    "requested_time": "2:0",
    "activation_time": "1496739064:0"
  },
  "transport_file": {
    "data": null,
    "type": null
  },
  "transport_params": [{
    "interface_ip": "192.168.200.15",
    "multicast_ip": "232.105.26.177",
    "source_ip": "192.168.200.10",
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_mode": "2D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": true,
    "rtcp_destination_ip": "auto",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }]
}

activate-scheduled-absolute:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_scheduled_absolute",
    "requested_time": "1496739064:0",
    "activation_time": "1496739064:2500"
  },
  "transport_file": {
    "data": null,
    "type": null
  },
  "transport_params": [{
    "interface_ip": "192.168.200.15",
    "multicast_ip": "232.105.26.177",
    "source_ip": "192.168.200.10",
    "destination_port": 5000,
    "fec_enabled": true,
    "fec_mode": "2D",
    "fec1D_destination_port": "auto",
    "fec2D_destination_port": "auto",
    "rtcp_enabled": true,
    "rtcp_destination_ip": "auto",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }]
}

HTTP status code 400

A 400 response is returned when the request did not meet the schema and constraints.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

Example:

{
  "code": 400,
  "error": "`source_ip` must be a valid IPv4 or IPv6 address",
  "debug": null
}

HTTP status code 404

Returned when the requested resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/receivers/3b8be755-08ff-452b-b217-c9151eb21193/staged

HTTP status code 423

HTTP status code 500

A 500 response may be returned if the transport file could not be parsed, or there is some failure which was not caused by a violation of schema or constraints.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

Example:

{
  "code": 500,
  "error": "Could not establish link to hardware",
  "debug": null
}

/single/receivers/{receiverId}/active get

get

Get active receiver parameters. When the master_enable parameter is false receivers should not process any incoming streams, and should unsubscribe from any multicast streams they are receiving. For RTP receivers the rtp_enabled parameter allows for the individual disabling of SMPTE 2022-7 legs. On activation all instances of auto must be resolved into the actual values that will be used by the receiver, unless there is an error condition. For example if a receiver has the interface_ip parameter set to auto in /staged then interface_ip in /active should show the IP address of the interface chosen by the receiver. The parameter will remain set to auto in staged, and may be resolved to a different value on each subsequent activation. In cases, such as interface_ip, where the parameter changing unexpectedly at activation through re-resolution may be undesirable, care should be taken in implementation to manage this. If there is an error condition that means auto cannot be resolved, the active transport parameters must not change, and the underlying receiver must continue as before.

Request
Response

URI Parameters

receiverId: required(string)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes a receiver",
  "title": "Receiver resource",
  "additionalProperties": false,
  "required": [
    "sender_id",
    "master_enable",
    "activation",
    "transport_file",
    "transport_params"
  ],
  "properties": {
    "sender_id": {
      "description": "ID of the Sender subscribed to by this Receiver. This will be null if the receiver has not been configured to receive anything, or if it is receiving from a non-NMOS sender.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "master_enable": {
      "description": "Master on/off control for receiver",
      "type": "boolean"
    },
    "activation": {
      "$ref": "activation-response-schema.json"
    },
    "transport_file": {
      "$ref": "receiver-transport-file.json"
    },
    "transport_params": {
      "$ref": "receiver_transport_params.json"
    }
  }
}

Examples:

NormalRTP:

{
  "sender_id": "5709255c-c0ae-4e1e-99a0-e872e83e48e0",
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": "1496739062:0",
    "activation_time": "1496739062:263900"
  },
  "transport_file": {
    "data": "v=0\r\no=- 1496222842 1496222842 IN IP4 172.29.226.25\r\ns=IP Studio Stream\r\nt=0 0\r\nm=video 5010 RTP/AVP 103\r\nc=IN IP4 232.250.98.80/32\r\na=source-filter: incl IN IP4 232.250.98.80 172.29.226.25\r\na=rtpmap:103 raw/90000\r\na=fmtp:103 sampling=YCbCr-4:2:2; width=1920; height=1080; depth=10; interlace; exactframerate=25; colorimetry=BT709; PM=2110GPM; SSN=ST2110-20:2017; TP=2110TPW; \r\na=mediaclk:direct=1876655126 rate=90000\r\na=extmap:1 urn:x-nmos:rtp-hdrext:origin-timestamp\r\na=extmap:2 urn:ietf:params:rtp-hdrext:smpte-tc 3600@90000/25\r\na=extmap:3 urn:x-nmos:rtp-hdrext:flow-id\r\na=extmap:4 urn:x-nmos:rtp-hdrext:source-id\r\na=extmap:5 urn:x-nmos:rtp-hdrext:grain-flags\r\na=extmap:7 urn:x-nmos:rtp-hdrext:sync-timestamp\r\na=extmap:9 urn:x-nmos:rtp-hdrext:grain-duration\r\na=ts-refclk:ptp=IEEE1588-2008:08-00-11-FF-FE-21-E1-B0:0\r\n",
    "type": "application/sdp"
  },
  "transport_params": [{
    "source_ip": "172.29.226.25",
    "multicast_ip": "232.250.98.80",
    "interface_ip": "172.23.19.35",
    "destination_port": 5010,
    "fec_enabled": false,
    "fec_mode": "2D",
    "fec1D_destination_port": 5012,
    "fec2D_destination_port": 5014,
    "rtcp_enabled": false,
    "rtcp_destination_ip": "232.250.98.80",
    "rtcp_destination_port": 5001,
    "rtp_enabled": true
  }]
}

NormalMQTT:

{
  "sender_id": "eae33112-b56c-4a36-8b68-05ab5b6268bc",
  "master_enable": true,
  "activation": {
    "mode": "activate_immediate",
    "requested_time": "1541508905:0",
    "activation_time": "1541508905:263900"
  },
  "transport_file": {
    "data": null,
    "type": null
  },
  "transport_params": [{
    "source_host": "broker.example.com",
    "source_port": 1883,
    "broker_topic": "my_topic_name",
    "broker_protocol": "mqtt",
    "broker_authorization": false,
    "connection_status_broker_topic": "my_status_topic_name"
  }]
}

Uninitialised:

{
  "sender_id": null,
  "master_enable": true,
  "activation": {
    "mode": null,
    "requested_time": null,
    "activation_time": null
  },
  "transport_file": {
    "data": null,
    "type": null
  },
  "transport_params": [{
    "source_ip": null,
    "multicast_ip": null,
    "interface_ip": "172.23.19.35",
    "destination_port": 5004,
    "fec_enabled": false,
    "fec_destination_ip": "172.23.19.35",
    "fec1D_destination_port": 5006,
    "fec2D_destination_port": 5008,
    "rtcp_enabled": false,
    "rtcp_destination_ip": "172.23.19.35",
    "rtcp_destination_port": 5005,
    "rtp_enabled": true
  }]
}

HTTP status code 404

Returned when the requested resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/receivers/3b8be755-08ff-452b-b217-c9151eb21193/active

/single/receivers/{receiverId}/transporttype get

get

Returns the URN base for the transport type employed by this receiver with any subclassifications or versions removed.

Request
Response

URI Parameters

receiverId: required(string)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Transport Type",
  "description": "Transport type URN base used by the Sender or Receiver (i.e. with any subclassifications or versions removed)",
  "type": "string",
  "anyOf": [
    {
      "enum": [
        "urn:x-nmos:transport:rtp",
        "urn:x-nmos:transport:dash",
        "urn:x-nmos:transport:websocket",
        "urn:x-nmos:transport:mqtt"
      ]
    },
    {
      "description": "Any transport type URN base defined by an AMWA specification in the Transports register of the NMOS Parameter Registers",
      "type": "string",
      "pattern": "^urn:x-nmos:transport:[a-zA-Z0-9_]+$"
    },
    {
      "description": "Any manufacturer-specific transport type URN base defined in the Transports register of the NMOS Parameter Registers",
      "not": {
        "pattern": "^urn:x-nmos:"
      }
    }
  ],
  "format": "uri"
}

Example:

"urn:x-nmos:transport:mqtt"

HTTP status code 404

Returned when the resource does not exist

HTTP status code 409

Returned when the requested resource is only available at a different API version.

Headers

Location: required(string)

Example:

/x-nmos/connection/{version}/single/receivers/3b8be755-08ff-452b-b217-c9151eb21193/transporttype

Documentation built at 03:01:01 CST on 2024-12-05.
(c) AMWA 2024. RAML/JSON licensed under Apache 2.0. Documentation licensed under CC BY-ND 4.0.

Connection API documentation version v1.1

Base

get /

HTTP status code 200

Body

Bulk control interface

get /bulk

HTTP status code 200

Body

get /bulk/senders

HTTP status code 405

options /bulk/senders

HTTP status code 200

HTTP status code 403

post /bulk/senders

Body

HTTP status code 200

Body

HTTP status code 400

Body

get /bulk/receivers

HTTP status code 405

options /bulk/receivers

HTTP status code 200

HTTP status code 403

post /bulk/receivers

Body

HTTP status code 200

Body

HTTP status code 400

Body

Single control interface

get /single

HTTP status code 200

Body

get /single/senders

HTTP status code 200

Body

get /single/senders/{senderId}

URI Parameters

HTTP status code 200

Body

HTTP status code 404

HTTP status code 409

Headers

get /single/senders/{senderId}/constraints

URI Parameters

HTTP status code 200

Body

HTTP status code 404

HTTP status code 409

Headers

get /single/senders/{senderId}/staged

URI Parameters

HTTP status code 200

Body

HTTP status code 404

HTTP status code 409

Headers

options /single/senders/{senderId}/staged

URI Parameters

HTTP status code 200

HTTP status code 403

HTTP status code 404

patch /single/senders/{senderId}/staged

URI Parameters

Body

HTTP status code 200

Body

HTTP status code 202

Body

HTTP status code 400

Body

HTTP status code 404

HTTP status code 409

Headers

HTTP status code 423

HTTP status code 500

Body

get /single/senders/{senderId}/active