Using Video Transcoding API

Video Transcoding API How To

Listing Available Providers

$ curl -X GET http://api.host.com/providers

[
  "elastictranscoder",
  "elementalconductor",
  "encodingcom"
]

Getting Provider Capabilities and Details

$ curl -X GET http://api.host.com/providers/encodingcom

{
  "name": "encodingcom",
  "capabilities": {
    "input": [
      "prores",
      "h264"
    ],
    "output": [
      "mp4",
      "hls",
      "webm"
    ],
    "destinations": [
      "akamai",
      "s3"
    ]
  },
  "health": {
    "ok": true
  },
  "enabled": true
}

Creating a Preset

Given a JSON file called preset.json:

{
  "providers": ["elastictranscoder", "elementalconductor", "encodingcom"],
  "preset": {
    "name": "sample_preset",
    "description": "This is an example preset",
    "container": "m3u8",
    "profile": "Main",
    "profileLevel": "3.1",
    "rateControl": "VBR",
    "video": {
        "height": "720",
        "width": "1080",
        "codec": "h264",
        "bitrate": "1000000",
        "gopSize": "90",
        "gopMode": "fixed",
        "interlaceMode": "progressive"
    },
    "audio": {
        "codec": "aac",
        "bitrate": "64000"
    }
  }
}

The Encoding API will try to create the preset in all providers specified in the providers field. It will also create a PresetMap registry on Redis, which is a map for all the provider's PresetIDs.

You can just set width or height instead of both if you want to maintain source's aspect ratio.

$ curl -X POST -d @preset.json http://api.host.com/presets

{
  "Results": {
    "elastictranscoder": {
      "PresetID": "1477507104705-jb2p0b",
      "Error": ""
    },
    "elementalconductor": {
      "PresetID": "sample_preset",
      "Error": ""
    },
    "encodingcom": {
      "PresetID": "sample_preset",
      "Error": ""
    }
  },
  "PresetMap": "sample_preset"
}

Creating a PresetMap

Sometimes users want to reuse a preset that's already defined in the provider, so it's possible to skip the preset creation and just map it to a Video Transcoding API preset. This is called a PresetMap in the API, and creating a new presetmap is very simple:

$ curl -XPOST -d '{"name":"1080p_mp4", "providerMapping": {"elastictranscoder": "1351620000001-000001"}, "output": {"extension": "mp4"}}' http://api.host.com/presetmaps

{
  "name": "1080p_mp4",
  "providerMapping": {
    "elastictranscoder": "1351620000001-000001"
  },
  "output": {
    "extension": "mp4"
  }
}

Listing PresetMaps

$ curl -X GET http://api.host.com/presetmaps

{
  "1080p_mp4": {
    "name": "1080p_mp4",
    "providerMapping": {
      "elastictranscoder": "1351620000001-000001"
    },
    "output": {
      "extension": "mp4"
    }
  },
  "sample_preset": {
    "name": "sample_preset",
    "providerMapping": {
      "elastictranscoder": "1477507104705-jb2p0b",
      "elementalconductor": "sample_preset",
      "encodingcom": "sample_preset"
    },
    "output": {
      "extension": "m3u8"
    }
  }
}

Deleting PresetMap

$  curl -XDELETE http://api.host.com/presetmaps/preset-1

Creating a Job

To create a job you need to specify a few required parameters: one or more preset, a provider, a video source. Additionally, there are optional parameters such as: callback URLs that notifies the transcoding progress and completion of the job and streaming parameters in case you want to create Adaptive Streamings outputs (HLS, DASH)

See an example below for job.json:

{
  "presets": ["preset_1", "preset_2"],
  "provider": "encodingcom",
  "source": "http://nytimes.com/BickBuckBunny.mov?nocopy",
  "statusCallbackInterval": 5,
  "statusCallbackURL": "http://callback.server.com/status",
  "completionCallbackURL": "http://callback.server.com/done",
  "streamingParams": {
    "SegmentDuration": 10,
    "Protocol": "hls"
  }
}

Then, make a POST request to the API:

$ curl -X POST -H "Content-Type: application/json" -d @job.json  http://api.host.com/jobs

{"jobId":"95e1ebbd6330f2b3"}

It's important to note that your callback server should be able to handle POST requests from the API.

Getting Job Details

With the jobId returned by job creation:

$ curl -X GET http://api.host.com/jobs/95e1ebbd6330f2b3

{
  "outputDestination": "s3://output-bucket",
  "providerJobId": "114",
  "providerName": "elementalconductor",
  "providerStatus": {
    "pct_complete": "0",
    "status": "pending",
    "submitted": "2016-03-31T22:01:16Z"
  },
  "status": "queued"
}