RetroAudio docs

Everything you need to give your website a voice.

Getting started

1. Create an account and add your website's address.
2. Copy the embed code from Websites → your site → Install and paste it before </body> on every page:

<script src="https://audio.theretrochat.com/r.js" data-site="YOUR_SITE_KEY" defer></script>

That's it. A Listen button appears under the article's title. The key is public, but it only works on the domains you list for the site (and their subdomains).

Placing the button

Choose where it appears under Button: above the article (automatic), floating in a corner, or only where you put it. To put it in a specific place, add this element where it should appear:

<div data-retroaudio-button></div>

You can add it more than once, for example at the top and bottom of a long article. The label, color and starting speed are set in the dashboard.

What gets read

RetroAudio looks for the page's main content (article, main and common content containers) and skips navigation, headers, footers, sidebars, buttons and forms. It reads only text a visitor can see: anything hidden with CSS (display:none, visibility:hidden, zero opacity, zero size, transparent text), screen-reader-only text, text moved off the page, collapsed accordions and closed

RetroAudio looks for the page's main content (article, main and common content containers) and skips navigation, headers, footers, sidebars, buttons, forms and hidden text. To be exact:

• Name the part to read on the script tag: data-content="#article-body", or set it under What to read.
• Mark the part with data-retroaudio-content.
• Skip anything with class="ra-skip" or data-retroaudio-skip, or list CSS selectors under What to read.
• The voice follows the page's language: <html lang="es"> is read in Spanish. Override it with data-lang="es" on the script tag.

Reading tools

Turn each on or off for a site under Reading tools. Visitors can also change most of them for themselves in the player's settings.

Keyboard

JavaScript API

window.addEventListener('retroaudio:ready', () => {
  RetroAudio.play();       // start or resume reading the page
  RetroAudio.pause();
  RetroAudio.stop();
  RetroAudio.toggle();
  RetroAudio.openReader(); // open the reader view
  RetroAudio.text();       // the text it will read (only what is visible on the page)
  RetroAudio.refresh();    // find the content again after your app changed the page
});

WordPress

1. Download the plugin.
2. In WordPress, go to Plugins → Add New → Upload Plugin, upload the zip and activate it.
3. Go to Settings → RetroAudio and paste your site key.

The button appears on posts and pages. Use the [retroaudio] shortcode to place it yourself.

Voices & languages

• Premium voices: natural, expressive voices in English (American, British, Australian, Irish and Filipino accents) and Spanish. On every plan.
• Standard voices: English, Spanish, French, Chinese, Japanese and Korean.
• Online voices: 50 languages, including Arabic, Hindi, Urdu, German, Russian, Turkish and more.
• Device voices: Persian, Irish and Slovenian use the voices built into the visitor's browser or phone. They're also the backup if your credits run out.

Pick the voice for each language under Websites → Voices. Visitors can switch voice and speed in the player.

Credits

New audio uses credits: one per character (not counting spaces) with standard voices, three with premium voices. Audio is cached, so when the next visitor plays the same text it costs nothing. Translations use one credit per character, a definition 50, and a summary one per 10 characters of the page. Device voices are free.

Pronunciation

Under Pronunciation, add words and how to say them, for example GIF → jif. Entries apply to every site, the Reader, Studio and the API, for all languages or just one, with or without matching case.

Studio & Reader

Studio turns scripts into audio files. Split a script into parts, give each its own voice and a pause after it, preview each part, and export MP3 or WAV. Each export can have a public link to share or embed.

Reader lets your team listen to uploaded documents (PDF, Word, OpenDocument, PowerPoint, Excel, text), web pages and pasted text, with highlighting, translation, summaries and MP3 download.

Text-to-speech API

Available on Pro and up. Create a key under API and send it as a bearer token.

curl https://audio.theretrochat.com/v1/speech \
  -H "Authorization: Bearer ra_live_…" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from RetroAudio.", "voice": "aura2-en-thalia", "format": "mp3"}' \
  --output hello.mp3

POST /v1/speech

Audio responses include the headers x-ra-duration (seconds), x-ra-characters and x-ra-credits.

GET /v1/voices

Lists every voice with its id, language, tier, gender, accent and credits per character. Add ?lang=es to filter. No key needed.

GET /v1/usage

This month's credits used and the limit for the key's workspace.

SSML

<speak>
  Welcome to <sub alias="R A">RA</sub> Radio.<break time="600ms"/>
  Your code is <say-as interpret-as="characters">AB12</say-as>.
  <p>Each paragraph ends with a short pause.</p>
</speak>

Supported: <break time="…ms|s"> or strength (up to 10 s), <p>, <s>, <sub alias>, and <say-as interpret-as="characters|spell-out|digits">. Other tags are ignored and their text is read.

Errors & limits

Errors are JSON: { "error": "message", "code": "…" }.

Voice list

Questions? Email hello@theretrochat.com.