Méthodes de l’API JavaScript

Créer une instance VoiceDropper

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

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

Conseil : gardez une référence vers l’instance (vd) pour pouvoir appeler ses méthodes plus tard, par exemple depuis vos propres boutons.

Méthodes de lecture

Basculer lecture / pause / reprise

C’est la méthode “tout-en-un” utilisée par l’interface native. Elle agit comme un toggle :

• si le lecteur est idle → la lecture démarre ;
• s’il joue déjà → il se met en pause ;
• s’il est en pause → il reprend.

// Toggle lecture
vd.playEvent();

Démarrer la lecture

Démarre explicitement la lecture. Si l’audio n’est pas encore prêt, il est d’abord récupéré puis préparé.

await vd.startPlayback();

Mettre en pause

Met la lecture en pause sans remettre la progression à zéro.

vd.pause();

Reprendre

Reprend à la position actuelle.

vd.resume();

Arrêter

Stoppe la lecture et remet la progression au début.

vd.stop();

Méthodes de rechargement

Recharger l’audio

Force le lecteur à recharger l’asset audio courant, réinitialise l’état interne et l’UI, puis peut éventuellement relancer la lecture.

• autoplay (boolean) : si true, la lecture démarre après le reload ;
• preload (boolean) : si true, les données audio sont préchargées sans autoplay.

// Recharge l’audio et le garde prêt (sans autoplay)
await vd.reloadAudioOnly({ preload: true, autoplay: false });

// Recharge l’audio avec autoplay (soumis aux règles du navigateur)
await vd.reloadAudioOnly({ preload: true, autoplay: true });

Cas d’usage fréquents :

• l’audio a été régénéré côté serveur ;
• vous voulez être sûr de charger la dernière version ;
• vous voulez un reset propre sans recréer l’instance.

Méthodes de navigation

Se déplacer en pourcentage

Permet d’aller à un pourcentage de la durée totale (0–100).

// Aller au milieu
vd.seekToPercent(50);

Se déplacer en millisecondes

Permet d’aller à une position absolue exprimée en millisecondes.

// Aller à 30 secondes
vd.seekToGlobalMs(30000);

Lire la position courante

Retourne la position actuelle de lecture en millisecondes.

const ms = vd.getGlobalCurrentTimeMs();
console.log('Position actuelle :', ms);

Personnalisation à l’exécution

Mettre à jour la configuration du lecteur

La méthode update() est la façon recommandée de modifier le thème, les labels, les icônes ou les options comme le sticky player et la vitesse sans recréer le lecteur.

Signature

vd.update(nextOptions, opts);

Exemple : changer le thème

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

Exemple : changer les labels

vd.update({
  labels: {
    play: 'Lecture',
    stop: 'Stop',
    resume: 'Reprendre',
    pause: 'Pause',
    speed: 'Vitesse de lecture',
    close: 'Fermer',
    init: 'Appuyez sur lecture pour écouter',
    loading: 'Chargement de l’audio...'
  }
});

Exemple : activer des fonctionnalités

// Activer le mini-lecteur sticky
vd.update({ stickyplayer: true });

// Activer le bouton de vitesse (désactivé automatiquement sur iOS)
vd.update({ playspeed: true });

Dans la plupart des cas, vous n’aurez pas besoin du paramètre optionnel opts.

Lire l’état du lecteur

Une instance VoiceDropper expose plusieurs valeurs utiles pour piloter votre propre interface :

• vd.isPlaying (boolean)
• vd.isPaused (boolean)
• vd.audioLoaded (boolean)
• vd.currentSpeed (number: 1, 1.5, 2)
• vd.totalDurationMs (number)

if (vd.isPlaying) {
  console.log('L’audio est en lecture');
}

if (vd.isPaused) {
  console.log('L’audio est en pause');
}

Callback onReady

Vous pouvez passer un callback onReady dans les options du constructeur pour exécuter du code lorsque le lecteur est prêt.

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

Bonnes pratiques

• Utilisez playEvent() si vous voulez un comportement toggle comme dans l’UI native.
• Utilisez startPlayback() pour des actions “lancer maintenant” explicites.
• Utilisez update() pour changer le thème ou la langue à l’exécution.
• Utilisez seekToPercent() pour des contrôles simples et seekToGlobalMs() pour un seek précis.