NAV
     

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:

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:

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

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" : "54.196.190.32/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:

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=54.196.190.32/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.