The HW Blog

Want to be updated? @HeyWatch | Feed

Thumbnail filename sequence number with printf

Bruno Celeste (@sadikzzz)

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 HeyWatch API v2

Bruno Celeste (@sadikzzz)

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 HeyWatch 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 in INI format and you wait for a webhook when the process is done (sounds familiar?) That's about it.

Here is a typical configuration sample heywatch.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 heywatch.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.

Eric Fontaine (@EricFontaine_)

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

Bruno Celeste (@sadikzzz)

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

Bruno Celeste (@sadikzzz)

September 30, 2014 Features

We introduced the sandbox environment to integrate and test HeyWatch 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

Bruno Celeste (@sadikzzz)

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

Bruno Celeste (@sadikzzz)

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">
<img src="" alt="" class="avatar" /> <a href="" target="_blank">Bruno Celeste</a> (<em><a href="" target="_blank">@sadikzzz</a></em>)</a>
<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 HeyWatch. 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

Bruno Celeste (@sadikzzz)

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.

HeyWatch 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

Bruno Celeste (@sadikzzz)

May 27, 2014 Features

We are thrilled to announce new features for the Control Panel that will help a lot with your HeyWatch 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 HeyWatch 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 HeyWatch very quickly and easily and we hope that all these features will improve your overall experience.

API update: 3 thumbnails generated by default

Bruno Celeste (@sadikzzz)

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

Eric Fontaine (@EricFontaine_)

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 HeyWatch account.

New Plans

HEVC and VP9 now supported (Beta)

Eric Fontaine (@EricFontaine_)

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 HeyWatch 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

Bruno Celeste (@sadikzzz)

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:

$ heywatch 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:

$ heywatch 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