# `Mob.Speech`
[🔗](https://github.com/genericjam/mob/blob/master/lib/mob/speech.ex#L1)

Text-to-speech. No permission required on either platform.

## Usage

    def handle_event("read_aloud", _params, socket) do
      Mob.Speech.speak(socket, socket.assigns.article_text)
      {:noreply, socket}
    end

Stop mid-utterance:

    Mob.Speech.stop_speaking(socket)

## Options

| Option   | Type    | Meaning                                  | Default |
|----------|---------|------------------------------------------|---------|
| `:rate`  | float   | Speech rate (0.0–1.0, platform-scaled)   | system  |
| `:pitch` | float   | Pitch multiplier (0.5–2.0)               | 1.0     |
| `:voice` | binary  | BCP-47 language/voice id (e.g. `"en-US"`)| system  |

Calling `speak/3` while speech is in progress enqueues the new utterance.
iOS uses `AVSpeechSynthesizer`; Android uses `TextToSpeech`.

# `speak`

```elixir
@spec speak(Mob.Socket.t(), binary(), keyword()) :: Mob.Socket.t()
```

Speak `text` aloud. Fire-and-forget; returns the socket unchanged so it can be
used inline without disrupting a `handle_event`/`handle_info` return value.

    Mob.Speech.speak(socket, "Returns a list.", rate: 0.5)

# `stop_speaking`

```elixir
@spec stop_speaking(Mob.Socket.t()) :: Mob.Socket.t()
```

Stop any in-progress speech immediately. Returns the socket.

---

*Consult [api-reference.md](api-reference.md) for complete listing*