Set up transports on sources and destinations

Each transport type has a specific way to configure it. This guide goes through the transport types and explains how to set them up in the context of sources and destinations.

SRT

SRT transports come in two forms: listeners and callers. Both kinds of SRT transport support encryption by allowing the encryption standard (e.g. AES128) and pass phrase to be configured.

SRT listener

An external SRT listener is associated with a URL. The SRT caller that MK.IO creates, must call to the SRT listener's URL. See the source creation example below:

PUT https://api.mk.io>/api/projects/myproject>/v1/flow/sources/sports1-primary

{
    "metadata": {
        "displayName": "Sports 1 - Primary"
    },
    "spec": {
        "contentName": "sports1",
        "networkName": "internet",
        "transport": {
            "type": "SRTCaller",
            "urls": ["srt://10.1.1.1:5000"],
            "encryptionStandard": "AES128",
            "passPhrase": "chooseasecret"
        }
    }
}

Destination transports are configured in the same way:

PUT {user.APIURL}/api/projects/myproject/v1/flow/destinations/sports1-affiliate

{
    "metadata": {
        "displayName": "Sports 1 - Affiliate"
    },
    "spec": {
        "networkName": "internet",
        "transport": {
            "type": "SRTCaller",
            "urls": ["srt://10.1.1.1:5000"],
            "encryptionStandard": "AES128",
            "passPhrase": "chooseasecret"
        }
    }
}

SRT caller

Where MK.IO models an external SRT caller, it must create a listener that is available to be called on a URL by the external SRT caller. The mechanism for exposing the listener URL varies depending on the system infrastructure. For example, SaaS sites requires public IP address / URL reservation and on-prem sites do not.

SaaS sites

In a SaaS site, a public IP address / URL must be reserved for the SRT listener that MK.IO will create. To reserve a public IP address / URL, include the spec.transport.ipResource field and set spec.transport.ipResource.type to External. See the example below:

PUT https://api.mk.io/api/projects/myproject/v1/flow/sources/sports1-primary

{
    "metadata": {
        "displayName": "Sports 1 - Primary"
    },
    "spec": {
        "contentName": "sports1",
        "networkName": "internet",
        "transport": {
            "type": "SRTListener",
            "port": 5000,
            "ipResource": {
                "type": "External"
            },
            "encryptionStandard": "AES128",
            "passPhrase": "chooseasecret"
        }
    }
}

To discover the IP address / URL that was reserved by MK.IO, get the resource after creation. Get periodically until the status.urls list is populated:

GET https://api.mk.io>/api/projects/myproject/v1/flow/sources/sports1-primary

{
    "metadata": {
        "displayName": "Sports 1 - Primary"
    },
    "spec": {
        "contentName": "sports1",
        "networkName": "internet",
        "transport": {
            "type": "SRTListener",
            "port": 5000,
            "ipResource": {
                "type": "External"
            },
            "encryptionStandard": "AES128",
            "passPhrase": "chooseasecret"
        }
    },
    "status": {
        "urls": ["srt://10.1.1.1:5000"]
    }
}

On-prem sites

For on-prem sites, the External IP resource type is not valid since there is no public cloud to reserve the IP address from. In this case, omit the spec.transport.ipResource field.

PUT https://api.mk.io/api/projects/myproject/v1/flow/sources/sports1-primary

{
    "metadata": {
        "displayName": "Sports 1 - Primary"
    },
    "spec": {
        "contentName": "sports1",
        "networkName": "internet",
        "transport": {
            "type": "SRTListener",
            "port": 5000,
            "encryptionStandard": "AES128",
            "passPhrase": "chooseasecret"
        }
    }
}

For on-prem sites, get the URL by reading it from the status.urls list in the same way as for SaaS sites. The IP address in the status URL will be the IP address of the device where the flow using the source is assigned. If it is necessary to make the IP address more static than the lifetime of an active flow, refiners can be used. For example:

refine the flow to a specific device, see Flow refiners, and/or
refine the flow input to a specific source label, see Flow input refiners.

UDP

UDP transports allow content carried inside MPEG2-TS to be ingested or sent. This can be multicast (on multicast enabled networks) or unicast and optionally wrapped in RTP. For example, a source representing content over a source-specific multicast could be represented with:

PUT https://api.mk.io/api/projects/myproject/v1/flow/sources/sports1-primary

{
    "metadata": {
        "displayName": "Sports 1 - Primary"
    },
    "spec": {
        "contentName": "sports1",
        "networkName": "internet",
        "transport": {
            "type": "UDP",
            "urls": ["udp://[email protected]:5000"]
        }
    }
}

Here the URL uses the UDP scheme as RTP is auto-detected for ingress and would be supported anyway. If the ingress multicast is not source-specific, set the entry inurls to udp://239.0.0.1:5000.

For a destination, if we wanted to explicitly wrap the MPEG2-TS in RTP, we would included it in the URL scheme, e.g.:

PUT https://api.mk.io>/api/projects/myproject/v1/flow/destinations/sports1-affiliate

{
    "metadata": {
        "displayName": "Sports 1 - Affiliate"
    },
    "spec": {
        "networkName": "internet",
        "transport": {
            "type": "UDP",
            "urls": ["rtp://239.0.0.2:5000"]
        }
    }
}

SDI

SDI transports allow uncompressed content to be ingested or sent. Ingest and transformation of uncompressed content is called 'encode'. Taking encoded content and transforming it back into uncompressed content is called 'decode'. To create a source that represents uncompressed content over SDI for an encode, use:

PUT https://api.mk.io/api/projects/myproject>/v1/flow/sources/sports1-primary

{
    "metadata": {
        "displayName": "Sports 1 - Primary"
    },
    "spec": {
        "contentName": "sports1",
        "networkName": "internet",
        "transport": {
            "type": "SDI",
            "urls": ["sdi://device1/board_1_connector_1"]
        }
    }
}

To create a destination that represents uncompressed content over SDI for an decode, use:

PUT https://api.mk.io/api/projects/myproject/v1/flow/destinations/sports1-affiliate

{
    "metadata": {
        "displayName": "Sports 1 - Affiliate"
    },
    "spec": {
        "networkName": "internet",
        "transport": {
            "type": "SDI",
            "urls": ["sdi://device1/board_1_connector_2"]
        }
    }
}

An entry within the spec.transport.urls list follows a specific format:

sdi://<device_name>/board_<board_index>connector<connector_index>

The device_name creates a hard reference to a device; the board_index and connector_index create a hard reference to a device interface. This means that a flow that resolves the content on a flow input to the SDI source, must be assigned to the specified device and the specified SDI interface cannot be shared with other active flows.