Getting Started

EasyVMAF runs VMAF video quality analysis on files stored in an S3-compatible bucket. Given a reference video and a distorted version, it computes a VMAF score and writes the result as a JSON file back to S3. No local Python or FFmpeg installation is required.

VMAF (Video Multi-Method Assessment Fusion) is Netflix's open source perceptual video quality metric. It is widely used to validate transcoded renditions against a source before publication.

Prerequisites

  • An OSC account (sign up here)
  • A MinIO or S3-compatible bucket containing the reference and distorted video files. See Service: MinIO if you need object storage on OSC.

Store access credentials as secrets

Create secrets for your S3 credentials before creating an EasyVMAF instance. See the Working with Secrets guide for instructions.

For example, create secrets named accesskeyid and secretaccesskey containing your S3 credentials.

Run a VMAF analysis

Set your personal access token:

export OSC_ACCESS_TOKEN=<your-personal-access-token>

You find your token under Settings / API in the OSC console.

Create an EasyVMAF instance with the analysis arguments in cmdLineArgs:

npx -y @osaas/cli create eyevinn-easyvmaf-s3 myvmafrun \
  -o AwsAccessKeyId="{{secrets.accesskeyid}}" \
  -o AwsSecretAccessKey="{{secrets.secretaccesskey}}" \
  -o S3EndpointUrl="https://myminio.minio-minio.auto.prod.osaas.io" \
  -o cmdLineArgs="-r s3://videos/reference.mp4 -d s3://videos/distorted_1080p.mp4 -o s3://videos/distorted_1080p_vmaf.json"

Replace the S3 endpoint URL and bucket paths with your actual values. The instance runs the analysis and exits. The output file distorted_1080p_vmaf.json will appear in the specified S3 bucket when complete.

CLI arguments

The cmdLineArgs value is passed directly to the easyVmaf tool:

Argument Required Description
-r <s3-url> Yes S3 URL of the reference (original) video
-d <s3-url> Yes S3 URL of the distorted (encoded) video
-o <s3-url> Yes S3 URL where the JSON result will be written
--phone No Use the VMAF phone model instead of the default HD model
--model HD\|4K No Specify HD (default) or 4K VMAF model

Example: compare two renditions

npx -y @osaas/cli create eyevinn-easyvmaf-s3 vmaf4k \
  -o AwsAccessKeyId="{{secrets.accesskeyid}}" \
  -o AwsSecretAccessKey="{{secrets.secretaccesskey}}" \
  -o S3EndpointUrl="https://myminio.minio-minio.auto.prod.osaas.io" \
  -o cmdLineArgs="-r s3://videos/source_4k.mp4 -d s3://videos/transcoded_4k.mp4 -o s3://videos/result_4k_vmaf.json --model 4K"

Read the result

The output is a JSON file with per-frame VMAF scores and an aggregate score:

{
  "VMAF score": 94.32,
  "frames": [
    { "frameNum": 0, "metrics": { "vmaf": 96.1 } },
    ...
  ]
}

A score of 100 means the distorted video is perceptually identical to the reference. Typical thresholds for streaming delivery are 85–95 depending on the use case.

Resources