DF Audio Product — Lecture audio des fiches produit

Introduction

DF Audio Product ajoute un lecteur audio sur chaque fiche produit de votre boutique PrestaShop. Un clic sur « Écouter la description » et le nom du produit, sa description courte et sa description longue sont lus à voix haute, à la vitesse choisie par le visiteur.

Le module fonctionne avec quatre moteurs de synthèse vocale : le moteur du navigateur (gratuit, sans clé API) et trois moteurs serveur premium (OpenAI, Google Cloud, ElevenLabs) dont les fichiers MP3 sont mis en cache pour maîtriser les coûts.

Prérequis

• PrestaShop 8.0 à 9.x
• PHP 8.0 ou supérieur
• Extension cURL activée (uniquement pour les moteurs serveur)
• Dossier var/ accessible en écriture par PHP (uniquement pour les moteurs serveur)
• Aucune dépendance Composer

Installation

1. Dans le back-office, allez dans Modules > Gestionnaire de modules.
2. Cliquez sur Installer un module et déposez le fichier dfaudioproduct-1.0.0.zip.
3. Cliquez sur Configurer une fois l’installation terminée.

À l’installation, le module crée automatiquement la table de cache, l’onglet d’administration sous Catalogue, le dossier de cache var/dfaudioproduct/ protégé par un fichier .htaccess, et s’enregistre sur les hooks nécessaires.

Choisir un moteur de synthèse vocale

Moteur navigateur (Web Speech API)

C’est le moteur par défaut. La voix est synthétisée directement sur l’appareil du visiteur par son navigateur (Chrome, Edge, Safari, Firefox). Aucune clé API, aucun coût, aucune donnée envoyée à un service tiers, et aucun fichier stocké sur votre serveur.

Le module transmet le texte de la fiche au navigateur, qui choisit automatiquement une voix correspondant à la langue du visiteur. La qualité et le catalogue de voix dépendent donc du système d’exploitation du visiteur : très bons sur macOS et iOS, corrects sur Windows et Android.

OpenAI TTS

Voix naturelles de haute qualité. Renseignez votre clé API OpenAI, choisissez un modèle (tts-1 pour la rapidité, tts-1-hd pour la qualité maximale, gpt-4o-mini-tts pour le meilleur compromis) et une voix parmi : alloy, echo, fable, onyx, nova, shimmer. Si le champ Voix est vide, alloy est utilisée.

Google Cloud Text-to-Speech

Renseignez une clé API Google Cloud avec l’API Text-to-Speech activée. Le champ Voix est optionnel : laissez-le vide et le module déduit automatiquement le code langue depuis la langue du visiteur (fr-FR, en-US, es-ES, de-DE, it-IT). Pour forcer une voix précise, saisissez son nom complet, par exemple fr-FR-Neural2-A — le code langue est alors déduit du nom de la voix.

ElevenLabs

Renseignez votre clé API ElevenLabs et, obligatoirement, l’identifiant de la voix (Voice ID) dans le champ Voix. Vous le trouverez dans votre bibliothèque de voix ElevenLabs. Le module utilise le modèle multilingue eleven_multilingual_v2, qui gère nativement les cinq langues.

Configuration

Activer

Interrupteur global. Désactivé, le lecteur disparaît des fiches produit et le contrôleur de génération audio ne répond plus.

Vitesse de lecture par défaut

Vitesse appliquée au premier chargement de la page : 0,75×, 1×, 1,25×, 1,5× ou 2×. Le visiteur peut ensuite cycler entre ces valeurs avec le bouton de vitesse du lecteur.

Nombre maximum de caractères

Longueur maximale du texte lu, entre 200 et 20 000 caractères (3 000 par défaut). Le texte est coupé proprement à la fin de la dernière phrase complète. Ce réglage a un impact direct sur le coût des moteurs serveur, facturés au caractère : une valeur basse réduit la facture, une valeur haute lit l’intégralité de vos descriptions.

Lire la description courte / la description longue

Deux interrupteurs indépendants. Le nom du produit est toujours lu en premier. Vous pouvez ne lire que la description courte (rapide, économique) ou l’ensemble.

Position d’affichage

• Sous le bloc d’achat (hook displayProductAdditionalInfo) — position recommandée, bien visible sous le prix et le bouton d’ajout au panier.
• Dans les actions produit (hook displayProductActions) — plus intégré aux boutons du thème.

Le module est enregistré sur les deux hooks, mais n’affiche le lecteur que sur celui sélectionné : changer de position ne demande aucune manipulation dans le positionnement des modules.

Durée de vie du cache (jours)

0 = les fichiers audio ne périment jamais (recommandé). Une valeur supérieure supprime automatiquement les fichiers générés depuis plus de N jours, lors de la prochaine génération. Utile si vous changez régulièrement de voix ou de moteur.

Fonctionnement du cache

Le cache ne concerne que les moteurs serveur ; le moteur navigateur ne génère aucun fichier.

1. Un visiteur clique sur « Écouter la description » pour la première fois.
2. Le module extrait le texte de la fiche côté serveur, le nettoie du HTML et le tronque selon votre limite de caractères.
3. Il calcule une empreinte unique à partir du moteur, du modèle, de la voix, de la langue, de la boutique et du texte lui-même.
4. Si aucun fichier ne correspond, il appelle l’API du moteur, reçoit le MP3 et l’écrit dans var/dfaudioproduct/.
5. Le fichier est servi avec un en-tête ETag et un Cache-Control d’un jour. Les visiteurs suivants reçoivent le fichier en cache, et les rechargements de page renvoient une réponse 304 sans retransférer l’audio.

Conséquence importante : vous payez au maximum une génération par produit et par langue, pas une par visite. Votre coût dépend de la taille de votre catalogue, jamais de votre trafic.

La vitesse de lecture n’entre pas dans l’empreinte : elle est appliquée par le navigateur sur le fichier existant. Un seul MP3 couvre donc les cinq vitesses.

Invalidation automatique

Le cache audio d’un produit est purgé automatiquement — dans toutes les langues et toutes les boutiques — dès que ce produit est modifié ou supprimé, via les hooks actionObjectProductUpdateAfter et actionObjectProductDeleteAfter. Le nouvel audio est généré à la prochaine écoute, avec le contenu à jour. Aucune action manuelle n’est nécessaire après une correction de description.

Emplacement des fichiers

Les MP3 sont stockés dans var/dfaudioproduct/, à la racine de PrestaShop, volontairement en dehors du dossier du module : une mise à jour du module ne détruit donc pas le cache. Le dossier est protégé par un fichier .htaccess et un index.php : les fichiers ne sont accessibles qu’à travers le contrôleur du module, jamais en accès direct.

Gestion du cache dans le back-office

La page de configuration affiche en haut un panneau de statistiques : nombre de fichiers en cache, espace disque occupé et nombre total de lectures.

Le bouton Parcourir les fichiers en cache ouvre l’onglet Catalogue > DF Audio Product, qui liste chaque fichier avec l’identifiant du produit, son nom, la langue, le moteur, la voix, la taille, le nombre de lectures et la date de génération. Vous pouvez supprimer un fichier, une sélection de fichiers, ou tout purger via le bouton Tout purger de la barre d’outils.

Le bouton Purger le cache audio de la page de configuration a le même effet : il supprime les fichiers du disque et vide la table. Les audios seront simplement régénérés à la demande.

Le lecteur côté boutique

Le lecteur se compose d’un bouton « Écouter la description », d’une barre de progression, d’un compteur de temps et d’un bouton de vitesse.

• Moteurs serveur : la barre de progression est cliquable pour se déplacer dans l’audio, et le compteur affiche le temps écoulé et la durée totale.
• Moteur navigateur : la barre de progression est indicative (elle avance mot par mot) et le compteur est masqué, la Web Speech API ne fournissant pas de durée.

Le changement de vitesse en cours de lecture est géré dans les deux cas. Avec le moteur navigateur, la synthèse ne pouvant pas changer de vitesse à la volée, le module la relance silencieusement depuis le dernier mot prononcé — la reprise est imperceptible. Un mécanisme de maintien en vie contourne également la coupure des synthèses longues après une quinzaine de secondes sur les navigateurs Chromium.

Le lecteur se réinitialise automatiquement lors d’un changement de déclinaison en AJAX, en écoutant l’événement updatedProduct du thème.

Accessibilité

Le lecteur est conçu pour être utilisable par tous, dans l’esprit de la directive européenne sur l’accessibilité (European Accessibility Act) :

• Bouton de lecture avec état aria-pressed reflétant la lecture en cours
• Zone d’annonce aria-live pour signaler le chargement, la lecture ou une erreur aux lecteurs d’écran
• Navigation et activation entièrement au clavier, avec anneau de focus visible
• Barre de progression étiquetée et manipulable au clavier
• Respect de la préférence système prefers-reduced-motion (ralentissement de l’animation de chargement)
• Cibles tactiles généreuses et disposition adaptée aux petits écrans

La lecture audio du contenu produit constitue une réponse concrète aux exigences d’accessibilité. La conformité globale de votre boutique dépend toutefois de l’ensemble de vos pages — thème, tunnel de commande, contenus éditoriaux.

Multilingue et multiboutique

Le texte est extrait dans la langue du visiteur : chaque langue produit donc son propre fichier audio, avec la voix adaptée. En multiboutique, le cache est également séparé par boutique, ce qui permet des descriptions différentes d’une boutique à l’autre.

Les libellés de l’interface du lecteur (« Écouter la description », « Pause », « Reprendre », « Chargement… ») sont traduisibles depuis International > Traductions > Traductions des modules.

Personnalisation du style

Le lecteur utilise des variables CSS que vous pouvez surcharger depuis la feuille de style de votre thème enfant, sans modifier le module :

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

Les classes utiles sont .dfap-player (conteneur), .dfap-play (bouton principal), .dfap-progress (barre), .dfap-speed (bouton de vitesse) et l’état .dfap-is-playing.

Coûts et bonnes pratiques

• Commencez par le moteur navigateur. Il est gratuit et permet de valider l’intérêt de la fonctionnalité sur votre audience avant tout investissement.
• Ajustez la limite de caractères. Passer de 3 000 à 1 200 caractères divise votre facture API par deux et suffit largement pour la plupart des descriptions.
• Ne lisez que la description courte si vos descriptions longues sont très denses ou contiennent des tableaux techniques peu adaptés à l’oral.
• Préchauffez le cache en visitant vos meilleures ventes après un changement de moteur : les premiers visiteurs n’auront pas à attendre la génération.

Dépannage

Le lecteur ne s’affiche pas

Vérifiez que le module est activé dans sa configuration, que la position d’affichage correspond bien à un hook présent dans votre thème, et que la fiche contient au moins vingt caractères de texte lisible. Videz ensuite le cache PrestaShop.

Le bouton passe en erreur au clic (moteurs serveur)

Utilisez le bouton Tester la connexion API : il affiche le message d’erreur exact renvoyé par le fournisseur. Les causes les plus fréquentes sont une clé API invalide ou expirée, un quota dépassé, une voix inexistante (notamment un Voice ID ElevenLabs erroné) ou l’extension cURL désactivée. Les erreurs sont également tracées dans Paramètres avancés > Journaux, préfixées par dfaudioproduct.

Rien ne se passe avec le moteur navigateur

Certains navigateurs exigent une interaction de l’utilisateur avant d’autoriser la synthèse vocale — c’est le cas ici, la lecture démarre au clic. Vérifiez ensuite qu’une voix est installée pour la langue concernée sur le système du visiteur. Sur un poste Windows sans pack vocal français, le navigateur peut n’avoir aucune voix disponible ; le module bascule alors sur la première voix compatible ou reste silencieux. Enfin, la Web Speech API exige une connexion HTTPS sur la plupart des navigateurs.

Erreur d’écriture du cache

Le dossier var/dfaudioproduct/ doit être accessible en écriture par l’utilisateur PHP. Vérifiez les droits du dossier var/ et l’espace disque disponible.

L’audio ne se met pas à jour après modification d’un produit

L’invalidation est automatique. Si l’ancien audio persiste, il s’agit du cache navigateur du visiteur : le fichier étant servi avec un Cache-Control d’un jour, un rechargement forcé (Ctrl+F5) résout le cas. Le nouvel ETag remplace ensuite l’ancien pour tous.

Désinstallation

La désinstallation supprime la table de cache, l’onglet d’administration, tous les réglages et l’intégralité des fichiers MP3 générés, dossier var/dfaudioproduct/ compris. Aucun résidu n’est laissé sur le serveur.

Support

Une question, un bug, une demande d’évolution ? Contactez l’équipe DataFirefly depuis la page de support du site. Précisez votre version de PrestaShop, votre version de PHP, le moteur utilisé et, le cas échéant, le contenu du journal d’erreurs.