Genera imágenes completas de forma de onda con audiowaveform

Tim Koschützki

Cofundador · Berlín, Alemania ·

Una forma de onda de 800 píxeles a 100 píxeles por segundo muestra solo los primeros ocho segundos de audio. Para obtener una vista completa, genera los datos de la forma de onda y ajusta todos sus puntos a la imagen. Este tutorial produce un PNG de 800×200 con canales estéreo separados que incluye el sonido de la ventana parcial de datos al final de la grabación.

Instala las herramientas probadas

Estos comandos usan Bash en Debian 13, amd64, con audiowaveform 1.10.2 y el paquete Python 3 de Debian. Necesitas cURL, certificados de CA y permiso para instalar paquetes con sudo. El pequeño programa de renderizado en Python usa solo la biblioteca estándar.

Ejecuta este bloque de instalación en un directorio con permiso de escritura. Crea audiowaveform-install para descargar el paquete y deja la shell en su directorio original. Si esa carpeta ya existe, la instalación se detiene; elige otro nombre de carpeta para repetirla. El paquete de versión fija proviene de la versión oficial 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
)

El resultado esperado es AudioWaveform v1.10.2. Este paquete está destinado a Debian 13 en amd64; no es una instalación mediante un PPA de Ubuntu. Consulta la guía de instalación del proyecto para otros sistemas.

Genera datos reutilizables de la forma de onda

Coloca una grabación WAV llamada input.wav en tu directorio de trabajo. Usa ese mismo directorio para los archivos y comandos restantes. El ejemplo se probó con audio WAV PCM de 16 bits y de punto flotante. La herramienta también documenta entradas MP3, FLAC, Ogg Vorbis y Opus; consulta sus opciones de formato de entrada para obtener detalles sobre los formatos y las dependencias.

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

Cada punto de waveform.json almacena las amplitudes mínima y máxima de un grupo de 256 muestras por canal. El último grupo puede ser más corto. --bits 16 controla la precisión de estas amplitudes almacenadas, y --split-channels mantiene los canales separados en lugar de combinarlos. En una grabación mono, hay un solo canal.

El formato JSON almacena datos de dibujo, no audio reproducible. Conserva input.wav si quieres reproducir la grabación o generar datos más detallados después. Estos comandos reemplazan los archivos JSON y PNG existentes que tengan los mismos nombres de salida sin pedir confirmación. Usa nombres distintos para los resultados que quieras conservar y ejecuta los comandos de forma secuencial.

Ajusta todos los puntos de datos al PNG

Guarda lo siguiente como render-waveform.py junto a 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,
)

Luego renderiza la imagen:

python3 render-waveform.py

Abre waveform.png. Una grabación estéreo tiene dos bandas apiladas, azul y roja, dentro de la imagen total de 800×200. Una grabación mono tiene una banda azul. --no-axis-labels elimina las etiquetas y el borde.

El cálculo redondea hacia arriba a un número entero de puntos de datos en caché por píxel. Por ejemplo, 2.344 puntos necesitan tres puntos por píxel para caber en 800 píxeles. Al multiplicar por las 256 muestras por punto de la caché, se obtiene --zoom 768. Esto incluye el último grupo, que puede estar incompleto, y puede dejar parte del ancho sin usar. Una grabación con menos de 800 puntos en caché deja más ancho sin usar; genera su JSON con un valor menor de --zoom, de al menos dos, si necesitas más detalle.

¿Por qué calcular la escala? En la versión 1.10.2, el ajuste automático a partir de datos en caché trunca su duración a segundos enteros. El cálculo de tiempo a escala también redondea hacia abajo las muestras por píxel. Por lo tanto, --zoom auto puede omitir el tramo final incluso al renderizar directamente desde el audio. Contar y agrupar los puntos en caché evita ambos problemas de redondeo.

Elige el intervalo y la apariencia

Para ampliar una sección concreta, renderiza desde el audio original con una escala de tiempo fija. Este comando muestra los primeros ocho segundos de input.wav con frecuencias de muestreo comunes, como 44.100 o 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

El audio posterior a ese intervalo queda fuera de la imagen. Para otras frecuencias de muestreo, el intervalo es aproximado porque audiowaveform usa un número entero de muestras por píxel. Una vista ampliada plana no demuestra que toda la grabación sea silenciosa: compárala con la vista completa.

En el programa de renderizado en Python, cambia width y height para adaptarlos al espacio de tu aplicación. El cálculo del zoom se ajusta al ancho. Los colores son valores RGB hexadecimales sin #; los colores de la forma de onda, separados por comas, corresponden a los canales. Mantener --split-channels al generar el JSON es lo que conserva esos canales para renderizarlos más adelante. Las opciones de imagen describen los controles de color y amplitud.

Revisa los resultados inesperados

Entrada ausente o ilegible: confirma el nombre del archivo y el formato, y vuelve a generar el JSON solo después de corregir la entrada. Si la generación falla, puede quedar un archivo JSON anterior.
Una imagen antigua después de una ejecución fallida: revisa el estado de salida del comando y su diagnóstico. El programa de renderizado en Python informa de una invocación fallida de audiowaveform mediante check=True; un PNG existente no demuestra que el último renderizado haya tenido éxito.
Un error de zoom no válido: una forma de onda en caché no puede proporcionar más detalle del que contiene. Genera nuevos datos a partir del audio con un valor menor de muestras por punto. El cálculo de la vista completa anterior nunca solicita una escala más detallada que la de su caché de entrada.
Un tramo final ausente: usa la escala calculada para la vista completa. Aumentar la altura de la imagen o la amplitud no amplía el intervalo de tiempo.

Usa la forma de onda en una aplicación

Usa el PNG como vista previa estática junto a un reproductor de audio, con un texto alternativo adecuado para lo que comunica la imagen. Conserva el JSON si quieres volver a dibujar la misma grabación con colores o dimensiones diferentes sin decodificar el audio de nuevo. Los controles de reproducción y desplazamiento por el audio corresponden al reproductor de tu aplicación; el PNG en sí es una imagen estática.