[DOCKER] [RELEASE] Versatile TTS service for any Docker environment and Sonoff iHost smart hub

[teo.alex]

Clean TTS for Sonoff iHost & Smart Home

Studio-Grade Neural Voice Announcements for Your Home Automations

Give your Sonoff iHost and smart home a natural, human-like voice. Clean TTS brings lifelike neural text-to-speech directly to the iHost’s built-in speaker and to any smart media player on your local network.

---

What Clean TTS Does

• Natural Neural Speech: Sounds like a real person talking in your room, with natural intonation, breathing rhythm, and clear pronunciation across multiple languages (English, Romanian, German, French, Italian, Spanish, etc.).
• Speaks on iHost Internal Speaker: Plays announcements directly out of your Sonoff iHost built-in speaker — zero extra cables, amplifiers, or audio accessories needed.
• Never Cuts Off Announcements: If multiple sensors trigger at the exact same moment (e.g. front door opens while a motion alert sounds), Clean TTS speaks every announcement clearly one after another instead of cutting words off or playing noisy overlapping sound.
• Pleasant Wake-Up Chime: Softly alerts household members that an announcement is coming before speaking.
• Smart Pronunciation Dictionary: Correctly pronounces smart home brand names and units instead of awkwardly spelling them out (e.g., “Zigbee” sounds like “zig-bi”, “Shelly” sounds like “she-lee”, “kWh” is read as “kilowatt hours”). Includes a live Play button to test words before saving.
• Live Web Studio: Friendly dashboard at http://ihost.local:8123 to test voices, adjust defaults, and test speech right from your browser.
• AI Assistant Ready (MCP): Connects natively with AI assistants (Claude Desktop, Hermes Agent, Antigravity) so your AI agents can speak out loud on your iHost.

---

Quick 1-Minute Setup on Sonoff iHost

1. In the eWeLink CUBE web interface, navigate to Docker → Images → Search: tmalex/clean-tts
2. Download the latest image.
3. Run the container with:

• Network Mode: Select host (do NOT use bridge mode; bridge causes connection errors with the internal speaker API). In host mode, the port is fixed to 8123.
• Volume Mount: Create a dedicated partition / folder specifically for Clean TTS (e.g. clean-tts) and map it to /data. Do NOT mount it to another container’s directory (like Node-RED). This dedicated folder keeps your custom words, generated voices, and settings permanently safe across container updates.

1. Open your browser at: http://ihost.local:8123
2. On your first visit, click “Request Access Token” and confirm Allow on your iHost screen to authorize physical speaker playback.

---

How Parameters Work (Override on the Fly)

In Clean TTS, you can configure your favorite default voice, volume, and speed in the web dashboard.

Whenever you send an announcement from Node-RED, Home Assistant, or an HTTP request, you can simply send the text, or you can optionally override any setting for that specific announcement:

Parameter	Type	Example	What it does
text	string	"Front door opened"	Required. The message to speak.
lang	string	"en", "ro", "de", "fr"	Language code. Automatically picks the best native voice.
voice	string	"en-US-JennyNeural"	Select a specific male or female voice.
volume	string	"+20%", "-15%"	Volume boost or reduction for this specific alert (e.g. louder for alarms, quieter at night).
rate	string	"+10%", "-10%"	Speech speed (faster or slower).
pitch	string	"+5Hz", "-5Hz"	Voice pitch adjustment.
bell	boolean	true / false	Enable or disable the notification chime before speaking.
nocache	boolean	true / false	Set true for spontaneous one-off alerts (current time, live temperature readings).

Tip: Any parameter you omit automatically falls back to your saved settings from the web dashboard!

---

Node-RED Integration (Step-by-Step)

Method A: Speak on the Sonoff iHost Speaker (Recommended)

To make your Sonoff iHost speak an announcement out loud:

1. Add an http request node to your flow.
2. Configure the node:

• Method: POST
• URL: http://ihost.local:8123/api/tts
• Return: a parsed JSON object

1. In a change or function node just before the request, set msg.payload:

msg.payload = {
    "text": "Motion detected in the backyard garden.",
    "bell": true,
    "volume": "+20%"
};
return msg;

When triggered, your iHost speaker chimes and speaks the message clearly!

---

Method B: Play Night-Time Gentle Alert (Node-RED Example)

Speak quietly without a wake-up chime:

msg.payload = {
    "text": "Living room lights turned off. Good night!",
    "bell": false,
    "volume": "-20%",
    "rate": "-5%"
};
return msg;

---

Method C: Stream to External Speakers or Home Assistant

If you want to play announcements on external DLNA speakers, Sonos, or through Home Assistant’s media_player.play_media service, use a simple GET request:

http://ihost.local:8123/api/tts?text=Welcome+home&lang=en&bell=true

In Home Assistant:

service: media_player.play_media
target:
  entity_id: media_player.living_room_speaker
data:
  media_content_id: "http://ihost.local:8123/api/tts?text=Front+door+opened&bell=true"
  media_content_type: "music"

---

Quick cURL Examples for Testing

Speak on iHost Speaker:

curl -X POST http://ihost.local:8123/api/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Washing machine cycle finished.",
    "bell": true,
    "volume": "+10%"
  }'

Urgent Alert (Louder & Faster):

curl -X POST http://ihost.local:8123/api/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Warning! Water leak detected in the bathroom.",
    "bell": true,
    "volume": "+40%",
    "rate": "+15%"
  }'

---

Web Dashboard Overview

Access http://ihost.local:8123 from any browser on your network:

• Studio (/): Test any text, preview voices, and adjust global volume and speed sliders.
• Phonetic Dictionary (/dict): Teach Clean TTS how to pronounce tricky local words or smart home brands with instant audio preview.
• Backup & Restore (/backup): Download a full ZIP backup of your dictionaries and settings with 1 click.
• Languages (/languages): Switch between English, Romanian, French, German, Spanish, and Italian.
• AI Agent Hub (/mcp): Connect AI assistants like Claude Desktop to control speech hands-free.

---

tmalex/clean-tts - Docker Image