StreamSmart™ is an enterprise software product that lets you encode smarter and save money. StreamSmart™ overlays on your existing encoding workflow and uses the most accurate measure of video quality, IMAX SVS (SSIMPLUS® Viewer Score), to retain the same visual quality of experience, while delivering a significant reduction in delivery costs.
The result? Millions of dollars in savings each year, typically 15-25% above what content-aware encoders are already delivering. StreamSmart™ has enabled a prominent streaming platform provider to save close to $25M annually by reducing bandwidth consumption across 22,000 titles, without affecting perceptual quality.
How does it work? The figure below shows a typical VOD workflow where a VOD processing queue module schedules jobs by pushing the content and the encoder configuration to the video encoding block. The output is then provided to an origin server and to a content delivery network (CDN) for delivery.
In the following figures, StreamSmart™ is installed as a smart layer for the video encoding block, where the VOD processing queue module provides the encoder configuration and the content path to the StreamSmart™ orchestration layer. StreamSmart™, based on the encoding configuration being used (denoted by the “anchor” encode), uses IMAX’s perceptual quality technology to determine the optimal revised configurations for some additional encodes (denoted as the “candidate” encodes).
All encoded segments for the anchor and the candidate encodes are scored using the IMAX SSIMPLUS® metric and then the selection process of picking the segments that meet the objective of maintaining the perceptual picture quality at the lowest possible bitrate.
Terminology and Branding
As the work to integrate SSIMWAVE into IMAX continues, we are working on rebranding our group, products and technology. It’s a big task, and in the middle of the transition, there may be a mix of old and new.
As part of this work, VOD Monitor and StreamSmart are being delivered together as a platform called IMAX Stream. We are leveraging a lot of the work we’ve done on VOD Monitor with respect to architecture, software packaging, deployment and UX, to help accelerate our time-to-market for StreamSmart. As a result, while we are in the middle of our integration and rebranding efforts, you may find references to VOD Monitor in this documentation for StreamSmart. These are not typos! In the not-too-distant future, the documentation for VOD Monitor and StreamSmart will be merged together and the new branding and terminology will be applied.
We appreciate your patience and understanding as we go through this exciting change.
Let’s take a look at the StreamSmart™ system architecture and call out some key details of each component within the context of a typical workflow. The diagram below represents a common view of the system architecture, regardless of your deployment model:
-
The IMAX Stream™ On-Demand Platform is the customer-deployed portion of the StreamSmart™ system and is designed as a set of cooperating software (Docker) containers that are orchestrated by Kubernetes.
-
The StreamSmart™ API & Services are a set of always-running containers that provide the following:
-
A REST API known as the Stream™ On-Demand REST API that can be used to:
- Submit new encoding optimization requests
- Visually inspect the results by capturing frames and a number of SSIMPLUS® maps (i.e. quality maps, banding maps, color volume difference maps).
ImportantThe Stream™ On-Demand REST API provides an OpenAPI Specification (OAS) that can be used to generate language-specific clients for those interested in jump-starting an integration into their production workflow. Both Swagger Codegen and OpenAPITools openapi-generator are examples of tools that can be used for this purpose. Additionally, any laguage that has support for sending and receiving HTTP requests/responses in JSON format can be also be used with minimal effort. Please contact your SSIMWAVE representative if you require any guidance.
-
Services for interacting with Kubernetes to take advantage of its various deployment, scaling, scheduling and management features
-
Services for interacting with various cloud API services (i.e. Amazon S3)
For fixed scale deployments of the IMAX Stream™ On-Demand Platform, there is only ever one running instance of each container as the scalability needs here are expected to be relatively low. Elastic scale deployments of the cluster, by contrast, will elastically scale these containers to meet the demand.
-
-
The Optimizers are Docker containers that drive the encoding and perform the optimization, generating the SSIMPLUS® metadata and metrics that are securely streamed to Insights. Optimizers are configured, deployed and managed by the Stream™ On-Demand REST API in response to POST requests to analyze one or more video assets.
-
Each Optimizer container is configured to request the compute resources (CPU/RAM) it needs in order to succesfully perform its analysis, given the properties of the assets being analyzed.
-
Optimizer containers never stream any part of the video to Insights and, as such, no content (i.e. video, frames or images) ever leaves the customer’s environment/control.
NoteUpon request, SSIMWAVE will provide examples of the metrics and metadata streamed to Insights.
-
For fixed scale deployments of the IMAX Stream™ On-Demand Platform, the number of concurrently running Analyzers will scale but only to a fixed number, as the cluster itself is constrained by the underlying properties of the virtual machine (i.e. OVA/QEMU) or EC2 instance (i.e. AMI). Elastic scale deployments of the cluster, by contrast, can elastically scale without an upper bound, if so desired, in order to meet even the most demanding analysis workloads.
-
-
-
Insights is SSIMWAVE’s multi-tenant cloud platform that leverages the power of our own viewer intelligence algorithms, along with leading business intelligence services, to present meaningful representations of the encoding and optimization results. Some of the key features of Insights include:
- Insights VOD Monitor Web UI which can be used to:
- view and interact with a summary/status of all analyses (both VOD Monitor analyses and StreamSmart™ optimizations),
- review results and
- perform frame-level inspections of your content, including image and map comparisons.
- Insights REST API which can be used to:
- fetch all captured metrics and measurements across a variety of time granularities including:
- per-frame,
- per-second (1s, 2s, 5s, etc.) and
- per-asset.
- fetch all captured metrics and measurements across a variety of time granularities including:
- 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.
- Insights VOD Monitor Web UI which can be used to:
-
The Automation computer/laptop icon above illustrates that the full StreamSmart™ system is designed to be used in a headless manner (i.e. through API/programmatic access) and that most key features are exposed through their respective REST APIs.
-
The user/human icon and its connections above illusrate that:
- to support those integrating StreamSmart™ into their production workflows, SSIMWAVE has provided Postman collections with numerous REST API examples that can be imported into the Postman UI in order to become familiarized with the API request/response structures and
- the Insights VOD Monitor Web UI can equally be used to interact graphically with the system by submitting the underlying API requests on the user’s behalf.
The IMAX Stream™ On-Demand Platform can be deployed in the following ways:
Fixed scale:
- As an EC2 instance on AWS using the IMAX Stream AMI
- As a virtual machine instance using an OVA or QEMU image
Elastic/dynamic scale:
- On Kubernetes using the provided container images and manifests (AWS EKS or otherwise)
- On AWS EKS as a managed service
For details, refer to the Deployment Guides section.
Recall from the architecture section above that the StreamSmart™ system is comprised of two major parts:
- The IMAX Stream™ On-Demand Platform, which is deployed in the customer’s on-prem/VPC environment, and
- Insights, which is a multi-tenant cloud solution deployed and maintained by SSIMWAVE.
Once you have successfully deployed IMAX Stream, you are ready to start using the system. While the architecture information to this point has given you an overview of the system components, this section adds more detail to the concepts already introduced, including important interactions between components and links to help you start using system.
Now that we’ve provided some detail on the high level components of the system architecture, let’s walk through the process of a typical optimization, along with some sample requests/responses in JSON. For the examples that follow, we are going to use assume a production deployment and workflow, which leverages the REST APIs for programmatic control and the Insights Web UI for out-of-band/follow-up inspections of the results. Lab/trial workflows would likely use the Insights Web UI exclusively.
-
Submit an FFmpeg encoding/optimization request using the Stream™ On-Demand REST API and the submit new FFmpeg optimization endpoint.
{ "content": { "title": "Example Title" }, "input": { "name": "example/input/path/example_source_file.mov", "storageLocation": { "type": "S3", "name": "example-s3-bucket-name" } }, "encoderConfig": { "type": "FFmpegConfig", "encodes": [ { "command": [ "ffmpeg -i {INPUT_LOCATION} -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=48:keyint_min=48:scenecut=0\" -profile:v high -level:v 4.1 -preset slow -b:v 4500k -maxrate 4500k -bufsize 6000k -an {OUTPUT_LOCATION}" ], "outputLocation": { "name": "example/output/path/encoded_video.mp4", "storageLocation": { "type": "S3", "name": "example-s3-bucket-name" } } } ] } }
A successful response from the Stream™ On-Demand REST API would look something like the following:
{ "uuid":"a378d122-fd7e-4f12-8a34-7f60cc129216", "organization":"SSIMWAVE", "site":"StreamSmart", "title":"Example Title", "status":"Created", "config":{ "encodes":[ { "commands":[ "ffmpeg -r 24 -i {INPUT_LOCATION} -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range mpeg -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=50:keyint_min=50:scenecut=0:stitchable=1\" -profile:v high -level:v 4.1 -b:v 5000k -maxrate 6250k -bufsize 10000k -r 24 -vf scale=1920x1080 -an {OUTPUT_LOCATION}" ], "outputLocation":{ "path":"example/output/path/example_output_file.ts", "storageLocation":{ "type":"S3", "name":"example-s3-bucket-name" } } } ], "inputLocation":{ "key":"example/input/path/example_source_file.mov", "storageLocation":{ "type":"S3", "name":"example-s3-bucket-name" } } } }
Notice in the response above the line
"uuid": "a378d122-fd7e-4f12-8a34-7f60cc129216"
reports back the analysis UUID which is the required key for fetching the status and results from Insights.Alternatively, you can submit an optimization that uses AWS Elemental MediaConvert (EMC) using an example like the following:
{ "content": { "title": "Example Title" }, "encoderConfig": { "type": "EMCConfig", "config": { "JobTemplate": "", "Queue": "arn:aws:mediaconvert:us-east-1:315835334412:queues/Default", "UserMetadata": {}, "Role": "arn:aws:iam::315835334412:role/mediaconvert-optimizer", "Settings": { "OutputGroups": [ { "CustomName": "top-profile-encode", "Name": "CMAF", "Outputs": [ { "ContainerSettings": { "Container": "CMFC" }, "VideoDescription": { "Width": 1920, "ScalingBehavior": "STRETCH_TO_OUTPUT", "Height": 1080, "TimecodeInsertion": "DISABLED", "AntiAlias": "ENABLED", "Sharpness": 50, "CodecSettings": { "Codec": "H_264", "H264Settings": { "InterlaceMode": "PROGRESSIVE", "NumberReferenceFrames": 3, "Syntax": "DEFAULT", "Softness": 0, "GopClosedCadence": 1, "GopSize": 2, "Slices": 1, "GopBReference": "ENABLED", "HrdBufferSize": 16000000, "MaxBitrate": 8000000, "EntropyEncoding": "CABAC", "RateControlMode": "QVBR", "QvbrSettings": { "QvbrQualityLevel": 9 }, "CodecProfile": "HIGH", "MinIInterval": 0, "AdaptiveQuantization": "AUTO", "CodecLevel": "AUTO", "SceneChangeDetect": "ENABLED", "QualityTuningLevel": "SINGLE_PASS", "UnregisteredSeiTimecode": "DISABLED", "GopSizeUnits": "SECONDS", "ParControl": "INITIALIZE_FROM_SOURCE", "NumberBFramesBetweenReferenceFrames": 3, "RepeatPps": "DISABLED", "DynamicSubGop": "ADAPTIVE" } } }, "NameModifier": "_8Mbps" } ], "OutputGroupSettings": { "Type": "CMAF_GROUP_SETTINGS", "CmafGroupSettings": { "TargetDurationCompatibilityMode": "SPEC_COMPLIANT", "WriteHlsManifest": "ENABLED", "WriteDashManifest": "ENABLED", "SegmentLength": 4, "Destination": "s3://s3-bucket/destination/path/", "FragmentLength": 2, "SegmentControl": "SEGMENTED_FILES", "WriteSegmentTimelineInRepresentation": "ENABLED", "ManifestDurationFormat": "FLOATING_POINT", "StreamInfResolution": "INCLUDE" } } } ], "Inputs": [ { "AudioSelectors": { "Audio Selector 1": { "DefaultSelection": "DEFAULT" } }, "VideoSelector": { "ColorSpace": "FOLLOW", "Rotate": "DEGREE_0", "AlphaBehavior": "DISCARD" }, "FilterEnable": "AUTO", "PsiControl": "USE_PSI", "FilterStrength": 0, "DeblockFilter": "DISABLED", "DenoiseFilter": "DISABLED", "TimecodeSource": "ZEROBASED", "FileInput": "s3://s3-bucket/sources/source.mov" } ] }, "AccelerationSettings": { "Mode": "DISABLED" }, "StatusUpdateInterval": "SECONDS_15", "Priority": 0, "HopDestinations": [] }, "region": "us-east-1", "endpointURL": "https://vasjpylpa.mediaconvert.us-east-1.amazonaws.com" } }
The following diagram illustrates the state of the system in response to the requests above:
At this point the StreamSmart™ API & Services have:
- validated the POST Optimization Request,
- inspected the properties of the underlying asset to determine the compute resources needed to analyze the asset,
- deployed a new Optimizer container to process the video file and
- prepared and returned a response to the caller.
-
The Optimizer container(s) use the specified encoder with the specified configuration to encode, and then optimize, the video. The progress and results are streamed to Insights. Once the analysis is complete, acknowledgements are recognized by both sides and the Optimizer container is destroyed (i.e. elastic scaling) in order to release the compute resources being used by the IMAX Stream™ On-Demand Platform.
-
Using the Insights REST API’s
api/4.0/queries/run/json
endpoint, we can fetch the status of the workflow to check if encoding and optimization has been completed.{ "model": "vod_monitor", "view": "vod_status_analysis", "fields": [ "vod_status_analysis.analysis_uuid", "vod_status_analysis.time", "vod_status_analysis.min_time", "vod_status_analysis.test_id", "vod_status_analysis.test_video", "vod_status_analysis.reference_video", "vod_status_analysis.stage", "vod_status_analysis.percent_done", "vod_status_analysis.test_count" ], "filters": { "vod_status_analysis.analysis_uuid": "<analysis_uuid>" } }
where
<analysis_uuid>
is the UUID for the analysis retrieved from the response in step 1. In this specific example, the value would bea378d122-fd7e-4f12-8a34-7f60cc129216
.The response indicates either that the workflow is in progress:
[ { "vod_status_analysis.analysis_uuid": "a378d122-fd7e-4f12-8a34-7f60cc129216", "vod_status_analysis.time": "2023-04-13 14:44:51", "vod_status_analysis.min_time": "2023-04-13 14:43:35", "vod_status_analysis.stage": "Encoding", "vod_status_analysis.percent_done": 78, "vod_status_analysis.test_count": 3 } ]
…or that it has completed:
[ { "vod_status_analysis.analysis_uuid": "a378d122-fd7e-4f12-8a34-7f60cc129216", "vod_status_analysis.time": "2023-04-13 14:45:23", "vod_status_analysis.min_time": "2023-04-13 14:43:35", "vod_status_analysis.stage": "Results Ready", "vod_status_analysis.percent_done": 100, "vod_status_analysis.test_count": 3 } ]
Once the optimization has completed, both the ‘Anchor’ encode (the unoptimized encode created using your encoder configuration), and the ‘Output’ (the optimized encode) will be available in the specified output location and can be inspected using the Insights REST API and/or the Web UI, as shown below:
To get started using the product, it is recommended that you take the following approach:
-
Review the SSIMPLUS® Terminology and Features section.
Here you can familiarize yourself with the various metrics and measurements supported by StreamSmart™ and which ones may be applicable to your specific use cases.
-
Book a demo/meeting with a SSIMWAVE representative.
If you haven’t already, consider booking a demonstration with your SSIMWAVE representative where you can see:
- a product overview, important features and future roadmap,
- how to use the Insights Web UI,
- how to use the Insights dashboards/reports and make customizations desired for your use cases and
- examples of common exchanges with the StreamSmart™ and Insights REST APIs.
-
Use the StreamSmart™ Postman Collection to submit an encode/optimization.
The best way to fully appreciate the product is to get busy using it.
For those ready to plan a production deployment, you are strongly encouraged to consider the following additional steps:
-
Install Postman and import the StreamSmart™ collection and environment.
-
Review the Stream™ On-Demand REST API and Postman examples.
-
Review the Insights REST API and Postman examples.
-
Start building your client/workflow code in your language of choice using the API experience you’ve gained above.
ImportantThe Stream™ On-Demand REST API provides an OpenAPI Specification (OAS) that can be used to generate language-specific clients for those interested in jump-starting an integration into their production workflow. Both Swagger Codegen and OpenAPITools openapi-generator are examples of tools that can be used for this purpose. Additionally, any laguage that has support for sending and receiving HTTP requests/responses in JSON format can be also be used with minimal effort. Please contact your SSIMWAVE representative if you require any guidance.
As illustrated in the Architecture Overview, the StreamSmart™ product separates the process of submitting and executing analyses from the storage, extraction and manipulation of the results. These latter activities fall under the purview of Insights, SSIMWAVE’s cloud-based data platform, and the purpose of this section is to describe and offer examples of how one interacts with this platform.
Insights 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 StreamSmart™. Insights allows SSIMWAVE to offer all manner of data manipulation and/or transformation, customized to our customer’s needs, which can then be consumed in any number of output formats, including visual (i.e. Web/GUI, PDF), API (i.e. JSON) and third-party product integrations (i.e. Excel).
Once you’ve worked through the Using StreamSmart™ section, you’re ready to get down to the business of using the Insights platform!
To start using Insights, you will need an account along with a clientId
and clientSecret
to access the Insights REST API. If you have not done so already, please use the SSIMWAVE Help Center to create a ticket specifying your organization and the email address you wish to use as your account login. Alternatively, you can send these values to your SSIMWAVE representative using Slack/email. Next, follow the instructions in your invitation email to set up your account. With a new account in place, you can login to the Insights VOD Monitor app along with a shared space that has been created for your organization, which includes pre-created dashboards to address the usage scenarios that will be of interest to you. Refer to the Insights Web UI section for a brief introduction to the Insights UI.
Your clientId
and clientSecret
are unique to your account and should be kept private. While the values need only be generated once, new ones can be regenerated in the case where they are lost or compromised.
The Insights platform offers a fully graphical experience via the Insights Web UI. For StreamSmart™ customers, there is an Insights VOD Monitor app which acts as your landing page when you login via your browser. This app is a system of interactive screens that allows you to submit new analyses, inspect their results and manage a library of completed analyses, among other things. Additionally, the Insights Web UI provides an advanced business intelligence tool that provides a number of out-of-the-box dashboards and reports for all levels of consumer, with the ability to easily create and extend new ones to meet specific needs.
The Insights Web UI provides a very rich and highly configurable user interface on top of the data and services provided by the data platform itself. As such, you are encouraged to contact your SSIMWAVE representative for a demonstration of the UI’s capabilities in addition to a discussion regarding your specific visualization needs and the range of possibilities offered by the platform.
The Insights VOD Monitor app provides a curated GUI for:
- submitting ad hoc analyses to your SSIMPLUS® Analyzer Cluster (Analyze - Submit an analysis),
- viewing the results of in-progress and past analyses (Results - View analysis and optimization results),
- performing detailed frame-level inspections of the results (Viewer - frame/map inspection) and
- defining and submitting optimization requests (Optimize - Submit a video asset for optimization) and
- managing a library of previously submitted analyses (Status - View analysis and optimization status).
The sections below provide a short overview on how to submit and view the results of a simple no-reference (NR) analysis.
Upcoming releases will look to provide additional instruction, through text and video, on how to use the various features of the Insights VOD Monitor App and Web UI. In the meantime, feel free to experiment with thesystem and reach to your SSIMWAVE representative for any questions or demonstrations.
This section is mandatory reading for anyone considering a production deployment of the StreamSmart™ product as the Insights REST API is the mechanism provided for programmatic retrieval of analysis results. The content is divided into sections that focus on the general use of the Insights REST API, including:
- API endpoints,
- API request structure,
- authentication,
- how to retrieve the SSIMPLUS® metrics and measurements for your analyzed videos
- how to configure quality checks to automatically find poor quality assets that suffer from a range of video and audio problems and
- examples with reference material to enable you to build and customize data retrieval to meet your specific workflow needs.
The Insights REST API exposes a single endpoint for all requests: /api/4.0/queries/run/json?cache=false
and each request must be sent using HTTP POST semantics.
The Insights platform supports caching for improved performance, especially from within the Web UI. When using the REST API, however, it is recommended that you bypass the cache by adding the cache=false
query parameter to all your requests, as shown above. In this manner, you will be guaranteed to see the latest data at all times.
Let’s examine the body of a typical Insights POST request shown below:
{
"model": "vod_monitor",
"view": "vod_analysis_results",
"fields": [
"vod_analysis_results.test_id",
"vod_analysis_results.test_video_time_1s",
"vod_analysis_results.ssimplus_viewer_score"
.
.
],
"filters": {
"vod_analysis_results.analysis_uuid": "59508525-070d-428b-8857-d5482bf7c690",
.
.
},
"sorts": [
"vod_analysis_results.test_video_time_1s",
"vod_analysis_results.test_id",
.
.
]
}
- Every Insights request must specify the
model
attribute and, for the StreamSmart™ product, its value should always bevod_monitor
. - Every Insights request must specify a
view
attribute (see Supported Views below). - Every Insights request should specify a list of view
fields
whose data will be included in the response. A field is specified using the<view>.<field_name>
notiation. - An Insights request may specify a list of
filters
which are view fields that are constrained to various values and/or ranges in order to limit/control the data retrieved. The most common filter to use here is<view>.analysis_uuid
, which constrains the results to a single analysis UUID (see example above). Filters become invaluable when your Insights responses return large datasets, as is the case when fetching frame results. - An Insights request may specify a list of
sorts
which are view fields that control the sort order applied to the data in the response. Sorting is particularly useful when retrieving results in a time series.
The examples provided in this sections below use cURL to send requests to the Insights REST API. When learning and/or experimenting with the Insights REST API, you may find it preferrable and easier to use a GUI tool like Postman to submit requests and view their responses. SSIMWAVE has created a Postman API collection and envionment which can be imported and used directly in Postman to aid in this effort. The structure of the Postman collection is meant to be a useful sampling/representation of the various examples presented in the sections below.
Supported views
For the StreamSmart™ product, Insights supports the following views:
View | Details |
---|---|
vod_analysis_results |
This view exposes fields to capture the various SSIMPLUS® measurements and metrics (e.g. SVS, EPS, SBS, CVD, CCM, physical and visual noise, HDR color gamut and luminance) for an analysis over multiple measurement periods (1s, 2s, 5s, 10s, 30s, 60s) and aggregate calculations (min, max, avg), thus enabling one to create a comprehensive time-series view of any supported measurement or metric. Additionally, this view exposes a subview, vod_video_asset_score , that exposes fields to capture the various asset scores (e.g. SVS, EPS, SBS and CCS) for an analysis. |
vod_analysis_frame_results |
This view exposes fields to capture the various SSIMPLUS® measurements and metrics (e.g. SVS, EPS, SBS, CVD, CCM, physical and visual noise, HDR color gamut and luminance) for each frame of the assets included in an analysis. |
vod_video_metadata |
This view exposes fields to capture the video metadata (e.g. title, resolution, dynamic range, encoder, frame rate, time base, aspect ratio, frame count, color primaries and space, color transfer characteristics and content/frame light levels) for the assets included in an analysis. |
vod_status_analysis |
This view exposes fields to capture a summary of the status of an analysis (e.g. percent done, test count, quality check failure count) |
vod_status_test |
This view exposes fields to capture the current status of an analysis (e.g. percent done, current step/state) |
vod_status_updates |
This view exposes fields to capture additional details associated with current status of an analysis (e.g. state details, error details) |
The views above, along with the fields they support, are presented in more detail, along with some examples, in the sections below.
Common view fields
Most Insights views for the StreamSmart™ product expose several common fields which can be used to add detail and context to your Insights responses. Use the following list of common fields:
Field Name | Details |
---|---|
organization |
The top level of the data topology. |
site |
The second level of the data topology. |
analysis_uuid |
The analysis ID |
title |
The name/title of the video. |
test_id |
The test ID of the asset (eg. Source, Anchor 1, Result 1) |
reference_file |
The path of the reference video (applies to FR analysis only) |
reference_video |
Concatenation of the reference video path and identifier (applies to FR analysis only) |
reference_video_no_path |
Concatenation of the reference video file (without path) and identifier (applies to FR analysis only) |
reference_video_identifier |
The reference video identifier (applies to FR analysis only) |
reference_video_json |
The JSON representation of the reference video, exactly as submitted into the API request (applies to FR analysis only) |
test_file |
The path of the subject/test video |
test_video |
Concatenation of the subject/test video path and identifier |
test_video_no_path |
Concatenation of the subject/test video file (without path) and identifier |
test_video_identifier |
The subject/test video identifier |
test_video_json |
The JSON representation of the subject/test video, exactly as submitted into the API request |
stream_index |
The index used to uniquely identify the stream (video/audio) in the test video |
viewer_type |
The viewer type for which scores were calculated |
device.device_name |
The device name |
In the rare case where a view doesn’t happen to support one of the common fields listed above, Insights will simply ignore field and omit it from the response.
The Insights REST API is secured using OAuth 2.0 tokens. As such, you are required to submit a POST request to the login
endpoint in order to receive an OAuth2 token, as shown below:
curl -X POST \
https://insights.ssimwave.com/api/4.0/login \
-header 'Accept: application/application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=<clientID>&client_secret=<clientSecret>'
where <clientID>
and <clientSecret>
are the values you received when setting up your Insights account.
The alphanumeric OAuth2 token will be included in the payload of the response and labelled as access_token
:
{
"access_token": "4RtxmBmskRFfcnvJXjVdXHZbWDbwCdrHHJH8qJNp",
"token_type": "Bearer",
"expires_in": 3600
}
The OAuth2 token must be included as a Bearer token in the Authorization header for all requests sent to an Insights REST API endpoint, as shown below:
curl -X POST \
https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false \
-H 'Authorization: Bearer 4RtxmBmskRFfcnvJXjVdXHZbWDbwCdrHHJH8qJNp'
.
.
.
Each OAuth2 token expires after 1 hour, regardless of activity. To obtain a new token, you will need to resubmit the POST request to the login
endpoint.
The examples in this section use cURL to illustrate sending requests to the Insights REST API. The Bearer tokens used in the headers are for illustrative purposes only and should be replaced by the access_token
you receive from the /login
endpoint, as presented above.
The focus of this section is on the options for retrieving video and audio SSIMPLUS® measurements and metrics from a given analysis. To that end, the discussion will center largely around the following Insights views:
View | Details |
---|---|
vod_analysis_results |
This view exposes fields to capture the various SSIMPLUS® measurements and metrics (e.g. SVS, EPS, SBS, CVD, CCM, physical and visual noise, HDR color gamut and luminance) for an analysis over multiple measurement periods (1s, 2s, 5s, 10s, 30s, 60s) and aggregate calculations (min, max, avg), thus enabling one to create a comprehensive time-series view of any supported measurement or metric. Additionally, this view exposes a subview, vod_video_asset_score , that exposes fields to capture the various asset scores (e.g. SVS, EPS, SBS and CCS) for an analysis. |
vod_analysis_frame_results |
This view exposes fields to capture the various SSIMPLUS® measurements and metrics (e.g. SVS, EPS, SBS, CVD, CCM, physical and visual noise, HDR color gamut and luminance) for each frame of the assets included in an analysis. |
vod_audio_loudness |
This view exposes fields to capture various audio loudness measurements and metrics (e.g. integrated loudness, loudness range, momentary loudness, short-term loudness, true peak level) for the assets included in an analysis. |
vod_cadence_pattern |
This view exposes fields to capture metadata about the various video cadence pattern detected (e.g. start/end time, duration, pattern, pattern offset etc.) for the assets included in an analysis. |
A SSIMPLUS® Asset Score is a summary metric that provides a single value for an entire asset that is more accurate than peforming the mathematical average of the underlying frame scores. StreamSmart™ provides Asset Scores for the following metrics:
- SSIMPLUS® Viewer Score (SVS),
- SSIMPLUS® Encoder Performance Score (EPS) and
- SSIMPLUS® Banding Score (SBS)
Asset SVS, EPS, and SBS are exposed as fields on the vod_video_asset_score
view, which is a subview of the vod_analysis_results
view and can be fetched from Insights as shown below:
curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer NPp7SWngHvMXYJsyPRNQXc6nKGgZ4Dx7FFWsb9S5' \
--data '{
"model": "vod_monitor",
"view": "vod_analysis_results",
"fields": [
"vod_analysis_results.test_id",
"device.device_name",
"vod_analysis_results.reference_video",
"vod_analysis_results.test_video",
"vod_video_asset_score.asset_ssimplus_viewer_score",
"vod_video_asset_score.asset_encoder_performance_score",
"vod_video_asset_score.asset_banding",
"vod_video_asset_score.asset_content_complexity"
],
"filters": {
"vod_analysis_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce"
},
"sorts": [
"vod_analysis_results.test_id"
]
}'
The JSON response payload is as follows:
[
{
"vod_analysis_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce",
"vod_analysis_results.test_id": "Source",
"device.device_name": "OLED65C9PUA",
"vod_analysis_results.reference_video": null,
"vod_analysis_results.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_video_asset_score.asset_ssimplus_viewer_score": 95.375,
"vod_video_asset_score.asset_encoder_performance_score": null,
"vod_video_asset_score.asset_banding": 0,
"vod_analysis_results.asset_content_complexity": 37.4
},
{
"vod_analysis_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce",
"vod_analysis_results.test_id": "Anchor 1",
"device.device_name": "OLED65C9PUA",
"vod_analysis_results.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_analysis_results.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
"vod_video_asset_score.asset_ssimplus_viewer_score": 83.416,
"vod_video_asset_score.asset_encoder_performance_score": 88.02,
"vod_video_asset_score.asset_banding": 18.2,
"vod_analysis_results.asset_content_complexity": null
},
{
"vod_analysis_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce",
"vod_analysis_results.test_id": "Result 1",
"device.device_name": "OLED65C9PUA",
"vod_analysis_results.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_analysis_results.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_41.mp4",
"vod_video_asset_score.asset_ssimplus_viewer_score": 60.048,
"vod_video_asset_score.asset_encoder_performance_score": 60.057,
"vod_video_asset_score.asset_banding": 42.6,
"vod_analysis_results.asset_content_complexity": null
}
]
We can make the following conclusions regarding the values above:
- The reference asset (
dog_running.mp4
) is a reasonably high quality asset as its Asset SVS score of 95 and Asset SBS of 0 places it in the excellent category where impairments, including color banding, are imperceptable for the typical viewer. - The 1-1 subject/test asset (
dog_running_1080_h264_qp_31.mp4
) qualifies as an excellent encode as its Asset SVS is above 80 and, although it has some banding, its Asset SBS of 18.2 falls into the imperceptible category. The Asset EPS of 88 indicates that the encoder did an excellent job of maintaining the reference quality. - The 1-2 subject/test asset (
dog_running_1080_h264_qp_41.mp4
) qualifies as a fair encode as its Asset SVS is only 60 and its Asset SBS of 42 means that the color banding is creeping into the slight annoying category. The Asset EPS score of 60 indicates that the encoder did not do a very good job of maintaining the reference quality, especially considering that the content complexity score of the reference (Asset CCS) is reasonably low at only 37. - The example above is purposefully terse in order to illustrate the fetching of Asset Scores. The
vod_analysis_results
has many additional fields that may of interest to include in your response. Please refer to Supported analysis results fields for details.
For full-reference analyses, the Asset CCS is computed only on the (SDR) reference asset.
When you’re interested in a more granular treatment of the SSIMPLUS® scores for a given asset, you’ll want to use the measurement period fields provided on the vod_analysis_results
view in order to build a time series view of your asset’s scores.
Using the Stream™ On-Demand REST API, let’s submit a no-reference analysis for an HDR asset that configures the SSIMPLUS® Analyzer to capture color information and statistics, in addition to banding, as shown below:
curl --location 'https://localhost/api/v1/analyses' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"content": {
"title": "HDR NR Test"
},
"subjectAssets": [
{
"name": "samsung-demo-reel-version-a.mp4",
"path": "content-similarity-assets/UHD-HDR-MP4-samsung-demo-reel",
"storageLocation": {
"type": "PVC",
"name": "on-201"
},
"hdr": true
}
],
"analyzerConfig": {
"enableBandingDetection": true,
"enableColorInformation": true,
"enableColorStatsCollection": true,
"viewingEnvironments": [
{
"device": {
"name": "oled65c9pua"
},
"viewerType": "TYPICAL"
}
]
}
}'
Next, let’s fetch our analysis results from Insights, including color gamut and luminance data, in a time series view using a measurement period of 2s:
curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 9tVkH455J5Z8X5jGVDBpRbSwBJz5f7vcHTftRv7K' \
--data '{
"model": "vod_monitor",
"view": "vod_analysis_results",
"fields": [
"vod_analysis_results.analysis_uuid",
"vod_analysis_results.test_video_time_2s",
"vod_analysis_results.test_video",
"vod_analysis_results.ssimplus_viewer_score",
"vod_analysis_results.max_ssimplus_viewer_score",
"vod_analysis_results.min_ssimplus_viewer_score",
"vod_analysis_results.avg_banding",
"vod_analysis_results.max_banding",
"vod_analysis_results.min_banding",
"vod_analysis_results.color_primaries",
"vod_analysis_results.color_space",
"vod_analysis_results.color_transfer_characteristics",
"vod_analysis_results.max_content_light_level",
"vod_analysis_results.max_frame_average_light_level",
"vod_analysis_results.color_gamut",
"vod_analysis_results.color_gamut_rec709",
"vod_analysis_results.color_gamut_p3d65",
"vod_analysis_results.color_gamut_rec2020",
"vod_analysis_results.color_gamut_unknown",
"vod_analysis_results.max_pixel_luminance",
"vod_analysis_results.min_pixel_luminance",
"vod_analysis_results.avg_frame_luminance",
"vod_analysis_results.max_frame_luminance",
"vod_analysis_results.min_frame_luminance",
"vod_analysis_results.frame_count"
],
"filters": {
"vod_analysis_results.analysis_uuid": "b9b437a7-f966-4e2b-8bb4-02d9cd1aa2a8"
},
"sorts": [
"vod_analysis_results.test_video_time_2s"
]
}'
The abbreviated JSON response payload is as follows:
[
{
"vod_analysis_results.analysis_uuid": "b9b437a7-f966-4e2b-8bb4-02d9cd1aa2a8",
"vod_analysis_results.test_video_time_2s": "00:00:02",
"vod_analysis_results.test_video": "file:///mnt/on-201/content-similarity-assets/UHD-HDR-MP4-samsung-demo-reel/samsung-demo-reel-version-a.mp4",
"vod_analysis_results.color_primaries": "bt2020",
"vod_analysis_results.color_space": "bt2020nc",
"vod_analysis_results.color_transfer_characteristics": "smpte2084",
"vod_analysis_results.max_content_light_level": 1000,
"vod_analysis_results.max_frame_average_light_level": 1000,
"vod_analysis_results.ssimplus_viewer_score": 97.9375,
"vod_analysis_results.max_ssimplus_viewer_score": 98,
"vod_analysis_results.min_ssimplus_viewer_score": 97.875,
"vod_analysis_results.avg_banding": 53.6875,
"vod_analysis_results.max_banding": 56,
"vod_analysis_results.min_banding": 50,
"vod_analysis_results.color_gamut": "P3D65",
"vod_analysis_results.color_gamut_rec709": 0,
"vod_analysis_results.color_gamut_p3d65": 48,
"vod_analysis_results.color_gamut_rec2020": 0,
"vod_analysis_results.color_gamut_unknown": 0,
"vod_analysis_results.max_pixel_luminance": 10000,
"vod_analysis_results.min_pixel_luminance": 0,
"vod_analysis_results.avg_frame_luminance": 281.4792,
"vod_analysis_results.max_frame_luminance": 283,
"vod_analysis_results.min_frame_luminance": 280,
"vod_analysis_results.frame_count": 48
},
{
"vod_analysis_results.analysis_uuid": "b9b437a7-f966-4e2b-8bb4-02d9cd1aa2a8",
"vod_analysis_results.test_video_time_2s": "00:00:04",
"vod_analysis_results.test_video": "file:///mnt/on-201/content-similarity-assets/UHD-HDR-MP4-samsung-demo-reel/samsung-demo-reel-version-a.mp4",
"vod_analysis_results.color_primaries": "bt2020",
"vod_analysis_results.color_space": "bt2020nc",
"vod_analysis_results.color_transfer_characteristics": "smpte2084",
"vod_analysis_results.max_content_light_level": 1000,
"vod_analysis_results.max_frame_average_light_level": 1000,
"vod_analysis_results.ssimplus_viewer_score": 97.9165,
"vod_analysis_results.max_ssimplus_viewer_score": 98,
"vod_analysis_results.min_ssimplus_viewer_score": 97.833,
"vod_analysis_results.avg_banding": 55.7083,
"vod_analysis_results.max_banding": 61,
"vod_analysis_results.min_banding": 52,
"vod_analysis_results.color_gamut": "P3D65",
"vod_analysis_results.color_gamut_rec709": 0,
"vod_analysis_results.color_gamut_p3d65": 48,
"vod_analysis_results.color_gamut_rec2020": 0,
"vod_analysis_results.color_gamut_unknown": 0,
"vod_analysis_results.max_pixel_luminance": 9043,
"vod_analysis_results.min_pixel_luminance": 0,
"vod_analysis_results.avg_frame_luminance": 280.0417,
"vod_analysis_results.max_frame_luminance": 281,
"vod_analysis_results.min_frame_luminance": 279,
"vod_analysis_results.frame_count": 48
},
{
"vod_analysis_results.analysis_uuid": "b9b437a7-f966-4e2b-8bb4-02d9cd1aa2a8",
"vod_analysis_results.test_video_time_2s": "00:00:06",
"vod_analysis_results.test_video": "file:///mnt/on-201/content-similarity-assets/UHD-HDR-MP4-samsung-demo-reel/samsung-demo-reel-version-a.mp4",
"vod_analysis_results.color_primaries": "bt2020",
"vod_analysis_results.color_space": "bt2020nc",
"vod_analysis_results.color_transfer_characteristics": "smpte2084",
"vod_analysis_results.max_content_light_level": 1000,
"vod_analysis_results.max_frame_average_light_level": 1000,
"vod_analysis_results.ssimplus_viewer_score": 96.5925,
"vod_analysis_results.max_ssimplus_viewer_score": 98,
"vod_analysis_results.min_ssimplus_viewer_score": 95.185,
"vod_analysis_results.avg_banding": 45.3542,
"vod_analysis_results.max_banding": 60,
"vod_analysis_results.min_banding": 28,
"vod_analysis_results.color_gamut": "P3D65",
"vod_analysis_results.color_gamut_rec709": 0,
"vod_analysis_results.color_gamut_p3d65": 48,
"vod_analysis_results.color_gamut_rec2020": 0,
"vod_analysis_results.color_gamut_unknown": 0,
"vod_analysis_results.max_pixel_luminance": 8835,
"vod_analysis_results.min_pixel_luminance": 0,
"vod_analysis_results.avg_frame_luminance": 236.8125,
"vod_analysis_results.max_frame_luminance": 282,
"vod_analysis_results.min_frame_luminance": 184,
"vod_analysis_results.frame_count": 48
},
.
.
.
]
Notice in the results above:
- We have one result in the response for each 2s measurement period (i.e. 2s, 4s, 6s etc).
- Insights provides the mathematical average, minimum and maximum for the various metrics and measurements requested. These values are calculated using the values of all the underlying frames that make up the measurement period (i.e. a frame count of 48 frames in the example above).
- We choose to sort the results based off the chosen measurement period (i.e.
vod_analysis_results.test_video_time_2s
)
When fetching scores for a full-reference (FR) time series view, you are strongly encouraged to use reference video time fields (e.g. vod_analysis_results.reference_video_time_1s
) as your only time-based sort field as the reference time should always be the x-axis. You are also cautioned not to mix different measurement periods between the reference and test.
When fetching scores for a no-reference (NR) time series view, you are strongly encouraged to use test video time fields (e.g. vod_analysis_results.test_video_time_1s
) as your only time-based sort field.
The vod_analysis_results
view exposes fields and subviews (e.g. vod_video_asset_score
) to capture the various SSIMPLUS® measurements and metrics for an analysis over an entire asset (i.e. Asset Scores) and/or various measurement periods (time series). The following subsections lists the various fields of interest on the vod_analysis_results
view (and its subviews) that can be used in the body of any request sent to the Insights REST API.
Metrics and measurements
The Insights vod_analysis_results
view exposes the following list of fields:
Metric/Measurement Field | Details |
---|---|
vod_analysis_results.end_time |
The time when the analysis completed |
vod_analysis_results.avg_bitrate |
The average bitrate of the video |
vod_analysis_results.max_bitrate |
The maximum bitrate of the video |
vod_analysis_results.min_bitrate |
The minimum bitrate of the video |
vod_analysis_results.ssimplus_viewer_score |
The SSIMPLUS® Viewer Score over the aggregated number of frames. |
vod_analysis_results.max_frame_ssimplus_viewer_score |
The maximum per frame SSIMPLUS® Viewer Score over the aggregated number of frames. |
vod_analysis_results.min_ssimplus_viewer_score |
The minimum SSIMPLUS® Viewer Score over the aggregated number of frames. |
vod_analysis_results.encoder_performance_score |
The Encoder Performance Score over the aggregated number of frames. |
vod_analysis_results.min_encoder_performance_score |
The minimum Encoder Performance Score over the aggregated number of frames. |
vod_analysis_results.max_encoder_performance_score |
The maximum Encoder Performance Score over the aggregated number of frames. |
vod_analysis_results.avg_banding |
The average amount of banding during the aggregated number of frames |
vod_analysis_results.max_banding |
The maximum measure of banding during the aggregated number of frames |
vod_analysis_results.min_banding |
The minimum measure of banding during the aggregated number of frames |
vod_analysis_results.avg_content_complexity |
The average content complexity over the aggregated number of frames. |
vod_analysis_results.min_content_complexity |
The minimum content complexity over the aggregated number of frames. |
vod_analysis_results.max_content_complexity |
The maximum content complexity over the aggregated number of frames. |
vod_analysis_results.avg_psnr |
The average PSNR value measured during the aggregated number of frames |
vod_analysis_results.max_psnr |
The maximum PSNR value measured during the aggregated number of frames |
vod_analysis_results.min_psnr |
The minimum PSNR value measured during the aggregated number of frames |
vod_analysis_results.avg_vmaf |
The average VMAF value measured during the aggregated number of frames |
vod_analysis_results.max_vmaf |
The maximum VMAF value measured during the aggregated number of frames |
vod_analysis_results.min_vmaf |
The minimum VMAF value measured during the aggregated number of frames |
vod_analysis_frame_results.color_transfer_characteristics |
The transfer characteristics (e.g. smpte2084) extracted from the video metadata |
vod_analysis_results.avg_color_volume_difference |
The average BT2124 color difference value measured during the aggregated number of frames |
vod_analysis_results.max_color_volume_difference |
The maximum BT2124 color difference value measured during the aggregated number of frames |
vod_analysis_results.min_color_volume_difference |
The minimum BT2124 color difference value measured during the aggregated number of frames |
vod_analysis_results.color_gamut |
The overall detected color gamnut for the frame, set of frames, or asset |
vod_analysis_results.color_gamut_rec709 |
The number of frames where the Rec.705 color space was detected |
vod_analysis_results.color_gamut_p3d65 |
The number of frames where the P3D65 color space was detected |
vod_analysis_results.color_gamut_rec2020 |
The number of frames where the Rec.2020 color space was detected |
vod_analysis_results.color_gamut_unknown |
The number of frames where a known color gamut could not be detected |
vod_analysis_results.min_pixel_luminance |
The lowest measured pixel light level (in nits) in all of the aggregated frames |
vod_analysis_results.max_pixel_luminance |
The highest measured pixel light level (in nits) in all of the aggregated frames. MaxCLL (Maximum Content Light Level) is the value of this field across an entire asset. |
vod_analysis_results.avg_frame_luminance |
The average frame light level (average of the frame’s pixel light levels, in nits) of the aggregated frames. |
vod_analysis_results.min_frame_luminance |
The lowest measured frame light level (average of the frame’s pixel light levels, in nits) in all of the aggregated frames |
vod_analysis_results.max_frame_luminance |
The highest measured frame light level (average of the frame’s pixel light levels, in nits) in all of the aggregated frames. MaxFALL (Maximum Frame Average Light Level) is the value of this field across an entire asset. |
vod_analysis_results.avg_visual_noise |
The average visual noise value measured during the aggregated number of frames |
vod_analysis_results.min_visual_noise |
The minimum visual noise value measured during the aggregated number of frames |
vod_analysis_results.max_visual_noise |
The maximum visual noise value measured during the aggregated number of frames |
vod_analysis_results.avg_physical_noise |
The average physical noise value measured during the aggregated number of frames |
vod_analysis_results.min_physical_noise |
The minimum physical noise value measured during the aggregated number of frames |
vod_analysis_results.max_physical_noise |
The maximum physical noise value measured during the aggregated number of frames |
And the following filter-only fields:
Metric/Measurement Field | Details |
---|---|
vod_analysis_results.use_smpte_timecode |
Apply the SMPTE start timecode to time value fields |
Measurement periods
Insights supports the following measurement period fields:
Measurement Period Field | Details |
---|---|
vod_analysis_results.reference_video_time_1s |
The reference video time in 1 second intervals |
vod_analysis_results.test_video_time_1s |
The test video time in 1 second intervals |
vod_analysis_results.reference_video_time_2s |
The reference video time in 2 second intervals |
vod_analysis_results.test_video_time_2s |
The test video time in 2 second intervals |
vod_analysis_results.reference_video_time_5s |
The reference video time in 5 second intervals |
vod_analysis_results.test_video_time_5s |
The test video time in 5 second intervals |
vod_analysis_results.reference_video_time_10s |
The reference video time in 10 second intervals |
vod_analysis_results.test_video_time_10s |
The test video time in 10 second intervals |
vod_analysis_results.reference_video_time_30s |
The reference video time in 30 second intervals |
vod_analysis_results.test_video_time_30s |
The test video time in 30 second intervals |
vod_analysis_results.reference_video_time_min |
The reference video time in 1 minute intervals |
vod_analysis_results.test_video_time_min |
The test video time in 1 minute intervals |
For some use cases, it may prove desirable to fetch the requested SSIMPLUS® measurements and metrics for each frame in your analyzed assets. Frame level data is provided using the vod_analysis_frame_results
view.
Using the Stream™ On-Demand REST API, we can submit a full-reference analysis for HDR assets that configures the SSIMPLUS® Analyzer to capture color information and statistics, in addition to SBS (color banding), EPS (encoder performance) and CVD (color volume differncing), as shown below:
curl --location 'https://localhost/api/v1/analyses' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"content": {
"title": "HDR FR Demo"
},
"referenceAssets": [
{
"hdr": true,
"name": "demo1_hdr10_ref.mp4",
"storageLocation": {
"type": "PVC",
"name": "on-201"
},
"path": "demo/encode_validation/HDR_demo"
}
],
"subjectAssets": [
{
"hdr": true,
"name": "demo1_hdr10_test_cbr_1920x1080_5400kbps.mp4",
"storageLocation": {
"type": "PVC",
"name": "on-201"
},
"path": "demo/encode_validation/HDR_demo"
}
],
"analyzerConfig": {
"enableBandingDetection": true,
"enableColorInformation": true,
"enableColorStatsCollection": true,
"enableColorVolumeDifference": true,
"viewingEnvironments": [
{
"device": {
"name": "oled65c9pua"
},
"viewerType": "TYPICAL"
},
{
"device": {
"name": "ssimpluscore"
},
"viewerType": "TYPICAL"
},
{
"device": {
"name": "xl2420t"
},
"viewerType": "TYPICAL"
}
]
}
}'
The following Insights request fetches the SVS, EPS, SBS and CVD scores along with the color gamut and pixel and frame luminance values for every frame:
curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 29RJCp5vn6WVt68rj4XMqh3dmyHcFbBxzD2WsM9J' \
--data '{
"model": "vod_monitor",
"view": "vod_analysis_frame_results",
"fields": [
"vod_analysis_frame_results.analysis_uuid",
"vod_analysis_frame_results.reference_video",
"vod_analysis_frame_results.test_video",
"vod_analysis_frame_results.test_id",
"vod_analysis_frame_results.reference_video_time_1frame",
"vod_analysis_frame_results.test_video_time_1frame",
"vod_analysis_frame_results.avg_encoder_performance_score",
"vod_analysis_frame_results.avg_ssimplus_viewer_score",
"vod_analysis_frame_results.avg_banding",
"vod_analysis_frame_results.color_primaries",
"vod_analysis_frame_results.color_space",
"vod_analysis_frame_results.color_transfer_characteristics",
"vod_analysis_frame_results.color_gamut",
"vod_analysis_frame_results.avg_color_volume_difference",
"vod_analysis_frame_results.avg_pixel_luminance",
"vod_analysis_frame_results.min_pixel_luminance",
"vod_analysis_frame_results.min_pixel_luminance_x",
"vod_analysis_frame_results.min_pixel_luminance_y",
"vod_analysis_frame_results.max_pixel_luminance",
"vod_analysis_frame_results.max_pixel_luminance_x",
"vod_analysis_frame_results.max_pixel_luminance_y",
"vod_analysis_frame_results.avg_frame_luminance",
"device.device_name"
],
"filters": {
"vod_analysis_frame_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce"
},
"sorts": [
"vod_analysis_frame_results.reference_video_time_1frame",
"vod_analysis_frame_results.test_id"
]
}'
The snippet below represents a small sampling of the response output:
[
.
.
{
"vod_analysis_frame_results.analysis_uuid": "0e37bc9b-34ca-45ea-aaf5-da713fada956",
"vod_analysis_frame_results.reference_video": null,
"vod_analysis_frame_results.test_video": "file:///mnt/on-201/demo/encode_validation/HDR_demo/demo1_hdr10_ref.mp4",
"vod_analysis_frame_results.test_id": "1",
"vod_analysis_frame_results.reference_video_time_1frame": "00:00:04:23",
"vod_analysis_frame_results.test_video_time_1frame": "00:00:04:23",
"vod_analysis_frame_results.color_primaries": "bt2020",
"vod_analysis_frame_results.color_space": "bt2020nc",
"vod_analysis_frame_results.color_transfer_characteristics": "smpte2084",
"device.device_name": "OLED65C9PUA",
"vod_analysis_frame_results.avg_encoder_performance_score": null,
"vod_analysis_frame_results.avg_ssimplus_viewer_score": 100,
"vod_analysis_frame_results.avg_banding": 50,
"vod_analysis_frame_results.color_gamut": "P3D65",
"vod_analysis_frame_results.avg_color_volume_difference": null,
"vod_analysis_frame_results.min_pixel_luminance": 0,
"vod_analysis_frame_results.min_pixel_luminance_x": 1170,
"vod_analysis_frame_results.min_pixel_luminance_y": 0,
"vod_analysis_frame_results.max_pixel_luminance": 749,
"vod_analysis_frame_results.max_pixel_luminance_x": 2490,
"vod_analysis_frame_results.max_pixel_luminance_y": 1028,
"vod_analysis_frame_results.avg_frame_luminance": 37
},
{
"vod_analysis_frame_results.analysis_uuid": "0e37bc9b-34ca-45ea-aaf5-da713fada956",
"vod_analysis_frame_results.reference_video": "file:///mnt/on-201/demo/encode_validation/HDR_demo/demo1_hdr10_ref.mp4",
"vod_analysis_frame_results.test_video": "file:///mnt/on-201/demo/encode_validation/HDR_demo/demo1_hdr10_test_cbr_1920x1080_5400kbps.mp4",
"vod_analysis_frame_results.test_id": "1-1",
"vod_analysis_frame_results.reference_video_time_1frame": "00:00:04:23",
"vod_analysis_frame_results.test_video_time_1frame": "00:00:04:23",
"vod_analysis_frame_results.color_primaries": "bt2020",
"vod_analysis_frame_results.color_space": "bt2020nc",
"vod_analysis_frame_results.color_transfer_characteristics": "smpte2084",
"device.device_name": "OLED65C9PUA",
"vod_analysis_frame_results.avg_encoder_performance_score": 92,
"vod_analysis_frame_results.avg_ssimplus_viewer_score": 89,
"vod_analysis_frame_results.avg_banding": 23,
"vod_analysis_frame_results.color_gamut": "P3D65",
"vod_analysis_frame_results.avg_color_volume_difference": 8.52735,
"vod_analysis_frame_results.min_pixel_luminance": 0,
"vod_analysis_frame_results.min_pixel_luminance_x": 1198,
"vod_analysis_frame_results.min_pixel_luminance_y": 0,
"vod_analysis_frame_results.max_pixel_luminance": 1237,
"vod_analysis_frame_results.max_pixel_luminance_x": 300,
"vod_analysis_frame_results.max_pixel_luminance_y": 674,
"vod_analysis_frame_results.avg_frame_luminance": 37
},
.
.
]
Please note the following about the Insights request and response above:
- While the
vod_analysis_frame_results
view exposes fields for the average, minimum and maximum values for most of the SSIMPLUS® measurements and metrics, one need only request the average (e.g.avg_ssimplus_viewer_score
) since the granularity of this view is already at the lowest (i.e. frame) level. Requesting the minimum and maximum fields will result in identical values to that of the average. - Where pixel values are provided, however, average, minimum and maximum will have proper meaning and different results (i.e. see
avg/min/max_pixel_luminance
above). - The
vod_analysis_frame_results
view exposes two fields,reference_video_time_1frame
andtest_video_time_1frame
, to capture the respective time within the reference and subject/test videos. These time fields are of the format HH:MM:SS:FF, where FF is the frame number within the given second and the possible values depend on the framerate of the underlying asset.
While there is no limit on the size of a given response from the Insights REST API, be aware that fetching all frame scores for an analysis may result in extremely large responses that size in megabytes, depending on the number of assets in your analysis, the length of the assets, the framerate of the assets and the number of devices scored.
As with all other queries submitted to the Insights REST API, you are encouraged to use filters to help reduce the size of your results and focus on specific parts of your data set. Using the query above, we can add a subject/test asset filter (i.e. vod_analysis_frame_results.test_id
) and device filter (i.e. device.device_name
) to return all the frame scores just for the subject/test asset identified by 1-1 and the OLED65C9PUA
device:
curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 29RJCp5vn6WVt68rj4XMqh3dmyHcFbBxzD2WsM9J' \
--data '{
"model": "vod_monitor",
"view": "vod_analysis_frame_results",
"fields": [
"vod_analysis_frame_results.analysis_uuid",
"vod_analysis_frame_results.reference_video",
"vod_analysis_frame_results.test_video",
"vod_analysis_frame_results.test_id",
"vod_analysis_frame_results.reference_video_time_1frame",
"vod_analysis_frame_results.test_video_time_1frame",
"vod_analysis_frame_results.avg_encoder_performance_score",
"vod_analysis_frame_results.avg_ssimplus_viewer_score",
"vod_analysis_frame_results.avg_banding",
"vod_analysis_frame_results.color_primaries",
"vod_analysis_frame_results.color_space",
"vod_analysis_frame_results.color_transfer_characteristics",
"vod_analysis_frame_results.color_gamut",
"vod_analysis_frame_results.avg_color_volume_difference",
"vod_analysis_frame_results.avg_pixel_luminance",
"vod_analysis_frame_results.min_pixel_luminance",
"vod_analysis_frame_results.min_pixel_luminance_x",
"vod_analysis_frame_results.min_pixel_luminance_y",
"vod_analysis_frame_results.max_pixel_luminance",
"vod_analysis_frame_results.max_pixel_luminance_x",
"vod_analysis_frame_results.max_pixel_luminance_y",
"vod_analysis_frame_results.avg_frame_luminance",
"device.device_name"
],
"filters": {
"vod_analysis_frame_results.analysis_uuid": "de66d3ab-7469-476b-9d15-965e173811ce",
"vod_analysis_frame_results.test_id": "1-1",
"device.device_name": "OLED65C9PUA"
},
"sorts": [
"vod_analysis_frame_results.reference_video_time_1frame",
"vod_analysis_frame_results.test_id"
]
}'
Supported view fields
The vod_analysis_frame_results
view exposes fields to capture the various SSIMPLUS® measurements and metrics (e.g. SVS, EPS, SBS, CVD, CCM, physical and visual noise, HDR color gamut and luminance) for each frame of the assets included in an analysis. The following section lists the various fields of interest on the vod_analysis_frame_results
view that can be used in the body of any request sent to the Insights REST API.
Metric/Measurement Field | Details |
---|---|
vod_analysis_frame_results.reference_video_time_1frame |
The reference video time with frame number within each second |
vod_analysis_frame_results.test_video_time_1frame |
The test video time with frame number within each second |
vod_analysis_frame_results.end_time |
The time when the analysis completed |
vod_analysis_frame_results.color_gamut |
The overall detected color gamnut for the frame, set of frames, or asset |
vod_analysis_frame_results.color_gamut_rec709 |
The number of frames where the Rec.705 color space was detected |
vod_analysis_frame_results.color_gamut_p3d65 |
The number of frames where the P3D65 color space was detected |
vod_analysis_frame_results.color_gamut_rec2020 |
The number of frames where the Rec.2020 color space was detected |
vod_analysis_frame_results.color_gamut_unknown |
The number of frames where a known color gamut could not be detected |
vod_analysis_frame_results.avg_color_volume_difference |
The average BT2124 color difference value measured during the aggregated number of frames |
vod_analysis_frame_results.max_color_volume_difference |
The maximum BT2124 color difference value measured during the aggregated number of frames |
vod_analysis_frame_results.min_color_volume_difference |
The minimum BT2124 color difference value measured during the aggregated number of frames |
vod_analysis_frame_results.avg_visual_noise |
The average visual noise value measured during the aggregated number of frames |
vod_analysis_frame_results.max_visual_noise |
The maximum visual noise value measured during the aggregated number of frames |
vod_analysis_frame_results.min_visual_noise |
The minimum visual noise value measured during the aggregated number of frames |
vod_analysis_frame_results.avg_physical_noise |
The average physical noise value measured during the aggregated number of frames |
vod_analysis_frame_results.max_physical_noise |
The maximum physical noise value measured during the aggregated number of frames |
vod_analysis_frame_results.min_physical_noise |
The minimum physical noise value measured during the aggregated number of frames |
vod_analysis_frame_results.max_pixel_luminance |
The highest measured pixel light level (in nits) in all of the aggregated frames. MaxCLL (Maximum Content Light Level) is the value of this field across an entire asset. |
vod_analysis_frame_results.max_pixel_luminance_x |
The image X coordinate of the highest measured pixel light level in the frame. |
vod_analysis_frame_results.max_pixel_luminance_y |
The image Y coordinate of the highest measured pixel light level in the frame. |
vod_analysis_frame_results.min_pixel_luminance |
The lowest measured pixel light level (in nits) in all of the aggregated frames |
vod_analysis_frame_results.min_pixel_luminance_x |
The image X coordinate of the lowest measured pixel light level in the frame. |
vod_analysis_frame_results.min_pixel_luminance_y |
The image Y coordinate of the lowest measured pixel light level in the frame. |
vod_analysis_frame_results.avg_frame_luminance |
The average frame light level (average of the frame’s pixel light levels, in nits) of the aggregated frames. |
vod_analysis_frame_results.max_frame_luminance |
The highest measured frame light level (average of the frame’s pixel light levels, in nits) in all of the aggregated frames. MaxFALL (Maximum Frame Average Light Level) is the value of this field across an entire asset. |
vod_analysis_frame_results.min_frame_luminance |
The lowest measured frame light level (average of the frame’s pixel light levels, in nits) in all of the aggregated frames |
vod_analysis_frame_results.avg_encoder_performance_score |
The average Encoder Performance Score over the aggregated number of frames. |
vod_analysis_frame_results.max_encoder_performance_score |
The maximum Encoder Performance Score over the aggregated number of frames. |
vod_analysis_frame_results.min_encoder_performance_score |
The minimum Encoder Performance Score over the aggregated number of frames. |
vod_analysis_frame_results.avg_psnr |
The average PSNR value measured during the aggregated number of frames |
vod_analysis_frame_results.max_psnr |
The maximum PSNR value measured during the aggregated number of frames |
vod_analysis_frame_results.min_psnr |
The minimum PSNR value measured during the aggregated number of frames |
vod_analysis_frame_results.avg_bytes |
The average number of bytes in a frame |
vod_analysis_frame_results.max_bytes |
The maximum number of bytes in a frame |
vod_analysis_frame_results.min_bytes |
The minimum number of bytes in a frame |
vod_analysis_frame_results.avg_banding |
The average amount of banding during the aggregated number of frames |
vod_analysis_frame_results.max_banding |
The maximum measure of banding during the aggregated number of frames |
vod_analysis_frame_results.min_banding |
The minimum measure of banding during the aggregated number of frames |
vod_analysis_frame_results.avg_vmaf |
The average VMAF value measured during the aggregated number of frames |
vod_analysis_frame_results.max_vmaf |
The maximum VMAF value measured during the aggregated number of frames |
vod_analysis_frame_results.min_vmaf |
The minimum VMAF value measured during the aggregated number of frames |
vod_analysis_frame_results.avg_ssimplus_viewer_score |
The average SSIMPLUS® Viewer Score over the aggregated number of frames. |
vod_analysis_frame_results.max_ssimplus_viewer_score |
The maximum SSIMPLUS® Viewer Score over the aggregated number of frames. |
vod_analysis_frame_results.min_ssimplus_viewer_score |
The minimum SSIMPLUS® Viewer Score over the aggregated number of frames. |
And the following filter-only fields:
Metric/Measurement Field | Details |
---|---|
vod_analysis_results.use_smpte_timecode |
Apply the SMPTE start timecode to time value fields |
vod_analysis_frame_results.time_mode |
Display real time or SMPTE timecode |
vod_analysis_frame_results.use_drop_frame |
Enables/disables drop frames |
An analysis will work its way through several states on its way to a success or failure. The SSIMPLUS® Analyzer sends a notification for each state transition and event update to the Insights platform. Please refer to the following table for a list of all the possible states and their meanings:
STATE | DESCRIPTION |
---|---|
Queued |
Indicates that the system has successfully received an analysis request and a process has been scheduled to perform the single-ended or full-reference analysis of the video asset(s). |
Estimating |
Indicates that the system has scheduled, is in the process of completing or has successfully completed the task to estimate the amount of computing resources (RAM, CPU) needed to complete the analysis. Once the estimation is complete, the status message will include the computing resources required. |
Initializing |
Indicates that the SSIMPLUS® Analyzer has been successfully started. The status message captures details on how the Analyzer was started, configured and the version in use. |
Aligning |
Indicates that the SSIMPLUS® Analyzer is in the process of completing or has completed the temporal alignment of the video assets. While in progress, the status message will include the percentage completed. Once complete, the status message will include the offsets being used in both the reference and subject/test assets. This state applies only to full-reference analyses and requires that temporal alignment is enabled (default). |
Analyzing |
Indicates the SSIMPLUS® Analyzer is in the process of completing or has completed analyzing the video asset(s). While in progress, the status message will include the percentage completed, along with the total number of frames. Once completed, the requested measurements and metrics are ready for post-processing by the Insights data platform. |
Results Ready |
Indicates that the Insights data platform has completed all post-processing of the analysis results and that they are ready to be retrieved/used. This is a terminal state. |
Failed |
Indicates that the system was unable to process one or more of the asset(s) in the analysis request. The message associated with this status should indicate the nature of the failure. A failure to estimate is generally not considered critical and the system should make every effort to analyze the asset(s) using default values for the computing resources. Other failures, such an inability to achieve temporal alignment with the chosen configuration values, may require remedial action to be applied in order to achieve success. This is a terminal state. |
The SSIMPLUS® Analyzer Cluster is designed to process large volumes of assets, of varying complexity and duration, concurrently. Due to the non-deterministic order of this processing, it becomes important for users of the system to be able to see the status of their analyses, if only to know when they can expect to fetch the completed results. The Insights REST API exposes 3 views for retreiving analysis status information:
View | Details |
---|---|
vod_status_analysis |
This view exposes fields to capture a summary of the status of an analysis (e.g. percent done, test count, quality check failure count) |
vod_status_test |
This view exposes fields to capture the current status of an analysis (e.g. percent done, current step/state) |
vod_status_updates |
This view exposes fields to capture additional details associated with current status of an analysis (e.g. state details, error details) |
Use the vod_status_analysis
view and an analysis UUID filter to see a summary or roll-up status of a given analysis, as shown below:
curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 7FYtb3FB39ngTgDXF4WsCXb2NMvR3PRvhJGgypVx' \
--data '{
"model": "vod_monitor",
"view": "vod_status_analysis",
"fields": [
"vod_status_analysis.analysis_uuid",
"vod_status_analysis.time",
"vod_status_analysis.min_time",
"vod_status_analysis.test_id",
"vod_status_analysis.test_video",
"vod_status_analysis.reference_video",
"vod_status_analysis.stage",
"vod_status_analysis.percent_done",
"vod_status_analysis.test_count",
"vod_quality_checks.count"
],
"filters": {
"vod_status_analysis.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b"
}
}'
Consider the following JSON sample response:
[
{
"vod_status_analysis.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_analysis.time": "2023-08-30 16:41:00",
"vod_status_analysis.min_time": "2023-08-30 16:40:14",
"vod_status_analysis.stage": "Results Ready",
"vod_status_analysis.percent_done": 100,
"vod_status_analysis.test_count": 3,
"vod_quality_checks.count": 4
}
]
Note in the example response above:
- the
test_count
value indicates that there are 3 separate NR and/or FR analyses being performed and - the
count
value indicates that there were 4 quality check failures found.
To fetch the status for a given analysis and to see the details of all no-reference and/or full-reference analyses being performed, use the vod_status_test
view and filter on the analysis UUID, as shown below:
curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer mFs5sKXwcVnCS4FC6kKbdFYqzcQYqVmHCKnKsNk5' \
--data '{
"model": "vod_monitor",
"view": "vod_status_test",
"fields": [
"vod_status_test.analysis_uuid",
"vod_status_test.time",
"vod_status_test.test_id",
"vod_status_test.test_video",
"vod_status_test.reference_video",
"vod_status_test.stage",
"vod_status_test.percent_done"
],
"filters": {
"vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b"
},
"sorts": [
"vod_status_test.test_id"
]
}'
Assuming that 2e4db929-d00b-493a-98fb-77e321f3219b
represents a full-reference analysis, you may see a response like the following if you query for the status immediately after submitting via the Stream™ On-Demand REST API:
[
{
"vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_test.time": "2023-08-30 16:40:36",
"vod_status_test.test_id": "1",
"vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_test.reference_video": null,
"vod_status_test.stage": "Analyzing",
"vod_status_test.percent_done": 33.33
},
{
"vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_test.time": "2023-08-30 16:40:37",
"vod_status_test.test_id": "1-1",
"vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
"vod_status_test.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_test.stage": "Analyzing",
"vod_status_test.percent_done": 20.12
},
{
"vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_test.time": "2023-08-30 16:40:37",
"vod_status_test.test_id": "1-2",
"vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_41.mp4",
"vod_status_test.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_test.stage": "Aligning",
"vod_status_test.percent_done": 88.75
}
]
Notice the following in the response above:
- The NR analysis of 1 (
dog_running.mp4
) 33% complete. - The FR analysis of 1-1 (
dog_running_1080_h264_qp_31.mp4
) has been temporarily aligned with the reference (i.e.Aligning
state is finished) and is 20% of the way through its analysis. - The 1-2 asset (
dog_running_1080_h264_qp_41.mp4
) is still being temporarily aligned with the reference and, as such, has not yet started its FR analysis.
Repeating the request above some minutes later results in the following response:
[
{
"vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_test.time": "2023-08-30 16:40:55",
"vod_status_test.test_id": "1",
"vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_test.reference_video": null,
"vod_status_test.stage": "Results Ready",
"vod_status_test.percent_done": 100
},
{
"vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_test.time": "2023-08-30 16:41:00",
"vod_status_test.test_id": "1-1",
"vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
"vod_status_test.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_test.stage": "Results Ready",
"vod_status_test.percent_done": 100
},
{
"vod_status_test.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_test.time": "2023-08-30 16:40:59",
"vod_status_test.test_id": "1-2",
"vod_status_test.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_41.mp4",
"vod_status_test.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_test.stage": "Results Ready",
"vod_status_test.percent_done": 100
}
]
In the result above, all analyses are complete and their results are ready to be used.
If you an encounter an error or unexpected behavior with a given analysis, you can choose to fetch a log of all the status messages for the analysis using the vod_status_updates
view and filters on the vod_status_updates.analysis_uuid
and vod_status_updates.test_id
, as shown below:
curl --location 'https://insights.ssimwave.com/api/4.0/queries/run/json?cache=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer rjV3dmFFrWfNWKPMmtcRtQdrPtjhYczCBFHPbn5z' \
--data '{
"model": "vod_monitor",
"view": "vod_status_updates",
"fields": [
"vod_status_updates.analysis_uuid",
"vod_status_updates.time",
"vod_status_updates.test_id",
"vod_status_updates.test_video",
"vod_status_updates.reference_video",
"vod_status_updates.stage",
"vod_status_updates.percent_done",
"vod_status_updates.details",
"vod_status_updates.error_details"
],
"filters": {
"vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_updates.test_id": "Result 1"
},
"sorts": [
"vod_status_updates.test_id",
"vod_status_updates.time desc"
]
}'
Fetch the vod_status_updates.details
and vod_status_updates.error_details
to see detailed messages and errors.
Since the volume of status updates can be extremely large, you are strongly encouraged to filter on both vod_status_updates.test_id
and vod_status_updates.stage
in order to reduce the volume of the response and focus on the asset of interest.
Sort on the vod_status_updates.time
field in descending order to see the most recent messages first.
An abbreviated sample JSON response would be as follows:
[
{
"vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_updates.time": "2023-08-30 16:41:01.176000",
"vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_updates.test_id": "1-1",
"vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
"vod_status_updates.stage": "Analyzing",
"vod_status_updates.details": "{\"result\":\"pass\",\"total\":492}",
"vod_status_updates.error_details": null,
"vod_status_updates.percent_done": 1
},
{
"vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_updates.time": "2023-08-30 16:41:01.122000",
"vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_updates.test_id": "1-1",
"vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
"vod_status_updates.stage": "Analyzing",
"vod_status_updates.details": "{\"progress\":{\"current\":492,\"total\":492}}",
"vod_status_updates.error_details": null,
"vod_status_updates.percent_done": 1
},
{
"vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_updates.time": "2023-08-30 16:41:00.937000",
"vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_updates.test_id": "1-1",
"vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
"vod_status_updates.stage": "Analyzing",
"vod_status_updates.details": null,
"vod_status_updates.error_details": null,
"vod_status_updates.percent_done": 1
},
{
"vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_updates.time": "2023-08-30 16:41:00.937000",
"vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_updates.test_id": "1-1",
"vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
"vod_status_updates.stage": "Results Ready",
"vod_status_updates.details": null,
"vod_status_updates.error_details": null,
"vod_status_updates.percent_done": 1
},
{
"vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_updates.time": "2023-08-30 16:41:00.615000",
"vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_updates.test_id": "1-1",
"vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
"vod_status_updates.stage": "Analyzing",
"vod_status_updates.details": "{\"progress\":{\"current\":485,\"total\":492}}",
"vod_status_updates.error_details": null,
"vod_status_updates.percent_done": 0.9858
},
{
"vod_status_updates.analysis_uuid": "2e4db929-d00b-493a-98fb-77e321f3219b",
"vod_status_updates.time": "2023-08-30 16:40:59.613000",
"vod_status_updates.reference_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/source/dog_running.mp4",
"vod_status_updates.test_id": "1-1",
"vod_status_updates.test_video": "file:///mnt/video-files-pvc/royalty_free/dog_running/outputs/dog_running_1080_h264_qp_31.mp4",
"vod_status_updates.stage": "Analyzing",
"vod_status_updates.details": "{\"progress\":{\"current\":466,\"total\":492}}",
"vod_status_updates.error_details": null,
"vod_status_updates.percent_done": 0.9472
},
.
.
.
]
If the SSIMPLUS® Analyzer encounters an error while processing an asset, it will report the content of the error in the vod_status_updates.error_details
field for inspection. Many errors will contain sufficient information such that a remedy can be readily applied and the analysis rerun with minimal effort (i.e. fixing an invalid asset path or filename). Some errors are more serious and may require input from a video analyst and/or manipulation of the assets themselves. A failure to achieve automatic alignment between the reference and subject asset, for example, will result in an alignment error and manual actions must be taken to apply fixes before resubmitting the analysis. If an error does occur for which the cause or solution is unknown, please post a trouble ticket using the SSIMWAVE Help Center.
The following table lists the various fields of interest on the vod_status_analysis
, vod_status_test
and vod_status_updates
views for extracting data on the status of an analysis. You can use these fields in the body of any request sent to the Insights REST API.
Metric/Measurement Field | Details |
---|---|
vod_status_analysis.min_time |
The time that the analysis started |
vod_status_analysis.time |
The time the status was updated |
vod_status_analysis.step |
The current step of analysis |
vod_status_analysis.percent_done |
The completion percentage of the current stage |
vod_status_analysis.test_count |
The number of files analyzed |
vod_quality_checks.count |
The number of quality check failures |
Metric/Measurement Field | Details |
---|---|
vod_status_test.min_time |
The time that the analysis started |
vod_status_test.time |
The time the status was updated |
vod_status_test.step |
The current step of analysis |
vod_status_test.percent_done |
The completion percentage of the current stage |
vod_quality_checks.count |
The number of quality check failures |
vod_status_test.asset_ssimplus_viewer_score |
The SSIMPLUS® Asset Viewer Score |
Metric/Measurement Field | Details |
---|---|
vod_status_updates.time |
The time the event occurred |
vod_status_updates.max_event_time |
The time that the event started |
vod_status_updates.min_event_time |
The latest time associated with the event |
vod_status_updates.stage |
The current stage of the analysis |
vod_status_updates.percent_done |
The completion percentage of the current stage |
vod_status_updates.details |
Additional details related to the event |
vod_status_updates.error_details |
The error description extracted from status updates that indicate that there was an error |
Installation and configuration
Both the IMAX Stream™ On-Demand Platform and Insights support being used in a headless/programmatic manner via the Stream™ On-Demand REST API and Insights REST API, respectively. To familiarize yourself with the API experience, SSIMWAVE offers Postman collection and environment files which can be imported and configured into the aforementioned tool by following the instructions below:
-
Download, install and launch the Postman app.
-
Under Settings->General make sure you set the Max response size in MB to 0 so no responses from the Insight’s REST API are truncated. This is especially useful if you plan to fetch results at per-frame granularity.
-
Under Settings->General make sure that the SSL certificate verifiation is set to Off.
-
(Recommended) Create a new workspace within Postman for isolation and ease of organization.
TipUse a workspace name that indicates the product and version, such as StreamSmart™ vX.YY
-
Import the Stream™ Postman collection and environment files (File->Import).
-
From the Collections view (left sidebar), you should see a folder called IMAX Stream™ with a set of subfolders and requests therein.
-
Make sure Postman is using the
IMAX Stream™
environment you imported above by selecting it from the Environment drop-down near the top right corner of the Postman GUI. -
Edit the
IMAX Stream™
environment by clicking on the eyeball button (Environment Quick Look) to the right of the drop-down and then the Edit link in the top right corner of the popup. Postman should launch a new tab showing an editable table of the environment variables.NoteModern versions of Postman also have an Environments button/view that can be selected from the sidebar on the left side of the UI.
-
In the table presented, modify the CURRENT VALUE column for the following key/value pairs:
VARIABLE CURRENT VALUE stream_host <stream_host>
insights_client_id <insights_client_id>
insights_client_secret <insights_client_secret>
where
<stream_host>
is the fully-qualified domain name (FQDN) or IP address of your IMAX Stream deployment and<insights_client_id>
and<insights_client_secret>
are the values sent to you by your SSIMWAVE representative after completing the Getting Started section of the Insights Data Platform.
Depending on the details of your deployment, the value for
<stream_host>
will differ:- For production VPC bare-metal/other deployments,
<stream_host>
will be the FQDN of the Ingress you installed in step 5 - For production VPC/EKS deployments,
<stream_host>
will be the hostname you selected when executing the Installation Prerequisites - For fixed scale deployments using an AMI deployed to an EC2 instance,
<stream_host>
will be the public DNS entry of your EC2 instance - For fixed scale deployments on bare metal using a virtual machine (i.e. OVA/QEMU),
<stream_host>
will be the IP address/FQDN of your virtual machine instance (Don’t forget to include the port if you used NAT.)
Submitting requests and viewing responses
At this point, you should be able to start submitting requests in the StreamSmart™ collection. In general, you will want to repeat the following process to submit new optimizations and view their results via the REST APIs:
-
Submit a new optimization by choosing the New optimization (FFmpeg) request example (listed under the StreamSmart™->Submit New Optimization folder).
-
Select the Body tab from the main view and edit the contents of your POST request to suit your needs (see the Stream™ On-Demand REST API and/or Insights REST API above for examples and details).
For example, the following optimization request modifications indicate that:
- our source asset lives in an S3 bucket
- we want to optimize the FFmpeg encode specified by the provided FFmpeg command
- the output should be written to a different S3 bucket
{ "title": "My First Optimization", "config": { "encodes": [{ "commands": ["ffmpeg -r 24 -i {INPUT_LOCATION} -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range mpeg -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=50:keyint_min=50:scenecut=0:stitchable=1\" -profile:v high -level:v 4.1 -b:v 5000k -maxrate 6250k -bufsize 10000k -r 24 -vf scale=1920x1080 -an {OUTPUT_LOCATION}"], "outputLocation": { "path": "tests/test1.ts", "storageLocation": { "type": "S3", "name": "encoding-test-assets" } } }], "inputLocation": { "key": "tests/test1-result.mov", "storageLocation": { "type": "S3", "name": "encoding-test-outputs" } } } }
-
Click the Send button.
-
Your response will be displayed in the Response container of the Postman GUI (to the right or bottom of the UI).
-
While the optimization is running, run the
Analysis Status->Status summary
query in the Insights REST API->Optimization Status folder to see the status and progress.ImportantThe Postman collection and environment work together to remember the UUID of the last successfully submitted optimization. As such, any request run from the Stream™ On-Demand REST API folder will have its resulting analysis UUID value stored in Postman and automatically fed into any subsequently executed query from the Insights REST API folder, to save you the bother of repeatedly copying and pasting the UUID. Additionally, all queries in the Insights REST API folder will automatically fetch and submit the OAuth tokens needed for secure interaction with the Insights REST API. If you wish to fetch results for a prior/different analysis, simply edit the environment paste the UUID of the desired analysis into the current value for
last_analysis_uuid
. -
(Optional) Select the Body tab from the main view and alter the details of your POST request to match your use case (see Insights REST API for examples and details).
NoteMany of the requests under the Insights REST API folder do not require editing in order to function unless a specific filter and/or sorting field/order is desired.
-
Click the Send button.
-
Your responses will be displayed in the Response container of the Postman GUI (to the right or bottom of the UI). Note: Postman also supports saving/exporting results to a file.
StreamSmart™ uses the following metrics to measure and optimize the quality of encoded video:
- no-reference SSIMPLUS® Viewer Score (NR SVS),
- full-reference SSIMPLUS® Viewer Score (FR SVS),
- SSIMPLUS® Encoder Performance Score (EPS),
- SSIMPLUS® Banding Score (SBS),
No-reference SSIMPLUS® Viewer Score (NR SVS)
The no-reference SSIMPLUS® Viewer Score (also known as Source SSIMPLUS® VIewer Score” or “NR SVS”, ) is a metric that assesses the quality of a source file or stream in a no-reference (NR) manner. This means that it does not require any additional information or reference material in order to evaluate the quality of the video content.
The NR SVS metric is highly accurate, with a strong correlation to both the SSIMPLUS reference-based score and the mean opinion score (MOS), and it uses deep neural networks (DNN) to make its evaluations. It is also computationally efficient, making it suitable for use at any stage of the content processing and delivery chain. The NR SVS metric supports all commonly used codecs, including ProRes, J2K, AVC, HEVC, MPEG2, and VP9, as well as all commonly used content attributes, including HDR content.
Full-reference SSIMPLUS® Viewer Score (FR SVS)
Sometimes referred to as “FR SVS” or “SSIMPLUS® Output Viewer Score”, it assesses the perceptual quality of an (encoded or processed) output in reference to a degraded (or pristine) source.
The quality of the output (FR SVS) is determined by both the quality of the source (NR SVS) and the performance of the encoder (EPS). If the encoder is working well but the source material is poor, the output quality will also be poor. This is because encoding always results in some loss of information. Thus, the output quality is a combination of the source quality, the full-reference quality EPS, and the psychovisual effects included in the model.
The metric supports all impairments, content attributes, and content types, as well as cross-resolution and cross-frame rate analysis. SSIMWAVE is currently developing supporting cross-dynamic range analysis and tone-mapped quality assessment. SSIMPLUS® correlates linearly with perceived quality and covers the full quality range.
The score ranges from 0 to 100, where 0=totally unwatchable and 100=pristine, without visual impairments).
The metric supports all commonly used codecs for source degradations, including ProRes, J2K, AVC, HEVC, MPEG2, and VP9, and it is display device and viewing conditions adaptive.
SSIMPLUS® Encoder Performance Score (EPS)
SSIMPLUS® Encoder Performance Score assesses the performance of an encoder or transcoder by comparing its output with the source. The metric assumes that the source is pristine or nearly pristine, and focuses solely on measuring the degradation introduced by encoding impairments. EPS supports all impairments, content attributes, content types, cross-resolution, and cross-frame rate analysis. We are currently developing support for cross-dynamic range analysis. The metric correlates linearly with perceived quality and covers the full quality range. It also automatically aligns a source with output across resolutions and frame rates. It computes the quality and saliency maps to normalize across all content types. EPS is adaptive to device display and viewing conditions.
Reference/Source | Output |
---|---|
![]() |
![]() |
The SSIMPLUS® quality map is generated as part of the SSIMPLUS® Viewer Score computation:
Encoding Examples
Example 1 | |
---|---|
The source video is high quality, and the encoder or transcoder is performing well. | |
![]() |
Example 2 | |
---|---|
The source video is high quality, but the encoder or transcoder is performing poorly. | |
![]() |
Example 3 | |
---|---|
The source video is poor quality, but the encoder or transcoder is performing well. | |
![]() |
Example 4 | |
---|---|
The source video is poor quality, and the encoder or transcoder is performing poorly. | |
![]() |
SSIMPLUS® Banding Score (SBS)
A SSIMPLUS® Banding Score (SBS) is a measurement of the amount of color banding that is present within the asset. Banding, otherwise known as color contouring, is a common artifact of the video compression process and due to the quantization introduced by the video codec. It is most obvious in areas where the content calls for the rendering of smooth gradient regions, such as the sky, water or ground. In these regions, pixel values that are meant to be represented uniquely so as to provide a gentle transition from one shade or color to another are, instead, aggregated into a much smaller set of values creating discrete bands of colors.
The SSIMPLUS® algorithm analyzes each frame of your asset for the presence of banding and records a score indicating the severity of the banding, according to the following scale:
- [ 0- 20] Imperceptible
- [21- 40] Perceptible but not annoying
- [41- 60] Slightly annoying
- [61- 80] Annoying
- [81-100] Very annoying
The following frame is an example of an SBS of 0, meaning that there is no discernible banding present:
This next frame is example of an SBS of 68, which would qualify as annoying. Notice the discrete bands of colors both in the sky and the asphalt track.
In addition to extracting scores based on measurement periods, Insights provides Asset Scores which employ additional intelligence beyond simple mathematical averages of individual frames scores or measurement periods to arrive at a single score for an entire asset.
A SSIMPLUS® Asset Score is a summary metric that assesses the overall experience of the viewer after watching a full asset or program or just a part of an asset or program. It is designed to accurately model the memory behavior of the human visual system and to take into account the response of the human visual system to variations in the viewer experience. For example, in typical scenarios, video quality changes significantly over time due to a number of reasons. Viewers’ opinion of video quality changes relies heavily on the amount, duration, and direction of such a change. SSIMPLUS® uses the Expectation Confirmation Theory to model the asymmetric behavior of the Human Visual System.
SSIMPLUS® VOD Monitor provides both the average and asset scores for the metrics:
- SSIMPLUS® Viewer Score (SVS),
- SSIMPLUS® Encoder Performance Score (EPS),
- SSIMPLUS® Banding Score (SBS)
It is generally recommended to use the Asset Score rather than the average score for content lengths that are longer than one minute in duration.
The Asset SVS, for example, provides a measurement that can be used to judge the overall quality of the entire asset, as perceived by the human visual system, taking into account the lingering effect of poor quality segments. The Asset SVS is particularly useful when your goal is to perform source selection on a population of assets by first removing all those with unacceptably low overall quality. Similarly, the Asset Encoder Performance Score (EPS) can provide a single judgement of the encoder’s performance.
The following scale provides the guide for how to interpret SSIMPLUS® (Asset) SVS and (Asset) EPS scores:
- Excellent = Impairments are imperceptible
- Good = Impairments are perceptible but not annoying
- Fair = Impairments are slightly annoying
- Poor = Impairments are annoying
- Bad = Impairments are very annoying
The following sections represent the various deployment guides for the customer-deployed portion of the StreamSmart™ product, otherwise referred to as the IMAX Stream™ On-Demand Platform. This is the portion of the system that acts as the “eyes” of the system and is installed with read-only access to your video assets and whose purpose is to analyze/score the content and securely stream the results to Insights. Please consult the Architecture Overview section for your deployment model to see more details.
The guides are divided into three sections:
-
Elastic scale deployments
These deployments are for those customers that are ready to deploy the product into their production workflow, having leveraged the StreamSmart™ and Insights REST APIs to achieve the desired level of integration. The IMAX Stream™ On-Demand Platform is installed in such a manner as to take full-advantage of all features expected of a production system (i.e. high availability, elastic scalability).
-
Fixed scale deployments
These deployments are for those customers that are trialing the StreamSmart™ product or have deployed the system for light/ad-hoc workloads where production-level features such as high availability and elastic scalability are unnecessary.
This deployment model addresses those customers wishing to deploy StreamSmart™ into an AWS Elastic Cloud Compute (EC2) instance for trial/lab usage. The preferred solution here is to use an Amazon Machine Image (AMI) which contains a full deployment of StreamSmart™ that can be deployed to the customer’s AWS account.
It is strongly encouraged that someone with at least a basic understanding of the following AWS concepts and services perform the installation:
- AWS Web console,
- CloudFormation (creating/deleting stacks),
- EC2 (launching, configuring, instance profiles, security groups) and
- S3 buckets.
An AMI deployment has some madatory costs, as described below:
-
EC2 instance
This is the cost of Amazon EC2 instance that launches the AMI described herein. The cost here varies depending on the EC2 instance type you choose and whether you are using spot instances or have a savings plan with Amazon. For more information and current prices, please refer to Amazon’s EC2 On-Demaind Instance Pricing.
-
StreamSmart™ minute usage fees
These fees are the charges per minute of output video analysis charged by SSIMWAVE. For those that deploy the product through AWS Marketplace, there is pricing information available on the site. SSIMWAVE does support private offerings via AWS Marketplace and access to the AMI outside of AWS Marketplace. Please contact your SSIMWAVE represenative for details.
The following steps are prerequisites for a successful deployment:
-
Provide your SSIMWAVE representative with the AWS account number and region that you will be using to launch the StreamSmart™ AMI.
SSIMWAVE needs your account number and region in order to share the AMI with the appropriate account. Your SSIMWAVE representative will let you know once this has been done.ImportantYou are required to deploy your EC2 instance in the same region as the S3 bucket(s) holding your video assets. This restriction has the further advantage of avoiding any cross-region data transfer costs.
-
The AWS user account or role that you will use for deployment has the followng minimum permissions:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "Statement1", "Effect": "Allow", "Action": [ "cloudformation:CreateStack", "cloudformation:DeleteStack", "cloudformation:UpdateStack", "ec2:DescribeVpcs", "ec2:CreateKeyPair", "ec2:CreateSecurityGroup", "ec2:DescribeAvailabilityZones", "ec2:DescribeSecurityGroups", "ec2:DescribeKeyPairs", "ec2:DeleteKeyPair", "ec2:DeleteSecurityGroup", "ec2:AuthorizeSecurityGroupEgress", "ec2:AuthorizeSecurityGroupIngress", "ec2:RevokeSecurityGroupIngress", "ec2:RevokeSecurityGroupEgress", "ec2:RunInstances", "ec2:DescribeInstances", "ec2:StopInstances", "ec2:TerminateInstances", "ssm:PutParameter", "ssm:DeleteParameter" ], "Resource": [ "*" ] } ] }
-
Your video assets are stored in Amazon S3.
-
Your AWS account allows for the creation of EC2 instances with the following resources:
c5.24xlarge
orc5a.24xlarge
instance type and a- 2TB attached EBS volume (General Purpose SSD - gp3).
-
The network ACL associated with your VPC and the security group associated with your EC2 instance must allow inbound/ingress and outbound/egress internet access on port
443
. -
You’ve created an account to access your results within SSIMWAVE’s Insights data platform.
-
You’ve received a StreamSmart™ feature license from your SSIMWAVE representative containing values for the following, according to your purchase/trial agreement:
- Alphanumeric license verification key
- Audio loudness measurements
- Banding detection scoring
- Frame and map (banding, quality, color volume difference) generation
- Color gamut and stats generation
- Color volume difference map generation
- Content complexity scoring
- Expiration date (the day on which your license expires)
- Frame level scoring
- HDR10 & Dolby Vision support
- Video, audio and quality check options
- Insights data streaming credentials
- Insights REST API (system-level) credentials
- Insights customer organization and site names
The following steps and examples will use the AWS Web Console. Please contact your SSIMWAVE representative if you have any questions.
-
Login to your AWS account using the AWS Web Console and pick your target region.
-
From the AWS UI console, choose Services -> Management & Governance -> CloudFormation.
-
Click Create stack to create a new stack.
Choose the Template is ready and Amazon S3 URL options, as shown below. The IMAX CloudFormation template you want can be found at the S3 URL:
-
Specify stack details
-
Name the stack appropriately for your deployed version (e.g. imax-stream-v3).
-
Provide a CIDR block that includes the public IP addresses of all end users of your IMAX StreamSmart | On-Demand EC2 instance, as everyone needs access to the web/HTTPS interface.
TipMany corporate LANs are configured to use a single IP address/range for all outbound/external Internet access. You may find it convenient to use this IP address/range here, knowing that this should cover all users on your local network.
-
Provide a CIDR block for the administrator/deployer of your IMAX StreamSmart | On-Demand EC2 instance.
The administrator/deployer needs access to the SSH (port 22) interface on your instance for potential deployment and troubleshooting activities. You are encouraged to use a single IP address here (i.e. x.x.x.x/32) where possible.NoteIf you are unable to isolate a single IP address for this administrator role and/or you would like to exercise a higher level of security, you are encouraged to remove the SSH inbound rule below from the resulting EC2 security group after the CloudFormation stack completes and add it back only if/when you have additional deployment or troubleshooting activities to perform.
-
Pick a VPC to use when deploying your IMAX StreamSmart | On-Demand EC2 instance.
You need to ensure that the network access control list (ACL) associated with your target VPC allows for the inbound and outbound rules below:
Inbound Rules
Type Protocol Port range Source Description SSH TCP 22 <customer_web_access_cidr>
SSH access for deployment/troubleshooting HTTPS TCP 443 <customer_web_access_cidr>
HTTPS access for StreamSmart™ where
<customer_web_access_cidr>
is the CIDR you used for StreamSmart web (HTTPS) access above.Outbound Rules
Type Protocol Port range Destination Description HTTPS TCP 443 All (0.0.0.0/0) IMAX Insights and IMAX Insights REST API -
Pick an EC2 instance type and backing EBS volume.
The EBS storage volume is used to hold the reference video you are optimizing, the encoded outputs and any frame captures, banding, quality and/or color volume difference maps generated as part of inspecting the results. While the default/minimum size here is 2TB, you should adjust this value such that it is sufficient to store 1.5 times the size of the largest reference video you expect to optimize.
-
-
Move through the wizard accepting all defaults and click on Submit.
-
Verify that the stack creation completes successfully and click on the Outputs tab.
Record the PublicDNS value of your IMAX StreamSmart | On-Demand EC2 instance and use it as the
<ec2_public_dns>
value in the steps below. -
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 (i.e.<ec2_public_dns>
).- Login to your Insights Account.
- Click on the user icon in the top right corner of the UI and pick
Account
from the dropdown menu. - Scroll down to the
Additional Details
section and change yourVOD Api Host
value to match the public IPv4 DNS (or IP) value of your EC2 instance (i.e. <ec2_public_dns>). - Click Save.
TipYour 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.
ImportantAll users of StreamSmart™ with their own Insights account, will need to make this same adjustment to their
VOD API Host
setting under their Insights account. -
Verify that your StreamSmart™ instance is operational.
To verify the system status, load the following URL:
https://<ec2_public_dns>/status
into your web browser, where<ec2_public_dns>
is the public host name of your EC2 instance.ImportantIt takes several minutes for the virtual machine to initialize and load the StreamSmart™ system. During this time, you may not get a response from the
https://<ec2_public_dns>/status
URL or you may see HTTP errors like: 404 (Not Found), 503 (Service Unavailable) or 500 (Proxy Error); this is expected. Simply refresh your browser every 30s until you see the correct content.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 direct your browser to accept the certificate and proceed to the site.
All users of the StreamSmart™ system will need to accept this certificate, so please direct your end user population to load
https://<ec2_public_dns>/status
into their browsers once.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:- 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. -
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.ImportantIt 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 revisithttps://<ec2_public_dns>/status
where all services and the final outcome should show asREADY
.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.
-
Provide access to your S3 bucket(s).
We need to add secrets to your deployment in order to read from the S3 buckets holding your video assets. Each S3 bucket requires a secret with field values for the bucket name, key id and access key. You can use the /s3AccessSecret endpoint on the Stream™ On-Demand REST API to create a conformant secret, as shown below:
curl -kvi -X PUT "https://<ec2_public_dns>/api/v1/s3AccessSecret" \ -H "Content-Type: application/json" \ -d '{ "bucketName": "mybucket", "clientId": "AKIAIOSFODNN7EXAMPLE", "clientSecret": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" }'
-
(Optional) Configure access to your AWS Elemental MediaConvert (EMC) endpoint.
For those that wish to use AWS EMC with StreamSmart, you must tell the system about your EMC endpoint. You can use the /configurations endpoint to create a secret configuration for your EMC endpoint, as shown below:
curl -kvi -X POST "https://<ec2_public_dns>/api/v1/configurations" \ -H "Content-Type: application/json" \ -d '{ "type": "SECRET", "id": "mediaconvert-config", "config": { "data": { "accesskey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "keyid": "AKIAIOSFODNN7EXAMPLE", "region": "us-east-1", "url": "https://vasjpylpa.mediaconvert.us-east-1.amazonaws.com", } } }'
ImportantPlease substitute the
accesskey
,keyid
andregion
values above for the details that apply to your specific AWS EMC endpoint.Be careful to ensure that you use the
mediaconvert-config
name when submitting your (secret) EMC configuration. -
(Optional) Download the Privacy Enhanced Mail (PEM) file associated witn your IMAX StreamSmart | On-Demand EC2 instance.
Run the following commands from a CLI:
keyPairID=$(aws ec2 --region=<region> describe-key-pairs --filters Name=key-name,Values=imax-streamsmart --query KeyPairs[*].KeyPairId --output text) aws ssm --region=<region> get-parameter --name /ec2/keypair/$keyPairID --with-decryption --query Parameter.Value --output text > imax-streamsmart.pem chmod 400 imax-streamsmart.pem
where
<region>
is your chosen region (e.g.us-east-1
).NoteThe commands above require the AWS CLI.
The commands above will create a PEM file that is used for SSH access to your IMAX StreamSmart | On-Demand EC2 instance and only needed by the administrator/deployer role for deployment and/or troubleshooting activities.
Upgrading Versions (~ 25 mins)
Upgrading to a new version of the StreamSmart™ AMI is simply a matter of terminating/destroying your existing instance and installing the new one by repeating the installation steps above for the new AMI.
- Login to your AWS account using the AWS Web Console.
- From the AWS UI console, choose Services -> Management & Governance -> CloudFormation.
- Select the stack you created when deploying your current IMAX StreamSmart | On-Demand EC2 instance (i.e. imax-stream-v3).
- Click on the Delete button to delete the stack. Deleting the stack should terminate the current IMAX StreamSmart | On-Demand EC2 instance and remove any supporting AWS objects.
- Follow the Installation instructions above for the new StreamSmart™ AMI.
Once the StreamSmart™ system is running, you are ready to submit new analyses and inspect the results.
For new users or those that are most comfortable with a GUI, you are encouraged to use the Insights VOD Monitor app to submit a new analysis. This app allows you to submit any number of no-reference (NR) or full-reference (FR) analyses and inspect their results using the built-in Insights dashboards. Please look here, should you need some help using the UI.
StreamSmart™ provides TLS through the use of self-signed certificates. As a first step towards using the GUI, you need to direct your browser to accept the certificate. One way to do this is to load https://<ec2_public_dns>/status
into your browser, where <ec2_public_dns>
represents the public IPv4 DNS value for your EC2 instance. Your browser will likely flag the site as a potential security risk. Please tell your browser to accept the certificate and proceed to the site. Each user of the StreamSmart™ system will need to accept this certificate into their browsers once.
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/v1/analyses \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"content": {
"title": "Rocket Launch Analysis - S3 NR - Test"
},
"subjectAssets": [
{
"name": "rocket_launch_1080_h265_qp_31.mp4",
"storageLocation": {
"type": "S3",
"name": "ssimwave-video-assets"
},
"path": "royalty_free/rocket_launch/outputs"
}
],
"analyzerConfig": {
"enableBandingDetection": true
}
}'
Take care to edit the URL used in the example above so that <ec2_public_dns>
is the public IPv4 hostname (or IP) of your EC2 instance.
Once you have successfully deployed and verfied that your StreamSmart™ AMI is working, you are strongly encouraged to read Using StreamSmart™ where you will be provided with a more detailed overview of the StreamSmart™ system and given specific steps for further product education.
If you encounter trouble or have any questions about installing/launching your SSIMPLUS® VOD Monitor AMI, please create a support ticket by using the SSIMWAVE Help Center or feel free to reach out to your SSIMWAVE representative directly.
Enabling the Kubernetes Dashboard
For fixed scale deployments of SSIMPLUS® VOD Monitor in AWS, you can optionally (and temporarily) enable the Kubernetes Dashboard. The dashboard provides a Web UI for interacting with Kubernetes which can be especially useful in troubleshooting sessions with SSIMWAVE support. To enable the Kubernetes Dashboard, please follow the steps below:
-
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.ImportantThe 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!
-
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.
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:
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!
This deployment model delivers SSIMPLUS® VOD Monitor as a virtual machine file and is meant for those customers wishing to deploy the product on to a bare metal server for trial and/or lab usage purposes. The solution options here are to use either an Open Virtual Appliance (OVA) or an open-source Quick Emulator (QEMU) container with KVM acceleration, both of which contain a full deployment of SSIMPLUS® VOD Monitor that is configured to work in environments with modest hardware capabilities, where the benefit of elastic scaling available in a cloud environment is unnecessary or unavailable.
The OVA solution has the advantage of working with several of the most common virtualization players and, as such, has good cross-platform support, including the Windows platform. Our OVA solution has been verified to work with both Oracle’s VirtualBox and VMware ESXi.
The QEMU container runs on any Linux-based systems and has been verified to work with tools such as VirtManager and oVirt.
It is recommended that someone with basic working knowledge of the following concepts perform the installation:
- Linux CLI basics (SSH) and
- basic networking (bridge and/or NAT adapters, HTTP/S proxy, IP addresses, hostnames).
For OVA deployments, knowledge or experience with VirtualBox is useful.
For QEMU deployments, knowledge of VirtManager is useful.
The following steps are prerequisites for a successful deployment:
-
From your SSIMWAVE representative, you should receive or request the following items:
-
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
-
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
whereMAJOR
,MINOR
,PATCH
andBUILD
represent the major, minor, patch and build numbers of the target build andYYYY
,HH
andMM
are the year, hour and date of the virtual machine’s creation.
-
-
The physical/virtual host machine must have the following minimum hardware resources that can be dedicated to the SSIMPLUS® VOD Monitor virtual machine:
- 24G RAM (32G RAM preferred)
- 24 CPU cores (32 cores preferred)
- 25G of free disk space (100G preferred)
NoteYou are strongly encouraged to use the preferred values above, when possible.
-
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
NoteYou 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.
-
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
-
The video assets you wish to process must be either:
- mounted on the host machine in a folder that can be shared with SSIMPLUS® VOD Monitor virtual machine through the virtualization player,
- mountable as a Linux file system within the SSIMPLUS® VOD Monitor virtual machine (you can SSH into the instance and install drivers as needed),
- available via a Network File System (NFS),
- 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
-
Your local network must allow outbound internet access on port
443
to the following hosts:NoteThe SSIMPLUS® VOD Monitor virtual machine supports using SOCKS5 and HTTP/S forward proxies, if required. Please see the Installation section below for configuration details.
-
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.
-
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.
-
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
) -
Configure your virtual machine network settings.
You will need the SSIMPLUS® VOD Monitor virtual machine to be accessible on your local network. Similarly, the virtual machine must be able to connect to the internet (i.e. on port 443 to the Insights hosts discussed in the Insights Prerequisites). There are two documented approaches below: Bridge Adapter and NAT.
Bridged Adapter
If the local network, on which your host machine resides, has a DHCP server then the simplest and preferred approach is to configure your virtual machine with a bridge adapter that is bound to your host machine’s physical network interface. This will ensure that, once the virtual machine is started, it will get its own IP address from your DHCP server and would then be directly accessible from any machine on your local network. The caveat here is that if you don’t want the IP address to change when the host or virtual machine is rebooted, you may need to modify your DHCP server to allow static assignment based on the interface’s MAC address or provide some alternative DNS solution.vboxmanage modifyvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" \ --nic1 bridged --bridgeadapter1 $(route | grep '^default' | grep -o '[^ ]*$' | head -n 1)
Notice in the example above
route | grep '^default' | grep -o '[^ ]*$' | head -n 1
is automated way of determining the default adapter on your host machine. If you’d prefer, you can substitute that logic with the name of the appropriate adapter (e.g.eth0
).Network Address Translation - NAT
If you don’t have a DHCP server available, you can use Network Address Translation (NAT) and port forwarding to provide access to your virtual machine via your host machine. The following steps can be used with VirtualBox:vboxmanage modifyvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" \ --nic1 nat --natpf1 "vodmonitorhttps,tcp,,8443,,443" --natpf1 "vodmonitorssh,tcp,,2222,,22"
Here we instruct VirtualBox to forward all packets that come to the host machine on port 8443 to port 443 (HTTPS) on the virtual machine. The same is done for port 2222 and the standard SSH port, 22. Using this approach you can access the Stream™ On-Demand REST API using the hostname/IP of your host machine and the 8443 port. The following examples are common URLs used to interact with the Stream™ On-Demand REST API, modified to account for NAT and the port forwarding example above:
https://<hostmachine>:8443/status
(System Status)https://<hostmachine>:8443/api/v1/analyses
(Analysis submission endpoint)
For more details on VirtualBox networking options, please take a look here.
-
(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
.ImportantPlease ensure that host folder names use only alphanumeric characters, dashes (
-
) and/or underscores (_
) in their names. -
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.
-
(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. -
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
).ImportantThe 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). -
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.NoteYou 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
).- From your machine (i.e. not the host machine for the VM), login to your Insights Account.
- Click on the user icon in the top right corner of the UI and pick
Account
from the dropdown menu. - Scroll down to the
Additional Details
section and change yourVOD Api Host
value to match your virtual machine’s IP/FQDN. - Click Save.
ImportantEach user of the SSIMPLUS® VOD Monitor system will need to use the same value for their
VOD API Host
in their Insights account.. -
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.ImportantIt takes several minutes for the virtual machine to initialize and load the StreamSmart™ system. During this time, you may not get a response from the
https://<ssimplus-vod-monitor>/status
URL or you may see HTTP errors like: 404 (Not Found), 503 (Service Unavailable) or 500 (Proxy Error); this is expected. Simply refresh your browser every 30s until you see the correct content.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 direct your browser to accept the certificate and proceed to the site.
All users of the StreamSmart™ system will need to accept this certificate, so please direct your end user population to load
https://<ssimplus-vod-monitor>/status
into their browsers once.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:- 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. -
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.ImportantIt 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 revisithttps://<ssimplus-vod-monitor>/status
where all services and the final outcome should show asREADY
.Additionally, you can expand the License information section to verify that the details of your feature license match with your expectations.
-
(Optional) Configure access to your AWS Elemental MediaConvert (EMC) endpoint.
For those that wish to use AWS EMC with StreamSmart, you must tell the system about your EMC endpoint. You can use the /configurations endpoint to create a secret configuration for your EMC endpoint, as shown below:
curl -kvi -X POST "https://<ec2_public_dns>/api/v1/configurations" \ -H "Content-Type: application/json" \ -d '{ "type": "SECRET", "id": "mediaconvert-config", "config": { "data": { "accesskey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "keyid": "AKIAIOSFODNN7EXAMPLE", "region": "us-east-1", "url": "https://vasjpylpa.mediaconvert.us-east-1.amazonaws.com", } } }'
ImportantPlease substitute the
accesskey
,keyid
andregion
values above for the details that apply to your specific AWS EMC endpoint.Be careful to ensure that you use the
mediaconvert-config
name when submitting your (secret) EMC configuration.
Upgrading Versions (~ 30 mins)
Upgrading to a new version of the SSIMPLUS® VOD Monitor virtual machine is simply a matter of powering off your existing instance and installing the new one by repeating the Installation steps above for the new file.
-
Power off your existing SSIMPLUS® VOD Monitor virtual machine
vboxmanage controlvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" poweroff
-
(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. -
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:
-
Power off your existing SSIMPLUS® VOD Monitor virtual machine
vboxmanage controlvm "simplus-vod-monitor_2.21.0-25_09-07-2023_19-16" poweroff
-
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.
-
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.
-
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 asREADY
.NoteIt 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.
-
If you are not using root, make sure you’ve add your user to the
libvirt
andkvm
groups and then logout and back in.sudo usermod -aG libvirt $(whoami) sudo usermod -aG kvm $(whoami) logout
-
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.NoteDepending 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. -
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.
NoteNote 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.
-
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 berunning
. -
(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.
NoteIf 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.
-
(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"
ImportantThe 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. -
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 or192.168.122.2
if you’re using NAT).ImportantThe 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 or192.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 or192.168.122.2
if you’re using NAT). -
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.- From your machine (i.e. not the host machine for the VM), login to your Insights Account.
- Click on the user icon in the top right corner of the UI and pick
Account
from the dropdown menu. - Scroll down to the
Additional Details
section and change yourVOD Api Host
value to match your virtual machine’s IP/FQDN. - Click Save.
ImportantEach user of the SSIMPLUS® VOD Monitor system will need to use the same value for their
VOD API Host
in their Insights account.. -
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.ImportantIt takes several minutes for the virtual machine to initialize and load the StreamSmart™ system. During this time, you may not get a response from the
https://<ssimplus-vod-monitor>/status
URL or you may see HTTP errors like: 404 (Not Found), 503 (Service Unavailable) or 500 (Proxy Error); this is expected. Simply refresh your browser every 30s until you see the correct content.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 direct your browser to accept the certificate and proceed to the site.
All users of the StreamSmart™ system will need to accept this certificate, so please direct your end user population to load
https://<ssimplus-vod-monitor>/status
into their browsers once.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:- 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. -
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.ImportantIt 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 revisithttps://<ssimplus-vod-monitor>/status
where all services and the final outcome should show asREADY
.Additionally, you can expand the License information section to verify that the details of your feature license match with your expectations.
-
(Optional) Configure access to your AWS Elemental MediaConvert (EMC) endpoint.
For those that wish to use AWS EMC with StreamSmart, you must tell the system about your EMC endpoint. You can use the /configurations endpoint to create a secret configuration for your EMC endpoint, as shown below:
curl -kvi -X POST "https://<ec2_public_dns>/api/v1/configurations" \ -H "Content-Type: application/json" \ -d '{ "type": "SECRET", "id": "mediaconvert-config", "config": { "data": { "accesskey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "keyid": "AKIAIOSFODNN7EXAMPLE", "region": "us-east-1", "url": "https://vasjpylpa.mediaconvert.us-east-1.amazonaws.com", } } }'
ImportantPlease substitute the
accesskey
,keyid
andregion
values above for the details that apply to your specific AWS EMC endpoint.Be careful to ensure that you use the
mediaconvert-config
name when submitting your (secret) EMC configuration.
Upgrading Versions (~ 30 mins)
Upgrading to a new version of the SSIMPLUS® VOD Monitor virtual machine is simply a matter of powering off your existing instance and installing the new one by repeating the Installation steps above for the new file.
-
Power off your existing SSIMPLUS® VOD Monitor virtual machine.
virsh shutdown "ssimplus-vod-monitor"
-
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. -
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.
-
Power off your existing SSIMPLUS® VOD Monitor virtual machine.
virsh shutdown "ssimplus-vod-monitor"
-
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.
-
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.
-
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 asREADY
.NoteIt 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:
- mounted on the host machine in a folder that is then shared with SSIMPLUS® VOD Monitor virtual machine through the virtualization player,
- mountable as a Linux file system within the SSIMPLUS® VOD Monitor virtual machine (you can SSH into the instance and install drivers as needed),
- available via a Network File System (NFS),
- 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"
}
The JSON snippet above presupposes accessing the SSIMPLUS® VOD Monitor using the REST API. However, the approach and values above apply equally to the Insights VOD Monitor app from the Insights Web UI.
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"
}
The JSON snippet above presupposes accessing the SSIMPLUS® VOD Monitor using the REST API. However, the approach and values above apply equally to the Insights VOD Monitor app from the Insights Web UI.
Any mounted file system or folder in the virtual machine that you wish to access using the local-media
PVC must support read-only access by the ubuntu
user and group (i.e. uid=1000(ubuntu) gid=1000(ubuntu)).
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
).
The NFS folder path must be accessible without needing any specific user/group permissions and/or credentials.
The SSIMPLUS® VOD Monitor virtual machine has SSH access using the following credentials user: ubuntu, password: ubuntu
. Take care to adjust for any port forwarding or hostname changes, if applicable.
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 SSIMPLUS® VOD Monitor virtual machine has SSH access using the following credentials user: ubuntu, password: ubuntu
. Take care to adjust for any port forwarding or hostname changes, if applicable.
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"
}
You don’t need to specify credentials as part of the storageLocation
above when using Kubernetes secrets to access the AWS S3 buckets. Translating this to the Insights VOD Monitor app in the Insights Web UI, however, requires you to pick Kubernetes Secret
from the Credentials
dropdown.
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.
SSIMPLUS® VOD Monitor virtual machine provides TLS through the use of self-signed certificates. As a first step towards using the GUI, you need to direct your browser to accept the certificate. One way to do this is to load https://<ssimplus-vod-monitor>/status
into your browser, where <ssimplus-vod-monitor>
is the IP address/FQDN of your SSIMPLUS® VOD Monitor virtual machine instance (adjusting for any port forwarding that applies). 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 into their browsers once.
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/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
}
}'
Take care to adjust the URL used in the example above for any port forwarding or hostname changes, if applicable.
Once you have successfully deployed and verfied that your SSIMPLUS® VOD Monitor virtual machine is working, you are strongly encouraged to read Using SSIMPLUS VOD Monitor where you will be provided with a more detailed overview of the SSIMPLUS® VOD Monitor system and given specific steps for further product education.
If you encounter trouble or have any questions about installing/launching your SSIMPLUS® VOD Monitor virtual machine, please create a support ticket by using the SSIMWAVE Help Center or feel free to reach out to your SSIMWAVE representative directly.
Enabling the Kubernetes Dashboard
For fixed scale deployments of SSIMPLUS® VOD Monitor in a virtual machine, you can optionally (and temporarily) enable the Kubernetes Dashboard. The dashboard provides a Web UI for interacting with Kubernetes which can be especially useful in troubleshooting sessions with SSIMWAVE support. To enable the Kubernetes Dashboard, please follow the steps below:
-
Deploy and configure the Kubernetes Dashboard
From a CLI, run the following command:
ssh ubuntu@<ssimplus-vod-monitor> "~/startKubernetesDashboard.sh"
ImportantThe 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!
-
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
ImportantIf 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"
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:
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!
These deployments are for those customers that are ready to deploy the product into their production workflow, having leveraged the StreamSmart™ and Insights REST APIs to achieve the desired level of integration. The IMAX Stream™ On-Demand Platform is installed in such a manner as to take full-advantage of all features expected of a production system (i.e. high availability, elastic scalability).
The following deployment guide identifies the actions required to deploy StreamSmart™ as managed service within a target AWS account. As a managed service, SSIMWAVE is responsible for deploying, managing, monitoring and upgrading StreamSmart™ and the customer is responsible for providing the AWS account that will act as the infrastructure to support the system. An architecture diagram of the AWS managed service is available here.
In order to facilitate a smooth deployment experience, SSIMWAVE has created instructions that require a minimum of manual steps by relying on a curated set of CloudFormation templates to add and configure the necessary AWS resources and services. As you will read below, to execute these templates, you need to create a CloudFormation stack for a given template, supply the required template parameters and then execute the stack. These tasks can be done using either the AWS web console or the CLI. These instructions herein walk you through the process using the AWS web console supplementing when useful with screen captures.
The following 30 minute companion video walks through the installation prerequisites and post-installation steps below:
It is strongly recommended that someone with at least a basic understanding of the following concepts and AWS services perform the installation:
- CloudFormation (creating and configuring stacks),
- IAM (policy, roles),
- basic networking (Route 53, CIDR blocks, hostnames, DNS A and CNAME records) and
- Amazon S3 buckets.
-
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.
-
Login to the AWS console and pick your target region.
ImportantIt is strongly recommended that you use an AWS user/role that has the
AWS::AdminstratorAccess
policy so that you have all of the permissions required to execute the CloudFormation scripts in later steps.Use the AWS region selector in the web console to select the target region into which you want to install the IMAX Stream™ On-Demand Platform.
ImportantIn order to avoid egress data costs, you are strongly encouraged to choose the same region as the S3 bucket(s) holding the video assets you will want to use with StreamSmart™.
-
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.yamlThis 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.
- IAM policies
-
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.
-
-
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.
-
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:
-
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.}
ImportantAt 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.
-
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.
NoteAll 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.
The following sections should be completed only after the SSIMPLUS® Analyzer Cluster has been deployed and you have received such notification from your SSIMWAVE representative.
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):
DNS Record Type | Name | Value |
---|---|---|
A | vodmonitor.companyx.com | a012c3d440fd94c3c8fabfeb1ead3645-66809327.us-east-1.elb.amazonaws.com. |
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.
- 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.
- 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.
-
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.
-
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.
- Name the stack ssimplus-vod-monitor-managed-service-s3-read-only-role.
-
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.
Complete/repeat steps 4, 5 and 6 below for each S3 bucket that you wish to use with the SSIMPLUS® Analyzer Cluster.
-
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.
-
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.
- 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.
-
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.
-
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"
.
In the example above, the role ARN arn:aws:iam::077383753319:role/aws-reserved/sso.amazonaws.com/AWSReservedSSO_companyx-vod-production_d28f75fb83bd9880
is being used for example/illustrative purposes only. The ARN for your specific installation will be provided as part of the Installation Prerequisites.
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/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 following sections provide instructions for deploying the IMAX Stream™ On-Demand Platform into a supported Kubernetes environment, including bare-metal and virtual private clouds (VPC) like AWS Elastic Kubernetes Service (EKS). Some instructions may be specific to the target Kubernetes environment and will be denoted as such (i.e. AWS Elastic Kubernetes Service (EKS) and Bare-Metal/Other).
For an EKS deployment, it is strongly encouraged that someone with strong working knowledge of the following concepts and AWS services perform the installation:
- EKS (eksctl),
- EFS (Elastic File System),
- AWS CLI,
- ECR (Elastic Container Registry),
- Kubernetes (kubectl, deployment descriptors, YAML, pods, services),
- CloudFormation (creating and configuring stacks),
- IAM (policy, roles),
- basic networking (CIDR blocks, hostnames, DNS A and CNAME records, TLS certificates),
- Bash shell scripts and
- Amazon S3 buckets.
For a deployment on bare-metal, it is strongly encouraged that someone with strong working knowledge of the following concepts perform the installation:
- Kubernetes (kubectl, deployment descriptors, YAML, ingress, pods, services, persistent volumes/claims),
- basic networking (CIDR blocks, hostnames, DNS A and CNAME records, TLS certificates) and
- Bash shell scripts.
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:
-
From your SSIMWAVE representative, you should receive or request the following items:
-
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
-
Google Cloud Repository (GCR) service account JSON key file providing temporary access to SSIMWAVE’s
gcr.io/ssimwave-vodmonitor
repository. -
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
whereMAJOR
,MINOR
,PATCH
andBUILD
represent the major, minor, patch and build numbers of the purchased build.
-
-
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
-
The machine you are using to deploy has the Docker engine installed.
-
The machine you are using to deploy has the Helm binary installed.
-
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
-
On the machine you are using to deploy, follow only the prerequisites identified here for installing
kubectl
andeksctl
.After following the prerequisites, you should have installed and configured the
kubectl
andeksctl
binaries and established IAM permissions for working with EKS clusters and nodes.
Please ensure that you have installed v1.24.7+ ofkubectl
and v0.125.0+ ofeksctl
. -
Pick a target AWS region into which you want to install the SSIMPLUS® Analyzer Cluster.
ImportantIn 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.
-
Follow the steps in the Installation Prerequisites for SSIMPLUS® Analyzer Cluster - AWS Managed Service, skipping the last step (i.e. step 8).
ImportantIt 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. -
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
-
The machine you are using to deploy has kubectl installed.
-
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
andpersistent volume claims
- get/list/watch/create/update/patch/delete on
-
Your
kubectl
executable has its context set to use your target namespace:kubectl config set-context <context>
.
-
Your Kubernetes cluster must have outbound internet access on port
443
to the following hosts:NoteThe 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.
-
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.
Use only the section that applies to your situation.
AWS Elastic Kubernetes Service (~ 45 mins)
-
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
whereMAJOR
,MINOR
,PATCH
andBUILD
represent the major, minor, patch and build numbers of the desired build. -
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
andkubectl
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
-
Create your Kubernetes cluster.
eksctl create cluster -f ./cluster/eks/cluster.yaml
NoteThis process can take 15-20 minutes and you may see repeated messages of “waiting for CloudFormation stack…”.
-
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.
-
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
withk8s.gcr.io/autoscaling/cluster-autoscaler:v1.24.0
- replace
<YOUR CLUSTER NAME>
withSSIMPLUS-VOD-Monitor
- add
- --scale-up-from-zero
to the bottom of thecommand
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
- replace
-
Create the desired namespace for your SSIMPLUS® Analyzer Cluster.
kubectl --context arn:aws:eks:<region>:<accountID>:cluster/SSIMPLUS-VOD-Monitor create namespace <NAMESPACE>
ImportantPick 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 ofcompanyx-vod-monitor-production
. -
Edit the YAML file
vodmonitor/vodmonitor.yaml
and modify thehttp-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.
ImportantMake 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 fromClusterIP
toLoadBalancer
.
-
Edit the YAML file
vodmonitor/vodmonitor.yaml
(approx. line 999) and remove thevod-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
-
Edit the YAML file
vodmonitor/vodmonitor.yaml
(approx. line 999) and modify thevod-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
-
(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 thedevices
list underanalyzer-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
NoteThe 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).
-
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
- Replace
-
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
. -
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.NoteIf 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.
ImportantFor 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.
-
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)
NoteAlthough 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.
- Replace
-
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 thehttp-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.
- Replace
-
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.- Login to your Insights Account.
- Click on the user icon in the top right corner of the UI and pick
Account
from the dropdown menu. - Scroll down to the
Additional Details
section and change yourVOD Api Host
value to match the FQDN associated with your TLS certificate. - Click Save.
ImportantAll users of SSIMPLUS® VOD Monitor will need to make this same adjustment to their
VOD API Host
setting under their Insights account. -
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.ImportantIt 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)
-
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
whereMAJOR
,MINOR
,PATCH
andBUILD
represent the major, minor, patch and build numbers of the desired build. -
Create the desired installation namespace <NAMESPACE> in your SSIMWAVE cluster.
kubectl create namespace <NAMESPACE>
ImportantPick 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 ofcompanyx-vod-monitor-production
. -
(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 thedevices
list underanalyzer-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 }
NoteThe 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).
-
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 thevod-frameservices-cache-pv
Kubernetes Persistent Volume (PV) andvod-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. -
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:
-
Install the nginx Helm repository:
helm repo add nginx-stable https://helm.nginx.com/stable
-
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:
- 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>"
- 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
-
-
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 dockerpull/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 namedsetup-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 togcr.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.NoteIf 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.
ImportantFor 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.
-
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
)
-
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).- Login to your Insights Account.
- Click on the user icon in the top right corner of the UI and pick
Account
from the dropdown menu. - Scroll down to the
Additional Details
section and change yourVOD Api Host
value to match the FQDN associated with your ingress (i.e.<ingress_hostname>
). - Click Save.
ImportantAll users of SSIMPLUS® VOD Monitor will need to make this same adjustment to their
VOD API Host
setting under their Insights account. -
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.ImportantIt 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:
Assets in AWS S3
There are three ways to access assets in an S3 bucket via the SSIMPLUS® Analyzer REST API:
-
Client/Secret
Requires that the S3 bucket key id and access key be passed in clear text to the REST API.
-
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 Stream™ On-Demand REST API to create a conformant secret. -
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.
Where possible, one should look to use option 3 (Assumed IAM role) as it is the most secure and an accepted AWS best practice.
Adding S3 Buckets to EKS using IAM (~ 15 mins)
-
Follow the instructions in Providing access to video assets in S3 under the Post Installation section of the AWS Managed Service deployment guide.
-
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/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.