Readivo Documentation

A complete guide to integrating the audio player, configuring content extraction, and using the JavaScript API.

Readivo is a SaaS service that automatically converts website text content into spoken audio using neural voices.

Quick Start

For a basic deployment, simply include the JS library and place the player into your article template.

You can also use the official Wordpress plugin: Readivo Wordpress plugin

1. Include the Library

Insert this code into the <head> or right before the closing </body>.

<script async src="https://cdn.readivo.app/dist/loader.js"></script>

2. Insert the Player

Place this tag where the player should appear (e.g., under the article title).

<readivo-player data-readivo-site="SITE_ID"></readivo-player>

SITE_ID is a unique hash you can find in the dashboard under My Sites.

Configuration via Data Attributes

The player behavior can be configured globally in the dashboard, or locally using attributes on the HTML tag. Local attributes always take precedence.

Attribute Type Description
data-readivo-site Required Site configuration ID from the dashboard.
data-readivo-player Optional Player ID from the dashboard.
data-readivo-voice Optional Voice ID (e.g. en-US-Steffan). Overrides dashboard settings.
data-readivo-sticky Optional 1 (enabled) or 0 (disabled). Determines whether the player sticks to the bottom of the window while scrolling.
data-readivo-ad-url Optional URL of a pre-roll advertisement in MP3 format.
data-readivo-play-id Optional ID of the audio file for directly playing a specific audio file.
data-readivo-custom-id Optional Your internal article/page ID (e.g. post-123). Audio for this ID will be generated only once. If the article content changes, a new audio version will not be generated for the given ID.
data-readivo-selector Optional CSS selector for content extraction (the element that contains the article content, e.g. .article-content). Useful if each article has a different structure.
data-readivo-vast-url Optional URL of an external VAST tag. If present, Readivo loads and resolves the VAST response, selects a playable audio media file, plays the ad as pre-roll, and then continues with the main content. This attribute takes precedence over data-readivo-ad-url.
data-readivo-vast-timeout Optional VAST request timeout in milliseconds. Default is typically 5000. If the timeout is reached, the ad is skipped and the main content starts.
data-readivo-vast-max-wrappers Optional Maximum number of allowed VAST wrappers. Default is typically 5. If the limit is exceeded, the ad request fails and the player continues with the main content.
data-readivo-vast-link-text Optional Text used for the ad click-through link shown in the player title area when the VAST response includes a ClickThrough URL. Example: Learn more.

Manual Content Injection

If you do not want to use automatic extraction, you can pass the content directly in HTML. This will skip downloading the page by our server.

AttributeDescription
data-readivo-title Article title. If missing, document.title will be used.
data-readivo-content Article content as plain text, or Base64-encoded. It may include HTML tags.

Text Localization

All texts in the player can be translated or customized using attributes.

<readivo-player
    data-readivo-player="..."
    data-readivo-text-init="Start audio"
    data-readivo-text-playing="Now playing"
    data-readivo-text-paused="Paused"
    data-readivo-text-generate="Preparing audio..."
    data-readivo-text-finished="Finished"
    data-readivo-text-error="Loading error"
    data-readivo-text-ad="Advertisement"
></readivo-player>

The data-readivo-text-ad attribute customizes the label shown while an ad is playing.

Content Extraction (How It Works)

Readivo uses one of three methods to retrieve the article text, depending on your site configuration.

Important: Audio quality depends on extraction quality. We recommend using the server-side method with a defined selector.

1. Server-side (Primary)

Our server visits the article URL, downloads the HTML, and extracts the article content.

2. Client-side

If server-side extraction fails (e.g., the site requires login or blocks bots) and you have Client-side extraction enabled in the dashboard, the player will attempt to extract the text directly from the visitor’s browser using JavaScript.

3. Direct Input (Manual)

If you provide the data-readivo-content attribute in HTML, automatic extraction is skipped and this content will be used.

Selectors & Content Cleaning

In the dashboard (Edit Site), you can define parsing rules.

Main Element (Content Selector)

CSS selector that wraps the main text. E.g. article, .post-body, .content. If not provided, Readivo will attempt to detect the content automatically.

Excluded Elements (Excluded Selectors)

Elements inside the content that should be ignored (removed before reading). Provide a list of CSS selectors.

Examples to exclude:

Minimum Length (Threshold)

If the extracted text is shorter than this limit, audio will not be generated.

Billing & Credits

How do we calculate consumed credits?

JavaScript API

You can control the player programmatically.

Get an Instance

const readivo = document.querySelector('readivo-player');

// It's best to use the 'readivo:ready' event
document.addEventListener('readivo:ready', () => {
    readivo.play();
});

Methods

MethodDescription
readivo.play()Starts playback (or plays the ad).
readivo.pause()Pauses playback.
readivo.togglePlay()Toggles between Play/Pause.
readivo.seek(seconds)Seeks to a specific time in seconds.
readivo.seekBy(delta)Seeks by delta seconds (e.g. -5).

Properties

Read the current player state (read-only).

Property Type Description
readivo.duration number Total audio duration in seconds (or 0 if not loaded).
readivo.currentTime number Current playback position in seconds.
readivo.paused boolean true if playback is paused or stopped.
readivo.isPlaying boolean true if audio is currently playing.

Events

The player dispatches CustomEvents that bubble (bubbles: true). You can listen on the element or on document.

Event List

Event nameData in event.detailDescription
readivo:ready{}Player initialized.
readivo:loading{}Generation/download started.
readivo:loaded{ duration: 120.5 }Audio is ready.
readivo:play{}Content playback started.
readivo:pause{}Playback paused.
readivo:ended{}Playback ended.
readivo:error{ message: "..." }An error occurred.
readivo:ad-start{}Ad mode started. For VAST ads, playback tracking such as impression and start is fired only after the ad media actually begins playing.
readivo:ad-end{}Ad finished or was skipped after an ad failure.

Example: Google Analytics 4

document.addEventListener('readivo:play', (e) => {
    gtag('event', 'audio_play', {
        'event_category': 'Readivo',
        'event_label': window.location.pathname
    });
});

Audio Ads

Readivo supports pre-roll audio advertisements. The ad always plays before the main content.

Supported Ad Modes

Ad Properties

Direct Audio URL Example

Add the data-readivo-ad-url attribute.

<readivo-player
    data-readivo-player="..."
    data-readivo-ad-url="https://example.com/promo.mp3"
></readivo-player>
Warning: The URL must point directly to a playable audio file such as MP3.

VAST Ads

Readivo supports external VAST pre-roll ads. Instead of linking directly to an audio file, you provide a VAST tag URL and the player handles the ad workflow automatically.

How VAST Works in Readivo

When data-readivo-vast-url is present, Readivo does not expect a direct MP3 file. Instead, it requests a VAST XML document from the ad server.

The player then performs the following steps:

Failure Handling

If the VAST request fails, the XML is invalid, no supported audio media file is found, or the ad media file cannot be played, Readivo sends the appropriate VAST error tracker (if provided) and then skips the ad.

In such cases:

Basic VAST Example

<readivo-player
    data-readivo-site="SITE_ID"
    data-readivo-vast-url="https://ads.example.com/vast?pv={PV_ID}&url={PAGE_URL}&cb={CACHEBUSTER}"
></readivo-player>

VAST Example with Full Options

<readivo-player
    data-readivo-site="SITE_ID"
    data-readivo-vast-url="https://ads.example.com/vast?pv={PV_ID}&url={PAGE_URL}&article={ARTICLE_ID}&cb={CACHEBUSTER}"
    data-readivo-vast-timeout="5000"
    data-readivo-vast-max-wrappers="5"
    data-readivo-vast-link-text="Learn more"
    data-readivo-text-ad="Advertisement"
></readivo-player>

Supported Macros in data-readivo-vast-url

Macro Description
{PV_ID} A unique page-view identifier generated once per page load and reused for all ad requests on that page.
{PAGE_URL} The current page URL, URL-encoded.
{REFERRER} The current document referrer, URL-encoded.
{ARTICLE_ID} The current article identifier, if available.
{PLAYER_ID} The current Readivo player instance identifier.
{CACHEBUSTER} A random cache-busting value.
[CACHEBUSTING] IAB-style cache-busting macro supported in VAST URLs and tracking URLs.
[TIMESTAMP] IAB-style timestamp macro supported in VAST URLs and tracking URLs.

ClickThrough and ClickTracking

If the VAST response contains a ClickThrough URL, Readivo can display a clickable link directly inside the player title area. When the user clicks the link, the player opens the destination URL and also fires all related ClickTracking URLs.

The link text is controlled using data-readivo-vast-link-text. If no ClickThrough is present in the VAST response, no link is shown.

VAST Notes

Important: A VAST URL does not return an audio file directly. It returns a VAST XML response that tells the player which media file to play and which tracking URLs to call.