Live Streaming API

Welcome to the Anvato Live Stream and Ingest documents.

Authentication

To access any of the API functions you must use an API token (MCP-TOKEN). Please see the MCP API documentation to see how you can obtain an MCP-TOKEN.

Include the token in the header in the following format, same as other APIs:

Authorization: MCP-TOKEN token=your-access-token

Features

Unlimited recording of your stream in the cloud.

Easily create clips (Live-to-VOD) from your recorded streams.

Use the APIs to view the recorded streams and create your own clip and monitoring tool.

Encoder

Example encoder object

{
    "id": "577eea6d-760a2c8a-85c2-4687-ab10-bedbe2925dd9",
    "state" : "running",
    "name": "My Live Stream",
    "entrypoint_id" : "577eea6d-c785955b-d46d-42af-a930-7c6012d941db",
    "m3u8_master_path" : "/577eea6d-760a2c8a-85c2-4687-ab10-bedbe2925dd9/master.m3u8",
    "dash_manifest_path" : "/577eea6d-760a2c8a-85c2-4687-ab10-bedbe2925dd9/manifest.mpd",
    "common_encryption" : {
    },
    "randomize_segment_urls" : true,
    "streams" : [
        {
            "format" : "hls",
            "video_width": 640,
            "video_height": 360,
            "video_bitrate" : 1200000,
            "audio_bitrate" : 96000,
            "video_codec" : "h264-main",
            "audio_codec" : "aac-he",
            "method" : "http-post",
            "http_post_path" : "http://my-cdn-ingest/"
        },
        {
            "format" : "hls",
            "video_width": 960,
            "video_height": 540,
            "video_bitrate" : 2500000,
            "audio_bitrate" : 96000,
            "video_codec" : "h264-main",
            "audio_codec" : "aac-he",
            "method" : "http-post",
            "http_post_path" : "http://my-cdn-ingest/"
        }
    ]
}

Encoders create multiple renditions of the ingested rtmp entrypoints and send the segments and fragments to the storage location of your choice.

An encoder object has this structure:

id: Assigned ID of the encoder
name: The name of the encoder.
randomize_segment_urls: Have the encoder create non-predictable urls in the manifests.
entrypoint_id: The entrypoint_id to use the stream from.
m3u8_master_path: Relative path of the master m3u8 file.
dash_manifest_path: Relative path of the dash manifest file.
common_encryption{}: An object that specifies the details of the common encryption key services. The following keys are supported: widevine, playready, fairplay
- widevine{}: Widevine encryption parameters
  - key_service: The key service url
- playready{}: PlayReady encryption parameters
  - key_service: The key service url
- fairplay{}: Fairplay encryption parameters
  - key_service: The key service url

Core concepts

Streams

Encoder creates lock-step, closed GOP, independently decodable segments and fragments with the specified codec parameters. Each of these are called a stream. Each stream can optionally be encrypted with common encryption.

The encoder has limits on a single encoded set. The following encoded set cannot be exceeded: single 1080p, single 720p, single 540p, single 360p stream and a single 180p stream.

The encoded set is defined by the unique encodings among your streams. If only the format and delivery method changes across to streams, then this only counts as one encoding. .e.g,

Stream 1 { "format" : "hls", "video_width": 960, "video_height": 540, "video_bitrate" : 2500000, "audio_bitrate" : 96000, "video_codec" : "h264-main", "audio_codec" : "aac-he", "method" : "http-post", "http_post_path" : "http://my-cdn-ingest/" }

Stream 2 { "format" : "dash", "video_width": 960, "video_height": 540, "video_bitrate" : 2500000, "audio_bitrate" : 96000, "video_codec" : "h264-main", "audio_codec" : "aac-he", "method" : "ftp", "ftp_path" : "ftp://user@pass:my-cdn-origin/" }

Since these streams share the same encoding parameters they count as a single encoding at 540p.

Storage

The storage location can be a private server of yours that supports FTP or HTTP-POST, or it can be common CDNs such as Google CDN, Akamai or Level3.

Another common use case is to send the segments and fragments to Google Storage or Amazon S3 and use those destinations as origins for a caching CND layer.

The following storage methods are supported:

http-post: Encoder performs an HTTP POST to the given location.
- http_post_path: The HTTP POST destination including the username and password if any (e.g., http://user:pass@server.com/...). The encoder will create sub-folders based on directory-rolling, bitrate and format.
ftp: Encoder performs an FTP PUT to the given location.
- ftp_path: The FTP destination including the username and password (e.g., ftp://user:pass@server.com/...). The encoder will create sub-folders based on directory-rolling, bitrate and format.
s3: Encoder stores the segments at the performs an HTTP POST to the given location.
- ftp_path: The FTP destination including the username and password (e.g., ftp://user:pass@server.com/...). The encoder will create sub-folders based on directory-rolling, bitrate and format.

Directory roll-over

As the encoder creates segments and fragments, the directory portion of the path will be changed at about every 1000 segments.

Error Handling

Retries: In case of errors during segment and manifest transfers, the encoder will retry. The retry number and time is adaptive and depends on the past condition of the stream. Hoeever, if the error is non-recoverable, such as 403, encoder will not retry.
Bandwidth checks: If segments are uploading too slow to complete in time, encoder will terminate the connection and attempt to create a new connection.
Error logs: All error logs are reported in the logging API of the encoder. The logs include the
DNS resolutions: DNS resolutions are cached until a server-side error occurs. This includes: a 5XX response, connect timeout, or a TCP RST.

Encoder Control

Once the encoder is started you have full access to the Live Encoder API (see documentation) through the encoder API point. Note that once the encoder is stopped all of the /media and /script queries will reset.

Get a specific encoder

curl https://live-ingest.anvatoapis.net/latest/encoder/<ID> \
  -H "Authorization: MCP-TOKEN token=your-access-key"

This endpoint retrieves a specific encoder

Endpoint

GET /encoder/<ID>

Query Parameters

None.

Response

An encoder object or non-2XX code in case of error.

Get all encoders

curl https://live-ingest.anvatoapis.net/latest/encoder \
  -H "Authorization: MCP-TOKEN token=your-access-key"

This endpoint retrieves all encoders.

Endpoint

GET /encoder

Query Parameters

Parameter	Default	Description
page_no	0	0 based page number.
page_sz	20	Number of items in the requested page.

Response

encoder objects or non-2XX code in case of error.

Create or Update an encoder

curl https://live-ingest.anvatoapis.net/latest/encoder/<ID_OR_EMPTY>" \
  -d name=My+first+encoder \
  -H "Authorization: MCP-TOKEN token=your-access-key"

This endpoint creates a new encoder or updates an existing one if the id is specified.

Endpoint

POST /encoder/<ID>

Query parameters

Parameter	Mandatory	Description
`name`	no	The name of the encoder.
`randomize_segment_urls`	no	Default: `true`
`entrypoint_id`	no	The `entrypoint_id` to use the stream from.
`common_encryption`	no	JSON encoded `common_encryption` specification.

Response

{ "success" : true, "id": "<ID>" }

Delete an encoder

curl https://live-ingest.anvatoapis.net/latest/encoder/<ID> \
  -X DELETE \
  -H "Authorization: MCP-TOKEN token=your-access-key"

This endpoint deletes an encoder.

Endpoint

DELETE /encoder/<ID>

Query parameters

None

Response

2XX if successful, non-2XX if fails.

Entrypoint

Example entrypoint object

{
    "id": "577eea6d-c785955b-d46d-42af-a930-7c6012d941db",
    "name": "My Live Channel",
    "type": "mpegts",
    "region": "us-west",
    "url" : "livein-east.apis.anvato.net:4431",
    "whitelist_cidr" : "3.226.248.180/32",
    "record" : true
}

Entrypoints are the main live ingest objects. For every live stream you have, you should create an RTMP entrypoint.

An entrypoint object has this structure:

id: ID of the entrypoint
name: The name of the entrypoint.
type: The stream name for your encoder's settings.
region: The hst and app name for your encoder's settings.
url: (read-only) The url assigned to this entrypoint. If type == rtmp then this will be an rtmp url such as rtmp://livein.apis.anvato.net/live/. If type == mpegts then this will be an ip:port.
whitelist_cidr: IPs in CIDR notation to whitelist that are allowed to publish to and pull from this entrypoint. Comma separate multiple values.
record: Flag that enables or disables recording of this stream. A non-recorded stream is useful for reviewing your streams before starting your live encoding.
egress_point: The egress host and port of the stream exposed via TCP (e.g., tcp://1139837615.live-egress.apis.anvato.net:5546). Only whitelisted IPs can access this host and port.
preview_url: A 30-second HTTP preview url that is accessible via HTTP. (e.g., https://live.apis.anvato.net/preview/ns1WqRvw482648r72bXk9zhk1ag4rg3aiOpfqsLimoa)

Entrypoint security is enforced by IP whitelisting.

Get a Specific Entrypoint

curl https://live-ingest.anvatoapis.net/latest/entrypoint/<ID> \
  -H "Authorization: MCP-TOKEN token=your-access-key"

This endpoint retrieves a specific entrypoint

Endpoint

POST /entrypoint/<ID>

Query Parameters

None.

Response

An entrypoint object or non-2XX code in case of error.

Get All Entrypoints

curl https://live-ingest.anvatoapis.net/latest/entrypoint \
  -H "Authorization: MCP-TOKEN token=your-access-key"

This endpoint retrieves all entrypoints.

Endpoint

GET /entrypoint

Query Parameters

Parameter	Default	Description
page_no	0	0 based page number.
page_sz	20	Number of items in the requested page.

Response

entrypoint objects or non-2XX code in case of error.

Create or Update an Entrypoint

curl https://live-ingest.anvatoapis.net/latest/entrypoint/<ID_OR_EMPTY>" \
  -d name=My+stream \
  -d whitelist_cidr=3.226.248.180/32
  -H "Authorization: MCP-TOKEN token=your-access-key"

This endpoint creates a new entrypoint or updates an existing one if the id is specified.

Endpoint

POST /entrypoint/<ID>

Query parameters

Parameter	Mandatory	Description
`name`	no	The name of the entrypoint.
`whitelist_cidr`	no	Comma separated whitelisted IPs in CIDR notation.

Response

{ "success" : true, "id": "<ID>" }

Delete an Entrypoint

curl https://live-ingest.anvatoapis.net/latest/entrypoint/<ID> \
  -X DELETE \
  -H "Authorization: MCP-TOKEN token=your-access-key"

This endpoint deletes an entrypoint

Endpoint

DELETE /entrypoint/<ID>

Query parameters

None

Response

2XX if successful, non-2XX if fails.

Previewing an Entrypoint

You can programmatically preview the raw streams received at each entrypoint. Take the preview_url in the entrypoint object, and play with a player such as VLC player, e.g.,

VLC

vlc https://live.apis.anvato.net/preview/ns1WqRvw482648r72bXk9zhk1ag4rg3aiOpfqsLimoa

Pull Egress

You can use the egress_point of the entrypoint object for pass-thru pulling of the streams.

ffmpeg

ffmpeg -i tcp://1139837615.live-egress.apis.anvato.net:5546 udp://226.1.1.1:5555?pkt_size=1316

Editing

Stream API allows you to preview the recorded media, create snapshots, thumbnails and clips.

Video Preview

This endpoint provides a Flash compatible FLV stream from the given timestamp. Each frame is enriched with onMetaData() events for full frame accurate absolute timestamps. You can use these timestamps to uniquely identify a position in the stream. This timestmap is consistent and frame-accurate across all APIs such as thumnbnail, snapshot and clips.

Endpoint

/edit/<ENTRYPOINT_ID>/preview

Query parameters

Parameter	Default	Description
ts	Current timestamp	Absolute timestamp to create the preview from

Thumbnails

This endpoint provides small thumbnails generated at the key frames of the recorded stream.

Endpoint

/edit/<ENTRYPOINT_ID>/thumbnails

Query parameters

Parameter	Default	Description
ts_begin	Current timestamp	Start of the thumbnail window as absolute timestamp.
ts_end	Current timestamp	End of the thumbnail window as absolute timestamp.

Clip creation

This endpoint creates a clip from the specified timestamps.

Endpoint

/edit/<ENTRYPOINT_ID>/clip

Query parameters

Parameter	Default	Description
ts_begin	Current timestamp	Start of the clip window as absolute timestamp.
ts_end	Current timestamp	End of the clip window as absolute timestamp.

High Resolution Snapshot

This endpoint creates a high resolution snapshot at the specified timestamp.

Endpoint

/edit/<ENTRYPOINT_ID>/snapshot

Query parameters

Parameter	Default	Description
ts	Current timestamp	Absolute timestamp to create the snapshot at.

Errors

The MCP API uses the following standard error codes:

Error Code	Meaning
400	Bad Request -- There was an error with your request, such as missing mandatory field or invalid value.
401	Unauthorized -- Your API key/token is wrong.
403	Forbidden -- Your access level does not allow the requested operation.
404	Not Found -- Object or endpoint does not exist.
405	Method Not Allowed -- Object or endpoint does not support the specified method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- Object was deleted and is no longer available.
429	Too Many Requests -- You must decrease your request rate.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarially offline for maintanance. Please try again later.