Player Embedding

Embed audio players on your website with customizable styling and JavaScript control.

Quick Start

Add the embed script to your page, then add a container element with your audio generation's UUID:

<!-- Include the embed script -->
<script src="https://voicethistext.com/js/embed.min.js" defer></script>

<!-- Add a player container -->
<div data-voicethistext="your-generation-uuid"></div>

The script will automatically initialize all player containers on page load. Players are rendered inside a Shadow DOM for style isolation, so they won't be affected by your site's CSS and vice versa.

Data Attributes

Customize the player using data attributes on the container element:

Attribute Values Description
data-voicethistext UUID Audio generation UUID (required)
data-style "default" | "compact" Player layout style (default: "default")
data-theme "light" | "dark" | "auto" Color theme (default: "auto")
data-color Hex color Accent color (default: "#18181b")
data-transcript "true" | "false" | "below" "true" = toggle button, "below" = always visible (default: "false")
data-transcript-target CSS selector Sync word highlighting to external element
data-mode "default" | "toggle" Display as full player or toggle button (default: "default")
data-toggle-text string Button text for play state (default: "Play")
data-toggle-stop-text string Button text for stop state (default: "Stop")
data-toggle-style "outline" | "solid" Button style for toggle mode (default: "outline")
data-show-download "true" | "false" Show download button (default: "false")
data-show-volume "true" | "false" Show volume control (default: "true", "false" for compact)
data-show-speed "true" | "false" Show speed control (default: "true", "false" for compact)
data-show-variants "true" | "false" Show version selector when multiple variants exist (default: "true")

Example with all options

<div
    data-voicethistext="abc123-def456-..."
    data-style="compact"
    data-theme="dark"
    data-color="#8b5cf6"
    data-transcript="below"
></div>

Variants

Variants allow you to offer multiple audio versions of the same content — for example, different languages or voices. When a generation has variants, the embedded player automatically shows a dropdown selector so listeners can switch between them. This feature is available on the Pro and Business plans.

How it works

  1. Create a main audio generation as usual.
  2. Create one or more variants via the API or the dashboard.
  3. Embed the main generation — the player loads all variants automatically.

Controlling the selector

Use data-show-variants to control whether the version selector is displayed: 

<!-- Show variant selector (default when variants exist) -->
<div data-voicethistext="your-uuid" data-show-variants="true"></div>

<!-- Hide variant selector -->
<div data-voicethistext="your-uuid" data-show-variants="false"></div>

Variant labels

Labels in the selector are resolved in this order: variant_label → title → fallback text. Set variant_label via the API to control exactly what users see. The main generation defaults to "Original" if no label is set. 

# Set a label on the main generation
curl -X PUT https://voicethistext.com/api/v1/audio-generations/550e8400-... \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "variant_label": "Cantonese" }'

When switching variants, the player preserves the relative playback position so the listener continues from roughly the same point in the content.

Toggle Mode

Use toggle mode to show a compact button that expands into the full player when clicked. This is perfect for blog posts or articles where you want a non-intrusive "Listen to this article" button. 

<div
    data-voicethistext="your-generation-uuid"
    data-mode="toggle"
    data-toggle-text="Listen to this article"
    data-toggle-stop-text="Stop listening"
></div>

When clicked, the button loads the player and starts playing automatically. The button remains visible and switches to a "Stop" state – clicking it again will stop playback and hide the player.

Toggle Mode Options

  • data-mode="toggle" – Enable toggle mode (shows button instead of full player)
  • data-toggle-text – Text for play state (default: "Play")
  • data-toggle-stop-text – Text for stop state (default: "Stop")
  • data-toggle-style – Button style: "outline" (subtle, default) or "solid" (bolder)

The button uses your data-color setting as its accent color.

Programmatic Control

You can also expand or collapse a toggle-mode player programmatically:

const player = VoiceThisText.get('your-uuid');
player.expand();   // Expands to full player and auto-plays
player.collapse(); // Stops playback and hides the player

JavaScript API

Control players programmatically using the global VoiceThisText object.

Getting a Player Instance

// Get a specific player by UUID
const player = VoiceThisText.get('your-generation-uuid');

// Get all players on the page
const allPlayers = VoiceThisText.getAll();

// Pause all players
VoiceThisText.pauseAll();

Playback Control

player.play();           // Start playback
player.pause();          // Pause playback
player.toggle();         // Toggle play/pause
player.seek(30);         // Seek to 30 seconds
player.setSpeed(1.5);    // Set playback speed
player.setVolume(0.8);   // Set volume (0-1)
player.mute();           // Mute audio
player.unmute();         // Unmute audio
player.expand();         // Toggle mode: expand to full player and auto-play
player.collapse();       // Toggle mode: stop playback and hide player

Player State

player.isPlaying();      // Returns true if playing
player.isMuted();        // Returns true if muted
player.getCurrentTime(); // Returns current time in seconds
player.getDuration();    // Returns total duration in seconds
player.getSpeed();       // Returns current playback speed
player.getVolume();      // Returns current volume (0-1)

Events

Listen for player events using the on() method:

player.on('ready', ({ duration }) => {
    console.log('Player ready, duration:', duration);
});

player.on('play', () => {
    console.log('Playback started');
});

player.on('pause', () => {
    console.log('Playback paused');
});

player.on('ended', () => {
    console.log('Playback ended');
});

player.on('timeupdate', ({ currentTime, duration, currentWord }) => {
    console.log('Time:', currentTime, '/', duration);
    if (currentWord) {
        console.log('Current word:', currentWord.word);
    }
});

player.on('wordchange', ({ word, index }) => {
    console.log('Now speaking word:', word, 'at index:', index);
});

// Remove event listener
player.off('play', myCallback);

// Remove all listeners for an event
player.off('play');

Transcript Control

player.showTranscript();     // Show built-in transcript
player.hideTranscript();     // Hide built-in transcript
player.toggleTranscript();   // Toggle transcript visibility
player.seekToWord(5);        // Seek to word at index 5

// Sync highlighting to external element
player.syncTranscriptTo('#my-article');

External Transcript Sync

Sync word-by-word highlighting to your own content using the data-transcript-target attribute or the syncTranscriptTo() method. This is perfect for highlighting the original article or post as the audio plays. 

<!-- Player with external transcript sync -->
<div
    data-voicethistext="your-uuid"
    data-transcript-target="#article-content"
></div>

<!-- Your article content -->
<article id="article-content">
    <p>Your article text here. Each word will be wrapped
    and highlighted as it's spoken.</p>
</article>

<style>
    /* Style the highlighted word */
    .vtt-word-active {
        background-color: rgba(251, 191, 36, 0.5);
    }
</style>

When playback starts, the script wraps each word in your content with a <span class="vtt-word"> element. The currently spoken word receives the vtt-word-active class, which you can style however you like.

CDN Hosting

If you're hosting the embed script on your own CDN, you need to tell the player where the API is located. There are two ways to do this:

Via Script Attribute

<script
    src="https://your-cdn.com/js/embed.js"
    data-api-url="https://voicethistext.com"
    defer
></script>

Via Global Config

<script>
    window.VoiceThisTextConfig = {
        apiBaseUrl: 'https://voicethistext.com'
    };
</script>
<script src="https://your-cdn.com/js/embed.js" defer></script>

Styling

The JavaScript player is rendered inside a Shadow DOM, so your page styles won't affect it. However, you can customize the appearance using data attributes:

  • data-theme – Switch between light, dark, or auto (follows system preference)
  • data-color – Set the accent color (progress bar, focus rings)
  • data-style – Choose between "default" (full-size) or "compact" (smaller)
<!-- Dark theme with purple accent -->
<div
    data-voicethistext="your-uuid"
    data-theme="dark"
    data-color="#8b5cf6"
    data-style="compact"
></div>