IS 05 Client

Please refer to the Generic API Client page as a starting point before considering the specifics below.

This guide assumes that the Senders and Receivers used by IS-05 have already been discovered, most likely by using the IS-04 mechanisms described here.

Basic Guide to Making a Connection

1. If required, set the transport parameters (IP addresses, port etc) on the Sender IS-05 API in the /staged endpoint.
2. Activate the changes to the Sender transport files. If desired, this can be done in the same PATCH request as step 1.
3. Download the SDP from the /transportfile endpoint of the sender.
4. Stage the transportfile to the /staged endpoint of the Receiver.
5. Perform or schedule an activation. This can be done in the same PATCH request as step 4.
6. If performing a scheduled activation, check back after the activation was due to complete to ensure the Sender is in the expected state.

Unicast Streams

The guidance above applies to both unicast and multicast streams. However, if the stream is unicast, the sender must be supplied with the address of the receiver during step one using the "receiver_ip" transport parameter. If the receiver is an NMOS device, the "receiver_id" field should also be populated with the UUID of the receiver as recorded in the IS-04 registry.

Best Practice

• Where making requests to a large number or Senders/Receivers on the same Device, make use of the /bulk endpoint to bundle them into a single request.
• Use the IS-04 Query API websocket to monitor version timestamp increments on Devices being controlled. A version timestamp increment may indicate that another controller has changed the transport parameters, and as such any information cached by the client may be stale.
• When altering the transport parameters in the /staged endpoint, check the /constraints endpoint to check the available choices of parameters accepted by a particular sender and receiver.
• Bear in mind when PATCHing to the transport parameters that parameters may have changed since your last get. Therefore it is important to set parameters that are important for your connection (e.g master_enable/rtp_enable) in the PATCH request, even if the client believes they are already set as required.
• When working with an NMOS Sender the controller should include the Sender UUID to the receiver using the sender_id parameter.

Identifying Active Connections

In order to populate the ‘subscription’ attribute of IS-04 Senders and Receivers, the Connection Management API includes keys for ‘sender_id’ and ‘receiver_id’ in its staged parameters. These should be used to signal that a Sender or Receiver is being connected to another NMOS compatible Sender or Receiver.

Support For Legacy IS-04 Connection Management

The Connection Management API supersedes the now deprecated method of updating the ‘target’ resource on Node API Receivers in order to establish connections. The two methods of operation are likely to co-exist until Version 2.0 of IS-04. As such the following best practice should be followed when both are in use:

• Where a client updates the Node API subscription, the result on the Connection Management API should be the same as if the client had first staged the parameters and then called an immediate activation. That is to say that the new parameters will be reflected both in the staged and active endpoints of the Receiver.
• Where a client updates a Connection Management API Receiver the active ‘sender_id’ parameter should be populated in the Node API subscription parameter with key ‘sender_id’.
• After a Connection Management API activation the corresponding Sender or Receiver’s ‘version’ property should be updated to the instant of the activation.

Should staged modifications be present when a legacy activation is performed, these parameters must be discarded in favour of those provided via the Node API interface.