API documentation

Coconut's API is a config-based API built with simplicity and flexibility in mind.
Encode your first video in less than 5 minutes.

API Reference

HTTP Stream packager

Available since 2017-09-31

Keyword: outputs must be prefixed by the keyword -> followed by the format ID.

Format ID: httpstream

The first value is the output URL without filename.

Packaging into MPEG-Dash and HLS:

var s3 = s3://accesskey:secretkey@bucket

-> httpstream = $s3, dash=/dash, hls=/hls, playlist_name=master

Packaging into HLS fMP4 as well. Will use the same fragmented MP4 files than MPEG-Dash.

-> httpstream = $s3, dash+hlsfmp4=/dash, playlist_name=master

Parameters

NameTypeDefaultRequired
if
If the given condition is false, the output won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT..
string No
variants
A list of Simple Formats separated by commas
The formats specs:
• container must be mp4
• Video codec must be either h264, novideo
• Audio codec must be either aac or noaudio
format ID[,] mp4:x:64k,
mp4:x,
mp4:240p_400k:x,
mp4:360p_600k:x,
mp4:360p_1000k:x,
mp4:480p_1500k:x,
mp4:720p:x
mp4:1080p:x
No
playlist_name
The filename without extension that will be used for every playlist or manifest names.
string master No
dash
Enable packaging into MPEG-Dash. Value is the relative path where the different files will be uploaded.
string No
dash+hlsfmp4
Enable packaging into MPEG-Dash and HLS fMP4 (Fragmented MP4 Files). Value is the relative path where the different files will be uploaded.
string No
hls
Enable packaging into HLS (.TS Files). Value is the relative path where the different files will be uploaded.
string No

DRM and Encryption

Widevine (Dash only)

Available since 2018-09-05

NameTypeDefaultRequired
dash_widevine_pssh
Widevine PSSH
string No
dash_encryption_key
Encryption key
string No

Playready (Dash only)

Available since 2018-09-05

NameTypeDefaultRequired
dash_playready_laurl
The license Acquisition URL
URL No
dash_encryption_key
Encryption key
string No


Widevine and Playready example:
var widevine_pssh = htb3ZpZVjRG9ubDQHRhPY2NaE65qWBi3cQQs2yGgLI0iZNUjSIQ0gkxEh7mH9WEj3JWbBg==
var playready_laurl = https://playready.ezdrm.com/cency/preauth.aspx?pX=ECD463
var dash_encryption_key = d21875b042cddb98018d7f6b7718ddb2:be02128f059b70c9e6a2e9d02ae64e14

-> httpstream = $s3/,
   dash=dash/,
   playlist_name=master,
   dash_widevine_pssh=$widevine_pssh,
   dash_playready_laurl=$playready_laurl,
   dash_encryption_key=$dash_encryption_key

Fairplay (HLS only)

Available since 2018-09-05

NameTypeDefaultRequired
hls_encryption_mode
Must be SAMPLE-AES
string No
hls_encryption_key
DRM Encryption Key. With FairPlay, the key and IV are delivered together. The first 32 characters are used in the key file for "key" and the last 32 characters are used for "iv"
string No
hls_encryption_key_uri
DRM server URI
string No


Fairplay example:
var hls_encryption_key = d013b7710d187bd8d8d6987f5b42cdb2:be260ec912d4e9f020e68e59b7a2a014
var hls_encryption_key_uri = skd://fps.ezdrm.com/;1XXXXXX0-c7ed-4XXX-b15c-XXXXXXXXXa25

-> httpstream = $s3/,
   hls=hls/,
   playlist_name=master,
   hls_encryption_mode=SAMPLE-AES,
   hls_encryption_key=$hls_encryption_key,
   hls_encryption_key_uri=$hls_encryption_key_uri

Simple HTTP Key Delivery (HLS only)

NameTypeDefaultRequired
hls_encryption_mode
Must be AES-128
string AES-128 No
hls_encryption_key
Hexadecimal key to enable AES-128 encryption.
string No
hls_encryption_key_uri
Encryption key URI (may be a relative or absolute URI).
string key.bin No


AES Encryption example:
-> httpstream = $s3,
   hls=/,
   playlist_name=master,
   hls_encryption_key=ba66aa7334ba85b3bc093db1db3ab931,
   hls_encryption_key_uri=http://yoursite.com/hls/aes/key.bin

Variants

It is important that you separate the video from the audio track to be compliant with the DASH-if guidelines.

To use a video only format, name it like this mp4:720p:x. For an audio only format: mp4:x:64k.

Cross-Origin Resource Sharing (CORS)

You will need to setup the CORS headers if the playlist and mp4 files are hosted on a different domain, which is most likely the case. Here are the different headers you need to setup:

  • Access-Control-Allow-Headers: "origin, range"
  • Access-Control-Allow-Methods: "GET, HEAD, OPTIONS"
  • Access-Control-Allow-Origin: "*"
  • Access-Control-Expose-Headers: "Server,range"

If your files are hosted on Amazon S3, the CORS policy should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <MaxAgeSeconds>3000</MaxAgeSeconds>
        <AllowedHeader>*</AllowedHeader>
    </CORSRule>
</CORSConfiguration>