HLS Analyzer Monitoring API (2.0)

Read the global alert configuration settings.

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.

The alert descriptions will be in JSON format, which will be emailed and POSTed when an alarm is triggered.

There are 3 sensitivty levels, increasing from least sensitive to most.Alerts are generated when 1) no data is being received (total outage), 2) when segments are slower than realtime and a specific outage duration has been accumulated (outage accumulation), or 3) when segments are delivered slower than realtime for a minimum amount of time (poor delivery).

To avoid excessive email communication, for any single stream only 10 email “STREAM Outage” alerts will be sent in 24 hours, with an additional 10 “Clear” email messages when enabled. No limits shall exist for HTTP callbacks or SCTE-35 outage alerts.

Specify alert limits for delivery outages in all streams. 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.

Read the delivery outage alert parameters for all streams.

Read the SCTE-35 outage alert parameters for all streams.

Specify alert limits for SCTE-35 outages in all streams. An outage condition is entered when consecutive SCTE-35 Cue-out and Cue-in playlist parameters have not been observed for outage_minutes. The alert condition must be cleared for a contiguous clear_minutes before a new alert may be raised for the same stream.

Enable or disable the stream outage alert mode for an individual link. If alerts are globally disabled, individual alerts cannot be enabled. Once a link is removed, its alert state will also be erased.

Get the currently enabled or disabled stream outage alerts for individual streams.

Get the current individually enabled or disabled SCTE-35 outage alerts.

Enable or disable the SCTE-35 outage alert mode for an individual link. SCTE-35 alerts are disabled by default, so they must be enabled individually for each stream. If alerts are globally disabled, individual alerts will not be enabled. Once a link is removed, its alert state will also be reset.

Get all alert records between the start and end timestamps for the specified LinkID. Timestamps are specified in Unix timestamp mode (UTC).

Get all SCTE-35 cue records between the start and end timestamps for the specified LinkID. Timestamps are specified in Unix timestamp mode (UTC).

SCTE-35 Source Types:

• playlist (default): SCTE-35 cues found in HLS playlist tags (#EXT-X-CUE-OUT, #EXT-X-CUE-IN, #EXT-X-DATERANGE)
• stream: SCTE-35 cues extracted directly from the MPEG transport stream segments (when present)

Requirements for Transport Stream Extraction:

• Segment downloading must be enabled (via /api/stream/segment?enable=true) when using source=stream
• Playlist-based SCTE-35 (source=playlist) does not require segment downloading

Both sources support the same time-based filtering using start and end timestamps. Transport stream extraction provides more detailed SCTE-35 information including splice commands and segmentation descriptors that may not be present in playlist tags.

Retrieve all current errors 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.

Retrieve all current 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.

Add a Master or Media HLS playlist (.m3u8). Monitoring will start immediately after the HLS URI has been added. An internal LinkID will be generated, unless it has been specified on the query string (between 6 and 32 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.

Custom HTTP Headers can be specified by adding "#http-custom-header=HeaderName:HeaderValue" to the end of any playlist URIs. The custom header will be stripped from the URI link and automatically added as an HTTP header when requesting the URIs and associated segments.

Remove a stream by specifying either the URI or the LinkID of the stream being monitored. Removing a stream will completely delete all its log and alert history from the system. Removing 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 removed).

Reset stream statistics by specifying either the URI or the LinkID of the stream being monitored. Resetting a stream will initialize all monitoring parameters and alerts. Similar to the remove process, reseting 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).

Remove all streams and their associated log and alert records from the system. This API will not wait for the completion status. Use the stream status API to determine all streams have been successfully removed.

Get the current status of individual Master or Media playlists. LinkIDs for individual Media playlists, or the top-level Master playlist can be specified. If no parameters are specified, the status for all streams will be returned.

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 is enabled by default and is required to monitor VOD streams.

Important: Segment downloading is required for:

• Caption extraction (CEA-608/708)
• Transport stream SCTE-35 cue extraction

Attempting to disable segment downloads when caption extraction is enabled will result in an error. Use the force=true parameter to override this protection.

Read the current segment download mode for the specified API key.

Retrieve detailed information about the MPEG Transport Stream (MPEG-TS) structure from HLS video segments. This endpoint provides access to Program Association Table (PAT), Program Map Table (PMT), and Packet Identifier (PID) mappings.

Transport Stream Components:

PAT (Program Association Table):

• Lists all programs in the transport stream
• Maps program numbers to their PMT PIDs
• Always transmitted on PID 0

PMT (Program Map Table):

• Describes the elementary streams for each program
• Specifies which PIDs carry video, audio, and data
• Includes stream type information (H.264, AAC, etc.)
• Indicates the PCR (Program Clock Reference) PID for timing

PID Information:

• Comprehensive mapping of all Packet Identifiers
• Stream types: Video (H.264/H.265), Audio (AAC/AC3/MP3), Captions (CEA-608/708)
• Special PIDs: PAT (0), PMT, PCR, and others

Use Cases:

• Transport stream structure analysis
• Validation of elementary stream composition
• Debugging encoding and muxing issues
• Automated stream monitoring and compliance checking
• Integration with video processing pipelines

Note: This endpoint requires that transport stream parsing is enabled for your API key. Information is extracted from the most recently downloaded segment.

Retrieve all currently available closed captions (CEA-608 or CEA-708) extracted from HLS video segments. This endpoint returns a snapshot of captions and closes the connection immediately.

Requirements:

• Segment downloading must be enabled (via /api/stream/segment?enable=true)
• Caption extraction feature must be enabled for your API key

Rate Limiting: To prevent excessive API calls, this endpoint enforces a minimum of 30 seconds between requests for the same stream.

Output Formats:

• json: Structured JSON with sequence numbers, timestamps, duration, and content
• srt: SubRip subtitle format compatible with most video players

Caption Types:

• 608: Legacy CEA-608 closed captions (Line 21, CC1-CC4) for Standard Definition
• 708: CEA-708 Digital Television captions for High Definition with enhanced formatting

Captions are extracted in real-time from MPEG-TS segments and cached for quick retrieval. For real-time streaming of captions as they arrive, use the /api/stream/captions/sse endpoint instead.

Establish a persistent Server-Sent Events (SSE) connection for real-time caption streaming. Unlike the polling endpoint (/api/stream/captions), this maintains an open connection and pushes captions to the client as they are extracted from the video stream.

Requirements:

• Segment downloading must be enabled (via /api/stream/segment?enable=true)
• Caption extraction feature must be enabled for your API key

Connection Behavior:

• Connection opens with a status message confirming stream details
• Initial captions (if any) are sent immediately upon connection
• New captions are pushed in real-time as they arrive from the video stream
• Heartbeat comments (: heartbeat) sent every 10 seconds to keep connection alive
• Connection automatically closes after 60 seconds if the stream is removed
• Client disconnect is detected and handled gracefully

Event Types:

• data: - Caption data in JSON or SRT format
• : - Comment lines for heartbeats and connection status
• Stream removal notification sent before closure

Output Formats:

• json: Each caption as a JSON object with sequence, timestamp, duration, and content
• srt: Each caption as SRT-formatted text blocks

Caption Types:

• 608: Legacy CEA-608 closed captions (Line 21, CC1-CC4) for Standard Definition
• 708: CEA-708 Digital Television captions for High Definition with enhanced formatting

Use Cases:

• Real-time caption display in video players
• Live transcription services
• Closed caption monitoring and quality assurance
• Accessibility features requiring low-latency caption delivery

Client Implementation Example:

const eventSource = new EventSource('/api/stream/captions/sse?apikey=KEY&linkid=ID&type=608&format=json');

eventSource.onmessage = (event) => {
  const caption = JSON.parse(event.data);
  console.log('New caption:', caption);
};

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
  eventSource.close();
};

List all associated information about the API, such as the number of variants being monitored, API key expiration, remaining variant quota, etc.

Check 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.

Use as an endpoint for testing HTTP POST alerts. All post data lengths will be limited to a maximum of 1500 characters, and the system will only keep the most recent 250 POSTs.

Clear all HTTP POST entires from the system.

Get the total HTTP POST counts send to the system.

Get all of the HTTP POST data that are available in the system (limited to the most recent 250 POSTs).