StreamSmart™ is an enterprise software product that lets you encode smarter and save money. StreamSmart™ overlays on your existing encoding workflow and uses the most accurate measure of video quality, IMAX SVS (SSIMPLUS® Viewer Score), to retain the same visual quality of experience, while delivering a significant reduction in delivery costs.

The result? Millions of dollars in savings each year, typically 15-25% above what content-aware encoders are already delivering. StreamSmart™ has enabled a prominent streaming platform provider to save close to $25M annually by reducing bandwidth consumption across 22,000 titles, without affecting perceptual quality.

How does it work? The figure below shows a typical VOD workflow where a VOD processing queue module schedules jobs by pushing the content and the encoder configuration to the video encoding block. The output is then provided to an origin server and to a content delivery network (CDN) for delivery.

In the following figures, StreamSmart™ is installed as a smart layer for the video encoding block, where the VOD processing queue module provides the encoder configuration and the content path to the StreamSmart™ orchestration layer. StreamSmart™, based on the encoding configuration being used (denoted by the “anchor” encode), uses IMAX’s perceptual quality technology to determine the optimal revised configurations for some additional encodes (denoted as the “candidate” encodes).

All encoded segments for the anchor and the candidate encodes are scored using the IMAX SSIMPLUS® metric and then the selection process of picking the segments that meet the objective of maintaining the perceptual picture quality at the lowest possible bitrate.

Terminology and Branding

Let’s take a look at the StreamSmart™ system architecture and call out some key details of each component within the context of a typical workflow. The diagram below represents a common view of the system architecture, regardless of your deployment model:

• The IMAX Stream™ On-Demand Platform is the customer-deployed portion of the StreamSmart™ system and is designed as a set of cooperating software (Docker) containers that are orchestrated by Kubernetes.

  • The StreamSmart™ API & Services are a set of always-running containers that provide the following:

    • A REST API known as the Stream™ On-Demand REST API that can be used to:

      • Submit new encoding optimization requests
      • Visually inspect the results by capturing frames and a number of SSIMPLUS® maps (i.e. quality maps, banding maps, color volume difference maps).
        
        
      Important

      The Stream™ On-Demand REST API provides an OpenAPI Specification (OAS) that can be used to generate language-specific clients for those interested in jump-starting an integration into their production workflow. Both Swagger Codegen and OpenAPITools openapi-generator are examples of tools that can be used for this purpose. Additionally, any laguage that has support for sending and receiving HTTP requests/responses in JSON format can be also be used with minimal effort. Please contact your SSIMWAVE representative if you require any guidance.

    • Services for interacting with Kubernetes to take advantage of its various deployment, scaling, scheduling and management features

    • Services for interacting with various cloud API services (i.e. Amazon S3)
      
      

    For fixed scale deployments of the IMAX Stream™ On-Demand Platform, there is only ever one running instance of each container as the scalability needs here are expected to be relatively low. Elastic scale deployments of the cluster, by contrast, will elastically scale these containers to meet the demand.
    
    

  • The Optimizers are Docker containers that drive the encoding and perform the optimization, generating the SSIMPLUS® metadata and metrics that are securely streamed to Insights. Optimizers are configured, deployed and managed by the Stream™ On-Demand REST API in response to POST requests to analyze one or more video assets.

    • Each Optimizer container is configured to request the compute resources (CPU/RAM) it needs in order to succesfully perform its analysis, given the properties of the assets being analyzed.

    • Optimizer containers never stream any part of the video to Insights and, as such, no content (i.e. video, frames or images) ever leaves the customer’s environment/control.

      Note

      Upon request, SSIMWAVE will provide examples of the metrics and metadata streamed to Insights.

    • For fixed scale deployments of the IMAX Stream™ On-Demand Platform, the number of concurrently running Analyzers will scale but only to a fixed number, as the cluster itself is constrained by the underlying properties of the virtual machine (i.e. OVA/QEMU) or EC2 instance (i.e. AMI). Elastic scale deployments of the cluster, by contrast, can elastically scale without an upper bound, if so desired, in order to meet even the most demanding analysis workloads.

  
  

• Insights is SSIMWAVE’s multi-tenant cloud platform that leverages the power of our own viewer intelligence algorithms, along with leading business intelligence services, to present meaningful representations of the encoding and optimization results. Some of the key features of Insights include:

  • Insights VOD Monitor Web UI which can be used to:
    • view and interact with a summary/status of all analyses (both VOD Monitor analyses and StreamSmart™ optimizations),
    • review results and
    • perform frame-level inspections of your content, including image and map comparisons.
      
      
  • Insights REST API which can be used to:
    • fetch all captured metrics and measurements across a variety of time granularities including:
      • per-frame,
      • per-second (1s, 2s, 5s, etc.) and
      • per-asset.
  • Insights dashboards and reports which are customizable content displays of analysis results that can be used interactively in the Web UI and exported in various archival formats such as PDF, PNG/JPG, Excel, JSON, etc.
    
    

• The Automation computer/laptop icon above illustrates that the full StreamSmart™ system is designed to be used in a headless manner (i.e. through API/programmatic access) and that most key features are exposed through their respective REST APIs.
  
  

• The user/human icon and its connections above illusrate that:

  • to support those integrating StreamSmart™ into their production workflows, SSIMWAVE has provided Postman collections with numerous REST API examples that can be imported into the Postman UI in order to become familiarized with the API request/response structures and
  • the Insights VOD Monitor Web UI can equally be used to interact graphically with the system by submitting the underlying API requests on the user’s behalf.

The IMAX Stream™ On-Demand Platform can be deployed in the following ways:

Fixed scale:

• As an EC2 instance on AWS using the IMAX Stream AMI
• As a virtual machine instance using an OVA or QEMU image

Elastic/dynamic scale:

• On Kubernetes using the provided container images and manifests (AWS EKS or otherwise)
• On AWS EKS as a managed service

For details, refer to the Deployment Guides section.

Now that we’ve provided some detail on the high level components of the system architecture, let’s walk through the process of a typical optimization, along with some sample requests/responses in JSON. For the examples that follow, we are going to use assume a production deployment and workflow, which leverages the REST APIs for programmatic control and the Insights Web UI for out-of-band/follow-up inspections of the results. Lab/trial workflows would likely use the Insights Web UI exclusively.

1. Submit an FFmpeg encoding/optimization request using the Stream™ On-Demand REST API and the submit new FFmpeg optimization endpoint.

   {
     "content": {
       "title": "Example Title"
     },
     "input": {
       "name": "example/input/path/example_source_file.mov",
       "storageLocation": {
         "type": "S3",
         "name": "example-s3-bucket-name"
       }
     },
     "encoderConfig": {
       "type": "FFmpegConfig",
       "encodes": [
         {
           "command": [
             "ffmpeg -i {INPUT_LOCATION} -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=48:keyint_min=48:scenecut=0\" -profile:v high -level:v 4.1 -preset slow -b:v 4500k -maxrate 4500k -bufsize 6000k -an {OUTPUT_LOCATION}"
           ],
           "outputLocation": {
             "name": "example/output/path/encoded_video.mp4",
             "storageLocation": {
               "type": "S3",
               "name": "example-s3-bucket-name"
             }
           }
         }
       ]
     }
   }
   

   A successful response from the Stream™ On-Demand REST API would look something like the following:

   {
     "uuid":"a378d122-fd7e-4f12-8a34-7f60cc129216",
     "organization":"SSIMWAVE",
     "site":"StreamSmart",
     "title":"Example Title",
     "status":"Created",
     "config":{
       "encodes":[
         {
           "commands":[
             "ffmpeg -r 24 -i {INPUT_LOCATION} -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range mpeg -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=50:keyint_min=50:scenecut=0:stitchable=1\" -profile:v high -level:v 4.1 -b:v 5000k -maxrate 6250k -bufsize 10000k -r 24 -vf scale=1920x1080 -an {OUTPUT_LOCATION}"
           ],
           "outputLocation":{
             "path":"example/output/path/example_output_file.ts",
             "storageLocation":{
               "type":"S3",
               "name":"example-s3-bucket-name"
             }
           }
         }
       ],
       "inputLocation":{
         "key":"example/input/path/example_source_file.mov",
         "storageLocation":{
           "type":"S3",
           "name":"example-s3-bucket-name"
         }
       }
     }
   }
   

   Notice in the response above the line "uuid": "a378d122-fd7e-4f12-8a34-7f60cc129216" reports back the analysis UUID which is the required key for fetching the status and results from Insights.

   Alternatively, you can submit an optimization that uses AWS Elemental MediaConvert (EMC) using an example like the following:

   {
     "content": {
       "title": "Example Title"
     },
     "encoderConfig": {
       "type": "EMCConfig",
       "config": {
         "JobTemplate": "",
         "Queue": "arn:aws:mediaconvert:us-east-1:315835334412:queues/Default",
         "UserMetadata": {},
         "Role": "arn:aws:iam::315835334412:role/mediaconvert-optimizer",
         "Settings": {
           "OutputGroups": [
             {
               "CustomName": "top-profile-encode",
               "Name": "CMAF",
               "Outputs": [
                 {
                   "ContainerSettings": {
                     "Container": "CMFC"
                   },
                   "VideoDescription": {
                     "Width": 1920,
                     "ScalingBehavior": "STRETCH_TO_OUTPUT",
                     "Height": 1080,
                     "TimecodeInsertion": "DISABLED",
                     "AntiAlias": "ENABLED",
                     "Sharpness": 50,
                     "CodecSettings": {
                       "Codec": "H_264",
                       "H264Settings": {
                         "InterlaceMode": "PROGRESSIVE",
                         "NumberReferenceFrames": 3,
                         "Syntax": "DEFAULT",
                         "Softness": 0,
                         "GopClosedCadence": 1,
                         "GopSize": 2,
                         "Slices": 1,
                         "GopBReference": "ENABLED",
                         "HrdBufferSize": 16000000,
                         "MaxBitrate": 8000000,
                         "EntropyEncoding": "CABAC",
                         "RateControlMode": "QVBR",
                         "QvbrSettings": {
                           "QvbrQualityLevel": 9
                         },
                         "CodecProfile": "HIGH",
                         "MinIInterval": 0,
                         "AdaptiveQuantization": "AUTO",
                         "CodecLevel": "AUTO",
                         "SceneChangeDetect": "ENABLED",
                         "QualityTuningLevel": "SINGLE_PASS",
                         "UnregisteredSeiTimecode": "DISABLED",
                         "GopSizeUnits": "SECONDS",
                         "ParControl": "INITIALIZE_FROM_SOURCE",
                         "NumberBFramesBetweenReferenceFrames": 3,
                         "RepeatPps": "DISABLED",
                         "DynamicSubGop": "ADAPTIVE"
                       }
                     }
                   },
                   "NameModifier": "_8Mbps"
                 }
               ],
               "OutputGroupSettings": {
                 "Type": "CMAF_GROUP_SETTINGS",
                 "CmafGroupSettings": {
                   "TargetDurationCompatibilityMode": "SPEC_COMPLIANT",
                   "WriteHlsManifest": "ENABLED",
                   "WriteDashManifest": "ENABLED",
                   "SegmentLength": 4,
                   "Destination": "s3://s3-bucket/destination/path/",
                   "FragmentLength": 2,
                   "SegmentControl": "SEGMENTED_FILES",
                   "WriteSegmentTimelineInRepresentation": "ENABLED",
                   "ManifestDurationFormat": "FLOATING_POINT",
                   "StreamInfResolution": "INCLUDE"
                 }
               }
             }
           ],
           "Inputs": [
             {
               "AudioSelectors": {
                 "Audio Selector 1": {
                   "DefaultSelection": "DEFAULT"
                 }
               },
               "VideoSelector": {
                 "ColorSpace": "FOLLOW",
                 "Rotate": "DEGREE_0",
                 "AlphaBehavior": "DISCARD"
               },
               "FilterEnable": "AUTO",
               "PsiControl": "USE_PSI",
               "FilterStrength": 0,
               "DeblockFilter": "DISABLED",
               "DenoiseFilter": "DISABLED",
               "TimecodeSource": "ZEROBASED",
               "FileInput": "s3://s3-bucket/sources/source.mov"
             }
           ]
         },
         "AccelerationSettings": {
           "Mode": "DISABLED"
         },
         "StatusUpdateInterval": "SECONDS_15",
         "Priority": 0,
         "HopDestinations": []
       },
       "region": "us-east-1",
       "endpointURL": "https://vasjpylpa.mediaconvert.us-east-1.amazonaws.com"
     }
   }
   

   The following diagram illustrates the state of the system in response to the requests above:

   

   At this point the StreamSmart™ API & Services have:

   • validated the POST Optimization Request,
   • inspected the properties of the underlying asset to determine the compute resources needed to analyze the asset,
   • deployed a new Optimizer container to process the video file and
   • prepared and returned a response to the caller.
     
     

2. The Optimizer container(s) use the specified encoder with the specified configuration to encode, and then optimize, the video. The progress and results are streamed to Insights. Once the analysis is complete, acknowledgements are recognized by both sides and the Optimizer container is destroyed (i.e. elastic scaling) in order to release the compute resources being used by the IMAX Stream™ On-Demand Platform.

   
   

3. Using the Insights REST API’s api/4.0/queries/run/json endpoint, we can fetch the status of the workflow to check if encoding and optimization has been completed.

   {
     "model": "vod_monitor",
     "view": "vod_status_analysis",
     "fields": [
       "vod_status_analysis.analysis_uuid",
       "vod_status_analysis.time",
       "vod_status_analysis.min_time",
       "vod_status_analysis.test_id",
       "vod_status_analysis.test_video",
       "vod_status_analysis.reference_video",
       "vod_status_analysis.stage",
       "vod_status_analysis.percent_done",
       "vod_status_analysis.test_count"
     ],
     "filters": {
       "vod_status_analysis.analysis_uuid": "<analysis_uuid>"
     }
   }
   

   where <analysis_uuid> is the UUID for the analysis retrieved from the response in step 1. In this specific example, the value would be a378d122-fd7e-4f12-8a34-7f60cc129216.

   The response indicates either that the workflow is in progress:

   [
     {
       "vod_status_analysis.analysis_uuid": "a378d122-fd7e-4f12-8a34-7f60cc129216",
       "vod_status_analysis.time": "2023-04-13 14:44:51",
       "vod_status_analysis.min_time": "2023-04-13 14:43:35",
       "vod_status_analysis.stage": "Encoding",
       "vod_status_analysis.percent_done": 78,
       "vod_status_analysis.test_count": 3
     }
   ]
   

   …or that it has completed:

   [
     {
       "vod_status_analysis.analysis_uuid": "a378d122-fd7e-4f12-8a34-7f60cc129216",
       "vod_status_analysis.time": "2023-04-13 14:45:23",
       "vod_status_analysis.min_time": "2023-04-13 14:43:35",
       "vod_status_analysis.stage": "Results Ready",
       "vod_status_analysis.percent_done": 100,
       "vod_status_analysis.test_count": 3
     }
   ]
   

   Once the optimization has completed, both the ‘Anchor’ encode (the unoptimized encode created using your encoder configuration), and the ‘Output’ (the optimized encode) will be available in the specified output location and can be inspected using the Insights REST API and/or the Web UI, as shown below:

   

To get started using the product, it is recommended that you take the following approach:

1. Review the SSIMPLUS® Terminology and Features section.

   Here you can familiarize yourself with the various metrics and measurements supported by StreamSmart™ and which ones may be applicable to your specific use cases.
   
   

2. Book a demo/meeting with a SSIMWAVE representative.

   If you haven’t already, consider booking a demonstration with your SSIMWAVE representative where you can see:

   • a product overview, important features and future roadmap,
   • how to use the Insights Web UI,
   • how to use the Insights dashboards/reports and make customizations desired for your use cases and
   • examples of common exchanges with the StreamSmart™ and Insights REST APIs.
     
     

3. Use the StreamSmart™ Postman Collection to submit an encode/optimization.

   The best way to fully appreciate the product is to get busy using it.

For those ready to plan a production deployment, you are strongly encouraged to consider the following additional steps:

4. Install Postman and import the StreamSmart™ collection and environment.
   
   

5. Review the Stream™ On-Demand REST API and Postman examples.
   
   

6. Review the Insights REST API and Postman examples.
   
   

7. Start building your client/workflow code in your language of choice using the API experience you’ve gained above.

   Important

   The Stream™ On-Demand REST API provides an OpenAPI Specification (OAS) that can be used to generate language-specific clients for those interested in jump-starting an integration into their production workflow. Both Swagger Codegen and OpenAPITools openapi-generator are examples of tools that can be used for this purpose. Additionally, any laguage that has support for sending and receiving HTTP requests/responses in JSON format can be also be used with minimal effort. Please contact your SSIMWAVE representative if you require any guidance.

Once you’ve worked through the Using StreamSmart™ section, you’re ready to get down to the business of using the Insights platform!

To start using Insights, you will need an account along with a clientId and clientSecret to access the Insights REST API. If you have not done so already, please use the SSIMWAVE Help Center to create a ticket specifying your organization and the email address you wish to use as your account login. Alternatively, you can send these values to your SSIMWAVE representative using Slack/email. Next, follow the instructions in your invitation email to set up your account. With a new account in place, you can login to the Insights VOD Monitor app along with a shared space that has been created for your organization, which includes pre-created dashboards to address the usage scenarios that will be of interest to you. Refer to the Insights Web UI section for a brief introduction to the Insights UI.

The Insights VOD Monitor app provides a curated GUI for:

• submitting ad hoc analyses to your SSIMPLUS® Analyzer Cluster (Analyze - Submit an analysis),
• viewing the results of in-progress and past analyses (Results - View analysis and optimization results),
• performing detailed frame-level inspections of the results (Viewer - frame/map inspection) and
• defining and submitting optimization requests (Optimize - Submit a video asset for optimization) and
• managing a library of previously submitted analyses (Status - View analysis and optimization status).

The Insights REST API exposes a single endpoint for all requests: /api/4.0/queries/run/json?cache=false and each request must be sent using HTTP POST semantics.

Let’s examine the body of a typical Insights POST request shown below:

{
    "model": "vod_monitor",
    "view": "vod_analysis_results",
    "fields": [
        "vod_analysis_results.test_id",
        "vod_analysis_results.test_video_time_1s",
        "vod_analysis_results.ssimplus_viewer_score"
        .
        .
    ],
    "filters": {
        "vod_analysis_results.analysis_uuid": "59508525-070d-428b-8857-d5482bf7c690",
        .
        .
    },
    "sorts": [
        "vod_analysis_results.test_video_time_1s",
        "vod_analysis_results.test_id",
        .
        .
    ]
}

• Every Insights request must specify the model attribute and, for the StreamSmart™ product, its value should always be vod_monitor.
• Every Insights request must specify a view attribute (see Supported Views below).
• Every Insights request should specify a list of view fields whose data will be included in the response. A field is specified using the <view>.<field_name> notiation.
• An Insights request may specify a list of filters which are view fields that are constrained to various values and/or ranges in order to limit/control the data retrieved. The most common filter to use here is <view>.analysis_uuid, which constrains the results to a single analysis UUID (see example above). Filters become invaluable when your Insights responses return large datasets, as is the case when fetching frame results.
• An Insights request may specify a list of sorts which are view fields that control the sort order applied to the data in the response. Sorting is particularly useful when retrieving results in a time series.

Supported views

For the StreamSmart™ product, Insights supports the following views:

The views above, along with the fields they support, are presented in more detail, along with some examples, in the sections below.

Common view fields

Most Insights views for the StreamSmart™ product expose several common fields which can be used to add detail and context to your Insights responses. Use the following list of common fields:

The Insights REST API is secured using OAuth 2.0 tokens. As such, you are required to submit a POST request to the login endpoint in order to receive an OAuth2 token, as shown below:

curl -X POST \
  https://insights.ssimwave.com/api/4.0/login \
  -header 'Accept: application/application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<clientID>&client_secret=<clientSecret>'

where <clientID> and <clientSecret> are the values you received when setting up your Insights account.

The alphanumeric OAuth2 token will be included in the payload of the response and labelled as access_token:

{
    "access_token": "4RtxmBmskRFfcnvJXjVdXHZbWDbwCdrHHJH8qJNp",
    "token_type": "Bearer",
    "expires_in": 3600
}

The OAuth2 token must be included as a Bearer token in the Authorization header for all requests sent to an Insights REST API endpoint, as shown below:

curl -X POST \
  https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false \
  -H 'Authorization: Bearer 4RtxmBmskRFfcnvJXjVdXHZbWDbwCdrHHJH8qJNp'
  .
  .
  .

Each OAuth2 token expires after 1 hour, regardless of activity. To obtain a new token, you will need to resubmit the POST request to the login endpoint.

A SSIMPLUS® Asset Score is a summary metric that provides a single value for an entire asset that is more accurate than peforming the mathematical average of the underlying frame scores. StreamSmart™ provides Asset Scores for the following metrics:

• SSIMPLUS® Viewer Score (SVS),
• SSIMPLUS® Encoder Performance Score (EPS) and
• SSIMPLUS® Banding Score (SBS)

Asset SVS, EPS, and SBS are exposed as fields on the vod_video_asset_score view, which is a subview of the vod_analysis_results view and can be fetched from Insights as shown below:

curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer NPp7SWngHvMXYJsyPRNQXc6nKGgZ4Dx7FFWsb9S5' \
--data '{
  "model": "vod_monitor",
  "view": "vod_analysis_results",
  "fields": [
    "vod_analysis_results.test_id",
    "device.device_name",
    "vod_analysis_results.reference_video",
    "vod_analysis_results.test_video",
    "vod_video_asset_score.asset_ssimplus_viewer_score",
    "vod_video_asset_score.asset_encoder_performance_score",
    "vod_video_asset_score.asset_banding",
    "vod_video_asset_score.asset_content_complexity"
  ],
  "filters": {
    "vod_analysis_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce"
  },
  "sorts": [
    "vod_analysis_results.test_id"
  ]
}'

The JSON response payload is as follows:

[
  {
    "vod_analysis_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce",
    "vod_analysis_results.test_id": "Source",
    "device.device_name": "OLED65C9PUA",
    "vod_analysis_results.reference_video": null,
    "vod_analysis_results.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_video_asset_score.asset_ssimplus_viewer_score": 95.375,
    "vod_video_asset_score.asset_encoder_performance_score": null,
    "vod_video_asset_score.asset_banding": 0,
    "vod_analysis_results.asset_content_complexity": 37.4
  },
  {
    "vod_analysis_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce",
    "vod_analysis_results.test_id": "Anchor 1",
    "device.device_name": "OLED65C9PUA",
    "vod_analysis_results.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_analysis_results.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
    "vod_video_asset_score.asset_ssimplus_viewer_score": 83.416,
    "vod_video_asset_score.asset_encoder_performance_score": 88.02,
    "vod_video_asset_score.asset_banding": 18.2,
    "vod_analysis_results.asset_content_complexity": null
  },
  {
    "vod_analysis_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce",
    "vod_analysis_results.test_id": "Result 1",
    "device.device_name": "OLED65C9PUA",
    "vod_analysis_results.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_analysis_results.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_41.mp4",
    "vod_video_asset_score.asset_ssimplus_viewer_score": 60.048,
    "vod_video_asset_score.asset_encoder_performance_score": 60.057,
    "vod_video_asset_score.asset_banding": 42.6,
    "vod_analysis_results.asset_content_complexity": null
  }
]

We can make the following conclusions regarding the values above:

• The reference asset (dog_running.mp4) is a reasonably high quality asset as its Asset SVS score of 95 and Asset SBS of 0 places it in the excellent category where impairments, including color banding, are imperceptable for the typical viewer.
• The 1-1 subject/test asset (dog_running_1080_h264_qp_31.mp4) qualifies as an excellent encode as its Asset SVS is above 80 and, although it has some banding, its Asset SBS of 18.2 falls into the imperceptible category. The Asset EPS of 88 indicates that the encoder did an excellent job of maintaining the reference quality.
• The 1-2 subject/test asset (dog_running_1080_h264_qp_41.mp4) qualifies as a fair encode as its Asset SVS is only 60 and its Asset SBS of 42 means that the color banding is creeping into the slight annoying category. The Asset EPS score of 60 indicates that the encoder did not do a very good job of maintaining the reference quality, especially considering that the content complexity score of the reference (Asset CCS) is reasonably low at only 37.
• The example above is purposefully terse in order to illustrate the fetching of Asset Scores. The vod_analysis_results has many additional fields that may of interest to include in your response. Please refer to Supported analysis results fields for details.

When you’re interested in a more granular treatment of the SSIMPLUS® scores for a given asset, you’ll want to use the measurement period fields provided on the vod_analysis_results view in order to build a time series view of your asset’s scores.

Using the Stream™ On-Demand REST API, let’s submit a no-reference analysis for an HDR asset that configures the SSIMPLUS® Analyzer to capture color information and statistics, in addition to banding, as shown below:

curl --location 'https://localhost/api/v1/analyses' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "content": {
    "title": "HDR NR Test"
  },
  "subjectAssets": [
    {
      "name": "samsung-demo-reel-version-a.mp4",
      "path": "content-similarity-assets/UHD-HDR-MP4-samsung-demo-reel",
      "storageLocation": {
        "type": "PVC",
        "name": "on-201"
      },
      "hdr": true
    }
  ],
  "analyzerConfig": {
    "enableBandingDetection": true,
    "enableColorInformation": true,
    "enableColorStatsCollection": true,
    "viewingEnvironments": [
      {
        "device": {
          "name": "oled65c9pua"
        },
        "viewerType": "TYPICAL"
      }
    ]
  }
}'

Next, let’s fetch our analysis results from Insights, including color gamut and luminance data, in a time series view using a measurement period of 2s:

curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 9tVkH455J5Z8X5jGVDBpRbSwBJz5f7vcHTftRv7K' \
--data '{
  "model": "vod_monitor",
  "view": "vod_analysis_results",
  "fields": [
    "vod_analysis_results.analysis_uuid",
    "vod_analysis_results.test_video_time_2s",
    "vod_analysis_results.test_video",
    "vod_analysis_results.ssimplus_viewer_score",
    "vod_analysis_results.max_ssimplus_viewer_score",
    "vod_analysis_results.min_ssimplus_viewer_score",
    "vod_analysis_results.avg_banding",
    "vod_analysis_results.max_banding",
    "vod_analysis_results.min_banding",
    "vod_analysis_results.color_primaries",
    "vod_analysis_results.color_space",
    "vod_analysis_results.color_transfer_characteristics",
    "vod_analysis_results.max_content_light_level",
    "vod_analysis_results.max_frame_average_light_level",
    "vod_analysis_results.color_gamut",
    "vod_analysis_results.color_gamut_rec709",
    "vod_analysis_results.color_gamut_p3d65",
    "vod_analysis_results.color_gamut_rec2020",
    "vod_analysis_results.color_gamut_unknown",
    "vod_analysis_results.max_pixel_luminance",
    "vod_analysis_results.min_pixel_luminance",
    "vod_analysis_results.avg_frame_luminance",
    "vod_analysis_results.max_frame_luminance",
    "vod_analysis_results.min_frame_luminance",
    "vod_analysis_results.frame_count"
  ],
  "filters": {
    "vod_analysis_results.analysis_uuid": "b9b437a7-f966-4e2b-8bb4-02d9cd1aa2a8"
  },
  "sorts": [
    "vod_analysis_results.test_video_time_2s"
  ]
}'

The abbreviated JSON response payload is as follows:

[
  {
    "vod_analysis_results.analysis_uuid": "b9b437a7-f966-4e2b-8bb4-02d9cd1aa2a8",
    "vod_analysis_results.test_video_time_2s": "00:00:02",
    "vod_analysis_results.test_video": "file:///mnt/on-201/content-similarity-assets/UHD-HDR-MP4-samsung-demo-reel/samsung-demo-reel-version-a.mp4",
    "vod_analysis_results.color_primaries": "bt2020",
    "vod_analysis_results.color_space": "bt2020nc",
    "vod_analysis_results.color_transfer_characteristics": "smpte2084",
    "vod_analysis_results.max_content_light_level": 1000,
    "vod_analysis_results.max_frame_average_light_level": 1000,
    "vod_analysis_results.ssimplus_viewer_score": 97.9375,
    "vod_analysis_results.max_ssimplus_viewer_score": 98,
    "vod_analysis_results.min_ssimplus_viewer_score": 97.875,
    "vod_analysis_results.avg_banding": 53.6875,
    "vod_analysis_results.max_banding": 56,
    "vod_analysis_results.min_banding": 50,
    "vod_analysis_results.color_gamut": "P3D65",
    "vod_analysis_results.color_gamut_rec709": 0,
    "vod_analysis_results.color_gamut_p3d65": 48,
    "vod_analysis_results.color_gamut_rec2020": 0,
    "vod_analysis_results.color_gamut_unknown": 0,
    "vod_analysis_results.max_pixel_luminance": 10000,
    "vod_analysis_results.min_pixel_luminance": 0,
    "vod_analysis_results.avg_frame_luminance": 281.4792,
    "vod_analysis_results.max_frame_luminance": 283,
    "vod_analysis_results.min_frame_luminance": 280,
    "vod_analysis_results.frame_count": 48
  },
  {
    "vod_analysis_results.analysis_uuid": "b9b437a7-f966-4e2b-8bb4-02d9cd1aa2a8",
    "vod_analysis_results.test_video_time_2s": "00:00:04",
    "vod_analysis_results.test_video": "file:///mnt/on-201/content-similarity-assets/UHD-HDR-MP4-samsung-demo-reel/samsung-demo-reel-version-a.mp4",
    "vod_analysis_results.color_primaries": "bt2020",
    "vod_analysis_results.color_space": "bt2020nc",
    "vod_analysis_results.color_transfer_characteristics": "smpte2084",
    "vod_analysis_results.max_content_light_level": 1000,
    "vod_analysis_results.max_frame_average_light_level": 1000,
    "vod_analysis_results.ssimplus_viewer_score": 97.9165,
    "vod_analysis_results.max_ssimplus_viewer_score": 98,
    "vod_analysis_results.min_ssimplus_viewer_score": 97.833,
    "vod_analysis_results.avg_banding": 55.7083,
    "vod_analysis_results.max_banding": 61,
    "vod_analysis_results.min_banding": 52,
    "vod_analysis_results.color_gamut": "P3D65",
    "vod_analysis_results.color_gamut_rec709": 0,
    "vod_analysis_results.color_gamut_p3d65": 48,
    "vod_analysis_results.color_gamut_rec2020": 0,
    "vod_analysis_results.color_gamut_unknown": 0,
    "vod_analysis_results.max_pixel_luminance": 9043,
    "vod_analysis_results.min_pixel_luminance": 0,
    "vod_analysis_results.avg_frame_luminance": 280.0417,
    "vod_analysis_results.max_frame_luminance": 281,
    "vod_analysis_results.min_frame_luminance": 279,
    "vod_analysis_results.frame_count": 48
  },
  {
    "vod_analysis_results.analysis_uuid": "b9b437a7-f966-4e2b-8bb4-02d9cd1aa2a8",
    "vod_analysis_results.test_video_time_2s": "00:00:06",
    "vod_analysis_results.test_video": "file:///mnt/on-201/content-similarity-assets/UHD-HDR-MP4-samsung-demo-reel/samsung-demo-reel-version-a.mp4",
    "vod_analysis_results.color_primaries": "bt2020",
    "vod_analysis_results.color_space": "bt2020nc",
    "vod_analysis_results.color_transfer_characteristics": "smpte2084",
    "vod_analysis_results.max_content_light_level": 1000,
    "vod_analysis_results.max_frame_average_light_level": 1000,
    "vod_analysis_results.ssimplus_viewer_score": 96.5925,
    "vod_analysis_results.max_ssimplus_viewer_score": 98,
    "vod_analysis_results.min_ssimplus_viewer_score": 95.185,
    "vod_analysis_results.avg_banding": 45.3542,
    "vod_analysis_results.max_banding": 60,
    "vod_analysis_results.min_banding": 28,
    "vod_analysis_results.color_gamut": "P3D65",
    "vod_analysis_results.color_gamut_rec709": 0,
    "vod_analysis_results.color_gamut_p3d65": 48,
    "vod_analysis_results.color_gamut_rec2020": 0,
    "vod_analysis_results.color_gamut_unknown": 0,
    "vod_analysis_results.max_pixel_luminance": 8835,
    "vod_analysis_results.min_pixel_luminance": 0,
    "vod_analysis_results.avg_frame_luminance": 236.8125,
    "vod_analysis_results.max_frame_luminance": 282,
    "vod_analysis_results.min_frame_luminance": 184,
    "vod_analysis_results.frame_count": 48
  },
  .
  .
  .
]

Notice in the results above:

• We have one result in the response for each 2s measurement period (i.e. 2s, 4s, 6s etc).
• Insights provides the mathematical average, minimum and maximum for the various metrics and measurements requested. These values are calculated using the values of all the underlying frames that make up the measurement period (i.e. a frame count of 48 frames in the example above).
• We choose to sort the results based off the chosen measurement period (i.e. vod_analysis_results.test_video_time_2s)

The vod_analysis_results view exposes fields and subviews (e.g. vod_video_asset_score) to capture the various SSIMPLUS® measurements and metrics for an analysis over an entire asset (i.e. Asset Scores) and/or various measurement periods (time series). The following subsections lists the various fields of interest on the vod_analysis_results view (and its subviews) that can be used in the body of any request sent to the Insights REST API.

Metrics and measurements

The Insights vod_analysis_results view exposes the following list of fields:

And the following filter-only fields:

Measurement periods

Insights supports the following measurement period fields:

For some use cases, it may prove desirable to fetch the requested SSIMPLUS® measurements and metrics for each frame in your analyzed assets. Frame level data is provided using the vod_analysis_frame_results view.

Using the Stream™ On-Demand REST API, we can submit a full-reference analysis for HDR assets that configures the SSIMPLUS® Analyzer to capture color information and statistics, in addition to SBS (color banding), EPS (encoder performance) and CVD (color volume differncing), as shown below:

curl --location 'https://localhost/api/v1/analyses' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "content": {
    "title": "HDR FR Demo"
  },
  "referenceAssets": [
    {
      "hdr": true,
      "name": "demo1_hdr10_ref.mp4",
      "storageLocation": {
        "type": "PVC",
        "name": "on-201"
      },
      "path": "demo/encode_validation/HDR_demo"
    }
  ],
  "subjectAssets": [
    {
      "hdr": true,
      "name": "demo1_hdr10_test_cbr_1920x1080_5400kbps.mp4",
      "storageLocation": {
        "type": "PVC",
        "name": "on-201"
      },
      "path": "demo/encode_validation/HDR_demo"
    }
  ],
  "analyzerConfig": {
    "enableBandingDetection": true,
    "enableColorInformation": true,
    "enableColorStatsCollection": true,
    "enableColorVolumeDifference": true,
    "viewingEnvironments": [
      {
        "device": {
          "name": "oled65c9pua"
        },
        "viewerType": "TYPICAL"
      },
      {
        "device": {
          "name": "ssimpluscore"
        },
        "viewerType": "TYPICAL"
      },
      {
        "device": {
          "name": "xl2420t"
        },
        "viewerType": "TYPICAL"
      }
    ]
  }
}'

The following Insights request fetches the SVS, EPS, SBS and CVD scores along with the color gamut and pixel and frame luminance values for every frame:

curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 29RJCp5vn6WVt68rj4XMqh3dmyHcFbBxzD2WsM9J' \
--data '{
  "model": "vod_monitor",
  "view": "vod_analysis_frame_results",
  "fields": [
    "vod_analysis_frame_results.analysis_uuid",
    "vod_analysis_frame_results.reference_video",
    "vod_analysis_frame_results.test_video",
    "vod_analysis_frame_results.test_id",
    "vod_analysis_frame_results.reference_video_time_1frame",
    "vod_analysis_frame_results.test_video_time_1frame",
    "vod_analysis_frame_results.avg_encoder_performance_score",
    "vod_analysis_frame_results.avg_ssimplus_viewer_score",
    "vod_analysis_frame_results.avg_banding",
    "vod_analysis_frame_results.color_primaries",
    "vod_analysis_frame_results.color_space",
    "vod_analysis_frame_results.color_transfer_characteristics",
    "vod_analysis_frame_results.color_gamut",
    "vod_analysis_frame_results.avg_color_volume_difference",
    "vod_analysis_frame_results.avg_pixel_luminance",
    "vod_analysis_frame_results.min_pixel_luminance",
    "vod_analysis_frame_results.min_pixel_luminance_x",
    "vod_analysis_frame_results.min_pixel_luminance_y",
    "vod_analysis_frame_results.max_pixel_luminance",
    "vod_analysis_frame_results.max_pixel_luminance_x",
    "vod_analysis_frame_results.max_pixel_luminance_y",
    "vod_analysis_frame_results.avg_frame_luminance",
    "device.device_name"
  ],
  "filters": {
    "vod_analysis_frame_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce"
  },
  "sorts": [
    "vod_analysis_frame_results.reference_video_time_1frame",
    "vod_analysis_frame_results.test_id"
  ]
}'

The snippet below represents a small sampling of the response output:

[
  .
  .
  {
    "vod_analysis_frame_results.analysis_uuid": "0e37bc9b-34ca-45ea-aaf5-da713fada956",
    "vod_analysis_frame_results.reference_video": null,
    "vod_analysis_frame_results.test_video": "file:///mnt/on-201/demo/encode_validation/HDR_demo/demo1_hdr10_ref.mp4",
    "vod_analysis_frame_results.test_id": "1",
    "vod_analysis_frame_results.reference_video_time_1frame": "00:00:04:23",
    "vod_analysis_frame_results.test_video_time_1frame": "00:00:04:23",
    "vod_analysis_frame_results.color_primaries": "bt2020",
    "vod_analysis_frame_results.color_space": "bt2020nc",
    "vod_analysis_frame_results.color_transfer_characteristics": "smpte2084",
    "device.device_name": "OLED65C9PUA",
    "vod_analysis_frame_results.avg_encoder_performance_score": null,
    "vod_analysis_frame_results.avg_ssimplus_viewer_score": 100,
    "vod_analysis_frame_results.avg_banding": 50,
    "vod_analysis_frame_results.color_gamut": "P3D65",
    "vod_analysis_frame_results.avg_color_volume_difference": null,
    "vod_analysis_frame_results.min_pixel_luminance": 0,
    "vod_analysis_frame_results.min_pixel_luminance_x": 1170,
    "vod_analysis_frame_results.min_pixel_luminance_y": 0,
    "vod_analysis_frame_results.max_pixel_luminance": 749,
    "vod_analysis_frame_results.max_pixel_luminance_x": 2490,
    "vod_analysis_frame_results.max_pixel_luminance_y": 1028,
    "vod_analysis_frame_results.avg_frame_luminance": 37
  },
  {
    "vod_analysis_frame_results.analysis_uuid": "0e37bc9b-34ca-45ea-aaf5-da713fada956",
    "vod_analysis_frame_results.reference_video": "file:///mnt/on-201/demo/encode_validation/HDR_demo/demo1_hdr10_ref.mp4",
    "vod_analysis_frame_results.test_video": "file:///mnt/on-201/demo/encode_validation/HDR_demo/demo1_hdr10_test_cbr_1920x1080_5400kbps.mp4",
    "vod_analysis_frame_results.test_id": "1-1",
    "vod_analysis_frame_results.reference_video_time_1frame": "00:00:04:23",
    "vod_analysis_frame_results.test_video_time_1frame": "00:00:04:23",
    "vod_analysis_frame_results.color_primaries": "bt2020",
    "vod_analysis_frame_results.color_space": "bt2020nc",
    "vod_analysis_frame_results.color_transfer_characteristics": "smpte2084",
    "device.device_name": "OLED65C9PUA",
    "vod_analysis_frame_results.avg_encoder_performance_score": 92,
    "vod_analysis_frame_results.avg_ssimplus_viewer_score": 89,
    "vod_analysis_frame_results.avg_banding": 23,
    "vod_analysis_frame_results.color_gamut": "P3D65",
    "vod_analysis_frame_results.avg_color_volume_difference": 8.52735,
    "vod_analysis_frame_results.min_pixel_luminance": 0,
    "vod_analysis_frame_results.min_pixel_luminance_x": 1198,
    "vod_analysis_frame_results.min_pixel_luminance_y": 0,
    "vod_analysis_frame_results.max_pixel_luminance": 1237,
    "vod_analysis_frame_results.max_pixel_luminance_x": 300,
    "vod_analysis_frame_results.max_pixel_luminance_y": 674,
    "vod_analysis_frame_results.avg_frame_luminance": 37
  },
  .
  .
]

Please note the following about the Insights request and response above:

• While the vod_analysis_frame_results view exposes fields for the average, minimum and maximum values for most of the SSIMPLUS® measurements and metrics, one need only request the average (e.g. avg_ssimplus_viewer_score) since the granularity of this view is already at the lowest (i.e. frame) level. Requesting the minimum and maximum fields will result in identical values to that of the average.
• Where pixel values are provided, however, average, minimum and maximum will have proper meaning and different results (i.e. see avg/min/max_pixel_luminance above).
• The vod_analysis_frame_results view exposes two fields, reference_video_time_1frame and test_video_time_1frame, to capture the respective time within the reference and subject/test videos. These time fields are of the format HH:MM:SS:FF, where FF is the frame number within the given second and the possible values depend on the framerate of the underlying asset.

As with all other queries submitted to the Insights REST API, you are encouraged to use filters to help reduce the size of your results and focus on specific parts of your data set. Using the query above, we can add a subject/test asset filter (i.e. vod_analysis_frame_results.test_id) and device filter (i.e. device.device_name) to return all the frame scores just for the subject/test asset identified by 1-1 and the OLED65C9PUA device:

curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 29RJCp5vn6WVt68rj4XMqh3dmyHcFbBxzD2WsM9J' \
--data '{
  "model": "vod_monitor",
  "view": "vod_analysis_frame_results",
  "fields": [
    "vod_analysis_frame_results.analysis_uuid",
    "vod_analysis_frame_results.reference_video",
    "vod_analysis_frame_results.test_video",
    "vod_analysis_frame_results.test_id",
    "vod_analysis_frame_results.reference_video_time_1frame",
    "vod_analysis_frame_results.test_video_time_1frame",
    "vod_analysis_frame_results.avg_encoder_performance_score",
    "vod_analysis_frame_results.avg_ssimplus_viewer_score",
    "vod_analysis_frame_results.avg_banding",
    "vod_analysis_frame_results.color_primaries",
    "vod_analysis_frame_results.color_space",
    "vod_analysis_frame_results.color_transfer_characteristics",
    "vod_analysis_frame_results.color_gamut",
    "vod_analysis_frame_results.avg_color_volume_difference",
    "vod_analysis_frame_results.avg_pixel_luminance",
    "vod_analysis_frame_results.min_pixel_luminance",
    "vod_analysis_frame_results.min_pixel_luminance_x",
    "vod_analysis_frame_results.min_pixel_luminance_y",
    "vod_analysis_frame_results.max_pixel_luminance",
    "vod_analysis_frame_results.max_pixel_luminance_x",
    "vod_analysis_frame_results.max_pixel_luminance_y",
    "vod_analysis_frame_results.avg_frame_luminance",
    "device.device_name"
  ],
  "filters": {
    "vod_analysis_frame_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce",
    "vod_analysis_frame_results.test_id": "1-1",
    "device.device_name": "OLED65C9PUA"
  },
  "sorts": [
    "vod_analysis_frame_results.reference_video_time_1frame",
    "vod_analysis_frame_results.test_id"
  ]
}'

Supported view fields

The vod_analysis_frame_results view exposes fields to capture the various SSIMPLUS® measurements and metrics (e.g. SVS, EPS, SBS, CVD, CCM, physical and visual noise, HDR color gamut and luminance) for each frame of the assets included in an analysis. The following section lists the various fields of interest on the vod_analysis_frame_results view that can be used in the body of any request sent to the Insights REST API.

And the following filter-only fields:

Use the vod_status_analysis view and an analysis UUID filter to see a summary or roll-up status of a given analysis, as shown below:

curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 7FYtb3FB39ngTgDXF4WsCXb2NMvR3PRvhJGgypVx' \
--data '{
  "model": "vod_monitor",
  "view": "vod_status_analysis",
  "fields": [
    "vod_status_analysis.analysis_uuid",
    "vod_status_analysis.time",
    "vod_status_analysis.min_time",
    "vod_status_analysis.test_id",
    "vod_status_analysis.test_video",
    "vod_status_analysis.reference_video",
    "vod_status_analysis.stage",
    "vod_status_analysis.percent_done",
    "vod_status_analysis.test_count",
    "vod_quality_checks.count"
  ],
  "filters": {
    "vod_status_analysis.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b"
  }
}'

Consider the following JSON sample response:

[
  {
    "vod_status_analysis.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_analysis.time": "2023-08-30 16:41:00",
    "vod_status_analysis.min_time": "2023-08-30 16:40:14",
    "vod_status_analysis.stage": "Results Ready",
    "vod_status_analysis.percent_done": 100,
    "vod_status_analysis.test_count": 3,
    "vod_quality_checks.count": 4
  }
]

Note in the example response above:

• the test_count value indicates that there are 3 separate NR and/or FR analyses being performed and
• the count value indicates that there were 4 quality check failures found.

To fetch the status for a given analysis and to see the details of all no-reference and/or full-reference analyses being performed, use the vod_status_test view and filter on the analysis UUID, as shown below:

curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer mFs5sKXwcVnCS4FC6kKbdFYqzcQYqVmHCKnKsNk5' \
--data '{
  "model": "vod_monitor",
  "view": "vod_status_test",
  "fields": [
    "vod_status_test.analysis_uuid",
    "vod_status_test.time",
    "vod_status_test.test_id",
    "vod_status_test.test_video",
    "vod_status_test.reference_video",
    "vod_status_test.stage",
    "vod_status_test.percent_done"
  ],
  "filters": {
    "vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b"
  },
  "sorts": [
    "vod_status_test.test_id"
  ]
}'

Assuming that 2e4db929-d00b-493a-98fb-77e321f3219b represents a full-reference analysis, you may see a response like the following if you query for the status immediately after submitting via the Stream™ On-Demand REST API:

[
  {
    "vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_test.time": "2023-08-30 16:40:36",
    "vod_status_test.test_id": "1",
    "vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_test.reference_video": null,
    "vod_status_test.stage": "Analyzing",
    "vod_status_test.percent_done": 33.33
  },
  {
    "vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_test.time": "2023-08-30 16:40:37",
    "vod_status_test.test_id": "1-1",
    "vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
    "vod_status_test.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_test.stage": "Analyzing",
    "vod_status_test.percent_done": 20.12
  },
  {
    "vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_test.time": "2023-08-30 16:40:37",
    "vod_status_test.test_id": "1-2",
    "vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_41.mp4",
    "vod_status_test.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_test.stage": "Aligning",
    "vod_status_test.percent_done": 88.75
  }
]

Notice the following in the response above:

• The NR analysis of 1 (dog_running.mp4) 33% complete.
• The FR analysis of 1-1 (dog_running_1080_h264_qp_31.mp4) has been temporarily aligned with the reference (i.e. Aligning state is finished) and is 20% of the way through its analysis.
• The 1-2 asset (dog_running_1080_h264_qp_41.mp4) is still being temporarily aligned with the reference and, as such, has not yet started its FR analysis.

Repeating the request above some minutes later results in the following response:

[
  {
    "vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_test.time": "2023-08-30 16:40:55",
    "vod_status_test.test_id": "1",
    "vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_test.reference_video": null,
    "vod_status_test.stage": "Results Ready",
    "vod_status_test.percent_done": 100
  },
  {
    "vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_test.time": "2023-08-30 16:41:00",
    "vod_status_test.test_id": "1-1",
    "vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
    "vod_status_test.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_test.stage": "Results Ready",
    "vod_status_test.percent_done": 100
  },
  {
    "vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_test.time": "2023-08-30 16:40:59",
    "vod_status_test.test_id": "1-2",
    "vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_41.mp4",
    "vod_status_test.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_test.stage": "Results Ready",
    "vod_status_test.percent_done": 100
  }
]

In the result above, all analyses are complete and their results are ready to be used.

If you an encounter an error or unexpected behavior with a given analysis, you can choose to fetch a log of all the status messages for the analysis using the vod_status_updates view and filters on the vod_status_updates.analysis_uuid and vod_status_updates.test_id, as shown below:

curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer rjV3dmFFrWfNWKPMmtcRtQdrPtjhYczCBFHPbn5z' \
--data '{
  "model": "vod_monitor",
  "view": "vod_status_updates",
  "fields": [
    "vod_status_updates.analysis_uuid",
    "vod_status_updates.time",
    "vod_status_updates.test_id",
    "vod_status_updates.test_video",
    "vod_status_updates.reference_video",
    "vod_status_updates.stage",
    "vod_status_updates.percent_done",
    "vod_status_updates.details",
    "vod_status_updates.error_details"
  ],
  "filters": {
    "vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_updates.test_id": "Result 1"
  },
  "sorts": [
    "vod_status_updates.test_id",
    "vod_status_updates.time desc"
  ]
}'

An abbreviated sample JSON response would be as follows:

[
  {
    "vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_updates.time": "2023-08-30 16:41:01.176000",
    "vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_updates.test_id": "1-1",
    "vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
    "vod_status_updates.stage": "Analyzing",
    "vod_status_updates.details": "{\"result\":\"pass\",\"total\":492}",
    "vod_status_updates.error_details": null,
    "vod_status_updates.percent_done": 1
  },
  {
    "vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_updates.time": "2023-08-30 16:41:01.122000",
    "vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_updates.test_id": "1-1",
    "vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
    "vod_status_updates.stage": "Analyzing",
    "vod_status_updates.details": "{\"progress\":{\"current\":492,\"total\":492}}",
    "vod_status_updates.error_details": null,
    "vod_status_updates.percent_done": 1
  },
  {
    "vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_updates.time": "2023-08-30 16:41:00.937000",
    "vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_updates.test_id": "1-1",
    "vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
    "vod_status_updates.stage": "Analyzing",
    "vod_status_updates.details": null,
    "vod_status_updates.error_details": null,
    "vod_status_updates.percent_done": 1
  },
  {
    "vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_updates.time": "2023-08-30 16:41:00.937000",
    "vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_updates.test_id": "1-1",
    "vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
    "vod_status_updates.stage": "Results Ready",
    "vod_status_updates.details": null,
    "vod_status_updates.error_details": null,
    "vod_status_updates.percent_done": 1
  },
  {
    "vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_updates.time": "2023-08-30 16:41:00.615000",
    "vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_updates.test_id": "1-1",
    "vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
    "vod_status_updates.stage": "Analyzing",
    "vod_status_updates.details": "{\"progress\":{\"current\":485,\"total\":492}}",
    "vod_status_updates.error_details": null,
    "vod_status_updates.percent_done": 0.9858
  },
  {
    "vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
    "vod_status_updates.time": "2023-08-30 16:40:59.613000",
    "vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
    "vod_status_updates.test_id": "1-1",
    "vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
    "vod_status_updates.stage": "Analyzing",
    "vod_status_updates.details": "{\"progress\":{\"current\":466,\"total\":492}}",
    "vod_status_updates.error_details": null,
    "vod_status_updates.percent_done": 0.9472
  },
  .
  .
  .
]

If the SSIMPLUS® Analyzer encounters an error while processing an asset, it will report the content of the error in the vod_status_updates.error_details field for inspection. Many errors will contain sufficient information such that a remedy can be readily applied and the analysis rerun with minimal effort (i.e. fixing an invalid asset path or filename). Some errors are more serious and may require input from a video analyst and/or manipulation of the assets themselves. A failure to achieve automatic alignment between the reference and subject asset, for example, will result in an alignment error and manual actions must be taken to apply fixes before resubmitting the analysis. If an error does occur for which the cause or solution is unknown, please post a trouble ticket using the SSIMWAVE Help Center.

The following table lists the various fields of interest on the vod_status_analysis, vod_status_test and vod_status_updates views for extracting data on the status of an analysis. You can use these fields in the body of any request sent to the Insights REST API.

Installation and configuration

Both the IMAX Stream™ On-Demand Platform and Insights support being used in a headless/programmatic manner via the Stream™ On-Demand REST API and Insights REST API, respectively. To familiarize yourself with the API experience, SSIMWAVE offers Postman collection and environment files which can be imported and configured into the aforementioned tool by following the instructions below:

1. Download, install and launch the Postman app.
   
   

2. Under Settings->General make sure you set the Max response size in MB to 0 so no responses from the Insight’s REST API are truncated. This is especially useful if you plan to fetch results at per-frame granularity.
   
   

3. Under Settings->General make sure that the SSL certificate verifiation is set to Off.
   
   

4. (Recommended) Create a new workspace within Postman for isolation and ease of organization.

   Tip

   Use a workspace name that indicates the product and version, such as StreamSmart™ vX.YY

5. Import the Stream™ Postman collection and environment files (File->Import).
   
   

6. From the Collections view (left sidebar), you should see a folder called IMAX Stream™ with a set of subfolders and requests therein.
   
   

7. Make sure Postman is using the IMAX Stream™ environment you imported above by selecting it from the Environment drop-down near the top right corner of the Postman GUI.
   
   

8. Edit the IMAX Stream™ environment by clicking on the eyeball button (Environment Quick Look) to the right of the drop-down and then the Edit link in the top right corner of the popup. Postman should launch a new tab showing an editable table of the environment variables.

   Note

   Modern versions of Postman also have an Environments button/view that can be selected from the sidebar on the left side of the UI.

9. In the table presented, modify the CURRENT VALUE column for the following key/value pairs:

   VARIABLE	CURRENT VALUE
   stream_host	<stream_host>
   insights_client_id	<insights_client_id>
   insights_client_secret	<insights_client_secret>

   where

   • <stream_host> is the fully-qualified domain name (FQDN) or IP address of your IMAX Stream deployment and
   • <insights_client_id> and <insights_client_secret> are the values sent to you by your SSIMWAVE representative after completing the Getting Started section of the Insights Data Platform.
     
     

   Depending on the details of your deployment, the value for <stream_host> will differ:

   • For production VPC bare-metal/other deployments, <stream_host> will be the FQDN of the Ingress you installed in step 5
   • For production VPC/EKS deployments, <stream_host> will be the hostname you selected when executing the Installation Prerequisites
   • For fixed scale deployments using an AMI deployed to an EC2 instance, <stream_host> will be the public DNS entry of your EC2 instance
   • For fixed scale deployments on bare metal using a virtual machine (i.e. OVA/QEMU), <stream_host> will be the IP address/FQDN of your virtual machine instance (Don’t forget to include the port if you used NAT.)

Submitting requests and viewing responses

At this point, you should be able to start submitting requests in the StreamSmart™ collection. In general, you will want to repeat the following process to submit new optimizations and view their results via the REST APIs:

1. Submit a new optimization by choosing the New optimization (FFmpeg) request example (listed under the StreamSmart™->Submit New Optimization folder).
   
   

2. Select the Body tab from the main view and edit the contents of your POST request to suit your needs (see the Stream™ On-Demand REST API and/or Insights REST API above for examples and details).

   For example, the following optimization request modifications indicate that:

   • our source asset lives in an S3 bucket
   • we want to optimize the FFmpeg encode specified by the provided FFmpeg command
   • the output should be written to a different S3 bucket

   {
       "title": "My First Optimization",
       "config": {
           "encodes": [{
               "commands": ["ffmpeg -r 24 -i {INPUT_LOCATION} -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range mpeg -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=50:keyint_min=50:scenecut=0:stitchable=1\" -profile:v high -level:v 4.1 -b:v 5000k -maxrate 6250k -bufsize 10000k -r 24 -vf scale=1920x1080 -an {OUTPUT_LOCATION}"],
               "outputLocation": {
                   "path": "tests/test1.ts",
                   "storageLocation": {
                       "type": "S3",
                       "name": "encoding-test-assets"
                   }
               }
           }],
           "inputLocation": {
               "key": "tests/test1-result.mov",
               "storageLocation": {
                   "type": "S3",
                   "name": "encoding-test-outputs"
               }
           }
       }
   }
   

   
   

3. Click the Send button.
   
   

4. Your response will be displayed in the Response container of the Postman GUI (to the right or bottom of the UI).
   
   

5. While the optimization is running, run the Analysis Status->Status summary query in the Insights REST API->Optimization Status folder to see the status and progress.

   Important

   The Postman collection and environment work together to remember the UUID of the last successfully submitted optimization. As such, any request run from the Stream™ On-Demand REST API folder will have its resulting analysis UUID value stored in Postman and automatically fed into any subsequently executed query from the Insights REST API folder, to save you the bother of repeatedly copying and pasting the UUID. Additionally, all queries in the Insights REST API folder will automatically fetch and submit the OAuth tokens needed for secure interaction with the Insights REST API. If you wish to fetch results for a prior/different analysis, simply edit the environment paste the UUID of the desired analysis into the current value for last_analysis_uuid.

6. (Optional) Select the Body tab from the main view and alter the details of your POST request to match your use case (see Insights REST API for examples and details).

   Note

   Many of the requests under the Insights REST API folder do not require editing in order to function unless a specific filter and/or sorting field/order is desired.

7. Click the Send button.
   
   

8. Your responses will be displayed in the Response container of the Postman GUI (to the right or bottom of the UI). Note: Postman also supports saving/exporting results to a file.

StreamSmart™ uses the following metrics to measure and optimize the quality of encoded video:

• no-reference SSIMPLUS® Viewer Score (NR SVS),
• full-reference SSIMPLUS® Viewer Score (FR SVS),
• SSIMPLUS® Encoder Performance Score (EPS),
• SSIMPLUS® Banding Score (SBS),

No-reference SSIMPLUS® Viewer Score (NR SVS)

The no-reference SSIMPLUS® Viewer Score (also known as Source SSIMPLUS® VIewer Score” or “NR SVS”, ) is a metric that assesses the quality of a source file or stream in a no-reference (NR) manner. This means that it does not require any additional information or reference material in order to evaluate the quality of the video content.

The NR SVS metric is highly accurate, with a strong correlation to both the SSIMPLUS reference-based score and the mean opinion score (MOS), and it uses deep neural networks (DNN) to make its evaluations. It is also computationally efficient, making it suitable for use at any stage of the content processing and delivery chain. The NR SVS metric supports all commonly used codecs, including ProRes, J2K, AVC, HEVC, MPEG2, and VP9, as well as all commonly used content attributes, including HDR content.

Full-reference SSIMPLUS® Viewer Score (FR SVS)

Sometimes referred to as “FR SVS” or “SSIMPLUS® Output Viewer Score”, it assesses the perceptual quality of an (encoded or processed) output in reference to a degraded (or pristine) source.

The quality of the output (FR SVS) is determined by both the quality of the source (NR SVS) and the performance of the encoder (EPS). If the encoder is working well but the source material is poor, the output quality will also be poor. This is because encoding always results in some loss of information. Thus, the output quality is a combination of the source quality, the full-reference quality EPS, and the psychovisual effects included in the model.

The metric supports all impairments, content attributes, and content types, as well as cross-resolution and cross-frame rate analysis. SSIMWAVE is currently developing supporting cross-dynamic range analysis and tone-mapped quality assessment. SSIMPLUS® correlates linearly with perceived quality and covers the full quality range.

The score ranges from 0 to 100, where 0=totally unwatchable and 100=pristine, without visual impairments).

The metric supports all commonly used codecs for source degradations, including ProRes, J2K, AVC, HEVC, MPEG2, and VP9, and it is display device and viewing conditions adaptive.

SSIMPLUS® Encoder Performance Score (EPS)

SSIMPLUS® Encoder Performance Score assesses the performance of an encoder or transcoder by comparing its output with the source. The metric assumes that the source is pristine or nearly pristine, and focuses solely on measuring the degradation introduced by encoding impairments. EPS supports all impairments, content attributes, content types, cross-resolution, and cross-frame rate analysis. We are currently developing support for cross-dynamic range analysis. The metric correlates linearly with perceived quality and covers the full quality range. It also automatically aligns a source with output across resolutions and frame rates. It computes the quality and saliency maps to normalize across all content types. EPS is adaptive to device display and viewing conditions.

Reference/Source	Output

The SSIMPLUS® quality map is generated as part of the SSIMPLUS® Viewer Score computation:

Encoding Examples

Example 1
The source video is high quality, and the encoder or transcoder is performing well.

Example 2
The source video is high quality, but the encoder or transcoder is performing poorly.

Example 3
The source video is poor quality, but the encoder or transcoder is performing well.

Example 4
The source video is poor quality, and the encoder or transcoder is performing poorly.

SSIMPLUS® Banding Score (SBS)

A SSIMPLUS® Banding Score (SBS) is a measurement of the amount of color banding that is present within the asset. Banding, otherwise known as color contouring, is a common artifact of the video compression process and due to the quantization introduced by the video codec. It is most obvious in areas where the content calls for the rendering of smooth gradient regions, such as the sky, water or ground. In these regions, pixel values that are meant to be represented uniquely so as to provide a gentle transition from one shade or color to another are, instead, aggregated into a much smaller set of values creating discrete bands of colors.
The SSIMPLUS® algorithm analyzes each frame of your asset for the presence of banding and records a score indicating the severity of the banding, according to the following scale:

• [ 0- 20] Imperceptible
• [21- 40] Perceptible but not annoying
• [41- 60] Slightly annoying
• [61- 80] Annoying
• [81-100] Very annoying

The following frame is an example of an SBS of 0, meaning that there is no discernible banding present:

This next frame is example of an SBS of 68, which would qualify as annoying. Notice the discrete bands of colors both in the sky and the asphalt track.

In addition to extracting scores based on measurement periods, Insights provides Asset Scores which employ additional intelligence beyond simple mathematical averages of individual frames scores or measurement periods to arrive at a single score for an entire asset.

A SSIMPLUS® Asset Score is a summary metric that assesses the overall experience of the viewer after watching a full asset or program or just a part of an asset or program. It is designed to accurately model the memory behavior of the human visual system and to take into account the response of the human visual system to variations in the viewer experience. For example, in typical scenarios, video quality changes significantly over time due to a number of reasons. Viewers’ opinion of video quality changes relies heavily on the amount, duration, and direction of such a change. SSIMPLUS® uses the Expectation Confirmation Theory to model the asymmetric behavior of the Human Visual System.

SSIMPLUS® VOD Monitor provides both the average and asset scores for the metrics:

• SSIMPLUS® Viewer Score (SVS),
• SSIMPLUS® Encoder Performance Score (EPS),
• SSIMPLUS® Banding Score (SBS)

It is generally recommended to use the Asset Score rather than the average score for content lengths that are longer than one minute in duration.

The Asset SVS, for example, provides a measurement that can be used to judge the overall quality of the entire asset, as perceived by the human visual system, taking into account the lingering effect of poor quality segments. The Asset SVS is particularly useful when your goal is to perform source selection on a population of assets by first removing all those with unacceptably low overall quality. Similarly, the Asset Encoder Performance Score (EPS) can provide a single judgement of the encoder’s performance.

The following scale provides the guide for how to interpret SSIMPLUS® (Asset) SVS and (Asset) EPS scores:

• Excellent = Impairments are imperceptible
• Good = Impairments are perceptible but not annoying
• Fair = Impairments are slightly annoying
• Poor = Impairments are annoying
• Bad = Impairments are very annoying

An AMI deployment has some madatory costs, as described below:

• EC2 instance

  This is the cost of Amazon EC2 instance that launches the AMI described herein. The cost here varies depending on the EC2 instance type you choose and whether you are using spot instances or have a savings plan with Amazon. For more information and current prices, please refer to Amazon’s EC2 On-Demaind Instance Pricing.
  
  

• StreamSmart™ minute usage fees

  These fees are the charges per minute of output video analysis charged by SSIMWAVE. For those that deploy the product through AWS Marketplace, there is pricing information available on the site. SSIMWAVE does support private offerings via AWS Marketplace and access to the AMI outside of AWS Marketplace. Please contact your SSIMWAVE represenative for details.
  
  

The following steps are prerequisites for a successful deployment:

1. Provide your SSIMWAVE representative with the AWS account number and region that you will be using to launch the StreamSmart™ AMI.
   SSIMWAVE needs your account number and region in order to share the AMI with the appropriate account. Your SSIMWAVE representative will let you know once this has been done.

   Important

   You are required to deploy your EC2 instance in the same region as the S3 bucket(s) holding your video assets. This restriction has the further advantage of avoiding any AWS cross-region data transfer costs.

   Note

   This step can be skipped if purchasing through AWS Marketplace.

2. Your AWS user account has permission to:

   • create/launch EC2 instances,
   • create security groups and
   • modify network ACLs on a VPC.
     
     

3. Your video assets are stored in Amazon S3.
   
   

4. Your AWS user account allows for the creation of EC2 instances with the following minimum list of hardware resources:

   1. 192GiB memory
   2. 96 vCPU
   3. 2.2TB of SSD disk space

   
   The minimum requirements above would dictate using a c5.24xlarge or c5a.24xlarge instance type with a 2.2TB attached EBS volume (General Purpose SSD - gp3).
   

   Note

   Your EC2 instance can be configured to use a spot instance with a persistent request, to save on costs. Note that in-progress analyses will need to be resubmitted if the backing spot instance is destroyed and, as a result, you may see partially complete data for those interrupted jobs within Insights.

5. The network ACL associated with your VPC and the security group associated with your EC2 instance must allow outbound internet access on port 443 to the following hosts:

   • ingest-gateway.us-east.insights.ssimwave.com
   • insights.ssimwave.com
     
     

6. You’ve created an account to access your results within SSIMWAVE’s Insights data platform.
   
   

7. You’ve received a StreamSmart™ feature license from your SSIMWAVE representative containing values for the following, according to your purchase/trial agreement:

   • Alphanumeric license verification key
   • Audio loudness measurements
   • Banding detection scoring
   • Frame and map (banding, quality, color volume difference) generation
   • Color gamut and stats generation
   • Color volume difference map generation
   • Content complexity scoring
   • Expiration date (the day on which your license expires)
   • Frame level scoring
   • HDR10 & Dolby Vision support
   • Video, audio and quality check options
   • Insights data streaming credentials
   • Insights REST API (system-level) credentials
   • Insights customer organization and site names

The following steps and examples will use the AWS Web Console. Please contact your SSIMWAVE representative if you have any questions.

1. Login to your AWS account using the AWS Web Console.
   
   

2. From the AWS UI console, choose Services -> Compute -> EC2.
   
   

3. Create a new Security Group (Network & Security -> Security Groups) with the following inbound and outbound rules:

   Inbound Rules
   

   Type	Protocol	Port range	Source	Description
   SSH	TCP	22	<customer_ip_range>	SSH access for deployment/troubleshooting
   HTTPS	TCP	443	<customer_ip_range>	HTTPS access for StreamSmart™

   where <customer_ip_range> is the public IP address for the single machine in your company’s network (i.e. #.#.#.#/32) or range of machines in your subnet (i.e. #.#.#.#/24), depending on who will need access to the StreamSmart™ system. If your company uses a single external IP address/range for all outbound Internet access (very common), you may find it convenient to specify this IP address/range here, knowing that this should cover all users on your local network.
   
   

   All users of StreamSmart™ need HTTPS access to the instance but only a single individual/administrator should need SSH access (i.e. SSH access is used only for deploying and troubleshooting). 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 above from the security group (and optionally from the NACL associated with the VPN) after deployment and add it back only when you have additional deployment or troubleshooting activities to perform.
   
   

   Outbound Rules
   

   Type	Protocol	Port range	Destination	Description
   HTTPS	TCP	443	All (0.0.0.0/0)	SSIMWAVE Insights and SSIMWAVE Insights REST API
   HTTPS	TCP	443	<region_prefix_list>	S3 prefix list (for accessing your video assets)

   where <region_prefix_list> is the AWS-managed prefix list for accessing S3 buckets in your region.
   You can look up the S3 prefix list for your region by navigating to Services -> Network & Content Delivery -> VPC -> Managed Prefix Lists.
   The prefix list for us-east-1, for example, is pl-63a5400a.

   Note that the first rule allows outbound traffic on port 443 to any IP address, even though it is only needed to ingest-gateway.us-east.insights.ssimwave.com and insights.ssimwave.com. The rule is structured in this fashion because, at this time, the IP addresses that resolves insights.ssimwave.com is not fixed. This rule may change to be more restrictive in future releases.

   Important

   You will need to ensure that the network access control list (ACL) associated with your target VPC also allows the inbound and outbound rules above.

4. Navigate to the list of available AMIs (Images -> AMIs).
   
   

5. Find the StreamSmart™ AMI under the list of Private Images.

   The AMI will be named according to the following pattern: ssimplus-vod-monitor_<version>_MM-DD-YYYY_HH-MM
   
   

6. Select the AMI and click on the Launch instance from AMI button to load the Launch an instance page.
   
   

7. Name the instance accordingly (i.e. StreamSmart <version>).
   
   

8. Select the EC2 instance type desired.

   The recommended instance type is c5.24xlarge/c5a.24xlarge.
   

   Note

   Your EC2 instance can be configured to use a spot instance with a persistent request, to save on costs. Note that in-progress analyses will need to be resubmitted if the backing spot instance is destroyed and, as a result, you may see partially complete data for those interrupted jobs within Insights.

9. Select/Create a key pair for secure SSH access to the EC2 instance.

   Important

   Make sure to save a copy of the key (.pem file) as the system’s administrator will need this value in order to SSH into the instance for any future deployment/troubleshooting activities.

10. Configure the Network Settings as follows:

    1. Auto-assign public IP -> Enable
    2. Security group -> Select existing security group -> select the Security Group that you created earlier (step 5)
       
       

11. Add a general purpose SSD (gp3) EBS volume.

    This storage volume is used to hold the reference video you are optimizing, the encoded outputs and any frame captures, banding, quality and/or color volume difference maps generated as part of inspecting the results. While the default/minimum size here is 2TB, you should adjust this value such that it is sufficient to store 1.5 times the size of the largest reference video you expect to optimize. As this device will be used for storing potentially proprietary/sensitive content, you should feel free to add at-rest encryption to this volume.
    
    

12. Click the Launch instance button from the Summary panel to the right of the page.
    
    

13. Click on the instance link provided on the completion page or navigate to the list of all your EC2 instances.
    
    

14. Select the EC2 instance that you launched for the StreamSmart™ AMI from the list.
    
    

15. Modify your VOD API Host setting in Insights.

    The VOD API Host value associated with your SSIMWAVE Insights account is used to redirect your browser to fetch frame images/maps when performing an in-depth inspection of a given result. For this functionality to work, you need to configure this value to match the public IPv4 DNS (or IP) value of your EC2 instance.

    Note

    The public IPv4 DNS value for your EC2 instance should be visible from the Details section at the bottom of the screen and should have the following pattern: ec2-<public_ip_address>.compute-#.amazonaws.com. You may also use the public IP address, if you wish.

    1. Login to your Insights Account.
    2. Click on the user icon in the top right corner of the UI and pick Account from the dropdown menu.
    3. Scroll down to the Additional Details section and change your VOD Api Host value to match the public IPv4 DNS (or IP) value of your EC2 instance.
    4. Click Save.
       
       
    Tip

    Your EC2 instance will get a new public IPv4 DNS (and IP) value every time it is (re)started. One option that avoids having to repeat this step on each restart is to use the AWS Elastic IPs service to associate an elastic IP address with your EC2 instance.

    Important

    All users of StreamSmart™ with their own Insights account, will need to make this same adjustment to their VOD API Host setting under their Insights account.

16. Verify that your StreamSmart™ instance is operational.

    To verify the system status, load the following URL: https://<ec2_public_dns>/status into your web browser, where <ec2_public_dns> is the public host name of your EC2 instance.

    The page displayed is a system status page for all the SSIMPLUS® VOD Monitor services. At this point, all services should show as READY except for the following which will be NOT_READY, in addition to the final outcome:

    • FilebeatConfigurationService
    • InsightsClientService
    • InsightsKafkaService
      
      

    The services above are NOT_READY because they directly depend on a valid feature license, which we will upload in the next step.

    Important

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

    Each user of the StreamSmart™ system will need to accept this certificate so please direct everyone to load https://<ec2_public_dns>/status into their browsers once.

    Note

    It takes several minutes for the virtual machine to initialize and load the StreamSmart™ system. During this time, you may not get a response from the https://<ssimplus-vod-monitor>/status URL or you may see 503 (Service Unavailable), 500 (Proxy Error) pages or 404 (Not Found); this is expected. Simply refresh your browser every 30s until you see the correct content.

17. Upload your feature license.

    To finish the system configuration and address the services that are still NOT_READY, you must now apply your feature license. Using your browser, navigate to the Host page in your Insights account, where you will be presented with the information on your current host. Here you will see the following:

    • under Host information, your Insights Status and Insights API Status are both NOT CONNECTED,
    • your License information section will show ERROR and details will say that your are “Unable to connect to the license server” and
    • your System health section will show OFFLINE.
      
      

    Under the License information section, click on Upload license and pick the license file you received from your SSIMWAVE representative. Shortly after successfully loading the license, the Host page should refresh and your license should show as ACTIVE and your system health as ONLINE. If this is the case for you, feel free to jump to the next section Next steps.

    Important

    It may take a minute for all the services to fully recognize the new license. If your system health reports OFFLINE even after uploading your license, click the Test host connection button in the Host information panel once every 10s until your system reports ONILNE. If your system health remains OFFLINE for more than a few minutes, you should expand the section to see the services that are not configured or responding as expected and consult the Troubleshooting section below.

    If you’re interested, you can expand the System health section and click on Show all services to verify that the services that were previously OFFLINE (i.e. NOT_READY) in the step above are now ONLINE (i.e. READY). You can also revisit https://<ec2_public_dns>/status where all services and the final outcome should show as READY.

    Additionally, you can expand the License information section to verify that the details of your feature license match with your expectations.

    Feel free to return to the Host page at any time in the future to both manage your feature license and assess the health of your system and its constituent services.
    
    

18. Provide access to your S3 bucket(s).

    We need to add Kubernetes secrets to your deployment in order to read and write to the S3 buckets holding your video assets. Each S3 bucket requires a Kubernetes secret with field values for the bucket name, key id and access key. You can use the /s3AccessSecret endpoint on the Stream™ On-Demand REST API to create a conformant secret, as shown below:

    curl -kvi -X PUT "https://<ec2_public_dns>/api/v1/s3AccessSecret"  \
     -H "Content-Type: application/json"  \
     -d '{
        "bucketName": "mybucket",
        "clientId": "AKIAIOSFODNN7EXAMPLE",
        "clientSecret": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }'
    

    
    

19. (Optional) Configure access to your AWS Elemental MediaConvert (EMC) endpoint.

    For those that wish to use AWS EMC with StreamSmart, you must tell the system about your EMC endpoint. You can use the /configurations endpoint to create a secret configuration for your EMC endpoint, as shown below:

    curl -kvi -X POST "https://<ec2_public_dns>/api/v1/configurations"  \
     -H "Content-Type: application/json"  \
     -d '{
        "type": "SECRET",
        "id": "mediaconvert-config",
        "config": {
          "data": {
            "accesskey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
            "keyid": "AKIAIOSFODNN7EXAMPLE",
            "region": "us-east-1",
            "url": "https://vasjpylpa.mediaconvert.us-east-1.amazonaws.com",
          }
        }
    }'
    

    Important

    Please substitute the accesskey, keyid and region values above for the details that apply to your specific AWS EMC endpoint.

    Be careful to ensure that you use the mediaconvert-config name when submitting your (secret) EMC configuration.

Upgrading Versions (~ 25 mins)

Upgrading to a new version of the StreamSmart™ AMI is simply a matter of terminating/destroying your existing instance and installing the new one by repeating the Installation steps above for the new AMI.

1. Login to your AWS account using the AWS Web Console.
   
   
2. From the AWS UI console, choose Services -> Compute -> EC2.
   
   
3. Select the EC2 instance that is hosting your current StreamSmart™ instance.
   
   
4. Choose Instance state -> Terminate instance from the dropdown menu.
   
   
5. Follow the Installation instructions above for the new StreamSmart™ AMI.

Once the StreamSmart™ system is running, you are ready to submit new analyses and inspect the results.

For new users or those that are most comfortable with a GUI, you are encouraged to use the Insights VOD Monitor app to submit a new analysis. This app allows you to submit any number of no-reference (NR) or full-reference (FR) analyses and inspect their results using the built-in Insights dashboards. Please look here, should you need some help using the UI.

For those that would prefer to use the CLI, the following example uses cURL to submit a no-reference (NR) analysis for a video asset in AWS S3:

curl -kvi -X POST \
  https://<ec2_public_dns>/api/vod/v1/analyses \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": {
      "title": "Rocket Launch Analysis - S3 NR - Test"
    },
    "subjectAssets": [
        {
            "name": "rocket_launch_1080_h265_qp_31.mp4",
            "storageLocation": {
                "type": "S3",
                "name": "ssimwave-video-assets"
            },
            "path": "royalty_free/rocket_launch/outputs"
        }
    ],
    "analyzerConfig": {
      "enableBandingDetection": true
    }
}'

Once you have successfully deployed and verfied that your StreamSmart™ AMI is working, you are strongly encouraged to read Using StreamSmart™ where you will be provided with a more detailed overview of the StreamSmart™ system and given specific steps for further product education.

If you encounter trouble or have any questions about installing/launching your SSIMPLUS® VOD Monitor AMI, please create a support ticket by using the SSIMWAVE Help Center or feel free to reach out to your SSIMWAVE representative directly.

Enabling the Kubernetes Dashboard

For fixed scale deployments of SSIMPLUS® VOD Monitor in AWS, you can optionally (and temporarily) enable the Kubernetes Dashboard. The dashboard provides a Web UI for interacting with Kubernetes which can be especially useful in troubleshooting sessions with SSIMWAVE support. To enable the Kubernetes Dashboard, please follow the steps below:

1. Deploy and configure the Kubernetes Dashboard

   From a CLI, run the following command:

   ssh -i key.pem ubuntu@<ec2_public_dns> "~/startKubernetesDashboard.sh"
   

   where key.pem is the key file you created in step 11 of the Installation.

   Important

   The SSIMPLUS® VOD Monitor virtual machine provides SSH access using the following credentials user: ubuntu, password: ubuntu.
   If you chose to disable the SSH inbound rule in your security group and/or NACL, you will need to add it back in order to execute the command above (see step 5 of the Installation).

   You should see output similar to the following:

   Starting and configuring the Kubernetes Dashboard...
   namespace/kubernetes-dashboard created
   serviceaccount/kubernetes-dashboard created
   service/kubernetes-dashboard created
   secret/kubernetes-dashboard-certs created
   secret/kubernetes-dashboard-csrf created
   secret/kubernetes-dashboard-key-holder created
   configmap/kubernetes-dashboard-settings created
   role.rbac.authorization.k8s.io/kubernetes-dashboard created
   clusterrole.rbac.authorization.k8s.io/kubernetes-dashboard created
   rolebinding.rbac.authorization.k8s.io/kubernetes-dashboard created
   clusterrolebinding.rbac.authorization.k8s.io/kubernetes-dashboard created
   deployment.apps/kubernetes-dashboard created
   service/dashboard-metrics-scraper created
   deployment.apps/dashboard-metrics-scraper created
   secret "kubernetes-dashboard-certs" deleted
   secret/kubernetes-dashboard-certs created
   deployment.apps/kubernetes-dashboard patched
   clusterrolebinding.rbac.authorization.k8s.io "kubernetes-dashboard" deleted
   
   Deploying Kubernetes Dashboard ingress and cluster-admin role binding...
   clusterrolebinding.rbac.authorization.k8s.io/kubernetes-dashboard created
   ingress.networking.k8s.io/dashboard-ingress created
   
   Creating Kubernetes Dashboard token...
   secret/kubernetes-dashboard-token created
   
   Kubernetes Dashboard login token:
   yJhbGciOiJSUzI1NiIsImtpZCI6ImdDaldoR3E4bEowN1JmOGpwM0FLQ2pDVjhJMGNNMGxVRlpiMnlZcjVuNHcifQ.eyJpc3MiOi
   JrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJrdWJlcm
   5ldGVzLWRhc2hib2FyZCIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJrdWJlcm5ldGVzLWRhc2
   hib2FyZC10b2tlbi02YzJnYyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VydmljZS1hY2NvdW50Lm5hbWUiOiJrdW
   Jlcm5ldGVzLWRhc2hib2FyZCIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VydmljZS1hY2NvdW50LnVpZCI6IjU2Mj
   X2SQBwGnXaRap89koCipxAJarjYZRCJyOLEbXhdzf-6oHxLySXX3S5FwRvzaAbFyE5wdhweYJaHsrhwQ
   
   Finished!
   

   
   

2. Login to the Kubernetes Dashboard using the login token.

   At this point, your Kubernetes Dashboard should be accessible from a browser at the URL: https://ec2_public_dns>/dashboard

   Use the Kubernetes Dashboard login token in the command output from the step above to log in to the Kubernetes Dashboard.

Disabling the Kubernetes Dashboard

Although access to the Kubernetes Dashboard is secured through the use of a private token, it is generally recommended that, after you have completed your troubleshooting effort, you should disable the Kubernetes Dashboard by removing it from the deployment.

From a CLI run the following command:

ssh -i key.pem ubuntu@<ec2_public_dns> "~/stopKubernetesDashboard.sh"

where key.pem is the key file you created in step 11 of the Installation.

You should see output similar to the following:

Stopping the Kubernetes Dashboard...
namespace "kubernetes-dashboard" deleted
serviceaccount "kubernetes-dashboard" deleted
service "kubernetes-dashboard" deleted
secret "kubernetes-dashboard-certs" deleted
secret "kubernetes-dashboard-csrf" deleted
secret "kubernetes-dashboard-key-holder" deleted
configmap "kubernetes-dashboard-settings" deleted
role.rbac.authorization.k8s.io "kubernetes-dashboard" deleted
clusterrole.rbac.authorization.k8s.io "kubernetes-dashboard" deleted
rolebinding.rbac.authorization.k8s.io "kubernetes-dashboard" deleted
clusterrolebinding.rbac.authorization.k8s.io "kubernetes-dashboard" deleted
deployment.apps "kubernetes-dashboard" deleted
service "dashboard-metrics-scraper" deleted
deployment.apps "dashboard-metrics-scraper" deleted

Removing Kubernetes Dashboard ingress and cluster-admin role binding...

Finished!

The following steps are prerequisites for a successful deployment:

1. From your SSIMWAVE representative, you should receive or request the following items:

   1. VOD Production features license file (features.lic) containing values for the following, according to your purchase/trial agreement:

      • Alphanumeric license verification key
      • Audio loudness measurements
      • Banding detection scoring
      • Frame and map (banding, quality, color volume difference) generation
      • Color gamut and stats generation
      • Color volume difference map generation
      • Content complexity scoring
      • Expiration date (the day on which your license expires)
      • Frame level scoring
      • HDR10 & Dolby Vision support
      • Video, audio and quality check options
      • Insights data streaming credentials
      • Insights REST API (system-level) credentials
      • Insights customer organization and site names
        
        

   2. The OVA/QEMU that has been built for your trial/lab.

      The OVA/QEMU will be large in size (approximately 3GB) and named according to the following pattern:
      ssimplus-vod-monitor_MAJOR.MINOR.PATCH-BUILD_MM-DD-YYYY_HH-MM.ova/qcow2
      where MAJOR, MINOR, PATCH and BUILD represent the major, minor, patch and build numbers of the target build and YYYY, HH and MM are the year, hour and date of the virtual machine’s creation.
      
      

2. The physical/virtual host machine must have the following minimum hardware resources that can be dedicated to the SSIMPLUS® VOD Monitor virtual machine:

   1. 24G RAM (32G RAM preferred)
   2. 24 CPU cores (32 cores preferred)
   3. 25G of free disk space (100G preferred)
      
      
   Note

   You are strongly encouraged to use the preferred values above, when possible.

3. The physical/virtual host machine should, ideally, use a 64-bit Linux operating system.
   

   Please ensure that your host machine has installed the following common networking and filesystem packages:

   • openssh-server
   • nfs-common
   • nfs-utils (may not be available for all Linux distros)
   • net-tools
   • bridge-utils
     
     
   Note

   You may use an alternative operating system (i.e. Windows/MacOS) provided that your virtualization player can host our supported virtual machine container (i.e. OVA or QEMU). Instructions in this guide, however, will assume the preferred Linux-based host operating system.

4. The physical/virtual host machine should have installed a virtualization player that can support your chosen virtual machine container (i.e. Open Virtualization Format (OVF) or QEMU) along with hardware-assisted virtualization (i.e. Intel VT-x or AMD-V).

   For OVA files, one of the more popular virtualization players is Oracle’s VirtualBox.
   For QEMU files, VirtManager is a common option. See here for instructions on how to install VirtManager and KVM on Ubuntu 20.04.
   

   On a Linux host machine, a positive value for the following command indicates that you have hardware-assisted virtualization enabled:

   grep -Eoc '(vmx|svm)' /proc/cpuinfo
   

   
   

5. The video assets you wish to process must be either:

   1. mounted on the host machine in a folder that can be shared with SSIMPLUS® VOD Monitor virtual machine through the virtualization player,
   2. mountable as a Linux file system within the SSIMPLUS® VOD Monitor virtual machine (you can SSH into the instance and install drivers as needed),
   3. available via a Network File System (NFS),
   4. and/or available via AWS S3.
      
      

   In the case of NFS, the exported folder(s) must allow for read-only access to the assets without needing any specific user/group permissions and/or credentials.
   

   In the case of S3, you must have the following details available:

   • bucket name
   • access key id
   • access key
     
     

6. Your local network must allow outbound internet access on port 443 to the following hosts:

   • ingest-gateway.us-east.insights.ssimwave.com
   • insights.ssimwave.com
     
     
   Note

   The SSIMPLUS® VOD Monitor virtual machine supports using SOCKS5 and HTTP/S forward proxies, if required. Please see the Installation section below for configuration details.

7. You’ve created an account to access your results within SSIMWAVE’s Insights data platform.

The following steps illustrate installing SSIMPLUS® VOD Monitor as an OVA container named simplus-vod-monitor_2.21.0-25_09-07-2023_19-16.ova, using VirtualBox as the virtualization player and a CLI. You should replace simplus-vod-monitor_2.21.0-25_09-07-2023_19-16.ova with the image filename for your release. Similar steps should apply to other virtualization player products, many of which have GUIs to achieve the same operations. Please contact your SSIMWAVE representative if you have any questions.

1. Import the SSIMPLUS® VOD Monitor OVA into your virtualization player.

   vboxmanage import simplus-vod-monitor_2.21.0-25_09-07-2023_19-16.ova
   

   Please wait 5 minutes for the virtual machine to successfully import and stand up the all the services inside.
   
   

2. Verify your virtual machine import.

   vboxmanage list vms
   

   You should see your VM name in this list (in this case simplus-vod-monitor_2.21.0-25_09-07-2023_19-16)
   
   

3. Configure your virtual machine network settings.

   You will need the SSIMPLUS® VOD Monitor virtual machine to be accessible on your local network. Similarly, the virtual machine must be able to connect to the internet (i.e. on port 443 to the Insights hosts discussed in the Insights Prerequisites). There are two documented approaches below: Bridge Adapter and NAT.

   Bridged Adapter
   If the local network, on which your host machine resides, has a DHCP server then the simplest and preferred approach is to configure your virtual machine with a bridge adapter that is bound to your host machine’s physical network interface. This will ensure that, once the virtual machine is started, it will get its own IP address from your DHCP server and would then be directly accessible from any machine on your local network. The caveat here is that if you don’t want the IP address to change when the host or virtual machine is rebooted, you may need to modify your DHCP server to allow static assignment based on the interface’s MAC address or provide some alternative DNS solution.

   vboxmanage modifyvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" \
   --nic1 bridged --bridgeadapter1 $(route | grep '^default' | grep -o '[^ ]*$' | head -n 1)
   

   Notice in the example above route | grep '^default' | grep -o '[^ ]*$' | head -n 1 is automated way of determining the default adapter on your host machine. If you’d prefer, you can substitute that logic with the name of the appropriate adapter (e.g. eth0).

   Network Address Translation - NAT
   If you don’t have a DHCP server available, you can use Network Address Translation (NAT) and port forwarding to provide access to your virtual machine via your host machine. The following steps can be used with VirtualBox:

   vboxmanage modifyvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" \
   --nic1 nat --natpf1 "vodmonitorhttps,tcp,,8443,,443" --natpf1 "vodmonitorssh,tcp,,2222,,22"
   

   Here we instruct VirtualBox to forward all packets that come to the host machine on port 8443 to port 443 (HTTPS) on the virtual machine. The same is done for port 2222 and the standard SSH port, 22. Using this approach you can access the Stream™ On-Demand REST API using the hostname/IP of your host machine and the 8443 port. The following examples are common URLs used to interact with the Stream™ On-Demand REST API, modified to account for NAT and the port forwarding example above:

   • https://<hostmachine>:8443/status (System Status)
   • https://<hostmachine>:8443/api/vod/v1/analyses (Analysis submission endpoint)
     
     

   For more details on VirtualBox networking options, please take a look here.
   
   

4. (Optional, OVA and VirtualBox only) Share the host folders containing your video assets with the SSIMPLUS® VOD Monitor virtual machine.

   vboxmanage sharedfolder add "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" --name videos --hostpath /mnt/videos --readonly --automount
   

   If you have one or more folders mounted on your host that contain video assets you wish to use, you can set them up as shared folders in the SSIMPLUS® VOD Monitor virtual machine. In the example above, the folder you wish to share with the virtual machine is mounted on the host at /mnt/videos.

   Important

   Please ensure that host folder names use only alphanumeric characters, dashes (-) and/or underscores (_) in their names.

5. Start the SSIMPLUS® VOD Monitor virtual machine, choosing a headless mode, if available.

   vboxmanage startvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" --type headless
   

   It may take several minutes for the virtual machine to fully start and all networking services to become available.
   
   

6. (Bridged Adapter) If you used the bridged adapter in the network configuration step above, once the virtual machine is up and running, record the IP address it was assigned from the command below:

   vboxmanage guestproperty get "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" "/VirtualBox/GuestInfo/Net/0/V4/IP"
   

   If the IP address is not yet available you will see a message similar to the following: No value set!. In this case, simply keep trying.
   If you used NAT, this step does not apply to you and you will see an internal address here (most likely on the 10.0.2.x network) which you can ignore.
   
   

7. Verify that your SSIMPLUS® VOD Monitor instance can connect to our Insights cloud data platform.

   From a CLI, run the following command:

   ssh ubuntu@<ssimplus-vod-monitor> "~/testInsightsConnections.sh"
   

   where <ssimplus-vod-monitor> is the IP address (or FQDN) associated with your virtual machine.
   If you are are using the Bridged Adapter above, the IP address to use here will be the one you recorded in the previous step (assigned to your virtual machine by your network DHCP server). If you are using NAT, the IP address (or FQDN) to use will be that of the host machine, including the port (e.g. https://<host_machine_ip>:8443).

   Important

   The SSIMPLUS® VOD Monitor virtual machine provides SSH access using the following credentials user: ubuntu, password: ubuntu. If you are using Network Address Translation (NAT) to access your SSIMPLUS® VOD Monitor, take care to add the SSH forwarding port to the command above.

   If the instance can successfully connect to Insights, you should see output like the following:

   Creating Insights connection testing pod...
   job.batch/check-insights-connectivity created
   
   Checking for Insights connection tester pod to be COMPLETED...
   Checking for Insights connection tester pod to be COMPLETED...
   
   ingest-gateway.us-east.insights.ssimwave.com:443 -> Good.
   insighs.ssimwave.com:443 -> Good.
   
   job.batch "check-insights-connectivity" deleted
   

   If you see failures in the connection attempts above, please make sure that your local network allows outbound access on port 443 to the addresses listed in the Installation Prerequisites. If your network requires use of a proxy, please consult the appropriate section below.

   HTTP Proxy
   Similarly, an HTTP proxy can be configured as follows:

   ssh ubuntu@<ssimplus-vod-monitor> "~/configureInsightsProxy.sh --http-proxy <IP>:<PORT>"
   

   If your HTTP proxy server requires credentials, you can add them as follows:

   ssh ubuntu@<ssimplus-vod-monitor> "~/configureInsightsProxy.sh --http-proxy <IP>:<PORT> --http-proxy-user <USER> --http-proxy-password <PASSWORD>"
   

   where <ssimplus-vod-monitor> is the IP address/FQDN of your SSIMPLUS® VOD Monitor virtual machine instance (adjusting for any port forwarding that applies).

   SOCKS Proxy
   If your network requires the use of a SOCKS5 or HTTP forward proxy in order to connect to external hosts, you can configure the SSIMPLUS® VOD Monitor virtual machine to use a SOCKS5 proxy server as follows:

   ssh ubuntu@<ssimplus-vod-monitor> "~/configureInsightsProxy.sh --socks5-proxy <IP>:<PORT>"
   

   If your SOCKS5 proxy server requires credentials, you can add them as follows:

   ssh ubuntu@<ssimplus-vod-monitor> "~/configureInsightsProxy.sh --socks5-proxy <IP>:<PORT> --socks5-proxy-user <USER> --socks5-proxy-password <PASSWORD>"
   

   where <ssimplus-vod-monitor> is the IP address/FQDN of your SSIMPLUS® VOD Monitor virtual machine instance (adjusting for any port forwarding that applies).
   
   

8. Modify your VOD API Host setting in Insights.

   The VOD API Host value associated with your SSIMWAVE Insights account is used to redirect your browser to fetch frame images/maps when performing an in-depth inspection of a given result. For this functionality to work, you need to configure this value to match the IP address (or FQDN) associated with your virtual machine.

   Note

   You can use either the IP address or the equivalent FQDN when specifying the VOD API Host name. If you use a FQDN, you must make sure that all users of the SIMPLUS® VOD Monitor virtual machine will be able to resolve the name (i.e. either through a shared/network DNS server or local modification of /etc/hosts).

   1. From your machine (i.e. not the host machine for the VM), login to your Insights Account.
   2. Click on the user icon in the top right corner of the UI and pick Account from the dropdown menu.
   3. Scroll down to the Additional Details section and change your VOD Api Host value to match your virtual machine’s IP/FQDN.
   4. Click Save.
      
      
   Important

   Each user of the SSIMPLUS® VOD Monitor system will need to use the same value for their VOD API Host in their Insights account..

9. Verify that your SSIMPLUS® VOD Monitor virtual machine is operational.

   To verify the system status, use your machine (i.e. not the host machine for the VM) to load the following URL: https://<ssimplus-vod-monitor>/status into a web browser, where <ssimplus-vod-monitor> is the IP address or FQDN associated with the virtual machine, adjusting as necessary for any NAT port forwarding that applies.

   The page displayed is a system status page for all the SSIMPLUS® VOD Monitor services. At this point, all services should show as READY except for the following which will be NOT_READY, in addition to the final outcome:

   • FilebeatConfigurationService
   • InsightsClientService
   • InsightsKafkaService
     
     

   The services above are NOT_READY because they directly depend on a valid feature license, which we will upload in the next step.

   Important

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

   Each user of the SSIMPLUS® VOD Monitor system will need to accept this certificate so please direct everyone to load https://<ssimplus-vod-monitor>/status into their browsers once.

   Note

   It takes several minutes for the virtual machine to initialize and load the SSIMPLUS® VOD Monitor system. During this time, you may not get a response from the https://<ssimplus-vod-monitor>/status URL or you may see 503 (Service Unavailable), 500 (Proxy Error) pages or 404 (Not Found); this is expected. Simply refresh your browser every 30s until you see the correct content.

10. Upload your feature license.

    To finish the system configuration and address the services that are still NOT_READY, you must now apply your feature license. Using a browser on your machine (i.e. not the host machine for the VM), navigate to the Host page in your Insights account, where you will be presented with the information on your current host. Here you will see the following:

    • under Host information, your Insights Status and Insights API Status are both NOT CONNECTED,
    • your License information section will show ERROR and details will say that your are “Unable to connect to the license server” and
    • your System health section will show OFFLINE.
      
      

    Under the License information section, click on Upload license and pick the license file you received from your SSIMWAVE representative. Shortly after successfully loading the license, the Host page should refresh and your license should show as ACTIVE and your system health as ONLINE. If this is the case for you, feel free to jump to the next section Acessing Video Assets.

    Important

    It may take a minute for all the services to fully recognize the new license. If your system health reports OFFLINE even after uploading your license, click the Test host connection button in the Host information panel once every 10s until your system reports ONILNE. If your system health remains OFFLINE for more than a few minutes, you should expand the section to see the services that are not configured or responding as expected and reach out to your SSIMWAVE representative for help.

    If you’re interested, you can expand the System health section and click on Show all services to verify that the services that were previously OFFLINE (i.e. NOT_READY) in the step above are now ONLINE (i.e. READY). You can also revisit https://<ssimplus-vod-monitor>/status where all services and the final outcome should show as READY.

    Additionally, you can expand the License information section to verify that the details of your feature license match with your expectations.
    
    

11. (Optional) Configure access to your AWS Elemental MediaConvert (EMC) endpoint.

    For those that wish to use AWS EMC with StreamSmart, you must tell the system about your EMC endpoint. You can use the /configurations endpoint to create a secret configuration for your EMC endpoint, as shown below:

    curl -kvi -X POST "https://<ec2_public_dns>/api/v1/configurations"  \
     -H "Content-Type: application/json"  \
     -d '{
        "type": "SECRET",
        "id": "mediaconvert-config",
        "config": {
          "data": {
            "accesskey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
            "keyid": "AKIAIOSFODNN7EXAMPLE",
            "region": "us-east-1",
            "url": "https://vasjpylpa.mediaconvert.us-east-1.amazonaws.com",
          }
        }
    }'
    

    Important

    Please substitute the accesskey, keyid and region values above for the details that apply to your specific AWS EMC endpoint.

    Be careful to ensure that you use the mediaconvert-config name when submitting your (secret) EMC configuration.

Upgrading Versions (~ 30 mins)

Upgrading to a new version of the SSIMPLUS® VOD Monitor virtual machine is simply a matter of powering off your existing instance and installing the new one by repeating the Installation steps above for the new file.

1. Power off your existing SSIMPLUS® VOD Monitor virtual machine

   vboxmanage controlvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" poweroff
   

   
   

2. (Optional) Unregister and, optionally, remove your existing SSIMPLUS® VOD Monitor virtual machine

   vboxmanage unregistervm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" --delete
   

   The --delete switch is optional and will completely remove the OVA from your host system.
   
   

3. Follow Installation instructions for your new SSIMPLUS® VOD Monitor virtual machine/OVA, using the same choices as before.

Upgrading VM Hardware (~ 5 mins)

Allocating more CPU cores and/or memory to your SSIMPLUS® VOD Monitor virtual machine will allow you to process more analyses concurrently. To add hardware resources, simply power off your virtual machine, alter the CPU/RAM to the desired levels and restart. The following procedure illustrates how to do this using VirtualBox as the virtualization player:

1. Power off your existing SSIMPLUS® VOD Monitor virtual machine

   vboxmanage controlvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" poweroff
   

   
   

2. Modify the CPU and/or RAM allocated to your SSIMPLUS® VOD Monitor virtual machine

   vboxmanage modifyvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" --memory 32000
   vboxmanage modifyvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" --cpus 32
   

   In the examples above, we set the memory to 32GB and the number of cores/cpus to 32.
   
   

3. Start the SSIMPLUS® VOD Monitor virtual machine, choosing a headless mode, if available.

   vboxmanage startvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" --type headless
   

   Please wait 5 minutes for the virtual machine to successfully import and stand up all the services inside.
   
   

4. At this point, your SSIMPLUS® VOD Monitor virtual machine should be up and running. Load the URL https://<ssimplus-vod-monitor>/status in your browser, where <ssimplus-vod-monitor> is the IP address or FQDN associated with the virtual machine, adjusting as necessary for any NAT port forwarding. Verify that all services and the final outcome at the bottom of the page show as READY.
   

   Note

   It takes several minutes for the virtual machine to initialize and load the SSIMPLUS® VOD Monitor system. During this time, you may not get a response from the https://<ssimplus-vod-monitor>/status URL or you may see 503 (Service Unavailable), 500 (Proxy Error) pages or 404 (Not Found); this is expected. Simply refresh your browser every 30s until you see the correct content.

The following steps illustrate installing SSIMPLUS® VOD Monitor as a QEMU container named ssimplus-vod-monitor_2.21.0-25_09-07-2023_20-20.qcow2, using VirtManager as the virtualization player and a CLI. You should replace ssimplus-vod-monitor_2.21.0-25_09-07-2023_20-20.qcow2 with the image filename for your release. Similar steps should apply to other virtualization player products, many of which have GUIs to achieve the same operations. Please contact your SSIMWAVE representative if you have any questions.

1. If you are not using root, make sure you’ve add your user to the libvirt and kvm groups and then logout and back in.

   sudo usermod -aG libvirt $(whoami)
   sudo usermod -aG kvm $(whoami)
   logout
   

   
   

2. Configure your virtual machine network settings.

   You will need the SSIMPLUS® VOD Monitor virtual machine to be accessible on your local network. Similarly, the virtual machine must be able to connect to the internet (i.e. on port 443 to the Insights hosts discussed in the Insights Prerequisites). There are two documented approaches below: Bridge Adapter and NAT.

   Bridged Adapter
   If the local network, on which your host machine resides, has a DHCP server then the simplest and preferred approach is to configure your virtual machine with a bridge adapter that is bound to your host machine’s physical network interface. This will ensure that, once the virtual machine is started, it will get its own IP address from your DHCP server and would then be directly accessible from any machine on your local network. The caveat here is that if you don’t want the IP address to change when the host or virtual machine is rebooted, you may need to modify your DHCP server to allow static assignment based on the interface’s MAC address or provide some alternative DNS solution.

   Assuming your host is Linux and you are using the NetworkManager service to manage your network, you can do the following to establish a bridge network:

   sudo nmcli con add ifname br0 type bridge con-name br0
   sudo nmcli con add type bridge-slave ifname $(route | grep '^default' | grep -o '[^ ]*$' | head -n 1) master br0
   sudo nmcli con modify br0 bridge.stp no
   sudo reboot
   

   Notice in the example above route | grep '^default' | grep -o '[^ ]*$' | head -n 1 is automated way of determining the default adapter on your host machine. If you’d prefer, you can substitute that logic with the name of the appropriate adapter (e.g. eth0), if you know it.

   Note

   Depending on the Linux variant on your host machine and what service you are using to manage your networking, your solution to creating a bridge network may be different. Moreover, your local network may not have a DHCP server from which new local IP addresses can be obtained. Consult instructions for your Linux variant and networking policies and make adjustments to the above as necessary.

   Next, we add the bridge network to VirtManager by creating a file called bridge.xml somewhere on your host machine with the following contents:

   <network>
     <name>bridge</name>
     <forward mode="bridge"/>
     <bridge name="bridge" />
   </network>
   

   Add the network to VirtManager by executing the following:

   virsh net-define bridge.xml
   virsh net-start bridge
   virsh net-autostart bridge
   

   Verify that the bridge network is active by executing the following:

   virsh net-list
   

   Network Address Translation - NAT
   If you don’t have a DHCP server available on your local network and your host machine’s IP/hostname is static, you can use Network Address Translation (NAT) and port forwarding to provide access to your virtual machine via your host machine.

   First, let’s modify the default network to assign the same local IP address to your SSIMPLUS® VOD Monitor virtual machine:

   virsh net-edit default
   

   Modify the default network’s <ip> element as shown below:

   .
   .
   .
   <ip address='192.168.122.1' netmask='255.255.255.0'>
     <dhcp>
       <range start='192.168.122.2' end='192.168.122.254'/>
         <host mac='52:54:00:8f:7f:a5' name='ssimplus-vod-monitor' ip='192.168.122.2'/>
     </dhcp>
   </ip>
   

   Create and edit a QEMU hook file for libvirt as follows:

   sudo touch /etc/libvirt/hooks/qemu
   sudo chmod a+rx /etc/libvirt/hooks/qemu
   

   Use the following contents for the /etc/libvirt/hooks/qemu file:

   #!/bin/bash
   
   # IMPORTANT: Change the "VM NAME" string to match your actual VM Name.
   # In order to create rules to other VMs, just duplicate the below block and configure
   # it accordingly.
   if [ "${1}" = "ssimplus-vod-monitor" ]; then
   
      # Update the following variables to fit your setup
      GUEST_IP=192.168.122.2
      GUEST_PORT=443
      HOST_PORT=8443
   
      if [ "${2}" = "stopped" ] || [ "${2}" = "reconnect" ]; then
   	/sbin/iptables -D FORWARD -o virbr0 -p tcp -d $GUEST_IP --dport $GUEST_PORT -j ACCEPT
   	/sbin/iptables -t nat -D PREROUTING -p tcp --dport $HOST_PORT -j DNAT --to $GUEST_IP:$GUEST_PORT
      fi
      if [ "${2}" = "start" ] || [ "${2}" = "reconnect" ]; then
   	/sbin/iptables -I FORWARD -o virbr0 -p tcp -d $GUEST_IP --dport $GUEST_PORT -j ACCEPT
   	/sbin/iptables -t nat -I PREROUTING -p tcp --dport $HOST_PORT -j DNAT --to $GUEST_IP:$GUEST_PORT
      fi
   fi
   

   Restart the default network and the libvirtd service:

   virsh net-destroy default
   virsh net-start default
   sudo systemctl restart libvirtd
   

   The steps above ensure that a private IP address of 192.168.122.2 will always be assigned to the SSIMPLUS® VOD Monitor virtual machine and that the host machine will provide NAT services on behalf of the virtual machine, mapping port 8443->443.
   
   

3. Install the SSIMPLUS® VOD Monitor QEMU into VirtManager.

   If you are using the bridged adapter, run the following:

   virt-install --virt-type kvm --name ssimplus-vod-monitor --memory 32768 --vcpus 32 \
       --graphics none --os-type Linux --os-variant ubuntu22.04 --disk <qemu_path> \
       --import --noautoconsole --autostart --network bridge
   

   If you are using NAT, run the following:

   virt-install --virt-type kvm --name ssimplus-vod-monitor --memory 32768 --vcpus 32 \
       --graphics none --os-type Linux --os-variant ubuntu22.04 --disk <qemu_path> 
       --import --noautoconsole --autostart --network=default,model=virtio,mac=52:54:00:8f:7f:a5
   

   where <qemu_path> is the absolute path on disk where you copied the SSIMPLUS® VOD Monitor QEMU container (e.g. /home/userX/ssimplus-vod-monitor_2.21.0-25_09-07-2023_20-20.qcow2).

   Please wait 5 minutes for the virtual machine to successfully import and stand up all the services inside.

   Note

   Note that the command above gives the virtual machine 32G of RAM and 32 vCPUs. You may alter these to suit your underlying hardware but you should not use anything less than the minimum specification presented in the Installation Prerequisites.

4. Verify your virtual machine import.

   virsh list --all
   

   You should see your VM name in this list (in this case ssimplus-vod-monitor) and the state should be running.
   
   

5. (Bridged Adapter) Once the virtual machine is up and running, record the IP address it was assigned from the command below:

   virsh domifaddr --source agent ssimplus-vod-monitor 2> /dev/null | grep eth0 | awk -F " " '{print $4}' | cut -d"/" -f1
   

   This IP address should be local to the network on which your host machine sits and will be furnished by the DHCP server on your local network.

   Note

   If you don’t see an IP address immediately, keep retrying the command. It may take 5 minutes for the virtual machine to successfully import and stand up all the services inside.

   If you are using NAT, this step does not apply to you.

6. (Network Address Translation - NAT) Update SSIMPLUS® VOD Monitor to use the IP address of the host machine.

   In order to support NAT, the SSIMPLUS® VOD Monitor instance within the virtual machine needs to know about the local IP address of the host machine so it doesn’t ignore requests that come from that address. Run the following from a host machine CLI:

   hostIP=$(ip a | grep ' '$(route | grep '^default' | grep -o '[^ ]*$' | head -n 1) | grep inet | awk -F " " '{print $2}' | cut -d"/" -f1) 
   ssh ubuntu@192.168.122.2 "sed -i 's=nginx.ingress.kubernetes.io/server-alias: \"=nginx.ingress.kubernetes.io/server-alias: \"'$hostIP',=' ~/analyzer-ingress.yaml" 
   ssh ubuntu@192.168.122.2 "kubectl apply -f ~/analyzer-ingress.yaml"
   

   Important

   The SSIMPLUS® VOD Monitor virtual machine provides SSH access using the following credentials user: ubuntu, password: ubuntu.

   Note that when sending commands via SSH to the SSIMPLUS® VOD Monitor virtual machine from the host machine, we use the fixed, private IP 192.168.122.2. Using this IP to reach the SSIMPLUS® VOD Monitor virtual machine is only valid from within the host machine and not from anywhere else on your local network.

7. Verify that your SSIMPLUS® VOD Monitor instance can connect to our Insights cloud data platform.

   From a CLI, run the following command:

   ssh ubuntu@<ssimplus-vod-monitor> "~/testInsightsConnections.sh"
   

   where <ssimplus-vod-monitor> is the IP address of your SSIMPLUS® VOD Monitor virtual machine instance (i.e. assigned by your network DHCP server if you’re using the bridged adapter or 192.168.122.2 if you’re using NAT).

   Important

   The SSIMPLUS® VOD Monitor virtual machine provides SSH access using the following credentials user: ubuntu, password: ubuntu.

   If the instance can successfully connect to Insights, you should see output like the following:

   Creating Insights connection testing pod...
   job.batch/check-insights-connectivity created
   
   Checking for Insights connection tester pod to be COMPLETED...
   Checking for Insights connection tester pod to be COMPLETED...
   
   ingest-gateway.us-east.insights.ssimwave.com:443 -> Good.
   insighs.ssimwave.com:443 -> Good.
   
   job.batch "check-insights-connectivity" deleted
   

   If you see failures in the connection attempts above, please make sure that your local network allows outbound access on port 443 to the addresses listed in the Installation Prerequisites. If your network requires use of a proxy, please consult the appropriate section below.

   HTTP Proxy
   Similarly, an HTTP proxy can be configured as follows:

   ssh ubuntu@<ssimplus-vod-monitor> "~/configureInsightsProxy.sh --http-proxy <IP>:<PORT>"
   

   If your HTTP proxy server requires credentials, you can add them as follows:

   ssh ubuntu@<ssimplus-vod-monitor> "~/configureInsightsProxy.sh --http-proxy <IP>:<PORT> --http-proxy-user <USER> --http-proxy-password <PASSWORD>"
   

   where <ssimplus-vod-monitor> is the IP address of your SSIMPLUS® VOD Monitor virtual machine instance (i.e. assigned by your network DHCP server if you’re using the bridged adapter or 192.168.122.2 if you’re using NAT).

   SOCKS Proxy
   If your network requires the use of a SOCKS5 or HTTP forward proxy in order to connect to external hosts, you can configure the SSIMPLUS® VOD Monitor virtual machine to use a SOCKS5 proxy server as follows:

   ssh ubuntu@<ssimplus-vod-monitor> "~/configureInsightsProxy.sh --socks5-proxy <IP>:<PORT>"
   

   If your SOCKS5 proxy server requires credentials, you can add them as follows:

   ssh ubuntu@<ssimplus-vod-monitor> "~/configureInsightsProxy.sh --socks5-proxy <IP>:<PORT> --socks5-proxy-user <USER> --socks5-proxy-password <PASSWORD>"
   

   where <ssimplus-vod-monitor> is the IP address of your SSIMPLUS® VOD Monitor virtual machine instance (i.e. assigned by your network DHCP server if you’re using the bridged adapter or 192.168.122.2 if you’re using NAT).
   
   

8. Modify your VOD API Host setting in Insights.

   The VOD API Host value associated with your SSIMWAVE Insights account is used to redirect your browser to fetch frame images/maps when performing an in-depth inspection of a given result. For this functionality to work, you need to configure this value to match the local IP address associated with your SSIMPLUS® VOD Monitor virtual machine. If you used the bridged adapter above, then this local IP address will the one you recorded in step 5. If you are using NAT, the local IP address will be that of the host machine along with the 8443 port forward value (e.g. 172.31.68.50:8443). Be careful to not use the private IP 192.168.122.2 that was used in the steps above when executing various commands on the SSIMPLUS® VOD Monitor virtual machine from the host machie via SSH.

   1. From your machine (i.e. not the host machine for the VM), login to your Insights Account.
   2. Click on the user icon in the top right corner of the UI and pick Account from the dropdown menu.
   3. Scroll down to the Additional Details section and change your VOD Api Host value to match your virtual machine’s IP/FQDN.
   4. Click Save.
      
      
   Important

   Each user of the SSIMPLUS® VOD Monitor system will need to use the same value for their VOD API Host in their Insights account..

9. Verify that your SSIMPLUS® VOD Monitor virtual machine is operational.

   To verify the system status, use your machine (i.e. not the host machine for the VM) to load the following URL: https://<ssimplus-vod-monitor>/status into a web browser, where <ssimplus-vod-monitor> is the IP address of your SSIMPLUS® VOD Monitor virtual machine. If you are using the bridged adapter, <ssimplus-vod-monitor> will be the IP assigned by your network DHCP server and recorded in step 5. If you are using NAT, <ssimplus-vod-monitor> will be the local IP address of your host machine along with the 8443 port forward value (e.g. 172.31.68.50:8443), which is the same value as you used in step 8 above.

   The page displayed is a system status page for all the SSIMPLUS® VOD Monitor services. At this point, all services should show as READY except for the following which will be NOT_READY, in addition to the final outcome:

   • FilebeatConfigurationService
   • InsightsClientService
   • InsightsKafkaService
     
     

   The services above are NOT_READY because they directly depend on a valid feature license, which we will upload in the next step.

   Important

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

   Each user of the SSIMPLUS® VOD Monitor system will need to accept this certificate so please direct everyone to load https://<ssimplus-vod-monitor>/status into their browsers once.

   Note

   It takes several minutes for the virtual machine to initialize and load the SSIMPLUS® VOD Monitor system. During this time, you may not get a response from the https://<ssimplus-vod-monitor>/status URL or you may see 503 (Service Unavailable), 500 (Proxy Error) pages or 404 (Not Found); this is expected. Simply refresh your browser every 30s until you see the correct content.

10. Upload your feature license.

    To finish the system configuration and address the services that are still NOT_READY, you must now apply your feature license. Using a browser on your machine (i.e. not the host machine for the VM), navigate to the Host page in your Insights account, where you will be presented with the information on your current host. Here you will see the following:

    • under Host information, your Insights Status and Insights API Status are both NOT CONNECTED,
    • your License information section will show ERROR and details will say that your are “Unable to connect to the license server” and
    • your System health section will show OFFLINE.
      
      

    Under the License information section, click on Upload license and pick the license file you received from your SSIMWAVE representative. Shortly after successfully loading the license, the Host page should refresh and your license should show as ACTIVE and your system health as ONLINE. If this is the case for you, feel free to jump to the next section Acessing Video Assets.

    Important

    It may take a minute for all the services to fully recognize the new license. If your system health reports OFFLINE even after uploading your license, click the Test host connection button in the Host information panel once every 10s until your system reports ONILNE. If your system health remains OFFLINE for more than a few minutes, you should expand the section to see the services that are not configured or responding as expected and reach out to your SSIMWAVE representative for help.

    If you’re interested, you can expand the System health section and click on Show all services to verify that the services that were previously OFFLINE (i.e. NOT_READY) in the step above are now ONLINE (i.e. READY). You can also revisit https://<ssimplus-vod-monitor>/status where all services and the final outcome should show as READY.

    Additionally, you can expand the License information section to verify that the details of your feature license match with your expectations.
    
    

11. (Optional) Configure access to your AWS Elemental MediaConvert (EMC) endpoint.

    For those that wish to use AWS EMC with StreamSmart, you must tell the system about your EMC endpoint. You can use the /configurations endpoint to create a secret configuration for your EMC endpoint, as shown below:

    curl -kvi -X POST "https://<ec2_public_dns>/api/v1/configurations"  \
     -H "Content-Type: application/json"  \
     -d '{
        "type": "SECRET",
        "id": "mediaconvert-config",
        "config": {
          "data": {
            "accesskey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
            "keyid": "AKIAIOSFODNN7EXAMPLE",
            "region": "us-east-1",
            "url": "https://vasjpylpa.mediaconvert.us-east-1.amazonaws.com",
          }
        }
    }'
    

    Important

    Please substitute the accesskey, keyid and region values above for the details that apply to your specific AWS EMC endpoint.

    Be careful to ensure that you use the mediaconvert-config name when submitting your (secret) EMC configuration.

Upgrading Versions (~ 30 mins)

Upgrading to a new version of the SSIMPLUS® VOD Monitor virtual machine is simply a matter of powering off your existing instance and installing the new one by repeating the Installation steps above for the new file.

1. Power off your existing SSIMPLUS® VOD Monitor virtual machine.

   virsh shutdown "ssimplus-vod-monitor"
   

   
   

2. Undefine and, optionally, remove your existing SSIMPLUS® VOD Monitor virtual machine.

   virsh undefine "ssimplus-vod-monitor" --remove-all-storage
   

   The --remove-all-storage switch is optional and will completely remove the QEMU image from your host system.
   
   

3. Follow Installation instructions for your new SSIMPLUS® VOD Monitor virtual machine/QEMU, using the same choices as before.

Upgrading VM Hardware (~ 5 mins)

Allocating more CPU cores and/or memory to your SSIMPLUS® VOD Monitor virtual machine will allow you to process more analyses concurrently. To add hardware resources, simply power off your virtual machine, alter the CPU/RAM to the desired levels and restart.

1. Power off your existing SSIMPLUS® VOD Monitor virtual machine.

   virsh shutdown "ssimplus-vod-monitor"
   

   
   

2. Modify the CPU and/or RAM allocated to your SSIMPLUS® VOD Monitor virtual machine.

   virsh edit "ssimplus-vod-monitor"
   

   Use the editor to change your values for memory and vcpu.
   
   

3. Start the SSIMPLUS® VOD Monitor virtual machine.

   virsh start "ssimplus-vod-monitor"
   

   Please wait 5 minutes for the virtual machine to successfully import and stand up all the services inside.
   
   

4. At this point, your SSIMPLUS® VOD Monitor virtual machine should be up and running. Load the URL https://<ssimplus-vod-monitor>/status in your browser, where <ssimplus-vod-monitor> is the IP address or FQDN associated with the virtual machine, adjusting as necessary for any NAT port forwarding. Verify that all services and the final outcome at the bottom of the page show as READY.
   

   Note

   It takes several minutes for the virtual machine to initialize and load the SSIMPLUS® VOD Monitor system. During this time, you may not get a response from the https://<ssimplus-vod-monitor>/status URL or you may see 503 (Service Unavailable), 500 (Proxy Error) pages or 404 (Not Found); this is expected. Simply refresh your browser every 30s until you see the correct content.

As mentioned in the Installation Prerequisites, the SSIMPLUS® VOD Monitor virtual machine can access any video assets that are:

1. mounted on the host machine in a folder that is then shared with SSIMPLUS® VOD Monitor virtual machine through the virtualization player,
2. mountable as a Linux file system within the SSIMPLUS® VOD Monitor virtual machine (you can SSH into the instance and install drivers as needed),
3. available via a Network File System (NFS),
4. and/or available via AWS S3.

Shared Host Folders (OVA, VirtualBox only)

If you shared one or more folders on the host machine with the SSIMPLUS® VOD Monitor virtual machine using VirtualBox (see step 4 from Installation), each folder will be automatically mounted as a subfolder under /media and named according to the following pattern: sf_<share_name>, where sf stands for shared folder and <share_name> is the name you choose for your share. To access assets in these folders within SSIMPLUS® VOD Monitor, you will want to use the PVC storage type and the PVC name virtual-box-shares which will put you at the root of /media where you can then build the remainder of the path to your asset.

For example, if you shared the folder /mnt/videos from the host machine as videos using the following command:

vboxmanage sharedfolder "ssimplus-vod-monitor_2.21.0-25_09-07-2023_19-16" --name videos --hostpath /mnt/videos --readonly --automount

your assets would be mounted in virtual machine under /media/sf_videos and you would use the virtual-box-shares PVC along with the remainder of the path from the /media folder, as shown in the following JSON snippet:

{
    "name": "rocket_launch.mp4",
    "storageLocation": {
        "type": "PVC",
        "name": "virtual-box-shares"
    },
    "path": "sf_videos/royalty_free/rocket_launch/source"
}

Mounted File System in Virtual Machine

The SSIMPLUS® VOD Monitor provides a PVC called local-media which can be used to access any folder in the virtual machine. As such, you can SSH into the virtual machine and mount any file system for which dirvers/support is available for Ubuntu 22.04. The local-media PVC is configured to resolve to the root of the virtual machien (i.e. /) and, as such, the paths you supply must be absolute, as demonstrated in the JSON snippet below:

{
    "name": "rocket_launch.mp4",
    "storageLocation": {
        "type": "PVC",
        "name": "local-media"
    },
    "path": "/media/sf_videos/royalty_free/rocket_launch/source"
}

NFS

Inside the SSIMPLUS® VOD Monitor virtual machine is a small script that facilitates mounting an existing NFS server and exported folder. From a CLI, you can execute the following:

ssh ubuntu@<ssimplus-vod-monitor> "~/loadNFS.sh -s <NFS_SERVER> -p <READ_ONLY_FOLDER> -n <PVC_NAME>"

where:

• <ssimplus-vod-monitor> is the IP address/FQDN of your SSIMPLUS® VOD Monitor virtual machine instance (adjusting for any port forwarding that applies)
• <NFS_SERVER> is the NFS server host/IP (e.g. nas.ssimwave.lan),
• <READ_ONLY_FOLDER> is the read-only folder path (e.g. /Public) and
• <PVC_NAME> is the prefix for the Kubernetes Persistent Volume Claim (PVC) name to use (e.g. video-files).

Before you run the command above, it is important to make sure that you have the exported NFS folder paths correctly specified and that they have been configured to allow access from the SSIMPLUS® VOD Monitor virtual machine. On your Linux host machine, you can run the following command to see the list of exported NFS folders (assuming you have NFS utils installed):

showmount -e <NFS_SERVER>
Export list for <NFS_SERVER>:
/mnt/temp_hdd3/videos 172.31.0.0/16

In the example above, /mnt/temp_hdd3/videos is the only exported folder path and it is available to any machine on the 172.31 network. Assuming that is correct for your environment (i.e. your SSIMPLUS® VOD Monitor virtual machine has an IP on the 172.31 network), then you would run the following command to create a PVC for the NFS mount:

ssh ubuntu@<ssimplus-vod-monitor> "~/loadNFS.sh -s <NFS_SERVER> -p /mnt/temp_hdd3/videos -n video-files"

NFS Example

Consider the following example:

ssh ubuntu@<ssimplus-vod-monitor> "~/loadNFS.sh -s nas.ssimwave.lan -p /Public -n video-files"

where <ssimplus-vod-monitor> is the IP address/FQDN of your SSIMPLUS® VOD Monitor virtual machine instance (adjusting for any port forwarding that applies).

The script creates a Kubernetes NFS persistent volume (PV) called video-files-pv, a corresponding persistent volume claim (PVC) called video-files-pvc and a temporary testing pod that mounts the associated PVC and lists the contents at the root to ensure that the configuration is correct.

If successful, you should output like the following:

Creating NFS PV, PVC and testing pod for /Public on nas.ssimwave.lan...
persistentvolume/video-files-pv created
persistentvolumeclaim/video-files-pvc created
pod/video-files-tester created

Checking for NFS PVC to be BOUND...
Checking for NFS tester pod to be RUNNING...
Checking for NFS tester pod to be RUNNING...

Mounted! Video files listing:

videoFolder1
videoFolder2
.
.
.

pod "video-files-tester" deleted

The name of the Kubernetes PVC (i.e. video-files-pvc) is important and you should take note of its name as it will be required when submitting analyses using assets from the folder. You can use the script above to mount as many NFS folders as you like so long as you take care to ensure that each one has a unique PVC name.

AWS S3

Inside the SSIMPLUS® VOD Monitor virtual machine is a small script that facilitates mounting an AWS S3 bucket. From a CLI, you can execute the following:

ssh ubuntu@<ssimplus-vod-monitor> "~/loadS3.sh -b <BUCKET_NAME> -k <ACCESS_KEY_ID> -a <ACCESS_KEY>"

where:

• <ssimplus-vod-monitor> is the IP address/FQDN of your SSIMPLUS® VOD Monitor virtual machine instance (adjusting for any port forwarding that applies)
• <BUCKET_NAME> is the AWS S3 bucket name, (e.g. ssimwave-video-assets),
• <ACCESS_KEY_ID> is the access key id (e.g. AKIAIOSFODNN7EXAMPLE) and
• <ACCESS_KEY> is the access key (e.g. wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY).

The script creates an encrypted Kubernetes secret to store the S3 bucket credentials.

If successful, you should output like the following:

Creating Kubernetes secret for S3 access data to bucket ssimwave-video-assets...
secret/s3secret-ssimwave-video-assets created

You can use the script above to mount as many S3 buckets as you wish.

The name of the S3 bucket (i.e. ssimwave-video-assets) is important and you should take note of its name as it will be required when submitting analyses using assets from the bucket. After setting an S3 bucket using this script, you would access assets from that bucket as demonstrated in the JSON snippet below:

{
    "name": "rocket_launch.mp4",
    "storageLocation": {
        "type": "S3",
        "name": "ssimwave-video-assets"
    },
    "path": "/royalty_free/rocket_launch/source"
}

Once the SSIMPLUS® VOD Monitor virtual machine is running and you have mounted your video assets, you are ready to submit new analyses and inspect the results.

For new users or those that are most comfortable with a GUI, you are encouraged to use the Insights VOD Monitor app to submit a new analysis. This app allows you to submit any number of no-reference (NR) or full-reference (FR) analyses and inspect their results using the built-in Insights dashboards. Please look here, should you need some help using the UI.

For those that would prefer to use the CLI, the following example uses cURL to submit a no-reference (NR) analysis for a video asset in NFS:

curl -kvi -X POST \
  https://<ssimplus-vod-monitor>/api/vod/v1/analyses \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": {
      "title": "Rocket Launch Analysis - NFS NR - Test"
    },
    "subjectAssets": [
        {
            "name": "rocket_launch.mp4",
            "storageLocation": {
                "type": "PVC",
                "name": "video-files-pvc"
            },
            "path": "videos/royalty_free/rocket_launch/source"
        }
    ],
    "analyzerConfig": {
      "enableBandingDetection": true
    }
}'

Once you have successfully deployed and verfied that your SSIMPLUS® VOD Monitor virtual machine is working, you are strongly encouraged to read Using SSIMPLUS VOD Monitor where you will be provided with a more detailed overview of the SSIMPLUS® VOD Monitor system and given specific steps for further product education.

If you encounter trouble or have any questions about installing/launching your SSIMPLUS® VOD Monitor virtual machine, please create a support ticket by using the SSIMWAVE Help Center or feel free to reach out to your SSIMWAVE representative directly.

Enabling the Kubernetes Dashboard

For fixed scale deployments of SSIMPLUS® VOD Monitor in a virtual machine, you can optionally (and temporarily) enable the Kubernetes Dashboard. The dashboard provides a Web UI for interacting with Kubernetes which can be especially useful in troubleshooting sessions with SSIMWAVE support. To enable the Kubernetes Dashboard, please follow the steps below:

1. Deploy and configure the Kubernetes Dashboard

   From a CLI, run the following command:

   ssh ubuntu@<ssimplus-vod-monitor> "~/startKubernetesDashboard.sh"
   

   Important

   The SSIMPLUS® VOD Monitor virtual machine provides SSH access using the following credentials user: ubuntu, password: ubuntu. If you are using Network Address Translation (NAT) to access your SSIMPLUS® VOD Monitor, take care to add the SSH forwarding port to the command above.

   You should see output similar to the following:

   Starting and configuring the Kubernetes Dashboard...
   namespace/kubernetes-dashboard created
   serviceaccount/kubernetes-dashboard created
   service/kubernetes-dashboard created
   secret/kubernetes-dashboard-certs created
   secret/kubernetes-dashboard-csrf created
   secret/kubernetes-dashboard-key-holder created
   configmap/kubernetes-dashboard-settings created
   role.rbac.authorization.k8s.io/kubernetes-dashboard created
   clusterrole.rbac.authorization.k8s.io/kubernetes-dashboard created
   rolebinding.rbac.authorization.k8s.io/kubernetes-dashboard created
   clusterrolebinding.rbac.authorization.k8s.io/kubernetes-dashboard created
   deployment.apps/kubernetes-dashboard created
   service/dashboard-metrics-scraper created
   deployment.apps/dashboard-metrics-scraper created
   secret "kubernetes-dashboard-certs" deleted
   secret/kubernetes-dashboard-certs created
   deployment.apps/kubernetes-dashboard patched
   clusterrolebinding.rbac.authorization.k8s.io "kubernetes-dashboard" deleted
   
   Deploying Kubernetes Dashboard ingress and cluster-admin role binding...
   clusterrolebinding.rbac.authorization.k8s.io/kubernetes-dashboard created
   ingress.networking.k8s.io/dashboard-ingress created
   
   Creating Kubernetes Dashboard token...
   secret/kubernetes-dashboard-token created
   
   Kubernetes Dashboard login token:
   yJhbGciOiJSUzI1NiIsImtpZCI6ImdDaldoR3E4bEowN1JmOGpwM0FLQ2pDVjhJMGNNMGxVRlpiMnlZcjVuNHcifQ.eyJpc3MiOi
   JrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJrdWJlcm
   5ldGVzLWRhc2hib2FyZCIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJrdWJlcm5ldGVzLWRhc2
   hib2FyZC10b2tlbi02YzJnYyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VydmljZS1hY2NvdW50Lm5hbWUiOiJrdW
   Jlcm5ldGVzLWRhc2hib2FyZCIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VydmljZS1hY2NvdW50LnVpZCI6IjU2Mj
   X2SQBwGnXaRap89koCipxAJarjYZRCJyOLEbXhdzf-6oHxLySXX3S5FwRvzaAbFyE5wdhweYJaHsrhwQ
   
   Finished!
   

   
   

2. Login to the Kubernetes Dashboard using the login token.

   At this point, your Kubernetes Dashboard should be accessible from a browser at the URL: https://<ssimplus-vod-monitor>/dashboard

   Important

   If you are using Network Address Translation (NAT) to access your SSIMPLUS® VOD Monitor, take care to add the HTTPS/443 forwarding port to the URL above.

   Use the Kubernetes Dashboard login token in the command output from the step above to log in to the Kubernetes Dashboard.

Disabling the Kubernetes Dashboard

Although access to the Kubernetes Dashboard is secured through the use of a private token, it is generally recommended that, after you have completed your troubleshooting effort, you should disable the Kubernetes Dashboard by removing it from the deployment.

From a CLI run the following command:

ssh ubuntu@<ssimplus-vod-monitor> "~/stopKubernetesDashboard.sh"

You should see output similar to the following:

Stopping the Kubernetes Dashboard...
namespace "kubernetes-dashboard" deleted
serviceaccount "kubernetes-dashboard" deleted
service "kubernetes-dashboard" deleted
secret "kubernetes-dashboard-certs" deleted
secret "kubernetes-dashboard-csrf" deleted
secret "kubernetes-dashboard-key-holder" deleted
configmap "kubernetes-dashboard-settings" deleted
role.rbac.authorization.k8s.io "kubernetes-dashboard" deleted
clusterrole.rbac.authorization.k8s.io "kubernetes-dashboard" deleted
rolebinding.rbac.authorization.k8s.io "kubernetes-dashboard" deleted
clusterrolebinding.rbac.authorization.k8s.io "kubernetes-dashboard" deleted
deployment.apps "kubernetes-dashboard" deleted
service "dashboard-metrics-scraper" deleted
deployment.apps "dashboard-metrics-scraper" deleted

Removing Kubernetes Dashboard ingress and cluster-admin role binding...

Finished!

1. Create your SSIMWAVE Insights account.

   If you have not done so already, create your account in SSIMWAVE’s Insights cloud data platform by sending your preferred email address(es) to your SSIMWAVE representative using Slack/email or the SSIMWAVE Help Center. Feel free at this time to pass along the email addresses of the users you expect to need access to SSIMPLUS® VOD Monitor system. Each user will be registered and receive a welcome email with instructions.
   
   

2. Login to the AWS console and pick your target region.

   Important

   It is strongly recommended that you use an AWS user/role that has the AWS::AdminstratorAccess policy so that you have all of the permissions required to execute the CloudFormation scripts in later steps.

   Use the AWS region selector in the web console to select the target region into which you want to install the IMAX Stream™ On-Demand Platform.

   Important

   In order to avoid egress data costs, you are strongly encouraged to choose the same region as the S3 bucket(s) holding the video assets you will want to use with StreamSmart™.

3. Create the ssimplus-vod-monitor-managed-service-deployment-prerequisites CloudFormation stack

   From the Search field beside the Services button in the menu bar, launch the CloudFormation service, and click the Create stack button to create a new stack. Choose the Template is ready and Amazon S3 URL options. The SSIMPLUS® CloudFormation template for the deployment prerequisites can be found at the S3 URL:
   https://ssimwave-public.s3.amazonaws.com/cloud-formation-templates/SSIMPLUS+VOD+Monitor+Managed+Service+Deployment+Prerequisites.yaml.

   

   This first CloudFormation template will establish the resources required for the SSIMWAVE to successfully deploy the SSIMPLUS® Analyzer Cluster in your AWS account. Specifically, the template creates the following resources:

   • IAM policies
     • ssimplus-vod-monitor-managed-service-policy (used to create/manage EKS clusters, load balancers, auto-scalers etc - minimum set of permissions)
     • AmazonEKS_EFS_CSI_Driver_Policy (Used to create/manage EFS file systems - minimum set of permissions)
   • IAM role: ssimplus-vod-monitor-managed-service-role (used for creating/managing the SSIMPLUS® Analyzer Cluster)
   • KMS encryption keys (for the encryption/decryption of secrets and filesystems with the SSIMPLUS® Analyzer Cluster)
   • TLS certificate (for encrypted access to the SSIMPLUS® Analyzer Cluster)
     
     

   Refer to the deployment architecture for more details.
   
   

4. Specify stack details

   

   • Name the stack ssimplus-vod-monitor-managed-service-deployment-prerequisites.
     
     

   • The SSIMPLUS Analyzer Cluster hostname parameter is the hostname for your SSIMPLUS® Analyzer Cluster.

     The hostname should be a fully-qualified domain name (FQDN) that you can use to directly access your SSIMPLUS® Analyzer Cluster (i.e. the part of the SSIMPLUS® VOD Monitor system deployed your private cloud/on-prem infrastructure). Typically, the hostname will be a subdomain of a parent domain that your company already owns and may even be managed as a hosted zone within AWS Route 53.

     CompanyX, for example, might own companyx.com and thus a logical hostname for the SSIMPLUS® Analyzer Cluster may be vodmonitor.companyx.com. Regardless of your choice of hostname, in later steps, you will need the permissions to add DNS A and CNAME records to the parent domain so traffic can be routed to the SIMPLUS® Analyzer Cluster.
     
     

   • The SSIMPLUS Analyzer Cluster access (CIDR blocks) parameter is the comma-delimited list of IPs that are allowed access to your SSIMPLUS® Analyzer Cluster.

     In order to secure access to your SSIMPLUS® Analyzer Cluster, you are encouraged to identify CIDR blocks that encompass the full range of IP addresses that are allowed access to the system.
     
     

   • The SSIMPLUS Analyzer Cluster availability zone (AZ1/AZ2) parameters are the availability zones to use for the SSIMPLUS® Analyzer Cluster deployment.

     The SSIMPLUS® Analyzer Cluster is deployed across multiple availability zones in order to support higher availability. If you don’t have or specify valid preferences here, SSIMWAVE will select two on your behalf.
     
     

   • The SSIMWAVE Managed Service AWS IAM role ARN parameter is provided to you by your SSIMWAVE representative through Slack/e-mail or the SSIMWAVE Help Center.

     This value represents the Amazon resource name (ARN) for the SSIMWAVE IAM role that you agree to grant access to your account for the purposes of deploying, configuring, managing and monitoring your SSIMPLUS® VOD Monitor system. This role is created by SSIMWAVE specifically for your managed instance and access to it is tightly controlled and monitored.
     
     

5. Configure stack options.

   Feel free to add a tag here to mark all resources that the are created by the CloudFormation script, as shown below:

   You should be able to accept all the default options but pay particular attention to the IAM role. If the AWS user/role that you are using to build and execute your CloudFormation stack does not have administrative privileges (i.e. AWS::AdminstratorAccess policy) in your AWS account then you must either grant them to your user/role or pick an IAM role name from the dropdown illustrated below that does have the AWS::AdminstratorAccess policy.

   

6. Review and submit stack.

   The only work to do on the review page is to select the checkbox that acknowledges that the CloudFormation script will be creating IAM resources, as shown below:

   

7. Create a CNAME record for your TLS certificate.

   Once you submit your stack, the AWS console will show you the stack progress as a table of events. At the point where the script creates your TLS certificate (i.e. SSIMPLUSVODMonitorCertificate), the script will pause and output a DNS record in the Status reason column that looks something like the following:
   

   Content of DNS Record is: {Name: _3ae0bc74e5128840e8c895b5aa3e28d8.vodmonitor.companyx.com.,Type: CNAME,Value: _bddcde8107a82addacbcb8b10dd9cc69.wrpxpmnjfs.acm-validations.aws.}

   Important

   At this point, you need to create a CNAME record in your hostname’s parent domain using the name and value displayed.
   The stack will remain paused until this record has been successfully added and it can validate the TLS certificate.
   
   Please note that it can take a few minutes after adding the CNAME record for it to propagate and be recognized.
   If you take too long to create the CNAME record, the stack may time out in which case you will have to delete the stack and start again from step 3.

   If you see any errors in the stack progress, feel free to contact your SSIMWAVE representative if you are unsure how to determine and/or fix the root cause. Errors when running the stack can often be attributed to a lack of permissions to perform the actions in the template. Please refer to step 5 above.
   
   

8. Contact your SSIMWAVE representative upon successful completion.

   Once the stack has successfully completed, please inform your SSIMWAVE representative that the installation prerequisites have been completed using the SSIMWAVE Help Center. At this point, SSIMWAVE has what it needs to install the SSIMPLUS® Analyzer Cluster as a managed service in your account and you should be notified via your support ticket as to the target date for installation completion. If you’re are interested, please refer to section Managed Service Installation Details below for some high-level information on what AWS resources and services are created as part of the installation.

Managed Service Installation Details

The following is a list of various AWS resources and services that are created as part of installing the SSIMPLUS® Analyzer Cluster. Please refer to the deployment architecture diagram for additional details:

• EKS cluster with 2 dynamically scalable node groups:

  • vod-monitor-control-nodes - This node group hosts the control plane for your SSIMPLUS® Analyzer Cluster and supports the REST APIs and various system services for communicating with Kubernetes, Amazon S3 and the SSIMWAVE Insights cloud data platform. The number of nodes elastically scales (i.e. grows and shrinks) to meet demand and both the minimum and preferred node count here is 2 while the maximum is 10. Most usages of the system would rarely require more than 2 nodes running concurrently. By default, each node created in this group is a c5.2xlarge on-demand EC2 instance and, due to the minimum count of 2, you can be guaranteed that at least two of the aforementioned EC2 instances will be running at all times (24/7/365). Since at least 2 nodes in this group should be available at all times, it is not recommended to use spot instances for this group.
    
    

  • vod-monitor-data-nodes - This node group hosts the data plane for your SSIMPLUS® Analyzer Cluster and supports the pods/processes used for the probing and analyzing of video assets and the streaming of their scores and metadata to SSIMWAVE Insights. The number of nodes elastically scales (i.e. grows and shrinks) to meet demand and both the minimum and preferred node count here is 0 while the maximum 30. By default, each node created in this group is a c5.4xlarge spot EC2 instance. Spot instances are considerably cheaper to operate but, if they are reclaimed, the SSIMPLUS® VOD Analyzer Cluster will need to (automatically) restart the affected probe or analysis. If your organization uses AWS reserved instance pricing or has a savings plan and you would like to use instead of spot instances, please inform your SSIMWAVE representative.
    
    

• Auto-scaler that controls the elastic scaling within the node groups.
  
  

• Amazon EFS system to store any frames and SSIMWAVE maps (quality, banding, color volume difference) when detailed inspection is requested.
  
  

• AWS VPC endpoint to ensure that all of the encrypted data streamed to the SSIMWAVE Insights cloud data platform stays within AWS and never travels over the Internet.
  
  

• Various other AWS resources such as a VPC, Subnets, Elastic IPs, EC2 instances, LoadBalancer, Prometheus agents and logging support.

  Note

  All application logs for the SSIMPLUS® Analyzer Cluster are configured to stream to SSIMWAVE’s Insights platform where they can be accessed via an ELK stack by SSIMWAVE Support.

DNS Records

After the SSIMPLUS® Analyzer Cluster managed service has been deployed, your SSIMWAVE representative will update your support ticket with the following DNS record information (record name and value will differ from example below):

The A record above associates the hostname you chose for your SSIMPLUS® Analyzer Cluster with the IP address of the AWS LoadBalancer that manages external HTTPS access to the system.

1. At this point, you will need to add this DNS record to your parent domain (i.e. companyx.com in the example above) using the tooling/processes appropriate for your organization. If you use AWS Route 53 for your parent domain, for example, you would navigate to its associated hosted zone and add the records there.
   
   
2. Once you’ve added the DNS A record, visit the Host page in your Insights account. You should see that your license is ACTIVE and your system health is ONLINE. If this is not the case, please check that you have added the DNS records above properly and waited 5-10 minutes for the values to propagate. If your system is still showing problems, please reach out to your SSIMWAVE representative.

SSIMPLUS® Analyzer Cluster namespace

Along with the DNS record information above, your SSIMWAVE representative will update your support ticket with the SSIMPLUS® Analyzer Cluster namespace. This string value represents the Kubernetes namespace used to hold all the Kubernetes pods for the various software components that comprise the SSIMPLUS® Analyzer Cluster. The value will be named according to the organization-site pattern. CompanyX with a site of VOD Monitor Production, for example, would use a namespace of companyx-vod-monitor-production. For now, you need only be aware that you will need this namespace value when providing access to the S3 buckets holding your video assets below.

Providing access to video assets in S3

Now that the SSIMPLUS® Analyzer Cluster is operational and reachable, you are ready to provide read-only access to the S3 bucket(s) that contain the video assets you wish to analyze. In order to facilitate a frictionless experience, SSIMWAVE has again curated a set of CloudFormation templates to create the AWS IAM policies and roles required to provide this read-only access.

1. Create the ssimplus-vod-monitor-managed-service-s3-read-only-role CloudFormation stack.

   Using the CloudFormation service, click the Create stack button to create a new stack. Choose the Template is ready and Amazon S3 URL options. The SSIMPLUS® CloudFormation template to create the IAM role for read-only access to your S3 bucket(s) can be found at the S3 URL: https://ssimwave-public.s3.amazonaws.com/cloud-formation-templates/SSIMPLUS+VOD+Monitor+Managed+Service+S3+Read-Only+Role.yaml.

   This CloudFormation template will create an IAM role (ssimplus-vod-monitor-managed-service-s3-read-only-role) that will serve as an aggregation point for all the S3 bucket read-only IAM policies that you will create in subsequent steps.
   
   

2. Specify stack details.

   

   • Name the stack ssimplus-vod-monitor-managed-service-s3-read-only-role.
     
     
   • The SSIMPLUS Analyzer EKS cluster name parameter is the name of your SSIMPLUS® Analyzer Cluster. The default value of SSIMPLUS-VOD-Monitor should always be sufficient here but your SSIMWAVE representative will inform you as part of the post-installation handoff if it needs to change.
     
     

3. Proceed to configure the stack options, review and submit the stack and monitor the stack progress.

   Follow steps 5 and 6, respectively, from the Installation Prequisites section above.

4. Create the ssimplus-vod-monitor-managed-service-add-s3-bucket CloudFormation stack.

   Using the CloudFormation service, click the Create stack button to create a new stack. Choose the Template is ready and Amazon S3 URL options.

   The SSIMPLUS® CloudFormation template for adding an S3 bucket can be found at the S3 URL: https://ssimwave-public.s3.amazonaws.com/cloud-formation-templates/SSIMPLUS+VOD+Monitor+Managed+Service+Add+S3+Bucket.yaml.

   This CloudFormation template will create an IAM policy that will permit read-only access to the S3 bucket in question. The policy will be attached to the IAM role created above (i.e. ssimplus-vod-monitor-managed-service-s3-read-only-role), thereby permitting your EKS cluster to read from the S3 bucket.
   
   

5. Specify stack details.

   

   • Name the stack in a way that identifies the specific bucket, such as ssimplus-vod-monitor-managed-service-s3-<bucket_name>. For a bucket called ssimwave-videos you might use ssimplus-vod-monitor-managed-service-s3-ssimwave-videos.
     
     
   • The S3 bucket name parameter is the name of your S3 bucket. Use only the name here and not the ARN.
     
     

6. Proceed to configure the stack options, review and submit the stack and monitor the stack progress.

   Follow steps 5 and 6, respectively, from the Installation Prequisites section above.
   
   

7. Submit a test analysis.

   At this point, the SSIMPLUS® VOD Monitor is ready for use. Using the Analyze page, submit a no-reference analysis of a short asset from one of your S3 buckets. For help on how to submit an analysis, please read here.

Exercising explicit control of role-based access

As described in the deployment architecture, SSIMWAVE uses IAM role-based sharing (i.e. customer-management-role -> ssimplus-vod-monitor-managed-service-role) in order to create and update the SSIMPLUS® Analyzer Cluster in the customer’s VPC. While the permissions for the ssimplus-vod-monitor-managed-service-role are the minimum required for successful operation, some customers may want to exercise explicit control over when and how long this role-based sharing is available (i.e. limit to periods of creation, upgrade etc.). To disconnect the role-based sharing between the two VPCs, one can use the AWS Web console (or CLI) to update the trust relationship on the ssimplus-vod-monitor-managed-service-role to deny the sts:AssumeRole permission for the SSIMWAVE role, as shown in the example below:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Principal": {
                "AWS": "arn:aws:iam::077383753319:role/aws-reserved/sso.amazonaws.com/AWSReservedSSO_companyx-vod-production_d28f75fb83bd9880"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

To re-enable the role-based sharing, you would change the "Effect": "Deny" line to read "Effect": "Allow".

Now that the SSIMPLUS® Analyzer Cluster has been successfully deployed, you are ready to submit new analyses and inspect the results.

For new users or those that are most comfortable with a GUI, you are encouraged to use the Insights VOD Monitor app to submit a new analysis. This app allows you to submit any number of no-reference (NR) or full-reference (FR) analyses and inspect their results using the built-in Insights dashboards. Please look here, should you need some help using the UI.

For those that would prefer to use the CLI, the following example uses cURL to submit a no-reference (NR) analysis for a video asset in AWS S3:

curl -kvi -X POST \
  https://<cluster_hostname>/api/vod/v1/analyses \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": {
      "title": "Rocket Launch Analysis - S3 NR - Test"
    },
    "subjectAssets": [
        {
            "name": "rocket_launch_1080_h265_qp_31.mp4",
            "storageLocation": {
                "type": "S3",
                "name": "ssimwave-video-assets",
                "credentials": {
                  "useAssumedIAMRole": true
                }
            },
            "path": "royalty_free/rocket_launch/outputs"
        }
    ],
    "analyzerConfig": {
      "enableBandingDetection": true
    }
}'

For AWS EKS deployments, the <cluster_hostname> will be the hostname/FQDN of your SSIMPLUS® Analyzer Cluster (see Installation Prequisites for details).

Lastly, you are strongly encouraged to read Using SSIMPLUS VOD Monitor where you will be provided with a more detailed overview of the SSIMPLUS® VOD Monitor system and given specific steps for further product education.

If you encounter trouble or have any questions about the installation prerequisites or post installation steps, please first consult the instructional video in the overview. If you still have issues, feel free to create a support ticket by using the SSIMWAVE Help Center or to reach out to your SSIMWAVE representative directly.

The SSIMPLUS® Analyzer Cluster is designed to be installed into any modern Kubernetes environment (v1.23+). The following steps are prerequisites for a successful deployment:

1. From your SSIMWAVE representative, you should receive or request the following items:

   1. VOD Production features license file (features.lic) containing values for the following, according to your purchase agreement:

      • Alphanumeric license verification key
      • Audio loudness measurements
      • Banding detection scoring
      • Frame and map (banding, quality, color volume difference) generation
      • Color gamut and stats generation
      • Color volume difference map generation
      • Content complexity scoring
      • Expiration date (the day on which your license expires)
      • Frame level scoring
      • HDR10 & Dolby Vision support
      • Video, audio and quality check options
      • Insights data streaming credentials
      • Insights REST API (system-level) credentials
      • Insights customer organization and site names
        
        

   2. Google Cloud Repository (GCR) service account JSON key file providing temporary access to SSIMWAVE’s gcr.io/ssimwave-vodmonitor repository.
      
      

   3. A deployment archive containing the Kubernetes cluster, deployment and service descriptors for the SSIMPLUS® Analyzer Cluster, in YAML format. The archive is named according to following pattern:
      ssimwave-vodmonitor-production-MAJOR.MINOR.PATCH-BUILD.tar.gz
      where MAJOR, MINOR, PATCH and BUILD represent the major, minor, patch and build numbers of the purchased build.
      
      

2. The machine you are using to deploy should use the Linux operating system.
   

   Please ensure that your host machine has installed the following common networking and filesystem packages:

   • openssh-server
   • nfs-common
   • nfs-utils
   • net-tools
     
     

3. The machine you are using to deploy has the Docker engine installed.
   
   

4. The machine you are using to deploy has the Helm binary installed.
   
   

5. The machine you are using to deploy has HTTPS (port 443) access to SSIMWAVE’S Google Cloud Repository (GCR) at the following location:

   • gcr.io/ssimwave-vodmonitor
     
     

AWS EKS Deployment

1. On the machine you are using to deploy, follow only the prerequisites identified here for installing kubectl and eksctl.

   After following the prerequisites, you should have installed and configured the kubectl and eksctl binaries and established IAM permissions for working with EKS clusters and nodes.
   Please ensure that you have installed v1.24.7+ of kubectl and v0.125.0+ of eksctl.
   
   

2. Pick a target AWS region into which you want to install the SSIMPLUS® Analyzer Cluster.

   Important

   In order to avoid egress data costs, you are strongly encouraged to choose the same region as the S3 bucket(s) holding the video assets you will want to use with SSIMPLUS® VOD Monitor.

3. Follow the steps in the Installation Prerequisites for SSIMPLUS® Analyzer Cluster - AWS Managed Service, skipping the last step (i.e. step 8).

   Important

   It is strongly recommended that you use an AWS user/role that has the AWS::AdminstratorAccess policy so that you have all of the permissions required to execute the installation.

4. You’ve created an account in SSIMWAVE’s Insights cloud data platform for you and anyone that will want to access the SSIMPLUS® VOD Monitor system.
   
   

Bare-metal Deployment

1. The machine you are using to deploy has kubectl installed.
   
   

2. You have the following authorizations in your Kubernetes cluster and/or namespace:

   • get/list/watch/create/update/patch/delete on pods, services, deployments, daemonsets, jobs, ingresses, configmaps, persistent volumes and persistent volume claims
     
     

3. Your kubectl executable has its context set to use your target namespace:
   

   • kubectl config set-context <context>.
     
     

4. Your Kubernetes cluster must have outbound internet access on port 443 to the following hosts:

   • ingest-gateway.us-east.insights.ssimwave.com
   • insights.ssimwave.com
     
     
   Note

   The Installation section below will address how to account for environments where your Kubernetes node(s) must use an HTTP or SOCKS5 proxy to reach the hosts above.

5. You’ve created an account in SSIMWAVE’s Insights cloud data platform for you and anyone that will want to access the SSIMPLUS® VOD Monitor system.

To simplify the process of installing and configuring the SSIMPLUS® Analyzer Cluster, separate sections have been created depending on your target Kubernetes environment. Deployments to AWS Elastic Kubernetes Service (EKS), for example, would follow the heading of the same name. As specific Kubernetes environments call for specialized procedures, new sections will be added. If you are unsure which instructions to use, please contact your SSIMWAVE representative or refer to steps in Bare-Metal/Other.

AWS Elastic Kubernetes Service (~ 45 mins)

1. Extract the SSIMPLUS® VOD Monitor archive, containing the Kubernetes cluster, deployment and service descriptors, to an empty folder using the following command:
   tar -zxf ssimwave-vodmonitor-production-MAJOR.MINOR.PATCH-BUILD.tar.gz
   where MAJOR, MINOR, PATCH and BUILD represent the major, minor, patch and build numbers of the desired build.
   
   

2. Edit the YAML file cluster/eks/cluster.yaml and replace all lines that end in # REPLACE-ME with the substitutions from the table below:
   

   Placeholder	Value
   <region>	The AWS region you selected and used when creating your ssimplus-vod-monitor-managed-service-deployment-prerequisites CloudFormation stack in the Installation Prerequisites. Use the CloudFormation service to consult the stack Outputs tab and the SSIMPLUSAnalyzerClusterRegion value.
   <availability_zone_1>	The first AWS availability zone you selected when creating your ssimplus-vod-monitor-managed-service-deployment-prerequisites CloudFormation stack in the Installation Prerequisites. Use the CloudFormation service to consult the stack Outputs tab and the SSIMPLUSAnalyzerClusterAZ1 value.
   <availability_zone_2>	The second AWS availability zone you selected when creating your ssimplus-vod-monitor-managed-service-deployment-prerequisites CloudFormation stack in the Installation Prerequisites. Use the CloudFormation service to consult the stack Outputs tab and the SSIMPLUSAnalyzerClusterAZ2 value.
   <kms_key>	The AWS KMS key ARN created as part of your ssimplus-vod-monitor-managed-service-deployment-prerequisites CloudFormation stack in the Installation Prerequisites. Use the CloudFormation service to consult the stack Outputs tab and the SSIMPLUSAnalyzerClusterKeyArn value.
   <cluster_access_cidr>	The CIDR block for restricting administrative access to your EKS cluster. This should be limited to the machine(s) that need eksctl and kubectl access to the EKS cluster. These values will not affect user access to the SSIMPLUS® VOD Monitor itself. At the very least, you need to include the machine that you currently using to execute the installation.
   <control_plane_ec2_instance_type>	The backing EC2 instance type for new nodes in the control-plane. The control-plane is used for the “always-on” pods and services, which include the Analyzer Cluster REST API. Instance type recommendation: c5.2xlarge/c5a.2xlarge
   <data_plane_ec2_instance_type>	The backing EC2 instance type for new nodes in the data-plane. The data-plane is used for the estimation and analysis pods. Instance type recommendation: c5.4xlarge/c5a.4xlarge

3. Create your Kubernetes cluster.

   eksctl create cluster -f ./cluster/eks/cluster.yaml
   

   Note

   This process can take 15-20 minutes and you may see repeated messages of “waiting for CloudFormation stack…”.

4. Create a kubectl context for your cluster and apply it.

   aws eks --region=<region> update-kubeconfig --name=SSIMPLUS-VOD-Monitor
   kubectl config use-context arn:aws:eks:<region>:<accountID>:cluster/SSIMPLUS-VOD-Monitor
   

   where
   

   • <region> is the AWS region you chose in Installation Prerequisites and
     
   • <accountID> is your AWS account ID.
     
     

5. Install the cluster autoscaler.

   wget https://raw.githubusercontent.com/kubernetes/autoscaler/master/cluster-autoscaler/cloudprovider/aws/examples/cluster-autoscaler-autodiscover.yaml
   

   Modify the YAML file (cluster-autoscaler-autodiscover.yaml) accordingly:

   • replace k8s.gcr.io/autoscaling/cluster-autoscaler:v1.22.2 with k8s.gcr.io/autoscaling/cluster-autoscaler:v1.24.0
   • replace <YOUR CLUSTER NAME> with SSIMPLUS-VOD-Monitor
   • add - --scale-up-from-zero to the bottom of the command list
     
     

   Next, apply the YAML with the following command:

   kubectl --context arn:aws:eks:<region>:<accountID>:cluster/SSIMPLUS-VOD-Monitor apply -f cluster-autoscaler-autodiscover.yaml
   

   
   

6. Create the desired namespace for your SSIMPLUS® Analyzer Cluster.

   kubectl --context arn:aws:eks:<region>:<accountID>:cluster/SSIMPLUS-VOD-Monitor create namespace <NAMESPACE>
   

   Important

   Pick an all lowercase namespace that represents your organization and site, separated by dashes (refer to the organization and site names in your VOD Monitor feature license file).
   CompanyX with a site of VOD Monitor Production, for example, would use a namespace of companyx-vod-monitor-production.

7. Edit the YAML file vodmonitor/vodmonitor.yaml and modify the http-reverse-proxy Service (approx. line 419) as shown below:
   

       - apiVersion: v1
         kind: Service
         metadata:
           name: http-reverse-proxy
           namespace: "{namespace}"
           annotations:
             service.beta.kubernetes.io/aws-load-balancer-backend-protocol: http
             service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "<tls_certificate_arn>"
             service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "http,probe"
             service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: "600"
             service.beta.kubernetes.io/aws-load-balancer-name: "SSIMPLUS-VOD-Monitor"
           labels:
             name: http-reverse-proxy
             app: ssimwave.vodmonitor.restapi
             cluster: SSIMWAVE
             provider: SSIMWAVE
             version: v1
         spec:
           ports:
           - name: http
             port: 443
             protocol: TCP
             targetPort: 8080
           selector:
             httpReverseProxy: "true"
           loadBalancerSourceRanges:
           - "<load_balancer_source_cidr>"
           .
           .
           - "<load_balancer_source_cidr_n>"
           type: LoadBalancer
   

   where:
   

   • <tls_certificate_arn> represents the ARN of the TLS certificate that was created as part of your ssimplus-vod-monitor-managed-service-deployment-prerequisites CloudFormation stack in the Installation Prerequisites. Use the CloudFormation service to consult the stack Outputs tab and the SSIMPLUSVODMonitorCertificate value.
     
   • <load_balancer_source_cidr>…<load_balancer_source_cidr_n> represent one or more CIDRs for restricting access to the AWS Load balancer and, hence, the SSIMPLUS® Analyzer Cluster itself. These CIDR block values are the same ones entered as part of your ssimplus-vod-monitor-managed-service-deployment-prerequisites CloudFormation stack in the Installation Prerequisites. Use the CloudFormation service to consult the stack Outputs tab and the SSIMPLUSAnalyzerClusterAccessCIDR values.
     
     
   Important

   Make sure that the CIDR block(s) you use for restricting access to the http-reverse-proxy LoadBalancer service include all potential users/clients that may want to use the SSIMPLUS® VOD Monitor system.

   For reference, with the modifications above, you are:

   • adding annotations to the http-reverse-proxy AWS LoadBalancer service to use the ARN for your TLS certificate and configure various LoadBalancer properties,
   • changing the external port named http from 8080 to 443,
   • adding CIDR block restrictions to restrict access to the load balancer service and
   • changing the http-reverse-proxy Kubernetes Service type from ClusterIP to LoadBalancer.
     
     

8. Edit the YAML file vodmonitor/vodmonitor.yaml (approx. line 999) and remove the vod-frameservices-cache-pv PersistentVolume completely (i.e. remove all of the following lines):
   

       - apiVersion: v1
         kind: PersistentVolume
         metadata:
           name: vod-frameservices-cache-pv
           namespace: "{namespace}"
           labels:
             app: vod-frameservices
             cluster: SSIMWAVE
             provider: SSIMWAVE
             type: local
             version: v1
         spec:
           accessModes:
           - ReadWriteOnce
           capacity:
             storage: 500Gi
           hostPath:
             path: /tmp
           storageClassName: image-cache
           volumeMode: Filesystem
   

   
   

9. Edit the YAML file vodmonitor/vodmonitor.yaml (approx. line 999) and modify the vod-frameservices-cache-pvc PersistentVolumeClaim as shown below:
   

       - apiVersion: v1
         kind: PersistentVolumeClaim
         metadata:
           name: vod-frameservices-cache-pvc
           namespace: "{namespace}"
           labels:
             app: vod-frameservices
             cluster: SSIMWAVE
             provider: SSIMWAVE
             version: v1
         spec:
           resources:
             requests:
               storage: 500Gi
           accessModes:
           - ReadWriteMany
           storageClassName: efs-sc
   

   
   

10. (Optional) SSIMPLUS® Analyzer is capable of producing device-adaptive scores for a multitude of devices. To choose a list of default devices that are used in absence of any per-analysis choices, edit the YAML file vodmonitor/vodmonitor.yaml and change the devices list under analyzer-config-map (approx. line 60) to suit your needs, an example of which is shown below:

       data:
         config.json: |-
           {
             "devices": [
               "ssimpluscore",
               "ipad2021pro12.9",
               "imac27inch",
               "macbookpro16.2inch",
               "iphone13promax",
               "oled65c9pua"
             ],
             "jpeg2000DecodeThreads": -1
           }
       kind: ConfigMap
         metadata:
           labels:
             app: ssimwave.vodmonitor.restapi
             provider: SSIMWAVE
           name: analyzer-config-map
    

    Note

    The example shown above uses commonly chosen devices that represent one device per category (i.e. tablet, monitor, laptop, smartphone, TV) and should be suitable for most customers. For details on all supported devices and their respective codes, please see the Scoring Devices section under SSIMPLUS® Analyzer Configuration of the REST API.

    Note that users can always choose to override the default devices used here and specify their own devices on a per-analysis basis by supplying them in the analyzer configuration of the request body (or using the Insights VOD Monitor App).

11. Configure AWS Elastic File System (EFS).

    From a Linux CLI, execute the following commands below while performing the following substitutions:

    • Replace <region> with the AWS region you chose in Installation Prerequisites
    • Replace <region_repo> below with the value that matches your target AWS region (see here).
    • Replace <accountID> with your AWS accountID
      
      

    kubectl config use-context arn:aws:eks:<region>:<accountID>:cluster/SSIMPLUS-VOD-Monitor
    
    eksctl create iamserviceaccount \
        --cluster SSIMPLUS-VOD-Monitor \
        --namespace kube-system \
        --name efs-csi-controller-sa \
        --attach-policy-arn arn:aws:iam::<accountID>:policy/AmazonEKS_EFS_CSI_Driver_Policy \
        --approve \
        --region <region>
    
    helm repo add aws-efs-csi-driver https://kubernetes-sigs.github.io/aws-efs-csi-driver/
    
    helm repo update
    
    helm upgrade --kube-context arn:aws:eks:<region>:<accountID>:cluster/SSIMPLUS-VOD-Monitor \
        -i aws-efs-csi-driver aws-efs-csi-driver/aws-efs-csi-driver \
        --namespace kube-system \
        --set image.repository=<region_repo>/eks/aws-efs-csi-driver \
        --set controller.serviceAccount.create=false \
        --set controller.serviceAccount.name=efs-csi-controller-sa
    
    vpc_id=$(aws eks describe-cluster \
        --name SSIMPLUS-VOD-Monitor \
        --query "cluster.resourcesVpcConfig.vpcId" \
        --output text)
    
    cidr_range=$(aws ec2 describe-vpcs \
        --vpc-ids $vpc_id \
        --query "Vpcs[].CidrBlock" \
        --output text \
        --region <region>)
    
    security_group_id=$(aws ec2 create-security-group \
        --group-name EKSEfsSecurityGroup \
        --description "EKS EFS security group" \
        --vpc-id $vpc_id \
        --output text)
    
    aws ec2 authorize-security-group-ingress \
        --group-id $security_group_id \
        --protocol tcp \
        --port 2049 \
        --cidr $cidr_range
    
    file_system_id=$(aws efs create-file-system \
        --region <region> \
        --performance-mode generalPurpose \
        --query 'FileSystemId' \
        --output text)
    
    for subnet in $(aws ec2 describe-subnets --filters "Name=vpc-id,Values=$vpc_id" --query 'Subnets[*].{SubnetId: SubnetId}' --output text); \
        do aws efs create-mount-target --file-system-id $file_system_id --subnet-id $subnet --security-groups $security_group_id; \
        done
    
    curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-efs-csi-driver/master/examples/kubernetes/dynamic_provisioning/specs/storageclass.yaml
    
    sed -i "s/fileSystemId:.*/fileSystemId: $file_system_id/g" storageclass.yaml
    
    kubectl --context arn:aws:eks:<region>:<accountID>:cluster/SSIMPLUS-VOD-Monitor apply -f storageclass.yaml
    

    
    

12. Create private repositories in AWS Elastic Container Registry (ECR) for the SSIMPLUS® Analyzer Cluster Docker images.

    The SSIMPLUS® Analyzer Cluster software is available as a series of Docker images stored in SSIMWAVE’s GCR Docker image repository (i.e. gcr.io/ssimwave-vodmonitor). The goal here is to create private repositories in AWS ECR for each Docker image required.

    To create the private repositories needed, execute the following from a Linux CLI:

    aws ecr create-repository --region <region> --repository-name vodmonitor/analyzer
    aws ecr create-repository --region <region> --repository-name vodmonitor/ssim-capture
    aws ecr create-repository --region <region> --repository-name vodmonitor/analyzer-resource-estimator
    aws ecr create-repository --region <region> --repository-name vodmonitor/analyzer-rest-api
    aws ecr create-repository --region <region> --repository-name vodmonitor/frame-services-rest-api
    

    where <region> is the AWS region you chose in Installation Prerequisites.

    From a Linux CLI, update your Docker instance with the login data for your AWS ECR:
    

    aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <aws_ecr_repository>
    

    where <aws_ecr_repository> is your AWS ECR repository and uses the format: <aws_account_id>.dkr.ecr.<region>.amazonaws.com.
    
    

13. Import the SSIMPLUS® Analyzer Cluster Docker images into your AWS ECR.

    Using the JSON key you received in the Installation Prerequisites, you’re now ready to fetch the Docker images for the SSIMPLUS® Analyzer Cluster and store them in your AWS ECR. To aid you in this endeavor, SSIMWAVE has included a BASH script named setup-for-k8s.sh inside the deployment archive you exploded in step 1.

    From a Linux CLI, update your Docker runtime instance with the login data for SSIMWAVE’s GCR:
    

    cat <keyfile.json> | docker login -u _json_key --password-stdin https://gcr.io
    

    where <keyfile.json> is the GCR service account JSON key file you received from your SSIMWAVE representative.

    Note

    If you are using gcloud and your docker is configured to use credential helpers for gcr.io, you will likely need to execute the following command:
    gcloud auth activate-service-account --key-file=<keyfile.json>

    From within the directory where you exploded the deployment archive, issue the following command:

    ./setup-for-k8s.sh -d "<aws_ecr_repository>/vodmonitor" -n <NAMESPACE>
    

    where <aws_ecr_repository> is your AWS ECR repository and in the format: <aws_account_id>.dkr.ecr.<region>.amazonaws.com and <NAMESPACE> is the namespace you created in step 7 above.

    The script will pull all the SSIMPLUS® Analyzer Cluster Docker images from our GCR repository, tag them with the new ECR location (i.e. <aws_ecr_repository>/vodmonitor) and then push them up to your ECR. The script also modifies all the image references in the YAML (i.e. vodmonitor/vodmonitor.yaml) for these new ECR locations.

    If you have problems with the script or require further assistance, please contact your SSIMWAVE representative.

    Important

    For security reasons, your JSON key will only work for a limited time (i.e 2 weeks). If your key has expired, the script above will fail with connection errors. You can get a new JSON key by contacting your SSIMWAVE representative.

14. Deploy the SSIMPLUS® Analyzer Cluster.

    From a CLI, execute the following command:

    kubectl --context arn:aws:eks:<region>:<accountID>:cluster/SSIMPLUS-VOD-Monitor apply -f ./vodmonitor/vodmonitor.yaml
    

    • Replace <region> with the AWS region you chose in Installation Prerequisites
    • Replace <accountID> with your AWS accountID
      
      

    If you see errors on the CLI after applying the YAML descriptors or your pods appear to have errors (check using kubectl -n <NAMESPACE> get pods), please review the content for the following:

    • YAML is properly formatted
    • JSON you altered or added is properly formed (i.e. you didn’t forget to add a comma to a previous line when adding a new line, etc.)
    • Image location references (i.e. image: XXX) are properly pointing to your ECR
    • Your features license (features.lic) has been properly copied/applied in the YAML (spaces and formatting are accurate)
      
      
    Note

    Although the SSIMPLUS® Analyzer Cluster’s deployment descriptors, service descriptors and RBAC definitions follow Kubernetes conventions, some elements may cause incompatibilities with your target Kubernetes environment, depending on security constraints. If this proves to be the case, please contact your SSIMWAVE representative for help in resolving any such problems.

15. Add the DNS A record.

    You will need to add a DNS A record to associate the hostname you chose for your SSIMPLUS® Analyzer Cluster with the hostname of your system’s AWS Load Balancer service. The system’s Load Balancer service name can be found by running the following command:
    

    kubectl --context arn:aws:eks:<region>:<accountID>:cluster/SSIMPLUS-VOD-Monitor -n <NAMESPACE> get services
    

    • Replace <region> with the AWS region you chose in Installation Prerequisites
    • Replace <accountID> with your AWS accountID
      
      

    Take note of the value displayed in the EXTERNAL-IP column for the http-reverse-proxy service (e.g. a012c3d440fd94c3c8fabfeb1ead3645-66809327.us-east-1.elb.amazonaws.com).
    

    At this point you should have a DNS A record that is similar to the following:

    DNS Record Type	Name	Value
    A	vodmonitor.companyx.com	a012c3d440fd94c3c8fabfeb1ead3645-66809327.us-east-1.elb.amazonaws.com.

    If you use AWS Route 53 and have access to the hosted zone for your parent domain (i.e. companyx.com in the example above), you can add the DNS A directly to the hosted zone.

    If you do not use AWS Route 53, then you will need to add both records to your parent domain using the tooling/processes appropriate for your organization.
    
    

16. Modify the VOD API Host setting in your Insights account.

    The VOD API Host value associated with your SSIMWAVE Insights account is used to redirect your browser to fetch frame images/maps as part of performing an in-depth inspection of a given result. For this functionality to work, you need to configure this value to match the hostname/FQDN associated with your SSIMPLUS® Analyzer Cluster.
    

    1. Login to your Insights Account.
    2. Click on the user icon in the top right corner of the UI and pick Account from the dropdown menu.
    3. Scroll down to the Additional Details section and change your VOD Api Host value to match the FQDN associated with your TLS certificate.
    4. Click Save.
       
       
    Important

    All users of SSIMPLUS® VOD Monitor will need to make this same adjustment to their VOD API Host setting under their Insights account.

17. Upload your feature license.

    To finish the system configuration, you must now apply your feature license. Using your browser, navigate to the Host page in your Insights account, where you will be presented with the information on your current host. Here you will see the following:

    • under Host information, your Insights Status and Insights API Status are both NOT CONNECTED,
    • your License information section will show ERROR and details will say that your are “Unable to connect to the license server” and
    • your System health section will show OFFLINE.
      
      

    Under the License information section, click on Upload license and pick the license file you received from your SSIMWAVE representative. Shortly after successfully loading the license, the Host page should refresh and your license should show as ACTIVE and your system health as ONLINE. If this is the case for you, feel free to jump to the next section Acessing Video Assets.

    Important

    It may take a minute for all the services to fully recognize the new license. If your system health reports OFFLINE even after uploading your license, click the Test host connection button in the Host information panel once every 10s until your system reports ONILNE. If your system health remains OFFLINE for more than a few minutes, you should expand the section to see the services that are not configured or responding as expected and reach out to your SSIMWAVE representative for help.

    If you’re interested, you can expand the System health section and click on Show all services to verify that the services that were previously OFFLINE (i.e. NOT_READY) in the step above are now ONLINE (i.e. READY). Additionally, you can expand the License information section to verify that the details of your feature license match with your expectations.

Bare-Metal/Other (~ 25 mins)

1. Extract the SSIMPLUS® VOD Monitor archive, containing the Kubernetes cluster, deployment and service descriptors, to an empty folder using the following command:
   tar -zxf ssimwave-vodmonitor-production-MAJOR.MINOR.PATCH-BUILD.tar.gz
   where MAJOR, MINOR, PATCH and BUILD represent the major, minor, patch and build numbers of the desired build.
   
   

2. Create the desired installation namespace <NAMESPACE> in your SSIMWAVE cluster.

   kubectl create namespace <NAMESPACE>
   

   Important

   Pick an all lowercase namespace that represents your organization and site, separated by dashes (refer to the organization and site names in your VOD Monitor feature license file).
   CompanyX with a site of VOD Monitor Production, for example, would use a namespace of companyx-vod-monitor-production.

3. (Optional) SSIMPLUS® Analyzer is capable of producing device-adaptive scores for a multitude of devices. To choose a list of default devices that are used in absence of any per-analysis choices, edit the YAML file vodmonitor/vodmonitor.yaml and change the devices list under analyzer-config-map to suit your needs, an example of which is shown below:

      kind: ConfigMap
      metadata:
        name: analyzer-config-map
        namespace: "{namespace}"
        labels:
          app: ssimwave.vodmonitor.restapi
          provider: SSIMWAVE
      data:
        config.json: |-
          {
            "devices": [
              "ssimpluscore",
              "ipad2021pro12.9",
              "imac27inch",
              "macbookpro16.2inch",
              "iphone13promax",
              "oled65c9pua"
            ],
            "jpeg2000DecodeThreads": -1
          }
   

   Note

   The example shown above uses commonly chosen devices that represent one device per category (i.e. tablet, monitor, laptop, smartphone, TV) and should be suitable for most customers. For details on all supported devices and their respective codes, please see the Scoring Devices section under SSIMPLUS® Analyzer Configuration of the REST API.

   Note that users can always choose to override the default devices used here and specify their own devices on a per-analysis basis by supplying them in the analyzer configuration of the request body (or using the Insights VOD Monitor App).

4. Adjust your image cache to use a persistent volume (PV) of your choice.

   The Analyzer Cluster REST API creates and maintains a writable image cache to store the frames and/or maps created when using the frame capture endpoints. By default, the YAML shipped configures the cache using a local volume, as shown below:

       - apiVersion: v1
         kind: PersistentVolume
         metadata:
           name: vod-frameservices-cache-pv
           namespace: "{namespace}"
           labels:
             app: vod-frameservices
             cluster: SSIMWAVE
             provider: SSIMWAVE
             type: local
             version: v1
         spec:
           accessModes:
           - ReadWriteMany
           capacity:
             storage: 250Gi
           hostPath:
             path: /tmp
           storageClassName: image-cache
           volumeMode: Filesystem
       - apiVersion: v1
         kind: PersistentVolumeClaim
         metadata:
           name: vod-frameservices-cache-pvc
           namespace: "{namespace}"
           labels:
             app: vod-frameservices
             cluster: SSIMWAVE
             provider: SSIMWAVE
             version: v1
         spec:
           resources:
             requests:
               storage: 250Gi
           accessModes:
           - ReadWriteMany
           selector:
             matchLabels:
               app: vod-frameservices
               pv: vod-frameservices-cache-pv
           storageClassName: image-cache
           volumeMode: Filesystem
           volumeName: vod-frameservices-cache-pv
   

   Generally speaking, local volumes (i.e. using hostPath) are not advisable for multi-node clusters and you are strongly encouraged to change the vod-frameservices-cache-pv Kubernetes Persistent Volume (PV) and vod-frameservices-cache-pvc Kubernetes Persistent Volume Claim (PVC) to PV and PVC choices, respectively, that are better suited to multi-node clusters before deploying into a production environment. Refer here for an example on how to use a Network File System (NFS) share. Currently, the image cache must reside on a file system storage device, as opposed to object storage (i.e. S3). The SSIMPLUS® Analyzer Cluster should support any Kubernetes volume or filesystem that can be mounted and shared for multiple read and write (i.e. ReadWriteMany) across all nodes in the cluster.
   
   

5. Add a Kubernetes Ingress.

   By default, the YAML shipped with the product configures the Analyzer Cluster REST API as a ClusterIP service. For a production deployment, it is preferred to use a Kubernetes Ingress to provide external access to the REST API service. Ingresses have the additional benefits of providing load balancing, SSL termination and name-based virtual hosting.

   To add a TLS-secured Kubernetes Ingress to your deployment using the nginx Ingress controller, you can do the following:

   1. Install the nginx Helm repository:

      helm repo add nginx-stable https://helm.nginx.com/stable
      

   2. Create a new namespace for the nginx controller and install it:

      kubectl create namespace nginx-ingress
      helm install vod-monitor-ingress nginx-stable/nginx-ingress -n nginx-ingress
      

      
      

   Now you can create your Kubernetes Ingress by copying the following into the new file vodmonitor/analyzer-ingress.yaml:

       apiVersion: networking.k8s.io/v1
       kind: Ingress
       metadata:
         name: analyzer-ingress
         annotations:
           nginx.ingress.kubernetes.io/proxy-connect-timeout: "600"
           nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
           nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
           nginx.ingress.kubernetes.io/client-header-timeout: "600"
           nginx.ingress.kubernetes.io/client-body-timeout: "600"
           nginx.ingress.kubernetes.io/keep-alive: "600"
           nginx.ingress.kubernetes.io/enable-cors: "true"
           nginx.ingress.kubernetes.io/cors-allow-origin: "*"
           nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST, PATCH, OPTIONS, DELETE"
           nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,X-CustomHeader,X-LANG,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,X-Api-Key,X-Device-Id,Access-Control-Allow-Origin"
           kubernetes.io/ingress.class: nginx 
       spec:
         tls:
         - hosts:
             - <ingress_hostname>
           secretName: analyzer-ingress-secret
         rules:
           - host: <ingress_hostname>
             http:
               paths:
                 - path: "/"
                   pathType: Prefix
                   backend:
                     service:
                       name: http-reverse-proxy
                       port:
                         name: http-rev-proxy
                 - path: "/api/vod"
                   pathType: Prefix
                   backend:
                     service:
                       name: vod-analyzer-rest-api
                       port:
                         number: http
   

   where <ingress_hostname> is the fully-qualified domain name you wish to assign your Ingress.
   

   To secure the Analyzer REST API service using TLS and a self-signed certificate, follow the instructions below:

   1. Obtain your identity certificate or create a self-signed certificate:

      openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ingress.key -out ./ingress.crt -subj "/CN=<ingress_hostname>/O=<ingress_hostname>"
      

      
      
   2. Create a Kubernetes TLS secret from the the (public) certificate and (private) key values created above:

      kubectl create secret tls analyzer-ingress-secret --key=./ingress.key --cert=./ingress.crt
      

      
      

   Finally you can apply the Kubernetes Ingress using the command below:

   kubectl apply -n <NAMESPACE> -f ./vodmonitor/analyzer-ingress.yaml
   

   
   

6. Import the SSIMPLUS® Analyzer Cluster Docker images to your local Docker registry.

   For security reasons, many, if not most, customer on-prem/VPC Kubernetes clusters will not have open-ended access to SSIMWAVE’s GCR Docker image repository (i.e. gcr.io/ssimwave-vodmonitor). Instead, you will be looking to perform a docker pull/tag/push combination in order to fetch and store the SSIMPLUS® Analyzer cluster Docker images in your own private/local Docker registry. To aid you in this endeavor, SSIMWAVE has included a BASH script named setup-for-k8s.sh inside the deployment archive you exploded in step 1. To use the script, you must be working from a machine that has both HTTPS (port 443) access to gcr.io/ssimwave-vodmonitor as well HTTP/HTTPS access to your on-prem/VPC container registry.

   From a Linux CLI, update your Docker instance with the login data for SSIMWAVE’s GCR:

   cat <keyfile.json> | docker login -u _json_key --password-stdin https://gcr.io
   

   where <keyfile.json> is the SSIMWAVE GCR service account JSON key file you received as part of the Installation Prerequisites.
   
   

   Note

   If you are using gcloud and your docker is configured to use credential helpers for gcr.io, you will likely need to execute the following command:
   gcloud auth activate-service-account --key-file=<keyfile.json>

   From within the directory where you exploded the deployment archive, issue the following command:

   ./setup-for-k8s.sh -d "<your_repo/vodmonitor>" -n <NAMESPACE>
   

   where <your_repo/vodmonitor> is the location of your on-prem/VPC Docker registry that will serve as the target for the images and <NAMESPACE> is the namespace to install into.

   The script will automatically pull all the SSIMPLUS® Analyzer Cluster Docker images from the SSIMWAVE GCR repository, tag them with the new location (i.e. <your_repo/vodmonitor>) and then push them up to your on-prem/VPC Docker registry. The script also modifies all the image references in the YAML (i.e. vodmonitor/vodmonitor.yaml) for these new locations.

   If you have problems with the script or require further assistance, please contact your SSIMWAVE representative.

   Important

   For security reasons, your JSON key will only work for a limited time (i.e 2 weeks). If your key has expired, the script above will fail with connection errors. You can get a new JSON key by contacting your SSIMWAVE representative.

7. Deploy the SSIMPLUS® Analyzer cluster by executing the following command:
   kubectl apply -f ./vodmonitor/vodmonitor.yaml

   If you see errors on the CLI after applying the YAML descriptors or your pods appear to have errors (check using kubectl get pods), please review the content for the following:

   • YAML is properly formatted
   • JSON you altered or added is properly formed (i.e. you didn’t forget to add a comma to a previous line when adding a new line, etc.)
   • Image location references (i.e. image: XXX) are properly pointing to your local Docker repository
   • Your features license (features.lic) has been properly copied/applied in the YAML (spaces and formatting are accurate)
   • Your image cache PV and PVC are properly configured
   • Required role-based access (RBAC) specifications are allowed in your Kubernetes cluster (see RBAC in vodmonitor/vodmonitor.yaml)
     
     

8. Modify the VOD API Host setting in your Insights account.

   The VOD API Host value associated with your SSIMWAVE Insights account is used to redirect your browser to fetch frame images/maps as part of performing an in-depth inspection of a given result. For this functionality to work, you need to configure this value to match the hostname/FQDN associated with your SSIMPLUS® Analyzer Cluster which will be the same as your <ingress_hostname> in this deployment scenario (see step 5).
   

   1. Login to your Insights Account.
   2. Click on the user icon in the top right corner of the UI and pick Account from the dropdown menu.
   3. Scroll down to the Additional Details section and change your VOD Api Host value to match the FQDN associated with your ingress (i.e. <ingress_hostname>).
   4. Click Save.
      
      
   Important

   All users of SSIMPLUS® VOD Monitor will need to make this same adjustment to their VOD API Host setting under their Insights account.

9. Upload your feature license.

   To finish the system configuration, you must now apply your feature license. Using your browser, navigate to the Host page in your Insights account, where you will be presented with the information on your current host. Here you will see the following:

   • under Host information, your Insights Status and Insights API Status are both NOT CONNECTED,
   • your License information section will show ERROR and details will say that your are “Unable to connect to the license server” and
   • your System health section will show OFFLINE.
     
     

   Under the License information section, click on Upload license and pick the license file you received from your SSIMWAVE representative. Shortly after successfully loading the license, the Host page should refresh and your license should show as ACTIVE and your system health as ONLINE. If this is the case for you, feel free to jump to the next section Acessing Video Assets.

   Important

   It may take a minute for all the services to fully recognize the new license. If your system health reports OFFLINE even after uploading your license, click the Test host connection button in the Host information panel once every 10s until your system reports ONILNE. If your system health remains OFFLINE for more than a few minutes, you should expand the section to see the services that are not configured or responding as expected and reach out to your SSIMWAVE representative for help.

   If you’re interested, you can expand the System health section and click on Show all services to verify that the services that were previously OFFLINE (i.e. NOT_READY) in the step above are now ONLINE (i.e. READY). Additionally, you can expand the License information section to verify that the details of your feature license match with your expectations.