DF Audio Product — Lectura en audio de fichas de producto
Instalar y configurar la lectura en audio (TTS) de las fichas de producto: motores, caché MP3, accesibilidad, resolución de problemas.
Introducción
DF Audio Product añade un reproductor de audio a cada ficha de producto de su tienda PrestaShop. Un clic en «Escuchar la descripción» y el nombre del producto, su descripción corta y su descripción larga se leen en voz alta, a la velocidad elegida por el visitante.
El módulo funciona con cuatro motores de síntesis vocal: el motor del navegador (gratuito, sin clave API) y tres motores de servidor premium (OpenAI, Google Cloud, ElevenLabs) cuyos archivos MP3 se almacenan en caché para controlar los costes.
Requisitos
- PrestaShop 8.0 a 9.x
- PHP 8.0 o superior
- Extensión cURL activada (solo para los motores de servidor)
- Carpeta
var/con permisos de escritura para PHP (solo para los motores de servidor) - Ninguna dependencia de Composer
Instalación
- En el back office, vaya a Módulos > Gestor de módulos.
- Haga clic en Subir un módulo y suelte el archivo
dfaudioproduct-1.0.0.zip. - Haga clic en Configurar una vez finalizada la instalación.
Al instalarse, el módulo crea automáticamente la tabla de caché, la pestaña de administración bajo Catálogo, la carpeta de caché var/dfaudioproduct/ protegida por un archivo .htaccess, y se registra en los hooks necesarios.
Inicio inmediato: con el motor del navegador activado por defecto, el reproductor funciona nada más instalarse, sin configuración ni clave API.
Elegir un motor de síntesis vocal
Motor del navegador (Web Speech API)
Es el motor por defecto. La voz se sintetiza directamente en el dispositivo del visitante mediante su navegador (Chrome, Edge, Safari, Firefox). Sin clave API, sin coste, sin datos enviados a terceros y sin archivos almacenados en su servidor.
El módulo transmite el texto de la ficha al navegador, que elige automáticamente una voz acorde con el idioma del visitante. La calidad y el catálogo de voces dependen, por tanto, del sistema operativo del visitante: excelentes en macOS e iOS, correctos en Windows y Android.
OpenAI TTS
Voces naturales de alta calidad. Introduzca su clave API de OpenAI, elija un modelo (tts-1 por rapidez, tts-1-hd por máxima calidad, gpt-4o-mini-tts por el mejor equilibrio) y una voz entre: alloy, echo, fable, onyx, nova, shimmer. Si el campo Voz está vacío, se usa alloy.
Google Cloud Text-to-Speech
Introduzca una clave API de Google Cloud con la API Text-to-Speech activada. El campo Voz es opcional: déjelo vacío y el módulo deducirá automáticamente el código de idioma a partir del idioma del visitante (fr-FR, en-US, es-ES, de-DE, it-IT). Para forzar una voz concreta, escriba su nombre completo, por ejemplo es-ES-Neural2-A — el código de idioma se deduce entonces del nombre de la voz.
ElevenLabs
Introduzca su clave API de ElevenLabs y, obligatoriamente, el identificador de la voz (Voice ID) en el campo Voz. Lo encontrará en su biblioteca de voces de ElevenLabs. El módulo usa el modelo multilingüe eleven_multilingual_v2, que gestiona de forma nativa los cinco idiomas.
Probar antes de publicar: el botón Probar la conexión API al final de la página de configuración sintetiza una frase corta y muestra el tamaño del archivo obtenido. No guarda nada en caché. Si la clave no es válida o la voz es desconocida, se muestra directamente el mensaje de error devuelto por la API.
Configuración
Activar
Interruptor global. Desactivado, el reproductor desaparece de las fichas de producto y el controlador de generación de audio deja de responder.
Velocidad de reproducción por defecto
Velocidad aplicada en la primera carga de la página: 0,75x, 1x, 1,25x, 1,5x o 2x. El visitante puede después alternar entre estos valores con el botón de velocidad del reproductor.
Número máximo de caracteres
Longitud máxima del texto leído, entre 200 y 20 000 caracteres (3 000 por defecto). El texto se corta limpiamente al final de la última frase completa. Este ajuste influye directamente en el coste de los motores de servidor, que facturan por carácter: un valor bajo reduce la factura, un valor alto lee sus descripciones íntegras.
Leer la descripción corta / la descripción larga
Dos interruptores independientes. El nombre del producto siempre se lee primero. Puede leer solo la descripción corta (rápido, económico) o el conjunto.
Posición de visualización
- Bajo el bloque de compra (hook
displayProductAdditionalInfo) — posición recomendada, bien visible bajo el precio y el botón de añadir al carrito. - En las acciones del producto (hook
displayProductActions) — más integrado con los botones del tema.
El módulo está registrado en ambos hooks, pero solo muestra el reproductor en el seleccionado: cambiar de posición no requiere ninguna manipulación en el posicionamiento de módulos.
Duración de la caché (días)
0 = los archivos de audio nunca caducan (recomendado). Un valor superior elimina automáticamente los archivos generados hace más de N días, en la siguiente generación. Útil si cambia de voz o de motor con frecuencia.
Funcionamiento de la caché
La caché solo afecta a los motores de servidor; el motor del navegador no genera ningún archivo.
- Un visitante hace clic en «Escuchar la descripción» por primera vez.
- El módulo extrae el texto de la ficha en el servidor, lo limpia de HTML y lo trunca según su límite de caracteres.
- Calcula una huella única a partir del motor, el modelo, la voz, el idioma, la tienda y el propio texto.
- Si no hay ningún archivo coincidente, llama a la API del motor, recibe el MP3 y lo escribe en
var/dfaudioproduct/. - El archivo se sirve con una cabecera ETag y un Cache-Control de un día. Los visitantes siguientes reciben el archivo en caché, y las recargas de página devuelven una respuesta 304 sin retransmitir el audio.
Consecuencia importante: paga como máximo una generación por producto e idioma, no una por visita. Su coste depende del tamaño de su catálogo, nunca de su tráfico.
La velocidad de reproducción no forma parte de la huella: la aplica el navegador sobre el archivo existente. Un solo MP3 cubre, por tanto, las cinco velocidades.
Invalidación automática
La caché de audio de un producto se purga automáticamente — en todos los idiomas y todas las tiendas — en cuanto ese producto se modifica o elimina, mediante los hooks actionObjectProductUpdateAfter y actionObjectProductDeleteAfter. El nuevo audio se genera en la siguiente escucha, con el contenido actualizado. No hace falta ninguna acción manual tras corregir una descripción.
Ubicación de los archivos
Los MP3 se almacenan en var/dfaudioproduct/, en la raíz de PrestaShop, deliberadamente fuera de la carpeta del módulo: una actualización del módulo no destruye la caché. La carpeta está protegida por un archivo .htaccess y un index.php: los archivos solo son accesibles a través del controlador del módulo, nunca por acceso directo.
Gestión de la caché en el back office
La página de configuración muestra arriba un panel de estadísticas: número de archivos en caché, espacio en disco ocupado y número total de reproducciones.
El botón Explorar los archivos en caché abre la pestaña Catálogo > DF Audio Product, que lista cada archivo con el identificador del producto, su nombre, el idioma, el motor, la voz, el tamaño, el número de reproducciones y la fecha de generación. Puede eliminar un archivo, una selección de archivos, o purgarlo todo con el botón Purgar todo de la barra de herramientas.
El botón Purgar la caché de audio de la página de configuración tiene el mismo efecto: elimina los archivos del disco y vacía la tabla. Los audios simplemente se regenerarán bajo demanda.
Tras cambiar de motor o de voz: los archivos antiguos ya no se usan (la huella ha cambiado) pero permanecen en el disco hasta que caduque la duración de la caché o se purgue manualmente. Recuerde purgar la caché para liberar espacio.
El reproductor en la tienda
El reproductor se compone de un botón «Escuchar la descripción», una barra de progreso, un contador de tiempo y un botón de velocidad.
- Motores de servidor: la barra de progreso permite desplazarse por el audio, y el contador muestra el tiempo transcurrido y la duración total.
- Motor del navegador: la barra de progreso es indicativa (avanza palabra a palabra) y el contador queda oculto, ya que la Web Speech API no proporciona duración.
El cambio de velocidad durante la reproducción se gestiona en ambos casos. Con el motor del navegador, al no poder la síntesis cambiar de velocidad sobre la marcha, el módulo la reinicia en silencio desde la última palabra pronunciada — la reanudación es imperceptible. Un mecanismo de mantenimiento evita además el corte de las síntesis largas tras unos quince segundos en los navegadores Chromium.
El reproductor se reinicializa automáticamente al cambiar de combinación por AJAX, escuchando el evento updatedProduct del tema.
Accesibilidad
El reproductor está diseñado para que todos puedan usarlo, en el espíritu de la directiva europea de accesibilidad (European Accessibility Act):
- Botón de reproducción con estado
aria-pressedque refleja la reproducción en curso - Zona de anuncio
aria-livepara señalar la carga, la reproducción o un error a los lectores de pantalla - Navegación y activación totalmente por teclado, con anillo de foco visible
- Barra de progreso etiquetada y manejable por teclado
- Respeto de la preferencia del sistema
prefers-reduced-motion(animación de carga ralentizada) - Zonas táctiles amplias y diseño adaptado a pantallas pequeñas
La lectura en audio del contenido del producto es una respuesta concreta a los requisitos de accesibilidad. La conformidad global de su tienda depende, no obstante, del conjunto de sus páginas: tema, proceso de compra, contenidos editoriales.
Multiidioma y multitienda
El texto se extrae en el idioma del visitante: cada idioma produce, por tanto, su propio archivo de audio, con la voz adecuada. En multitienda, la caché también se separa por tienda, lo que permite descripciones distintas de una tienda a otra.
Las etiquetas de la interfaz del reproductor («Escuchar la descripción», «Pausa», «Reanudar», «Cargando…») son traducibles desde Internacional > Traducciones > Traducciones de los módulos.
Personalización del estilo
El reproductor usa variables CSS que puede sobrescribir desde la hoja de estilos de su tema hijo, sin modificar el módulo:
.dfap-player {
--dfap-accent: #2b6cb0;
--dfap-accent-hover: #1f4f85;
--dfap-muted: #718096;
--dfap-bg: #ffffff;
}Las clases útiles son .dfap-player (contenedor), .dfap-play (botón principal), .dfap-progress (barra), .dfap-speed (botón de velocidad) y el estado .dfap-is-playing.
Costes y buenas prácticas
- Empiece por el motor del navegador. Es gratuito y permite validar el interés de la funcionalidad en su audiencia antes de cualquier inversión.
- Ajuste el límite de caracteres. Pasar de 3 000 a 1 200 caracteres reduce a la mitad su factura de API y basta de sobra para la mayoría de descripciones.
- Lea solo la descripción corta si sus descripciones largas son muy densas o contienen tablas técnicas poco adecuadas para el audio.
- Precaliente la caché visitando sus productos más vendidos tras cambiar de motor: los primeros visitantes no tendrán que esperar a la generación.
Resolución de problemas
El reproductor no aparece
Compruebe que el módulo está activado en su configuración, que la posición de visualización corresponde a un hook presente en su tema, y que la ficha contiene al menos veinte caracteres de texto legible. Vacíe después la caché de PrestaShop.
El botón muestra un error al hacer clic (motores de servidor)
Use el botón Probar la conexión API: muestra el mensaje de error exacto devuelto por el proveedor. Las causas más frecuentes son una clave API no válida o caducada, una cuota superada, una voz inexistente (en particular un Voice ID de ElevenLabs erróneo) o la extensión cURL desactivada. Los errores también se registran en Parámetros avanzados > Registros, con el prefijo dfaudioproduct.
No pasa nada con el motor del navegador
Algunos navegadores exigen una interacción del usuario antes de permitir la síntesis vocal — es el caso aquí, la reproducción empieza al hacer clic. Compruebe después que hay una voz instalada para el idioma en cuestión en el sistema del visitante. En un equipo Windows sin paquete de voz en español, el navegador puede no tener ninguna voz disponible; el módulo recurre entonces a la primera voz compatible o permanece en silencio. Por último, la Web Speech API exige una conexión HTTPS en la mayoría de navegadores.
Error de escritura de la caché
La carpeta var/dfaudioproduct/ debe tener permisos de escritura para el usuario PHP. Compruebe los permisos de la carpeta var/ y el espacio en disco disponible.
El audio no se actualiza tras modificar un producto
La invalidación es automática. Si el audio antiguo persiste, se trata de la caché del navegador del visitante: como el archivo se sirve con un Cache-Control de un día, una recarga forzada (Ctrl+F5) lo resuelve. El nuevo ETag reemplaza después al antiguo para todos.
Desinstalación
La desinstalación elimina la tabla de caché, la pestaña de administración, todos los ajustes y la totalidad de los archivos MP3 generados, incluida la carpeta var/dfaudioproduct/. No queda ningún residuo en el servidor.
Soporte
¿Una duda, un error, una petición de mejora? Contacte con el equipo de DataFirefly desde la página de soporte del sitio. Indique su versión de PrestaShop, su versión de PHP, el motor utilizado y, si procede, el contenido del registro de errores.