DF Audio Product: audioweergave van productfiches

Inleiding

DF Audio Product voegt een audiospeler toe aan elke productfiche van uw PrestaShop-winkel. Eén klik op « Beschrijving beluisteren » en de productnaam, de korte beschrijving en de lange beschrijving worden voorgelezen, op de snelheid die de bezoeker kiest.

De module werkt met vier spraaksynthesemotoren: die van de browser (gratis, zonder API-sleutel) en drie premium servermotoren (OpenAI, Google Cloud, ElevenLabs), waarvan de MP3-bestanden in cache worden gezet om de kosten te beheersen.

Vereisten

• PrestaShop 8.0 tot 9.x
• PHP 8.0 of hoger
• cURL-extensie ingeschakeld (alleen voor de servermotoren)
• Map var/ beschrijfbaar door PHP (alleen voor de servermotoren)
• Geen enkele Composer-afhankelijkheid

Installatie

1. Ga in de backoffice naar Modules > Modulebeheer.
2. Klik op Een module installeren en plaats het bestand dfaudioproduct-1.0.0.zip.
3. Klik na de installatie op Configureren.

Bij de installatie maakt de module automatisch de cachetabel aan, het beheertabblad onder Catalogus en de cachemap var/dfaudioproduct/ beschermd door een .htaccess-bestand, en registreert hij zich op de nodige hooks.

Een spraaksynthesemotor kiezen

Browsermotor (Web Speech API)

Dit is de standaardmotor. De stem wordt rechtstreeks op het toestel van de bezoeker door zijn browser gesynthetiseerd (Chrome, Edge, Safari, Firefox). Geen API-sleutel, geen kosten, geen gegevens naar een externe dienst en geen bestanden op uw server.

De module geeft de tekst van de fiche door aan de browser, die automatisch een stem kiest die bij de taal van de bezoeker past. De kwaliteit en het aanbod aan stemmen hangen dus af van het besturingssysteem van de bezoeker: zeer goed op macOS en iOS, behoorlijk op Windows en Android.

OpenAI TTS

Natuurlijke stemmen van hoge kwaliteit. Vul uw OpenAI-API-sleutel in, kies een model (tts-1 voor snelheid, tts-1-hd voor maximale kwaliteit, gpt-4o-mini-tts voor het beste compromis) en een stem uit: alloy, echo, fable, onyx, nova, shimmer. Is het veld Stem leeg, dan wordt alloy gebruikt.

Google Cloud Text-to-Speech

Vul een Google Cloud-API-sleutel in met de Text-to-Speech-API ingeschakeld. Het veld Stem is optioneel: laat het leeg en de module leidt de taalcode automatisch af uit de taal van de bezoeker (fr-FR, en-US, es-ES, de-DE, it-IT). Wilt u een bepaalde stem afdwingen, vul dan de volledige naam in, bijvoorbeeld fr-FR-Neural2-A; de taalcode wordt dan uit de naam van de stem afgeleid.

ElevenLabs

Vul uw ElevenLabs-API-sleutel in en, verplicht, de identificatie van de stem (Voice ID) in het veld Stem. Die vindt u in uw ElevenLabs-stemmenbibliotheek. De module gebruikt het meertalige model eleven_multilingual_v2, dat de vijf talen van nature aankan.

Configuratie

Inschakelen

Hoofdschakelaar. Staat die uit, dan verdwijnt de speler van de productfiches en antwoordt de controller voor audiogeneratie niet meer.

Standaard afspeelsnelheid

De snelheid die bij het eerste laden van de pagina geldt: 0,75×, 1×, 1,25×, 1,5× of 2×. De bezoeker kan daarna met de snelheidsknop van de speler door deze waarden bladeren.

Maximaal aantal tekens

Maximale lengte van de voorgelezen tekst, tussen 200 en 20 000 tekens (standaard 3 000). De tekst wordt netjes afgekapt aan het einde van de laatste volledige zin. Deze instelling heeft rechtstreeks invloed op de kosten van de servermotoren, die per teken factureren: een lage waarde drukt de factuur, een hoge waarde leest uw volledige beschrijvingen voor.

Korte en lange beschrijving voorlezen

Twee onafhankelijke schakelaars. De productnaam wordt altijd als eerste voorgelezen. U kunt alleen de korte beschrijving laten voorlezen (snel en zuinig) of het geheel.

Weergavepositie

• Onder het aankoopblok (hook displayProductAdditionalInfo): de aanbevolen positie, goed zichtbaar onder de prijs en de knop om aan de winkelwagen toe te voegen.
• Bij de productacties (hook displayProductActions): meer geïntegreerd in de knoppen van het thema.

De module is op beide hooks geregistreerd, maar toont de speler alleen op de gekozen hook: van positie wisselen vergt dus geen enkele ingreep in de modulepositionering.

Levensduur van de cache (dagen)

0 = de audiobestanden verlopen nooit (aanbevolen). Bij een hogere waarde worden bestanden die ouder zijn dan N dagen bij de volgende generatie automatisch verwijderd. Handig als u regelmatig van stem of motor wisselt.

Werking van de cache

De cache geldt alleen voor de servermotoren; de browsermotor maakt geen enkel bestand aan.

1. Een bezoeker klikt voor het eerst op « Beschrijving beluisteren ».
2. De module haalt de tekst van de fiche aan serverzijde op, ontdoet die van HTML en kapt hem af volgens uw tekenlimiet.
3. Hij berekent een unieke vingerafdruk op basis van de motor, het model, de stem, de taal, de winkel en de tekst zelf.
4. Is er geen overeenkomstig bestand, dan roept hij de API van de motor aan, ontvangt hij de MP3 en schrijft hij die naar var/dfaudioproduct/.
5. Het bestand wordt geleverd met een ETag-header en een Cache-Control van één dag. Volgende bezoekers krijgen het bestand uit de cache, en herladen van de pagina geeft een 304-antwoord zonder de audio opnieuw te versturen.

Belangrijk gevolg: u betaalt hoogstens één generatie per product en per taal, niet één per bezoek. Uw kosten hangen af van de omvang van uw catalogus, nooit van uw verkeer.

De afspeelsnelheid zit niet in de vingerafdruk: die past de browser toe op het bestaande bestand. Eén MP3 dekt dus alle vijf de snelheden.

Automatische invalidatie

De audiocache van een product wordt automatisch geleegd, in alle talen en alle winkels, zodra dat product wordt gewijzigd of verwijderd, via de hooks actionObjectProductUpdateAfter en actionObjectProductDeleteAfter. De nieuwe audio wordt bij de volgende beluistering aangemaakt, met de bijgewerkte inhoud. Na een correctie aan een beschrijving is geen enkele handmatige actie nodig.

Locatie van de bestanden

De MP3’s staan in var/dfaudioproduct/, in de root van PrestaShop en bewust buiten de map van de module: een update van de module vernietigt de cache dus niet. De map is beschermd met een .htaccess-bestand en een index.php: de bestanden zijn alleen via de controller van de module bereikbaar, nooit rechtstreeks.

Cachebeheer in de backoffice

De configuratiepagina toont bovenaan een statistiekenpaneel: aantal bestanden in cache, ingenomen schijfruimte en totaal aantal beluisteringen.

De knop De bestanden in cache doorbladeren opent het tabblad Catalogus > DF Audio Product, dat elk bestand toont met de product-ID, de naam, de taal, de motor, de stem, de grootte, het aantal beluisteringen en de aanmaakdatum. U kunt één bestand, een selectie of via de knop Alles leegmaken in de werkbalk alles verwijderen.

De knop De audiocache leegmaken op de configuratiepagina heeft hetzelfde effect: hij verwijdert de bestanden van de schijf en leegt de tabel. De audio wordt eenvoudigweg op aanvraag opnieuw aangemaakt.

De speler aan winkelzijde

De speler bestaat uit een knop « Beschrijving beluisteren », een voortgangsbalk, een tijdteller en een snelheidsknop.

• Servermotoren: de voortgangsbalk is aanklikbaar om door de audio te navigeren, en de teller toont de verstreken tijd en de totale duur.
• Browsermotor: de voortgangsbalk is indicatief (die vordert woord voor woord) en de teller is verborgen, omdat de Web Speech API geen duur doorgeeft.

De snelheid wijzigen tijdens het afspelen werkt in beide gevallen. Bij de browsermotor kan de synthese de snelheid niet in vlucht wijzigen, dus start de module die stilletjes opnieuw vanaf het laatst uitgesproken woord: de hervatting is niet merkbaar. Een keep-alivemechanisme omzeilt bovendien het afbreken van lange syntheses na een vijftiental seconden in Chromium-browsers.

De speler stelt zichzelf automatisch opnieuw in bij een AJAX-wissel van variant, door te luisteren naar de gebeurtenis updatedProduct van het thema.

Toegankelijkheid

De speler is ontworpen om voor iedereen bruikbaar te zijn, in de geest van de Europese richtlijn over toegankelijkheid (European Accessibility Act):

• Afspeelknop met een aria-pressed-status die het afspelen weerspiegelt
• aria-live-zone die het laden, het afspelen of een fout aan schermlezers meldt
• Volledige bediening met het toetsenbord, met zichtbare focusring
• Voortgangsbalk met label, bedienbaar met het toetsenbord
• Respect voor de systeemvoorkeur prefers-reduced-motion (tragere laadanimatie)
• Ruime aanraakzones en een opmaak die op kleine schermen werkt

Het voorlezen van de productinhoud is een concreet antwoord op de toegankelijkheidseisen. De algemene conformiteit van uw winkel hangt niettemin af van al uw pagina’s: thema, bestelproces en redactionele inhoud.

Meertaligheid en multistore

De tekst wordt in de taal van de bezoeker opgehaald: elke taal levert dus een eigen audiobestand op, met de passende stem. In multistore is de cache ook per winkel gescheiden, wat verschillende beschrijvingen per winkel mogelijk maakt.

De opschriften van de speler (« Beschrijving beluisteren », « Pauze », « Hervatten », « Laden… ») zijn vertaalbaar via Internationaal > Vertalingen > Vertalingen van de modules.

De stijl aanpassen

De speler gebruikt CSS-variabelen die u vanuit de stylesheet van uw childthema kunt overschrijven, zonder de module te wijzigen:

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

De nuttige klassen zijn .dfap-player (container), .dfap-play (hoofdknop), .dfap-progress (balk), .dfap-speed (snelheidsknop) en de status .dfap-is-playing.

Kosten en goede praktijken

• Begin met de browsermotor. Die is gratis en laat u toe het nut van de functie bij uw publiek te toetsen vóór enige investering.
• Stel de tekenlimiet bij. Van 3 000 naar 1 200 tekens gaan halveert uw API-factuur en volstaat ruimschoots voor de meeste beschrijvingen.
• Lees alleen de korte beschrijving voor als uw lange beschrijvingen erg dicht zijn of technische tabellen bevatten die zich slecht laten voorlezen.
• Verwarm de cache voor door na een wissel van motor uw bestsellers te bezoeken: de eerste bezoekers hoeven dan niet op de generatie te wachten.

Problemen oplossen

De speler verschijnt niet

Controleer of de module in zijn configuratie is ingeschakeld, of de weergavepositie overeenkomt met een hook die in uw thema aanwezig is, en of de fiche minstens twintig tekens leesbare tekst bevat. Leeg daarna de PrestaShop-cache.

De knop geeft een fout bij het klikken (servermotoren)

Gebruik de knop De API-verbinding testen: die toont de exacte foutmelding van de aanbieder. De meest voorkomende oorzaken zijn een ongeldige of verlopen API-sleutel, een overschreden quotum, een onbestaande stem (met name een verkeerde ElevenLabs Voice ID) of een uitgeschakelde cURL-extensie. De fouten worden ook vastgelegd in Geavanceerde parameters > Logboeken, met het voorvoegsel dfaudioproduct.

Er gebeurt niets met de browsermotor

Sommige browsers vragen een interactie van de gebruiker voordat ze spraaksynthese toelaten; dat is hier het geval, want het afspelen begint bij de klik. Controleer daarna of er op het systeem van de bezoeker een stem voor de betrokken taal is geïnstalleerd. Op een Windows-machine zonder Nederlands spraakpakket kan de browser geen enkele stem beschikbaar hebben; de module valt dan terug op de eerste geschikte stem of blijft stil. Tot slot vereist de Web Speech API in de meeste browsers een HTTPS-verbinding.

Schrijffout bij de cache

De map var/dfaudioproduct/ moet beschrijfbaar zijn voor de PHP-gebruiker. Controleer de rechten op de map var/ en de beschikbare schijfruimte.

De audio wordt niet bijgewerkt na een productwijziging

De invalidatie gebeurt automatisch. Blijft de oude audio toch hangen, dan gaat het om de browsercache van de bezoeker: omdat het bestand met een Cache-Control van één dag wordt geleverd, lost een geforceerde herlading (Ctrl+F5) dat op. De nieuwe ETag vervangt daarna de oude voor iedereen.

Verwijderen

Bij het verwijderen worden de cachetabel, het beheertabblad, alle instellingen en alle gegenereerde MP3-bestanden gewist, de map var/dfaudioproduct/ inbegrepen. Er blijft niets achter op de server.

Ondersteuning

Een vraag, een bug of een verzoek tot uitbreiding? Neem contact op met het DataFirefly-team via de supportpagina van de site. Vermeld uw PrestaShop-versie, uw PHP-versie, de gebruikte motor en, indien van toepassing, de inhoud van het foutenlogboek.