HLS Monitoring API Overview
HLSAnalyzer.com is an online HLS analyzer and monitoring service. We follow the official HTTP Live Streaming specification (RFC 8216) and check for a variety of error conditions as well as HLS conformance points. For any HLS stream, we initialize the playlist buffer with segment durations that are greater than 3 times the target duration. We maintain this buffer with the arrival of each new segment while taking to account the real elapsed time in the playlist refresh cycle.
For private monitoring of streams, we provide an API for adding, removing, and alerting on outages of Live and VOD HLS Streams. With our simple HTTP-Based API, your team can monitor Live HLS streams and receive alerts when a stream stops publishing playlists or segments. These APIs also allow for automated testing of streams in CI/CD development environments.
All API-based streams are private, and can only be accessed and monitored with a corresponding API key.
Contents
1.4 Configure Alert Parameters
2.2 Reset or Remove Individual Streams
2.5 Check Individual Stream Status
2.9 Select Individual Stream Alert Mode
2.13 Retrieve Analyzer Errors and Warnings
4 Cloud Monitoring and Management
6 Analyzer Error and Warning Codes
1 Browser Interface
The HLSAnalyzer.com browser-based UI can be used to add and remove streams, check the current API status, add files from a .csv file, and configure alert parameters. The interface utilizes the same API calls that are documented in the next section, ensuring a consistent experience while interacting with the HLS Analyzer monitoring server. The browser can also be used to monitor the state of all links associated with an API key in realtime.
For the best experience, the use of Google Chrome, Firefox, or Microsoft Edge is recommended.
1.1 Monitor All Streams
/monitor-hls-playlists/monitor-api/api_key/
Description: All streams associated with the particular API key will be available for inspection, via an interface similar to the following:
Features include:
- Consolidated summary of all streams being monitored:
- Total number of non-live variants
- Master playlist status and media playlist status for each stream
- Playback URL for individual stream monitoring
- LinkID for the master and variant streams
- Total monitoring time for each stream
- The estimated playback and outage values:
- For playlists with multiple variants, these numbers are averaged across all variants
- For playlists with a single variant, these numbers are the actual values for that stream
- Alert status for each stream. Alerts may be enabled or disabled globally, or individually for each stream
1.2 View API Status
All of the important parameters of the API can be monitored, including the current alert configuration state.
1.3 Perform Stream Processing
HLS streams can be added and removed from this interface. LinkIDs may be supplied for each stream, to make their identification easier. When not supplied, LinkIDs will automatically be assigned by the server when adding streams. Alerts may be individually enabled or disabled for each stream.
1.4 Configure Alert Parameters
The different alert parameters can be configured via this interface. This panel will utilize the existing API calls (/api/alertlimits, /api/alertsetup) to configure the alerting functionality of the analyzer. Please refer to the documentation for the API calls for additional information.
1.5 Batch Processing
Batch processing functions perform functions that involve a large set of streams:
- Export the currently active stream list
- Reset all stream statistics without removing them, or remove all streams (requires enablement via check-box)
- Add streams based on a CSV file with each line containing the HLS link following by an optional LinkID, as shown here:
http://www.example.com/playlist.m3u8, mylinkID2 |
https://www.example.com/playlsit2.m3u8, |
http://www.example.com/playlist3.m3u8, mylinkID3 |
2 API Specification
The monitoring interface consists of a unique API key assigned to each client. The API key will be configured with a total number of available monitoring streams and an expiration date, based on the client’s specifications.
All commands may be issued via URL query strings, with the specified formats. All responses from the analyzer will be in JSON format, with an appropriate HTML response code.
2.1 Add Individual Streams
/api/add?apikey=unique_key&m3u8=https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8[&linkid=d421d046]
Behavior: blocking, 15-second timeout
Description: Add a Master or Media HLS Playlist (.m3u8). Monitoring will start immediately after the link has been added. An internal LinkID will be generated, unless it has been specified on the query string (between 6 and 16 alphanumeric characters), in which case it will be applied to the Master playlist. All variants and their generated LinkIDs will be returned in the JSON response. The available monitoring quota for the API key will be updated.
Sample Response:
{
"link": "https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8",
"type": "Master",
"variants": {
"d421dd64": "https://bitdash-a.akamaihd.net/content/sintel/hls/video/250kbit.m3u8",
"d421e2a8": "https://bitdash-a.akamaihd.net/content/sintel/hls/video/500kbit.m3u8",
"d421e7dc": "https://bitdash-a.akamaihd.net/content/sintel/hls/video/800kbit.m3u8",
"d421ed7a": "https://bitdash-a.akamaihd.net/content/sintel/hls/video/1100kbit.m3u8",
"d421f24a": "https://bitdash-a.akamaihd.net/content/sintel/hls/video/1500kbit.m3u8",
"d421f7e2": "https://bitdash-a.akamaihd.net/content/sintel/hls/video/4000kbit.m3u8",
"d421fbfa": "https://bitdash-a.akamaihd.net/content/sintel/hls/video/6000kbit.m3u8",
"d4220168": "https://bitdash-a.akamaihd.net/content/sintel/hls/video/10000kbit.m3u8",
"d422058c": "https://bitdash-a.akamaihd.net/content/sintel/hls/audio/stereo/en/128kbit.m3u8",
"d42209ba": "https://bitdash-a.akamaihd.net/content/sintel/hls/audio/stereo/none/128kbit.m3u8",
"d4220de8": "https://bitdash-a.akamaihd.net/content/sintel/hls/audio/surround/en/320kbit.m3u8",
"d42211ba": "https://bitdash-a.akamaihd.net/content/sintel/hls/subtitles_de.m3u8",
"d422163a": "https://bitdash-a.akamaihd.net/content/sintel/hls/subtitles_en.m3u8",
"d4221a0c": "https://bitdash-a.akamaihd.net/content/sintel/hls/subtitles_es.m3u8",
"d4221edc": "https://bitdash-a.akamaihd.net/content/sintel/hls/subtitles_fr.m3u8"
},
"linkid": "d421d046"
}
2.2 Reset or Remove Individual Streams
/api/reset?apikey=unique_key&m3u8=https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8
/api/reset?apikey=unique_key&linkid=d421d046
/api/remove?apikey=unique_key&m3u8=https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8
/api/remove?apikey=unique_key&linkid=d421d046
Behavior: blocking, 15-second timeout
Description: Remove or reset a Master or Media HLS Playlist by specifying either the m3u8 or the LinkID. Resetting a stream will initialize all monitoring parameters and alerts, whereas removing a stream will completely delete it and all its associated records from the system. Removing or resetting a Master playlist will also affect all of its variants. Only the top-level LinkID for a stream can be specified (individual variants within a master playlist cannot be reset or removed).
Sample Response:
{
"link": "https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8",
"linkid": "d421d046"
}
2.3 Remove All Streams
/api/remove?apikey=unique_key
Behavior: non-blocking, use the status command to confirm the removal of all links
Description: Remove all streams associated with the API key.
Sample Response:
{
"links": "https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8, https://mnmedias.api.telequebec.tv/m3u8/29880.m3u8, "
}
2.4 Check API Key Status
/api/checkapi?apikey=unique_key
Behavior: blocking
Description: List all associated information about the API, such as the number of variants being monitored, API key expiration, remaining variant quota, etc.
Sample Response:
{
"StreamLimit": 120,
"TimeRemaining": "30 days",
"ActiveStreams": 12
}
2.5 Check Individual Stream Status
/api/status?apikey=unique_key&m3u8=https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8
/api/status?apikey=unique_key&linkid=d421d046
Behavior: blocking
Description: Get the current status of individual Master or Media playlists. LinkIDs for individual Media playlists, or the top-level Master playlist can be specified.
Sample Response:
{
"status": {
"Variants": {
"https://bitdash-a.akamaihd.net/content/sintel/hls/video/250kbit.m3u8": {
"Status": "ProgramEnd",
"Variants": 0,
"Uptime": 12.25,
"Buffer": 0,
"Outage": 0,
"SegDuration": 2.0,
"Errors": 0,
"Warnings": 0,
"UUID": "9f59d1f8",
"ISP": "",
"Delta": 0,
"PlaylistType": "Media",
"Timestamp": 1553022626.0042748,
"tracks": "VIDEO",
"vcodec": "h264@Main,L1.3",
"acodec": "",
"vres": "426x180",
"vfr": "24.00"
},
"https://bitdash-a.akamaihd.net/content/sintel/hls/video/500kbit.m3u8": {
. . . .
2.6 Check All Stream Status
/api/status?apikey=unique_key
Behavior: blocking
Description: Get the current status of all Master or Media playlists associated with the API key, including any alerts.
Sample Response:
{
"link": "All available links",
"status": {
"https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8": {
"Variants": {
"https://bitdash-a.akamaihd.net/content/sintel/hls/video/250kbit.m3u8": {
. . . .
2.7 Configure Alert Frequency
/api/alertlimits?apikey=unique_key[&outage=outage_seconds][&clear=clear_seconds]
Behavior: blocking
Description: Specify the global alert limits for stream outages. An outage condition is entered when the stream playback buffer reaches 0 seconds, or if the Media Playlist contains an “#EXT-X-ENDLIST” tag. If an outage condition continues for more than outage_seconds, an alert will be raised. The alert condition must be cleared for a contiguous clear_seconds, before a new alert may be raised for the same stream. If the command is issued with no options, the current settings are returned.
- outage: minimum seconds of the outage before an alert is raised [default: 120, minimum: 30; maximum: 3600]
- clear: minimum seconds for which an alert must be contiguously resolved, after which a new alert may be raised for the same outage stream [default, minimum: 300; maximum: 3600]
Sample Response:
{
"outage": 120.0,
"clear": 300.0
}
2.8 Configure Alert Features
/api/alertsetup?apikey=unique_key[&email=email_address][&callback=http://www.example.com/callback.html][&enable=false][&force=false] [¬ifyclear=false]
Behavior: blocking
Description: Specify the global alert destinations, which will be used in case an alert is raised. When specified, the parameters will be tested for validity: a test email will be sent to the address provided, and the callback link will be confirmed via an HTTP POST. Alerts may also be enabled and disabled using this command:
- email: email address to which alert messages will be sent, or “none” to remove an existing email address. Up to 3 email addresses (separated by commas) may be specified
- callback: an HTTP address to which alert messages will be POSTed, or “none” to remove existing HTTP callback address
- enable: enable or disable alerting [default: false]
- force: use email address without confirming the domain name [default: false]
- notifyclear: enable or disable sending an email when an alert condition has cleared [default: false]
The alert descriptions will be in JSON format, which will be emailed and POSTed when an alarm is triggered. If the command is issued with no options, the current settings are returned.
To avoid excessive email communication, for any single stream only 10 email “outage” alerts will be sent in 24 hours, with an additional 10 “clear” email messages when enabled. No limits shall exist for HTTP callbacks.
Sample Response:
{
"email": "noname@example.com",
"callback": "https://httpbin.org/post",
"enable": true,
“notifyclear”: false
}
2.9 Select Individual Stream Alert Mode
/api/alertselect?apikey=unique_key&m3u8=https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8[&mode=0]
/api/alertselect?apikey=unique_key&linkid=d421d046[&mode=0]
Behavior: blocking
Description: Set the alert mode for an individual link (mode 0: alerts disabled, mode 1: alerts enabled). If alerts are globally disabled, individual alerts cannot be enabled. Once a link is removed, its alert state will also be erased.
Sample Response:
{
"mode": "0",
"linkid": "d421d046"
}
2.10 Retrieve Stream Logs
/api/log?apikey=unique_key&linkid=d421d046&start=utc_time&end=utc_time
Behavior: blocking
Description: Download the log associated with the specified LinkID and the duration between start and end UTC timestamps, for up to the previous 14 days. LinkIDs may only be specified for individual Media playlists. This API may take up to 30 seconds to complete.
Sample Response:
{
"error": "",
"heading": " Time,MediaSequence,PlaylistState,SegmentState, BufferLevel, Outage, SegmentName,SegmentDuration,SegmentBytes,SegmentDownloadTime",
"log": [
" 1580989097, 0, VOD, Monitoring, 7.62, 0.00, seq-4.ts, 2.0, 147204, 0.12",
" 1580989099, 0, VOD, Monitoring, 7.61, 0.00, seq-5.ts, 2.0, 146264, 0.12",
" 1580989101, 0, VOD, Monitoring, 7.62, 0.00, seq-6.ts, 2.0, 122200, 0.11",
" 1580989103, 0, VOD, Monitoring, 7.62, 0.00, seq-7.ts, 2.0, 104716, 0.11",
" 1580989105, 0, VOD, Monitoring, 7.55, 0.00, seq-8.ts, 2.0, 119568, 0.18"
]
}
2.11 Enable Segment Downloads
/api/segment?apikey=unique_key[&enable=true]
Behavior: blocking
Description: Enable or disable downloading of segments for all streams of the specified API key. When disabled, only HLS playlists are monitored for outages and underflows. Segment downloading must be enabled to monitor VOD streams.
- enable: enable or disable segment downloads [default: disabled]
The API returns the current state when no parameters are specified.
Sample Response:
{
"enable": true
}
2.12 Check Health Status
/api/checkhealth?apikey=unique_key
Behavior: blocking
Description: Get the health status of the various system services, in addition to information about the number of streams being monitored and the aggregate download rate of all segments in kilobits per second (KBPS). This API can be called at most once every 30 seconds.
Sample Response:
{
"StatusAlertService": "OK",
"StatusEmailService": "OK",
"StatusMonitorService": "OK",
"InfoDownloadRate": 11016,
"InfoStreamCount": 8,
"InfoStreamErrors": 0,
"InfoMonitoringTime": 108413,
"InfoCPUPercentage": 30.6
}
2.13 Retrieve Analyzer Errors and Warnings
/api/errors?apikey=unique_key&linkid=d421d046&start=utc_time&end=utc_time
/api/warnings?apikey=unique_key&linkid=d421d046&start=utc_time&end=utc_time
Behavior: blocking
Description: Download all current errors and warnings associated with the specified LinkID and the duration between start and end UTC timestamps, for up to the 1000 most recent occurrences. LinkIDs may only be specified for both Master as well as Media playlists.
Sample Response:
[
{
"timestamp": "1613519709",
"code": " WA-1001",
"warning": " WARNING WA-1001: Rebuffering Error - Total Outage: 34.90 seconds"
},
{
"timestamp": "1613519701",
"code": " WA-1001",
"warning": " WARNING WA-1001: Rebuffering Error - Total Outage: 27.08 seconds"
},
{
"timestamp": "1613519693",
"code": " WA-1001",
"warning": " WARNING WA-1001: Rebuffering Error - Total Outage: 19.27 seconds"
},
]
3 Alert Functionality
HLSAnalyzer.com continually downloads both media playlists as well as segments. When playlists or segments are not delivered on time, then alerts may be received according to configuration parameters. Media playlists may be in any of the following states:
Media Playlist State | Description |
Live | Playlist does not have an ENDLIST and is progressing by adding new segments. |
Stalled | New segments are not added to the playlist (stale playlist). |
HTTPError | The playlist cannot be downloaded due to HTTP errors. |
LiveEnd | The steam was in Live state, but has transitioned to ENDLIST. When in this state, no segment monitoring will be performed until the playlist returns to Live state again. |
VOD | The stream was never in Live state and has an ENDLIST. |
Unknown | The starting state of the stream, which will transition to any of the states described above. |
When either media playlist or segments arrive at a slower rate than the expected time duration, the playlist buffer will be depleted and eventually reach zero, which would indicate a rebuffering event at the player. The total time spent while the player is rebuffering is considered as the amount of outage and is reported by the analyzer. Alerts are based on the time that the player is in a rebuffering state (e.g. the hypothetical playback buffer is zero), which can help track both complete stream outages, as well as intermittent delivery issues. As a result of this, the actual outage amount (where no data was theoretically available for playback) may be smaller than the period where data experienced inconsistent delivery. For example, if 10-second segments are delivered at non real time rates and the playback buffer was already at or near zero, both outage and inconsistent delivery durations would be incurred. However, the accumulated outages would be 2 seconds for each segment, where the inconsistent delivery period would be accounted for the entire duration of the slower than real-time delivery times, as shown in the following diagram:
In general, users interested in total stream outages are encouraged to configure alert parameters to a minimum outage time of 300 seconds to avoid alerts based on transitionary delivery problems.
Alerts may be programmed to report the inconsistent delivery times, as well as when those conditions have been cleared. Alert email messages will generally have the following format:
Subject: OUTAGE: HLSAnalyzer Outage Alert for 5fa1ab24559c
This is an alert update from HLSAnalyzer.com for:
https://example.com/example.m3u8
Alerts:
[5fa1ab24559c] Outage Time (UTC): 1610541723.00, Alert Condition Duration: 125.00 (sec), Total Accumulated Stream Outage: 128.3 (sec), Status: Stalled , Variant: https://example.com/example.m3u8
[5fa1ab24559c] This stream experienced inconsistent delivery for 125.00 seconds.
Subject: OK: HLSAnalyzer Clear Alert for 5fa1ab24559c
This is an alert update from HLSAnalyzer.com for:
https://example.com/example.m3u8
Alerts:
[5fa1ab24559c] Outage Time (UTC): 1610542123.00, Alert Condition Duration: 305.00 (sec), Total Accumulated Stream Outage: 386.0 (sec), Status: Live , Variant: https://example.com/example.m3u8
[5fa1ab24559c] This stream's alert condition has been cleared after a consistent delivery period of 305.00 seconds.
4 Cloud Monitoring and Management
The HLSAnalyzer.com service is a fully managed and monitored solution that provides high service availability for our customers. The health of our system is monitored by:
- Checking specific CPU and bandwidth threshold alerts every 15 minutes
- Conducting hourly tests of the liveness of the monitoring server
- Testing the end-to-end alert delivery capabilities of every monitoring instance every 6 hours
- Evaluating the API key expiration date every 24 hours
- Backing up of all configuration and stream settings every 6 hours
Our list of internal monitoring tools is always expanding to ensure that our service remains up and available and continuously monitors our clients’ HLS streams.
5 API Error Response Codes
Category | Error Code | Description |
API | EC100 | General Error or Warning |
EC101 | Link quota limit reached | |
EC102 | Invalid API Key | |
EC103 | This feature requires a paid subscription | |
EC104 | API Key has expired | |
M3U8 Links | EC110 | Error condition with a specific text message |
EC111 | Warning condition with a specific text message | |
LinkID | EC120 | Invalid or missing LinkID |
Alerting | EC130 | Invalid alert limit value specified |
EC131 | Invalid alert setup value specified |
6 Analyzer Error and Warning Codes
Error Code | Error Message | Description |
EC-1000 | Media playlist has become a master playlist | A URI previously associated with a media playlist has become a master playlist. This is generally an unexpected condition. |
EC-1001 | An unusually large jump in media playlist progression | Media sequence numbers are expected to increase by 1, per RFC 8216 Section 6.2.2. |
EC-1002 | Media sequence wraparound | According to RFC 8216 Section 6.2.2, media sequence numbers MUST not wrap. |
EC-1003 | Negatively increasing media sequence | According to RFC 8216 Section 6.2.2, media sequence numbers MUST not decrease. |
EC-1004 | Extra player buffer accumulation | This error indicates the arrival of new segments faster than in realtime. This condition may eventually lead to skipped segment playback. |
EC-1005 | Negative segment duration | Segment duration must always be greater than zero. |
EC-1006 | Segment duration is greater than the target duration | Segment duration is greater than the target duration by more than 150%. |
EC-1007 | An unusually large segment duration | Any segment duration greater than 120 seconds is considered to be an error condition. |
EC-1008 | Invalid target or segment duration | The server could not decipher the segment or target duration in the playlist. |
EC-2000 | Bandwidth parameter not specified for media Playlist | According to RFC 8216 Section 4.3.4.2: “ Every EXT-X-STREAM-INF tag MUST include the BANDWIDTH attribute.” |
EC-2001 | The ratio of measured Peak Bitrate exceeds the specified bitrate | The measured peak bitrate must be less than the specified bitrate from the Master playlist |
EC-2002 | Could not download the segment | The segment specified by the media playlist could not be downloaded |
EC-2003 | Playlist and stream mismatch | The parameter specified in the Master playlist does not match the stream’s characteristic |
EC-2004 | Could not download the playlist | An HTTP error is reported by the operating system when trying to read the link |
EC-2005 | Additional HLS conformance errors | A specific error was encountered; refer to the error message for details |
EC-3000 | Subscription required | Some operations, such as downloading high-bitrate streams, require a subscription |
Warning Code | Warning Message | Description |
WA-1001 | Rebuffering Error | A rebuffering event experienced by the monitoring server, due to the slow arrival of media playlist segments. |
WA-1002 | Slow segment download time | Downloading of the segment took longer than the specified segment duration. |
WA-1003 | Media sequence number increment mismatch | Media sequence number differences do not match the expected segment counts in a live playlist. |
WA-2000 | Master playlist feature not supported | Media playlists that change resolution or are added or removed are not yet supported. |
Copyright © 2021 Task One, LLC. All Rights Reserved.