Use the REST API

To simplify the process of running a bunch of measurements, we've also developed a simple to use REST API.

Current features

• Possible to start new AutoVMAF jobs.
• Possible to run multiple AutoVMAF jobs in parallel.
• Monitor how long a job have been running (milliseconds) and the status i.e ACTIVE/INACTIVE.
• Download and compile VMAF results from S3 for all measured bitrates and resolutions for a specific job.

New AutoVMAF workers will automatically be created if all current ones are in use. This makes it really easy to create and run jobs in parallel.

Endpoints

Available endpoints are:

Endpoint	Method	Description
/	GET	Heartbeat endpoint of service
/autoabr	POST	Create a new autoabr job. Provide JSON body with settings
/autoabr	GET	List all active autoabr workers
/autoabr/:id	GET	List info about a specific autoabr worker
/autoabr/result/:output/	GET	Download VMAF results from S3 and compile it into JSON. NOTE: Trailing slash is not optional!
/autoabr/result/:output/:model	GET	Download VMAF results from S3 and compile it into JSON for a specific model
?format=csv or ?format=tsv	-	Optional query parameter for the /autoabr/result/ endpoints. Compiles results into CSV or TSV.
/autoabr/cache	DELETE	Clear MediaConvert and AWS pipeline settings cache

Setup

You can run the API as an NPM package or as a Docker container, the latter being easiest.

Environment

The following environment variables need to be set no matter what way you chose to run the API. Using an .env file is supported. Just rename .env.example to .env and insert your values.

AWS_ACCESS_KEY_ID=MyAccessKeyID
AWS_SECRET_ACCESS_KEY=MySecretAccessKey
AWS_REGION=eu-north-1
LOAD_CREDENTIALS_FROM_ENV=true // If false, it will load credentials from ~/.aws/credentials

NPM package

Install the package:

npm install --save @eyevinn/autoabr-api

To initialize a new AutoabrService do:

index.ts

import { AutoabrService } from "@eyevinn/autoabr-api";

// initialize a new instance of AutoabrService
const autoabrService = new AutoabrService();
// register the routes
autoabrService.listen(3000);

Start¹ the service:

ts-node index.js

The AutoVMAF service is now up and running and available on port 3000.

Docker

The easiest way to run the API is through Docker.

docker run -e 'AWS_ACCESS_KEY_ID=MyAccessKeyID'\
           -e 'AWS_SECRET_ACCESS_KEY=MySecretAccessKey'\
           -e 'AWS_REGION=eu-north-1'\
           -e 'LOAD_CREDENTIALS_FROM_ENV=true'\
           -p 3000:3000 eyevinntechnology/autovmaf-api

Or, if you want to use the env-file:

docker run --env-file .env -p 3000:3000 eyevinntechnology/autovmaf-api

Using Docker Compose

version: "3.7"

services:
 autovmaf-api:
    image: eyevinntechnology/autovmaf-api
    container_name: autovmaf-api
    env_file: .env
    restart: unless-stopped
    ports:
      - 3000:3000

Example Requests

Start a job

To start a new AutoVMAF job send a POST request to the /autoabr endpoint with the following payload:

{
  "encodingSettingsUrl": "s3://bucket-name/encoding-profile.json",
  "pipelineUrl": "s3://bucket-name/pipeline.json",
  "job": {
    "name": "job-name",
    "reference": "s3://bucket-name/reference.mov",
    "models": ["UHD"],
    "bitrates": [10000000, 12800000],
    "resolutions": [
      {
        "width": 768,
        "height": 432
      },
      {
        "width": 1280,
        "height": 720
      },
      {
        "width": 1920,
        "height": 1080
      },
      {
        "width": 2560,
        "height": 1440
      },
      {
        "width": 3840,
        "height": 2160
      }
    ]
  }
}

Get results

The endpoint /autoabr/result/:output/ (output is the output specified in the job payload) will download and process all resulting VMAF files from AWS and return the result. This process can take a while depending on how many resolutions and bitrates that have been generated. This means that the response from the endpoint can take several seconds.

Example JSON Response

GET /autoabr/result/job-name/

{
  "id": "BxTH45aRiyAAq_TBbbHqH",
  "status": "INACTIVE",
  "result": {
    "job-name": {
      "PhoneHD": {},
      "HD": {
        "1280x720_10000000_vmaf.json": 91.12216,
        "1280x720_12800000_vmaf.json": 91.12216,
        "1920x1080_10000000_vmaf.json": 97.427916,
        "1920x1080_12800000_vmaf.json": 97.427916
      },
      "UHD": {}
    }
  }
}

Example CSV Response

GET /autoabr/result/job-name/?format=csv

jobname,model,width,height,bitrate,score
job-name,HD,1280,720,10000000,91.12216
job-name,HD,1280,720,12800000,91.12216
job-name,HD,1920,1080,10000000,97.427916
job-name,HD,1920,1080,12800000,97.427916

Example TSV Response

GET /autoabr/result/job-name/?format=tsv

jobname model   width   height  bitrate score
job-name    HD  1280    720 10000000    91.12216
job-name    HD  1280    720 12800000    91.12216
job-name    HD  1920    1080    10000000    97.427916
job-name    HD  1920    1080    12800000    97.427916

Info

TSV (Tab Separated Values) are very easy to copy/paste into Excel

---

1. You will have to have ts-node installed in order for this to work. ↩