JavaScript API Methods

Create a VoiceDropper Instance

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

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

Tip: keep a reference to the instance (vd) so you can call methods later (for example from your own custom buttons or UI controls).

Playback Methods

Toggle play / pause / resume

This is the main “single-button” method used internally by the player UI. It behaves like a toggle:

• If idle → starts playback
• If playing → pauses
• If paused → resumes

// Toggle playback
vd.playEvent();

Start playback

Explicitly starts playback. If the audio is not loaded yet, it will be fetched and prepared before playing.

await vd.startPlayback();

Pause playback

Pauses playback without resetting the current progress.

vd.pause();

Resume playback

Resumes playback from the current position.

vd.resume();

Stop playback

Stops playback and resets progress to the beginning (00:00).

vd.stop();

Reload Methods

Reload audio

Forces the player to reload the current audio asset (same key), resetting internal state and UI, then optionally autoplays.

• autoplay (boolean): if true, starts playback after reload
• preload (boolean): if true, preloads audio data (no autoplay)

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

Common use cases:

• The audio was regenerated server-side.
• You want to ensure the latest version is loaded.
• You need a clean reset without recreating the player instance.

Seek Methods

Seek by percentage

Seeks to a percentage of the total duration (0–100).

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

Seek by milliseconds

Seeks to an absolute position expressed in milliseconds.

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

Get current time

Returns the current playback position in milliseconds.

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

Runtime Customization

Update player configuration

Updates the instance settings at runtime. This is the recommended way to change theme colors, labels, icons, and feature toggles (sticky player / playback speed) without recreating the player.

Signature

vd.update(nextOptions, opts);

Example: update theme

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

Example: update labels

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

Example: toggle features

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

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

In most integrations you won’t need the optional opts parameter.

Reading Player State

A VoiceDropper instance exposes useful state values you can read to build custom UI logic.

• 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');
}

onReady Callback

You can pass an onReady callback in the constructor options to run code when the player is initialized and ready.

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

Best Practices

• Use playEvent() if you want a single toggle control like the built-in UI.
• Use startPlayback() for explicit “play now” actions.
• Use update() for runtime theme or language changes.
• Use seekToPercent() for simple progress controls and seekToGlobalMs() for precise seeking.