p5.sound.js per l'audio visualizzazione con p5.js 2

Questa guida è stata scritta da Claude Opus 5.5, un modello di IA, e non è ancora stata verificata nel dettaglio. Il codice è stato provato solo in Chrome, su Windows.

Con p5.js 2 l’audio si gestisce con la nuova versione della libreria p5.sound.js, riscritta sulla base di Tone.js: la versione precedente, la 1.0, non si carica con p5.js 2. Questa pagina raccoglie quello che serve per l’audio visualizzazione: l’inclusione della libreria, lo sketch di base, le differenze rispetto alla versione precedente e il modo di ottenere le funzioni che non ci sono più, come getEnergy() e addCue().

Il codice è stato provato con p5.js 2.3.3 e p5.sound.js 0.4.1. Quasi tutti gli esempi che si trovano online riguardano la versione precedente, e gli agenti di programmazione tendono a scrivere codice per quella, con metodi che non esistono più o che ora si comportano in modo diverso, spesso senza nessun messaggio di errore: quando le due versioni non coincidono valgono le indicazioni di questa pagina, che conviene indicare anche all’agente.

Per le slide e gli sketch con p5.js 1 resta la guida precedente, P5.sound.js per l’audio visualizzazione.

1. Inclusione della libreria

Nell’index.html dello sketch la libreria si carica subito dopo p5.js:

  <script src="https://cdn.jsdelivr.net/npm/p5@2.3.3/lib/p5.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/p5.sound@0.4.1/dist/p5.sound.min.js"></script>
<script src="sketch.js"></script>

Il file audio (MP3, oppure WAV o OGG) va nella cartella dello sketch, e lo sketch va aperto con Live Server: aperto direttamente come file, loadSound() non termina mai e la tela non compare, senza nessun messaggio di errore.

2. Lo sketch di base

Carica un brano, lo collega all’analisi e lo avvia o lo ferma a ogni clic, disegnando la forma d’onda del frammento in esecuzione.

    let brano;      // il file audio
let fft;        // analisi delle frequenze e dei campioni

async function setup() {
  createCanvas( 670, 200 );
  textSize( 16 );
  brano = await loadSound( 'liszt.mp3' );
  fft = new p5.FFT( 256 );   // bande: potenza di 2 fra 16 e 1024
  brano.connect( fft );      // senza connect() l'analisi resta a zero
  brano.loop();              // ripete, ma non avvia il brano
}

function draw() {
  background( 255 );
  if (!brano.isPlaying()) {
    text( 'clic per avviare il brano', 20, 30 );
  }
  let campioni = fft.waveform();   // 1024 valori fra -1 e 1
  noFill();
  beginShape();
  for (let i = 0; i < campioni.length; i++) {
    let x = map( i, 0, campioni.length, 0, width );
    let y = map( campioni[i], -1, 1, height, 0 );
    vertex( x, y );
  }
  endShape();
}

function mousePressed() {
  userStartAudio();          // sblocca l'audio, fermo fino a un clic
  if (brano.isPlaying()) {
    brano.stop();
  } else {
    brano.play();
  }
}
  

  brano = await loadSound( 'liszt.mp3' );

Carica il file audio. Con p5.js 2 loadSound() si usa con await dentro async function setup(), al posto di preload().

  fft = new p5.FFT( 256 );
brano.connect( fft );

Creano l’oggetto che analizza l’audio e gli collegano il brano: senza connect() l’analisi restituisce solo zeri. Il numero di bande dello spettro si stabilisce qui, con una potenza di 2 fra 16 e 1024 (32 se non indicato).

  brano.loop();

Attiva la ripetizione, ma non avvia il brano: lo avvia play().

  userStartAudio();

Riattiva l’audio, che il browser tiene sospeso finché l’utente non compie un’azione: un brano avviato in setup() resta muto. Per questo play() sta in mousePressed(), o in keyPressed().

  let campioni = fft.waveform();

Restituisce i 1024 campioni del frammento in esecuzione, con valori fra -1 e 1. Il numero è fisso: un parametro fra le parentesi viene ignorato.

3. Che cosa è cambiato

Altri comportamenti della versione 0.4.1, verificati, che la documentazione non segnala:

• un secondo play() durante la riproduzione fa ricominciare il brano dall’inizio;
• dopo una pause() il brano riprende con play(), ma stop() seguito da play() non lo fa più ripartire, anche se isPlaying() restituisce true: per fermare e ricominciare conviene usare solo stop() e play();
• isPlaying() resta true anche quando un brano senza ripetizione arriva alla fine, che si intercetta invece con onended();
• p5.AudioIn manda il suono del microfono anche agli altoparlanti (capitolo 10).

4. Classi e metodi

p5.SoundFile

Il brano caricato con loadSound() (reference della classe):

• play() e stop(): avviano e fermano il brano, che dopo stop() riparte dall’inizio;
• loop(): attiva la ripetizione, e loop( false ) la disattiva;
• pause(): ferma la riproduzione nel punto raggiunto (vedi il capitolo 3);
• isPlaying() e isLooping(): dicono se il brano è in riproduzione e se si ripete;
• jump( secondi ): sposta la riproduzione al punto indicato, mentre il brano suona;
• rate( velocità ): cambia insieme la velocità e l’altezza del suono (1 è la velocità normale, 0.5 la metà);
• amp( volume ): volume, da 0 a 1;
• duration(), frames(), channels() e sampleRate(): durata in secondi, numero dei campioni, numero dei canali e campioni al secondo;
• onended( funzione ): funzione chiamata quando il brano finisce o viene fermato;
• connect( analisi ): collega il brano a un’analisi, come p5.FFT o p5.Amplitude, che altrimenti restituisce solo zeri; il brano continua a uscire dagli altoparlanti;
• disconnect(): stacca il brano da tutti i collegamenti, altoparlanti compresi.

amp(), connect() e disconnect() valgono per quasi tutte le classi della libreria, che li ereditano dalla classe p5soundNode: nella reference stanno nella sua pagina, non in quella di p5.SoundFile.

p5.FFT

L’analisi delle frequenze e dei campioni (reference della classe):

• new p5.FFT( bande ): crea l’analisi, con il numero di bande dello spettro, una potenza di 2 fra 16 e 1024 (32 se non indicato); va collegata al suono con connect();
• analyze(): restituisce lo spettro, un array con un valore fra 0 e 1 per ogni banda, dalle frequenze basse alle alte, oppure in decibel con fft.analyzer.normalRange = false (capitolo 5);
• waveform(): restituisce i 1024 campioni del frammento in esecuzione, fra -1 e 1.

p5.Amplitude

L’analisi del volume (reference della classe):

• new p5.Amplitude(): crea l’analisi, che va collegata al suono con connect();
• getLevel(): volume del frammento in esecuzione, da 0 a 1, ma di solito molto più basso: con il brano di Liszt arriva al massimo a 0,09;
• smooth( valore ): smussa le variazioni, da 0 (nessuna smussatura) a quasi 1.

Funzioni

• userStartAudio(): riattiva l’audio dopo un’azione dell’utente;
• getAudioContext(): restituisce il contesto audio del browser, da cui si leggono la frequenza di campionamento (getAudioContext().sampleRate) e l’orologio dell’audio (getAudioContext().currentTime, capitolo 7).

5. Valori in decibel

analyze() restituisce l’ampiezza di ogni banda su una scala lineare, con valori quasi sempre molto piccoli: nei primi 15 secondi del brano di Liszt il massimo è 0,016, e un diametro ricavato direttamente da questi valori resta sotto il pixel. L’orecchio percepisce invece il volume su una scala logaritmica, quella dei decibel, e la versione precedente restituiva i valori già convertiti, da 0 a 255. I decibel si ottengono con una riga, subito dopo aver creato l’analisi:

  fft = new p5.FFT( 256 );
fft.analyzer.normalRange = false;   // analyze() restituisce decibel

analyzer è l’analisi della libreria Tone.js usata da p5.FFT, e la sua proprietà normalRange decide se i valori vanno da 0 a 1 (true, l’impostazione di p5.sound.js) o sono in decibel (false). La proprietà non è nella reference di p5.js, e una versione successiva della libreria potrebbe cambiarla. Con i due brani delle slide di Codestesie i decibel vanno da circa -200, nelle bande quasi silenziose, a circa -25, e prima che il brano parta valgono -Infinity. La versione precedente trasformava -100 decibel in 0 e -30 decibel in 255, e la funzione seguente fa la stessa conversione:

  // converte un valore di analyze(), in decibel, nella scala da 0 a 255
function livello( decibel ) {
  return map( decibel, -100, -30, 0, 255, true );
}

Con true i valori sotto -100 decibel, -Infinity compreso, danno 0. Senza, diventerebbero negativi: p5.js disegna un cerchio con un diametro negativo come se fosse positivo, e una media calcolata con lerp() (capitolo 9) passerebbe a -Infinity e poi a NaN, senza più tornare un numero. Se non si vuole usare normalRange, i decibel si ricavano dai valori fra 0 e 1 con un logaritmo: 20 * Math.log10( valore ).

I valori tornano così quasi uguali a quelli della versione precedente: con il brano di Liszt, nei primi 15 secondi, il massimo dello spettro è 234 contro 231, e l’energia media dei bassi 70 contro 71. Il codice scritto per la versione precedente funziona quindi passando ogni valore per livello():

  let spettro = fft.analyze();
for (let i = 0; i < spettro.length; i++) {
  let diametro = livello( spettro[i] ) * 0.6;
  circle( i * 4, height / 2, diametro );
}

6. Energia delle frequenze

getEnergy() restituiva il livello medio delle frequenze comprese fra due valori, o di una delle cinque fasce predefinite. Con l’analisi in decibel e livello() (capitolo 5) si ricostruisce così:

  // livello medio delle bande fra due frequenze, come getEnergy()
function energia( spettro, frequenzaMin, frequenzaMax ) {
  let nyquist = getAudioContext().sampleRate / 2;  // frequenza massima
  let primo = round( frequenzaMin / nyquist * spettro.length );
  let ultimo = round( frequenzaMax / nyquist * spettro.length );
  let somma = 0;
  for (let i = primo; i <= ultimo; i++) {
    somma += livello( spettro[i] );
  }
  return somma / (ultimo - primo + 1);
}

Le cinque fasce della versione precedente:

Lo spettro si legge una volta sola per fotogramma, e lo stesso array si passa a tutte le chiamate di energia(). Per le frequenze basse servono molte bande: con new p5.FFT( 1024 ) ognuna copre poco più di 20 Hz, e i bassi ne comprendono una mezza dozzina; con 32 bande, il valore predefinito, la prima va da 0 a circa 700 Hz e comprende da sola bassi e medio-bassi.

7. Posizione e cue

La libreria non dice in che punto del brano è arrivata la riproduzione, e non ha un equivalente di addCue(), che chiamava una funzione in un momento stabilito del brano: la mancanza è segnalata anche da una richiesta aperta nel repository della libreria. La posizione si ricava dall’orologio dell’audio, getAudioContext().currentTime, che conta i secondi con precisione: basta memorizzare l’istante d’avvio, tenendo conto che il suono parte circa un decimo di secondo dopo la chiamata a play(). Misurata con un brano di prova, la posizione così calcolata coincide con il suono entro un centesimo di secondo.

I cue si ottengono controllando a ogni fotogramma quali momenti la posizione ha superato dall’ultimo controllo, compreso il passaggio dalla fine all’inizio di un brano in ripetizione. Nell’esempio lo sfondo cambia a 3, 6 e 9 secondi dall’inizio, a ogni giro del brano.

    let brano;                  // il file audio
let inizio;                 // istante d'avvio, sull'orologio dell'audio
let ultimaPosizione = 0;    // posizione all'ultimo controllo dei cue
let cue = [];               // momenti del brano a cui succede qualcosa
let grigio = 255;           // colore dello sfondo, cambiato dai cue

async function setup() {
  createCanvas( 670, 200 );
  textSize( 16 );
  brano = await loadSound( 'liszt.mp3' );
  brano.loop();
  aggiungiCue( 3, cambiaSfondo, 220 );
  aggiungiCue( 6, cambiaSfondo, 170 );
  aggiungiCue( 9, cambiaSfondo, 255 );
}

function draw() {
  background( grigio );
  if (brano.isPlaying()) {
    controllaCue();
    text( posizione().toFixed( 1 ) + ' secondi', 20, 30 );
  } else {
    text( 'clic per avviare il brano', 20, 30 );
  }
}

function cambiaSfondo( valore ) {
  grigio = valore;
}

function mousePressed() {
  userStartAudio();
  if (brano.isPlaying()) {
    brano.stop();
  } else {
    avvia();
  }
}

function avvia() {
  brano.play();
  inizio = getAudioContext().currentTime + 0.1;  // 0.1 s di ritardo
  ultimaPosizione = 0;
}

function posizione() {
  let trascorso = max( 0, getAudioContext().currentTime - inizio );
  if (brano.isLooping()) {
    return trascorso % brano.duration();   // a ogni giro riparte da 0
  }
  return min( trascorso, brano.duration() );
}

function aggiungiCue( tempo, azione, valore ) {
  cue.push( { tempo: tempo, azione: azione, valore: valore } );
}

function controllaCue() {
  let ora = posizione();
  for (let c of cue) {
    let superato;
    if (ora >= ultimaPosizione) {
      superato = c.tempo > ultimaPosizione && c.tempo <= ora;
    } else {   // il brano è ricominciato dall'inizio
      superato = c.tempo > ultimaPosizione || c.tempo <= ora;
    }
    if (superato) {
      c.azione( c.valore );
    }
  }
  ultimaPosizione = ora;
}
  

  inizio = getAudioContext().currentTime + 0.1;

Memorizza l’istante in cui il suono comincia davvero, un decimo di secondo dopo play().

  let trascorso = max( 0, getAudioContext().currentTime - inizio );

Calcola i secondi passati dall’inizio del suono, che nel primo decimo di secondo valgono 0. Se il brano si ripete, % li riporta a 0 a ogni giro.

  aggiungiCue( 3, cambiaSfondo, 220 );

Come addCue(): a 3 secondi dall’inizio del brano chiama cambiaSfondo( 220 ).

  controllaCue();

Chiamata a ogni fotogramma durante la riproduzione, esegue i cue con un momento compreso fra l’ultimo controllo e la posizione attuale.

Il calcolo vale per la riproduzione continua a velocità normale: con rate() o pause() la posizione non corrisponde più al suono. Dopo jump() basta riallineare l’istante d’avvio:

  function salta( secondi ) {
  brano.jump( secondi );
  inizio = getAudioContext().currentTime + 0.1 - secondi;
  ultimaPosizione = posizione();  // i cue scavalcati non scattano
}

8. Forma d’onda del brano

getPeaks() restituiva i picchi del volume lungo tutto il brano, per disegnarne la forma d’onda completa anche prima della riproduzione. I campioni si leggono dal buffer del brano, che la libreria tiene nella proprietà node: non è documentata, quindi potrebbe cambiare nelle versioni successive.

  // volume massimo in "quanti" tratti del brano, come getPeaks()
function picchi( suono, quanti ) {
  let dati = suono.node.buffer.getChannelData( 0 );  // primo canale
  let passo = floor( dati.length / quanti );
  let risultato = [];
  for (let i = 0; i < quanti; i++) {
    let massimo = 0;
    for (let j = i * passo; j < (i + 1) * passo; j++) {
      massimo = Math.max( massimo, Math.abs( dati[j] ) );
    }
    risultato.push( massimo );
  }
  return risultato;
}

I valori vanno da 0 a 1. Con let forma = picchi( brano, width ); in setup(), dopo loadSound(), si ottiene un valore per ogni colonna della tela; per un brano di due minuti il calcolo richiede pochi millesimi di secondo.

9. Picchi del volume

p5.PeakDetect segnalava i colpi, per esempio quelli della batteria, quando l’energia di una fascia di frequenze superava una soglia. Un risultato simile si ottiene confrontando l’energia con la sua media recente, che si adatta al volume del brano:

  let media = 0;            // media recente dell'energia
let scarto = 10;          // quanto l'energia deve superare la media
let distanzaMinima = 10;  // fotogrammi minimi fra due picchi
let ultimoPicco = 0;

function piccoRilevato( valore ) {
  let sopraLaMedia = valore > media + scarto;
  let abbastanzaDistante = frameCount - ultimoPicco > distanzaMinima;
  let picco = sopraLaMedia && abbastanzaDistante;
  if (picco) {
    ultimoPicco = frameCount;
  }
  media = lerp( media, valore, 0.02 );
  return picco;
}

Con questi valori, nei primi 20 secondi dei due brani usati nelle slide di Codestesie i picchi dei bassi sono circa due al secondo; uno scarto più alto li rende più rari. Per esempio, in draw():

  let spettro = fft.analyze();
if (piccoRilevato( energia( spettro, 20, 140 ) )) {
  tinta = random( 360 );   // un colore nuovo a ogni colpo dei bassi
}

10. Microfono

p5.AudioIn legge il suono del microfono dopo il permesso dell’utente, che il browser chiede solo alle pagine servite da Live Server o da un sito in https. A differenza della versione precedente manda il suono anche agli altoparlanti, con il rischio di un fischio (effetto Larsen): va staccato con disconnect() prima di collegarlo all’analisi.

  let microfono;   // l'ingresso audio
let volume;      // analisi del volume

function setup() {
  createCanvas( 670, 200 );
  microfono = new p5.AudioIn();
  volume = new p5.Amplitude();
  microfono.disconnect();   // altrimenti esce dagli altoparlanti
  microfono.connect( volume );
}

function mousePressed() {
  microfono.start();   // chiede il permesso di usare il microfono
}

function draw() {
  background( 255 );
  let diametro = map( volume.getLevel(), 0, 0.3, 0, height );
  circle( width / 2, height / 2, diametro );
}

11. Classi mancanti e Tone.js

Le classi tolte dalla libreria (p5.MonoSynth, p5.PolySynth, p5.SoundLoop, p5.Compressor, p5.EQ e altre) non danno errore: mostrano solo un avviso nella console, e il codice che le usa resta muto. p5.Filter è diventata p5.Biquad, con le varianti p5.LowPass, p5.HighPass e p5.BandPass. Per il resto si usano le classi di Tone.js, la libreria su cui è costruita p5.sound.js, caricata dopo di essa nella stessa versione che usa internamente:

  <script src="https://cdn.jsdelivr.net/npm/tone@15.0.2/build/Tone.js"></script>

Le due librerie devono usare lo stesso contesto audio. Per esempio, p5.Amplitude misura il volume dei due canali insieme, mentre Tone.Meter può misurarli separatamente:

  // in setup(), prima di creare oggetti di Tone.js
Tone.setContext( getAudioContext() );
canali = new Tone.Meter( { channelCount: 2, normalRange: true } );
Tone.connect( brano.output, canali );   // da p5.sound.js a Tone.js

// in draw(): volume dei canali sinistro e destro, da 0 a 1
let volumi = canali.getValue();

brano.connect( canali ) dà invece un errore: il collegamento da p5.sound.js a Tone.js passa per Tone.connect() e per la proprietà output, che non è documentata. Nel senso opposto vale setInput(), per esempio fft.setInput( oscillatore ) per analizzare un suono generato direttamente con Tone.js.

12. Riferimenti

• reference di p5.sound.js, con un esempio per ogni metodo;
• esempi del repository di p5.sound.js: alcuni usano setInput() con un brano caricato, che nella versione 0.4.1 dà errore;
• differenze fra le due versioni, nella guida al passaggio a p5.js 2 (in inglese);
• Tone.js, con la documentazione e gli esempi.