DF Audio Product — Text-to-speech product pages

Introduction

DF Audio Product adds an audio player to every product page of your PrestaShop store. One click on “Listen to the description” and the product name, short description and full description are read aloud, at the speed chosen by the visitor.

The module works with four speech synthesis engines: the browser engine (free, no API key) and three premium server engines (OpenAI, Google Cloud, ElevenLabs) whose MP3 files are cached to keep costs under control.

Requirements

• PrestaShop 8.0 to 9.x
• PHP 8.0 or higher
• cURL extension enabled (server engines only)
• var/ folder writable by PHP (server engines only)
• No Composer dependency

Installation

1. In the back office, go to Modules > Module Manager.
2. Click Upload a module and drop the dfaudioproduct-1.0.0.zip file.
3. Click Configure once the installation completes.

On install, the module automatically creates the cache table, the admin tab under Catalog, the cache folder var/dfaudioproduct/ protected by an .htaccess file, and registers the required hooks.

Choosing a speech engine

Browser engine (Web Speech API)

This is the default engine. The voice is synthesized directly on the visitor’s device by their browser (Chrome, Edge, Safari, Firefox). No API key, no cost, no data sent to any third party, and no file stored on your server.

The module passes the product text to the browser, which automatically picks a voice matching the visitor’s language. Voice quality and catalog therefore depend on the visitor’s operating system: excellent on macOS and iOS, decent on Windows and Android.

OpenAI TTS

High-quality natural voices. Enter your OpenAI API key, pick a model (tts-1 for speed, tts-1-hd for maximum quality, gpt-4o-mini-tts for the best trade-off) and a voice among: alloy, echo, fable, onyx, nova, shimmer. If the Voice field is empty, alloy is used.

Google Cloud Text-to-Speech

Enter a Google Cloud API key with the Text-to-Speech API enabled. The Voice field is optional: leave it empty and the module derives the language code from the visitor’s language (fr-FR, en-US, es-ES, de-DE, it-IT). To force a specific voice, enter its full name, for example en-US-Neural2-C — the language code is then derived from the voice name.

ElevenLabs

Enter your ElevenLabs API key and, mandatorily, the Voice ID in the Voice field. You will find it in your ElevenLabs voice library. The module uses the eleven_multilingual_v2 model, which natively handles all five languages.

Settings

Enable

Global switch. When disabled, the player disappears from product pages and the audio generation controller stops responding.

Default playback speed

Speed applied on first page load: 0.75x, 1x, 1.25x, 1.5x or 2x. Visitors can then cycle through these values with the player’s speed button.

Maximum characters

Maximum length of the spoken text, between 200 and 20,000 characters (3,000 by default). The text is cleanly truncated at the end of the last complete sentence. This setting directly impacts the cost of server engines, which bill per character: a low value reduces your bill, a high value reads your descriptions in full.

Read the short description / the full description

Two independent switches. The product name is always read first. You can read the short description only (fast, cheap) or everything.

Display position

• Below the buy block (displayProductAdditionalInfo hook) — recommended position, clearly visible under the price and the add-to-cart button.
• Within product actions (displayProductActions hook) — more integrated with the theme’s buttons.

The module registers both hooks but only renders the player on the selected one: changing position requires no work in the module positioning screen.

Cache lifetime (days)

0 = audio files never expire (recommended). A higher value automatically deletes files generated more than N days ago, on the next generation. Useful if you change voice or engine regularly.

How the cache works

The cache only applies to server engines; the browser engine generates no file at all.

1. A visitor clicks “Listen to the description” for the first time.
2. The module extracts the product text server-side, strips the HTML and truncates it according to your character limit.
3. It computes a unique fingerprint from the engine, model, voice, language, shop and the text itself.
4. If no file matches, it calls the engine’s API, receives the MP3 and writes it to var/dfaudioproduct/.
5. The file is served with an ETag header and a one-day Cache-Control. Subsequent visitors get the cached file, and page reloads return a 304 response without re-transferring the audio.

Important consequence: you pay for at most one generation per product and language, not one per visit. Your cost depends on your catalog size, never on your traffic.

Playback speed is not part of the fingerprint: it is applied by the browser to the existing file. A single MP3 therefore covers all five speeds.

Automatic invalidation

A product’s audio cache is purged automatically — in every language and every shop — as soon as that product is updated or deleted, via the actionObjectProductUpdateAfter and actionObjectProductDeleteAfter hooks. Fresh audio is generated on the next play, with the up-to-date content. No manual action is needed after fixing a description.

File location

MP3 files are stored in var/dfaudioproduct/, at the PrestaShop root, deliberately outside the module folder: a module update therefore does not destroy the cache. The folder is protected by an .htaccess file and an index.php: files are only reachable through the module controller, never by direct access.

Cache management in the back office

The settings page displays a statistics panel at the top: number of cached files, disk space used and total play count.

The Browse cached files button opens the Catalog > DF Audio Product tab, which lists every file with the product ID, product name, language, engine, voice, size, play count and generation date. You can delete one file, a selection of files, or purge everything with the Purge all toolbar button.

The Purge audio cache button on the settings page has the same effect: it deletes the files from disk and empties the table. The audio will simply be regenerated on demand.

The storefront player

The player consists of a “Listen to the description” button, a progress bar, a time counter and a speed button.

• Server engines: the progress bar is seekable, and the counter shows elapsed time and total duration.
• Browser engine: the progress bar is indicative (it advances word by word) and the counter is hidden, since the Web Speech API provides no duration.

Changing speed mid-playback is handled in both cases. With the browser engine, since speech synthesis cannot change rate on the fly, the module silently restarts it from the last spoken word — the resume is imperceptible. A keep-alive mechanism also works around the cutoff of long utterances after roughly fifteen seconds on Chromium browsers.

The player re-initializes automatically on an AJAX combination change, by listening to the theme’s updatedProduct event.

Accessibility

The player is designed to be usable by everyone, in the spirit of the European Accessibility Act:

• Play button with an aria-pressed state reflecting ongoing playback
• An aria-live region announcing loading, playback or errors to screen readers
• Full keyboard navigation and activation, with a visible focus ring
• A labelled progress bar operable by keyboard
• Support for the prefers-reduced-motion system preference (slower loading animation)
• Generous touch targets and a layout adapted to small screens

Audio playback of product content is a concrete answer to accessibility requirements. Your store’s overall compliance nonetheless depends on all your pages — theme, checkout flow, editorial content.

Multilingual and multistore

Text is extracted in the visitor’s language: each language therefore produces its own audio file, with a suitable voice. In multistore, the cache is also separated per shop, which supports different descriptions from one store to another.

The player’s interface labels (“Listen to the description”, “Pause”, “Resume”, “Loading…”) are translatable from International > Translations > Module translations.

Styling

The player uses CSS variables you can override from your child theme’s stylesheet, without touching the module:

.dfap-player {
  --dfap-accent: #2b6cb0;
  --dfap-accent-hover: #1f4f85;
  --dfap-muted: #718096;
  --dfap-bg: #ffffff;
}

The useful classes are .dfap-player (container), .dfap-play (main button), .dfap-progress (bar), .dfap-speed (speed button) and the .dfap-is-playing state.

Costs and best practices

• Start with the browser engine. It is free and lets you validate the feature’s appeal with your audience before any investment.
• Tune the character limit. Going from 3,000 to 1,200 characters halves your API bill and is more than enough for most descriptions.
• Read the short description only if your full descriptions are very dense or contain technical tables that do not translate well to speech.
• Warm up the cache by visiting your best sellers after switching engine: the first visitors will not have to wait for generation.

Troubleshooting

The player does not appear

Check that the module is enabled in its settings, that the display position matches a hook present in your theme, and that the product page contains at least twenty characters of readable text. Then clear the PrestaShop cache.

The button turns to an error state on click (server engines)

Use the Test API connection button: it displays the exact error message returned by the provider. The most common causes are an invalid or expired API key, an exceeded quota, a non-existent voice (notably a wrong ElevenLabs Voice ID) or a disabled cURL extension. Errors are also logged in Advanced Parameters > Logs, prefixed with dfaudioproduct.

Nothing happens with the browser engine

Some browsers require a user interaction before allowing speech synthesis — which is the case here, since playback starts on click. Then check that a voice is installed for the relevant language on the visitor’s system. On a Windows machine with no French voice pack, the browser may have no voice available; the module then falls back to the first compatible voice or stays silent. Finally, the Web Speech API requires an HTTPS connection on most browsers.

Cache write error

The var/dfaudioproduct/ folder must be writable by the PHP user. Check the permissions of the var/ folder and the available disk space.

Audio does not update after editing a product

Invalidation is automatic. If the old audio persists, it is the visitor’s browser cache: since the file is served with a one-day Cache-Control, a hard reload (Ctrl+F5) solves it. The new ETag then replaces the old one for everyone.

Uninstalling

Uninstalling removes the cache table, the admin tab, all settings and every generated MP3 file, including the var/dfaudioproduct/ folder. Nothing is left behind on the server.

Support

A question, a bug, a feature request? Contact the DataFirefly team from the site’s support page. Please mention your PrestaShop version, your PHP version, the engine in use and, if relevant, the content of the error log.