====== Text2speech ======

===== Zusammenfassung =====

Komfortable Text-to-Speech Engine für den LoxBerry. Wandelt Texte im MP3 um und spielt diese ab. Über Add-on's gibt es noch div. Erweiterungen wie z. B.:

  * //aktuelle Zeitansage//
  * //Wetteransage (basierend auf installiertem Weather4Lox Plugin)//
  * //Wetterwarnungen//
  * //Pollenvorhersage//
  * //Zeit zum Zielort//
  * //Müllkalender //(basierend auf installiertem CalDAV4Lox Plugin)
  * //Kalender (basierend auf installiertem CalDAV4Lox Plugin)//\\ // //

Darüber hinaus können auch gespeicherte MP3 Dateien abgespielt werden.

Das Plugin unterstützt bis zu 150 verschiedene Sprachen (je nach Provider) und die Texte der Add-on's können teilweise (je nach Add-on) frei konfiguriert werden.

===== Download =====

Alle Releases: [[https://github.com/Liver64/LoxBerry-TTS/releases]]

Dort beim aktuellsten Release

  * entweder den "Source code (zip)" herunterladen, am LoxBerry auswählen und installieren,
  * oder den "Source code (zip)"-Link in die Zwischenablage kopieren, diesen in der Pluginverwaltung bei der URL einfügen, und installieren.

Repository bei Github: [[https://github.com/Liver64/LoxBerry-TTS]]

===== Installation =====

Das Plugin kann normal installiert werden. Nach der Installation muss der LoxBerry nicht neu gestartet werden. In LoxBerry muss mindestens ein Miniserver konfiguriert sein.

<WRAP center round tip 100%>

Minimale LoxBerry Version

Zur Verwendung des Plugins ist mindestens die **LoxBerry Version 1.2.5** notwendig! Bitte führe vor der Installation über das Update Widget eine Aktualisierung auf die letzte Release-Version Deines LoxBerrys durch.

</WRAP>

===== Konfigurationsoptionen =====

In der Plugin-Konfiguration können folgend Optionen definiert werden.

| Text-to-Speech (T2S) Instanz | Beschreibung  |
| T2S Engine  | Auswahl der Text-to-Speech Engine die verwendet werden soll (Empfehlung: Responsive Voice) |

| Cache Einstellungen | Beschreibung  |
| Cache Verweildauer  | 1 Tag / 1 Woche / 1 Monat / 1 Jahr / Für immer - wie lange eine erzeugte MP3 gespeichert wird, bevor diese bei der täglichen Reorganisation gelöscht wird. |
| Max. Cachegröße (MB) | 100 bis 5000 MB. Der Cache wird täglich auf diese Größe reduziert, beginnend mit den ältesten Dateien.  |

**Bitte beachte:** Es wird sowohl die "Verweildauer" als auch die "Maximale Cachegröße" gleichermaßen ausgewertet. Wenn du die Dateien beispielsweise nur anhand der Cachegröße bereinigen möchtest, stelle bei der Verweildauer "Für immer" ein.

MP3 erstellen

Um wiederkehrende MP3 Dateien zu erstellen wie z.B. "Die Waschmaschine ist fertig" generiert man einmalig den Text bzw. die Syntax über den Browser:

__http:%%//%%<IP-LOXBERRY> oder <HOSTNAME>/plugins/text2speech/index.php?text=die waschmaschine ist fertig.__

Angenommen ihr habt als Speicherort "Local Data Dir" ausgewählt, wechselt dann in das Verzeichnis **/opt/loxberry/data/plugins/text2speech,** kopiert von dort die gerade erzeugte MP3 Datei in das Verzeichnis **/opt/loxberry/data/plugins/text2speech/mp3/** und benennt Sie einfach um in z.B. "waschmaschine.mp3". Anschließend kann diese in Zukunft immer mit folgender Syntax aufgerufen werden:

__http:%%//%%<IP-LOXBERRY> oder <HOSTNAME>/plugins/text2speech/index.php?file=waschmaschine__

Hinweis: Die Originaldatei wird nach Ablauf der Verweildauer dann automatisch gelöscht. Hinweis 2: Es darf hier die Dateierweiterung ".mp3" //nicht// mit angegeben werden!

| Wähle Jingle  | Beschreibung  |
| Dateiname des Standard Jingles | Vor jedem Aufruf eines T2S Requests kann ein beliebiges Jingle abgespielt werden (näheres unter "**Funktionen des Plugins**").\\ \\ Mit dieser Option wird das Standardjingle definiert. |

| Auswahl des Ausgabemediums | Beschreibung  |
| MP3 Ausgabesteuerung  | Wahl der zur Verfügung stehenden Ausgabemöglichkeiten des LoxBerry. |

| Speicherplatz für MP3 Dateien | Beschreibung  |
| Speicherplatz für MP3 Dateien | Es werden nur Speichermöglichkeiten gemäß deiner LoxBerry Konfiguration angezeigt, die lesen **und** schreiben erlauben.\\ \\ Dateien im **/data/plugins/text2speech/tts/mp3/** Ordner (siehe unten) werden automatisch verschoben, //nicht jedoch der TTS-Cache.// |

===== Funktionen des Plugins =====

Das Plugin wandelt geschriebenen Text in MP3 Dateien um und spielt diese auf den am LoxBerry angeschlossenen Audio Outputs ab. Der Text wird je nach Auswahl der T2S Engine aufbereitet, anschließend an den Provider geschickt, dieser wandelt den Text in Sprache um und schickt eine MP3 zurück, die dann final gespeichert wird. Wurde ein Text bereits im Vorfeld verwendet, wird die Anforderung nicht mehr an den Provider geschickt, sondern die vorhandene Datei wird erneut abgespielt (insofern sie noch vorhanden ist → siehe "Verweildauer der MP3 Dateien").

Folgende Funktionen sind möglich:

==== Allgemeine Parameter ====

Folgende Werte sind Parameter, die in der Syntax bei jedem Befehl optional genutzt werden können. Die jeweilige Befehlsverknüpfung ist ein "//**&**" //vorangestellt

| Eigenschaft  | Wert  | Beschreibung  |
| Lautstärke der Audio Ausgabe  | //volume=<WERT>//  | Angabe der Lautstärke der Audioausgabe. Nur Werte von x bis xxx der Standardlautstärke sind zulässig.  |
| Standard Jingle welches vor der T2S ausgegeben werden soll | //jingle//  | das Standard Jingle aus der Plugin Konfiguration wird ausgegeben. Dieses muss sich in **/data/plugins/text2speech/tts/mp3/** befinden.  |
| Jingle welches vor der T2S ausgegeben werden soll  | //jingle=<MP3 DATEI>// | Dateiname des für diese Ansage individuellen Jingle wird ausgegeben. Dieses muss sich in **/data/plugins/text2speech/tts/mp3/** befinden.  |
| automatische Grußformel  | //greet//  | Bei einer T2S (nicht file) kann eine Begrüßung vor dem Text angesagt werden. Die Begrüßungstexte können über das Translate Widget des LB individualisiert werden (t2s-text_en.ini). Je nach Tageszeit (4h-10h, 10h-17h, 17h-22h und >22h können jeweils 5 Grußformeln hinterlegt werden die per Zufallsgenerator vor der eigentlichen T2S angesagt werden. Bitte bei der Pflege Interpunktion beachten! |
| nur für Enwickler  | json  | erstellt das MP3 und gerneriert das JSON file mit den notwendigen Informationen zur Weiterverarbeitung (näheres siehe [[https://loxwiki.atlassian.net/wiki/pages/resumedraft.action?draftId=1219756464#T2SRequest|Text2speech#T2S Request]])  |

==== Spezifische Parameter ====

Nachfolgende Übersicht über die zur Verfügung stehenden Befehle

| Eigenschaft  | Wert  | Beschreibung  |
| Ausgabe eines Textes (ohne Werte aus LoxConfig) | //text=//<TEXT>  | Text der ausgegeben werden soll → "Als Digitalausgang verwenden" im MS muss "**aktiv**" sein.  |
| Ausgabe eines Textes (mit Werten aus LoxConfig) | //text=//<TEXT>  | Text der ausgegeben werden soll → "Als Digitalausgang verwenden" im MS darf "**nicht aktiv**" sein. Der Text kann die Variable <v> enthalten. |
| Ausgabe einer gespeicherten MP3 Datei  | //file=//<DATEINAME> | Datei die ausgegeben werden soll.  |

==== Add-on Parameter ====

Nachfolgende Übersicht über die zur Verfügung stehenden Befehle für die Addon's

| Eigenschaft  | Wert  | Beschreibung  |
| Ausgabe der Wettervorhersage in Abhängigkeit zur Uhrzeit  | //text=weather//  | Ausgabe der Wettervorhersage (nur bei installiertem "Weather4Lox" Plugin).  |
| Ausgabe der Uhrzeit  | //text=clock//  | Ausgabe der aktuellen MS Uhrzeit.  |
| Augabe einer Wetterwarnung (insofern vorhanden)  | //text=warning//  | Ausgabe einer vorhandenen Wetterwarnung (basierend auf dem DWD).  |
| Ausgabe eine Pollenvorhersage  | //text=pollen//  | Ausgabe einer Pollenvorhersage.  |
| Ausgabe eines evtl. vorhanden Abfallkalenders  | //text=abfall//  | Ausgabe der abzuholenden Abfallbehälter (nur bei installiertem "CalDAV4Lox" Plugin).  |
| Ausgabe eines Kalendereintrages  | //text=calendar//  | Ausgabe eines anstehenden Kalendereintrages (nur bei installiertem "CalDAV4Lox" Plugin). |
| Ausgabe eines Zufallwitzes  | //text=witz//  | Ausgabe eines 18+ Witzes nach dem Zufallsprinzip  |
| Ausgabe der Zeit und Entfernung zu einem angegebenen Zielort | //text=&distance&to=<ZIEL>// | Ausgabe der Strecke und die zu erwartende Fahrzeit zu einem Ziel.  |

==== Beispiele ====

| Syntax  | Beschreibung  |
| __/plugins/text2speech/index.php?file=gartentor_offen&jingle__  | Abspielen der Datei "gartentor_offen.mp3" mit dem Standardjingle vorher  |
| __/plugins/text2speech/index.php?text=weather&jingle=gong__  | Abspielen der Wetteransage mit dem Jingle "gong.mp3" vorher  |

===== Einrichtung in der Loxone Config Software =====

==== Virtuellen Ausgang einrichten ====

Dafür einen //Virtuellen Ausgang// erstellen:

| Eigenschaft  | Wert  | Anmerkung  |
| Bezeichnung und Beschreibung  | Nach Belieben  | Ist für die Funktion nicht relevant.  |
| Adresse  | http:%%//%%<HOSTNAME> oder <LOXBERRY IP> | Hostname des LoxBerry oder IP-Adresse des LoxBerry eingeben. (siehe Hinweis "[[https://loxwiki.atlassian.net/wiki/pages/resumedraft.action?draftId=1219756464#Troubleshooting|Text2speech#Troubleshooting]]") |
| Verbindung nach Senden schließen | Aktiv  |   |

==== Virtuellen Ausgang Befehl anlegen ====

im zweiten Schritt einen //Virtuellen Ausgang Befehl// erstellen:

| Eigenschaft  | Wert  | Anmerkung  |
| Bezeichnung und Beschreibung | Nach Belieben  | Ist für die Funktion nicht relevant.  |
| Befehl bei EIN  | /plugins/text2speech/index.php?<BEFEHL> | Befehl der ausgeführt werden soll (siehe oben).  |
| Als Digitalausgang verwenden | Aktiv  | Für den Fall es sollen **keine** Werte aus dem Miniserver angesagt werden (z.B. Text: Die Waschmaschine ist fertig).  |
| Als Digitalausgang verwenden | Nicht aktiv  | Für den Fall das Werte aus dem Miniserver angesagt werden sollen (z.B. Text: Die momentane Zimmertemperatur beträgt <v> Grad). |

==== Loxone XML Vorlage ====

XML Vorlage zum importieren in die Loxone Config. Bitte noch die IP-Adresse deines LoxBerry eintragen:

{{plugins:text2speech:1219757305.xml|1219757305.xml}}

===== Roadmap =====

Übersicht der nächsten geplanten Erweiterungen

LIVE automatische Grußformel je nach Tageszeit

WORKING Schnittstelle zu anderen Plugins/Hard- und Software Plattformen

===== Troubleshooting =====

**GELÖST**: Bei der parallelen Verwendung von //weather4lox// UND eingeschaltetem "**Wetter Service Emulator**" bitte in der Loxone Ausgangskonfiguration die //IP-Adresse// statt dem Hostnamen angeben, ansonsten wird keine MP3 ausgegeben

===== Fragen stellen und Fehler melden =====

Fragen und Probleme wie immer im [[https://www.loxforum.com/forum/projektforen/loxberry/plugins/169062-plugin-text-2-speech-plugin-f%C3%BCr-loxberry|Forum]] oder ein Issue auf Github

Wer Fehler im Wiki findet darf sie gerne behalten oder korrigieren