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"
}

Deleting Preset

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

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 outputs (preset + file name), a provider and a video source. Additionally, you can also provide some streaming parameters, used for Adaptive Streaming outputs (such as HLS and DASH, currently only HLS is supported).

See an example below for job.json:

{
  "outputs": [
    {"preset": "720p_mp4", "fileName": "my_video_720p.mp4"},
    {"preset": "1080p_mp4", "fileName": "my_video_1080p.mp4"},
    {"preset": "256p_hls", "fileName": "hls/my_video_480p.m3u8"},
    {"preset": "480p_hls", "fileName": "hls/my_video_480p.m3u8"},
    {"preset": "720p_hls", "fileName": "hls/my_video_720p.m3u8"},
    {"preset": "1080p_hls", "fileName": "hls/my_video_1080p.m3u8"},
    {"preset": "2160p_hls", "fileName": "hls/my_video_2160p.m3u8"}
  ],
  "provider": "encodingcom",
  "source": "s3://somebucket/folder/my_video.mov",
  "streamingParams": {
    "playlistFileName": "hls/playlist.m3u8",
    "segmentDuration": 5,
    "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"}

All file names are optional, the transcoding-api will pick some defaults:

• fileName: the default file name is derived from the source file and the preset information <source_file_minus_extension>_<preset_name>.<preset_extension> (for example, using the preset "sample_preset" defined above and the file "my_video.mov", the transcoding-api would pick "my_video_sample_preset.m3u8")
• playlistFilename: the default value is hls/index.m3u8 when protocol is "hls", otherwise no default value is assumed.

Getting Job Details

With the jobId returned by job creation:

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

{
  "providerJobId": "1477508730516-t2yo6o",
  "status": "finished",
  "providerName": "elastictranscoder",
  "progress": 100,
  "providerStatus": {
    "outputs": {
      "cbdf9a3886b84c10/awesome_video.mp4": ""
    }
  },
  "output": {
    "destination": "s3://mybucket/cbdf9a3886b84c10",
    "files": [
      {
        "path": "s3://mybucket/cbdf9a3886b84c10/awesome_video.mp4",
        "container": "mp4",
        "videoCodec": "H.264",
        "height": 1080,
        "width": 1920
      }
    ]
  },
  "mediaInfo": {
    "duration": 349315000000,
    "height": 1080,
    "width": 1920
  }
}

Please notice the the "providerStatus" field is provider specific and intended for debugging. All the other fields are reported in all providers.