VOD Monitor is a highly available and scalable solution to measure viewer experience of file based content from creation to consumption. Our two-time Emmy® award-winning solution uses the most accurate, complete and advanced technologies to mimic human perception of video content in the form of a SSIMPLUS® score. The score traces viewer experiences across a VOD workflow to measure drops at various stages. The solution empowers users to make critical decisions when viewer experience does not meet expectations of key stakeholders, including end-viewers. The result is a reduced mean time to resolution by an order of magnitude.

Other capabilities include:

• Pinpoints issues at various stages of a VOD workflow
• Detailed understanding of preservation of creative intent
• Flexible reports and APIs to consume actionable data
• Plug and play implementation of pass/fail approaches
• Consistent performance across all content types and impairments
• An order of magnitude faster than competing technologies
• Support for advanced High Dynamic Range (HDR) workflows
• Comparison across content providers on library, asset, and scene basis
• Comparison across encoders and playback implementations
• Quality Checks for various video, audio, and close caption anomalies

This production deployment model is combination of a software-as-a-service (SaaS) and the SSIMPLUS® Analyzer Cluster - VPC deployment models. The architecture follows the VPC model in that both the SSIMPLUS® Analyzer Cluster and all customer video assets are kept within the customer’s AWS account but, as with a traditional SaaS offering, the AWS resources and services required to support the SSIMPLUS® Analyzer Cluster are all provisioned and configured by SSIMWAVE, with only minimal interaction required on the customer’s part. This hands-off or turnkey approach applies equally to the deploying, managing, monitoring and upgrading of the SSIMPLUS® software as well. This solution is recommended for those AWS customers that are not interested in the work of maintaining a production EKS cluster.

In reference to the AWS architecture diagram above, please note the following:

• Customer Deployer is an AWS-knowledgeable customer representative who is responsible for executing the CloudFormation templates that are authored and maintained by SSIMWAVE. These templates are executed as part of the system’s deployment instructions and exist in order to prepare and configure the customer’s AWS account for the successful installation, functioning and on-going maintenance of the SSIMPLUS® Analyzer Cluster. From a security perspective, let’s take a closer look at the IAM roles and policies created by SSIMWAVE’s CloudFormation templates:

  • The ssimplus-vod-monitor-managed-service-deployment-prerequisites template is responsible for creating the following IAM policies and role:
    

    • ssimplus-vod-monitor-managed-service-policy

      This policy is the minimum set of permissions required in order to create and update the SSIMPLUS® Analyzer Cluster as an AWS EKS cluster. SSIMWAVE uses Weaveworks eksctl to install and configure the cluster.
      
      

    • ssimplus-vod-monitor-managed-service-role

      This role realizes the ssimplus-vod-monitor-managed-service-policy above and exists solely to establish a trust relationship with the customer-management-role in SSIMWAVE’s VPC (see diagram above). Because SSIMWAVE is responsible for the creation, maintenance and upgrading of the EKS cluster, this role is required in order to give SSIMWAVE the necessary permissions within the customer’s VPC.

      Important

      Please take note that the ssimplus-vod-monitor-managed-service-role and the ssimplus-vod-monitor-managed-service-policy do not have permission to access any customer video assets stored in Amazon S3.

    • AmazonEKS_EFS_CSI_Driver_Policy

      This policy is minimum set of permissions required in order to install the Amazon EFS CSI driver, which is used solely by the SSIMPLUS® Analyzer Cluster in order to create an EFS filesystem to store the frames and maps generated as part of an analysis (see diagram above).
      
      

  • The ssimplus-vod-monitor-managed-service-s3-read-only-role template is responsible for creating the following IAM role:
    

    • ssimplus-vod-monitor-managed-service-s3-read-only-role

      This role exists for two reasons:

      1. to realize all of the individual read-only S3 bucket policies created by the ssimplus-vod-monitor-managed-service-add-s3-bucket template and
      2. to bind to the SSIMPLUS® Analyzer Cluster’s OIDC, which uses AWS STS to provide the cluster with read-only access to the S3 buckets holding customer video assets (see diagram above).
         
         
      Important

      Please take note that the ssimplus-vod-monitor-managed-service-s3-read-only-role does not have any trust relationship with the ssimplus-vod-monitor-managed-service-role and, as such, read-only access to customer S3 assets is not provided to anything outside of the customer’s VPC.

  • The ssimplus-vod-monitor-managed-service-add-s3-bucket template is executed for every S3 bucket that the customer wishes to use with the SSIMPLUS® Analyzer Cluster. Each execution of the templates produces an IAM policy (i.e. ssimplus-vod-monitor-managed-service-s3-policy-<bucket_name>) that allows for read-only access to the given S3 bucket and then attaches that policy to the ssimplus-vod-monitor-managed-service-s3-read-only-role discussed above (see diagram).
    
    

• SSIMWAVE Support is an AWS and VOD Monitor knowledgeable SSIMWAVE representative who is responsible for creating, configuring, managing and upgrading the SSIMPLUS® Analyzer Cluster. In order to effectively achieve these tasks, SSIMWAVE Support assumes a role within the SSIMWAVE VPC that is unique and specific to the customer (i.e. customer-management-role in the diagram above). This role, in turn, is configured to assume the ssimplus-vod-monitor-managed-service-role, created by the Customer Deployer when executing the CloudFormation scripts.
  
  

• The architecture above is specifically designed to ensure that customer video assets never leave the customer’s VPC, either in whole or in part. Read-only access to customer assets is provided on a per-S3 bucket basis and granted only to the SSIMPLUS® Analyzer Cluster, itself. Frames and maps generated as part of in-depth inspection are stored in an encrypted Amazon EFS filesystem within the customer’s VPC.
  
  

• SSIMPLUS metrics and metadata are the only encrypted data that leave the customer VPC for SSIMWAVE’s Insights platform. Since Insights is also hosted on Amazon AWS, the architecture above uses AWS VPC Endpoint services to ensure that the data streamed to Insights stays wholly within the AWS infrastructure and is never sent over the Internet.

  Note

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

Please refer to the SSIMPLUS® Analyzer Cluster - AWS Managed Service for deployment details.

In this production deployment model, SSIMWAVE makes available the software components that comprise the SSIMPLUS® Analyzer Cluster so that they can be deployed into a virtual private cloud (VPC) controlled by the customer (see SSIMPLUS® Analyzer Cluster - VPC deployment guide). The Analyzer Cluster makes use of industry standard containerization and platform technologies, such as Docker and Kubernetes, to facilitate deployment into any compatible on-prem or private cloud environment. This approach is recommended for those non-AWS customers that have both the human and computing resources necessary to support the SSIMPLUS® Analyzer Cluster. As with the most other deployment models, access to the SSIMPLUS® Analyzer Cluster is achieved via the provided REST API.

Some customers may wish to deploy the SSIMPLUS® Analyzer into an AWS Elastic Cloud Compute (EC2) instance. Typically, this deployment strategy is used for trials or lab usage of the product where the customer is also an AWS customer and their video assets are already stored in S3 buckets. To support this usage scenario, SSIMWAVE provides an Amazon Machine Image (AMI) which contains a full deployment of SSIMPLUS® VOD Monitor that can be deployed to the customer’s AWS account by following a short number of installation instructions. The caveat to this deployment model is that the system is constrained in its ability to scale by the hardware resources allocated to the given EC2 instance. For trial usage, however, concurrent, high-volume processing of video assets isn’t usually a priority.

To deploy the SSIMPLUS® Analyzer virtual machine, please follow the deployment instructions here.

Some customers may wish to deploy the SSIMPLUS® Analyzer to a bare metal server or on-prem virtual machine orchestrator (i.e. VMWare EsXI). Typically, this deployment strategy is used for trials of the product or lab installations where the goal is to stand up an instance of SSIMPLUS® VOD Monitor quickly and with a minimum of effort. The caveat to this deployment model is that the system is constrained in its ability to scale and achieve high availability by the hardware resources of the hosting machine. For trials and lab usage, however, concurrent, high-volume processing of video assets in a 24/7 environment isn’t usually a priority.

SSIMWAVE can provide a virtual machine in the form of an Open Virtual Appliance (OVA) or a QEMU (QCOW2) container which contains a full deployment of SSIMPLUS® VOD Monitor that is pre-configured to work with only a few steps of additional installation instructions.

To deploy the SSIMPLUS® Analyzer virtual machine, please follow the deployment instructions here.

Some customers may have specific deployment needs or concerns that do not align with the AWS, virtual machine or Kubernetes-based deployment models described herein. Consider these scenarios:

• A customer is using a proprietary container management system that is incompatible with the Kubernetes design supported in the VPC model and would like to integrate the SSIMPLUS® Analyzer technology into this alternative environment while still benefiting from the power of the Insights data platform.
  
  
• A customer is using a vendor that offers an alternative and/or proprietary container management system, for value-added reasons, and would like SSIMWAVE to work with the vendor to deploy into this environment.

Still other customers may want to “kick the tires” on the VOD Monitor Product and don’t yet have a need for the volume processing available with the SSIMPLUS® Analyzer cluster. For all such cases described above, SSIMWAVE provides access to a Docker image of the SSIMPLUS® Analyzer, which can be pulled and pushed into any local Docker registry and invoked from a CLI or other compatible tooling.

Customers that would like to create a SSIMPLUS® Analyzer cluster in a proprietary/alternative container management system are encouraged to contact their SSIMWAVE representative directly in order to discuss how to design a custom deployment that meets their needs. Because SSIMWAVE is a 100% software solution, we have the flexibility to support both custom and industry-standard container management systems.

To deploy the SSIMPLUS® Analyzer as a Docker image, please follow the deployment instructions here.

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

The SSIMPLUS® Analyzer Cluster can work with video assets exposed in any one of the three following ways:

1. AWS Simple Storage Service (S3)
2. Kubernetes Persistent Volume (PV)
3. HTTP Live Streaming (HLS)

Assets in AWS S3

There are three ways to access assets in an S3 bucket via the SSIMPLUS® Analyzer REST API:

1. Client/Secret

   Requires that the S3 bucket key id and access key be passed in clear text to the REST API.
   
   

2. Kubernetes Secret

   Requires creating a Kubernetes secret with field values for the bucket name, key id and access key and whose name follows the pattern s3secret-<s3_bucket_name>, where <s3_bucket_name> is the name of the S3 bucket. You should use the /s3AccessSecret endpoint on the SSIMPLUS® Analyzer REST API to create a conformant secret.
   
   

3. Assumed AWS Identity and Access Management (IAM) Role

   Requires creating an AWS IAM role, which is assigned the necessary read-only privileges to the S3 bucket, and then associating it with a Kubernetes service account.

Adding S3 Buckets to EKS using IAM (~ 15 mins)

1. Follow the instructions in Providing access to video assets in S3 under the Post Installation section of the AWS Managed Service deployment guide.
   
   

2. Using the ARN of the created IAM ssimplus-vod-monitor-managed-service-s3-read-only-role role, annotate the default service account as follows:

   kubectl --context arn:aws:eks:<region>:<accountID>:cluster/SSIMPLUS-VOD-Monitor \
       -n <namespace> annotate sa default \
       eks.amazonaws.com/role-arn=arn:aws:iam::<accountID>:role/ssimplus-vod-monitor-managed-service-s3-read-only-role
   

   where:
   <region> is the target region for your EKS cluster,
   <accountID> is the target AWS account ID and
   <namespace> is the namespace into which you deployed the SSIMPLUS® Analyzer Cluster.
   
   At this point, your SSIMPLUS® Analyzer Cluster should be able to read video assets from your S3 bucket(s).

Assets in a Persistent Volume (PV) (~ 5 mins)

To use a storage device represented by a Kubernetes Persistent Volume (PV), both the PV and the Persistent Volume Claim (PVC) must be first applied to the Kubernetes cluster. The name applied to the PVC will be required when submitting analyses via the SSIMPLUS® Analyzer REST API.

NFS Example

Here are examples of an NFS PV and corresponding PVC:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: video-files-pv
spec:
  capacity:
    storage: 200Gi
  accessModes:
    - ReadOnlyMany
  nfs:
    server: nfs-server.default.svc.cluster.local
    path: "/"

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: video-files-pvc
  labels:
    app: video-files
spec:
  accessModes:
    - ReadOnlyMany
  volumeName: video-files-pv
  storageClassName: "video-files"
  resources:
    requests:
      storage: 200Gi
  selector:
    matchLabels:
      app: video-files

With regards to the SSIMPLUS® Analyzer Cluster itself, there is no additional setup or configuration required to use assets in HLS.

Now that the SSIMPLUS® VOD Monitor 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://<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 bare-metal/other deployments, <cluster_hostname> will the same as your <ingress_hostname>.
For AWS EKS deployments, the <cluster_hostname> will be the FQDN established in your AWS Route 53.

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.

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.
  
  

• SSIMPLUS® VOD Monitor 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 import the SSIMPLUS® VOD Monitor 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 strongly encouraged to use the same region as the S3 buckets holding your video assets, otherwise you may be subject to 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,
   • modify network ACLs on a VPC and
   • create IAM policies and roles.
     
     

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/preferred list of hardware resources:

   1. 96GiB/128GiB memory
   2. 48/64 vCPU
   3. 250G of SSD disk space

   
   The minimum/preferred requirements above would dictate using a c5.12xlarge/c5.18xlarge or c5a.12xlarge/c5a.16xlarge instance type with a 250GB attached EBS volume (General Purpose SSD - gp3). Selecting the larger/preferred EC2 instance type, will allow your instance to process more content simultaneously and analyses that are more complex to decode (i.e. 4K, Dolby Vision, ProRes, JPEG 2000) may complete faster. If you have questions about alternative EC2 instance types, please contact your SSIMWAVE representative.
   

   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 SSIMPLUS® VOD Monitor 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. Choose Services -> Security, Identity & Compliance -> IAM.
   
   

3. Create a new IAM role for read-only access to the S3 bucket(s) that contain your video assets.

   • Use AWS service as the trusted entity

   • Use EC2 - Allows EC2 instances to call AWS services on your behalf as the use case.

   • Create a new policy with the following details:

     • Service: S3
     • Actions: ListBucket, GetObject and GetBucketLocation
     • Resources:
       • bucket: use the ARN for your S3 bucket (e.g. arn:aws:s3:::ssimwave-video-assets)
       • object: use the ARN for your S3 bucket and allow any object (e.g. arn:aws:s3:::ssimwave-video-assets/*)

     
     The JSON for your policy should look similar to the following:

     {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Sid": "VODReadOnly",
           "Effect": "Allow",
           "Action": [
             "s3:GetObject",
             "s3:ListBucket",
             "s3:GetBucketLocation"
           ],
           "Resource": [
             "arn:aws:s3:::ssimwave-video-assets",
             "arn:aws:s3:::ssimwave-video-assets/*"
           ]
         }
       ]
     }
     

     
     
     Important

     Be careful to assign the permissions above only to the resources (i.e. S3 buckets) that contain the video assets you wish to use with SSIMPLUS® VOD Monitor.

     If your S3 bucket is using a custom AWS KMS key to encrypt your video assets at rest within your S3 bucket(s), then you will need to allow the role you create here to also use the key to decrypt the contents by editing the policy associated with the key as shown below:

     {
       "Statement": [
         {
           "Sid": "VODKeyAccess",
           "Effect": "Allow",
           "Action": [
             "kms:Decrypt",
             "kms:GenerateDataKey"
           ],
           "Principal": {
             "AWS": "arn:aws:iam::<accountId>:role/<role_name>"
           },
           "Resource": "*"
         }
       ]
     }
     

     where <accountId> and <role_name> match your AWS account ID and the role name you are creating in this step.
     
     

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

5. 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 SSIMPLUS® VOD Monitor

   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 SSIMPLUS® VOD Monitor 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 SSIMPLUS® VOD Monitor 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.

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

7. Find the SSIMPLUS® VOD Monitor 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
   
   

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

9. Name the instance accordingly (i.e. SSIMPLUS VOD Monitor <version>).
   
   

10. Select the EC2 instance type desired.

    The recommended instance type is c5.18xlarge/c5a.16xlarge.
    

    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.

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

12. 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)
       
       

13. Add a 250GB general purpose SSD (gp3) EBS volume.

    This storage volume is used to cache any frame captures, banding, quality and/or color volume difference maps generated as part of your usage. As this device will be used for storing frames of potentially proprietary/sensitive content, you should feel free to add at-rest encryption to this volume.
    
    

14. Configure the Advanced Details section as follows:

    1. IAM instance profile -> Choose the IAM role you created above (step 3) that provides read permission to the S3 bucket containing your video assets.
       
       

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

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

17. Select the EC2 instance that you launched for the SSIMPLUS® VOD Monitor AMI from the list.
    
    

18. 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 SSIMPLUS® VOD Monitor with their own Insights account, will need to make this same adjustment to their VOD API Host setting under their Insights account.

19. Verify that your SSIMPLUS® VOD Monitor 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 SSIMPLUS® VOD Monitor 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 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.

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

Upgrading Versions (~ 25 mins)

Upgrading to a new version of the SSIMPLUS® VOD Monitor 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 SSIMPLUS® VOD Monitor instance.
   
   
4. Choose Instance state -> Terminate instance from the dropdown menu.
   
   
5. Follow the Installation instructions above for the new SSIMPLUS® VOD Monitor AMI.

Once the SSIMPLUS® VOD Monitor 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",
                "credentials": {
                  "useAssumedIAMRole": true
                }
            },
            "path": "royalty_free/rocket_launch/outputs"
        }
    ],
    "analyzerConfig": {
      "enableBandingDetection": true
    }
}'

Once you have successfully deployed and verfied that your SSIMPLUS® VOD Monitor AMI 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 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 trial/lab 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 SSIMPLUS® Analyzer 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 SSIMPLUS® Analyzer 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.

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.

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 trial/lab 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. 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.
      
      

2. Your target machine is using 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
   • net-tools
     
     

3. Your target machine has the Docker engine installed.
   
   

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

   • Docker registry: gcr.io/ssimwave-vodmonitor
     
     

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

   If your installation machine is required to use a SOCKS5 or HTTP forward proxy to reach the IP addresses listed above, you must install and use the Insights Proxy.

6. (Optional) Deploy the Insights Proxy.
   
   

7. Read about SSIMWAVE’s Insights data platform and create an account to access results.

1. From a Linux CLI, use docker to log in to SSIMWAVE’S Google Container Registry (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>

2. Pull the SSIMPLUS® Analyzer image to your local Docker repository:
   docker pull gcr.io/ssimwave-vodmonitor/analyzer:MAJOR.MINOR.PATCH-BUILD
   where MAJOR, MINOR, PATCH and BUILD represent the major, minor, patch and build numbers of the desired build. Now use docker tag and docker push to register this image in your on-prem Docker registry.
   
   

3. Save the features.lic features license file, distributed to you by SSIMWAVE, to your local storage (i.e. /ssimwave/features.lic).
   
   

4. (Insights Proxy only) Create an analyzer config.json file (i.e. /ssimwave/config.json) to include the IP address and port of your Insights Proxy as follows:
   

       {
           "insights_proxy": "<insights_proxy_address>:<insights_proxy_port>"
       }
   

   If you did not change/customize the ports on your proxy, then the value to use for your <insights_proxy_port> above will be 9800. The system will automatically discover and use the rest of the ports (i.e. 9801-9804).
   
   

5. (Optional) SSIMPLUS® Analyzer is capable of producing device-adaptive scores for a multitude of devices. To select the devices you wish to use, create/edit your analyzer’s config.json file and change the devices list as follows:
   

       {
           "devices": [
               "ipad2017",
               "xl2420t",
               "macbookpro",
               "iphonex",
               "oled65c9pua"
           ],
           "licenseServer": "<ssimwave_customer_license_server>",
           .
           .
           .
       }
   

   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 appropriate for most customers. For details on all supported devices and their respective codes, please see the Scoring Devices section under SSIMPLUS® Analyzer Configuration. As of v2.11.0, you can choose devices on a per-analysis basis by supplying them in the request body.

6. Mount the file shares that host the video assets you wish to make available to the SSIMPLUS® Analyzer (see Mounting Network Drives)

Starting a new analysis is done by running the SSIMPLUS® Analyzer image using the docker program, which creates a SSIMPLUS® Analyzer container. In order to successfully run the Analyzer image, you will need to mount the following 3 things:

1. config.json (mounted to /opt/ssimwave/vodmonitor/etc),
2. features.lic (mounted to /opt/ssimwave/vodmonitor/etc),
3. video asset folders (mounted anywhere you want).

Docker lets you mount files and folders using the --mount argument.

Please consult the SSIMPLUS® Analyzer Configuration section for details on how to configure the SSIMPLUS® Analyzer when using the Docker image.

Executing a Full-Reference Analysis

In the example below, we start a SSIMPLUS® Analyzer v2.21.0-25 container in full-reference mode, configured using /opt/ssimwave/vodmonitor/etc/config.json, licensed using /opt/ssimwave/vodmonitor/etc/features.lic and passing a reference and subject asset from the mounted folder /videos:

docker run --rm \
  --mount src=/ssimwave/config.json,target=/opt/ssimwave/vodmonitor/etc/config.json,type=bind \
  --mount src=/ssimwave/features.lic,target=/opt/ssimwave/vodmonitor/etc/features.lic,type=bind \
  --mount src=/mnt/NAS/videos,target=/videos,type=bind \
  gcr.io/ssimwave-vodmonitor/analyzer:2.21.0-25 \
  --content-metadata "{\"title\": \"Content title goes here\"}" \
  --temporal-alignment 1 \
  --ref-video /videos/ref.mp4 --test-video /videos/test.mp4

• mounts /ssimwave/config.json to /opt/ssimwave/vodmonitor/etc/config.json
• mounts /ssimwave/features.lic to /opt/ssimwave/vodmonitor/etc/features.lic
• mounts the video folder /mnt/NAS/videos/ to /videos

Executing a No-Reference Analysis

To run a no-reference analysis, we simply omit the --ref-video option, as shown below:

docker run --rm \
  --mount src=/ssimwave/config.json,target=/opt/ssimwave/vodmonitor/etc/config.json,type=bind \
  --mount src=/ssimwave/features.lic,target=/opt/ssimwave/vodmonitor/etc/features.lic,type=bind \
  --mount src=/mnt/NAS/videos,target=/videos,type=bind \
  gcr.io/ssimwave-vodmonitor/analyzer:2.21.0-25 \
  --content-metadata "{\"title\": \"Content title goes here\"}" \
  --test-video /videos/test.mp4

Specifying a Custom Analysis UUID

In the examples above, we are relying on the SSIMPLUS® Analyzer to automatically generate a UUID to associate with the analysis. Optionally, you may find it more useful to generate the UUID in advance and pass this to the Analyzer container via a command line argument. In this manner, the caller/integrator can immediately use the UUID for other activities in their workflow, such as to fetch the current status of the analysis from Insights. To use your own generated UUID, you can use the Linux uuidgen command (or a compatible equivalent) to generate a UUID, save it to an environment variable and pass that variable to the SSIMPLUS® Analyzer as follows:

ANALYSIS_ID=$(uuidgen)
docker run --rm \
  --mount src=/ssimwave/config.json,target=/opt/ssimwave/vodmonitor/etc/config.json,type=bind \
  --mount src=/ssimwave/features.lic,target=/opt/ssimwave/vodmonitor/etc/features.lic,type=bind \
  --mount src=/mnt/NAS/videos/,target=/videos,type=bind \
  gcr.io/ssimwave-vodmonitor/analyzer:2.21.0-25 \
  --id ${ANALYSIS_ID} \
  --content-metadata "{\"title\": \"Content title goes here\"}" \
  --temporal-alignment 1 \
  --ref-video /videos/ref.mp4 --test-video /videos/test.mp4

Using Raw Video Assets

If your reference and/or test asset is in YUV or raw format, you must use the --ref-raw-params and/or --test-raw-params to send the required raw video parameters through to the SSIMPLUS® Analyzer, as shown below:

ANALYSIS_ID=$(uuidgen)
docker run --rm \
  --mount src=/ssimwave/config.json,target=/opt/ssimwave/vodmonitor/etc/config.json,type=bind \
  --mount src=/ssimwave/features.lic,target=/opt/ssimwave/vodmonitor/etc/features.lic,type=bind \
  --mount src=/mnt/NAS/videos,target=/videos,type=bind \
  gcr.io/ssimwave-vodmonitor/analyzer:2.21.0-25 \
  --id ${ANALYSIS_ID} \
  --content-metadata "{\"title\": \"Content title goes here\"}" \
  --temporal-alignment 1 \
  --ref-video /videos/ref.yuv \ 
  --ref-raw-params '{"width": 1920, "height": 1080, "fps": 24, "pixel_format": "yuv420p"}' \ 
  --test-video /videos/test.mp4

The SSIMPLUS® Analyzer supports the following raw video parameters:

Using HDR10 Assets

If your reference and/or test asset contains HDR10 content, you must use the --hdr option to when running the SSIMPLUS® Analyzer, as shown below:

ANALYSIS_ID=$(uuidgen)
docker run --rm \
  --mount src=/ssimwave/config.json,target=/opt/ssimwave/vodmonitor/etc/config.json,type=bind \
  --mount src=/ssimwave/features.lic,target=/opt/ssimwave/vodmonitor/etc/features.lic,type=bind \
  --mount src=/mnt/NAS/videos/,target=/videos,type=bind \
  gcr.io/ssimwave-vodmonitor/analyzer:2.21.0-25 \
  --id ${ANALYSIS_ID} \
  --content-metadata "{\"title\": \"Content title goes here\"}" \
  --temporal-alignment 1 \
  --hdr \
  --ref-video /videos/ref.mp4 --test-video /videos/test.mp4

Using Region Of Interest

If your reference and/or test asset frames have areas you wish exclude when scoring, you can use the region of interest to instruct the analyzer to consider only a specific rectangular region. The region of interest is specified in pixels, using screen coordinates, where the origin (0,0) is the top left corner of the frame. Consider the example below where both the reference and test are adjusted with a region of interest:

ANALYSIS_ID=$(uuidgen)
docker run --rm \
  --mount src=/ssimwave/config.json,target=/opt/ssimwave/vodmonitor/etc/config.json,type=bind \
  --mount src=/ssimwave/features.lic,target=/opt/ssimwave/vodmonitor/etc/features.lic,type=bind \
  --mount src=/mnt/NAS/videos/,target=/videos,type=bind \
  gcr.io/ssimwave-vodmonitor/analyzer:2.21.0-25 \
  --id ${ANALYSIS_ID} \
  --content-metadata "{\"title\": \"Content title goes here\"}" \
  --temporal-alignment 1 \
  --ref-video /videos/ref.mp4 --test-video /videos/test.mp4 \
  --ref-roi 20:0:400:300 --test-roi 20:0:400:300

The example above puts the origin of the region of interest at (20, 0) and the area extends to cover a rectangular area of 400x300 pixels.

Capturing SSIMPLUS® Content Complexity Scores (CCS)

To run a no-reference analysis and to capture context complexity scores, you would add the --content-complexity switch as shown below:

ANALYSIS_ID=$(uuidgen)
docker run --rm \
  --mount src=/ssimwave/config.json,target=/opt/ssimwave/vodmonitor/etc/config.json,type=bind \
  --mount src=/ssimwave/features.lic,target=/opt/ssimwave/vodmonitor/etc/features.lic,type=bind \
  --mount src=/mnt/NAS/videos/,target=/videos,type=bind \
  gcr.io/ssimwave-vodmonitor/analyzer:2.21.0-25 \
  --id ${ANALYSIS_ID} \
  --content-metadata "{\"title\": \"Content title goes here\"}" \
  --content-complexity \
  --test-video /videos/test.mp4

Capturing SSIMPLUS® Banding Scores (SBS)

To run a full-reference analysis and detect the level of color banding, you would add the --banding switch as shown below:

ANALYSIS_ID=$(uuidgen)
docker run --rm \
  --mount src=/ssimwave/config.json,target=/opt/ssimwave/vodmonitor/etc/config.json,type=bind \
  --mount src=/ssimwave/features.lic,target=/opt/ssimwave/vodmonitor/etc/features.lic,type=bind \
  --mount src=/mnt/NAS/videos/,target=/videos,type=bind \
  gcr.io/ssimwave-vodmonitor/analyzer:2.21.0-25 \
  --id ${ANALYSIS_ID} \
  --content-metadata "{\"title\": \"Content title goes here\"}" \
  --temporal-alignment 1 \
  --banding \
  --ref-video /videos/ref.mp4 --test-video /videos/test.mp4

Color banding can equally be run for no-reference analyses.

Executing Video, Audio and Closed Captions Quality Checks

By default, the SSIMPLUS® Analyzer will perform all the quality checks that your feature license allows for each full-reference and no-reference analysis, using the default configuration values described here. To turn off a given quality check or otherwise configure how it runs, you will want to modify the contents of your Analyzer’s config.json, as described here in the Quality Checks section under SSIMPLUS® Analyzer Configuration.

Checking Status of an Analysis

To check the status (including the real-time progress) of any submitted analysis, please follow the instructions here under the Insights Platform section.

Upon successful execution, the SSIMPLUS® Analyzer container will:

• exit with return code 0
• write the execution results in a JSON document to stdout

Upon faliure, the SSIMPLUS® Analyzer container will:

• exit with non-zero return code
• write error and logging information in a JSON document to stderr

You can separate stdout from stderr using redirects. In the example below, successful results will be written to analysis.json and errors to error.log:

ANALYSIS_ID=$(uuidgen)
docker run --rm \
  --mount src=/ssimwave/config.json,target=/opt/ssimwave/vodmonitor/etc/config.json,type=bind \
  --mount src=/mnt/NAS/videos/,target=/videos,type=bind \
  gcr.io/ssimwave-vodmonitor/analyzer:2.21.0-25 --temporal-alignment 1 \
  --ref-video /videos/ref.mp4 --test-video /videos/test.mp4 \
  --id ${ANALYSIS_ID} 1> analysis.json 2> error.log

Here is the an example of a JSON document written upon successful execution:

{
    "org": "SSIMWAVE",
    "ste": "VOD Testing",
    "analysisId": "9da571b6-2909-4c7f-8e5f-3fb59c1dc756",
    "tId": 1,
    "rId": 1,
    "startTs": 1596569864593,
    "exitCode": 0
}

The analysisId is the UUID for the analysis and is required in order to work with the results stored in the Insights data platform.

If the SSIMPLUS® Analyzer encounters an error before it has started reporting status updates to Insights, the format of the error will be as follows:

{
    "exitCode": 2,
    "description": "the option '--test-video' is required but missing"
}

If an error occurs after reporting the first status update, the format of the error will be as follows:

{
    "org": "SSIMWAVE",
    "ste": "VOD Testing",
    "analysisId": "9da571b6-2909-4c7f-8e5f-3fb59c1dc756",
    "tId": 1,
    "startTs": 1596569864593,
    "exitCode": 1,
    "description": "Cannot open 'does_not_exit.mp4'. No such file or directory"
}

If the SSIMPLUS® Analyzer encounters a fatal error signal (i.e. segfault, out of memory, etc.), the container will exit with a return code in the 129-192 range. In this case, there may or may not be debugging information written to stderr. See Fatal system errors for more details.

Once you have successfully deployed the SSIMPLUS® Analyzer Cluster, you are strongly encouraged to read and consult the Insights data platform sections as they contain crucial details on how to extract meaningful data from your asset analyses.

Mounting drives so the current user has read/write access requires knowing the user’s UID and GID. You can determine it using the Linux id command.

You can find the UID/GUID of the current user by running:

$ id
uid=0(root) gid=0(root) groups=0(root)

You can find the UID/GUID of another user by running id <username> example:

$ id ssimwave
uid=997(ssimwave) gid=995(ssimwave) groups=995(ssimwave)

The example below shows how to mount an Amazon S3 bucket to /mnt/s3 from a shell. Please ensure your S3 bucket has the correct permissions for read/write access.

1. Add your AWS credentials to /etc/passwd-s3fs. Run the command below, substituting AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY for your AWS credentials.
   

   $ sudo su
   $ echo AWS_ACCESS_KEY_ID:AWS_SECRET_ACCESS_KEY | tee /etc/passwd-s3fs
   $ chmod 600 /etc/passwd-s3fs
   

   
   
2. Mount the S3 bucket. Run the command below, substituting SSIMWAVE_GID and SSIMWAVE_UID for the ssimwave user’s UID/GID (see here for UID/GID)
   

   $ mkdir -p /mnt/s3
   $ /usr/bin/s3fs S3_BUCKET_NAME /mnt/s3 -o \ 
   passwd_file=/etc/passwd-s3fs,allow_other,gid=SSIMWAVE_GID,uid=SSIMWAVE_UID
   

The example below shows how to mount a Windows network share to /mnt/NAS from a shell. This may not work for all Windows shares as some have different security requirements.

1. Add your Windows share credentials to a .cifs file in your home directory. Run the command below, substituting USER and PASSWORD for your Windows share credentials.
   

   $ echo "username=USER
   $ password=PASSWORD" > ~/.cifs
   

   
   
2. Create the directory to use as your mount point
   

   $ sudo mkdir -p /mnt/NAS
   

   
   
3. Add your network drive mount to /etc/fstab
   

   //SHARE_IP/SHARE_NAME /mnt/NAS cifs credentials=/home/user/.cifs,gid=GID,uid=UID
   

   where
   • GID and UID are the ssimwave user’s UID/GID (see here)
   • SHARE_IP is the IP address of the Windows share
   • SHARE_NAME is the name of the Windows share
   • /home/user/.cifs is the full path to the cifs credential file you created above
     
     
4. Mount the drive

   $ sudo mount -a
   

1. From your SSIMWAVE representative, you should receive or request the following account information:
   • Insights publisher username and password (Insights SASL/SCRAM credentials)
   • Google Cloud Repository (GCR) service account JSON key file providing access to SSIMWAVE’s repository gcr.io/ssimwave-insights
     
     
2. The Insights Proxy is distributed as a Docker container and, as such, Docker v18.09.7+ is required to be present on the target installation machine.
   
   
3. Target installation machine must have:
   • 4 cores/VCPUs
   • 8GB of RAM
   • 1G free disk space
     
     
4. Ports 9800 - 9804 should be open to the internal (i.e. on-premise) network.
   
   
5. Outbound/Internet access to the Insights cloud-based data platform on port 443 at the following hosts:
   • ingest-gateway.us-east.insights.ssimwave.com
   • insights.ssimwave.com
     
     
   Note

   The Insights Proxy supports using SOCKS5 and HTTP forward proxies, if required. Please see the Installation section for configuration details.

1. From a Linux CLI, log in to Google Container Registry (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>

2. Pull the Insights Proxy image to your local Docker repository:
   docker pull gcr.io/ssimwave-insights/proxy:MAJOR.MINOR.PATCH-BUILD
   where MAJOR, MINOR, PATCH and BUILD represent the major, minor, patch and build numbers of the desired build. Please see your SSIMWAVE representative for the appropriate build.
   
   

3. Start the proxy by running the Docker image as follows:
   

   docker run --rm -p 9800:9800 -p 9801:9801 -p 9802:9802 -p 9803:9803 -p 9804:9804 \
   -e USERNAME=<insights_platform_publisher_username> \
   -e PASSWORD=<insights_platform_publisher_password> \
   -e INTERNAL_PROXY_IP=<host_ip> \
   -e SOCKS5_PROXY=<socks5_proxy_ip> \
   -e SOCKS5_PROXY_USER=<socks5_proxy_user> \
   -e SOCKS5_PROXY_PASSWORD=<socks5_proxy_password> \
   -e HTTP_PROXY=<http_proxy_ip> \
   -e HTTP_PROXY_USER=<http_proxy_user> \
   -e HTTP_PROXY_PASSWORD=<http_proxy_password> \
   --net=host \
   gcr.io/ssimwave-insights/proxy:MAJOR.MINOR.PATCH-BUILD
   

   where <insights_platform_publisher_username> and <insights_platform_publisher_password> represent your Insights publisher username and password, respectively, MAJOR, MINOR, PATCH and BUILD represent the major, minor, patch and build numbers of the desired build and <host_ip> represents the local IP address of the machine running Docker.

   Note

   You cannot use the loopback adapter (127.0.0.1) for the <host_ip>. The IP address used must be a valid local IP address.

   Notice above that you can, optionally, specify either a SOCKS5 or HTTP proxy server (and credentials) if either is required for outbound connections.

   After a successfully launching the proxy as directed above, you should see output on the console similar to the following:

   Unable to find image 'gcr.io/ssimwave-insights/proxy:1.0.3-1' locally
   1.0.3-1: Pulling from ssimwave-insights/proxy
   c87736221ed0: Pull complete
   352d38e80cbc: Pull complete
   Digest: sha256:403fea7aa00fc17e5aef2dbb4e17049a34d1b25e6e49ef24cdfa0077aa17e864
   Status: Downloaded newer image for gcr.io/ssimwave-insights/proxy:1.0.0-1
   INFO[2019-07-10T15:13:57Z] Starting kafka-proxy version v0.1.2-1-g7d600af-dirty
   INFO[2019-07-10T15:13:57Z] Bootstrap server ingest00.us-east.insights.ssimwave.com:9095 advertised as 127.0.0.1:9800
   INFO[2019-07-10T15:13:57Z] Bootstrap server ingest01.us-east.insights.ssimwave.com:9095 advertised as 127.0.0.1:9801
   .
   .
   .
   INFO[2019-07-10T15:13:57Z] Ready for new connections
   

The first step when troubleshooting is to ensure you have connectivity from your Insights Proxy to the Insights data platform.

In order to access let’s ensure DNS is working as expected:

$ or host in "ingest-gateway.us-east.insights.ssimwave.com" "insights.ssimwave.com"; do host $host; done
ingest-gateway.us-east.insights.ssimwave.com has address 3.232.252.138
ingest-gateway.us-east.insights.ssimwave.com has address 3.211.65.212
ingest-gateway.us-east.insights.ssimwave.com has address 3.220.211.137
insights.ssimwave.com is an alias for ssimwave.looker.com.
ssimwave.looker.com is an alias for 5845660a-0155-41c8-bd43-8b3386cdcd99.cloud.looker.com.
5845660a-0155-41c8-bd43-8b3386cdcd99.cloud.looker.com is an alias for a15bd4510389b4aa6b9f68ed30fa75f5-1609311009.us-east-1.elb.amazonaws.com.
a15bd4510389b4aa6b9f68ed30fa75f5-1609311009.us-east-1.elb.amazonaws.com has address 44.196.133.194
a15bd4510389b4aa6b9f68ed30fa75f5-1609311009.us-east-1.elb.amazonaws.com has address 52.72.206.4
a15bd4510389b4aa6b9f68ed30fa75f5-1609311009.us-east-1.elb.amazonaws.com has address 44.213.239.188

Next, let’s ensure we can connect to the Insights by running the following script:

#!/bin/sh

RED='\033[1;31m';
GREEN='\033[1;32m';
WHITE='\033[1;37m';
NC='\033[0m';
              
for host in "ingest-gateway.us-east.insights.ssimwave.com" "insights.ssimwave.com"
do
  nc -w 1 -z $host 443 ;
  RES=$?
  if [[ "$RES" -eq "0" ]] ; then
    echo -e "${WHITE}$host:443 -> ${GREEN}Good.${NC}"
  else
    echo -e "${WHITE}$host:443 -> ${RED}Cannot connect.${NC}"    
  fi
done

If you are able to connect you should see output like the following:

ingest-gateway.us-east.insights.ssimwave.com:443 -> Good.
insights.ssimwave.com:443 -> Good.

If you are unable to connect then it is likely there are firewall issues that need to be resolved.

If the above works but the proxy is not working in the container then it is likely an issue with the container command line invocation.

If you encounter other problems successfully deploying the Insights Proxy, please contact your SSIMWAVE representative.

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

• The SSIMPLUS® Analyzer Cluster is the customer-deployed portion of the SSIMPLUS® VOD Monitor system and is designed as a set of cooperating software (Docker) containers that are orchestrated by Kubernetes.

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

    • A REST API known as the SSIMPLUS® Analyzer REST API that can be used to:

      • Submit new analyses and configure the SSIMPLUS® Analyzer to capture the various metrics and measurements of interest
      • Cancel running analyses
      • Delete completed analyses
      • Inspect videos for quality impairments by capturing frames and a number of SSIMPLUS® maps (i.e. quality maps, banding maps, color volume difference maps) to illustrate areas of poor quality.
        
        
      Important

      The SSIMPLUS® Analyzer 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 trial/lab deployments of the SSIMPLUS® Analyzer Cluster, there is only ever one running instance of each container as the scalability needs here are expected to be relatively low. Production deployments of the cluster, by contrast, will elastically scale these containers to meet the demand.
    
    

  • The Analyzers are Docker containers that wrap the SSIMPLUS® Analyzer and perform the analysis of the video assets, generating the SSIMPLUS® metadata and metrics that are securely streamed to Insights. Analyzers are configured, deployed and managed by the SSIMPLUS® Analyzer REST API in response to POST requests to analyze one or more video assets.

    • Each Analyzer container is responsible for analyzing either a single video, in the case of a no-reference (NR) analysis, or a pair of reference and test videos together, in the case of a full-referenece (FR) analysis.

    • Each Analyzer 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.

    • Analyzer 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 trial/lab deployments of the SSIMPLUS® Analyzer Cluster, 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). Production 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 measurements and metrics captured by the SSIMPLUS® Analyzer. Some of the key features of Insights include:

  • Insights VOD Monitor Web UI which can be used to:
    • submit ad-hoc analyses,
    • configure and save various analyzer configurations into reusable and shareable templates,
    • view and interact with a summary/status of all analyses,
    • review analysis results for customizable quality failures 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 SSIMPLUS® VOD Monitor 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 the SSIMPLUS® VOD Monitor 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 both the SSIMPLUS® Analyzer and Insights REST APIs by submitting the underlying API requests on the user’s behalf.

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 analysis, 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 a NR analysis of a video asset using the SSIMPLUS® Analyzer REST API and the submit new analyses endpoint.

   Notice here that:

   • our asset is lives in an S3 bucket and we are relying on IAM roles to provide read-only access to the bucket,
   • we are configuring the SSIMPLUS® Analyzer to target the LG OLED65C9PUA device from an expert viewer’s perspective and
   • we are configuring a score check on our asset that will consider the video to have failed if there is any period of 5 or more seconds where the SSIMPLUS® Viewer Score (SVS) for our selected device falls below 85.
     
     

   {
     "content": {
       "title": "NR Analysis With SVS Score Check"
     },
     "subjectAssets": [
       {
         "name": "dog_running.mp4",
         "path": "royalty_free/dog_running/source",
         "storageLocation": {
           "type": "S3",
           "name": "video-files",
           "credentials": {
             "useAssumedIAMRole": true
           }
         },
         "qualityCheckConfig": {
           "scoreChecks": [
             {
               "metric": "SVS",
               "threshold": 85,
               "durationSeconds": 5,
               "viewingEnvironmentIndex": 0
             }
           ]
         }
       }
     ],
     "analyzerConfig": {
       "viewingEnvironments": [
         {
           "device": {
             "name": "oled65c9pua"
           },
           "viewerType": "EXPERT"
         }
       ]
     }
   }
   

   A successful response from the SSIMPLUS® Analyzer REST API would look something like the following:

   {
     "submittedAnalyses": [
       {
         "analyzerConfig": {
           "viewingEnvironments": [
             {
               "device": {
                 "name": "oled65c9pua"
               },
               "viewerType": "EXPERT"
             }
           ]
         },
         "id": "13afcc15-6808-4819-9cd3-fde950dda0f2",
         "subjectAsset": {
           "content": {
             "title": "NR Analysis With SVS Score Check"
           },
           "hdr": false,
           "name": "dog_running.mp4",
           "path": "royalty_free/dog_running/source",
           "qualityCheckConfig": {
             "scoreChecks": [
               {
                 "durationSeconds": 5,
                 "metric": "SVS",
                 "skipEnd": 0,
                 "skipStart": 0,
                 "threshold": 85,
                 "viewingEnvironmentIndex": 0
               }
             ]
           },
           "storageLocation": {
             "name": "video-files",
             "type": "S3"
           }
         },
         "submissionTimestamp": "2023-08-08T17:53:40.969Z",
         "testId": "1"
       }
     ]
   }
   

   Notice in the response above the line "id": "13afcc15-6808-4819-9cd3-fde950dda0f2" reports back the analysis UUID which is the required key for fetching the analysis results from Insights.

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

   Notice that the Analyzer API & Services have:

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

2. The Analyzer container works to analyze the video and streams the resulting metrics and metadata to Insights.

   

   As illustrated above:

   • the Analyzer evaluates the video asset and streams the SSIMPLUS® measrements and metrics to Inisghts (Note: no part of the video itself is streamed to Insights),
   • Insights applies additional viewer intelligence algorithms to the incoming streams before storing the data and,
   • once the analysis is complete, acknowledgements are recognized by both sides and the Analyzer container is destroyed (i.e. elastic scaling) in order to release the compute resources being used by the SSIMPLUS® Analyzer Cluster.
     
     

3. Using the Insights REST API’s api/4.0/queries/run/json endpoint, we can fetch the results of our analysis to see if our video passed its quality check.

   {
     "model": "vod_monitor",
     "view": "vod_quality_checks",
     "fields": [
       "vod_quality_checks.analysis_uuid",
       "vod_quality_checks.time",
       "vod_quality_checks.title",
       "vod_quality_checks.organization",
       "vod_quality_checks.site",
       "vod_quality_checks.test_id",
       "vod_quality_checks.test_video",
       "vod_quality_checks.category",
       "vod_quality_checks.type",
       "vod_quality_checks.interval_start_time",
       "vod_quality_checks.interval_end_time",
       "vod_quality_checks.check_duration_seconds",
       "vod_quality_checks.check_duration_percentage",
       "vod_quality_checks.test_video_duration_seconds"
     ],
     "filters": {
       "vod_quality_checks.analysis_uuid": "<analysis_uuid>"
     },
     "sorts": [
       "vod_quality_checks.interval_start_time"
     ]
   }
   

   where <analysis_uuid> is the UUID for the analysis retrieved from the response in step 1. In this specific example, the value would be 13afcc15-6808-4819-9cd3-fde950dda0f2.

   An empty response:

   []
   

   from the Insights REST API indicates that the asset passes our score checks criteria (i.e. no period of 5s or more where SVS falls below 85) and there is nothing more to do (see below).
   
   

   

   If the asset fails our score check criteria, as it does in the response below from 0s - 6.16s:

       [
         {
           "vod_quality_checks.analysis_uuid": "13afcc15-6808-4819-9cd3-fde950dda0f2",
           "vod_quality_checks.time": "2023-08-08 13:54:01.851000",
           "vod_quality_checks.title": "NR Analysis With SVS Score Check",
           "vod_quality_checks.organization": "SSIMWAVE",
           "vod_quality_checks.site": "VOD Demo",
           "vod_quality_checks.test_id": "1",
           "vod_quality_checks.test_video": "royalty_free/dog_running/source/dog_running.mp4",
           "vod_quality_checks.category": "Video",
           "vod_quality_checks.type": "SSIMPLUS Viewer Score",
           "vod_quality_checks.interval_start_time": "00:00:00.000",
           "vod_quality_checks.interval_end_time": "00:00:06.160",
           "vod_quality_checks.test_video_duration_seconds": 19.68,
           "vod_quality_checks.check_duration_seconds": 6.16,
           "vod_quality_checks.check_duration_percentage": 0.313008130081
         }
       ]
   

   the workflow would likely take additional measures not explicitly captured here (i.e. flag/remove the asset) and may well require human/operator involvement to visually inspect the results in detail using the Insights Web UI and/or reports and dashboards, as shown below:

   

The source validation example above is but one of many supported by the SSIMPLUS® VOD Monitor, which can be used to realize a number of key use cases, including:

• source selection,
• encoder validation,
• encoder comparisons,
• content similarity evaluations,
• HDR luminance evaluations,
• packaging/metadata errors,
• cadence mismatch detections,
• color gamut and volume differencing
• and more.

All use cases are available in both trial/lab and production deployments of SSIMPLUS® VOD Monitor.

Please reach out to your SSIMWAVE representative for examples of how the product can be leveraged and tailored to meet your specific needs.

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 SSIMPLUS® VOD Monitor 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 SSIMPLUS® Analyzer and Insights REST APIs.
     
     

3. Use the Insights Web UI to submit some adhoc no-reference/full-reference analyses and inspect their results.

   The best way to fully appreciate the product is to get busy using it. The Insights Web UI provides a familiar graphical interface that allows you to execute and review the results for anything from a simple no-reference analysis to a full ABR ladder, in addition to any number of video and audio quality checks.

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

4. Install Postman and import the SSIMPLUS® VOD Monitor collection and environment.
   
   

5. Review the SSIMPLUS® Analyzer 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 SSIMPLUS® Analyzer 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.

The SSIMPLUS® VOD Monitor/Analyzer can be configured to produce the following video measurements:

• no-reference SSIMPLUS® Viewer Score (NR SVS),
• full-reference SSIMPLUS® Viewer Score (FR SVS),
• SSIMPLUS® Encoder Performance Score (EPS),
• SSIMPLUS® Banding Score (SBS),
• perceptual Color Volume Difference Score (CVD),
• SSIMPLUS® Content Complexity Measure (CCM),
• macroblocking,
• noise estimation,
• and HDR-specific metrics such as MaxFALL, MaxCLL and color gamut detection.

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.

Perceptual Color Volume Difference Score (CVD)

SSIMPLUS® Viewer Score and SSIMPLUS® Encoder Performance Score take into account color quality. The perceptual color difference is a dedicated metric for color quality assessment that supports both HDR and SDR content. The metric provides a visibility map that helps to quickly identify areas with significant perceptual color differences. The score ranges from 0 to 100, where0 represents no deviation, <15 color difference is perceptible and 100 denotes colors are opposite.

Reference/Source	Output

The SSIMPLUS® color volume differece map:

SSIMPLUS® Content Complexity Score (CCS)

The primary challenge for a video processing/encoding system to operate at the optimal level is the vast variety of video characteristics also called video complexity. Different content types (such as sports, news, nature, movie, and documentary) require the video system to run in different configurations.

Traditional measures, like spatial and temporal information, don’t describe the video complexity very well. For example, a frame with high spatial information doesn’t mean it’s difficult to encode.

Content Complexity Score (CCS) is a measure to describe how difficult it is to encode an asset/any piece of content. Content Complexity is one of the most important metrics when making decisions about encoding configurations like bitrate allocation, resolution etc. Complexity measurements can be used to make more intelligent decisions regarding the type of encoder, and/or profile settings to apply, when encoding asset for downstream packaging or consumption.

The CCS can deliver significant value by:

• saving bandwidth for relatively easy content while maintaining the target quality (as measured by SSIMPLUS® Viewer Score),
• mintaining the target quality even for complex content by redistributing the resources wisely across content with different requirements,
• reducing the quality variation of the asset library,
• optimizing encoders for asset libraries with a wide range of content,
• saving time and encoding power and
• optimizing transmission costs

Macroblocking

Macroblocking artifacts are a type of visual distortion that can occur during video transmission when packets of data are lost. The severity and appearance of these artifacts can vary, depending on the content of the video, the encoding algorithm used, the packetization strategy, and how the decoder handles errors. Macroblocking detection is a method of analyzing a video frame to determine whether or not it contains macroblocking artifacts. While some non-reference quality metrics may be unable to accurately identify the presence of these artifacts, others, SSIMWAVE, is specifically designed to do so. This is important because these artifacts can significantly impact the perceived quality of the video.

The SSIMPLUS® Viewer Score (SVS) takes macroblocking artifacts into consideration after enabling the macroblocking detection.

Noise estimation

Noise estimation is critical to measure how much noise exists in the content so that the quality assessment metric can be adapted to generate the objective quality score which is consistent with human opinion.

Noise and film grain are different. Noise needs to be suppressed, while film grain needs to be preserved as it is part of the creative intent. Instead of the structural fidelity of film grain, the human visual system (HVS) is sensitive to the statistical similarity which hasn’t been captured by the existing quality assessment methodologies.

SSIMPLUS® provides two noise metrics for content analysis:

• Physical Noise

  Physical Noise measures the standard deviation of camera/sensor noise when the statistical behavior of noise is random with gaussian (or similar) distribution. If noisy content is processed multiple times, then noise can become correlated with content and lose the randomness, which would reduce the effectiveness of the metric due to deviation of appearance of noise from “true noise.”
  
  

• Visual Noise

  Visual Noise measures the standard deviation of noise considering contrast masking behavior of underlying content. For example, noise is much more visible in plain regions than in areas with textures. Similar to the case of Physical Noise measurement, if noisy content is processed multiple times, then noise can become correlated with content and lose the randomness, which would reduce the effectiveness of the metric due to the deviation of the appearance of noise from “true noise.”

HDR

HDR displays are typically limited in terms of emitting enough luminance so they must perform tone mapping or luminance shifting/clipping to render HDR content.

Understanding minimum, maximum, and average luminance values for each frame as well as maximum frame average light level (MaxFALL) and maximum content level light level (MaxCLL) is very helpful for content providers to ensure the creative intent does not get compromised because of display capabilities. Embedded HDR10 metadata is not reliable and often gets ignored by HDR displays. SSIMPLUS® analyzes pixels and calculates per-frame min, max and average luminance value as well as MaxFALL and MaxCLL. This feature is used for Quality Control of HDR productions or to validate embedded metadata.

Color gamut detection

The beauty of HDR videos is not solely due to the brighter and darker pixels. Accommodating wider color gamuts (WCG) brings richer color tones to the content.

Grading HDR is typically done using a P3 color gamut. HDR delivery pipelines always use Rec 2020 primaries and so HDR metadata does not provide useful insight into the gamut coverage of the content.

SSIMPLUS is able to look at pixel values and determine the gamut coverage of each frame. Receiving HDR/WCG content, content providers will know how much of the content is actually in Rec 709, P3 or Rec 2020 when receiving HDR/WCG content.

*SSIMPLUS® VOD Monitor supports HLG, HDR10 and Dolby Vision analysis.

SSIMPLUS® no-reference (Source SSIMPLUS® Viewer Score), full-reference (Encoder Performance Score), and degraded-reference (Output SSIMPLUS® Viewer Score) technologies assess perceived quality for any target display device and viewing environment:

1. Device adaptive

   SSIMPLUS® Scores are device adaptive; this means that the metrics consider the device display attributes and viewing conditions when computing the score and take into account content scaling performed to match device attributes. Impairment perceptibility varies significantly across device displays and viewing conditions. SSIMPLUS takes into account content quality and playback behavior to accurately reflect viewer experience in real time.

   The score can be used to assess degradation in the Viewer Experience introduced by the performance of content delivery and playback, adapted to the display device used by each viewer. It correlates linearly with perceived quality and covers the full quality range.

   The scores support displays of any size, resolution, frame-rate, and brightness. The scores also adapt according to viewing distance, angle, and other important viewing conditions.

   VOD Monitor supports more than 100 model devices from vendors like Samsung, LG, Sony, Canon, Apple, etc.
   
   

2. Viewer adaptive

   SSIMPLUS® Scores are Viewer Adaptive; SSIMPLUS® Viewer Scores and Encoder Performance Scores adapt according to the viewer type, based on the psychovisual behavior: Studio, Expert, and Typical viewers differ in the following ways:

   1. Typical Viewer

      The Typical Viewer is primarily concerned with the content of the video rather than the overall viewing experience. They tend to be more critical of quality drops and less likely to notice or appreciate improvements in quality. They also recognize that not all regions of the content are equally important, and their overall evaluation of the content is influenced by this fact.
      
      

   2. Expert Viewer

      The Expert Viewer, on the other hand, is primarily focused on the quality of the video rather than the content itself. They are aware that different regions of the content may be more or less important, and their overall evaluation of the video is largely dependent on the worst segments of the content.
      
      

   3. Studio Viewer

      The Studio Viewer is primarily concerned with the preservation of the creative intent of the video, and they place particular importance on regions of the content that are impaired or degraded in some way. They are less concerned with the overall quality of the video and more focused on ensuring that the content is being presented in a way that is consistent with the original creative vision.

The SSIMPLUS® Analyzer streams scores for every frame of every asset analyzed to the Insights data platform, where our processing provides aggregates of these frame scores over time intervals called measurement periods and these values are used for various analytics, including many of the pre-configured views presented in the sections below. When it comes to generating a single score (SVS, EPS, SBS or CCS) for all frames over a given measurement period, there are three value types that are available: average, minimum and maximum. As you would expect, these values are the mathematical average, minimum and maximum calculated across the population of frame scores over the given measurement/time period.

The following screen capture provides a useful illustration for understanding measurement periods:

Here we can see that the graph’s reference time is delineated into 2s intervals which we will use as the measurement period in this example. Using this approach, we’ve augmented the graph with labels for a selection of measurement periods showing the approximate average, minimum and maximum scores.

When you use the Insights REST API to fetch analysis results, you’ll have the ability to customize the measurement period used and, in some cases, the measurement type (i.e. average, minimum or maximum). Generally speaking, you have the choice of the following measurement periods to use when aggregating the frame scores:

• 1s
• 2s
• 5s
• 10s
• 30s
• 60s

Unless requested otherwise, the default measurement period is 1s and the type used is average. You may, at any time, request scores down to the frame level, should your use case require that level of granularity.

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) and
• SSIMPLUS® Content Complexity Score (CCS).

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, an Asset Encoder Performance Score (EPS) and an Asset Content Complexity Score (CCS) can provide a single judgement of the encoder’s performance and the complexity of an entire asset, respectively.

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

Cadence is defined as the repetition pattern of frames when content that was originally produced at a lower framerate is presented at a higher frame rate as a result of frame rate conversion.

Since content may be transcoded multiple times between the original and the analyzed video and different transcoders apply different cadence patterns when performing frame rate conversion and deinterlacing, SSIMPLUS® VOD Monitor applies heuristics to determine what cadence pattern is observed. Additionally, since some long form content may be a combination of different sources stitched together, SSIMPLUS® VOD Monitor can detect several cadences throughout the asset and report the detected cadence patterns along with the times observed to Insights.

If there is not enough differentiation between frames within the content due to low motion, then SSIMPLUS® VOD Monitor will not report a cadence but instead report "Unknown (Low Motion)" as well as a confidence threshold for all detected cadence patterns.

The list of cadence patterns SSIMPLUS® VOD Monitor can detect and their typical use case are

Loudness Metrics

SSIMPLUS® VOD Monitor is capable of performing several loudness measurements that follow the ITU-R BS.1770, EBU Tech 3341 and EBU Tech 3342 measurement standards. These measurements can have Quality Checks applied to them.

• True Peak Level
• Integrated Loudness
• Momentary Loudness
• Short-Term Loudness
• Loudness Range

True Peak Level

True Peak Level is defined within the ITU-R BS.1770 specification.

True Peak Level measurement performs 4x oversampling of the audio samples of the track to determine what the true peak as opposed to the sample peak.

The unit of measurement for True Peak Level is dBTP or decibels relative to full scale, true-peak.

Integrated Loudness

Integrated Loudness (also known as Programme Loudness) is defined within the ITU-R BS.1770 specification.

Integrated Loudness is a loudness measurment that weights the individual channels to determine a perceived loudness.

Integrated Loudness is measured over the entire asset.

The unit of measurment for Integrated Loudness is LKFS or Loudness, K-weighted, relative to full scale. LKFS is equivalent to a decibel - an increase in the level of a signal by 1 dB will cause the loudness reading to increase by 1 LKFS.

Momentary Loudness

Momentary Loudness is defined within the EBU Tech 3341 specification.

Momentary Loudness is an ungated loudness measurment derived from Integrated Loudness that uses a sliding rectangular time window of length 400ms.

The unit of measurment for Momentary Loudness is LUFS or Loudness Units, relative to full scale. LUFS is equivalent to LKFS, but in EBU documentation the preferred term is LUFS.

Short-Term Loudness

Short-Term Loudness is defined within the EBU Tech 3341 specification.

Short-Term Loudness is an ungated loudness measurement derived from Integrated Loudness that uses a sliding rectangular time window of length 3s.

The unit of measurment for Short Term Loudness is LUFS.

Loudness Range

Loudness Range is defined within the EBU Tech 3342 specification.

Loudness Range quantifies the variation in a gated loudness measurement over a 3s period.

The unit of measurement for Loudness Range is LU or Loudness Units.

The unit of measurement for Loudness Range High Level and Loudness Range Low Level is LUFS.

Standards

The SSIMPLUS® VOD Monitor product allows for configuration of the ITU-R BS.1770 measurement standard when performing loudness measurement and loudness based quality checks. A description of the standards can be found in the table below.

The default measurement standard is ITU-R BS.1770-4.

Configuration and Supported Formats

SSIMPLUS® VOD Monitor Audio Loudness measurements and all audio quality checks support a variety of codecs and formats. This includes but is not limited to:

• Dolby Digital AC-3
• Dolby Digital Plus E-AC-3
• Dolby Digital Plus with Dolby Atmos E-AC-3
• AAC
• MPEG-2 Audio
• MPEG-3 Audio
• PCM Audio

If a desired codec is not listed above, customers should contact their SSIMWAVE representative for more information.

When performing audio loudness measurements, all physical audio tracks within an asset will have their loudness measured according to the metrics listed in the Loudness Metrics section.

PCM Audio Support

Certain container formats (e.g. MXF) will have additional metadata indicating the channel layout of PCM audio and are fully supported. However, for PCM audio tracks that do not have an explicit channel layout, support is currently limited in SSIMPLUS® VOD Monitor. The number of channels within the track will default to a specific channel layout. There are two tables to assist in tracking how PCM audio tracks without channel layout metadata will be processed by the analyzer. A mapping of channel acronyms and channels along with a list of channels to channel layout mapping supported in SSIMPLUS® VOD Monitor can be found below.

Channel Acronym to Channel Name Mapping