Guidance for Video on Demand on AWS Foundation

Summary: This implementation guide provides an overview of the Guidance for Video on Demand on AWS Foundation, its reference architecture and components, considerations for planning the deployment, configuration steps for deploying the Guidance to the AWS Cloud.

Overview

Video on Demand on AWS Foundation is a reference implementation that automatically provisions the Amazon Web Services (AWS) services necessary to build a scalable, distributed video-on-demand workflow.

To build highly available, resilient architectures that ingest, store, process, and deliver video content on demand, this Guidance uses the following AWS services:

• AWS Elemental MediaConvert to transcode media files from their source format into versions that play back on smartphones, tablets, PCs, and other devices.

• Amazon CloudFront for global distribution.

• Amazon Simple Storage Service (Amazon S3) for object storage.

• AWS Lambda to run code without provisioning or managing servers.

• Amazon EventBridge to invokethe Lambda job complete function.

• Amazon CloudWatch to log metrics about encoding jobs in MediaConvert.

• Amazon Simple Notification Service (Amazon SNS) to send notifications for completed jobs.

We designed this Guidance to help you begin encoding video files with MediaConvert. Out of the box, this Guidance provides a sample MediaConvert job-settings.json file, which you can use to transcode videos uploaded to an Amazon S3 bucket. By default, the Guidance can encode MP4, MPG, M4V, M2TS, and MOV files. You can customize the architecture to encode any media file type supported by MediaConvert. For more information, refer to Customization.

If you want to build out more complex workflows with options around ingest processing and publishing video content, AWS also offers the Video on Demand on AWS Guidance.

The intended audience for using this Guidance’s features and capabilities in their environment includes IT infrastructure architects, Guidance architects, administrators, business decision makers, DevOps engineers, data scientists, and cloud professionals.

Use this navigation table to quickly find answers to these questions:

Features and benefits

The Guidance provides the following features:

Reference implementation

Leverage this Guidance as a reference implementation to automatically provision the AWS services necessary to build a scalable, distributed video-on-demand workflow.

Customization

You can customize this Guidance and then use it as the starting point to create a more complex workflow. 

Integration with AWS Service Catalog AppRegistry and Application Manager, a capability of AWS Systems Manager

This Guidance includes a Service Catalog AppRegistry resource to register the Guidance’s AWS CloudFormation template and its underlying resources as an application in both AppRegistry and Application Manager. With this integration, you can centrally manage the Guidance’s resources and enable application search, reporting, and management actions.

Use cases

Streaming media

As consumer demand for video streaming increases, media and entertainment companies are looking for secure and reliable web-based video streaming alternatives to traditional television. This Guidance automatically provisions the services necessary to build a scalable, distributed architecture that ingests, stores, processes, and delivers video content. Using this Guidance, you can avoid inefficient trial-and-error approaches, and save on time and costs for your streaming media projects.

Educational content delivery

Professional development and educational initiatives create incentives and can be important revenue generators for nonprofit organizations. This Guidance can help you create modern, scalable content delivery and learning management systems (LMS) to support your membership and programming offerings. The Guidance streamlines the processes for delivering online training and learning content.

Concepts and definitions

This section describes key concepts and defines terminology specific to this Guidance: 

Application

A logical group of AWS resources that you want to operate as a unit.

Dynamic Adaptive Streaming over HTTP (DASH)

An HTTP-based streaming protocol (also known as MPEG-DASH) to deliver media over the internet and developed under Motion Picture Experts Group (MPEG).

HTTP Live Streaming (HLS)

An HTTP-based streaming protocol to deliver media over the internet and developed by Apple Inc.

Quality-Defined Variable Bitrate (QVBR)

A video encoding technology that uses fewer bits in low-complexitiy periods of content, and more bits during high-completely periods (up to the maximum bitrate), delivering consistently high video quality. For more information, see What is Quality-Defined Variable Bitrate (QVBR)?

Workflow

Generated state machines that run a number of operations in sequence.

For a general reference of AWS terms, see the AWS glossary  in the AWS General Reference.

Architecture overview

This section provides a reference implementation architecture diagram for the components deployed with this Guidance.

Architecture diagram

Deploying this Guidance with the default parameters deploys the following components in your AWS account.

Figure 1: AWS Architecture

The AWS CloudFormation template deploys the following infrastructure:

1. An Amazon S3 bucket stores source video files. The Guidance also uploads a sample job settings file to the source S3 bucket. This file defines the encoding settings for AWS Elemental MediaConvert.

2. An AWS Lambda job submit function creates the encoding jobs in MediaConvert.

3. AWS Elemental MediaConvert transcodes the video into HLS adaptive bitrate (ABR) files.

4. Amazon CloudWatch logs metrics about encoding jobs in MediaConvert.

5. Amazon EventBridge invokes the Lambda job complete function.

6. A Lambda job complete function processes the outputs.

7. An Amazon SNS topic sends notifications of completed jobs.

8. Another Amazon S3 bucket stores the MediaConvert outputs.

9. Amazon CloudFront is configured with the output S3 bucket as the origin for global distribution of the transcoded video content.

AWS Well-Architected design considerations

This Guidance uses the best practices from the AWS Well-Architected Framework , which helps customers design and operate reliable, secure, efficient, and cost-effective workloads in the cloud.

This section describes how the design principles and best practices of the Well-Architected Framework benefit this Guidance.

Operational excellence

This section describes how we architected this Guidance using the principles and best practices of the operational excellence pillar.

This Guidance pushes metrics to CloudWatch at various stages to provide observability into the infrastructure, Lambda functions, MediaConvert, S3 buckets, and the rest of the Guidance components.

Security

This section describes how we architected this Guidance using the principles and best practices of the security pillar.

This Guidance uses AWS Identity and Access Management (IAM) roles to allow customers to assign granular access policies and permissions to services and users in the AWS Cloud.

Reliability

This section describes how we architected this Guidance using the principles and best practices of the reliability pillar.

This Guidance uses AWS serverless services wherever possible (for example, Lambda and Amazon S3) to ensure high availability and quick recovery from service failure.

Performance efficiency

This section describes how we architected this Guidance using the principles and best practices of the performance efficiency pillar.

This Guidance uses serverless architecture. It can be launched in any AWS Region that supports the AWS services used in the Guidance, such as Lambda, Amazon S3, and MediaConvert.

This Guidance is automatically tested and reviewed by solutions architects and subject matter experts for areas to experiment and improve.

Cost optimization

This section describes how we architected this Guidance using the principles and best practices of the cost optimization pillar.

You can measure the efficiency of the workloads, and the costs associated with delivery, by using Application Manager.

Sustainability

This section describes how we architected this Guidance using the principles and best practices of the sustainability pillar.

This Guidance uses managed and serverless services to minimize the environmental impact of the backend services. If desired, you can run this Guidance only during specific events and then delete the stack after the program ends. This approach helps reduce the carbon footprint compared to the footprint of continually operating on-premises servers.

Architecture details

This section describes the components and AWS services that make up this Guidance and the architecture details on how these components work together.

Ingest

To invoke the video processing workflow, you must upload the source video assets to the source S3 bucket through standard tools. For example, you can use the AWS Management Console, AWS Command Line Interface (AWS CLI), or third-party tools that interface with Amazon S3.

By default, this Guidance creates an assets01 folder in the root of the source S3 bucket with a job-settings.json file. Each time you upload a video to the assets01 folder, or any other folder that you created:

1. An Amazon S3 event notification invokes the job-submit Lambda function.

2. The job-submit Lambda function:

   a. Receives the details for the source video from the event.

   b. Applies the settings contained in the job settings file in the same top-level folder as the uploaded video in Amazon S3.

   c. Submits a job to MediaConvert using the processed job settings file.

To help you track the job in MediaConvert, the Guidance includes the following in the submitted job:

• Name of the workflow defined at deployment

• A globally unique identifier (GUID) created by the job-submit Lambda function

Encoding

The Guidance supports MediaConvert QVBR encoding mode, which ensures consistent, high-quality video transcoding with the smallest file size for any type of source video content.

By default, this Guidance includes a sample encoding job settings file that encodes your source videos into MP4, SD and HD formats of HLS, and SD and HD formats of DASH. You can overwrite the provided encoding job settings to use output formats that are supported by MediaConvert.

The sample job settings file created as part of the CloudFormation deployment has the QVBR rate control activated with accelerated transcoding set to PREFERRED. This generates the following output:

• HLS ABR with 5 renditions @ 1920x1080, 1280x720, 960x540, 640x360, 480x270

To change the settings, you can update or replace the job settings file in Amazon S3 with your own settings. For details, refer to Exporting and importing AWS Elemental MediaConvert jobs in the _MediaConvert User Guide_. To ensure validity of the job settings file, only export jobs that have successfully run and completed.

Processing

This Guidance includes an EventBridge rule configured to invoke the job-complete Lambda function each time an encoding job starts up, completes successfully, or fails in MediaConvert. This function retrieves the details of the job from the event and generates the CloudFront URLs for the MediaConvert outputs. The Guidance then adds details for the input file, job settings, and outputs to a jobs-manifest.json file stored at the root of the source S3 bucket. The following is an example jobs-manifest.json file.

{
    "Jobs":
    {
        "jobId-0001": {
            "FileInput": "s3://SOURCE_BUCKET/example.mp4",
            "JobSettings": {...},
            "Outputs": {
                "HLS": "https://cloudfront.net/..."
            }
        }
    },
    {
        "jobId-0002": {
            "FileInput": "s3://SOURCE_BUCKET/example2.mp4",
            "JobSettings": {...},
            "Outputs": {
                "HLS": "https://cloudfront.net/..."
            }
        }
    }
...

}

The job-complete Lambda function also sends a summary of the job and the outputs to the Amazon SNS topic created at deployment. Errors from the encoding process are also captured by the Lambda function and sent to the SNS topic.

AWS services in this Guidance

Plan your deployment

This section describes the cost, security, Regions, and other considerations prior to deploying the Guidance.

Cost

You are responsible for the cost of the AWS services used while running this Guidance. The total cost for running this Guidance depends on the size of your videos, the number of outputs created, and the number of views the published content receives through CloudFront. After encoding all of your videos with this Guidance, the monthly cost will be for Amazon S3 storage, and any CloudFront costs from streaming your new video content to users.

As of this revision, the estimated cost of running this Guidance for a 60-minute video with the dimensions listed in the following table, in the US East (N. Virginia) Region, is approximately $232.86 per month per job.

We recommend creating a budget  through AWS Cost Explorer  to help manage costs. Prices are subject to change. For full details, see the pricing webpage for each AWS service used in this Guidance.

Cost table for a 60-minute source video

The following table provides a sample cost breakdown for processing a 60-minute source video using the Guidance deployed with the default parameters in the US East (N. Virginia) Region.

MediaConvert cost

A significant cost of running this Guidance comes from MediaConvert. This section breaks down the MediaConvert costs for the sample 60-minute source video.

The video outputs in the Cost table for a 60-minute source video use the following Basic tier MediaConvert settings:

• AVC codec
• 1 pass quality
• 30 fps

This Guidance’s CloudFormation template creates a destination S3 bucket where the processed videos are stored. The Guidance stores each processed result in a folder with the same name as the process ID. Pricing increases when using higher frame rates than 30 fps. For more information about MediaConvert pricing, refer to AWS Elemental MediaConvert Pricing.

Security

When you build systems on AWS infrastructure, security responsibilities are shared between you and AWS. This shared responsibility model reduces your operational burden because AWS operates, manages, and controls the components including the host operating system, the virtualization layer, and the physical security of the facilities in which the services operate. For more information about AWS security, visit AWS Cloud Security.

Amazon S3 bucket policy

The S3 buckets for MediaConvert output include a policy that allows access from CloudFront. Because the CloudFront endpoints are publicly accessible, the MediaConvert output bucket is also publicly accessible when accessed with CloudFront. For information on how to secure Amazon CloudFront, refer to Serving private content with signed URLs and signed cookies in the _Amazon CloudFront Developer Guide_.

IAM roles

IAM roles allow you to assign granular access policies and permissions to services and users on the AWS Cloud. This Guidance creates several IAM roles, including a role that grants MediaConvert access to Amazon S3. This role is necessary to allow the services to operate in your account.

Supported AWS Regions

This Guidance uses the MediaConvert service, which is not currently available in all AWS Regions. For the most current availability of AWS services by Region, see the AWS Regional Services List.

This Guidance is available in the following AWS Regions:

Customization

This Guidance uses a serverless architecture that you can update and extend for your specific video processing needs. For example, you can add or replace Amazon SNS with Amazon Simple Queue Service (Amazon SQS) to allow upstream workflows to subscribe and get notifications on the workflow outputs. You can also add multiple folders and job settings files in the source S3 bucket to accommodate different use cases. For details, refer to Working with mulitple job settings files.

Quotas

Service quotas, also referred to as limits, are the maximum number of service resources or operations for your AWS account.

Quotas for AWS services in this Guidance

Make sure you have sufficient quota for each of the services implemented in this Guidance. For more information, see AWS service quotas.

Use the following links to go to the page for that service. To view the service quotas for all AWS services in the documentation without switching pages, view the information in the Service endpoints and quotas page in the PDF instead.

AWS CloudFormation quotas

Your AWS account has AWS CloudFormation quotas that you should be aware of when launching the stack in this Guidance. By understanding these quotas, you can avoid limitation errors that would prevent you from deploying this Guidance successfully. For more information, see AWS CloudFormation quotas in the in the _AWS CloudFormation User’s Guide_.

AWS Elemental MediaConvert quotas

All MediaConvert jobs run in a queue. If you don’t specify a queue when you create your job, MediaConvert sends it to the default on-demand queue. For information about how many queues you can create and how many jobs those queues can run, refer to How queues work in AWS Elemental MediaConvert in the _MediaConvert User Guide_ and see Service quotas in the _AWS General Reference Guide_.

Deploy the Guidance

This Guidance uses CloudFormation templates and stacks to automate its deployment. The CloudFormation template specifies the AWS resources included in this Guidance and their properties. The CloudFormation stack provisions the resources that are described in the template.

Before you launch the Guidance, review the cost, architecture, network security, and other considerations discussed earlier in this guide.

Time to deploy: Approximately 10 minutes

Important: This Guidance includes an option to send anonymized operational metrics to AWS. We use this data to better understand how customers use this Guidance and related services and products. AWS owns the data gathered though this survey. Data collection is subject to the AWS Privacy Notice.

To opt out of this feature, download the template, modify the AWS CloudFormation mapping section, and then use the AWS CloudFormation console to upload your updated template and deploy the Guidance. For more information, see the Anonymized data collection section of this guide.

1. Download or clone the repo.
2. Update the source code.
3. Either deploy the solution using the CDK or run the deployment/build-s3-dist.sh script. The build script:
   1. Generates the CloudFormation template from the CDK source code using cdk synth.
   2. Runs deployment/cdk-solution-helper to update the template so that it pulls the Lambda source code from Amazon S3.
   3. Packages the Lambda code ready to be deployed to an Amazon S3 bucket in your account.

For details on deploying the solution using the CDK see the CDK Getting Started guide.

Deploy using CloudFormation

1. Run unit tests for customization

Run unit tests to ensure that your added customization passes the tests:

cd deployment
chmod +x ./run-unit-tests.sh
./run-unit-tests.sh

2. Create an S3 bucket

We configured the CloudFormation template to pull the Lambda deployment packages from an S3 bucket in the Region the template is being launched in. Create a bucket in the desired Region and append the Region name to the bucket name (for example, my-bucket-us-east-1).

aws s3 mb s3://my-bucket-us-east-1

3. Create the deployment packages

Build the distributable:

chmod +x ./build-s3-dist.sh
./build-s3-dist.sh my-bucket video-on-demand-on-aws-foundation v1.2.0

Note: The _build-s3-dist_ script expects the bucket name as one of its parameters, and this value should not include the Region suffix.

Deploy the distributable to the S3 bucket in your account:

aws s3 cp ./regional-s3-assets/ s3://my-bucket-us-east-1/video-on-demand-on-aws-foundation/v1.2.0/ \
    --recursive --acl bucket-owner-full-control

4. Launch the stack

Follow the step-by-step instructions in this section to configure and deploy the Guidance into your account.

Time to deploy: Approximately 10 minutes

1. Sign in to the AWS CloudFormation console

   Note: This Guidance uses MediaConvert, which is available in specific AWS Regions only. Therefore, you must deploy this Guidance in a Region that supports this service. For the most current service availability by Region, refer to the AWS Regional Services List.

2. Deploy the CloudFormation template from deployment/global-assets/video-on-demand-on-aws-foundation.template into the same Region as your newly created S3 bucket.

3. On the Specify stack details page, assign a name to your Guidance stack. For information about naming character limitations, see IAM and AWS STS quotas, name requirements, and character limits in the _AWS Identity and Access Management User Guide_.

4. Under Parameters, review the parameters for this Guidance template and modify them as necessary. This Guidance uses the following parameters.

   Parameter	Description
   Notification Email Address	A valid email address to receive Amazon SNS notifications.

5. Select Next.

6. On the Configure stack options page, choose Next.

7. On the Review page, review and confirm the settings. Select the box acknowledging that the template creates IAM resources.

8. Choose Create stack to deploy the stack.

   You can view the status of the stack in the AWS CloudFormation console in the Status column. You should receive a CREATE_COMPLETE status in approximately 10 minutes.

   After the stack is created, Amazon SNS sends three subscription notifications to the admin email address with links to allow encoding, publishing, and error notifications.

9. In the subscription notification emails, select each link to allow SNS notifications.

Note: In addition to the Lambda functions that create Guidance resources and manage the workflow, this Guidance includes the custom-resource Lambda function, which runs only during initial configuration or when resources are updated or deleted.

When running this Guidance, the custom-resource function is inactive. However, do not delete the function, since it is necessary to manage associated resources.

Monitoring the Guidance with AWS Service Catalog AppRegistry

This Guidance includes an AppRegistry resource to register the CloudFormation template and underlying resources as an application in both AppRegistry and Application Manager.

Application Manager gives you an application-level view into this Guidance and its resources so that you can:

• Monitor its resources, costs for the deployed resources across stacks and AWS accounts, and logs associated with this Guidance from a central location.

• View operations data for the Guidance’s AWS resources (such as deployment status, Amazon CloudWatch alarms, resource configurations, and operational issues) in the context of an application.

  The following figure depicts an example of the application view for this Guidance stack in Application Manager.

Figure 2: Application Manager

Note: You must activate CloudWatch Application Insights, Cost Explorer, and cost allocation tags associated with this Guidance. They aren’t activated by default.

Activate CloudWatch Application Insights

1. Sign in to the Systems Manager console.

2. In the navigation pane, choose Application Manager.

3. In Applications, choose AppRegistry applications.

4. In AppRegistry applications, search for the application name for this Guidance and select it.

The next time you open Application Manager, you can find the new application for your Guidance in the AppRegistry application category.

1. In the Components tree, choose the application stack you want to activate.

2. In the Monitoring tab, in Application Insights, select Auto-configure Application Monitoring.

Figure 3: Application Insights

Monitoring for your applications is now activated and the following status box appears:

Figure 4: Monitoring Enabled

Activate AWS Cost Explorer

You can see the overview of the costs associated with the application and application components within the Application Manager console through integration with Cost Explorer which must be first activated. Cost Explorer helps you manage costs by providing a view of your AWS resource costs and usage over time. To activate Cost Explorer for the Guidance:

1. Sign in to the AWS Cost Management console.

2. In the navigation pane, select Cost Explorer.

3. On the Welcome to Cost Explorer page, choose Launch Cost Explorer.

The activation process can take up to 24 hours to complete. Once activated, you can open the Cost Explorer user interface to further analyze cost data for the Guidance.

Activate cost allocation tags associated with the Guidance

After you activate Cost Explorer, you must activate the cost allocation tags associated with this Guidance to see the costs for this Guidance. The cost allocation tags can only be activated from the management account for the organization. To activate cost allocation tags:

1. Sign in to the AWS Billing and Cost Management console.

2. In the navigation pane, select Cost Allocation Tags.

3. On the Cost allocation tags page, filter for the AppManagerCFNStackKey tag, then select the tag from the results shown.

4. Choose Activate.

The activation process can take up to 24 hours to complete and the tag data to appear.

Confirm cost tags associated with the Guidance

After you activate cost allocation tags associated with the Guidance, you must confirm the cost allocation tags to see the costs for this Guidance. To confirm cost allocation tags:

1. Sign in to the Systems Manager console.

2. In the navigation pane, choose Application Manager.

3. In Applications, choose the application name for this Guidance and select it.

4. In the Overview tab, in Cost, select Add user tag.

   

   Figure 5: Add User Tag

5. On the Add user tag page, enter confirm, then select Add user tag.

The activation process can take up to 24 hours to complete and the tag data to appear.

Update the Guidance

If you have previously deployed the Guidance, follow this procedure to update the Guidance’s CloudFormation stack to get the latest version of the Guidance’s framework.

1. From the main account where the Guidance is deployed, sign in to the AWS CloudFormation console.

2. Select your existing Video on Demand on AWS Foundation CloudFormation stack, and select Update.

3. Select Replace current template.

4. Under Specify template:

   a. Select Upload File.

   b. Upload a new version of the template generated by following the steps in Create the deployment packages.

   c. Choose Next. Choose Next again.

5. Under Parameters, review the parameters for the template and modify them as necessary. For details about the parameters, see Launch the stack.

6. Choose Next.

7. On the Configure stack options page, choose Next.

8. On the Review page, review and confirm the settings. Select the box acknowledging that the template creates IAM resources.

9. Choose View change set and verify the changes.

10. Choose Update stack to deploy the stack.

You can view the status of the stack in the AWS CloudFormation console in the Status column. You should receive a UPDATE_COMPLETE status in approximately 10 minutes.

Troubleshooting

The email address you provided when deploying this Guidance receives notifications both when MediaConvert jobs complete successfully and when they fail. The email address also receives notifications about errors that might have occurred while trying to submit a job or process the output from a job.

If you’re notified about a MediaConvert job failure, complete the following steps.

1. From the main account where the Guidance is deployed, sign in to the AWS Elemental MediaConvert console.

2. In the navigation pane, select Jobs.

3. Select the job ID of the job that failed.

4. On the Job Summary page, review the Overview section for an error message with more information on why the job failed. On this page, you can also find MediaConvert error codes for details on how to address the issue.

If the error is not a MediaConvert job failure, possibly one of the two Lambda functions, job_submit or job_complete, encountered an error. The email you received has an ErrorDetails link that takes you directly to the CloudWatch logs generated by the failed function. The logs have additional details on why it failed.

Note: When overriding the sample job-settings.json, we recommend exporting job settings from a MediaConvert job that’s successfully completed. Incorrect encoding settings will result in the job_submit Lambda function to fail.

Uninstall the Guidance

You can uninstall this Guidance from the AWS Management Console or by using the AWS CLI. You must manually delete the S3 buckets and CloudWatch logs created by this Guidance. AWS Solutions do not automatically delete these resources in case you have stored data to retain.

Using the AWS Management Console

1. Sign in to the CloudFormation console.

2. On the Stacks page, select this Guidance’s installation stack.

3. Choose Delete.

Using AWS Command Line Interface

Determine whether the AWS CLI is available in your environment. For installation instructions, see What Is the AWS Command Line Interface  in the AWS CLI User Guide. After confirming that the AWS CLI is available, run the following command.

aws cloudformation delete-stack --stack-name <installation-stack-name>

Deleting the Amazon S3 buckets

To prevent accidental data loss, this Guidance retains the Guidance-created Amazon S3 bucket (for deploying in an opt-in Region) if you decide to delete the CloudFormation stack. After uninstalling the Guidance, you can manually delete this S3 bucket if you do not need to retain the data. Follow these steps to delete the Amazon S3 bucket.

1. Sign in to the Amazon S3 console.

2. Choose Buckets from the left navigation pane.

3. Locate the <stack-name> S3 buckets.

4. Select the S3 bucket and choose Delete.

To delete the S3 bucket using AWS CLI, run the following command:

aws s3 rb s3://<bucket-name> --force

Alternatively, you can configure the CloudFormation template to delete the S3 buckets automatically. Before deleting the stack, change the deletion behavior in the AWS CloudFormation DeletionPolicy attribute.

Deleting the CloudWatch Logs

To prevent accidental data loss, this Guidance retains the CloudWatch logs if you decide to delete the CloudFormation stack. After uninstalling the Guidance, you can manually delete the logs if you don’t need to retain the data. Follow these steps to delete the CloudWatch logs.

1. Sign in to the Amazon CloudWatch console.

2. Choose Log Groups from the left navigation pane.

3. Locate the log groups created by the Guidance.

4. Select one of the log groups.

5. Choose Actions and then choose Delete.

Repeat the steps until you have deleted all the Guidance log groups.

Developer guide

This section provides the source code for the Guidance.

Source code

Visit our GitHub repository to download the source files for this Guidance and to share your customizations with others.

Job settings file

By default, this Guidance creates an assets01 folder in the root of the S3 bucket with a job-settings.json file. Video uploads to this folder invoke a workflow to apply job settings to the job created in MediaConvert.

Changing the job settings file

You can customize the job-settings.json file or replace it with a new MediaConvert job template. To make a new job template or to customize the existing job-setting.json job template, refer to Working with AWS Elemental MediaConvert job templates in the _MediaConvert User Guide_.

When your updated job template JSON file is ready, name the file job-settings.json and upload it to replace the one that is already in the assets01 folder of the S3 source bucket.

Working with multiple job settings files

To support different job settings, create additional folders at the root of the source S3 bucket and include different job setting for each folder. The following shows an example folder structure. With this example configuration in the source S3 bucket, video-01.mp4 files are encoded with the settings stored in the assets01 folder. Meanwhile, video-02.mp4 and video-03.mpg files are encoded using the settings in the assets02 folder:

assets01/
  job-settings.json
  video-01.mp4
assets02/
  job-settings.json
  video-02.mp4
  subfolder/
    video-03.mpg

Important: You must name the settings file job-settings.json. There are no specific requirements for the folder names.

Although you can export a completed job from MediaConvert to use as a job settings file, this Guidance doesn’t support input stitching or input clipping because it only launches on the upload of one video file source.

If AccelerationSettings is not defined in the job settings JSON file, this Guidance will automatically add this and set it to PREFERRED.

We recommend that you provide a custom name for your output groups, especially if your job settings include more than one output group of the same type. For example, three HLS output groups. The Guidance uses the output group name as part of the output destination path, and having distinct names makes it easier to locate where each output is being written.

Reference

This section includes information about an optional feature for collecting unique metrics for this Guidance and a list of builders who contributed to this Guidance.

Anonymized data collection

This Guidance includes an option to send anonymized operational metrics to AWS. We use this data to better understand how customers use this Guidance and related services and products. When activated, the following information is collected and sent to AWS each time a video is processed:

• Solution ID - The AWS Guidance identifier.

• Unique ID (UUID) - Randomly generated, unique identifier for each Guidance for Video on Demand on AWS Foundation deployment.

• Timestamp - Data-collection timestamp.

• Job Settings - The job settings with the source and destination object paths removed. This helps us understand what output groups customers are looking for.

AWS owns the data gathered though this survey. Data collection is subject to the AWS Privacy Notice. To opt out of this feature, complete the following steps before launching the AWS CloudFormation template.

1. Download the CloudFormation template to your local hard drive.

2. Open the CloudFormation template with a text editor.

3. Modify the CloudFormation template mapping section from:

   AnonymizedData:
     SendAnonymizedData:
       Data: Yes
   

   to:

   AnonymizedData:
     SendAnonymizedData:
       Data: No
   

4. Sign in to the AWS CloudFormation console.

5. Select Create stack.

6. On the Create stack page, Specify template section, select Upload a template file.

7. Under Upload a template file, choose Choose file and select the edited template from your local drive.

8. Choose Next and follow the steps in Launch the stack in the Deploy the Guidance section of this guide.

Contributors

• Joan Morgan
• Eddie Goynes
• Raul Marquez
• Damian McNamara
• Sean Byrne

Revisions

Notices

Customers are responsible for making their own independent assessment of the information in this document. This document: (a) is for informational purposes only, (b) represents AWS current product offerings and practices, which are subject to change without notice, and (c) does not create any commitments or assurances from AWS and its affiliates, suppliers or licensors. AWS products or services are provided “as is” without warranties, representations, or conditions of any kind, whether express or implied. AWS responsibilities and liabilities to its customers are controlled by AWS agreements, and this document is not part of, nor does it modify, any agreement between AWS and its customers.

Video on Demand on AWS Foundation is licensed under the terms of the of the Apache License Version 2.0 available at The Apache Software Foundation.