Cloudinary Blog
How to generate waveform images from audio files

Many social networks, websites and messaging applications allow users to upload a wide variety of media files, and although the majority of files are in the form of images and video clips, a significant minority are audio files. When the website or application subsequently needs to display a thumbnail that describes the uploaded content, images can be cropped and resized down to scale, and a single frame from a video clip can be converted to an image and then also cropped and resized down to scale.

So what do you display when you need something to uniquely and visually represent an audio file? A useful solution is to display a waveform image, which is a visual representation of the audio file and is presented as a graph of the sound amplitude against time.

Creating waveform images

Cloudinary's media management service has support for uploading, manipulating and managing all kinds of media files, including images, videos and audio files. You can create waveform thumbnails of audio files just as easily as you can create thumbnails for images and videos, with fine control over the look & feel of the generated waveform image to match your graphic design and the responsive layouts of all devices and browsers. All the audio processing, image generation and manipulation takes place on-the-fly and in the cloud using dynamic URLs, and with no need to install any complex software.

Creating an image waveform from an audio file uploaded to your Cloudinary account is as simple as changing the file extension (format) of the Cloudinary audio delivery URL to an image format like PNG, and enabling the waveform flag (fl_waveform in URLs). By default, the resulting waveform image is delivered with a high resolution, so you will also want to scale down the resulting image.

For example, to generate a PNG waveform image of the bumblebee.mp3 audio file uploaded to Cloudinary's demo account, scaled to a height of 200 pixels and a width of 500 pixels:

Ruby:
cl_image_tag("bumblebee.png", :height=>200, :width=>500, :flags=>"waveform", :resource_type=>"video")
PHP:
cl_image_tag("bumblebee.png", array("height"=>200, "width"=>500, "flags"=>"waveform", "resource_type"=>"video"))
Python:
CloudinaryVideo("bumblebee.png").image(height=200, width=500, flags="waveform")
Node.js:
cloudinary.image("bumblebee.png", {height: 200, width: 500, flags: "waveform", resource_type: "video"})
Java:
cloudinary.url().transformation(new Transformation().height(200).width(500).flags("waveform")).resourceType("video").imageTag("bumblebee.png")
JS:
cl.videoTag('bumblebee.png', {height: 200, width: 500, flags: "waveform"}).toHtml();
jQuery:
$.cloudinary.image("bumblebee.png", {height: 200, width: 500, flags: "waveform", resource_type: "video"})
React:
<Video publicId="bumblebee.png" resource_type="video">
  <Transformation height="200" width="500" flags="waveform" />
</Video>
Angular:
<cl-video public-id="bumblebee.png" resource_type="video">
  <cl-transformation height="200" width="500" flags="waveform">
  </cl-transformation>
</cl-video>
.Net:
cloudinary.Api.UrlVideoUp.Transform(new Transformation().Height(200).Width(500).Flags("waveform")).BuildImageTag("bumblebee.png")
Audio waveform image of 500x200

Note that as well as generating waveform images from audio files, you can also generate waveform images from the audio track of a video file in the same way as described above: simply change the file extension of a Cloudinary video URL to an image format like PNG, and enable the waveform flag (fl_waveform in URLs).

Customizing the waveform image

You can also control the colors used in the waveform image with the color parameter (co in URLs) to set the color for the waveform (default white) and the background parameter (b in URLs) to set the background color of the image (default black).

For example, to generate the same PNG waveform image of the bumblebee.mp3 audio file in the example above in inverted colors - with the waveform rendered in black on a white background:

Ruby:
cl_image_tag("bumblebee.png", :height=>200, :width=>500, :flags=>"waveform", :color=>"black", :background=>"white", :resource_type=>"video")
PHP:
cl_image_tag("bumblebee.png", array("height"=>200, "width"=>500, "flags"=>"waveform", "color"=>"black", "background"=>"white", "resource_type"=>"video"))
Python:
CloudinaryVideo("bumblebee.png").image(height=200, width=500, flags="waveform", color="black", background="white")
Node.js:
cloudinary.image("bumblebee.png", {height: 200, width: 500, flags: "waveform", color: "black", background: "white", resource_type: "video"})
Java:
cloudinary.url().transformation(new Transformation().height(200).width(500).flags("waveform").color("black").background("white")).resourceType("video").imageTag("bumblebee.png")
JS:
cl.videoTag('bumblebee.png', {height: 200, width: 500, flags: "waveform", color: "black", background: "white"}).toHtml();
jQuery:
$.cloudinary.image("bumblebee.png", {height: 200, width: 500, flags: "waveform", color: "black", background: "white", resource_type: "video"})
React:
<Video publicId="bumblebee.png" resource_type="video">
  <Transformation height="200" width="500" flags="waveform" color="black" background="white" />
</Video>
Angular:
<cl-video public-id="bumblebee.png" resource_type="video">
  <cl-transformation height="200" width="500" flags="waveform" color="black" background="white">
  </cl-transformation>
</cl-video>
.Net:
cloudinary.Api.UrlVideoUp.Transform(new Transformation().Height(200).Width(500).Flags("waveform").Color("black").Background("white")).BuildImageTag("bumblebee.png")
Black on white waveform image

If you only want to capture the waveform of a specific segment of the audio file, you can use a combination of the following 3 parameters to specify the section of the audio file to sample for the waveform:

  • start_offset (so in URLs) specifies the start of the sample.
  • end_offset (eo in URLs) specifies the end of the sample.
  • duration (du in URLs) specifies the duration of the sample.

For example, to display a PNG waveform image of a sample from the 2 second mark until the 4 second mark of the bumblebee.mp3 audio file uploaded to Cloudinary's demo account, scaled to a height of 250 pixels and a width of 400 pixels, with the waveform rendered in blue on a green background:

Ruby:
cl_image_tag("bumblebee.png", :height=>250, :width=>400, :flags=>"waveform", :start_offset=>"2", :end_offset=>"4", :color=>"blue", :background=>"#02b30a", :resource_type=>"video")
PHP:
cl_image_tag("bumblebee.png", array("height"=>250, "width"=>400, "flags"=>"waveform", "start_offset"=>"2", "end_offset"=>"4", "color"=>"blue", "background"=>"#02b30a", "resource_type"=>"video"))
Python:
CloudinaryVideo("bumblebee.png").image(height=250, width=400, flags="waveform", start_offset="2", end_offset="4", color="blue", background="#02b30a")
Node.js:
cloudinary.image("bumblebee.png", {height: 250, width: 400, flags: "waveform", start_offset: "2", end_offset: "4", color: "blue", background: "#02b30a", resource_type: "video"})
Java:
cloudinary.url().transformation(new Transformation().height(250).width(400).flags("waveform").startOffset("2").endOffset("4").color("blue").background("#02b30a")).resourceType("video").imageTag("bumblebee.png")
JS:
cl.videoTag('bumblebee.png', {height: 250, width: 400, flags: "waveform", start_offset: "2", end_offset: "4", color: "blue", background: "#02b30a"}).toHtml();
jQuery:
$.cloudinary.image("bumblebee.png", {height: 250, width: 400, flags: "waveform", start_offset: "2", end_offset: "4", color: "blue", background: "#02b30a", resource_type: "video"})
React:
<Video publicId="bumblebee.png" resource_type="video">
  <Transformation height="250" width="400" flags="waveform" start_offset="2" end_offset="4" color="blue" background="#02b30a" />
</Video>
Angular:
<cl-video public-id="bumblebee.png" resource_type="video">
  <cl-transformation height="250" width="400" flags="waveform" start_offset="2" end_offset="4" color="blue" background="#02b30a">
  </cl-transformation>
</cl-video>
.Net:
cloudinary.Api.UrlVideoUp.Transform(new Transformation().Height(250).Width(400).Flags("waveform").StartOffset("2").EndOffset("4").Color("blue").Background("#02b30a")).BuildImageTag("bumblebee.png")
Waveform of a partial audio cut with color customization

Visualization of uploaded audio files made simple

Waveform images are a nice way to visualize audio files, and are useful for user generated content, social networks and social messaging apps. With Cloudinary you can easily generate images of the waveforms of audio files, with the images generated on-the-fly using dynamic delivery URLs and delivered optimized via a fast CDN. The generated image thumbnails for audio, as well as image and video files, can be further manipulated to match any graphic design and any responsive layout, just like any other image uploaded to Cloudinary.

Full audio support including upload, manipulation, streaming and waveform generation is available in all Cloudinary's plans, including the free tier. Try it yourself by opening a free account.

Recent Blog Posts

Build the Back-End For Your Own Instagram-style App with Cloudinary

Github Repo

Managing media files (processing, storage and manipulation) is one of the biggest challenges we encounter as practical developers. These challenges include:

A great service called Cloudinary can help us overcome many of these challenges. Together with Cloudinary, let's work on solutions to these challenges and hopefully have a simpler mental model towards media management.

Read more

Build A Miniflix in 10 Minutes

By Prosper Otemuyiwa
Build A Miniflix in 10 Minutes

Developers are constantly faced with challenges of building complex products every single day. And there are constraints on the time needed to build out the features of these products.

Engineering and Product managers want to beat deadlines for projects daily. CEOs want to roll out new products as fast as possible. Entrepreneurs need their MVPs like yesterday. With this in mind, what should developers do?

Read more

Your Web Image is Unnecessarily Bloated

By Christian Nwamba
Your Web Image is Unnecessarily Bloated

As a developer, it seems inefficient to serve a 2000kb JPEG image when we could compress images to optimize the performance without degrading the visual quality.

We are not new to this kind of responsibility. But our productivity will end up being questioned if we do not deliver fast. In order to do so, the community has devised several patterns to help improve productivity. Let's review few of these patterns based on their categories:

Read more

Google For Nigeria: We saw it all…

By Christian Nwamba
Google For Nigeria: We saw it all…

Note from Cloudinary: Christian Nwamba, a frequent Cloudinary contributor, recently attended, and was a main speaker, at the Google Developer Group (GDG) Conference in Lagos, Nigeria. Christian led a session teaching more than 500 developers how to “Build Offline Apps for the Next Billion Users.” The stack he used included JS (Vue), Firebase, Service Workers and Cloudinary. Below is his account of the conference and his talk.

Read more
Viral Images: Securing Images and Video uploads to your systems

When was the last time you got paid $40,000 for a few days of work? That is what happened last year to Russian independent security researcher Andrey Leonov, who discovered that if you upload a specially constructed image file to Facebook, you can make Facebook's internal servers, nested deep within their firewalls, run arbitrary commands to expose sensitive internal files in a way that could easily lead to a data breach.

Read more