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

HLS and MPEG-Dash

Jump to

Every outputs must be set inside the outputs key with each value being a Hash describing the output format and settings.

Examples

Packaging into MPEG-Dash and HLS:

{
  "outputs": {
    "httpstream": {
      "hls": {
        "path": "/hls"
      },
      "dash": {
        "path": "/dash"
      }
    }
  }
}

Customizing the variants:

{
  "outputs": {
    "httpstream": {
      "hls": {
        "path": "/hls"
      },
      "dash": {
        "path": "/dash"
      },
      "variants": [
        "mp4:x:64k",
        "mp4:240p::quality=2",
        "mp4:480p::quality=3,maxrate=1500k",
        "mp4:720p::quality=4,maxrate=3000k"
      ]
    }
  }
}

Packaging into MPEG-Dash and HLS fMP4:

{
  "outputs": {
    "httpstream": {
      "dash": {
        "path": "/dash",
        "hlsfmp4": true
      }
    }
  }
}

Parameters

HLS & MPEG-Dash options

NameTypeDefaultRequired
path
The path where the files will be uploaded. See Destination.
string / No
if
If the given condition is false, the output won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT. See Conditional outputs.
string No
key
Will rename the output key which is sent in the notification payload. Very useful because you can change the output settings but the key name you get at the end will be unchanged. No code to update on your side.
string No
variants
A list of formats
The formats specs:
• container must be mp4
• Video codec must be either h264 (default), hevc, novideo
• Audio codec must be either aac or noaudio
array mp4:x:64k mp4:240p::quality=4,maxrate=400k mp4:360p::quality=4,maxrate=1000k mp4:480p::quality=4,maxrate=1500K mp4:720p::quality=4,maxrate=2000k mp4:1080p::quality=4,maxrate=4000k mp4:2160p::quality=4,maxrate=8000k 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.
hash No
path
The relative path where the different Dash files will be uploaded.
string Yes
hlsfmp4
Will also generate HLS fMP4 playlist files.
bool No
hls
Enable packaging into HLS (.TS Files).
hash No
path
The relative path where the different HLS files will be uploaded.
string Yes
version
if version=3, the media will be segmented (multiple files) instead of fragmented (single file).
int 3 No
segment_duration
The segment duration in second. By default 4sec or 5sec depending on the original GOP.
int 4|5 No


Video manipulation

NameTypeDefaultRequired
fit
Option to change the fit mode. To keep the original aspect ratio by cropping instead of padding (default behavior), set fit=crop
width and height are required.
string pad No
transpose
Rotate the video
0 90CounterCLockwise and Vertical Flip (default)
1 90Clockwise
2 90CounterClockwise
3 90Clockwise and Vertical Flip
We automatically use transpose for videos taken in portrait mode.
int 0 No
vflip
Vertically Flip the video
We automatically use vflip for videos taken upsidedown.
bool false No
hflip
Horizontally Flip the video
We automatically use hflip for videos taken upsidedown.
bool false No
duration
Max duration in second of the video. if 10, the encoded video length will be 10 seconds.
int No
offset
Will start the encoding at the given offset in second.
int No
watermark
Overlay an image (PNG) over the video.
hash No
url
URL of the png image that will be incrusted in the video. Transparent and semi-transparent images are compatible.
URL No
position
Position of the watermark.
topleft topright bottomleft bottomright
string topleft No


Add a watermark and cut the output at 2min:

{
  "outputs": {
    "httpstream": {
      "dash": {
        "path": "/dash",
        "hlsfmp4": true
      },
      "duration": 120,
      "watermark": {
        "url": "https://host/coconut/watermark.png",
        "position": "bottomright"
      }
    }
  }
}

DRM and Encryption

Widevine (Dash only)

NameTypeDefaultRequired
dash
hash No
widevine_pssh
Widevine PSSH
string No
encryption_key
Encryption key.
Syntax is: KeyIDHex:KeyHex
string No

Playready (Dash only)

NameTypeDefaultRequired
dash
hash No
playready_laurl
The license Acquisition URL
URL No
encryption_key
Encryption key.
Syntax is: KeyIDHex:KeyHex
string No



Widevine and Playready example:

{
  "outputs": {
    "httpstream": {
      "dash": {
        "path": "/dash",
        "widevine_pssh": "htb3ZpZVjRG9ubDQHRhPY2NaE65qWBi3cQQs2yGgLI0iZNUjSIQ0gkxEh7mH9WEj3JWbBg==",
        "playready_laurl": "https://playready.ezdrm.com/cency/preauth.aspx?pX=ECD463",
        "encryption_key": "d21875b042cddb98018d7f6b7718ddb2:be02128f059b70c9e6a2e9d02ae64e14"
      }
    }
  }
}

Fairplay (HLS only)

NameTypeDefaultRequired
hls
hash No
encryption_mode
Must be SAMPLE-AES
string No
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
encryption_key_uri
DRM server URI
string No



Fairplay example:

{
  "outputs": {
    "httpstream": {
      "hls": {
        "path": "/hls",
        "encryption_mode": "SAMPLE-AES",
        "encryption_key": "d013b7710d187bd8d8d6987f5b42cdb2:be260ec912d4e9f020e68e59b7a2a014",
        "encryption_key_uri": "skd://fps.ezdrm.com/;1XXXXXX0-c7ed-4XXX-b15c-XXXXXXXXXa25"
      }
    }
  }
}

Simple HTTP Key Delivery (HLS only)

NameTypeDefaultRequired
hls
hash No
encryption_mode
Must be AES-128
string AES-128 No
encryption_key
Hexadecimal key to enable AES-128 encryption.
string No
encryption_key_uri
Encryption key URI (may be a relative or absolute URI).
string key.bin No



AES Encryption example:

{
  "outputs": {
    "httpstream": {
      "hls": {
        "path": "/hls",
        "encryption_mode": "AES-128",
        "encryption_key": "ba66aa7334ba85b3bc093db1db3ab931",
        "encryption_key_uri": "http://yoursite.com/hls/aes/key.bin"
      }
    }
  }
}

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>