Welcome to the StreamSmart On-Air product manual. StreamSmart On-Air is a cutting-edge video optimization solution designed to seamlessly integrate into existing live streaming workflows. Released as a Docker container, AMI, and a CloudFormation Stack, the product enhances video streaming efficiency by dynamically optimizing video bitrates while maintaining high-quality viewing experiences. This manual provides a comprehensive guide on how to deploy, configure, and maximize the potential of StreamSmart On-Air within your infrastructure.

Product Overview

StreamSmart On-Air is an advanced dynamic optimization tool that sits between video encoders and packagers, specifically designed to reduce bandwidth usage by 15% to 25% without compromising on video quality. The product leverages IMAX’s proprietary VisionScience™ technology to evaluate multiple renditions of the same content and intelligently select the lowest bitrate that preserves the quality of the original (or anchor) stream. The optimization process reduces distribution costs while delivering the same exceptional visual experience to viewers.

Use-Case

StreamSmart On-Air is ideal for live streaming platforms and broadcasters who aim to minimize bandwidth consumption while ensuring top-tier visual quality for their viewers. Deployed in between any transcoder that outputs HLS or DASH and any packager that accepts these formats, the product acts as a transparent optimization layer. By leveraging dynamic optimization algorithms, it continuously adjusts and improves the output based on real-time analysis, all without requiring major infrastructure overhauls.

Benefits

• Bandwidth Savings - StreamSmart On-Air reduces video streaming bandwidth consumption by optimizing bitrate usage, typically achieving 15% to 25% savings.

• Seamless Integration - StreamSmart On-Air can be seamlessly deployed as a Docker container, AMI, or CloudFormation Stack, integrating smoothly into existing workflows between transcoding and packaging systems, without disrupting video delivery processes.

• Video Quality Assurance - With its patented ViewerScore™ technology, the product ensures that visual quality remains indistinguishable from the original while eliminating unnecessary bits that are imperceptible to the human eye.

• Scalability - Whether deployed on-premises or in the cloud, StreamSmart On-Air is scalable to meet the needs of both small streaming services and large broadcast networks, reducing costs across diverse environments.

Technical Specifications

This manual will guide you through the steps to set up, configure, and operate StreamSmart On-Air effectively, so you can immediately start optimizing your video streams and reducing operational costs.

User Interface Overview

The StreamSmart™ On-Air interface provides real-time visibility into video stream optimization. This document outlines its key components, functionality, and what users can expect when monitoring streams, configuring settings, or reviewing logs.

To access the StreamSmart™ On-Air UI, open a web browser and enter the IP address of the StreamSmart On-Air™ instance (https://<System IP Address>)
Ensure that your computer has network access to StreamSmart On-Air™ instance (eg. access allowed by applicable NACLs, security groups, firewalls, etc.).

Dashboard Page

The Dashboard page provides a real-time summary of the system’s status, input and output streams, and key performance metrics, including bitrate optimization and quality scores.

Dashboard Key Elements:

• System Status Panel[1]: Displays overall system health, and allows users to view detailed issues by expanding the panel.

• Input and Output Preview[2]: Displays thumbnails the Input(anchor) and optimized output streams.

• Graphs[3]: This section provides real-time insights into video quality and bitrate optimization.
  The IMAX ViewerScore™ graph compares the Anchor, Optimized Output, and Candidate encodes to ensure quality is maintained. The Bitrate, Savings, and Segment Selection graphs help analyze bitrate trends, efficiency gains, and how different segments contribute to the optimized stream.
  Average quality and bitrate savings[4] are calculated based on the selected time range (15 min, 30 min, 1 hr, etc.).
  

  • Tips for interacting with the graphs:
    • Toggle Stream Visibility: Click on a Stream Name legend[5] to show or hide its data on the graph. Disabled streams appear grayed out.
    • Zooming In: Click and drag to select a section of the timeline to zoom in on that period for a more detailed analysis
    • Reset Zoom: After zooming in, click the “Reset zoom” button to return to the full timeline view.
    • Hover for Details: Move the cursor over the graph to display Metrics details[6] for that point in the timeline.

• Input and Output: This section provides details of all input and output stream properties
  

Settings Page
This page allows users to manage configuration and licensing. Users can upload or download the files or manually edit the JSON settings directly on the screen.

Logs Page
The Logs Page provides access to real-time and historical system logs for monitoring and troubleshooting, selectable using the dropdown menu[7]. Each log corresponds to a specific system component, allowing users to analyze different aspects of StreamSmart™ On-Air’s operation.

Users can:

• Download a compressed .gz file containing all logs[8].
• Enable Tail Log View to monitor logs in real-time for live debugging[9].
• Download logs individually using the download button[10].
  • Log Descriptions
    • Analyzer: Tracks video analysis, including quality measurements, bitrate optimizations, and segment selection.
    • Controller: Records system operations, workflow execution, and coordination between components.
    • Database Cleaner: Logs database maintenance activities, such as clearing old records and optimizing storage.
    • Latency Monitor: Tracks system latency, measuring processing delays and optimization workflow timing.
    • Media Server: Captures interactions related to media handling, including stream ingestion and playback requests.
    • Output Generator: Logs details of optimized stream creation, including segment processing and bitrate adjustments.
    • Reverse Proxy: Captures incoming and outgoing HTTP requests, managing communication between internal services and external clients while monitoring real-time activity, traffic, and errors.
    • Segment Arrival Monitor: Tracks video segment arrival times to detect delays and ensure synchronization.

Player Page
The Player page allows users to visually compare the Anchor (original) and Optimized video streams to evaluate quality preservation and bitrate savings. It offers two comparison modes:

• Side-by-Side Comparison: Displays both versions side by side for easy visual assessment.

• Hairline Comparison: Provides a draggable vertical line that lets users move left or right to compare the Anchor vs. Optimized Output in specific areas of the frame, allowing for detailed visual analysis.

The architecture of StreamSmart On-Air is designed to integrate seamlessly into existing video streaming workflows while optimizing bandwidth usage and preserving video quality. The system operates as a virtualized solution (container, AMI, or CloudFormation Stack), capable of being deployed between any encoder/transcoder that outputs HLS or DASH and any packager that accepts these formats. Below is an overview of the key components that make up the system architecture and how they interact with each other.

Components

• Encoder/Transcoder - The encoder/transcoder is responsible for generating multiple renditions of the video stream, typically at different bitrates, resolutions, or qualities. These renditions are used to create an Adaptive Bitrate (ABR) ladder, which enables the delivery of streams optimized for a range of devices and network conditions. StreamSmart On-Air works with any encoder that outputs HLS (HTTP Live Streaming) or DASH (Dynamic Adaptive Streaming over HTTP) formats, such as AWS Elemental MediaLive.

• StreamSmart On-Air - At the heart of the architecture is StreamSmart On-Air, a virtualized solution designed to optimize video streams in real time. It acts as an intermediary between the transcoder and the packager, intercepting the ABR ladder, analyzing the quality of each rendition, and selecting the lowest bitrate that maintains the same visual quality as the top profile (the anchor). Key features include:

  • /input endpoint - The transcoder pushes its HLS or DASH output to this endpoint, available on ports 80 and 443.
  • Quality optimization - StreamSmart On-Air evaluates multiple renditions (anchor and up to two candidate profiles) and produces an optimized single rendition, reducing the overall bitrate.
  • Manifest manipulation - The product manipulates the manifest (playlist) files to ensure that the optimized output is sent to the downstream packager, with the same format (HLS or DASH) as the input.

• Packager - The packager takes the optimized video stream and prepares it for final delivery to content distribution networks (CDNs) or media servers. It wraps the optimized content in a format suitable for streaming, such as MPEG-DASH or HLS. Common packagers include AWS Elemental MediaPackage. StreamSmart On-Air integrates smoothly into this process by pushing its optimized manifest and media segments directly to the packager, ensuring minimal disruption to the packaging workflow.

• Content Delivery Network (CDN) - After the video has been optimized and packaged, it is delivered to viewers through a Content Delivery Network (CDN), such as Amazon CloudFront. The CDN ensures that the content is distributed efficiently across the internet, providing fast and reliable delivery to end users while benefiting from the reduced bandwidth generated by StreamSmart’s optimization.

• Viewer - At the end of the workflow is the viewer, who accesses the optimized video stream through various devices, such as smartphones, tablets, smart TVs, or computers. The viewer experiences high-quality video while using less bandwidth, thanks to StreamSmart’s dynamic optimization.

Typical Workflow

• Ingestion - The video stream is ingested from a live video source (e.g. camera feed), through some contribution equipment into the transcoder, which produces multiple renditions of the content.

• Pushing to StreamSmart On-Air - The transcoder sends its HLS or DASH output to the /input endpoint of StreamSmart On-Air. The transcoder is configured to add up to two additional candidate encodes for the rendition(s) that is being optimized.

• Optimization - StreamSmart On-Air analyzes the renditions, evaluating quality using the proprietary ViewerScore™ technology, which closely mimics human visual perception. It then selects the most efficient rendition that preserves visual quality and pushes the optimized version (replacing the original and the candidates) along with other renditions and media streams (e.g. audio and captions) to the packager. StreamSmart On-Air temporarily stores manifests and media segments while the optimization is taking place.

• Packaging - The optimized rendition is sent to the packager, which prepares the stream for delivery in the requested formats (HLS or DASH).

• Delivery via CDN - The packaged content is distributed to viewers via a CDN, which ensures low-latency, high-quality delivery across different regions and devices. Storage and distribution costs significantly reduced.

• Viewer Experience - Viewers receive a high-quality video stream while consuming less bandwidth, contributing to lower distribution costs for the streaming service and higher overall quality of experience due to reductions in rebuffering and other congestion-related impairments.

Here is a more detailed view of the integration between the Transcoder, StreamSmart On-Air, and the Packager. It shows the anchor and additional candidate encodes being combined into an optimized top profile and pushed to the Packager.

StreamSmart On-Air is released as a Docker container as well as an AMI or CloudFormation Stack on AWS. It can be deployed in various environments to suit different operational needs:

On-Premises - For enterprises that prefer to maintain their own infrastructure, StreamSmart On-Air can run on local servers or private clouds, integrating with on-premises transcoding and packaging systems.

Cloud - The container can also be deployed on cloud platforms such as Amazon Web Services (AWS), utilizing cloud-native services like AWS Elemental MediaLive and AWS Elemental MediaPackage. It supports orchestration services such as Amazon EKS, ECS, Fargate, or traditional EC2 instances, and is also available as an AMI-based product on AWS Marketplace. It can also be deployed on AWS as a CloudFormation Stack.

Hybrid - StreamSmart On-Air is versatile enough to operate in hybrid cloud environments, allowing for flexibility between on-premises and cloud-based components.

Regardless of how it is deployed, the following table describes the system requirements:

For details, refer to the Deployment Guides section.

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.

Monitoring and maintaining the health of StreamSmart On-Air is crucial to ensuring continuous and efficient video optimization. The product provides two dedicated health-check endpoints and logs its activity to standard out, which can be monitored and analyzed for troubleshooting purposes. This chapter outlines the methods for monitoring the health and performance of StreamSmart On-Air and troubleshooting common issues.

Health Monitoring

StreamSmart On-Air provides two HTTP-based health check endpoints: /readyz and /livez. These endpoints can be used for monitoring the application’s readiness to serve traffic and its overall health, respectively.

The /readyz endpoint checks whether StreamSmart On-Air is fully initialized and ready to start processing video streams. This endpoint is typically used by load balancers or orchestrators (like Kubernetes) to determine if the application should receive traffic.

The /livez endpoint is used to check the general health of the StreamSmart On-Air container. It verifies if the application is running smoothly and is able to perform its intended operations. This endpoint is typically used for long-term health monitoring by cloud platforms or container orchestration systems.

Both /readyz and /livez endpoints can be integrated with monitoring systems such as:

• Prometheus - Using black-box exporters to monitor the HTTP response status of these endpoints.
• Kubernetes Liveness and Readiness Probes - You can configure Kubernetes pods to automatically restart if the application fails the /livez health check or is not ready via /readyz.

Prometheus Metrics

StreamSmart On-Air provides Prometheus metrics at the /metrics endpoint. This endpoint can be queried via an HTTP GET request to view a textual representation of various counters from the system. This includes basic counters such as the number of manifests and video segments received from the encoder as well as transmitted to the packager. Details of all available metrics are covered in-depth in the Prometheus Metrics section.

Logging

StreamSmart On-Air writes detailed logs to standard output (stdout), which can be used for both monitoring and troubleshooting. The log contains essential information about the application’s operations, including:

• Initialization events
• Optimization processes and decisions.
• Errors or warnings related to input/output handling or configuration issues

Access to the logs will depend on how the container is being deployed. For more details, refer to the Deployment Guides section.

Common Troubleshooting Steps

1. Check Health Endpoints

• Ensure the /readyz and /livez endpoints are returning a 200 OK response.
• If the /livez endpoint returns 503, inspect the logs to identify any critical errors preventing the application from running.

2. Check Configuration

• Incorrect or missing configuration parameters can lead to issues with initialization or processing. Errors related to invalid configuration will be logged to stdout.
• Ensure the configuration provided to the container is correct, and all necessary fields (input, optimizations, outputs) are properly set.

3. Check License Validity

• Ensure that the license passed to the container is valid and not expired. License-related errors will be logged in stdout and may prevent the application from processing input streams.
• Errors related to invalid licenses will usually prevent the /readyz endpoint from returning a 200 OK.

4. Verify Input Stream

• Ensure that the transcoder is pushing the video streams to the correct /input endpoint (ports 80 or 443).
• If the input manifest (HLS or DASH) contains errors, StreamSmart On-Air might not be able to process it, leading to issues that will be logged.

5. Monitor Optimization Results

• StreamSmart On-Air logs optimization decisions (such as the selection of the optimized top profile) to stdout. If optimization appears ineffective, review these logs to ensure that candidate renditions are properly configured.

6. Check for Network or Port Issues

• If the application is not accessible via /readyz or /livez, verify that the necessary ports (80 and/or 443) are open and that there are no network issues preventing access.

7. Check Resource Utilization

• Ensure the instance/container running StreamSmart On-Air has sufficient CPU and memory resources. Under-provisioned resources can lead to slow performance or crashes.

By monitoring the health endpoints and analyzing the logs, you can ensure that StreamSmart On-Air operates smoothly and efficiently. In the event of issues, logs and configuration reviews provide the necessary insights for troubleshooting. This monitoring and troubleshooting approach will help you maintain high availability and ensure optimal video stream delivery at all times.

Accessing Support

The IMAX Streaming and Consumer Technology Customer Success team can be contacted by emailing sct-support@imax.com.

Overview

The following diagram shows how StreamSmart On-Air can be deployed into a live media workflow on AWS:

The workflow breaks down as follows:

Video Source - The video input starts from a camera or video source.

AWS Elemental MediaConnect - The video stream is initially sent to AWS Elemental MediaConnect, which is used to ingest the live video into the AWS cloud, and allows for reliable video transport. MediaConnect flows are input into specific availability zones when they are created. While not required, it is highly recommended that the rest of the workflow is orchestrated such that the availability zones used by MediaLive and StreamSmart On-Air align with the ones used by MediaConnect, as shown in the architecture diagram above. This ensures that data transfer between the services is as efficient and resilient as possible.

AWS Elemental MediaLive - After MediaConnect, the video is passed to AWS Elemental MediaLive, which handles real-time encoding of the video stream into multiple adaptive bitrate (ABR) formats. MediaLive is configured with up to two additional candidate encodes for the top profile, which will be used by StreamSmart On-Air to produce an optimized output. When AWS MediaLive is using AWS MediaConnect as an input, it automatically aligns the availability zones used by MediaLive with those used by the MediaConnect flow. While not required, it is highly recommended that you use VPC output delivery when setting up MediaLive, as it provides enhanced security, improved performance and reliability, and cost efficiency. VPC delivery is required in order to keep all data transfer between MediaLive and StreamSmart On-Air within an availability zone, as the architecture diagram above illustrates.

IMAX StreamSmart On-Air - The encoded video streams are then optimized by IMAX StreamSmart On-Air, which releases as a Docker container image and can be deployed on EC2, ECS, Fargate and EKS, or by launching an EC2 instance that contains Docker and the StreamSmart On-Air container image on AWS Marketplace. This system, deployed across multiple Availability Zones for redundancy and failover (when MediaLive is configured with a standard channel with two pipelines), selects the lowest bitrate segments that maintain high video quality, optimizing the bandwidth usage while keeping the viewer’s quality experience intact. While not required, it is highly recommended that you deploy StreamSmart On-Air into the same availability zones that were selected when configuring MediaConnect. This ensures that all of the data transfer from MediaConnect, through MediaLive and to StreamSmart On-Air remains within the same availability zone, which provides enhanced security, improved performance and reliability, and cost efficiency. StreamSmart On-Air should be deployed with an IAM role that gives it permission to push to the MediaPackage input endpoint (see below for more information). Each instance of StreamSmart On-Air requires 16 vCPUs, 32 GB of memory (c5.4xlarge) and at least 20 GB of storage.

AWS Elemental MediaPackage - The optimized video streams are passed to AWS Elemental MediaPackage, which prepares the content for delivery by packaging it into formats like HLS or DASH, suitable for a wide range of devices. Each StreamSmart instance pushes to one of the two MediaPackage input URLs. Permission to push into the MediaPackage input endpoints can be managed with network ACLs, or using IAM roles. While not required, it is highly recommended that permission is granted to StreamSmart On-Air by assinging it an IAM role that has the necessary permissions.

Amazon CloudFront - The packaged content is distributed via Amazon CloudFront, AWS’s content delivery network (CDN), which delivers the streams to end viewers with low latency.

Viewer - Finally, the optimized video stream reaches the end viewer, who experiences high-quality video with reduced bandwidth usage.

If you are creating a workflow without redundancy, the architecture is similar but involves deploying only once instance of StreamSmart On-Air, as shown below:

To deploy a media streaming workflow using AWS Elemental MediaLive, StreamSmart On-Air, and AWS Elemental MediaPackage, it is important to follow the correct deployment order to ensure seamless integration and functionality. Below is the recommended deployment order and the reasoning behind it:

1. AWS Elemental MediaConnect

• MediaConnect allows you to choose the availability zones for the one (if using a single-pipeline channel in MediaLive) or two (if using a standard channel in MediaLive) flows that you will create.
• Deploying this first makes these availability zones known, which can then be used when deploying StreamSmart On-Air on step 3 to ensure that all data-transfer remains within the same zone.

2. AWS Elemental MediaPackage

• MediaPackage is responsible for preparing the video streams for delivery to viewers after they are optimized. By deploying MediaPackage first, you can set up the ingest endpoints that will be used to configure the output of StreamSmart On-Air.
• Steps:
  • Create a new MediaPackage channel (v1 or v2) and configure the packaging formats (e.g., HLS or DASH output).
  • Obtain the ingest endpoint URLs where MediaPackage will expect to receive the optimized content from StreamSmart On-Air.
    • Important Note: when copying these endpoint URLs into the StreamSmart On-Air configuration in Step 3, you must leave off the /channel (for v1) or /index (for v2) part of the URL. See Step 3 for details.
  • Once MediaPackage is set up, you will have the necessary output details to use when configuring StreamSmart On-Air.

3. StreamSmart On-Air

• StreamSmart On-Air sits between MediaLive (the encoder) and MediaPackage (the packager), optimizing the video stream before sending it to MediaPackage. After MediaPackage is ready to receive content, you can configure StreamSmart On-Air to push the optimized stream to the MediaPackage ingest endpoints. This step will define the URL of StreamSmart’s /input endpoint, which can then be used to configure the output of MediaLive.
• Steps:
  • Deploy the StreamSmart On-Air container(s) on either EC2, ECS, Fargate, or EKS, or by launching an instance from AWS Marketplace:
    • Select a subnet that is in the same availability zone as the MediaConnect flow created in step 1.
    • Ensure that the Network ACL associated with the subnet contains an outbound rule allowing HTTP traffic to the MediaPackage ingest endpoints.
    • Ensure that the routing table associated with the subnet has a route from the StreamSmart On-Air instance to an internet gateway attached to the parent VPC.
    • Select a security group that contains the following rules:
      • Allow inbound HTTP traffic from the MediaLive channel that will be configured in the next step (eg. from the CIDR block of the subnet where the MediaLive channel pipeline will be deployed).
      • Allow outbound HTTP traffic from the StreamSmart On-Air instance to the MediaPackage ingest endpoints added in step 2.
  • Each instance of StreamSmart On-Air requires 16 vCPUs, 32 GB of memory (c5.4xlarge) and at least 20 GB of storage.
    • Make note of the host information, which will be used to configure the MediaLive output in step 4.
    • If deploying on EC2 or launching from AWS Marketplace, you will need to SSH into the instance in order to configure and launch the Docker container.
      • When launching the instance, make sure that you configure a key pair so you can securely connect to it.
      • Once it is running, SSH into the instance using the key that you configured. If setting up your own EC2 instance, use the appropriate username for the base OS or image that you selected. If launching from AWS Marketplace, log in as the user ubuntu.
  • Configure the input and optimization sections of the configuration with the expected manifest settings (manifest name, anchor and candidate identifiers).
  • Configure the output section of the configuration with the MediaPackage ingest endpoints from step 2.
    • Important Note: When giving the ingest endpoints, leave off the /channel or /index parts of the URLs.
    • For example: if the endpoint is https://wcgoaw-1.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/group1/1/mychannel/index, give https://wcgoaw-1.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/group1/1/mychannel in the configuration file (with no /index at the end).
  • Start the container instance prior to proceeding to the next step.

4. AWS Elemental MediaLive

• MediaLive is responsible for encoding the live video stream and sending it to StreamSmart On-Air for optimization. Once both MediaPackage and StreamSmart On-Air are set up and ready, MediaLive can begin encoding and pushing the stream to StreamSmart On-Air’s /input endpoint.
• Steps:
  • Begin configuration of a new MediaLive channel
  • On the “Channel and input details” page under “Output delivery”, select the VPC delivery method to co-locate the MediaLive channel with the StreamSmart On-Air instance.
    • Select a subnet that is in the same availability zone as the StreamSmart On-Air instance.
      • It is recommended to deploy the MediaLive channel pipeline in the same subnet as the StreamSmart On-Air instance. If this is not possible, please ensure that the appropriate Network ACLs and routing table rules are in place to allow communication between instances residing in the two subnets.
    • Select a security group containing a rule to allow outbound HTTP traffic from the MediaLive channel to the StreamSmart On-Air instance (eg. to the CIDR block of the subnet where the StreamSmart On-Air instance is deployed)
  • Add an HLS output group containing the anchor and additional candidate encodes for the rendition that is to be optimized
    • Each anchor and candidate must have the following identical codec parameters
      • Resolution
      • Frame-rate
      • Codec
      • Codec Profile
      • Codec Level (must not be set to auto)
    • Configure it to push to the /input endpoint of StreamSmart On-Air. For CDN settings, use “HLS basic put” method to transmit data to the StreamSmart On-Air instance.
  • Start the MediaLive channel to begin streaming, which will trigger the optimization process in StreamSmart On-Air and the delivery of optimized content to MediaPackage.

By following this deployment order and following all of the recommendations, you ensure that each component is set up and ready to receive or send content at the correct time, resulting in a smooth, secure, and optimized media streaming workflow.

StreamSmart On-Air as a Docker container can be run on any environment that supports Docker, including Amazon EKS, ECS, Fargate, or traditional EC2. To deploy StreamSmart On-Air, the container must be launched with the appropriate configuration, license, and optionally, TLS certificates for secure communication. This section covers the steps to launch the container and the various methods for passing these required inputs.

Quick Start

The following is an example of how to launch the container using the docker command at the command-line:

docker run --rm -p 80:80 -p 443:443 imax-streamsmart-onair --config '{
  "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://wcgoaw-1.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/group1/1/mychannel",
        "https://wcgoaw-2.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/group1/1/mychannel"
      ]
    }
  ]
}' --license '
  20bb26a811874bb220d607036e258c72ce6cf579feb4f7ab4f9c8719a2765720
  {
  "expiry": "2030-01-01",
  "organization": "ACME",
  "site": "Production"
}'

This will produce output similar to the following:

[2024-09-18 15:39:36,634] [info] Applying config from --config
[2024-09-18 15:39:36,636] [info] Enabling demo player
[2024-09-18 15:39:36,636] [info]   Anchor playback URL: /output/ANCHOR/channel.m3u8
[2024-09-18 15:39:36,636] [info]   Optimized playback URL: /output/OPTIMIZED/channel.m3u8
[2024-09-18 15:39:36,637] [info] Applying license from --license
[2024-09-18 15:39:36,646] [info] Generating HTTPS certificate using a self-signed key
[2024-09-18 15:39:36,710] [info] Starting StreamSmart On-Air...

Breaking down the arguments passed to the docker run command:

• --rm - This flag automatically removes the container once it stops. The StreamSmart On-Air container is designed to be disposable, so there is nothing that needs to be persisted after it exits. This flag can be omitted, and others like -d to run the container in detached mode can be used in addition or instead.
• -p 80:80 -p 443:443 - This options bind ports 80 and 443 for HTTP and HTTPS communication, respectively. You only need to bind the ports that will be used, so if you know that your transcoder will only be pushing using HTTPS, port 80 can be omitted.
• imax-streamsmart-onair - The container image name, which will vary depending on where and how the container is being deployed. The container image will be provided by IMAX as a .tar.gz file, in which case it can be loaded with the docker image load command. Alternatively, the image can be loaded into an online registry, such as AWS ECR. Please work with your IMAX account and/or support teams to determine the version that is right for you.
• --config - This option loads the configuration JSON that follows into the container. See below for details, and for other ways that configuration has be loaded into the container.
• --license - This option loads the license that follows into the container. StreamSmart On-Air always requires a valid license in order to run.

Passing Configuration, License, and TLS Certificates

StreamSmart On-Air requires certain parameters to be passed at runtime, including a configuration file, a product license, and optionally, a TLS certificate and key for secure communication. These can be passed in one of the following ways:

Using Command-line Parameters

You can directly pass the configuration, license, and optionally the TLS certificate and key using command-line options when starting the container. This approach requires passing in the actual text/values, not paths to files.

docker run --rm -p 80:80 -p 443:443 imax-streamsmart-onair \
  --config '<configuration JSON>' \
  --license '<license text>' \
  --tls-cert '<TLS certificate>' \
  --tls-key '<TLS key>'

The Quick Start example above uses this approach to passing the configuration and license into the container.

Using Environment Variables

Another method to pass the configuration, license, and TLS certificates is by setting them as environment variables when launching the container. This is useful when using orchestration tools such as Kubernetes, ECS, or Docker Compose. This approach also requires passing in the actual text/values, not paths to files.

docker run --rm -p 80:80 -p 443:443 \
  -e CONFIG='<configuration JSON>' \
  -e LICENSE='<license text>' \
  -e TLS_CERT='<TLS certificate>' \
  -e TLS_KEY='<TLS key>' \
  imax-streamsmart-onair

In this method:

• CONFIG - The JSON-formatted configuration is passed directly as an environment variable.
• LICENSE - The license string is passed as an environment variable.
• TLS_CERT and TLS_KEY (optional) - TLS certificate and key are also passed as environment variables if secure communication is needed.

Using Mounted Volumes

If you prefer to keep the configuration, license, and TLS files in the host system, you can mount these files or directories into the container at runtime. There are two options:

1. Mount a directory that contains all of the files:

   docker run --rm -p 80:80 -p 443:443 --mount type=bind,source=/path/to/config/,target=/config/ imax-streamsmart-onair

   In this case, container looks for the following files in the directory mounted at /config/:

   • config.json - for configuration
   • features.lic - for the license
   • tls.crt - for the TLS certificate, optional
   • tls.key - for the TLS key, optional

2. Mount individual files:

   docker run --rm -p 80:80 -p 443:443 --mount type=bind,source=/path/to/config/config.json,target=/config/config.json --mount type=bind,source=/path/to/config/features.lic,target=/config/features.lic imax-streamsmart-onair

   In this case, the files must be mounted to /config/ with specific destination file names:

   • /config/config.json - for configuration
   • /config/features.lic - for the license
   • /config/tls.crt - for the TLS certificate, optional
   • /config/tls.key - for the TLS key, optional

You have several options to pass the necessary configuration, license, and TLS certificates when launching StreamSmart On-Air. Choose the method that best fits your deployment environment—whether it’s passing them directly via command-line arguments, mounting files from the host system, or using environment variables for more dynamic and cloud-friendly setups.

Before deploying StreamSmart On-Air on AWS, it is important to have the following prerequisites in place to ensure a smooth and successful deployment:

1. Understanding of Media Workflows on AWS

• Familiarity with how to set up and manage media streaming workflows using AWS services such as AWS Elemental MediaLive, MediaPackage, and CloudFront, including an understanding of the difference between MediaLive standard and single-pipeline channels.
• Experience in configuring Adaptive Bitrate (ABR) streaming using HLS or DASH formats is essential, as StreamSmart On-Air integrates seamlessly into these workflows.

2. Experience with Docker Containers

• A solid understanding of Docker, including how to pull, configure, and launch Docker containers.
• Familiarity with passing configuration and environment variables to containers and managing Docker logs for troubleshooting.

3. Experience with AWS Deployment Options

• Knowledge of the AWS deployment option you plan to use (e.g., Amazon ECS, AWS Fargate, Amazon EKS, or Amazon EC2). This includes:
  • Setting up and configuring clusters or instances.
  • Working with IAM roles and policies to grant the necessary permissions for container execution.
  • Configuring networking, security groups, and load balancers as part of your deployment.

4. AWS CLI or Management Console

• Experience using the AWS Management Console or AWS CLI to manage AWS resources, such as creating EC2 instances, setting up ECS clusters, or configuring Fargate tasks.

5. Experience with Infrastructure as Code (IaC) Tools for Automation

• If you plan to automate the deployment of the media workflow, experience with Infrastructure as Code (IaC) tools such as AWS CloudFormation, Terraform, or other automation frameworks is essential. These tools allow you to define and deploy your infrastructure in a consistent and repeatable manner, reducing manual intervention and streamlining the deployment process. Familiarity with writing templates, managing state, and integrating with AWS services will help ensure smooth automation of the deployment.

6. Access to the StreamSmart On-Air Container Image and Valid License

• Work with your IMAX account and/or support representative to obtain the .tar.gz Docker container image file for the release that is right for you. Depending on how you intend to deploy the image, you may want/need to upload the image into Amazon Elastic Container Registry (ECR). You will also need a valid product license to activate and run StreamSmart On-Air. Licenses are typically generated per deployment (e.g. dev, prod), not per deployment instance, and are issued for a one-year subscription to the product and renewed annually.
• StreamSmart On-Air is also available as an AMI-based product on AWS Marketplace. Subscribing to and launching StreamSmart On-Air provides you with EC2 instance that has the Docker runtime environment and StreamSmart On-Air docker container pre-installed. Once deployed, you can access the system via SSH and configure and launch the application the same way that you would if using the container directly or setting up an EC2 instance on your own.

Having this foundational knowledge will ensure you can deploy and manage StreamSmart On-Air efficiently in an AWS environment.

Before you proceed with the installation steps, make sure the AWS user account or role that you will be using to create the stack has the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudformation:CreateChangeSet",
        "cloudformation:CreateStack",
        "cloudformation:DeleteStack",
        "cloudformation:DescribeStacks",
        "cloudformation:GetStackPolicy",
        "cloudformation:GetTemplate",
        "cloudformation:GetTemplateSummary",
        "cloudformation:ListStackResources",
        "cloudformation:ListStacks",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:CreateKeyPair",
        "ec2:CreateSecurityGroup",
        "ec2:CreateTags",
        "ec2:DeleteKeyPair",
        "ec2:DeleteSecurityGroup",
        "ec2:DescribeAvailabilityZones",
        "ec2:DescribeInstanceAttribute",
        "ec2:DescribeInstanceCreditSpecifications",
        "ec2:DescribeInstances",
        "ec2:DescribeKeyPairs",
        "ec2:DescribeNetworkInterfaces",
        "ec2:DescribeRegions",
        "ec2:DescribeSecurityGroupRules",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeVolumes",
        "ec2:DescribeVpcs",
        "ec2:RevokeSecurityGroupEgress",
        "ec2:RevokeSecurityGroupIngress",
        "ec2:RunInstances",
        "ec2:TerminateInstances",
        "iam:AddRoleToInstanceProfile",
        "iam:AttachRolePolicy",
        "iam:CreateInstanceProfile",
        "iam:CreatePolicy",
        "iam:CreateRole",
        "iam:DeleteInstanceProfile",
        "iam:DeletePolicy",
        "iam:DeleteRole",
        "iam:DetachRolePolicy",
        "iam:GetInstanceProfile",
        "iam:GetPolicy",
        "iam:GetPolicyVersion",
        "iam:GetRole",
        "iam:ListAttachedRolePolicies",
        "iam:ListEntitiesForPolicy",
        "iam:ListPolicyVersions",
        "iam:ListRolePolicies",
        "iam:PassRole",
        "iam:RemoveRoleFromInstanceProfile",
        "kms:CreateGrant",
        "kms:Encrypt",
        "kms:GenerateDataKeyWithoutPlaintext",
        "ssm:DeleteParameter",
        "ssm:GetParameter",
        "ssm:ListAssociations",
        "ssm:PutParameter",
        "sts:AssumeRoleWithSAML"
      ],
      "Resource": "*"
    }
  ]
}

You will also need the config.json file and license.lic in an S3 bucket. Talk to your IMAX representative if you do not have those.

The following installation steps and examples will use the AWS Web Console.

1. Login to your AWS account using the AWS Web Console and pick your target region.
   
   

2. From the AWS UI console, choose Services -> Management & Governance -> CloudFormation.
   
   

3. Click Create stack (with new resources) to create a new stack.

   Launch the CloudFormation service, and

   • click the Create stack button to create a stack with new resources,
   • and select the Choose an existing template and Amazon S3 URL options.
     
     

   The IMAX CloudFormation template you want can be found at the following Amazon S3 URL:
   1.1.0: https://imax-sct-public.s3.us-east-1.amazonaws.com/streamsmart-on-air/cf-templates/1.1.0/cloudformation-StreamSmart-On-Air-1.1.0.yaml
   1.1.1: https://imax-sct-public.s3.us-east-1.amazonaws.com/streamsmart-on-air/cf-templates/1.1.1/cloudformation-StreamSmart-On-Air-1.1.1.yaml
   1.1.2: https://imax-sct-public.s3.us-east-1.amazonaws.com/streamsmart-on-air/cf-templates/1.1.2/cloudformation-StreamSmart-On-Air-1.1.2.yaml
   1.1.3: https://imax-sct-public.s3.us-east-1.amazonaws.com/streamsmart-on-air/cf-templates/1.1.3/cloudformation-StreamSmart-On-Air-1.1.3.yaml
   1.1.4: https://imax-sct-public.s3.us-east-1.amazonaws.com/streamsmart-on-air/cf-templates/1.1.4/cloudformation-StreamSmart-On-Air-1.1.4.yaml

4. Specify your stack details, as shown and explained below:

   • Name the stack imax-stream-smart-onair-ami.
     
     

   • StreamSmart On-Air instance target availability zone (AZ)
     Pick your desired availability zone.
     
     

   • StreamSmart On-Air HTTPS access allowlist
     Provide a comma-separated list (no spaces) of IPs, in CIDR notation, that are allowed access the HTTPS interface of your IMAX StreamSmart On-Air instance.

     Important

     Note that all users of the system need access to the HTTPS interface regardless of whether they use the Web UI and/or the REST API.

     You are encouraged to be judicious in your input here such that you include the full range of (company) IP addresses that are allowed access to the system and no more. The values here are used to build the AWS Security Group controlling access to the EC2 instance in the architecture diagram above.
     

     Tip

     Many corporate LANs are configured to use a single IP address/range for all outbound/external Internet access. You may find it convenient to use this IP address/range here, knowing that this should cover all users on your local network.

   • StreamSmart On-Air SSH access allowlist
     Provide a comma-separated list (no spaces) of IPs, in CIDR notation,that are allowed to access the SSH interface of your IMAX StreamSmart On-Air instance. The administrator/deployer is the only role that needs access to the SSH (port 22) interface on your instance for potential deployment and troubleshooting activities. You are encouraged to use a single IP address here (i.e. x.x.x.x/32) where possible.

     Note

     If you are unable to isolate a single IP address for this administrator role and/or you would like to exercise a higher level of security, you are encouraged to remove the SSH inbound rule below from the resulting EC2 security group after the CloudFormation stack completes and add it back only if/when you have additional deployment or troubleshooting activities to perform.

   • StreamSmart On-Air instance target VPC
     Pick a VPC to use when deploying your IMAX StreamSmart On-Air instance.
     You need to ensure that the network access control list (ACL) associated with your target VPC allows inbound/ingress traffic on port 443 and 22 and outbound/egress internet access on port 443. Moreover, your selected VPC must have subnets that support auto-assigning a public IP for EC2 instances deployed therein. In most cases, you should be able to use the default (AWS-created) VPC.
     
     

   • StreamSmart On-Air EC2 instance type and EBS volume (in GB)
     Pick an EC2 instance type and backing EBS volume.
     
     The (encrypted) EBS storage volume is used to hold the video you are optimizing. The default/minimum size here is 50GB.
     
     

   • Bucket to read config and license files from
     Provide the S3 bucket ARN that holds the config and license files, to which read-only access will be granted to the IMAX StreamSmart On-Air instance. Use the full ARN for your S3 bucket here.
     
     

   • Object URL for the config file
     Provide the object URL for the StreamSmart On-Air Configuration file that will be deployed onto the EC2 instance.
     
     

   • Object URL for the license file
     Provide the object URL for the StreamSmart On-Air License file that will be deployed onto the EC2 instance.
     
     

5. Configure stack options and create/submit the stack.

   You should accept all the default options here. Make sure to select the checkboxes that acknowledge that the CloudFormation script will be creating IAM resources, as shown below:

6. Verify that the stack creation completes successfully and click on the Outputs tab. Record the PublicDNS value of your IMAX StreamSmart On-Air instance and use it as the <ec2_public_dns> value in the steps below.
   
   

7. Verify that your IMAX StreamSmart On-Air instance is operational.

   Once your EC2 instance has successfully started, open a new tab in your browser and load the URL: https://<ec2_public_dns>/, where <ec2_public_dns> is the public host name of your EC2 instance you recorded in the previous step (e.g. https://ec2-35-163-225-83.compute-1.amazonaws.com/).

   Important

   It can take several minutes for the virtual machine to initialize and load IMAX StreamSmart On-Air. You can verify the operational status of the EC2 instance by visiting EC2->Instances in the AWS console.

   The system provides TLS through the use of self-signed certificates and, as such, your browser will likely flag the URL/site as a potential security risk. Please direct your browser to accept the certificate and proceed to the site.

   All users of IMAX StreamSmart On-Air will need to accept this certificate in their respective browsers.

   You will then be taken to the IMAX StreamSmart On-Air Dashboard tab.

8. (Optional) Download the Privacy Enhanced Mail (PEM) file associated with your IMAX StreamSmart On-Air instance.

   Run the following commands from a CLI that has the AWS environment variables assigned for your account (i.e. AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN):

   keyPairID=$(aws ec2 --region=<region> describe-key-pairs --filters Name=key-name,Values=imax-stream-smart-on-air-keypair* --query KeyPairs[*].KeyPairId --output text) 
   aws ssm --region=<region> get-parameter --name /ec2/keypair/$keyPairID --with-decryption --query Parameter.Value --output text > imax-stream-smart-on-air-cf-ami.pem 
   chmod 400 imax-stream-smart-on-air-cf-ami.pem
   

   where <region> is your chosen region (e.g. us-east-1).

   Note

   The commands above require the AWS CLI.

   The commands above will create a PEM file that is used for SSH access to your IMAX StreamSmart On-Air EC2 instance and only needed by the administrator/deployer role for deployment and/or troubleshooting activities.
   
   

StreamSmart On-Air as an AMI can be run on Amazon EC2 instances when configured with the appropriate configuration, license, and optionally, TLS certificates for secure communication. This section covers the steps to launch the AMI and thow to provide these inputs.

Quick Start

The AMI is configured to detect files located in the directory /default_run_config and start the Docker container automatically. As such, simply place a features.lic and a config.json file in this directory for StreamSmart On-Air to use.

The following is an example of a config.json file located at /default_run_config/config.json:

{
  "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://wcgoaw-1.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/group1/1/mychannel",
        "https://wcgoaw-2.ingest.t7c7zl.mediapackagev2.us-east-1.amazonaws.com/in/v1/group1/1/mychannel"
      ]
    }
  ]
}

The following is an example of a features.lic file located at /default_run_config/features.lic:

  20bb26a811874bb220d607036e258c72ce6cf579feb4f7ab4f9c8719a2765720
  {
  "expiry": "2030-01-01",
  "organization": "ACME",
  "site": "Production"
}'

StreamSmart On-Air will auto-detect the license and configuration file and start automatically. You can check that it worked by using sudo systemctl status stream-smart-on-air-container.service as follows:

ubuntu@ip-172-31-30-18:~$ sudo systemctl status stream-smart-on-air-container.service
● stream-smart-on-air-container.service - StreamSmart On-Air Container
     Loaded: loaded (/etc/systemd/system/stream-smart-on-air-container.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2025-02-25 21:51:12 UTC; 21min ago
TriggeredBy: ● stream-smart-on-air-container.timer
   Main PID: 4380 (docker)
      Tasks: 11 (limit: 18614)
     Memory: 9.1M
        CPU: 41ms
     CGroup: /system.slice/stream-smart-on-air-container.service
             └─4380 /usr/bin/docker run --rm --name stream-smart-on-air-default -p 80:80 -p 443:443 --mount type=bind,source=/default_run_config/,target=/config/ 573620721324.dkr.ecr.us-east-1.amazonaws.com/imax-streamsmart-onair:1.1.0-1687878758

Prometheus is a powerful open-source tool for monitoring and alerting time series data. StreamSmart On-Air exposes numerical measurements that can be ‘scraped’ by Prometheus and used for validation and oversight of the application.

StreamSmart On-Air uses the text-based exposition format which can be retrieved from the /metrics HTTP endpoint of your installation. All metrics are prefixed with the string imax_ssoa_ and contain various labels informing the specific counters usage. As an example, the counter imax_ssoa_received_manifest_count is a count of the number of manifests received. Labels such as name indicate which manifest has been received. For example, name="anchor.m3u8" indicates the number of times the anchor manifest was received.

Here is a full example showing the number of times that the multivariant, anchor, and candidate manifests have been received by the StreamSmart On-Air file ingest endpoint. As can be seen, each manifest has been received 2220 times while the main.m3u8 manifest has been received a single time.

# HELP imax_ssoa_received_manifest_count Total number of manifest files received by the media server.
# TYPE imax_ssoa_received_manifest_count counter
imax_ssoa_received_manifest_count{name="main.m3u8"} 1
imax_ssoa_received_manifest_count{name="anchor.m3u8"} 2220
imax_ssoa_received_manifest_count{name="candidate1.m3u8"} 2220
imax_ssoa_received_manifest_count{name="candidate2.m3u8"} 2220

StreamSmart On-Air provides numerous counters to indicate reception of data by the ingest endpoint as well as other general request counters. This is valuable in troubleshooting whether the application is receiving data from an upstream sending entity.

imax_ssoa_received_http_requests

The number of http requests received by the HTTP server.

This counter gives an indication as to whether external agents are performing GET, POST, PUT, DELETE, etc… HTTP requests to the StreamSmart On-Air application.

Labels:

• method indicates the HTTP method of the request

# HELP imax_ssoa_received_http_requests The number of http requests received
# TYPE imax_ssoa_received_http_requests counter
imax_ssoa_received_http_requests{method="GET"} 14454

imax_ssoa_received_manifest_count

The number of manifests of a particular name that have been received by the input ingestion endpoint.

This counter gives an indication as to whether specific manifest files have been PUT/POST to the input enpdoint.

Labels:

• name indicates the manifest name that was received.

# HELP imax_ssoa_received_manifest_count Total number of manifest files received by the media server.
# TYPE imax_ssoa_received_manifest_count counter
imax_ssoa_received_manifest_count{name="main.m3u8"} 1
imax_ssoa_received_manifest_count{name="anchor.m3u8"} 2412
imax_ssoa_received_manifest_count{name="candidate1.m3u8"} 2412
imax_ssoa_received_manifest_count{name="candidate2.m3u8"} 2412

imax_ssoa_received_manifest_invalid

The number of manifests of a particular name that have been received and deemed invalid by the input ingestion endpoint.

This counter gives an indication as to whether specific manifest files were able to be parsed and accepted by the application.

Labels:

• name indicates the manifest name that was received.

# HELP imax_ssoa_received_manifest_invalid Total number of manifest files received by the media server.
# TYPE imax_ssoa_received_manifest_invalid counter
imax_ssoa_received_manifest_invalid{name="main_corrupt.m3u8"} 2

imax_ssoa_received_manifest_with_discontinuity

The number of manifests of a particular name that have been received and contained a discontinuity tag by the input ingestion endpoint.

This counter gives an indication as to whether specific manifest files contained a discontinuity tag.

Labels:

• name indicates the manifest name that was received.

# HELP imax_ssoa_received_manifest_with_discontinuity Total number of manifest files received by the media server.
# TYPE imax_ssoa_received_manifest_with_discontinuity counter
imax_ssoa_received_manifest_with_discontinuity{name="main_disc.m3u8"} 27

imax_ssoa_received_segment_count

The number of segments for a particular rendition that has been received by the input ingestion endpoint.

This counter gives an indication as to whether specific rendition’s segment files have been PUT/POST to the input endpoint.

Labels:

• optimization: numeric indicator of which optimization
• stream: indicator as to what type of stream the rendition is

# HELP imax_ssoa_received_segment_count Total number of segments received for a stream.
# TYPE imax_ssoa_received_segment_count counter
imax_ssoa_received_segment_count{optimization="0",stream="anchor"} 2412
imax_ssoa_received_segment_count{optimization="0",stream="candidate1"} 2412
imax_ssoa_received_segment_count{optimization="0",stream="candidate2"} 2412

imax_ssoa_received_segment_bytes

The number of segment bytes for a particular rendition that has been received by the input ingestion endpoint.

This counter gives an indication as to the total size of a rendition’s segment files that have been PUT/POST to the input endpoint.

Labels:

• optimization: numeric indicator of which optimization
• stream: indicator as to what type of stream the rendition is

# HELP imax_ssoa_received_segment_bytes Total number of segment bytes received for a stream.
# TYPE imax_ssoa_received_segment_bytes counter
imax_ssoa_received_segment_bytes{optimization="0",stream="anchor"} 337197364
imax_ssoa_received_segment_bytes{optimization="0",stream="candidate1"} 272661476
imax_ssoa_received_segment_bytes{optimization="0",stream="candidate2"} 208456280

StreamSmart On-Air provides numerous counters to indicate transmission of data as well as general response counters. This is valuable in troubleshooting whether the application is transmitting data to a downstream receiving entity.

imax_ssoa_sent_http_requests

This number of downstream HTTP requests attempted.

This counter is an indicator of the number of times an outgoing HTTP request has been initiated to a downstream receiving entity.

Labels:

• name: A name indicating which rendition the request is for
• method: The HTTP method used
• output: The specific optimization output it was send for
• endpoint: The specific endpoint the request was destined for

# HELP imax_ssoa_sent_http_requests The number of http requests sent
# TYPE imax_ssoa_sent_http_requests counter
imax_ssoa_sent_http_requests{name="master.m3u8",method="PUT",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 2
imax_ssoa_sent_http_requests{name="optimized.m3u8",method="PUT",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 4670
imax_ssoa_sent_http_requests{name="optimized_XXXX.ts",method="PUT",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 4670

imax_ssoa_sent_http_response

This counter specifies how many times an outbound HTTP request received a particular response code.

This counter is an indicator as to whether the downstream receiving entity is receiving the requests as expected.

Labels:

• name: A name indicating which rendition the request is for
• method: The HTTP method used
• code: The HTTP response code received
• output: The specific optimization output it was send for
• endpoint: The specific endpoint the request was destined for

# HELP imax_ssoa_sent_http_response The number of http responses received from sent requests
# TYPE imax_ssoa_sent_http_response counter
imax_ssoa_sent_http_response{name="master.m3u8",method="PUT",code="200",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 2
imax_ssoa_sent_http_response{name="optimized.m3u8",method="PUT",code="200",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 4670
imax_ssoa_sent_http_response{name="optimized_XXXX.ts",method="PUT",code="200",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 4670

imax_ssoa_sent_manifest

This counter specifies how many times a specific manifest was sent successfully.

This counter is an indicator as to whether the downstream receiving entity has accepted a manifest PUT/POST.

Labels:

• name: The specific manifest being sent
• output: The specific optimization output it was send for
• endpoint: The specific endpoint the request was destined for

# HELP imax_ssoa_sent_manifest The number of manifest files successfully sent
# TYPE imax_ssoa_sent_manifest counter
imax_ssoa_sent_manifest{name="anchor.m3u8",output="ANCHOR",endpoint="LOCAL"} 4670
imax_ssoa_sent_manifest{name="anchor_web_vtt_annotations.m3u8",output="ANCHOR",endpoint="LOCAL"} 4670
imax_ssoa_sent_manifest{name="master.m3u8",output="ANCHOR",endpoint="LOCAL"} 2
imax_ssoa_sent_manifest{name="master.m3u8",output="OPTIMIZED",endpoint="LOCAL"} 2
imax_ssoa_sent_manifest{name="master.m3u8",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 4
imax_ssoa_sent_manifest{name="optimized.m3u8",output="OPTIMIZED",endpoint="LOCAL"} 4670
imax_ssoa_sent_manifest{name="optimized.m3u8",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 9340
imax_ssoa_sent_manifest{name="optimized_web_vtt_annotations.m3u8",output="OPTIMIZED",endpoint="LOCAL"} 4670

imax_ssoa_sent_segment

This counter specifies how many times a specific media segment was sent successfully.

This counter is an indicator as to whether the downstream receiving entity has accepted a media segment PUT/POST.

Labels:

• name: The specific manifest being sent
• output: The specific optimization output it was send for
• endpoint: The specific endpoint the request was destined for

# HELP imax_ssoa_sent_segment The number of segment files successfully sent
# TYPE imax_ssoa_sent_segment counter
imax_ssoa_sent_segment{name="anchor_XXXX.ts",output="ANCHOR",endpoint="LOCAL"} 4670
imax_ssoa_sent_segment{name="optimized_XXXX.ts",output="OPTIMIZED",endpoint="LOCAL"} 4670
imax_ssoa_sent_segment{name="optimized_XXXX.ts",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 9340

imax_ssoa_sent_segment_error

This counter specifies how many times a specific media segment failed to send successfully.

This counter is an indicator as to whether the downstream receiving entity is unable to receive segments.

Labels:

• name: The specific manifest being sent
• output: The specific optimization output it was send for
• endpoint: The specific endpoint the request was destined for

# HELP imax_ssoa_sent_segment_error The number of segment files unsuccessfully sent
# TYPE imax_ssoa_sent_segment_error counter
imax_ssoa_sent_segment_error{name="optimized_XXXX.ts",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 2

imax_ssoa_sent_manifest_error

This counter specifies how many times a specific media manifest failed to send successfully.

This counter is an indicator as to whether the downstream receiving entity is unable to receive manifests.

Labels:

• name: The specific manifest being sent
• output: The specific optimization output it was send for
• endpoint: The specific endpoint the request was destined for

# HELP imax_ssoa_sent_manifest_error The number of manifest files unsuccessfully sent
# TYPE imax_ssoa_sent_manifest_error counter
imax_ssoa_sent_manifest_error{name="main.m3u8",output="OPTIMIZED_FULL_LADDER",endpoint="http://packager-simulator-v1:9090/input/"} 2

StreamSmart On-Air provides numerous system level metrics disclosing the general health of the system.

imax_ssoa_daemon_started

This counter indicates how many times a particular daemon has started in the system.

Labels:

• name: Daemon name

# HELP imax_ssoa_daemon_started The number of times the specified daemon has started
# TYPE imax_ssoa_daemon_started counter
imax_ssoa_daemon_started{name="controller"} 1

VBR Mode

When using VBR, Candidates are derived using the following formulas:

• Example Calculation (VBR):
  For an Anchor with Average Bitrate = 5 Mbps and Max Bitrate = 10 Mbps
  The Candidates are calculated as follows:
  • Candidate 1 = 4.4 Mbps avg Bitrate, 8.8 Mbps max Bitrate
    
  • Candidate 2 = 3.8 Mbps avg Bitrate, 7.6 Mbps max Bitrate
    

QVBR Mode

When using QVBR, Candidates are set using Quality Levels (QL) and Max Bitrate adjustments:

If the Anchor QL is set to 10, use 10, 9, and 8.
If the Anchor QL is set to 8, use 8, 7, and 6.

For simple content (low motion, low complexity), additional tuning is applied:

If the Anchor QL is set to 8, use 8, 8, 7