Vollständige Wellenformbilder mit audiowaveform erzeugen

Tim Koschützki

Mitgründer · Berlin, Deutschland ·

Eine 800 Pixel breite Wellenform zeigt bei 100 Pixeln pro Sekunde nur die ersten acht Sekunden Audio. Für eine vollständige Übersicht erzeugen Sie Wellenformdaten und passen alle Datenpunkte in das Bild ein. Diese Anleitung erstellt ein PNG mit 800×200 Pixeln und getrennten Stereokanälen. Es enthält auch den Ton aus dem letzten, nur teilweise gefüllten Datenfenster der Aufnahme.

Die getesteten Werkzeuge installieren

Diese Befehle verwenden Bash unter Debian 13, amd64, mit audiowaveform 1.10.2 und dem Python-3-Paket von Debian. Sie benötigen cURL, CA-Zertifikate und die Berechtigung, Pakete mit sudo zu installieren. Der kleine Python-Renderer nutzt nur die Standardbibliothek.

Führen Sie diesen Installationsblock in einem Verzeichnis mit Schreibrechten aus. Er erstellt audiowaveform-install für den Paketdownload und belässt Ihre Shell im ursprünglichen Verzeichnis. Falls dieser Ordner bereits existiert, stoppt die Installation. Wählen Sie für einen erneuten Versuch einen neuen Ordnernamen. Das Paket mit festgelegter Version stammt aus dem offiziellen Release 1.10.2.

(
  mkdir audiowaveform-install &&
  cd audiowaveform-install &&
  curl -fsSLo audiowaveform.deb \
    https://github.com/bbc/audiowaveform/releases/download/1.10.2/audiowaveform_1.10.2-1-13_amd64.deb &&
  printf '%s\n' '4208706c6ae5ffb5761dddf8294eaf648c7ba9fb4d6fc6ec9f021d1bb109ea6e  audiowaveform.deb' | sha256sum --check - &&
  sudo apt-get update &&
  sudo apt-get install -y ./audiowaveform.deb python3 &&
  audiowaveform --version &&
  python3 --version
)

Als Ausgabe ist AudioWaveform v1.10.2 zu erwarten. Dieses Paket ist für Debian 13 auf amd64 vorgesehen; es handelt sich nicht um eine Installation über ein Ubuntu-PPA. Informationen zu anderen Systemen finden Sie in der Installationsanleitung des Projekts.

Wiederverwendbare Wellenformdaten erzeugen

Legen Sie eine WAV-Aufnahme namens input.wav in Ihr Arbeitsverzeichnis. Verwenden Sie dasselbe Verzeichnis für die übrigen Dateien und Befehle. Das Beispiel wurde mit WAV-Audio in 16-Bit-PCM und im Gleitkommaformat getestet. Das Werkzeug dokumentiert außerdem MP3, FLAC, Ogg Vorbis und Opus als Eingabeformate. Details zu Formaten und Abhängigkeiten finden Sie in den Optionen für Eingabeformate.

audiowaveform -i input.wav -o waveform.json --zoom 256 --bits 16 --split-channels

Jeder Punkt in waveform.json speichert die minimalen und maximalen Amplituden für eine Gruppe von 256 Samples pro Kanal. Die letzte Gruppe kann kürzer sein. --bits 16 steuert die Genauigkeit dieser gespeicherten Amplituden, und --split-channels erhält die getrennten Kanäle, statt sie zusammenzuführen. Bei einer Monoaufnahme gibt es nur einen Kanal.

Das JSON-Format speichert Zeichnungsdaten, kein abspielbares Audio. Behalten Sie input.wav, wenn Sie die Aufnahme abspielen oder später detailliertere Daten erzeugen möchten. Diese Befehle ersetzen vorhandene JSON- und PNG-Dateien mit denselben Ausgabenamen ohne Rückfrage. Verwenden Sie separate Namen für Ausgaben, die Sie behalten möchten, und führen Sie die Befehle nacheinander aus.

Jeden Datenpunkt in das PNG einpassen

Speichern Sie dies als render-waveform.py neben waveform.json:

import json
import subprocess
from pathlib import Path

waveform = json.loads(Path("waveform.json").read_text(encoding="utf-8"))
width = 800
height = 200
points_per_pixel = max(1, (waveform["length"] + width - 1) // width)
zoom = waveform["samples_per_pixel"] * points_per_pixel

subprocess.run(
    [
        "audiowaveform", "-i", "waveform.json", "-o", "waveform.png",
        "--zoom", str(zoom), "--width", str(width), "--height", str(height),
        "--no-axis-labels",
        "--background-color", "ffffff",
        "--waveform-color", "1a73e8,dc2626",
    ],
    check=True,
)

Rendern Sie anschließend das Bild:

python3 render-waveform.py

Öffnen Sie waveform.png. Eine Stereoaufnahme hat zwei übereinanderliegende Bänder in Blau und Rot innerhalb des insgesamt 800×200 Pixel großen Bildes. Eine Monoaufnahme hat ein blaues Band. --no-axis-labels entfernt die Beschriftungen und den Rahmen.

Die Berechnung rundet die Anzahl zwischengespeicherter Datenpunkte pro Pixel auf eine ganze Zahl auf. Beispielsweise benötigen 2.344 Punkte drei Punkte pro Pixel, um in 800 Pixel zu passen. Multipliziert mit den 256 Samples pro Punkt im Cache ergibt das --zoom 768. So wird auch die letzte, möglicherweise unvollständige Gruppe erfasst. Dabei kann ein Teil der Breite ungenutzt bleiben. Bei einer Aufnahme mit weniger als 800 zwischengespeicherten Punkten bleibt mehr Breite ungenutzt. Erzeugen Sie die JSON-Datei mit einem kleineren Wert für --zoom, mindestens zwei, wenn Sie mehr Details benötigen.

Warum den Maßstab berechnen? In Version 1.10.2 kürzt die automatische Anpassung die Dauer auf ganze Sekunden, wenn sie zwischengespeicherte Daten verwendet. Die Berechnung des Maßstabs aus der Zeit rundet außerdem die Samples pro Pixel ab. Daher kann --zoom auto das äußerste Ende auslassen, selbst beim Rendern direkt aus Audio. Das Zählen und Gruppieren der zwischengespeicherten Punkte vermeidet beide Rundungsprobleme.

Zeitintervall und Darstellung wählen

Für eine gezielte Detailansicht rendern Sie aus dem Originalaudio mit einem festen Zeitmaßstab. Dieser Befehl zeigt die ersten acht Sekunden von input.wav bei gängigen Abtastraten wie 44.100 oder 48.000 Hz:

audiowaveform -i input.wav -o waveform-first-8s.png \
  --start 0 --pixels-per-second 100 --width 800 --height 200 \
  --split-channels --no-axis-labels \
  --background-color ffffff --waveform-color 1a73e8,dc2626

Audio nach diesem Intervall liegt außerhalb des Bildes. Bei anderen Abtastraten ist das Intervall nur näherungsweise genau, da audiowaveform eine ganzzahlige Anzahl von Samples pro Pixel verwendet. Eine flache Wellenform in der Detailansicht beweist nicht, dass die gesamte Aufnahme stumm ist: Vergleichen Sie sie mit der vollständigen Übersicht.

Passen Sie im Python-Renderer width und height an den verfügbaren Platz in Ihrer Anwendung an. Die Zoomberechnung richtet sich nach der Breite. Farben sind hexadezimale RGB-Werte ohne #; die durch Kommas getrennten Wellenformfarben entsprechen den Kanälen. Nur wenn Sie --split-channels beim Erzeugen der JSON-Datei beibehalten, bleiben diese Kanäle für das spätere Rendern erhalten. Die Bildoptionen beschreiben die Einstellungen für Farbe und Amplitude.

Unerwartete Ergebnisse prüfen

Fehlende oder unlesbare Eingabe: Prüfen Sie Dateinamen und Format. Erzeugen Sie die JSON-Datei erst erneut, nachdem Sie die Eingabe korrigiert haben. Wenn die Erzeugung fehlschlägt, kann eine ältere JSON-Datei bestehen bleiben.
Ein altes Bild nach einem fehlgeschlagenen Durchlauf: Prüfen Sie den Exit-Status und die Diagnosemeldung des Befehls. Der Python-Renderer meldet einen fehlgeschlagenen audiowaveform-Aufruf mit check=True. Ein vorhandenes PNG beweist nicht, dass das letzte Rendern erfolgreich war.
Fehlermeldung wegen ungültigem Zoom: Eine zwischengespeicherte Wellenform kann nicht mehr Details liefern, als sie enthält. Erzeugen Sie neue Daten aus dem Audio mit einem kleineren Wert für Samples pro Punkt. Die obige Berechnung für die vollständige Übersicht fordert nie einen feineren Maßstab an, als der Eingabecache bietet.
Ein fehlendes Ende: Verwenden Sie den berechneten Übersichtsmaßstab. Eine größere Bildhöhe oder Amplitude erweitert das Zeitintervall nicht.

Die Wellenform in einer Anwendung verwenden

Verwenden Sie das PNG als statische Vorschau neben einem Audioplayer, mit einem Alternativtext, der zur Aussage des Bildes passt. Behalten Sie die JSON-Datei, wenn Sie dieselbe Aufnahme mit anderen Farben oder Abmessungen neu zeichnen möchten, ohne das Audio erneut zu decodieren. Die Steuerelemente zur Wiedergabe und zum Springen auf der Zeitleiste gehören zum Audioplayer Ihrer Anwendung; das PNG selbst ist ein statisches Bild.