StreamSmart On-Air REST API

healthz

GET /healthz

livez

GET /livez

readyz

GET /readyz

metrics

GET /metrics

status

GET /status

GET /healthz

Check if the instance is healthy or not

Responses

200 OK

Service is alive and processing (or ready to process)

Body

Object

result

string

System state

Example:

HEALTHY

Examples

System healthy

{
    "result": "HEALTHY"
}

503 Service Unavailable

Service is in a bad state and should be restarted

Body

Object

result

string

System state

Example:

NOT_HEALTHY

Examples

System not healthy

{
    "result": "NOT_HEALTHY"
}

GET /livez

Check if the instance is healthy or not

Responses

200 OK

Service is alive and processing (or ready to process)

Body

Object

result

string

System state

Example:

ALIVE

Examples

System healthy

{
    "result": "ALIVE"
}

503 Service Unavailable

Service is in a bad state and should be restarted

Body

Object

result

string

System state

Example:

NOT_ALIVE

Examples

System not healthy

{
    "result": "NOT_ALIVE"
}

GET /readyz

Check if the instance is configured and ready to accept traffic

Responses

200 OK

System is prepared to accept traffic

Body

Object

result

string

System state

Example:

READY

Examples

Ready

{
    "result": "READY"
}

503 Service Unavailable

System is not yet ready. We may become ready to accept traffic at a later point in time.

Body

Object

result

string

System state

Example:

NOT_READY

Examples

Not yet ready

{
    "result": "NOT_READY"
}

GET /metrics

Operation metrics in prometheus format. Details of all available metrics are covered in-depth in the Prometheus Metrics section.

Responses

200 OK

503 Service Unavailable

System is not ready yet

GET /status

The overall system readiness as well as the readiness of the individual (micro)services that comprise the system.

Responses

200 OK

Body

Array of SystemStatus

Examples

Status of a SSOA instance currently optimizing, with no recent errors or warnings

[
    {
        "category": "System",
        "status": "OK"
    },
    {
        "category": "Input",
        "status": "OK"
    },
    {
        "category": "Output",
        "status": "OK"
    }
]

Status of an SSOA instance that has not received any input recently

[
    {
        "category": "System",
        "status": "OK"
    },
    {
        "category": "Input",
        "details": [
            {
                "details": "No playlist arrival in 30.0 seconds",
                "severity": "ERROR",
                "timestamp": 1733153802469
            }
        ]
        "status": "ERROR"
    },
    {
        "category": "Output",
        "status": "OK"
    }
]

503 Service Unavailable

System is not ready yet

Status detail of a system component

Object

Responses

200 OK

Body

Object

version

Object

Software Version Information

commitBranch

string

The git branch where the release was committed.

Min length: 1

Example:

streamsmart-onair/release/1.0.0

commitHash

string

The hashcode associated with the release’s git commit.

Example:

191db597034f0635c6a4cef42cfa7ae5f8f833cd

commitTime

string

The UTC timestamp associated with the release’s git commit.

Example:

2024-09-27T00:30:04Z

stamped

boolean

Indicates if the version was stamped.

Example:

true

versionString

string

The alphanumeric system version for the API.

Example:

1.0.0-1

Examples

{
    "version": {
        "commitBranch": "streamsmart-onair/release/1.0.0",
        "commitHash": "191db597034f0635c6a4cef42cfa7ae5f8f833cd",
        "commitTime": "2024-09-27T00:30:04Z",
        "stamped": "true",
        "versionString": "1.0.0-1"
    }
}

503 Service Unavailable

System is not ready yet

Apply a new license

PUT /license

Get the current license

GET /license

PUT /license

Apply license and restart required processes

Request parameters

dryrun

integer optional

If set and non-zero, validate the license and return any errors but do not apply the changes

Enumeration:

0

Validate and apply the changes (default)

1

Validate only

Responses

200 OK

License applied successfully

400 Invalid Request

An invalid license was provided and cannot be applied

GET /license

Fetch and return the current license

Responses

200 OK

Apply new configuration

PUT /config

Get the current configuration

GET /config

PUT /config

Apply configuration, clean up processing state, and restart required processes. Note that even if the configuration has not changed a call to this endpoint will perform a cleanup and restart of required processes. Additionally, while a configuration may be applied when the product is in an unlicensed state, stream processing will not begin until a valid license is applied.

Request parameters

dryrun

integer optional

If set and non-zero, validate the configuration and return any errors but do not apply the changes

Enumeration:

0

Validate and apply the changes (default)

1

Valdiate only

Request body

Config

Examples

Responses

200 OK

Configuration applied

400 Invalid Request

Configuration request was invalid

Examples

The below config will start the StreamSmart On-Air container to accept input from a MediaKind encoder

Input is MPEG_DASH mpd
Anchor rendition will be trackId-100
Candidate renditions will be trackId-101 and trackId-102
Full optimized ladder will be sent to an external downstream receiving entity

{
   "input": {
        "type": "MPEG_DASH",
        "manifestPath": "channel/manifest.mpd"
    },
    "optimizations": [
        {
            "outputIdentifier": "optimized",
            "anchorIdentifier": "trackId-100",
            "candidateIdentifiers": [
                "trackId-101",
                "trackId-100"
            ]
        }
    ],
    "outputs": [
        {
            "endpoints": [
                "http://x.y.z.a:pppp/downstreamEndpoint"
            ]
        }
    ]
}

The below config will start the StreamSmart On-Air container to accept input from an AWS Elemental MediaLive channel

Input is HLS m3u8
Anchor rendition will be channel_anchor
Candidate renditions will be channel_candidate1, and channel_candidate2
Full optimized ladder will be sent to two external downstream receiving entities

Here is a modified example configuration to receive from AWS Elemental Media Live and send to AWS Elemental Media Package

{
    "input": {
        "type": "HLS",
        "manifestPath": "channel.m3u8"
    },
    "optimizations": [
        {
            "outputIdentifier": "optimized.m3u8",
            "anchorIdentifier": "channel_anchor.m3u8",
            "candidateIdentifiers": [
                "channel_candidate1.m3u8",
                "channel_candidate2.m3u8"
            ]
        }
    ],
    "outputs": [
        {
            "endpoints": [
                "https://wcgoaw-1.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/example-channel/1/example-full-ladder",
                "https://wcgoaw-2.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/example-channel/2/example-full-ladder"
            ]
        }
    ]
}

The below config will start the StreamSmart On-Air container to accept input from an HLS source (eg. AWS Elemental MediaLive channel) and to produce both an optimized only and anchor only output

Input is HLS m3u8
Anchor rendition will be channel_anchor
Candidate renditions will be channel_candidate1, and channel_candidate2
The anchor output with XVS and Candidate IDs in WebVTT format will be sent to two external downstream receiving entities
The optimized output with XVS and Candidate IDs in WebVTT format will be sent to two external downstream receiving entities

{
    "input": {
        "type": "HLS",
        "manifestPath": "channel.m3u8"
    },
    "optimizations": [
        {
            "outputIdentifier": "optimized.m3u8",
            "anchorIdentifier": "channel_anchor.m3u8",
            "candidateIdentifiers": [
                "channel_candidate1.m3u8",
                "channel_candidate2.m3u8"
            ]
        }
    ],
    "outputs": [
        {
            "type": "ANCHOR",
            "endpoints": [
                "https://wcgoaw-1.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/example-channel/1/example-original",
                "https://wcgoaw-2.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/example-channel/2/example-original"
            ],
            "playbackURL": "https://wcgoaw.egress.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/out/v1/example-channel/example-original/example-original/original.m3u8",
            "annotations": [
                {
                    "type": "WEB_VTT",
                    "outputIdentifier": "original_subtitles.m3u8",
                    "fields": [
                        "XVS",
                        "CANDIDATE_ID"
                    ]
                }
            ]
        },
        {
            "type": "OPTIMIZED",
            "endpoints": [
                "https://wcgoaw-1.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/example-channel/1/example-optimized",
                "https://wcgoaw-2.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/example-channel/2/example-optimized"
            ],
            "playbackURL": "https://wcgoaw.egress.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/out/v1/example-channel/example-optimized/example-optimized/optimized.m3u8",
            "annotations": [
                {
                    "type": "WEB_VTT",
                    "outputIdentifier": "optimized_subtitles.m3u8",
                    "fields": [
                        "XVS",
                        "CANDIDATE_ID"
                    ]
                }
            ]
        }
    ]
}

GET /config

Fetch and return the current running configuration

Responses

200 OK

Body

Config

Examples

{
    "input": {
        "type": "MPEG_DASH",
        "manifestPath": "channel.mpd"
    },
    "optimizations": [
        {
            "outputIdentifier": "optimized",
            "anchorIdentifier": "trackId-100",
            "candidateIdentifiers": [
                "trackId-101",
                "trackId-102"
            ]
        }
    ],
    "outputs": [
        {
            "type": "OPTIMIZED_FULL_LADDER",
            "endpoints": [
                "https://downstreamreceivingentity/anchor-only/endpoint1"
            ]
        }
    ]
}

The following specification describes the configuration JSON schema that can be passed in to the StreamSmart On-Air container image as a command-line parameter, environment variable, or using volume or file mounting. The configuration has the following general structure:

{
  "input": {
    <defines the incoming video stream, such as HLS or DASH>
  },
  "optimizations": [
    {
      <specifies the settings for bitrate optimization, including the anchor and candidate renditions>
    }
  ],
  "output": {
    <defines how and where the optimized output should be delivered>
  }
}

See below for information on how to configure the input, optimizations and output sections.

Object

input

Input required

Input configuration

optimizations

Array of Optimization required

Optimization configuration

Min items: 1

Max items: 1

outputs

Array of Output nullable

Output configuration

When this array is omitted from the configuration, StreamSmart On-Air functions in demo mode, where the product will output both ANCHOR and OPTIMIZED only streams to the local storage. The two video streams can be viewed for comparison through the internal player page.

When this array is explicitly configured, each Output object must contain a unique value for it’s type field. Therefore, only a single output for each one of ANCHOR, OPTIMIZED, OPTIMIZED_FULL_LADDER can exist at a time.

Min items: 1

Max items: 3

Unique items: YES

advanced

Object nullable

Advanced configuration

Methods: Apply new configuration Get the current configuration

Examples

{
    "input": {
        "type": "MPEG_DASH",
        "manifestPath": "channel.mpd"
    },
    "optimizations": [
        {
            "outputIdentifier": "optimized",
            "anchorIdentifier": "trackId-100",
            "inputIdentifiers": [
                "1"
            ],
            "qualityDelta": {
                "value": 1
            }
        }
    ],
    "outputs": [
        {
            "type": "OPTIMIZED_FULL_LADDER",
            "endpoints": [
                "https://downstreamreceivingentity/anchor-only/endpoint1"
            ]
        }
    ]
}

An object that contains two fields: type and manifestPath

Object

type

string required

The type of the input object.

Enumeration:

HLS

MPEG_DASH

manifestPath

string required

The relative path to the container’s media ingest endpoint where the manifest will be found. This is specific to HLS and MPEG_DASH input types. Must end with .m3u8 for HLS, and .mpd for MPEG_DASH

Pattern: .*\.(mpd|m3u8)$

Example:

channel.mpd

Types: Config

Objects describing the candidates to consider for optimization

Object

outputIdentifier

string required

The identifier for the optimized stream

For HLS, the name of optimized m3u8 media playlist
For MPEG_DASH, the ID of the optimized representation attribute in the mpd

Example:

optimized

anchorIdentifier

string required

The anchor candidate (often the original top video profile, main target for optimization)

Min length: 1

Examples:

variant1.m3u8trackId-100

candidateIdentifiers

Array required

A list of candidates to be used for optimization

For HLS, this should be the filenames of the m3u8 media playlists as they appear in the multivariant top level playlist
For MPEG_DASH, the IDs of the representation attribute as they appear in the mpd

Min items: 1

Max items: 2

Unique items: YES

Examples:

["candidate1","candidate2"]

["variant2.m3u8", "variant3.m3u8"]

string

Min length: 1

Example:

candidate1

Types: Config

Output configuration

Object

type

string

This field describes what type of output is to be pushed to a downstream endpoint. Values accepted are

Enumeration:

OPTIMIZED_FULL_LADDER

Sends the received ladder (all non-candidate renditions/variants, including audio and closed captions) to the downstream receiving entity. The candidates and anchor profiles identified within the optimization configuration are replaced with the optimized version.

ANCHOR

Sends manifests and segments containing only anchor content to the downstream receiving entity

OPTIMIZED

Sends manifests and segments containing only optimized content to the downstream receiving entity

Default:

OPTIMIZED_FULL_LADDER

endpoints

Array required read-only

A list of downstream receiving entity URLs.

Note that all endpoints must be of the same type (http, https, or LOCAL)

StreamSmart On-Air currently supports WebDAV authentication. If the receiving entity endpoint requires authentication, the username and password must be injected through the URL in the following format:

http(s)://<username>:<password>@<host>, e.g. http://johndoe:p@55w0rd@my.streamsmart.com

A special value LOCAL can be used to publish the specified output type to local storage, which can be connected to by a player at:

http(s)://<host>/output/<outputType>/<outputIdentifier>, e.g. http://my.streamsmart.com/output/OPTIMIZED_FULL_LADDER/optimized.m3u8

Min items: 1

Max items: 2

Unique items: YES

Example:

["https://downstreamreceivingentity/anchor-only/endpoint1","https://downstreamreceivingentity/anchor-only/endpoint2"]

string

Example:

https://downstreamreceivingentity/anchor-only/endpoint1

playbackURL

string

Note: Only applicable for ANCHOR and OPTIMIZED output types.

Configures the StreamSmart On-Air internal player page to play content from an external location (eg. a downstream packager). When this value is not configured, StreamSmart On-Air defaults to playing back content from local storage.

Example:

https://cdn.com/original/channel/original.m3u8

annotations

Array nullable

Note: Only applicable for ANCHOR and OPTIMIZED output types.

Annotations to make to the output stream

Max items: 1

Unique items: YES

Object

type

string nullable

The type of annotations to be included with the output

Enumeration:

WEB_VTT

Default:

WEB_VTT

outputIdentifier

string nullable

The identifier for the annotation stream

For HLS input, the m3u8 media playlist name as it would appear in the multivariant top level playlist
For MPEG_DASH input, the ID of the caption representation as it would appear in the mpd

Default

For an output type of ANCHOR, the anchorIdentifier within the optimization configuration with a suffix appended based on the annotation type (eg. channel_top_profile_web_vtt_annotations.m3u8)
For an output type of OPTIMIZED, the outputIdentifier within the optimization configuration with a suffix appended based on the annotation type (eg. channel_optimized_web_vtt_annotations.m3u8)
OPTIMIZED_FULL_LADDER is currently unsupported

Example:

original_subtitles

fields

Array nullable

A list of strings that identify what will be included in each annotation for the corresponding segments.

Unique items: YES

Example:

["XVS","CANDIDATE_ID","SEGMENT_ID"]

string

Enumeration:

XVS

The average XVS score of the segment

SAVINGS

The savings of this segment compared with the original top profile (anchor)

CANDIDATE_ID

The candidate identifier of the current segment

SEGMENT_ID

The running segment ID (for HLS this would be similar to the Media Sequence Number, for MPEG_DASH, the $Number$ template value - if present)

TIMESTAMP

The wallclock timestamp of the container

Types: Config

Examples

Configuration for optimized full ladder output

{
    "type": "OPTIMIZED_FULL_LADDER",
    "endpoints": [
        "https://downstreamreceivingentity/optimized-full-ladder/endpoint1"
    ]
}

Configuration for anchor only output

{
    "type": "ANCHOR",
    "endpoints": [
        "https://downstreamreceivingentity/anchor-only/endpoint1"
    ],
    "playbackURL": "https://cdn.com/original/channel/original.m3u8",
    "annotations": [
        {
            "type": "WEB_VTT",
            "outputIdentifier": "original_subtitles",
            "fields": [
                "TIMESTAMP"
            ]
        }
    ]
}

Configuration for optimized only output

{
    "type": "OPTIMIZED",
    "endpoints": [
        "https://downstreamreceivingentity/optimized-only/endpoint1"
    ],
    "playbackURL": "https://cdn.com/optimized/channel/optimized.m3u8",
    "annotations": [
        {
            "type": "WEB_VTT",
            "outputIdentifier": "original_subtitles",
            "fields": [
                "TIMESTAMP"
            ]
        }
    ]
}

AWS Elemental

This example accepts HLS m3u8 input from AWS Elemental MediaLive, and pushes the full optimized ladder output to two MediaPackage version 2 endpoints. The input contains two additional candidate encodes (channel_candidate1.m3u8 and channel_candidate2.m3u8) that will be used for optimization.

{
  "input": {
    "type": "HLS",
    "manifestPath": "channel.m3u8"
  },
  "optimizations": [
    {
      "outputIdentifier": "optimized.m3u8",
      "anchorIdentifier": "channel_anchor.m3u8",
      "candidateIdentifiers": [
          "channel_candidate1.m3u8",
          "channel_candidate2.m3u8"
      ]
    }
  ],
  "outputs": [
    {
      "type": "OPTIMIZED_FULL_LADDER",
      "endpoints": [
        "https://abcde-1.ingest.abcde.mediapackagev2.us-east-1.amazonaws.com/in/v1/example-channel/1/example-full-ladder",
        "https://abcde-2.ingest.abcde.mediapackagev2.us-east-1.amazonaws.com/in/v1/example-channel/2/example-full-ladder"
      ]
    }
  ]
}

MediaKind

This example accepts MPEG-DASH mpd input from a MediaKind transcoder and pushes the full optimized ladder to a downstream endpoint. The input contains a single additional candidate encode (trackId-101) that will be used for optimization.

{
  "input": {
    "type": "MPEG_DASH",
    "manifestPath": "channel/manifest.mpd"
  },
  "optimizations": [
    {
      "outputIdentifier": "optimized",
      "anchorIdentifier": "trackId-100",
      "candidateIdentifiers": [
        "trackId-101"
      ]
    }
  ],
  "outputs": [
    {
      "type": "OPTIMIZED_FULL_LADDER",
      "endpoints": [
        "http://x.y.z.a:pppp/downstreamEndpoint"
      ]
    }
  ]
}

Local Playback

For demonstrations or testing without a downstream packager, StreamSmart On-Air can be configured to publish its output locally, and then serves the optimized output via the /output HTTP or HTTPS endpoint. This examples could be used to accept input from AWS MediaLive, and serve the optimized output.

{
  "input": {
    "type": "HLS",
    "manifestPath": "channel.m3u8"
  },
  "optimizations": [
    {
      "outputIdentifier": "optimized.m3u8",
      "anchorIdentifier": "channel_anchor.m3u8",
      "candidateIdentifiers": [
          "channel_candidate1.m3u8",
          "channel_candidate2.m3u8"
      ]
    }
  ],
  "outputs": [
    {
      "type": "OPTIMIZED_FULL_LADDER",
      "endpoints": [
        "LOCAL"
      ]
    }
  ]
}

A player would be able to play the output by connecting to http://<streamsmart-host>/output/OPTIMIZED_FULL_LADDER/optimized.m3u8.

Get the list of available logs

GET /logs

Get the logs

GET /logs/{name}

Get a support package

GET /supportPackage

GET /logs

Get the list of services with available logs

Responses

200 OK

Body

Array of Log

Examples

 [
    {
        "displayName": "Reverse Proxy",
        "name": "reverse-proxy"
    },
    {
        "displayName": "Controller",
        "name": "controller"
    },
    {
        "displayName": "Media Server",
        "name": "media-server"
    },
    {
        "displayName": "Analyzer",
        "name": "analyzer"
    },
    {
        "displayName": "Optimizer",
        "name": "optimizer"
    },
    {
        "displayName": "Latency Monitor",
        "name": "latency-monitor"
    },
    {
        "displayName": "Segment Arrival Monitor",
        "name": "segment-arrival-monitor"
    }
]

GET /logs/{name}

Fetch the list of available logs, or the contents of a specific log

Path variables

name

LogName required

The service to fetch the log of

Request parameters

tail

integer optional

Instead of fetching the current log file, keep the connection open and stream the log as it updates

Enumeration:

0

No tailing (default)

1

Enable log tailing

Responses

200 OK

Plain text containing (up to) the last 2MB of the log file.

404 Not Found

The requested log does not exist.

GET /supportPackage

Generate and download a support package for debugging purposes

Responses

200 OK

A compressed tarball (.tar) containing logs and other general information used for debugging.

Get a list of available service logs and their user friendly display name

Object

Example:

{
    "displayName": "Reverse Proxy",
    "name": "reverse-proxy"
}

displayName

string

Display friendly name for the service

Example:

Reverse Proxy

name

LogName

Serivce name to use when querying the logs and logTail endpoints

Methods: Get the list of available logs

Name of an internal StreamSmart On-Air log

string

Enumeration:

controller

Top level process monitoring input/output and internal processes

media-server

HTTP(S) server receiving and serving media

analyzer

Video stream analyzer

optimizer

Optimized playlist creation

reverse-proxy

HTTP(S) reverse proxy

latency-monitor

Latency profiler/monitor

segment-arrival-monitor

Segment arrival monitor

Methods: Get the logs

Types: Log

Probed input and output manifest information

Get input/output manifest metadata

GET /manifests/metadata

Get input manifest metadata

GET /manifests/metadata/input

Get output manifest metadata

GET /manifests/metadata/output

GET /manifests/metadata

Get details about the input/output streams

Responses

200 OK

Body

Object

input

ManifestMetadata

Input manifest details

output

ManifestMetadata

Output manifest details

Examples

{
    "input": {
        "manifest": "manifest.mpd",
        "streams": [
        {
            "identifier": "video_1080p",
            "bitrate": 6000,
            "width": 1920,
            "height": 1080,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video",
            "language": "eng",
            "tags": [
                "anchor"
            ]
        },
        {
            "identifier": "video_1080p_1",
            "bitrate": 5000,
            "width": 1920,
            "height": 1080,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video",
            "language": "eng",
            "tags": [
                "candidate 1"
            ]
        },
        {
            "identifier": "video_1080p_2",
            "bitrate": 4000,
            "width": 1920,
            "height": 1080,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video",
            "language": "eng",
            "tags": [
                "candidate 2"
            ]
        },
        {
            "identifier": "video_720p",
            "bitrate": 1600,
            "width": 1280,
            "height": 720,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video"
        },
        {
            "identifier": "video_360p",
            "bitrate": 800,
            "width": 640,
            "height": 360,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video"
        },
        {
            "identifier": "audio_eng",
            "bitrate": 128,
            "codec": "ac3",
            "type": "audio"
        },
        {
            "identifier": "audio_spa",
            "bitrate": 128,
            "type": "audio"
        },
        {
            "identifier": "subtitles_eng",
            "type": "subtitle"
        }
    ]
    },
    "output": {
        "manifest": "optimized.mpd",
        "streams": [
        {
            "identifier": "video_1080p",
            "bitrate": 6000,
            "width": 1920,
            "height": 1080,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video",
            "language": "eng",
            "tags": [
                "optimized"
            ]
        },
        {
            "identifier": "video_720p",
            "bitrate": 1600,
            "width": 1280,
            "height": 720,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video"
        },
        {
            "identifier": "video_360p",
            "bitrate": 800,
            "width": 640,
            "height": 360,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video"
        },
        {
            "identifier": "audio_eng",
            "bitrate": 128,
            "codec": "ac3",
            "type": "audio"
        },
        {
            "identifier": "audio_spa",
            "bitrate": 128,
            "type": "audio"
        },
        {
            "name": "subtitles_eng",
            "type": "subtitle"
        }
    ]
    }
}

404 Not Found

No input or output manifests currently available

GET /manifests/metadata/input

Get details about the input streams

Responses

200 OK

Body

ManifestMetadata

Examples

Input stream information

{
    "manifest": "manifest.mpd",
    "streams": [
        {
            "identifier": "video_1080p",
            "bitrate": 7000,
            "width": 1920,
            "height": 1080,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video",
            "tags": [
                "Anchor"
            ]
        },
        {
            "identifier": "video_1080p_1",
            "bitrate": 6000,
            "width": 1920,
            "height": 1080,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video",
            "tags": [
                "Candidate 1"
            ]
        },
        {
            "identifier": "video_1080p_2",
            "bitrate": 5000,
            "width": 1920,
            "height": 1080,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video",
            "tags": [
                "Candidate 2"
            ]
        },
        {
            "identifier": "video_720p",
            "bitrate": 1600,
            "width": 1280,
            "height": 720,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video"
        },
        {
            "identifier": "video_360p",
            "bitrate": 800,
            "width": 640,
            "height": 360,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video"
        },
        {
            "identifier": "audio_eng",
            "bitrate": 128,
            "codec": "ac3",
            "type": "audio"
        },
        {
            "identifier": "audio_spa",
            "bitrate": 128,
            "type": "audio"
        },
        {
            "identifier": "subtitles_eng",
            "type": "subtitle"
        }
    ]
}

404 Not Found

No input manifest received

GET /manifests/metadata/output

Get details about the output streams

Responses

200 OK

Body

ManifestMetadata

Examples

Output stream information

{
    "manifest": "optimized.mpd",
    "streams": [
        {
            "identifier": "video_1080p",
            "bitrate": 7000,
            "width": 1920,
            "height": 1080,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video"
        },
        {
            "identifier": "video_720p",
            "bitrate": 1600,
            "width": 1280,
            "height": 720,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video"
        },
        {
            "identifier": "video_360p",
            "bitrate": 800,
            "width": 640,
            "height": 360,
            "frameRate": "30",
            "codec": "AVC",
            "type": "video"
        },
        {
            "identifier": "audio_eng",
            "bitrate": 128,
            "codec": "ac3",
            "type": "audio"
        },
        {
            "identifier": "audio_spa",
            "bitrate": 128,
            "type": "audio"
        },
        {
            "identifier": "subtitles_eng",
            "type": "subtitle"
        }
    ]
}

404 Not Found

No output manifest currently available

Details about a parsed manifest

Object

manifest

string

Manifest file name

Examples:

main.m3u8manifest.mpdchannel.m3u8

streams

Array of StreamMetadata

List of streams in the manifest

Methods: Get input manifest metadata Get input/output manifest metadata Get output manifest metadata

Information of about a stream probed from the manifest

Object

identifier

string

Stream identifier (Variant name in HLS, Representation ID in DASH)

Example:

video_1080p

bitrate

integer

Average bitrate

Example:

1234

width

integer

Pixel width of the stream (if applicable)

Example:

1920

height

integer

Pixel height of the stream (if applicable)

Example:

1080

frameRate

string

Frame rate of the stream (if applicable)

Example:

30

codec

string

Codec of the stream (if applicable)

Example:

AVC

type

string

Type of stream (video, audio, subtitle, other)

Example:

video

language

string

The langauge of the stream (if applicable)

Example:

eng

Request parameters

from

string optional

A timestamp in either relative time format or absolute (epoch) time in milliseconds

Examples:

now-1hnow-5m1730937600000

to

string optional

A timestamp in either relative time format or absolute (epoch) time in milliseconds

Examples:

now-1hnow-5m1730937600000

Responses

200 OK

Body

Object

startTime

integer

The start time of the segments returned as a millisecond UTC time

Example:

1730937600000

endTime

integer

The end time of the segments returned as a millisecond UTC time

Example:

1731023999000

durationMs

integer

The total duration of the returned segments in milliseconds

Example:

86400000

savingsPercent

number

The total savings of the returned segments

Example:

16.17

segments

Array of SegmentStats

List of segments that have a timestamp between the inclusive range of startTime and endTime

Examples

{
  "durationMs": 2000,
  "endTime": 1733239369191,
  "startTime": 1733239369192,
  "savingsPercent": 35.16483516483517,
  "segments": [
    {
      "timestamp": 1733239367191,
      "segmentId": 3,
      "programTime": 0,
      "durationMs": 2000,
      "optimizations": [
        {
          "anchor": {
            "identifier": "anchor.m3u8",
            "xvs": 69,
            "sizeBytes": 153972,
            "selected": 0
          },
          "candidates": [
            {
              "identifier": "candidate1.m3u8",
              "xvs": 69.2, 
              "sizeBytes": 124080,
              "selected": 0,
              "savingsPercent": 19.413919413919412
            },
            {
              "identifier": "candidate2.m3u8",
              "xvs": 69,
              "sizeBytes": 99828,
              "selected": 1,
              "savingsPercent": 35.16483516483517
            }
          ],
          "output": {
            "identifier": "optimize.m3u8",
            "xvs": 69,
            "sizeBytes": 99828,
            "savingsPercent": 35.16483516483517
          }
        }
      ]
    }
  ]
}

400 Invalid Request

The specified to and/or from time argument was not in the correct format.

500 Internal Server Error

The segment stats could not be obtained from internal data storage.

Segment statistics, containing information about input rendition segments and optimized output rendition segments.

Object

timestamp

integer

Timestamp for when the stats entry was created (optimization finished for segment)

segmentId

integer

The segment ID

Example:

1

programTime

integer

The presentation time of the segment as a UTC epoch (in milliseconds)

Example:

234125154345

durationMs

integer

The duration of the segments in milliseconds

Example:

8000

optimizations

Array of OptimizationSegmentStats

Statistics for the optimizations for the segment

Methods: Get segment statistics

Segment statistics for an optimization

Array

Object

anchor

RenditionOptimizationSegmentStats

Segment statistics for the anchor stream

candidates

Array of RenditionOptimizationSegmentStats

Segment statistics for the candidate stream(s)

output

RenditionOptimizationSegmentStats

Segment statistics for the optimized output stream

Types: SegmentStats

Statistics for a single segment within a video rendition stream

Object

identifier

string

The stream identifier, as specified by the configuration

Example:

anchor.m3u8

xvs

number

The average XVS score for the segment

Min: 0

Max: 100

sizeBytes

integer

The size (in bytes) of the segment

Example:

5000

selected

integer nullable

Set to 1 if the segment was selected for the optimized output, 0 otherwise

Enumeration:

0

False

1

True

savingsPercent

number

The savings percentage exhibited against the anchor for this segment.

Example:

36.543

Types: OptimizationSegmentStats

Retrieve thumbnails of the key video streams

Get input stream thumbnail

GET /thumbnails/input

Get output stream thumbnail

GET /thumbnails/output

GET /thumbnails/input

Get a thumbnail for the latest segment of the main (anchor) input stream.

Responses

200 OK

Respond with raw PNG data for the thumbnail

404 Not Found

A thumbnail was not available for the stream.

GET /thumbnails/output

Get a thumbnail for the latest segment of the optimized output stream.

NOTE: The optimized thumbnail may be up to a segment duration behind the anchor thumbnail due to the analysis and optimization process.

Responses

200 OK

Respond with raw PNG data for the thumbnail

404 Not Found

A thumbnail was not available for the stream.

API endpoints to transmit media content to StreamSmart On-Air.

StreamSmart On-Air will receive media content (manifests and media segments) via HTTP PUT or HTTP POST to this endpoint. Media segments will be retained in local storage throughout and after the optimization process, while they are still referenced by their parent manifest. However, the media segments can be removed at any time from StreamSmart On-Air via an HTTP DELETE.

Note: StreamSmart On-Air will respond with a 405 Method Not Allowed response in the event that an HTTP PUT or HTTP POST request is made to an endpoint that is not listed in this section.

Push media content

PUT /input/{file_path}

Push media content

POST /input/{file_path}

Get pushed media content

GET /input/{file_path}

Delete pushed media content

DELETE /input/{file_path}

PUT /input/{file_path}

Push a media segment or media manifest (HLS or DASH) using HTTP PUT to StreamSmart On-Air.

Path variables

file_path

string required

The file path of the media content.

Responses

201 Created

File accepted.

403 Forbidden

Attempt to push to an invalid path

POST /input/{file_path}

Push a media segment or media manifest (HLS or DASH) using HTTP POST to StreamSmart On-Air.

Path variables

file_path

string required

The file path of the media content.

Responses

201 Created

File accepted

403 Forbidden

Attempt to push to an invalid path

GET /input/{file_path}

Get media content that was previously pushed to StreamSmart On-Air

Path variables

file_path

string required

The path that the media content was pushed with

Responses

200 OK

The media content specified

403 Forbidden

The specified request is forbidden

404 Not Found

The specified media content was not found

DELETE /input/{file_path}

Delete media content that was previously pushed to StreamSmart On-Air

Path variables

file_path

string required

The file path that the media content was pushed with

Responses

200 OK

Specified media content was deleted

403 Forbidden

The specified request is forbidden

500 Internal Server Error

The file could not be deleted due to an internal error

API endpoints to retrieve media content from StreamSmart On-Air.

These endpoints can be used to get the following types of content:

The content chosen as the anchor by StreamSmart On-Air given the specified configuration.
The selected output that has underwent optimization by StreamSmart On-Air.

Get anchor media content

GET /output/ANCHOR/{file_path}

Get optimized media content

GET /output/OPTIMIZED/{file_path}

GET /output/ANCHOR/{file_path}

Get media content for the anchor rendition as specified by the configuration.

Path variables

file_path

string required

Path of requested media file

Responses

200 OK

Media content

404 Not Found

Media content not found

GET /output/OPTIMIZED/{file_path}

Get media content for the anchor rendition as specified by the configuration.

Path variables

file_path

string required

Path of requested media file

Responses

200 OK

Media content

404 Not Found

Media content not found