---
title: "Waveform View"
manual: "Kitodo.Presentation"
version: "dev-demo"
source: "Features/MediaPlayer/Waveform.rst"
rendered: "2026-09-27T16:21:24+00:00"
---

# Waveform View {#waveform-view}

-   [Overview](#overview)
-   [METS](#mets)
-   [Integration](#integration)
-   [Frontend](#frontend)
-   [Backend](#backend)

## Overview {#overview}

The waveform component is based on a toolkit provided by BBC.
It can be used, for example, to set points and segments that can be processed or exported.

-   [peaks.js: JavaScript UI component for interacting with audio waveforms](https://github.com/bbc/peaks.js/)
-   [waveform-data.js: Audio Waveform Data Manipulation API – resample, offset and segment waveform data in JavaScript](https://github.com/bbc/waveform-data.js)
-   [audiowaveform: C++ program to generate waveform data](https://github.com/bbc/audiowaveform)

## METS {#mets}

For information on how to link preprocessed audio waveform data, see [the section on METS](METS.html#mets_waveform).

## Integration {#integration}

A custom `<dlf-waveform>` tag is exposed that can be used in the HTML template.

```html
<dlf-waveform
   id="tx-dlf-media-waveform"
   forPlayer="tx-dlf-media"
   src="https://www.example.com/waveform.dat"
   type="application/vnd.kitodo.audiowaveform"
></dlf-waveform>
```

Other attributes:

-   Use `hidden` to control whether or not the waveform is visible.

## Frontend {#frontend}

An instance of Peaks.js fulfills multiple functions:

-   Model for point and segment data
-   Controller and view to render waveform and points/segments into a given DOM element

An instance of BBC's `WaveformData` is used as a model of the waveform data and passed to Peaks.js for rendering.

We have the following class structure:

-   `Markers` is the model for a collection of points and segments.
    An instance of this is created in `DlfMediaPlayer`.
    Actions to add markers via keybindings also are registered in the player.
-   Custom components that serve as view of the player's markers:

    -   `WaveForm` renders a waveform by integrating and customizing Peaks.js.
        A major part also is to adapt Peaks to `Markers`.
        (We don't use the internal model of Peaks.js directly. This allows to set markers when Peaks is not, or not yet, initialized, e.g., if a waveform is not available or not shown yet.)
    -   `MarkerTable` lists all segments and allows to further interact with them, e.g. to edit labels or export the list.

## Backend {#audiowaveform}

To avoid loading the full audio file before waveform data can be displayed,
the audio is preprocessed using `audiowaveform`.

For installation or build instructions, see [https://github.com/bbc/audiowaveform](https://github.com/bbc/audiowaveform).

Sample call:

```shell
# 8 bit, 1024 samples/pixel
# (at 44800 Hz, this corresponds to a maximum resolution of 43.75 pixels/second)
audiowaveform -i input.mp3 -o output.dat -b 8 -z 1024
```