Gere imagens de forma de onda completas com o audiowaveform

Tim Koschützki

Cofundador · Berlim, Alemanha ·

Uma forma de onda de 800 pixels a 100 pixels por segundo mostra apenas os primeiros oito segundos de áudio. Para ter uma visão geral completa, gere os dados da forma de onda e encaixe todos os pontos na imagem. Este passo a passo produz um PNG de 800×200 com canais estéreo separados, incluindo o som da janela de dados parcial final da gravação.

Instale as ferramentas testadas

Estes comandos usam Bash no Debian 13, amd64, com o audiowaveform 1.10.2 e o pacote Python 3 do Debian. Você precisa de cURL, certificados de CA e permissão para instalar pacotes com sudo. O pequeno renderizador em Python usa apenas a biblioteca padrão.

Execute este bloco de instalação em um diretório com permissão de escrita. Ele cria audiowaveform-install para o download do pacote e deixa seu shell no diretório original. Se essa pasta já existir, a instalação é interrompida; escolha um novo nome de pasta para repeti-la. O pacote fixado vem da versão 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
)

Você deve ver AudioWaveform v1.10.2. Este pacote é destinado ao Debian 13 em amd64; não se trata de uma instalação via PPA do Ubuntu. Consulte o guia de instalação do projeto para outros sistemas.

Gere dados de forma de onda reutilizáveis

Coloque uma gravação WAV chamada input.wav no seu diretório de trabalho. Use esse mesmo diretório para os demais arquivos e comandos. O exemplo foi testado com áudio WAV PCM de 16 bits e de ponto flutuante. A ferramenta também documenta entradas MP3, FLAC, Ogg Vorbis e Opus; consulte as opções de formato de entrada para detalhes sobre formatos e dependências.

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

Cada ponto em waveform.json armazena as amplitudes mínima e máxima de um grupo de 256 amostras por canal. O último grupo pode ser menor. --bits 16 controla a precisão dessas amplitudes armazenadas, e --split-channels mantém os canais separados em vez de combiná-los. Em uma gravação mono, há apenas um canal.

O formato JSON armazena dados de desenho, não áudio reproduzível. Guarde input.wav se quiser reproduzir a gravação ou gerar dados mais detalhados depois. Estes comandos substituem, sem pedir confirmação, arquivos JSON e PNG existentes com os mesmos nomes de saída. Use nomes diferentes para as saídas que quiser manter e execute os comandos em sequência.

Encaixe todos os pontos de dados no PNG

Salve isto como render-waveform.py ao lado 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,
)

Em seguida, renderize a imagem:

python3 render-waveform.py

Abra waveform.png. Uma gravação estéreo tem duas bandas empilhadas, azul e vermelha, dentro da imagem total de 800×200. Uma gravação mono tem uma banda azul. --no-axis-labels remove os rótulos e a borda.

O cálculo arredonda para cima até um número inteiro de pontos de dados em cache por pixel. Por exemplo, 2.344 pontos precisam de três pontos por pixel para caber em 800 pixels. Multiplicar pelas 256 amostras por ponto do cache resulta em --zoom 768. Isso inclui o último grupo, possivelmente incompleto, e pode deixar largura sem uso. Uma gravação com menos de 800 pontos em cache deixa ainda mais largura sem uso; se precisar de mais detalhes, gere o JSON dela com um --zoom menor, de no mínimo dois.

Por que calcular a escala? Na versão 1.10.2, o ajuste automático a partir de dados em cache trunca a duração para segundos inteiros. O cálculo de tempo para escala também arredonda para baixo as amostras por pixel. Consequentemente, --zoom auto pode omitir o finalzinho da gravação mesmo ao renderizar diretamente a partir do áudio. Contar e agrupar os pontos em cache evita os dois problemas de arredondamento.

Escolha o intervalo e a aparência

Para um close-up proposital, renderize a partir do áudio original com uma escala de tempo fixa. Este comando mostra os primeiros oito segundos de input.wav em taxas de amostragem comuns, como 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

O áudio posterior a esse intervalo fica fora da imagem. Em outras taxas de amostragem, o intervalo é aproximado, porque o audiowaveform usa um número inteiro de amostras por pixel. Um close-up plano não prova que a gravação inteira está em silêncio: compare-o com a visão geral completa.

No renderizador em Python, altere width e height para se adequar ao espaço da sua aplicação. O cálculo do zoom acompanha a largura. As cores são valores RGB hexadecimais sem #; as cores da forma de onda, separadas por vírgula, correspondem aos canais. É manter --split-channels ao gerar o JSON que preserva esses canais para renderizações posteriores. As opções de imagem descrevem os controles de cor e amplitude.

Verifique resultados inesperados

Entrada ausente ou ilegível: confirme o nome e o formato do arquivo e gere o JSON novamente somente depois de corrigir a entrada. Uma geração com falha pode deixar um arquivo JSON antigo no lugar.
Uma imagem antiga após uma execução com falha: verifique o status de saída e o diagnóstico do comando. O renderizador em Python informa uma invocação do audiowaveform com falha por meio de check=True; um PNG existente não prova que a renderização mais recente foi bem-sucedida.
Um erro de zoom inválido: uma forma de onda em cache não pode fornecer mais detalhes do que contém. Gere novos dados a partir do áudio com um valor menor de amostras por ponto. O cálculo da visão geral completa acima nunca solicita uma escala mais fina que a do cache de entrada.
Um final ausente: use a escala de visão geral calculada. Aumentar a altura ou a amplitude da imagem não amplia o intervalo de tempo.

Use a forma de onda em uma aplicação

Use o PNG como uma prévia estática ao lado de um player de áudio, com um texto alternativo adequado ao que a imagem comunica. Guarde o JSON se quiser redesenhar a mesma gravação com cores ou dimensões diferentes sem decodificar o áudio novamente. Os controles de reprodução e de navegação na linha do tempo pertencem ao player de áudio da sua aplicação; o PNG em si é uma imagem estática.