Generate a waveform image with FFmpeg

ffmpeg -i input.mp3 -filter_complex "showwavespic=s=1280x240:colors=#21B4CE" -frames:v 1 waveform.png

Reads the audio, draws its amplitude over time into a 1280x240 image and writes one PNG. The background is transparent (the output pixel format is rgba), so the waveform can sit on any page.

Flags, explained

showwavespic=s=1280x240

Output size. Each column summarises the samples that fall into it, so width sets the time resolution.

colors=#21B4CE

Trace colour, hex or named. Several values separated by | are used per channel.

split_channels=1

Draw each channel in its own band instead of overlapping them.

scale=sqrt

Amplitude scale: lin (default), log, sqrt or cbrt. Non-linear scales make quiet audio visible.

draw=full:filter=peak

Fill the shape and use peak values per column rather than averages.

-frames:v 1

Write a single image. showwavespic emits one frame anyway; the flag makes the intent explicit.

-filter_complex

Required because the filter turns audio into video; -af cannot change the media type.

Variants

ffmpeg -i input.mp3 -filter_complex "showwavespic=s=1280x240:colors=#21B4CE|#E0489B:split_channels=1" -frames:v 1 waveform.png

ffmpeg -i input.mp3 -filter_complex "color=c=#17181C:s=1280x240[bg];[0:a]showwavespic=s=1280x240:colors=#F2C93B[w];[bg][w]overlay=format=auto,format=rgb24" -frames:v 1 waveform.png

ffmpeg -i input.mp4 -filter_complex "[0:a]aformat=channel_layouts=mono,showwavespic=s=1280x240:colors=white:scale=sqrt" -frames:v 1 waveform.png

ffmpeg -i input.mp3 -filter_complex "showwavespic=s=1280x240:colors=#21B4CE:draw=full:filter=peak" -frames:v 1 waveform.png

ffmpeg -i input.mp3 -filter_complex "showspectrumpic=s=1280x480:legend=0" -frames:v 1 spectrogram.png

Pitfalls we hit

• The default background is transparent (rgba). Some viewers render that as black, and JPEG cannot store it: overlay on a colour and convert to rgb24 first.
• Steady tones draw as a flat band; the test tone at -16 dBFS filled a thin stripe. Real speech or music shows the envelope you expect.
• Linear scale hides quiet material. Podcasts normalised to -16 LUFS look small at scale=lin; use sqrt or log.
• Very long files are downsampled to the image width: a 2 h recording in 1280 columns averages about 5.6 s per pixel. Increase the width or trim the input.
• -af showwavespic fails because the filter outputs video; use -filter_complex or -lavfi.

The same edit as a typed operation

generate_audio_waveform takes a width, a height and a colour, accepts audio or video input, and returns a transparent PNG through a signed URL. No filter graph to assemble and no pixel format to remember.

{
  "inputs": [{ "id": "main", "url": "https://example.com/podcast.mp3" }],
  "options": { "width": 1280, "height": 240, "color": "#C4FF4C" }
}

FAQ