API Reference

HTTP Live Streaming

This tutorial uses the basics we explained in the tutorial How to encode videos. You should read it first if you haven't yet.

Mobile users growth rate has become so high that you have to make your videos perfectly viewable under any conditions.

Years ago, Apple released the HLS technology to stream a video with different bitrates so that it can adapt, whether you are using a phone with edge/3G/4G connection or a tablet with WiFi for example.

For iOS Developers

If you plan creating an iOS application, Apple requires using HLS if videos are longer than 10 minutes or exceeds 5MB of data in a 5 minutes period.

Create a new config file coconut.conf and write the usual lines:

var s3 = s3://accesskey:secretkey@mybucket/video

set source = http://media.s3.amazonaws.com/demo.mp4

Encoding videos for HLS

HTTP Live Streaming requires many technical steps that we do for you:

  • Encoding the videos into multiple formats with different bitrates. The format specs must be MPEG-TS H264 / AAC
  • Segmenting (splitting) the ts files in chunks of 10 seconds (default)
  • Generating a playlist in m3u8 for each variant video
  • Generating a master playlist in m3u8

Let's see how to do it:

hls -> $s3/hls/video.m3u8

By default, we use the following variants: aac_64k_22050hz hls_240p_300k hls_360p_600k hls_360p_1000k hls_480p_1500k hls_720p At the end of the process, you will find every variant playlists and ts files inside mybucket/video/hls/.

Super easy, right? Learn more about the HLS configuration.

To go further: Closed Captions

As you may know, if you are American, you must provide closed captioning for people who are deaf and hard of hearing. Read this guide to learn more.

Closed Captions

Fortunately for us, Apple added support for closed captions in WebVTT format.

To demonstrate the use of closed captions, we are going to add English and Spanish captions to our HLS video. Edit the config file like this:

var cc_urls = http://mysite.com/subtitle/demo-en.srt,http://mysite.com/subtitle/demo-es.srt
var cc_langs = en,es
var cc_names = English,Español

-> hls = $s3/video/hls/video.m3u8, caption_urls=$cc_urls, caption_languages=$cc_langs, caption_names=$cc_names

Thanks to caption_urls caption_languages and caption_names, we can handle multiple captions in SRT or WebVTT format separated by comma.

Submitting the config file

The config file looks like this so far:

var s3 = s3://accesskey:secretkey@mybucket/video

set source = http://media.s3.amazonaws.com/demo.mp4

# we suggest you to use our Webhook Inspector https://app.coconut.co/tools/webhooks
# to inspect the POST request we send. Very handy for testing
set webhook = http://yourserver.com/webhooks/coconut

-> hls = $s3/hls/video.m3u8

Here is the curl command to create the job:

curl https://api.coconut.co/v1/job \
-u api-key: \
-T coconut.conf

We provide a number of client libraries to make requests very easily, so be sure to check them out.

That concludes our tutorial about how to provide HTTP Live Streaming videos for mobile users. If you want to learn more, read the full documentation here.


In the Next tutorial, we will show you how to manage Webhooks in your application to retrieve all the media URLs and get notified about errors