Text To Speech

Summary

• Internal name: TextToSpeech
• Category: Notifications
• Purpose: Read a text out loud using the device text-to-speech engine. The task waits until playback ends.
• Task type: Normal

---

Compatibility

• Minimum AndroMate version: 1.1.0

• Maximum AndroMate version: 1.1.0

• Minimum Android: Android 13 (API 33)

• Maximum Android tested: Android 16 (API 36)

• Required permissions: None

---

Detailed description

The Text To Speech task speaks a text aloud through the Android TextToSpeech engine. It works from the background (foreground service) — it is audio output, not UI, and needs no special runtime permission.

The TTS engine has an asynchronous lifecycle (init → speak → done). The task handles this internally and blocks until playback finishes (or the timeout expires), then releases the engine. Waiting is mandatory: releasing the engine too early would cut off the speech.

If the engine fails to initialize, the chosen language data is missing, or the timeout expires, the task throws TTS-TASK-001.

---

Input parameters

Parameter	Type	Required	Possible values / Rules	Android Compatibility	AndroMate Compatibility	Default
tts_text	String	Yes	Text to read (supports interpolation)	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	""
language	Enum / String	No	BCP-47 tag (en, fr, ar, …); empty → device default	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	""
timeout_s	Integer	No	Safety timeout for init + playback (seconds)	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	30

---

Output parameters

This task produces no output variable. It returns a VoidResult on success.

---

Exceptions

Code	Trigger condition
TTS-TASK-001	TTS engine init failed, language unavailable, or timeout expired

---

Execution flowchart

flowchart TD
    Start([▶ TextToSpeech]) --> Resolve[🔧 Resolve text & language]

    Resolve --> Init[⚙️ Init TTS engine\nwait for onInit]

    Init --> Ok{Init success ?}

    Ok -->|No| Throw([❌ TTS-TASK-001])
    Ok -->|Yes| Lang[🌐 Set language\nfallback to default]

    Lang --> Speak[🗣️ speak QUEUE_FLUSH]

    Speak --> Wait[⏳ Wait for onDone / timeout]

    Wait --> Shutdown[🧹 shutdown engine]

    Shutdown --> Success([✅ VoidResult])

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Throw fill:#ffcdd2
    style Init fill:#fff9c4
    style Speak fill:#f3e5f5
    style Wait fill:#fff9c4

How it works:

1. Resolve: tts_text and language are resolved against the AndroMate context
2. Init: the TTS engine is initialized; the task waits for the onInit callback (up to timeout_s)
3. Language: the requested language is set; if unsupported, it falls back to the device default
4. Speak: the text is spoken with QUEUE_FLUSH
5. Wait: the task blocks until the onDone callback fires (or the timeout)
6. Shutdown: the engine is released
7. Result: returns VoidResult, or throws TTS-TASK-001 on failure

---

Code examples

Example 1 — Speak a message in English

{
  "TextToSpeech": [
    {
      "id": "1",
      "title": "Speak",
      "tts_text": "Test completed successfully",
      "language": "en",
      "timeout_s": 30
    }
  ]
}

---

Example 2 — Speak a variable in the device language

{
  "TextToSpeech": [
    {
      "id": "2",
      "title": "Announce result",
      "tts_text": "Speed is $speed_kmh kilometers per hour",
      "language": ""
    }
  ]
}

---

Input parameter details

tts_text — Text to speak

The text read aloud. Supports $variable and ${SPECIAL_VAR} interpolation.

language — Language

A BCP-47 language tag selecting the voice language:

Value	Language
""	Device default
en	English
fr	French
ar	Arabic
es	Spanish
de	German
it	Italian

If the chosen language is not available on the device, the engine falls back to the device default.

timeout_s — Safety timeout

Maximum time (in seconds) to wait for both engine initialization and playback. Prevents the workflow from blocking forever if the engine hangs. Default 30.

---

Output parameter details

This task produces no output variable.

---

Complete JSON example

{
  "TextToSpeech": [
    {
      "id": "1",
      "title": "Text To Speech",
      "tts_text": "Workflow finished",
      "language": "en",
      "timeout_s": 30
    }
  ]
}