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 available as a Docker container as well as an AMI which can be deployed through AWS Marketplace offerings. 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.

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

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 (c6i.4xlarge) and at least 50 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 Media services and StreamSmart On-Air, 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 in 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 receive 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 receive the output of MediaLive.
• Steps:
  • Deploy the StreamSmart On-Air container(s) through 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 endpoint(s). If you have deployed your StreamSmart On-Air container(s) into a private subnet, you will have to setup a NAT gateway(s) in your VPC to allow outbound HTTPS to your MediaPackage ingest endpoint(s).
    • Ensure that the routing table associated with the chosen subnet has a route from the StreamSmart On-Air instance to the NAT gateway (if using private subnet) or an internet gateway attached to the parent VPC (if using public subnet).
    • Select a security group that contains the following rules:
      • Allow inbound HTTPS 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 HTTPS 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 AMI on EC2, you may 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 IMAX’s AMI, 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 (e.g. 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.

In order to deploy using IMAX’s CloudFormation template, the following are prerequisites:

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 MediaConnect, 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. Basic familiarity with AWS tools and services

   • Some basic knowledge and experience with the AWS console and/or CLI and the following services:
     • CloudFormation,
     • VPC, subnet, NAT gateway, Internet gateway,
     • IAM roles and policies and
     • EC2 instances, security groups and load balancers.
       
       

3. Access to an AWS user account or role with AWS::AdminstratorAccess permission

   You are encouraged to use an account with AWS::AdminstratorAccess permission when executing the CloudFormation template as there are a variety of AWS services being created and configured.
   
   

4. A valid StreamSmart On-Air license

   • If you are deploying the StreamSmart On-Air (BYOL) Marketplace product (i.e. option 2 above), you need to contact your IMAX representative for a valid StreamSmart On-Air license.
     
   • If you are deploying the StreamSmart On-Air Marketplace product (i.e. option 1 above), you don’t have to do anything here.
     
     

5. Validate required AWS service quotas and region support

   The AWS Media Services workflow with CloudFormation creates the following AWS services:

   • 1 VPC, 1 public subnet, 1 private subnet, 1 NAT gateway, 1 Elastic IP (EIP) in each of the chosen 2 availability zones
   • 1 (SINGLE pipeline) or 2 (STANDARD pipeline) MediaConnect flow(s)
   • 1 MediaLive channel
   • 1 MediaPackage channel with 1 HLS and 1 DASH origin endpoint
   • 1 (SINGLE pipeline) or 2 (STANDARD pipeline) StreamSmart On-Air EC2 instance(s)
   • Up to 2 elastic load balancers (private, public-facing) per StreamSmart On-Air EC2 instance
   • 1 CloudFront distribution
   • Various IAM roles, policies and security groups
     
     

   By default, AWS accounts are limited as to the number of services, such as elastic IPs (EIPs) and MediaLive channels/inputs, that can exist at any one time. Depending on the existing services in your account, you may need to contact AWS and ask for increases in your service quotas before executing the IMAX CloudFormation template. For example, a full workflow deployment uses 2 EIPs and, by default, AWS accounts are allotted only 5 EIPs. Additionally, AWS Media Services are not available in all regions. Please check to ensure that your chosen region is supported.

   Failure to adhere to service level quotas or region availability will result in CloudFormation template/stack execution errors. Use the AWS web console to inspect such errors and, if you are unsure how to resolve them, please reach out to your IMAX representative for additional support.

Use the following section for guidance on the CloudFormation template parameters.

AWS Common Configuration

• Primary Availability Zone

  Represents the primary availability zone where AWS Media services and StreamSmart On-Air resources will be created. Note this value is required in order for the stack to execute successfully and must be different from the value for the Second Availability Zone below.
  
  

• Secondary Availability Zone

  Represents the secondary availability zone where AWS Media services and StreamSmart On-Air resources will be created. Note this value is required in order for the stack to execute successfully and must be different from the value for the Primary Availability Zone above.

AWS Elemental Configuration

• Channel Class

  Represents whether your MediaLive channel should be STANDARD or SINGLE_PIPLINE.
  STANDARD pipelines support redundancy by having both primary and redundant flows whereas a SINGLE pipeline has only one flow.
  
  

• Protocol

  Represents the protocol chosen for your AWS MediaConnect flow(s).
  
  

• MediaConnect flow allowlist

  A single CIDR block, representing one or more IP addresses, that is allowed to connect/write to the AWS MediaConnect flow(s) created as part of your workflow deployment. You must specify a CIDR block here and you are strongly encouraged to use a value that restricts access to IPs from your network.
  Example: x.x.x.x/32
  
  

• Profile

  Controls the encoder settings (bitrate etc.) used with the created AWS MediaLive channel. Currently, there are profile options for HD and UHD.

IMAX StreamSmart On-Air Configuration

• StreamSmart On-Air HTTP/HTTPS allowlist

  A single CIDR block, representing one or more public/internet IP addresses, that is allowed to access the HTTP/S interface of your IMAX StreamSmart On-Air instance, via a public-facing elastic load balancer (ELB). If this value is left blank, the public-facing ELB will not be created and the aforementioned HTTP/S interface will remain private and unreachable from outside your VPC’s private subnet. Regardless of the value provided here, a private elastic load balancer (ELB) is always created, as part of the workflow, in order to provide (private) brokered access to the HTTP/S interface from IPs in your VPC’s private subnet.
  Example: x.x.x.x/16

  Important

  If you decide to leave this value blank and keep the HTTP/S interface of the StreamSmart On-Air instance private, you will need to arrange for some means of accessing this interface if you need to use the StreamSmart On-Air Web UI or REST API. Note that all users of the StreamSmart On-Air Web UI and/or REST API require access to the HTTP/S interface. Additionally, for those deploying the StreamSmart On-Air (BYOL) product in AWS Marketplace (see option 2 here), you will need access to the HTTP/S interface in order to apply your license.

• StreamSmart On-Air TLS certificate

  A TLS certificate to use with your StreamSmart On-Air deployment’s HTTPS interface. Supplying a value here will allow you to create a DNS A record (i.e. in Route 53) that binds the hostname associated with your certificate to the DNS value for your (public/private) StreamSmart On-Air elastic load balancer (ELB), provided as an output value upon successful execution of this stack. If you plan to make regular use of the StreamSmart On-Air Web UI or REST API, you are strongly encouraged to provide a certificate value here as it affords you full control over the hostname associated with the underlying EC2 instance and a proper/validated certificate. If this value is left blank, your StreamSmart On-Air will provide only an HTTP interface.
  Example: arn:aws:acm:us-east-1:<AccountNumber>:certificate/8dee3f52-376d-22b2-ab88-7f9ea45479c1.
  
  

• StreamSmart On-Air AMI

  Use this value to override the built-in defaults and specify a custom/pre-release AMI for your StreamSmart On-Air deployment. You should only provide a value here if so directed by your deployment instructions.
  AWS Marketplace deployments pre-fill this value and it must not be changed.
  
  

• StreamSmart On-Air EC2 instance type

  The EC2 instance type to use for your IMAX StreamSmart On-Air instance. The default is c5.4xlarge.
  
  

• StreamSmart On-Air EBS volume (in GB)

  The size (in GB) of the EBS volume to use with your IMAX StreamSmart On-Air EC2 instance. The default size is 50GB.
  
  

Once you have supplied the necessary parameters, you are ready to execute the CloudFormation stack. You should be free to accept all the default stack options, including acknowledging any stack capabilities. The full workflow can take up to 25 minutes to successfully execute.

The full media services workflow consists of several nested stacks, each with its own set of related tasks/events, resources created and outputs recorded. Under the Outputs for the StreamSmart On-Air nested stack(s), you should see values for StreamSmartOnAirPrivateDNS and StreamSmartOnAirPublicDNS, as shown in the example below for the primary instance:

The StreamSmartOnAirPublicDNS is the DNS value for the public-facing elastic load balancer (ELB) brokering access to the HTTP/S interface of your StreamSmart On-Air instance. Provided your public IP matches the CIDR specified during the configuration of your template parameters, you can load this ELB hostname directly into your browser and it should result in the display of the StreamSmart On-Air Web UI. You can also use this hostname value to access the StreamSmart On-Air REST API.

If you supplied a TLS certificate as a template parameter, you should be able to use the hostname associated with the certificate in place of the ELB’s (awkward) hostname, provided that you first create and register a DNS A record binding your certificate with the ELB hostname.

Once the template’s stack has completed successfully, you need to perform these final steps in order to start the workflow:

1. Ensure StreamSmart On-Air is licensed

   If you deployed using the StreamAware On-Air (BYOL) product in AWS Marketplace (option 2 here), you must configure your StreamSmart On-Air instance(s) with a valid license now. To load a license using the StreamSmart On-Air Web UI, follow the instructions for obtaining your hostname(s) here and then navigate to the Settings page described here to upload your license.

   Note

   If you have configured a STANDARD pipeline, you will need to upload your license into both the primary and secondary StreamSmart On-Air instances.

2. Start the AWS MediaConnect flow(s)
   
   

3. Start the AWS MediaLive channel
   
   

4. Stream media content to your AWS MediaConnect flow(s)

   If you created srt-listener flow(s), for example, you would need to start your srt-producer processes/services that will connect to the flow’s inbound source IP and stream your source media content.
   
   

5. Inspect the running workflow

   Under the Outputs for the main stack, you should see a value for the CloudFront domain, StreamSmartOnAirCloudFrontDomain, created as part of the workflow:

   Key	Value	Description
   StreamSmartOnAirCloudFrontDomain	d34xbtwev0ybb7.cloudfront.net	The StreamSmart On-Air CloudFront domain

   You can substitute the CloudFront domain value above for the hostname used in the URL for your MediaPackage channel to see the StreamSmart-optimized output via your AWS CDN. Using the HLS endpoint from a sample deployment, for example, the Manifest settings reports the master URL as: https://i9af9q.egress.szy3xx.mediapackagev2.us-east-1.amazonaws.com/out/v1/StreamSmartOnAirChannelGroup-cd19d4c0/StreamSmartOnAirChannel-cd19d4c0/HLS/master.m3u8. Substituting i9af9q.egress.szy3xx.mediapackagev2.us-east-1.amazonaws.com with the value for the StreamSmartOnAirCloudFrontDomain above (i.e. d34xbtwev0ybb7.cloudfront.net) gives you the following URL: https://d34xbtwev0ybb7.cloudfront.net/out/v1/StreamSmartOnAirChannelGroup-cd19d4c0/StreamSmartOnAirChannel-cd19d4c0/HLS/master.m3u8. Loading this URL stream into a suitable player will allow you to view the StreamSmart-optimized output for your media content, taking advantage of the CDN features provided by AWS CloudFront.

   Additionally, you can load the StreamSmart On-Air Web UI for your instance(s) and view the Dashboard and Player tabs to see the progress and savings provided by StreamSmart.

The CloudFormation template is designed to execute until completion without requiring further input. In the event of an error, there will be a message reported in the CloudFormation service and you are encouraged to use the AWS web console to discover the root cause, which should, itself, be clearly labelled. Failed stacks can be deleted and the process of creating a new stack can be repeated once the error has been remedied. If you are unable to determine the root cause of the error or how to resolve it, please reach out to your IMAX representative.

The following are prerequisites for deploying the StreamSmart On-Air AMI:

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 MediaConnect, 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. Basic familiarity with AWS tools and services

   • Some basic knowledge and experience with the AWS console and/or CLI and the following services:
     • EC2 and security groups,
     • VPC, subnet, NAT gateway, Internet gateway.
       
       

3. Access to an AWS user account or role with ec2::* permissions

   You are encouraged to use an account with ec2::* permissions when deploying the StreamSmart On-Air instance.
   
   

4. A valid StreamSmart On-Air license

   • If you are deploying using the StreamSmart On-Air (BYOL) Marketplace product (i.e. option 2 above), you will need to contact your IMAX representative for a valid StreamSmart On-Air license.
     
   • If you are deploying using the StreamSmart On-Air Marketplace product (i.e. option 1 above), you do not have to do anything here.

When you launch the StreamSmart On-Air AMI from the AWS Marketplace, your browser is automatically redirected to the EC2 launch service within the AWS Web console. The StreamSmart On-Air AMI that is appropriate for your selected version and region is automatically selected, as is the preferred/default instance type.

The following additional steps should be taken next:

1. Create a key pair

   Create a key pair for secure SSH access to the resulting EC2 instance. Store the resulting PEM file locally.
   
   

2. Configure the networking Settings

   • Select an appropriate VPC and Subnet

     If you deploy to a private subnet, the HTTP/S interface of the StreamSmart On-Air instance will only be visible to IPs inside that private subnet unless additional services and/or network configuration is done to expand visibility/access. Note that all users of the StreamSmart On-Air Web UI and/or REST API require access to the HTTP/S interface.
     
     

   • Select/create an appropriate security group

     The default security group here is likely not sufficient for your needs as it is configured to allow all HTTP/S traffic from the Internet. You will want to select/create a security group that allows HTTP/S connections from your AWS MediaLive channel as well as HTTPS outbound connections to your AWS MediaPackage channel’s ingest endpoints. Please refer to our guidance on deployment details addressed in the Overview and Deployment Order sections. Finally, you will want to consider allowing incoming HTTP/S (and possibly SSH) to the StreamSmart On-Air instance for those that may want to use the StreamSmart Web UI or REST API.
     
     

3. Increase the root volume storage

   Under the Configure storage section, update the root volume to ensure that it has the following properties:

   • 50G size,
   • volume type of gp3,
   • encryption enabled and
   • delete on termination.
     
     

4. Configure StreamSmart On-Air instance with User Data

   Here we will use User data feature (i.e. Advanced details->User data in AWS Web EC2 console) to (pre)configure the StreamSmart On-Air instance with its configuration JSON file and, if needed, your product license.

   You can read about the StreamSmart On-Air configuration file here but for the purposes of this step, we’ll use the example below:

   {
     "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://qfe49g-1.ingest.szy3xx.mediapackagev2.us-east-1.amazonaws.com/in/v1/BigBuckBunnyChannelGroup/1/bigbuckbunny-channel"
         ]
       }
     ]
   }
   

   If you are deploying using the StreamSmart On-Air (BYOL) Marketplace product (i.e. option 2 above), you will have acquired a StreamSmart On-Air license from your IMAX representative as part of the prerequisites. For the purposes of this step, we’ll use the example below:

   20bb26a811874bb220d607036e258c72ce6cf579feb4f7ab4f9c8719a2765720
   {
     "expiry": "2025-12-31",
     "organization": "ACME",
     "site": "Production"
   }
   

   Using the content above, add the following cloud-init directives to the User data for the EC2 instance:

   #cloud-config
   write_files:
   - content: |
       {
         "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://qfe49g-1.ingest.szy3xx.mediapackagev2.us-east-1.amazonaws.com/in/v1/BigBuckBunnyChannelGroup/1/bigbuckbunny-channel"
             ]
           }
         ]
       }
     path: /default_run_config/config.json
     permissions: '0644'
   - content: |
       20bb26a811874bb220d607036e258c72ce6cf579feb4f7ab4f9c8719a2765720
       {
         "expiry": "2025-12-31",
         "organization": "ACME",
         "site": "Production"
       }
     path: /default_run_config/features.lic
     permissions: '0644'
   

   The image below shows what this looks like from the AWS Web console:

   If you are deploying using the StreamSmart On-Air Marketplace product (i.e. option 1 above), you do not need to acquire a license directly from IMAX and so your User data content will omit the license and provide only the JSON config:

   #cloud-config
   write_files:
   - content: |
       {
         "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://qfe49g-1.ingest.szy3xx.mediapackagev2.us-east-1.amazonaws.com/in/v1/BigBuckBunnyChannelGroup/1/bigbuckbunny-channel"
             ]
           }
         ]
       }
     path: /default_run_config/config.json
     permissions: '0644'
   

The following are prerequisites:

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

2. Access to the StreamSmart On-Air container image and a 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. 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.

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.

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.

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