On this page

Generating Waveform Data

Introduction

The Waveform output generates audio peak data (per-segment min/max values) for the audio track of your source media, returned as JSON compatible with BBC audiowaveform, peaks.js, and the waveform-data format. Use it to render a waveform visualization in players, audio editors, or podcast/video timelines without having to download and process the full audio track on the client.

Please note

Waveform output is currently only available for Encoder Version 2

Start a Task with the "waveform" Output

Waveform outputs can be created by adding a 'waveform' output format to your transcoding job. Use the /v1/start_encode2 method to launch a transcoding job with the output parameter set to waveform.

Request Example

{
  "query": {
    "encoder_version": 2,
    "source": "YOUR_VIDEO_URL",
    "format": [
      {
        "output": "waveform",
        "waveform_bits": 8,
        "destination": [
          {
            "url": "YOUR_STORAGE_URL",
            "key": "YOUR_KEY",
            "secret": "YOUR_SECRET",
            "permissions": "public-read"
          }
        ]
      }
    ]
  }
}

Output Settings

Parameter	Type	Requirement	Description
output	string	Required	Must be set to "waveform".
waveform_bits	integer	Optional	Peak resolution: 8 or 16. Defaults to 8.
destination	object / array	Required	Where to store the resulting JSON file.

Please note

Higher resolution (waveform_bits: 16) produces more precise peak values, at the cost of a larger output file. 8 bits is usually enough for typical waveform rendering in a player UI.

Access the Waveform Data

Once the task completes, you'll get a single JSON file describing the waveform in the waveform-data v2 format.

Output JSON structure:

{
  "version": 2,
  "channels": 1,
  "sample_rate": 44100,
  "samples_per_pixel": 256,
  "bits": 8,
  "length": 36295,
  "data": [-1, 2, -3, 4, "..."]
}

Field	Description
version	Format version (2).
channels	Channel count. Audio is downmixed to mono, so this is always 1.
sample_rate	PCM sample rate, in Hz.
samples_per_pixel	Number of audio samples represented by one (min, max) pair.
bits	Value resolution: 8 or 16.
length	Number of (min, max) pairs in data.
data	Flat array of (min, max) pairs in sequence. Its length is always length * 2.

The value range of each entry in data depends on bits:

bits: 8 → values from -128 to 127 bits: 16 → values from -32768 to 32767

Need More Help?

For additional information, tutorials, or support, visit the Qencode Documentation page Link or contact Qencode Support at support@qencode.com.