@mezzo-forte/webaudio v1.0.0-beta.0

Mezzo Forte Web Audio module

Folder structure

• /src js source files
• /example example/test webpage

Testare l'applicazione

• clone git clone https://github.com/francescocretti/mezzoforte-webaudio.git
• install dependencies npm install
• link current module to npm global space npm link /absolute/path/to/mezzoforte-webaudio (e.g. npm link ~/git/MezzoForte/webaudio-module/)
• build with webpack npm run build
• run webpack development server npm run start

Formati supportati

Formato mp3, aac (con contenitore m4a), wav, ogg (non supportato da Safari). Tendenzialmente è preferibile non caricare file wav date le dimensioni dei file.

Fare riferimento a questa tabella per approfondire i formati audio supportati dai vari browser.

In sunto:

Utilizzare i suoni nell'applicazione

Per utilizzare i suoni all'interno dell'applicazione esistono due alternative:

• Buffer Sources
• Media Stream Sources

Buffer Source Nodes

Sfruttano il metodo createBufferSource per caricare, decodificare e rendere disponibili il contenuto audio sotto forma di buffer, per essere riprodotto attraverso nodi AudioBufferSourceNode. Questo approccio garantisce più precisione e controllo sull'audio ma, dato che il suono viene caricato direttamente in memoria, è consigliato per suoni più brevi (approssimativamente di durata inferiore al minuto).

Media Stream Sources

Sfruttano il metodo createMediaElementSource per wrpappare il contenuto di un elemento HTML5 <audio> o <video> dentro un nodo di tipo MediaElementAudioSourceNode, che sfrutta le potenzialità di streaming out-of-the-box dei tag HTML e wrappa il contenuto audio dentro il grafo di WebAudio API. È meno flessibile di un Audio Buffer, ma è molto utile per contenuti audio lunghi.

Best practices

Prima di iniziare a lavorare con Web Audio API, è vivamente consigliata la lettura di questo articolo -> Web Audio API best practices

Definire i suoni da caricare

Per definire quali sono (e di che tipo) i suoni da utilizzare, occorre dichiarare un array di configurazione (nell'esempio qui sotto la variabile audioAssets), specificando, per ogni suono, un identificativo a piacere (key), il path del file (url), se si tratta di un suono stereo o mono (channels) e se si desidera un source node buffer o media-stream (type). Ad esempio:

const audioAssets = [
  {
    key: 'suono_1',
    url: '/audio/sound1.wav',
    channels: 'stereo',
    type: 'buffer'
  },
  {
    key: 'suono_2',
    url: '/audio/sound2_lossy.mp3',
    channels: 'stereo',
    type: 'media-stream'
  }
];

Per caricare i suoni richiamare il metodo App.load, che ha come unico argomento la configurazione dei file audio e restituisce una Promise. Dopodichè si possono utilizzare i suoni caricati e decodificati, se ti tipo Buffer Source, o avviare lo streaming, se di tipo Media Stram Source.

Ad esempio (con riferimento ai suoni di esempio indicati qui sopra):

import MezzoForteAudioEngine from '@mezzo-forte/webaudio';

const App = new MezzoForteAudioEngine(audioContext);

App.load(audioAssets)
  .then() => {
    // avvia il suono sound1.wav
    App.start('suono_1');

    // setto un listnere sulla fine del suono /bch_mix.m4a
    App.onended('suono_2', () => {
      // suono_2 è terminato, posso fare qualcosa (ad esempio mostrare un messaggio, o triggerare un nuvo suono)
    });
  })
  .catch(error => {
    console.error('Opz, qualcosa è andato storto', error);
  });

I metodi attualmente disponibili per i suoni sono:

App.onended(sound_key, callback); // imposto una callback che viene eseguita al termine di sound_key
App.start(sound_key); // avvio sound_key dall'inizio
App.stop(sound_key); // stop
App.resume(sound_key); // riprendo sound_key dall'ultima posizione in cui si è stoppato

TODO

• aggiungere funzioni di fade
• aggiungere gestione di suoni azione (con solo metodo trigger)
• aggiungere qualche effetto (pan, gain, reverb?, distortion?)
• aggiungere possibilità di creare una sorta di playlist con i propri metodi
• altro? ogni suggerimento è ben accetto