API JavaScript

Creare un'istanza VoiceDropper

const target = document.querySelector('#vd-target');

const vd = new VoiceDropper(target, {
  speech: '[YOUR_SPEECH_ID]'
});

Suggerimento: conserva un riferimento all’istanza (vd) così da poter richiamare i metodi in seguito, ad esempio da pulsanti personalizzati o controlli UI esterni.

Metodi di riproduzione

Alternare play / pausa / ripresa

Questo è il principale metodo “toggle” utilizzato internamente dall’interfaccia del player. Si comporta come un interruttore:

• Se il player è inattivo → avvia la riproduzione
• Se è in riproduzione → mette in pausa
• Se è in pausa → riprende

// Toggle playback
vd.playEvent();

Avviare la riproduzione

Avvia esplicitamente la riproduzione. Se l’audio non è ancora stato caricato, verrà prima recuperato e preparato.

await vd.startPlayback();

Mettere in pausa

Mette in pausa la riproduzione mantenendo la posizione corrente.

vd.pause();

Riprendere la riproduzione

Riprende la riproduzione dalla posizione corrente.

vd.resume();

Interrompere la riproduzione

Interrompe la riproduzione e riporta l’avanzamento all’inizio (00:00).

vd.stop();

Metodi di ricarica

Ricaricare l’audio

Forza il player a ricaricare la risorsa audio corrente (stesso ID audio), reimpostando stato interno e interfaccia, con possibilità opzionale di autoplay.

• autoplay (booleano): se true, avvia la riproduzione dopo il ricaricamento
• preload (booleano): se true, precarica i dati audio senza avviare la riproduzione

// Reload audio and keep it ready (no autoplay)
await vd.reloadAudioOnly({ preload: true, autoplay: false });

// Reload audio and autoplay (note: autoplay behavior may vary by browser policies)
await vd.reloadAudioOnly({ preload: true, autoplay: true });

Casi d’uso comuni:

• L’audio è stato rigenerato lato server.
• Vuoi assicurarti che venga caricata la versione più recente.
• Hai bisogno di un reset pulito senza ricreare l’istanza del player.

Metodi di seek

Seek in percentuale

Sposta la riproduzione a una percentuale della durata totale (0–100).

// Jump to the middle
vd.seekToPercent(50);

Seek in millisecondi

Sposta la riproduzione a una posizione assoluta espressa in millisecondi.

// Jump to 30 seconds
vd.seekToGlobalMs(30000);

Ottenere la posizione corrente

Restituisce la posizione corrente di riproduzione in millisecondi.

const ms = vd.getGlobalCurrentTimeMs();
console.log('Current position:', ms);

Personalizzazione a runtime

Aggiornare la configurazione del player

Aggiorna le impostazioni dell’istanza durante l’esecuzione. Questo è il metodo consigliato per modificare colori del tema, etichette, icone e opzioni funzionali (mini player sticky / velocità di riproduzione) senza ricreare il player.

Firma

vd.update(nextOptions, opts);

Esempio: aggiornare il tema

vd.update({
  style: {
    primary: '#7CD259',
    background: '#0C120D',
    foreground: '#FFFFFF',
    'widget-btn-background': '#7CD259',
    'widget-btn-foreground': '#0C120D'
  }
});

Esempio: aggiornare le etichette

vd.update({
  labels: {
    play: 'Play',
    stop: 'Stop',
    resume: 'Resume',
    pause: 'Pause',
    speed: 'Playback speed',
    close: 'Close',
    init: 'Press play to listen',
    loading: 'Loading speech...'
  }
});

Esempio: attivare o disattivare funzionalità

// Enable sticky mini player
vd.update({ stickyplayer: true });

// Enable playback speed button (auto-disabled on iOS)
vd.update({ playspeed: true });

Nella maggior parte delle integrazioni non avrai bisogno del parametro opzionale opts.

Lettura dello stato del player

Un’istanza VoiceDropper espone valori di stato utili che puoi leggere per costruire logiche UI personalizzate.

• vd.isPlaying (booleano)
• vd.isPaused (booleano)
• vd.audioLoaded (booleano)
• vd.currentSpeed (numero: 1, 1.5, 2)
• vd.totalDurationMs (numero)

if (vd.isPlaying) {
  console.log('Audio is playing');
}

if (vd.isPaused) {
  console.log('Audio is paused');
}

Callback onReady

Puoi passare una callback onReady nelle opzioni del costruttore per eseguire codice quando il player è inizializzato e pronto.

const vd = new VoiceDropper(target, {
  speech: '[YOUR_SPEECH_ID]',
  onReady(instance) {
    console.log('VoiceDropper ready:', instance);
  }
});

Best practice

• Usa playEvent() se vuoi un singolo controllo toggle, come nell’interfaccia integrata.
• Usa startPlayback() per azioni esplicite del tipo “riproduci ora”.
• Usa update() per modifiche a runtime di tema, lingua o configurazione.
• Usa seekToPercent() per controlli di avanzamento semplici e seekToGlobalMs() per uno spostamento preciso.