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 encodername
: The name of the encoder.randomize_segment_urls
: Have the encoder create non-predictable urls in the manifests.entrypoint_id
: Theentrypoint_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 parameterskey_service
: The key service url
playready{}
: PlayReady encryption parameterskey_service
: The key service url
fairplay{}
: Fairplay encryption parameterskey_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 stream
s, 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 method
s 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" : "100.26.179.251/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 entrypointname
: 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. Iftype == rtmp
then this will be an rtmp url such as rtmp://livein.apis.anvato.net/live/. If type == mpegts
then this will be anip: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=100.26.179.251/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. |