DF Audio Product — Produktseiten vorlesen lassen

Einführung

DF Audio Product fügt jeder Produktseite Ihres PrestaShop-Shops einen Audio-Player hinzu. Ein Klick auf „Beschreibung anhören“ und Produktname, Kurzbeschreibung sowie ausführliche Beschreibung werden vorgelesen — in der vom Besucher gewählten Geschwindigkeit.

Das Modul arbeitet mit vier Sprachsynthese-Engines: der Browser-Engine (kostenlos, ohne API-Schlüssel) und drei Premium-Server-Engines (OpenAI, Google Cloud, ElevenLabs), deren MP3-Dateien zwischengespeichert werden, um die Kosten zu begrenzen.

Voraussetzungen

• PrestaShop 8.0 bis 9.x
• PHP 8.0 oder höher
• Aktivierte cURL-Erweiterung (nur für die Server-Engines)
• Für PHP beschreibbarer Ordner var/ (nur für die Server-Engines)
• Keine Composer-Abhängigkeit

Installation

1. Gehen Sie im Back Office zu Module > Modul-Manager.
2. Klicken Sie auf Modul hochladen und legen Sie die Datei dfaudioproduct-1.0.0.zip ab.
3. Klicken Sie nach Abschluss der Installation auf Konfigurieren.

Bei der Installation legt das Modul automatisch die Cache-Tabelle an, den Verwaltungs-Tab unter Katalog, den Cache-Ordner var/dfaudioproduct/ geschützt durch eine .htaccess-Datei, und registriert die erforderlichen Hooks.

Sprachsynthese-Engine wählen

Browser-Engine (Web Speech API)

Dies ist die Standard-Engine. Die Stimme wird direkt auf dem Gerät des Besuchers vom Browser erzeugt (Chrome, Edge, Safari, Firefox). Kein API-Schlüssel, keine Kosten, keine Datenübertragung an Dritte und keine Datei auf Ihrem Server.

Das Modul übergibt den Produkttext an den Browser, der automatisch eine zur Sprache des Besuchers passende Stimme auswählt. Qualität und Stimmenauswahl hängen daher vom Betriebssystem des Besuchers ab: sehr gut unter macOS und iOS, ordentlich unter Windows und Android.

OpenAI TTS

Hochwertige natürliche Stimmen. Tragen Sie Ihren OpenAI-API-Schlüssel ein, wählen Sie ein Modell (tts-1 für Tempo, tts-1-hd für maximale Qualität, gpt-4o-mini-tts für den besten Kompromiss) und eine Stimme aus: alloy, echo, fable, onyx, nova, shimmer. Bleibt das Feld Stimme leer, wird alloy verwendet.

Google Cloud Text-to-Speech

Tragen Sie einen Google-Cloud-API-Schlüssel mit aktivierter Text-to-Speech-API ein. Das Feld Stimme ist optional: Lassen Sie es leer, leitet das Modul den Sprachcode automatisch aus der Sprache des Besuchers ab (fr-FR, en-US, es-ES, de-DE, it-IT). Um eine bestimmte Stimme zu erzwingen, geben Sie ihren vollständigen Namen ein, etwa de-DE-Neural2-B — der Sprachcode wird dann aus dem Stimmennamen abgeleitet.

ElevenLabs

Tragen Sie Ihren ElevenLabs-API-Schlüssel ein und zwingend die Stimmen-ID (Voice ID) im Feld Stimme. Sie finden sie in Ihrer ElevenLabs-Stimmenbibliothek. Das Modul verwendet das mehrsprachige Modell eleven_multilingual_v2, das alle fünf Sprachen nativ beherrscht.

Konfiguration

Aktivieren

Globaler Schalter. Deaktiviert verschwindet der Player von den Produktseiten und der Controller zur Audioerzeugung antwortet nicht mehr.

Standard-Wiedergabegeschwindigkeit

Geschwindigkeit beim ersten Laden der Seite: 0,75x, 1x, 1,25x, 1,5x oder 2x. Der Besucher kann anschließend mit dem Geschwindigkeits-Button des Players zwischen diesen Werten wechseln.

Maximale Zeichenanzahl

Maximale Länge des vorgelesenen Textes, zwischen 200 und 20 000 Zeichen (Standard: 3 000). Der Text wird sauber am Ende des letzten vollständigen Satzes gekürzt. Diese Einstellung wirkt sich direkt auf die Kosten der Server-Engines aus, die pro Zeichen abrechnen: Ein niedriger Wert senkt die Rechnung, ein hoher Wert liest Ihre Beschreibungen vollständig vor.

Kurzbeschreibung / Langbeschreibung vorlesen

Zwei unabhängige Schalter. Der Produktname wird immer zuerst vorgelesen. Sie können nur die Kurzbeschreibung vorlesen lassen (schnell, günstig) oder alles.

Anzeigeposition

• Unter dem Kaufblock (Hook displayProductAdditionalInfo) — empfohlene Position, gut sichtbar unter Preis und Warenkorb-Button.
• Bei den Produktaktionen (Hook displayProductActions) — stärker in die Buttons des Themes integriert.

Das Modul ist auf beiden Hooks registriert, zeigt den Player aber nur am ausgewählten an: Ein Positionswechsel erfordert keinerlei Eingriff in die Modulpositionierung.

Cache-Lebensdauer (Tage)

0 = Audiodateien verfallen nie (empfohlen). Ein höherer Wert löscht bei der nächsten Erzeugung automatisch Dateien, die älter als N Tage sind. Nützlich, wenn Sie Stimme oder Engine häufig wechseln.

Funktionsweise des Caches

Der Cache betrifft nur die Server-Engines; die Browser-Engine erzeugt keinerlei Dateien.

1. Ein Besucher klickt zum ersten Mal auf „Beschreibung anhören“.
2. Das Modul extrahiert den Text der Produktseite serverseitig, entfernt das HTML und kürzt ihn gemäß Ihrem Zeichenlimit.
3. Es berechnet einen eindeutigen Fingerabdruck aus Engine, Modell, Stimme, Sprache, Shop und dem Text selbst.
4. Passt keine Datei, ruft es die API der Engine auf, empfängt die MP3 und schreibt sie nach var/dfaudioproduct/.
5. Die Datei wird mit einem ETag-Header und einem Cache-Control von einem Tag ausgeliefert. Folgende Besucher erhalten die gecachte Datei, und Seiten-Reloads liefern eine 304-Antwort, ohne das Audio erneut zu übertragen.

Wichtige Konsequenz: Sie bezahlen höchstens eine Erzeugung pro Produkt und Sprache, nicht eine pro Besuch. Ihre Kosten hängen von der Größe Ihres Katalogs ab, niemals von Ihrem Traffic.

Die Wiedergabegeschwindigkeit fließt nicht in den Fingerabdruck ein: Sie wird vom Browser auf die vorhandene Datei angewendet. Eine einzige MP3 deckt daher alle fünf Geschwindigkeiten ab.

Automatische Invalidierung

Der Audio-Cache eines Produkts wird automatisch bereinigt — in allen Sprachen und allen Shops — sobald dieses Produkt geändert oder gelöscht wird, über die Hooks actionObjectProductUpdateAfter und actionObjectProductDeleteAfter. Das neue Audio wird beim nächsten Abspielen mit dem aktuellen Inhalt erzeugt. Nach einer Korrektur der Beschreibung ist kein manueller Eingriff nötig.

Speicherort der Dateien

Die MP3-Dateien liegen in var/dfaudioproduct/ im PrestaShop-Wurzelverzeichnis, bewusst außerhalb des Modulordners: Ein Modul-Update zerstört den Cache also nicht. Der Ordner ist durch eine .htaccess-Datei und eine index.php geschützt: Die Dateien sind ausschließlich über den Controller des Moduls erreichbar, niemals per Direktzugriff.

Cache-Verwaltung im Back Office

Die Konfigurationsseite zeigt oben ein Statistik-Panel: Anzahl der gecachten Dateien, belegter Speicherplatz und Gesamtzahl der Wiedergaben.

Der Button Gecachte Dateien durchsuchen öffnet den Tab Katalog > DF Audio Product, der jede Datei mit Produkt-ID, Produktname, Sprache, Engine, Stimme, Größe, Wiedergabezahl und Erzeugungsdatum auflistet. Sie können eine Datei, eine Auswahl von Dateien oder über den Toolbar-Button Alles bereinigen den gesamten Cache löschen.

Der Button Audio-Cache bereinigen auf der Konfigurationsseite hat dieselbe Wirkung: Er löscht die Dateien von der Festplatte und leert die Tabelle. Die Audiodateien werden anschließend einfach bei Bedarf neu erzeugt.

Der Player im Shop

Der Player besteht aus einem Button „Beschreibung anhören“, einem Fortschrittsbalken, einer Zeitanzeige und einem Geschwindigkeits-Button.

• Server-Engines: Der Fortschrittsbalken erlaubt das Springen im Audio, und die Zeitanzeige zeigt die verstrichene Zeit sowie die Gesamtdauer.
• Browser-Engine: Der Fortschrittsbalken ist orientierend (er wandert Wort für Wort) und die Zeitanzeige ist ausgeblendet, da die Web Speech API keine Dauer liefert.

Der Geschwindigkeitswechsel während der Wiedergabe wird in beiden Fällen unterstützt. Da die Sprachsynthese der Browser-Engine die Rate nicht während der Ausgabe ändern kann, startet das Modul sie unbemerkt beim zuletzt gesprochenen Wort neu — die Wiederaufnahme ist nicht wahrnehmbar. Ein Keep-Alive-Mechanismus umgeht zudem den Abbruch langer Ausgaben nach rund fünfzehn Sekunden in Chromium-Browsern.

Der Player initialisiert sich bei einem AJAX-Variantenwechsel automatisch neu, indem er auf das Event updatedProduct des Themes hört.

Barrierefreiheit

Der Player ist so gestaltet, dass ihn alle nutzen können — im Sinne des European Accessibility Act (in Deutschland umgesetzt durch das BFSG):

• Wiedergabe-Button mit aria-pressed-Zustand, der die laufende Wiedergabe abbildet
• aria-live-Bereich, der Laden, Wiedergabe oder Fehler an Screenreader meldet
• Vollständige Bedienung per Tastatur mit sichtbarem Fokusring
• Beschrifteter, per Tastatur bedienbarer Fortschrittsbalken
• Berücksichtigung der Systemeinstellung prefers-reduced-motion (verlangsamte Ladeanimation)
• Großzügige Touch-Flächen und ein für kleine Bildschirme angepasstes Layout

Die Audiowiedergabe der Produktinhalte ist eine konkrete Antwort auf die Anforderungen an Barrierefreiheit. Die Gesamtkonformität Ihres Shops hängt jedoch von allen Seiten ab — Theme, Bestellprozess, redaktionelle Inhalte.

Mehrsprachig und Multishop

Der Text wird in der Sprache des Besuchers extrahiert: Jede Sprache erzeugt somit ihre eigene Audiodatei mit der passenden Stimme. Im Multishop-Betrieb ist der Cache zusätzlich pro Shop getrennt, was unterschiedliche Beschreibungen je Shop erlaubt.

Die Beschriftungen des Players („Beschreibung anhören“, „Pause“, „Fortsetzen“, „Wird geladen…“) sind über Internationales > Übersetzungen > Modulübersetzungen übersetzbar.

Gestaltung anpassen

Der Player nutzt CSS-Variablen, die Sie im Stylesheet Ihres Child-Themes überschreiben können, ohne das Modul zu verändern:

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

Die nützlichen Klassen sind .dfap-player (Container), .dfap-play (Hauptbutton), .dfap-progress (Balken), .dfap-speed (Geschwindigkeits-Button) und der Zustand .dfap-is-playing.

Kosten und Empfehlungen

• Beginnen Sie mit der Browser-Engine. Sie ist kostenlos und erlaubt es, das Interesse Ihrer Zielgruppe an der Funktion zu prüfen, bevor Sie investieren.
• Justieren Sie das Zeichenlimit. Von 3 000 auf 1 200 Zeichen halbiert Ihre API-Rechnung und reicht für die meisten Beschreibungen völlig aus.
• Lesen Sie nur die Kurzbeschreibung vor, wenn Ihre Langbeschreibungen sehr dicht sind oder technische Tabellen enthalten, die sich schlecht vorlesen lassen.
• Wärmen Sie den Cache vor, indem Sie nach einem Engine-Wechsel Ihre Bestseller aufrufen: Die ersten Besucher müssen dann nicht auf die Erzeugung warten.

Fehlerbehebung

Der Player erscheint nicht

Prüfen Sie, ob das Modul in seiner Konfiguration aktiviert ist, ob die Anzeigeposition einem in Ihrem Theme vorhandenen Hook entspricht und ob die Produktseite mindestens zwanzig Zeichen lesbaren Text enthält. Leeren Sie anschließend den PrestaShop-Cache.

Der Button wechselt beim Klick in den Fehlerzustand (Server-Engines)

Nutzen Sie den Button API-Verbindung testen: Er zeigt die exakte Fehlermeldung des Anbieters an. Häufigste Ursachen sind ein ungültiger oder abgelaufener API-Schlüssel, ein überschrittenes Kontingent, eine nicht existierende Stimme (insbesondere eine falsche ElevenLabs Voice ID) oder eine deaktivierte cURL-Erweiterung. Fehler werden zudem unter Erweiterte Einstellungen > Protokolle mit dem Präfix dfaudioproduct protokolliert.

Mit der Browser-Engine passiert nichts

Manche Browser verlangen vor der Sprachsynthese eine Nutzerinteraktion — die hier gegeben ist, da die Wiedergabe per Klick startet. Prüfen Sie anschließend, ob auf dem System des Besuchers eine Stimme für die betreffende Sprache installiert ist. Auf einem Windows-Rechner ohne deutsches Sprachpaket kann dem Browser jede Stimme fehlen; das Modul weicht dann auf die erste kompatible Stimme aus oder bleibt stumm. Schließlich verlangt die Web Speech API in den meisten Browsern eine HTTPS-Verbindung.

Fehler beim Schreiben des Caches

Der Ordner var/dfaudioproduct/ muss für den PHP-Benutzer beschreibbar sein. Prüfen Sie die Rechte des Ordners var/ und den verfügbaren Speicherplatz.

Das Audio aktualisiert sich nach einer Produktänderung nicht

Die Invalidierung erfolgt automatisch. Bleibt das alte Audio bestehen, handelt es sich um den Browser-Cache des Besuchers: Da die Datei mit einem Cache-Control von einem Tag ausgeliefert wird, löst ein erzwungener Reload (Strg+F5) den Fall. Der neue ETag ersetzt anschließend den alten für alle.

Deinstallation

Die Deinstallation entfernt die Cache-Tabelle, den Verwaltungs-Tab, sämtliche Einstellungen und alle erzeugten MP3-Dateien einschließlich des Ordners var/dfaudioproduct/. Auf dem Server bleibt nichts zurück.

Support

Eine Frage, ein Fehler, ein Verbesserungswunsch? Kontaktieren Sie das DataFirefly-Team über die Support-Seite der Website. Nennen Sie bitte Ihre PrestaShop-Version, Ihre PHP-Version, die verwendete Engine und gegebenenfalls den Inhalt des Fehlerprotokolls.