Why isn't my video ready yet?

A couple of times a month, we get queries about a video not being ready to play. In this post we'll walk through how you can check the status of your video upload using our API and using our webhook.

Sometimes we'll be asked: "I uploaded my video a few minutes ago, and the quality is really pixelated. Why does my video look so bad?"

Both of these questions have roots with the same phenomenon. When a video is uploaded, there is a period of time while the api.video servers encode your video, and place it on our hosting server for delivery. Until the videos are encoded, they cannot be played back.

When we can up the video's encoding status on our backend, and we often see something like:

The 240p video took 17 minutes to encode, but is ready for playback. The other video qualities are being processed, but are not yet ready, so when the developer looks at the video, she only sees the 240p version. For an idea of why this video was so slow, the video was 120 minutes long. Shorter videos encode faster than longer ones, because there is less data to process.

Our first user (above) had a very long video, and none of the versions had been encoded yet.

You can check this yourself!

The video status API endpoint will give you the encoding status of each version of your video.

"encoding":{
"playable":true
"qualities":[
{
"quality":"360p"
"status":"encoded"
}
{
"quality":"480p"
"status":"encoded"
}
{
"quality":"720p"
"status":"encoded"
}
{
"quality":"1080p"
"status":"encoding"
}
{
"quality":"2160p"
"status":"waiting"
}
]

This API is what we used to diagnose the video encoding above - we've used it to built an internal dashboard to tell where a video stands in the encoding pipeline. You could do this too!

In the JSON example above, all versions from 240p to 720p have been encoded and are ready to play. The 1080p encoding is in progress, and the 4K is waiting in the queue to be encoded.

Is my video ready to play?

With this endpoint, you can check to ensure that the minimum quality that you want is ready for playback. You can use this to decide whether or not to show the video on your site

Polling is slow

Polling a server for this status is slow and time consuming. If your app will be handling many videos being uploaded, you don't want to manage polling the status for each video.

Webhooks push the encoding status to you

We have a video encoding webhook that pushes an alert to your server whenever a video/quality combination is ready for playback. That way, you can set up a webhook, and let api.video tell you when your videos are ready for playback. You can see a demo at webhook.a.video, and read the blog post on how we built this app.

We're here to help

If you think your video encoding is slow, we're here to help you understand what is going on, and we are happy to help. But, you can also use our APIs and tools to get this information to your servers in an automatic fashion - and it might just give you the answer you are looking for. (And while we're here for support during the week, the API does not take evenings or weekends off.)