Deliver a live stream from Live Ingest

You create the connector that takes a live stream into Azion, and the rule that delivers that stream to viewers, from Azion Console, the Azion API, or the Azion CLI. For an HLS stream that your own origin produces, refer to Enforce HLS cache for live streaming.

Your encoder pushes the stream over RTMP to Live Ingest, which converts it to HLS: a playlist, .m3u8, and the segments it lists, .ts. Viewers never reach Live Ingest directly. They request the stream from an application, and a rule of that application names the connector.

mermaid

%%{init: {"layout": "dagre", "themeVariables": {"fontSize": "13px"}, "flowchart": {"nodeSpacing": 12, "rankSpacing": 12, "padding": 6, "wrappingWidth": 70, "minNodeWidth": 40, "useMaxWidth": true}}}%%

02flowchart TD

03 Encoder["Encoder"] -->|"RTMP to the region of the connector"| LI["Live Ingest converts the stream to HLS"]

04 LI --> Connector["connector of type live_ingest"]

05 Player["Viewer's player"] -->|"HTTPS request"| Rule["application rule: Set Connector"]

06 Rule --> Cache["Enforce HLS cache: playlist 5 seconds, segment 60 seconds"]

07 Cache -->|"miss or expired copy"| Connector

08 Cache -->|"valid copy"| Player

The encoder pushes the stream over RTMP to Live Ingest, in the region of the connector.
Live Ingest converts the stream to HLS.
A viewer’s player requests the stream from the application, and a rule’s Set Connector behavior names the connector.
Azion adds the Enforce HLS cache behavior to that rule, which caches each playlist for 5 seconds and each segment for 60 seconds.
A valid cached copy answers every viewer, and only an expired or missing copy is fetched through the connector.

Prerequisites

An application served by a workload, with a hostname that viewers request. To create both, refer to Applications quickstart.
An encoder that pushes RTMP with username and password authentication. Azion provides the credentials and the ingest URLs of a primary and a backup endpoint. For the requirement, refer to Ingestion.
A personal token, for the API procedures.
The Azion CLI installed and authorized, for the CLI procedures.
Access to Azion Console, for the Console procedures. Refer to Access Azion Console.

This guide does not cover how you obtain the ingest URLs and credentials, or the URL layout of the playlist that viewers request. The examples use my-live-connector for the connector and us-east-1 for the region. Replace them with your values.

Create the Live Ingest connector

The connector carries one setting, the region where Live Ingest receives the stream. Choose the region closest to the encoder, not to the viewers: it shortens the path the stream travels before Azion receives it. The region accepts us-east-1, us-east-2, br-east-1, br-east-2, and br-east-3.

To create the connector in Azion Console:

Open the Connectors page

Access Azion Console > Connectors.

Start a new connector

The Create Connector page opens.

Name the connector

In General, enter my-live-connector as the Name.

Select the Live Ingest type

In Connector Type, select Live Ingest.

Select the region

In Region, select us-east-1. The field is required.

Select Create

The my-live-connector connector exists in your account in us-east-1.

To create the connector, send its name, its type, and its region to the connectors endpoint:

Shell

01curl --request POST \

02 --url https://api.azion.com/v4/workspace/connectors \

03 --header 'Authorization: Token <personal-token>' \

04 --header 'Content-Type: application/json' \

05 --data {

06 "name": "my-live-connector",

07 "type": "live_ingest",

08 "attributes": { "region": "us-east-1" }

09}

The API answers 202 with "state": "pending", and the connector reads back with "attributes": {"region": "us-east-1"}. Record its id: the rule names the connector by it. A request without region fails with 10059, and a region outside the five values fails with 10039.

To create the connector with the Azion CLI, save its body as connector.json:

JSON

01{

02 "name": "my-live-connector",

03 "type": "live_ingest",

04 "attributes": { "region": "us-east-1" }

05}

Create the connector from the file. The command needs --type even when the file names the type:

azion create connector --type live_ingest --file connector.json

The output carries the ID of the new connector, which the rule names:

Created Connector with ID <connector-id>

The connector exists in your account, and no viewer request reaches it until a rule of the application names it. A change to a connector reaches Azion’s distributed infrastructure in several minutes.

Send the viewers’ requests to the connector

A Request Phase rule with the Set Connector behavior sends the requests it matches to the connector. On an application that serves only the stream, the rule matches every path: ${uri} starts with /. When several matching rules carry Set Connector, only the last one runs, so keep this rule after any rule that sends every path to another connector. A new rule goes after the rules the application already has.

To create the rule in Azion Console:

Open the application

Access Azion Console > Applications, and select the application that delivers the stream.

Select the Rules Engine tab

Select + Rule

Name the rule

In General, enter send-to-live-ingest as the Name.

Select the request phase

In Phase, select Request Phase.

Set the criterion

Under Criteria, select the variable ${uri} and the operator starts_with, and enter / as the argument.

Select the Set Connector behavior

Under Behaviors, select Set Connector.

Select the Live Ingest connector

In Connector, select my-live-connector. Azion adds the Enforce HLS cache behavior to the rule.

Select Save

The rule appears in the Rules Engine tab, under the Request heading.

To create the rule, send it to the Request Phase rules of the application. Replace <connector-id> with the id of the connector:

Shell

01curl --request POST \

02 --url https://api.azion.com/v4/workspace/applications/<application-id>/request_rules \

03 --header 'Authorization: Token <personal-token>' \

04 --header 'Content-Type: application/json' \

05 --data {

06 "name": "send-to-live-ingest",

07 "active": true,

08 "criteria": [[{ "variable": "${uri}", "conditional": "if", "operator": "starts_with", "argument": "/" }]],

09 "behaviors": [{ "type": "set_connector", "attributes": { "value": <connector-id> } }]

10}

The API answers 202 with a state of pending and the rule as the platform stored it. Enforce HLS cache has no API type to send, because Azion adds it to the rule.

To create the rule with the Azion CLI, keep it in a file, because on a command line the shell would expand ${uri}. Save this body as rule.json, and replace <connector-id> with the ID of the connector:

JSON

01{

02 "name": "send-to-live-ingest",

03 "active": true,

04 "criteria": [[{ "variable": "${uri}", "conditional": "if", "operator": "starts_with", "argument": "/" }]],

05 "behaviors": [{ "type": "set_connector", "attributes": { "value": <connector-id> } }]

06}

Create the rule in the request phase of the application:

azion create rules-engine --application-id <application-id> --phase request --file rule.json

The output carries the ID of the new rule:

Created Rules Engine with ID <rule-id>

Every request of the application now reaches the stream through the connector, under the live HLS cache policy. A new rule can take a few minutes to propagate.

Keep the cache of the stream to Enforce HLS cache

Enforce HLS cache bypasses the cache settings of the application and applies the cache policy Azion defines for live HLS. A cache setting that a Set Cache Policy behavior applies to these requests therefore has no effect, so do not add one. To confirm the rule carries the policy:

Open the Rules Engine tab of the application

Access Azion Console > Applications, select the application, and select the Rules Engine tab.

Open the send-to-live-ingest rule

Read the behaviors

The rule carries Set Connector, naming my-live-connector, and Enforce HLS cache.

The application caches each playlist for 5 seconds and each segment for 60 seconds. One cached copy of a segment answers every viewer who requests it in that time, so a large audience does not send each of its requests to Live Ingest.

Live Ingest is billed on Data Ingestion, the volume of stream data that Azion ingests, and a test transmission is ingested like a real one. For the rate, refer to Pricing.

Next steps

Ingestion and deliveryHow Live Ingest takes the stream in a region, and how the application delivers it.Connectors best practicesRedundant endpoints, encoder settings, player fallback, alerts, and a load test before the event.Query Live Ingest connected usersCount the unique sessions of the stream per host, during and after the event.Stream live events to large audiencesA live event delivered from Live Ingest to a large audience, with its values and checks.