Connection API documentation version v1.0
http://example.api.com/x-nmos/connection/{version}
- version: required(v1.0)
Overview
The Connection API is exposed by NMOS Devices as a standard control interface for management of inter-device connnections.
Endpoint Discovery
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/v1.0". 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
List of modes available from this API - single and bulk. Both are compulsory parts of the spec.
Bulk control interface
Senders / receivers options
Target for bulk staging of transport parameters.
Allows staging and activation of multiple sender parameters at the same time in a single request.
post /bulk/senders
Allows staging and activation of multiple sender parameters at the same time in a single request.
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": "v1.0-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>"
}
Target for bulk uploads of transport parameters.
Allows staging and activation of a subset of multiple receiver parameters at the same time in a single request.
post /bulk/receivers
Allows staging and activation of a subset of multiple receiver parameters at the same time in a single request.
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": "v1.0-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=1; framerate=25; colorimetry=BT709-2\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\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
Sender root
get /single/senders
Sender root
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: any
Example:
[
"c72cca5b-01db-47aa-bb00-03893defbfae/",
"171d5c80-7fff-4c23-9383-46503eb1c63e/",
"a2655c48-8a46-4c82-b9bc-98760d59d7f8/"
]
List all the API endpoints for a single sender.
get /single/senders/{senderId}
List all the API endpoints for a single sender.
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.
get /single/senders/{senderId}/constraints
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.
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": "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",
"maxitems": 2,
"items": {
"type": "object",
"description": "Contains the constraints for on transport leg",
"properties": {
"multicast_ip": {
"$ref": "#/definitions/constraint"
},
"destination_ip": {
"$ref": "#/definitions/constraint"
},
"destination_port": {
"$ref": "#/definitions/constraint"
},
"source_ip": {
"$ref": "#/definitions/constraint"
},
"interface_ip": {
"$ref": "#/definitions/constraint"
},
"source_port": {
"$ref": "#/definitions/constraint"
},
"fec_enabled": {
"$ref": "#/definitions/constraint"
},
"fec_destination_ip": {
"$ref": "#/definitions/constraint"
},
"fec_mode": {
"$ref": "#/definitions/constraint"
},
"fec_type": {
"$ref": "#/definitions/constraint"
},
"fec_block_width": {
"$ref": "#/definitions/constraint"
},
"fec_block_height": {
"$ref": "#/definitions/constraint"
},
"fec1D_destination_port": {
"$ref": "#/definitions/constraint"
},
"fec2D_destination_port": {
"$ref": "#/definitions/constraint"
},
"fec1D_source_port": {
"$ref": "#/definitions/constraint"
},
"fec2D_source_port": {
"$ref": "#/definitions/constraint"
},
"rtcp_enabled": {
"$ref": "#/definitions/constraint"
},
"rtcp_destination_ip": {
"$ref": "#/definitions/constraint"
},
"rtcp_destination_port": {
"$ref": "#/definitions/constraint"
},
"rtcp_source_port": {
"$ref": "#/definitions/constraint"
},
"rtp_enabled": {
"$ref": "#/definitions/constraint"
}
}
},
"definitions": {
"constraint": {
"type": "object",
"description": "The constraints for a single transport parameter",
"properties": {
"maximum": {
"description": "The inclusive maximum value the parameter can be set to",
"type": [
"integer",
"number"
]
},
"minimum": {
"description": "The inclusive minimum value the parameter can be set to",
"type": [
"integer",
"number"
]
},
"enum": {
"description": "An array of allowed values",
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"anyOf": [{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "null"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"pattern": {
"description": "A regex pattern that must be satisfied for this parameter",
"type": "string",
"format": "regex"
},
"description": {
"description": "A human readable string describing the constraint (optional)",
"type": "string"
}
},
"additionalProperties": false
}
}
}
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": {
"maximum": 50000,
"minimum": 49151
},
"destination_port": {
"maximum": 50000,
"minimum": 49151
},
"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": 49151
},
"fec2D_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"fec1D_source_port": {
"minimum": 5000,
"maximum": 49151
},
"fec2D_source_port": {
"minimum": 5000,
"maximum": 49151
},
"rtcp_enabled": {},
"rtcp_destination_ip": {},
"rtcp_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"rtcp_source_port": {
"minimum": 5000,
"maximum": 49151
},
"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": {
"maximum": 50000,
"minimum": 49151
},
"destination_port": {
"maximum": 50000,
"minimum": 49151
},
"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": 49151
},
"fec2D_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"fec1D_source_port": {
"minimum": 5000,
"maximum": 49151
},
"fec2D_source_port": {
"minimum": 5000,
"maximum": 49151
},
"rtcp_enabled": {},
"rtcp_destination_ip": {},
"rtcp_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"rtcp_source_port": {
"minimum": 5000,
"maximum": 49151
},
"rtp_enabled": {}
}
]
No2022-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": {
"maximum": 50000,
"minimum": 49151
},
"destination_port": {
"maximum": 50000,
"minimum": 49151
},
"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": 49151
},
"fec2D_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"fec1D_source_port": {
"minimum": 5000,
"maximum": 49151
},
"fec2D_source_port": {
"minimum": 5000,
"maximum": 49151
},
"rtcp_enabled": {},
"rtcp_destination_ip": {},
"rtcp_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"rtcp_source_port": {
"minimum": 5000,
"maximum": 49151
},
"rtp_enabled": {}
}]
HTTP status code 404
Returned when the requested resource does not exist
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. When the master_enable parameter is false the RTP sender should stop transmitting media and the /transportfile endpoint should return an HTTP 404 response.
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.
get /single/senders/{senderId}/staged
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. When the master_enable parameter is false the RTP sender should stop transmitting media and the /transportfile endpoint should return an HTTP 404 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": "v1.0-activation-response-schema.json"
},
"transport_params": {
"description": "Transport-specific parameters",
"oneOf": [{
"$ref": "v1.0_sender_transport_params_rtp.json"
},
{
"$ref": "v1.0_sender_transport_params_dash.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
patch /single/senders/{senderId}/staged
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.
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": "v1.0-activation-schema.json"
},
"transport_params": {
"description": "Transport-specific parameters",
"oneOf": [{
"$ref": "v1.0_sender_transport_params_rtp.json"
},
{
"$ref": "v1.0_sender_transport_params_dash.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. When the master_enable parameter is false senders should not transmit any media streams. For RTP senders the rtp_enable parameter allows for the individual disabling of SMPTE 2022-7 legs.
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": "v1.0-activation-response-schema.json"
},
"transport_params": {
"description": "Transport-specific parameters",
"oneOf": [{
"$ref": "v1.0_sender_transport_params_rtp.json"
},
{
"$ref": "v1.0_sender_transport_params_dash.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": "v1.0-activation-response-schema.json"
},
"transport_params": {
"description": "Transport-specific parameters",
"oneOf": [{
"$ref": "v1.0_sender_transport_params_rtp.json"
},
{
"$ref": "v1.0_sender_transport_params_dash.json"
}
]
}
}
}
Examples:
relative-scheduled-activation:
{
"master_enable": true,
"receiver_id": "",
"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_relative",
"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 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 the transport file could not be parsed, or there is some failure caused by activation which was not caused by a violation or 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
}
Get active sender parameters. 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.
get /single/senders/{senderId}/active
Get active sender parameters. 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.
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": "v1.0-activation-response-schema.json"
},
"transport_params": {
"description": "Transport-specific parameters",
"oneOf": [{
"$ref": "v1.0_sender_transport_params_rtp.json"
},
{
"$ref": "v1.0_sender_transport_params_dash.json"
}
]
}
}
}
Examples:
Normal:
{
"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
}]
}
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
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.
get /single/senders/{senderId}/transportfile
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.
List available receivers. All UUIDs are appended with / to indicate the ID forms part of the URL for the next layer down.
get /single/receivers
List available receivers. All UUIDs are appended with / to indicate the ID forms part of the URL for the next layer down.
HTTP status code 200
Body
Media type: application/json
Type: any
Example:
[
"c72cca5b-01db-47aa-bb00-03893defbfae/",
"171d5c80-7fff-4c23-9383-46503eb1c63e/",
"a2655c48-8a46-4c82-b9bc-98760d59d7f8/"
]
List API endpoints
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.
get /single/receivers/{receiverId}/constraints
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.
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": "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",
"maxitems": 2,
"items": {
"type": "object",
"description": "Contains the constraints for on transport leg",
"properties": {
"multicast_ip": {
"$ref": "#/definitions/constraint"
},
"destination_ip": {
"$ref": "#/definitions/constraint"
},
"destination_port": {
"$ref": "#/definitions/constraint"
},
"source_ip": {
"$ref": "#/definitions/constraint"
},
"interface_ip": {
"$ref": "#/definitions/constraint"
},
"source_port": {
"$ref": "#/definitions/constraint"
},
"fec_enabled": {
"$ref": "#/definitions/constraint"
},
"fec_destination_ip": {
"$ref": "#/definitions/constraint"
},
"fec_mode": {
"$ref": "#/definitions/constraint"
},
"fec_type": {
"$ref": "#/definitions/constraint"
},
"fec_block_width": {
"$ref": "#/definitions/constraint"
},
"fec_block_height": {
"$ref": "#/definitions/constraint"
},
"fec1D_destination_port": {
"$ref": "#/definitions/constraint"
},
"fec2D_destination_port": {
"$ref": "#/definitions/constraint"
},
"fec1D_source_port": {
"$ref": "#/definitions/constraint"
},
"fec2D_source_port": {
"$ref": "#/definitions/constraint"
},
"rtcp_enabled": {
"$ref": "#/definitions/constraint"
},
"rtcp_destination_ip": {
"$ref": "#/definitions/constraint"
},
"rtcp_destination_port": {
"$ref": "#/definitions/constraint"
},
"rtcp_source_port": {
"$ref": "#/definitions/constraint"
},
"rtp_enabled": {
"$ref": "#/definitions/constraint"
}
}
},
"definitions": {
"constraint": {
"type": "object",
"description": "The constraints for a single transport parameter",
"properties": {
"maximum": {
"description": "The inclusive maximum value the parameter can be set to",
"type": [
"integer",
"number"
]
},
"minimum": {
"description": "The inclusive minimum value the parameter can be set to",
"type": [
"integer",
"number"
]
},
"enum": {
"description": "An array of allowed values",
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"anyOf": [{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "null"
},
{
"type": "number"
},
{
"type": "string"
}
]
}
},
"pattern": {
"description": "A regex pattern that must be satisfied for this parameter",
"type": "string",
"format": "regex"
},
"description": {
"description": "A human readable string describing the constraint (optional)",
"type": "string"
}
},
"additionalProperties": false
}
}
}
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": {
"maximum": 50000,
"minimum": 49151
},
"fec_enabled": {},
"fec_destination_ip": {},
"fec_mode": {
"enum": [
"1D",
"2D"
]
},
"fec1D_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"fec2D_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"rtcp_enabled": {},
"rtcp_destination_ip": {},
"rtcp_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"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": {
"maximum": 50000,
"minimum": 49151
},
"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": 49151
},
"fec2D_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"rtcp_enabled": {},
"rtcp_destination_ip": {},
"rtcp_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"rtp_enabled": {}
}
]
No2022-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": {
"maximum": 50000,
"minimum": 49151
},
"fec_enabled": {},
"fec_destination_ip": {},
"fec_mode": {
"enum": [
"1D",
"2D"
]
},
"fec1D_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"fec2D_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"rtcp_enabled": {},
"rtcp_destination_ip": {},
"rtcp_destination_port": {
"minimum": 5000,
"maximum": 49151
},
"rtp_enabled": {}
}]
HTTP status code 404
Returned when the requested resource does not exist
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.
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 RTP 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. 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_enable parameter allows for the individual disabling of SMPTE 2022-7 legs.
get /single/receivers/{receiverId}/staged
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.
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": "v1.0-activation-response-schema.json"
},
"transport_file": {
"type": "object",
"description": "Transport file parameters",
"additionalProperties": false,
"required": [
"data",
"type"
],
"properties": {
"data": {
"description": "Content of the transport file",
"type": [
"string",
"null"
]
},
"type": {
"description": "IANA assigned media type for file (e.g application/sdp)",
"type": [
"string",
"null"
]
}
}
},
"transport_params": {
"description": "Transport-specific parameters",
"oneOf": [{
"$ref": "v1.0_receiver_transport_params_rtp.json"
},
{
"$ref": "v1.0_receiver_transport_params_dash.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": "application/sdp"
},
"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": "application/sdp"
},
"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
patch /single/receivers/{receiverId}/staged
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 RTP 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. 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_enable parameter allows for the individual disabling of SMPTE 2022-7 legs.
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": "v1.0-activation-schema.json"
},
"transport_file": {
"type": "object",
"description": "Transport file parameters",
"additionalProperties": false,
"properties": {
"data": {
"description": "Content of the transport file",
"type": [
"string",
"null"
]
},
"type": {
"description": "IANA assigned media type for file (e.g application/sdp)",
"type": [
"string",
"null"
]
}
}
},
"transport_params": {
"description": "Transport-specific parameters",
"oneOf": [{
"$ref": "v1.0_receiver_transport_params_rtp.json"
},
{
"$ref": "v1.0_receiver_transport_params_dash.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=1; framerate=25; colorimetry=BT709-2\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\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": "v1.0-activation-response-schema.json"
},
"transport_file": {
"type": "object",
"description": "Transport file parameters",
"additionalProperties": false,
"required": [
"data",
"type"
],
"properties": {
"data": {
"description": "Content of the transport file",
"type": [
"string",
"null"
]
},
"type": {
"description": "IANA assigned media type for file (e.g application/sdp)",
"type": [
"string",
"null"
]
}
}
},
"transport_params": {
"description": "Transport-specific parameters",
"oneOf": [{
"$ref": "v1.0_receiver_transport_params_rtp.json"
},
{
"$ref": "v1.0_receiver_transport_params_dash.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": "application/sdp"
},
"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=1; framerate=25; colorimetry=BT709-2\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\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": "application/sdp"
},
"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": "v1.0-activation-response-schema.json"
},
"transport_file": {
"type": "object",
"description": "Transport file parameters",
"additionalProperties": false,
"required": [
"data",
"type"
],
"properties": {
"data": {
"description": "Content of the transport file",
"type": [
"string",
"null"
]
},
"type": {
"description": "IANA assigned media type for file (e.g application/sdp)",
"type": [
"string",
"null"
]
}
}
},
"transport_params": {
"description": "Transport-specific parameters",
"oneOf": [{
"$ref": "v1.0_receiver_transport_params_rtp.json"
},
{
"$ref": "v1.0_receiver_transport_params_dash.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": "application/sdp"
},
"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": "application/sdp"
},
"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 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 the transport file could not be parsed, or there is some failure caused by activation which was not caused by a violation or 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
}
Get active receiver parameters. 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.
get /single/receivers/{receiverId}/active
Get active receiver parameters. 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.
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": "v1.0-activation-response-schema.json"
},
"transport_file": {
"type": "object",
"description": "Transport file parameters",
"additionalProperties": false,
"required": [
"data",
"type"
],
"properties": {
"data": {
"description": "Content of the transport file",
"type": [
"string",
"null"
]
},
"type": {
"description": "IANA assigned media type for file (e.g application/sdp)",
"type": [
"string",
"null"
]
}
}
},
"transport_params": {
"description": "Transport-specific parameters",
"oneOf": [{
"$ref": "v1.0_receiver_transport_params_rtp.json"
},
{
"$ref": "v1.0_receiver_transport_params_dash.json"
}
]
}
}
}
Examples:
running-state:
{
"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=1; framerate=25; colorimetry=BT709-2\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\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
}]
}
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