✏️

This is a beta feature and may have incomplete functionality or bugs; breaking changes may be introduced.

Feeds

Feeds represent the connection between a source and a destination. A feed can include one or more flows.

Flows

👉

The flow concept is not visible in the UI.

Flows are part of the Flows API.

Flows are API resources that represent either or both of the following:

• Transmission of content from one place to another.
• Transformation of content from one format to another.

Examples of things flows can do:

• Stream content from one site to another site (e.g. Set up on-prem contribution).
• Transcode content from one bitrate to another.
• Transcode content from one format to another (e.g. h.264 to HEVC).
• Retransmit content from one transport protocol to another (e.g. multicast UDP/RTP to SRT).

A simple SaaS transcode flow can be created with:

PUT https://api.mk.io/api/projects/myproject/v1/flow/flows/sports1

{
    "metadata": {
        "displayName": "Sports 1",
    },
    "spec": {
        "siteName": "westus2",
        "mode": "Active",
        "transformName": "h264-transcode",
        "inputs": [
            {
                "contentName": "sports1",
                "transformInput": "encoding/input_1/source_1"
            }
        ],
        "outputs": [
            {
                "destinationName": "sports1-affliate",
                "transformOutput": "encoding/output_1"
            }
        ]
    }
}

Flows tend to fall into one of three categories:

Whilst the categorisation is not important to MK.IO and the categories are not mutually exclusive within a flow, it can help to describe the common usages of flows and therefore help to plan a system.

An end-to-end flow would be connected as follows:

📘

Solid arrows represent direct references, dashed arrows represent references that are calculated automatically by SERVICENAME.

A pair of upstream/downstream flows would be connected as follows.

📘

Note that in the upstream/downstream flow case, the dashed arrows that represent automatic system assignments can point to sources or internal flow outputs.

Anatomy of a flow

A flow:

• Can be activated and deactivated.
• Runs on a site (is also assigned to a device on an on-prem site).
• Has flow inputs that always reference content.
• Has flow outputs that optionally reference a destination.
• Optionally references a flow transform.

Flow inputs and outputs

A flow input is how a flow specifies the content it will ingest. When content is referenced by a flow, it must be resolved to actual streams of data the flow can use; the process by which this happens is described in Resolving content.

A flow output represents a stream of content that will come out of the flow. Flow outputs can send content directly to a destination or they can omit the destination to become an internal flow output and be used to send content to a downstream flow.

If a flow references a transform, flow inputs and outputs must link internally to the inputs and outputs of the transform. For example:

In the diagram above, the flow is being directly fed by a source and output 1 directly references a destination, so the flow is behaving as an end-to-end flow in this regard. Note also though, that output 0 and output 2 do not reference destinations, so they are internal flow outputs that allow this flow to behave as an upstream flow. This illustrates that, as described earlier, flows do not have to fit exactly and exclusively into one of the 3 categories: end-to-end, upstream or downstream.

🎓

To learn more about the practical uses of internal flow outputs, read Set up on-prem site-to-site contribution .

Flow refiners

refiners can be added to the flow inputs and outputs or to the flow itself. For an overview on refiners, read Refiners.

Flows will be assigned to a devices if they reference an on-prem site, so a device refiner is supported directly on the flow to allow the device assignment to be constrained.

Flow input refiners

Flow inputs can be fulfilled by upstream flows and sources, so refiners are supported that target both kinds of resource. Sources and flows can provide content over a network, so a network refiner is supported to allow the network assignment to be constrained.

When a flow refiner is used on a flow input, the content must come from a flow; when a source refiner is used, the content must come from a source. Source and flow refiners must therefore not be used at the same time on the same flow input. Network refiners can be used in conjunction with both source and flow refiners.

📘

Flows inputs always select sources by label and not by name, this is to encourage the use of sources that can be added and removed dynamically without needing to recreate flows. If a flow input does need a specific source, add a label to the source that is unique enough.

Flow output refiners

Flow outputs can provide content over a network, so a network refiner is supported to allow the network assignment to be constrained.

Monitoring

Thumbnails

Some flows (depending on the transform type used) can generate thumbnails and other metadata such as audio levels for the content they handle. The URLs of this data are available from the status section of the flow. The get request below omits most of the fields in the response, but includes the monitoring field:

GET https://api.mk.io/api/projects/myproject/v1/flow/flows/sports1

{
    "kind": "Flow",
    "metadata": {},
    "spec": {},
    "status": {
        "monitoring": {
            "encoding": {
                "thumbnailUrl": "https://qotgdxhvhuiussdbwdqd.blob.core.windows.net/flow-afdc6d48-bf33-4932-899f-5c221b9d5c9b/thumbnail.jpg?st=2024-10-25T09%3A11%3A53Z&se=2034-09-03T09%3A11%3A53Z&sp=rl&sv=2024-05-04&sr=c&sig=h5HM96Lab%2BbyZuVVNZyy322JUE26vNAroc7EyThzYIQ%3D",
                "metadataUrl": "https://qotgdxhvhuiussdbwdqd.blob.core.windows.net/flow-afdc6d48-bf33-4932-899f-5c221b9d5c9b/metadata.json?st=2024-10-25T09%3A11%3A53Z&se=2034-09-03T09%3A11%3A53Z&sp=rl&sv=2024-05-04&sr=c&sig=h5HM96Lab%2BbyZuVVNZyy322JUE26vNAroc7EyThzYIQ%3D"
            }
        }
    }
}

The encoding key under status.monitoring varies according to the type and configuration of flow transform referenced by the flow. It is recommended that API clients reading the monitoring dictionary iterate the key/value pairs rather than looking for specific keys.

Whitelisting

For on-prem sites, whitelisting may be required for devices to allow thumbnails to be uploaded to blob storage:

• *.blob.core.windows.net HTTPS port 443 (with wildcard) - to allow upload of monitoring thumbnails (and related metadata)

🚧

The blob storage URLs may change in future which could require updates to whitelisting rules. However, a notice period will be provided.