Frequency Documentation

S3 Ingestion

Frequency provides two different paths to utilize AWS S3 for content ingestion via either a Frequency provided S3 or direct integration with a partner S3.

Frequency S3 Ingestion

Frequency can set up a dedicated Amazon S3 storage space to securely transfer content into Frequency Studio with a provided access key ID and a secret access key. You can learn more about AWS S3 here. The following assets are used for successful content ingestion:

Deliverable

Required

Description

Example

Video asset

Required

This is the video asset being ingested.

  • Supported file extensions: mp4, mov, mpg, avi

  • Minimum 1280x720 resolution

  • 16:9 Aspect Ratio

movie.mp4

Image asset

Required

An image to represent your video asset. Cannot be a black square.

  • Supported file extensions: jpg, png

  • Minimum 1280x720 resolution

  • 16:9 Aspect Ratio

thumbnail.png

Caption file

Optional

Caption files to accompany video assets.

  • Supported file extensions: srt, vtt, srt, ttml, stl, smi

captions.scc

Metadata file

Required

A .csv file containing required and optional metadata for ingestion. This is how your assets and metadata will be linked into one item.

Required metadata:

For optional metadata fields, please see the attached manifest, and refer to Metadata Definitions.

  • GUID

  • Title

  • Description

  • Video File Name + Extension (e.g. video.mp4)

  • Thumbnail File Name + Extension (e.g. thumbnail.jpg

metadata-manifest.csv

Credentials delivery

Frequency will securely deliver the following credentials to allow access to Frequency S3 storage. Credentials include:

  • Access Key ID - Example: AKIARECHFGWRLHEXAMPLE

  • Secret Access Key (Do not share) - Example: arLwJXUtnFEMI/f+/cxv/bPxRfiCYEXAMPLEKEY

  • Path - Example: partner-videos

Credentials should be kept private and secure and can be used with third-party clients to provide remote access to the provided S3 storage. Some clients that can be used for this are Transmit or Cyberduck, among many others.

Connecting to a client

Input the following information into your S3 client:

  1. Address: s3.amazonaws.com

  2. Access Key ID: <provided by Frequency>

  3. Secret Access Key: <provided by Frequency>

  4. Path: <provided by Frequency>

Uploading files

All assets (videos, thumbnails, and caption files) must be uploaded to S3 before the metadata.csv is updated. Any items uploaded after the .csv file is updated risk being omitted from the ingestion package and in some cases the video will fail to ingest due to missing required assets.

It is essential that valid file and folder path names are in the .csv file to ensure smooth ingestion via S3. Notably, file names are case sensitive, should not contain spaces and only a limited set of special characters are supported. See AWS’ guide on Creating Object Key Names.

Upload Metadata Manifest File

You must upload a manifest file in CSV format (e.g.: metadata.csv) that describes your content uploaded. Refer to this template and example for the correct field and field values.

  • The only required fields are video_file and image_file (both must be of 16:9 aspect ratio and  at least 720p resolution). These fields must match the file names in the folder otherwise this may cause issues with ingestion

  • Refer to the file paths if necessary.  For example if myvideo.mp4 is in the main folder, use that for the video file.  If it was in the subfolder "videos", use videos/myvideo.mp4

  • You must update this manifest file after you have confirmed that all associated assets have been uploaded successfully, otherwise this may cause issues with ingestion

  • Do not use spaces or special characters for any folder names

  • In the future, you can overwrite this file with new information when necessary

CSV Example

metadata.csv

Live Google Sheet Example

Metadata File Template (metadata.csv) - Google Sheets

File Structure Guidelines
  • Upload your metadata.csv after all assets have been fully uploaded

  • Avoid using spaces in file names

  • Avoid using special characters aside from those detailed below

  • Data ending with line breaks will not be valid

  • Ensure file paths on assets are correct

  • File names are case sensitive

  • The ordering of the entries in the metadata.csv reflects the order in which they will be ingested

Automated Ingestion

Frequency will check the metadata Manifest file periodically and detect new videos to ingest. Videos that are ingested successfully will appear in the MANAGE tool.Overview

File Name Convention

Asset names must adhere to S3's Creating Object Key Names.

The name for a key is a sequence of Unicode characters whose UTF-8 encoding is at most 1,024 bytes long.

Safe characters

Please ensure your file names only use the following safe characters:

Alphanumeric characters

  • 0-9

  • a-z

  • A-Z

Special characters

  • No spaces in file or folder names

  • Forward slash ( / )

  • Exclamation point ( ! )

  • Hyphen ( - )

  • Underscore ( _ )

  • Period ( . ) Exception: Object name key cannot end with a single period (.), or two periods (..)

  • Asterisk ( * )

  • Single quote ( ' )

  • Open parenthesis ( ( )

  • Close parenthesis ( ) )

Partner S3 Ingestion

Alternatively, Frequency can access your Amazon Web Services (AWS) S3 buckets, you would need to grant Frequency's account cross-account bucket permissions.  Delivery otherwise is the same as above.

Deliverable

Deliverable

Example

Cross Account Bucket Permissions

If you've configured authentication on your S3 files, we will require access to your S3 bucket in order to process videos. Please see the AWS documentation on granting cross-account bucket permissions.

Please be aware of S3 bucket naming limitations, as this may impact our ability to ingest your content.

In order to complete this provisioning process, please reach out to your account manager on slack or email operations@frequency.com for the frequency account ID.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Example permissions", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::<frequency-account-id>:root" }, "Action": [ "s3:GetBucketLocation", "s3:ListBucket", "s3:GetObject" ], "Resource": "arn:aws:s3:::<bucket-name>" "Resource": "arn:aws:s3:::<bucket-name>/*" } ]
}

Video assets

This is the video asset being ingested.

  • Supported file extensions: mp4, mov, mpg, avi

  • Minimum 1280x720 resolution

  • 16:9 Aspect Ratio

movie.mp4

Image assets

An image to represent your video asset. It is preferable if it is unique. These files must be publicly available.

Supported file extensions: jpg, png

  • Minimum 1280x720 resolution

  • 16:9 Aspect Ratio

thumbnail.jpg

Metadata file

A .csv file containing required and optional metadata for ingestion. This is how you assets will be linked into one object. This file must be publicly available but does not necessarily need to be saved in the shared S3 bucket. This could be hosted in Dropbox or Google Sheets.

Required metadata:

  • GUID

  • Title

  • Description

  • Video S3 URL

  • Thumbnail S3 URL

For optional metadata fields, please see the attached manifest, and refer to Metadata Definitions.

metadata-manifest.csv

Allowing Frequency to Read S3 Bucket Files

Go to the S3 bucket, click on Permissions, and Edit the Bucket Policy

23069755.png

Add the Policy JSON with Frequency's Account ID (Frequency will provide this to you), and your S3 bucket name to allow Frequency to be able to access your bucket's files.

23069753.png
File Name Convention

Asset names must adhere to S3's Object key and metadata rules.

The name for a key is a sequence of Unicode characters whose UTF-8 encoding is at most 1,024 bytes long

Safe characters

Please ensure your file names only use the following safe characters:

Alphanumeric characters

  • 0-9

  • a-z

  • A-Z

Special characters

  • Forward slash ( / )

  • Exclamation point ( ! )

  • Hyphen ( - )

  • Underscore ( _ )

  • Period ( . ) Exception: Object name key cannot end with a single period (.), or two periods (..)

  • Asterisk ( * )

  • Single quote ( ' )

  • Open parenthesis ( ( )

  • Close parenthesis ( ) )