The Coconut Blog

Want to be updated? @opencoconut | Feed

Announcing support of sprite, vtt and new every options for thumbnail generation

October 17, 2018 Features

New API version: 2018-10-17

We've worked hard on the preview API so your users can have the best experience. Today, we are announcing 3 new features just for thumbnails that we hope you and your users will enjoy.

Generate thumbnails every 10 seconds

It's now possible to generate thumbnails every X seconds, so you won't have to calculate offsets yourself. We do the math for you.

-> jpg:160x = $s3/sprite.jpg, every=10

If you set every=0, we even calculate the right gap according to the following rules:

  • every 2 sec if duration <= 2 min
  • every 5 sec if duration <= 10 min
  • every 10 sec if duration <= 30 min
  • every 20 sec if duration <= 60 min
  • every 30 sec if duration > 60 min

A single Sprite image instead of hundred images is better

It's faster to retrieve one "big" image instead of small hundred images from an external resource, that's why we've added the new sprite option. Here is an example:


To generate it, it's easy:

-> jpg:160x = $s3/sprite.jpg, every=5, sprite=yes

I want my player to show toolip thumbnails like Netflix does!

To make your HTML5 player shows the right thumbnail at the right time, you need a WebVTT file which includes a list of cues with the corresponding individual thumbnails or single sprite file with the right coordinates. We provide both!

Here is an example of a WebVTT file:


00:00:00.000 --> 00:00:05.000

00:00:05.000 --> 00:00:10.000

00:00:10.000 --> 00:00:15.000

00:00:15.000 --> 00:00:20.000

00:00:20.000 --> 00:00:25.000

To generate it along with a sprite file:

-> jpg:160x = $s3/sprite.jpg, every=5, sprite=yes, vtt=yes

You can read the documentation about all these cool features here.

Announcing support of DRM Widevine, Playready and Fairplay for HLS and MPEG-Dash

September 07, 2018 Features

New API version: 2018-09-05

We are pleased to announce the support of the well known DRM Widevine, Playready and Fairplay for HLS and MPEG-Dash. You will be able to protect your content no matter the target platform with just a couple of new line in your config file.

Here is how you can protect your files using Widevine and Playready DRM:

var widevine_pssh = htb3ZpZVjRG9ubDQHRhPY2NaE65qWBi3cQQs2yGgLI0iZNUjSIQ0gkxEh7mH9WEj3JWbBg==
var playready_laurl =
var dash_encryption_key = d21875b042cddb98018d7f6b7718ddb2:be02128f059b70c9e6a2e9d02ae64e14

-> httpstream = $s3/,

To use Fairplay DRM, it's simple as AES-Encryption, except you need to set the HLS Encryption mode to SAMPLE-AES:

var hls_encryption_key = d013b7710d187bd8d8d6987f5b42cdb2:be260ec912d4e9f020e68e59b7a2a014
var hls_encryption_key_uri = skd://;1XXXXXX0-c7ed-4XXX-b15c-XXXXXXXXXa25

-> httpstream = $s3/,

You can learn more about HTTPStream output here.

DigitalOcean Spaces supported

September 06, 2018 Features

Hey DigitalOcean happy users πŸ‘ŠπŸ»

We just added the new DigitalOcean Spaces as one of our many output destinations. They choose to be AWS S3 compatible, which is a good thing as we support many other services like this.

Here is an example:


Note that we set the HTTPS protocol to force the upload to be secured.

Package for HLS and MPEG-Dash with the new HTTPstream output

October 31, 2017 Features

New API version: 2017-10-31

We've worked hard in the past few months to bring you a new output httpstream to package both HLS and MPEG-Dash at the same time at the cost of only one output. Under the hood, we convert the source files to mp4 formats and use the result to generate HLS and MPEG-Dash streams.

In this release, we support both HLSv4 (MPEG TS files), HLSv6 (HLS fMP4) and MPEG-Dash.

The syntax is simple as usual:

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

The httpstream also supports HLS AES Encryption (only HLSv4):

-> httpstream = $s3, hls=/hls, playlist_name=master, hls_encryption_key=ba66aa7334ba85b3bc093db1db3ab931, hls_encryption_key_uri=

You can learn more about HTTPStream output here.

In the meantime, we removed HLS and dash outputs in this release, so be sure to migrate to httpstream before you upgrade your API version from your account.

Backblaze B2 supported

January 19, 2017 Features

We are happy to announce the support of a new CDN called Backblaze B2, it's similar to AWS S3 but for 1/4th the cost!

The syntax is simple as usual:

-> mp4 = b2://account_id:app_key@bucket_id/path/filename.mp4

You can learn more about all the CDN we support here.

Simple Formats v2

May 31, 2016 Features

Simple Formats, formerly Dynamic Formats, just got a major update that makes the need to create a format – the old fashioned way – totally useless and deprecated.

Unlike the first version, you can specify any format specs you need, including codecs, bitrates, FPS, sample rate, audio channels and even 2pass encoding option. But don't worry, with Coconut, we like to keep things simple, so 95% of the time, you will just customize the resolution as usual. Keep in mind that all those options are here for users having specific needs!

The syntax changed to support all possible options. However, we will continue to support the old one. You are still advised to update all the formats including v1 and the really old ones created via a form (with integer ID).

So here is the new syntax:


Instead of mixing video and audio settings, we choose to separate them with :. Settings order becomes irrelevant, which is clearer and simpler while making available all possible options.

For example the popular format MP4 720p was written like this in the first version: mp4_720p. Now it's mp4:720p, so as you can see the change is small!

Let's see some more complicated examples to show you all the new possibilities that you couldn't do before:

Simple FormatDescription
mp4:1080p:256kSet the audio bitrate to 256k
mp4:1080p:xDisable the audio track
mp4:720p::2passUse 2pass encoding while keeping the default audio specs
mp4:x:64k_monoMP4 format with audio only at 64kbits and in mono channel
mp4:xDisable the video track while keeping the default audio specs
webm:720p_1400kWebM 720p with video bitrate = 1400kbps
webm:240p_15fps:64kFramerate is set to 15fps and the audio bitrate at 64kbits
webm:1080p:256k_48000hz:2passWebM 1080p with audio bitrate at 256kbits, sample rate at 48000Hz and 2pass encoding enabled
mp4:hevc_1080p_2500k_30fps:256k_48000hzMP4 HEVC with video bitrate at 2500kbits, framerate at 30fps, audio bitrate at 256
mp3:monoMP3 audio only format with mono channel
mp3:22050hz_monoMP3 audio only format with sample rate set to 22050hz and mono channel
aac:256kAAC audio only format at 256kbps
wav:48000hzWAV audio only format with sample rate set to 48000hz

To learn more about Simple Format various options, you can read the full documentation.

Introducing MPEG-DASH support

May 25, 2016 Features

API version: 2016-05-24

To upgrade, connect to your dashboard to review the changes with care and click on the button to immediately upgrade your version.

Here is the list of changes.

New MPEG-DASH output

The MPEG-DASH or Dynamic Adaptive Streaming over HTTP program allows streaming videos to be played over a variety of different internet connections. This is similar to Apple's HTTP Live Streaming (HLS).

Unlike HLS, MPEG-DASH is widely adopted by other constructors and services like Samsung, Sony, Google and Netflix. If you want adaptive bitrate streaming for Android devices, this is definitely the way to go as DASH is supported natively on this platform.

Using it with Coconut is straightforward as usual with our API:

-> dash = $s3/video.mpd

You can learn more in the MPEG-DASH documentation.

Thumbnail fit option

You can now select the fit mode between pad (default) and crop. crop is especially useful when you want a fixed thumbnail resolution while keeping the original aspect ratio and do not want black bars. Here is a comparison of a thumbnail 600x200 but with different fit mode:

fit comparison

The thumbnail with fit=crop is way better, don't you think? Again, enabling this option is simple:

-> jpg:600x200 = $s3/thumb.jpg, fit=crop

You can learn more in the thumbnail documentation.

Have a question or feedback? Contact us

API update: Webhook event, thumbnail offsets and more

May 12, 2015 Features

API version: 2015-05-07

To upgrade, connect to your dashboard to review the changes with care and click on the button to immediately upgrade your version.

Here is the list of changes.

Webhook event

Sometimes you need to know in real time when something happens like a source file transferred or an output processed. You can now receive a webhook when a specific event is triggered. In addition to this, you will get an overall progress in percent so you can show a nice progress bar in your application.

To get notified for each event, declare your webhook URL like this:

set webhook =, events=true

An example of webhook when an output is processed:

  "id": 5194,
  "event": "output.processed",
  "progress": "75%",
  "format": "mp4:240p",
  "url": ""

You can learn more in the webhook documentation.

Thumbnail offsets

Another feature asked by developers is a way to grab a thumbnail at specific time of the video. It is now possible thanks to the parameter offsets.

For instance, if we want to get 3 thumbnails at 5sec, 10sec and 15sec of the video, we will write this line in our config file:

-> jpg:300x = $s3/thumb_#num#.jpg, offsets=5,10,15

Amazon S3 custom headers

Finally, we added the support of any custom headers in Amazon S3 output URL. For example, you can control the cache expiration date or add any metadata headers you need. See the complete list of headers on the Amazon S3 documentation.

API update: receive all the metadata into the webhook

April 09, 2015 Features

API version: 2015-04-07

This update brings a feature often asked by developers, the access to the metadata.

You can now receive all the metadata of the source and output videos directly into the webhook. Simply use the new metadata parameter in the webhook declaration:

set webhook =, metadata=true

You can see an example of a webhook with metadata enabled in the webhook documentation.

Upgrading to the new API version

Connect to your dashboard to review the changes with care and click on the button to immediately upgrade your version.

We hope you will enjoy this update, happy coding!

AWS Signature V4 for new S3 regions supported

March 31, 2015 Features

3 years ago, Amazon Web Service announced in their forum a new signature algorithm called AWS Signature Version 4 for even more security. Existing regions are still compatible with V2, whereas the new ones launched after January 30, 2014 only support V4 like the Frankfurt and Beijing regions.

So today, we added support for AWS Signature V4 which is now the default algorithm used by the Coconut platform. There is nothing to do on your side when providing the S3 output_url, we automatically retrieve the bucket location which is an essential part in the signature Version 4.

Thumbnail filename sequence number with printf

March 03, 2015 Features

We just added a new functionality that lets you customize the thumbnail filename sequence number.

By default we use the special variable #num# that is a 2 digits sequence number (%.2d) so you get thumb_01.jpg, thumb_02.jpg, thumb_03.jpg, etc by default. If you are not happy with this choice, you can now set your own printf format identifier. Note that we currently support decimal format only.

For instance, if you don't want the 0 before the first 9 numbers, just set the filename like this: thumb_%1d.jpg and you will get thumb_1.jpg, thumb_2.jpg, etc. Easy enough!

Introducing the Coconut API v2

January 08, 2015 Features

We are thrilled to now show you the new API we've been building for the past months, which is by far the best and easiest API we have ever released.

8 years old

The original Coconut API turned 8 without really having any breaking changes. It means the code you wrote at that time is still working today, which is pretty exceptional by today's standards!

Our API was created at a time where everyone just needed a simple Flash version of their videos, so that visitors could watch them on the web. The workflow was pretty straightforward: Transfer -> FLV Encoding -> Deliver. Today, it's way more complicated due to all the new formats: MP4, WebM, HLS, JPG (thumbnails), GIF, and soon HEVC and VP9. That's a lot of work!

In 8 years we have seen multiple revolutions in the video industry, for example the rise of the H264 codec, the WebM codec released by Google, the revolution in the mobile industry with iPhone and Android devices, HTTP Live Streaming, and more. All these changes got us transcoding into more and more formats.

First attempt

We introduced the Robot API a couple of years ago. We wanted a simple API that managed everything for you: you submitted a simple config file and we executed everything in the background. You just needed to handle the single webhook sent at the end of the process.

It was great, it simplified the integration process a great deal, but it was just a layer built on top of our original API. The original API was still everywhere and every bit of the Robot implementation was pointing to it. We needed to move on.

Moving on

We designed a complete new API with today's transcoding needs in mind, all by keeping the flexibility of the Robot API.

From now, the Core API, Preview API, HLS API and Robot API are deprecated and we advise you to migrate as soon as possible to the new one. For those using the Robot API, it’s very simple as you just need to rewrite the config file and adapt your webhook script a little.

Introducing the new API

It is pretty straightforward to use the new API: you submit a config file and you wait for a webhook when the process is done (sounds familiar?) That's about it.

Here is a typical configuration sample coconut.conf:

var vid = abcdefg
var s3  = s3://a:s@videobucket/videos/$vid/outputfile1234

set source  =
set webhook =$vid

-> mp4  = $s3.mp4
-> webm = $s3.webm
-> hls  = $s3.m3u8
-> jpg:300x = $s3_#num#.jpg, number=3

The config file is so simple that it's self-explanatory. It's also very easy to submit the job:

curl \
-u api-key: \
-T coconut.conf

To learn more, read the full documentation and our getting started tutorials on how to encode videos.

If you have any questions or need any help migrating to this new API, send us an email! We hope you will enjoy this new API as much as we do.

Introducing a new 1GB free plan for startups, developers and students.

December 03, 2014 Features

Today, we are thrilled to introduce a 1GB free plan.

Whether you are a startup, a developer or a student, you can now get 1GB free every month to start your project.

Instead of building your own encoding system to save money, enjoy our encoding service at no cost.

Note that you can review all our plans on our pricing page.

Now supporting any S3 compatible services as output URL

September 30, 2014 Features

Today, we are adding support for any cloud storage platforms providing S3-compatible API such as:

To get your videos tranferred to an S3-compatible service, you just need to set the host in the output URL like this:

output_url = s3://accesskey:secretkey@bucket/path/objectkey?

You can see all the CDN and protocols we support here.

Introducing API Keys with different environment

September 30, 2014 Features

We introduced the sandbox environment to integrate and test Coconut for free years ago.

The only caveat was that the environment was setup at the account level. If you wanted to test new features while your app was already live, you were out of luck. Your only option was to create another account, which was not really convenient.

This is why, we are introducing the notion of environment per API key. Instead of having many accounts with different environments, you only have one with several API keys.

api keys

Generating a new API key is easy: go to your control panel, select either sandbox or production and click on the Generate button.

Adding watermark support to the HLS API

September 09, 2014 Features

We just added watermark support to the HLS API so you can better work on your brand on mobile devices. Use the already known parameters watermark_image_url and watermark_position from the Job resource, that's easy!

video_id = ${get:video::id}
format_ids = aac_64k_22050hz,hls_416x234_110k,hls_416x234_200k,hls_360p_600k,hls_360p_1000k,hls_720p,hls_1080p
watermark_image_url =
watermark_position = bottomright
output_url = s3://...@bucket/video/

Read more info about watermarking your videos here.

New option to start encoding at a given offset

June 25, 2014 Features

We just added a new encoding option offset, to set the start time offset in second. Note that, combined with duration, you can create chunks of video wherever you want.

For instance, to create a fragment of 10 seconds starting at 1 minute:

video_id = ${get:video::id}
format_id = mp4
offset = 60
duration = 10
output_url = s3://....
```<hr />

<h2><a href="/blog/features/2014-06-25-introducing-openstack-storage-support">Introducing OpenStack Storage support</a></h2>
<p class="date">
<br /><br /><i class="fa fa-calendar"></i> June 25, 2014 <span class="category"><a href="/blog/features"><i class="fa fa-folder"></i> Features</a></span></p>

<img class="right" src="" alt="" style="width:200px;box-shadow:none" />

Today, we are happy to announce the support of OpenStack Storage as a new [destination](/docs/output-urls) for your encoded videos.

[OpenStack]( is an Open Source Cloud Platform created in 2010 by RackSpace and NASA. Today, more than 200 companies have joined the OpenStack project.

From now, send your encoded videos directly to your hosted [OpenStack Storage]( with Coconut. We created a new output URL scheme for that purpose:

os://auth_token@host/v1/account/container/filename ```

You will find the complete list of cloud providers and protocols we support in output here.

HLS improvements

June 25, 2014 Features

Today, we have added a couple of improvements to our HLS API to better comply with the Apple's requirements.

Bandwidth values are more accurate

The Apple's mediastreamvalidator was complaining about the bandwidth values written in the playlists because they were too far from the actual media bitrates. Here is a typical warning message if it exceeds 10%:

WARNING: Media segment bandwidth exceeded target playlist bandwidth by 61 % ( 2.48 Mbits/sec vs. 1.54 Mbits/sec, limit is 10 %).

All the warning messages are now gone and the playlists we generate are 100% valid.

Support of Audio-only streams

iOS applications using HLS over cellular networks are required to provide at least one audio stream at 64KB/s, so in case of a very bad internet connection, the user is still able to listen to the audio track.

Coconut supports both MP3 and AAC formats. See an API example:

video_id = ${get:video::id}
format_ids = aac_64k_22050hz,hls_416x234_110k,hls_416x234_200k,hls_360p_600k,hls_360p_1000k,hls_720p,hls_1080p
output_url = s3://...@bucket/video/

Read more about the HTTP Live Streaming API here.

The control panel just got way better with an API Request Builder, a Ping Inspector and more

May 27, 2014 Features

We are thrilled to announce new features for the Control Panel that will help a lot with your Coconut integration.

Introducing a visual API Request Builder

We totally revamped the Job creation form that is not just a basic form anymore, but a very powerful API Request Builder that lets you use every APIs we provide. You can either submit the job directly through the interface or get the generated config to use with your code.

A Ping Inspector to inspect and debug Webhooks

One of the fundamental part of Coconut is the ping notification we send to you when specific events occur. Services like exist for that purpose but giving you this feature out of the box makes sense because everything is in one place and more integrated into the control panel.

Ping Inspector

Use the given URL whenever you need to and we will show you a nice HTTP request with syntax highlighting.

Better API Logs, available for 3 days

We now give access to 3 days of data so you have more time finding an information or a bug. We also improved the design of the page which makes everything clearer.

API logs

The control panel has never been this useful! We though a lot about how we can help you integrate Coconut very quickly and easily and we hope that all these features will improve your overall experience.

API update: 3 thumbnails generated by default

May 12, 2014 Features

Depending on your project, the default thumbnail we generated was too small. Your only option was to use the preview API to get another one that better fits your needs.

To improve that part, we now generate 3 thumbnails in small (100px), medium(300px) and large (600px) sizes for each videos and encoded videos you have in your account.

The JSON output has been updated to reflect this change:

  "created_at": "2014-05-12T13:52:49+02:00",
  "updated_at": "2014-05-12T13:52:49+02:00",
  "title": "testthumb",
  "specs": {
    "mime_type": "video/mp4",
    "size": 7111,
    "video": {
      "length": 17,
      "pix_format": "yuv420p",
      "bitrate": 3283,
      "fps": 30.0,
      "width": 320,
      "height": 240,
      "container": "mov",
      "stream": 0.0,
      "codec": "h264",
      "aspect": 1.33,
      "rotation": 0
    "audio": {
      "bitrate": 128,
      "sample_rate": 44100,
      "codec": "aac",
      "channels": 1,
      "stream": 0.1,
      "synched": true
    "thumb": "",
    "thumbnails": {
      "small": "",
      "medium": "",
      "large": ""
  "url": "",
  "link": "",
  "filename": "1051",
  "id": 35942302

Nothing to do on your side, everything is done automatically. Keep in mind that if you need other sizes and more than one thumbnail, the preview API is still your best friend.

Introducing new plans for startups and developers

May 09, 2014 Features

Today, we are thrilled to announce brand new plans starting at $5/month. If you are a startup or a developer, you can now afford to start your encoding project in the cloud.

You can review all our plans on our pricing page and subscribe easily to one of them in your Coconut account.

New Plans

HEVC and VP9 now supported (Beta)

April 16, 2014 Features

We are excited to announce our support for the next generation encoding HEVC and VP9 codecs in beta.

Adding these new video codecs will allow Coconut to bring cloud video encoding to a whole new level in meeting the highest video industry requirements. HEVC video codec delivers 50% better compression than its H.264 predecessor.

Trying the HEVC or VP9 codecs is simple thanks to the dynamic format IDs and their simple syntax:

  • HEVC with MP4 container: mp4:hevc
  • VP9 with WebM container: webm:vp9

HEVC and VP9 are the future of video and promise to deliver even higher video quality for an incredible lower video bit rate, which will be great for Ultra High Definition and 4K standard.

Specifying codecs in dynamic format IDs

April 15, 2014 Features

With Dynamic format IDs, you could use standard formats such as MP4 with H264 / AAC codecs by just naming the format_id mp4. Very handy. But if you want to use another codec instead, like H263, you had to create a new format the old way.

Today, we updated the dynamic format feature to let you choose the video codec and audio codec of your choice. The new naming becomes:


$VCODEC and $ACODEC are absolutely not mandatory, use them only if you need to.

Let's say you want to use the H263 codec with an MP4 container:

$ coconut format:info mp4:h263
  "container": "mp4",
  "audio_channels": 2,
  "owner": false,
  "audio_codec": "aac",
  "category": null,
  "fps": 0.0,
  "name": "mp4:h263",
  "width": 640,
  "video_bitrate": 800.0,
  "video_codec": "h263",
  "id": "mp4:h263",
  "sample_rate": 44000,
  "two_pass": false,
  "height": 0,
  "audio_bitrate": 128.0

Another format with the Matroska container and H264 / MP3:

$ coconut format:info mkv:h264:mp3_720p
  "owner": false,
  "category": null,
  "container": "mkv",
  "height": 720,
  "name": "mkv:h264:mp3 720p",
  "width": 1280,
  "fps": 0.0,
  "sample_rate": 44100,
  "video_codec": "h264",
  "id": "mkv:h264:mp3_720p",
  "video_bitrate": 1500.0,
  "audio_bitrate": 128.0,
  "two_pass": false,
  "audio_channels": 2,
  "audio_codec": "mp3"

Read our article to learn more about Dynamic Format IDs.

Other posts