API JavaScript

Crear una instancia de VoiceDropper

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

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

Consejo: guarda una referencia a la instancia (vd) para poder llamar a sus métodos más adelante, por ejemplo desde botones personalizados o controles UI externos.

Métodos de reproducción

Alternar reproducción / pausa / reanudación

Este es el método principal de tipo toggle que utiliza internamente la interfaz del reproductor. Funciona así:

• Si está inactivo → inicia la reproducción
• Si está reproduciendo → la pausa
• Si está en pausa → la reanuda

// Toggle playback
vd.playEvent();

Iniciar la reproducción

Inicia la reproducción de forma explícita. Si el audio aún no está cargado, primero se recuperará y preparará.

await vd.startPlayback();

Pausar la reproducción

Pausa la reproducción manteniendo la posición actual.

vd.pause();

Reanudar la reproducción

Reanuda la reproducción desde la posición actual.

vd.resume();

Detener la reproducción

Detiene la reproducción y restablece el progreso al inicio (00:00).

vd.stop();

Métodos de recarga

Recargar el audio

Obliga al reproductor a recargar el recurso de audio actual (mismo ID de audio), reiniciando el estado interno y la interfaz, con opción de reproducción automática.

• autoplay (boolean): si true, inicia la reproducción después de recargar
• preload (boolean): si true, precarga el audio sin iniciar la reproducción

// 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 });

Casos de uso habituales:

• El audio se ha regenerado en el servidor.
• Quieres asegurarte de cargar la versión más reciente.
• Necesitas un reinicio limpio sin recrear la instancia del reproductor.

Métodos de seek

Seek por porcentaje

Mueve la reproducción a un porcentaje de la duración total (0–100).

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

Seek por milisegundos

Mueve la reproducción a una posición absoluta expresada en milisegundos.

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

Obtener la posición actual

Devuelve la posición actual de reproducción en milisegundos.

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

Personalización en tiempo real

Actualizar la configuración del reproductor

Actualiza la configuración de la instancia en tiempo de ejecución. Esta es la forma recomendada de cambiar colores del tema, etiquetas, iconos y opciones de funcionalidad (mini reproductor sticky / velocidad de reproducción) sin recrear el reproductor.

Firma

vd.update(nextOptions, opts);

Ejemplo: actualizar el tema

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

Ejemplo: actualizar etiquetas

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

Ejemplo: activar o desactivar funciones

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

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

En la mayoría de las integraciones no necesitarás el parámetro opcional opts.

Lectura del estado del reproductor

Una instancia de VoiceDropper expone valores de estado útiles que puedes consultar para crear lógica UI personalizada.

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

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

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

Callback onReady

Puedes pasar una callback onReady en las opciones del constructor para ejecutar código cuando el reproductor esté inicializado y listo.

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

Buenas prácticas

• Usa playEvent() si quieres un único control toggle, como en la interfaz integrada.
• Usa startPlayback() para acciones explícitas del tipo “reproducir ahora”.
• Usa update() para cambios de tema, idioma o configuración en tiempo real.
• Usa seekToPercent() para controles de progreso simples y seekToGlobalMs() para desplazamientos precisos.