Générer des images de forme d’onde complètes avec audiowaveform

Tim Koschützki

Cofondateur · Berlin, Allemagne · Afficher la bio

Une forme d’onde de 800 pixels à 100 pixels par seconde ne montre que les huit premières secondes de l’audio. Pour une vue d’ensemble complète, générez des données de forme d’onde et faites tenir tous leurs points dans l’image. Ce guide produit un PNG de 800×200 avec des canaux stéréo séparés, en incluant le son de la dernière fenêtre de données partielle de l’enregistrement.

Installer les outils testés

Ces commandes utilisent Bash sur Debian 13, amd64, avec audiowaveform 1.10.2 et le paquet Python 3 de Debian. Vous avez besoin de cURL, de certificats CA et de l’autorisation d’installer des paquets avec sudo. Le petit moteur de rendu Python n’utilise que la bibliothèque standard.

Exécutez ce bloc d’installation dans un répertoire accessible en écriture. Il crée audiowaveform-install pour le téléchargement du paquet et laisse votre shell dans son répertoire d’origine. Si ce dossier existe déjà, l’installation s’arrête ; choisissez un nouveau nom de dossier pour la relancer. Le paquet épinglé provient de la version officielle 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
)

Vous devriez obtenir AudioWaveform v1.10.2. Ce paquet cible Debian 13 sur amd64 ; il ne s’agit pas d’une installation via un PPA Ubuntu. Consultez le guide d’installation⁠ du projet pour les autres systèmes.

Générer des données de forme d’onde réutilisables

Placez un enregistrement WAV nommé input.wav dans votre répertoire de travail. Utilisez ce même répertoire pour les fichiers et commandes restants. L’exemple a été testé avec de l’audio WAV PCM 16 bits et à virgule flottante. L’outil documente aussi les entrées MP3, FLAC, Ogg Vorbis et Opus ; consultez ses options de format d’entrée⁠ pour les détails sur les formats et les dépendances.

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

Chaque point de waveform.json stocke les amplitudes minimale et maximale d’un groupe de 256 échantillons par canal. Le dernier groupe peut être plus court. --bits 16 contrôle la précision de ces amplitudes stockées, et --split-channels conserve des canaux séparés au lieu de les combiner. Pour un enregistrement mono, il n’y a qu’un seul canal.

Le format JSON⁠ stocke des données de dessin, pas de l’audio lisible. Conservez input.wav si vous voulez lire l’enregistrement ou générer plus tard des données plus détaillées. Ces commandes remplacent sans confirmation les fichiers JSON et PNG existants portant les mêmes noms de sortie. Utilisez des noms distincts pour les sorties que vous voulez conserver, et exécutez les commandes l’une après l’autre.

Faire tenir chaque point de données dans le PNG

Enregistrez ceci sous render-waveform.py à côté de 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,
)

Générez ensuite le rendu de l’image :

python3 render-waveform.py

Ouvrez waveform.png. Un enregistrement stéréo comporte deux bandes superposées, bleue et rouge, dans l’image totale de 800×200. Un enregistrement mono comporte une seule bande bleue. --no-axis-labels supprime les libellés et la bordure.

Le calcul arrondit à l’entier supérieur le nombre de points de données en cache par pixel. Par exemple, 2 344 points nécessitent trois points par pixel pour tenir dans 800 pixels. En multipliant par les 256 échantillons par point du cache, on obtient --zoom 768. Ce résultat inclut le dernier groupe, éventuellement incomplet, et peut laisser de la largeur inutilisée. Un enregistrement de moins de 800 points en cache laisse davantage de largeur inutilisée ; générez son JSON avec un --zoom plus petit, d’au moins deux, si vous avez besoin de plus de détails.

Pourquoi calculer l’échelle ? Dans la version 1.10.2, l’ajustement automatique à partir des données en cache tronque la durée à des secondes entières⁠. Le calcul de conversion de la durée en échelle⁠ arrondit aussi à l’inférieur le nombre d’échantillons par pixel. Par conséquent, --zoom auto peut omettre la toute fin, même lors d’un rendu direct à partir de l’audio. Compter et regrouper les points en cache évite ces deux problèmes d’arrondi.

Choisir l’intervalle et l’apparence

Pour un gros plan délibéré, générez le rendu à partir de l’audio d’origine avec une échelle de temps fixe. Cette commande montre les huit premières secondes de input.wav aux fréquences d’échantillonnage courantes, comme 44 100 ou 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

L’audio situé après cet intervalle se trouve hors de l’image. Pour d’autres fréquences d’échantillonnage, l’intervalle est approximatif, car audiowaveform utilise un nombre entier d’échantillons par pixel. Un gros plan plat ne prouve pas que tout l’enregistrement est silencieux : comparez-le avec la vue d’ensemble complète.

Dans le moteur de rendu Python, modifiez width et height selon l’espace disponible dans votre application. Le calcul du zoom suit la largeur. Les couleurs sont des valeurs RGB hexadécimales sans # ; les couleurs de forme d’onde séparées par des virgules correspondent aux canaux. C’est le fait de conserver --split-channels lors de la génération du JSON qui préserve ces canaux pour un rendu ultérieur. Les options d’image⁠ décrivent les réglages de couleur et d’amplitude.

Vérifier les résultats inattendus

• Entrée manquante ou illisible : vérifiez le nom et le format du fichier, et ne régénérez le JSON qu’après avoir corrigé l’entrée. Une génération échouée peut laisser en place un ancien fichier JSON.
• Une ancienne image après une exécution échouée : vérifiez le code de sortie et le diagnostic de la commande. Le moteur de rendu Python signale un appel d’audiowaveform échoué via check=True ; un PNG existant ne prouve pas que le dernier rendu a réussi.
• Une erreur de zoom invalide : une forme d’onde en cache ne peut pas fournir plus de détails qu’elle n’en contient. Générez de nouvelles données à partir de l’audio avec une valeur d’échantillons par point plus petite. Le calcul de vue d’ensemble complète ci-dessus ne demande jamais une échelle plus fine que son cache d’entrée.
• Une fin manquante : utilisez l’échelle de vue d’ensemble calculée. Augmenter la hauteur de l’image ou l’amplitude n’élargit pas l’intervalle de temps.

Utiliser la forme d’onde dans une application

Utilisez le PNG comme aperçu statique à côté d’un lecteur audio, avec un texte alternatif adapté à ce que l’image communique. Conservez le JSON si vous voulez redessiner le même enregistrement avec d’autres couleurs ou dimensions sans décoder à nouveau l’audio. Les commandes de lecture et de navigation dans la piste audio relèvent du lecteur audio de votre application ; le PNG lui-même est une image statique.