# Como usar Text-to-Speech (TTS) e Speech-to-Text (STT)

> Falar um texto em voz alta e transcrever a fala do usuário para texto, com configuração de locale/velocidade.

Source: https://crossfly.dev/pt/docs/cookbook/device/tts-stt — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Como usar Text-to-Speech (TTS) e Speech-to-Text (STT)

**Propósito.** Fazer o dispositivo **falar** um texto (TTS) e **transcrever** a fala do usuário para
texto (STT). Suporte: Android e iOS.

## APIs usadas
- `Device.textToVoice(String text)` — sintetiza e reproduz `text` como fala. **A mesma string serve para configurar** o motor via pares `chave:valor` separados por vírgula.
  - `locale:por_BRA` — código de idioma (ex.: `por_BRA`, `eng_USA_f00`).
  - `speech:0.75` — multiplicador de velocidade (`1.0` = normal, `0.5` = lento, `2.0` = rápido).
  - `languages` — lista os idiomas disponíveis no logcat (debug). `quit` — desliga o motor TTS.
- `Device.voiceToText(VoiceToTextListener listener)` — inicia o reconhecimento de fala; resultados chegam pelos callbacks.
- `Device.VoiceToTextListener` — `onStart()`, `onFinish()`, `onResult(String text)`, `onError(int code, String msg)`.
- `Device.soundToSpeechTimeout` (estático, ms, default `5000`) — timeout do reconhecimento.

> **Sim, `textToVoice` aceita string de configuração.** A primeira chamada pode configurar
> `locale`/`speech` (ex.: `"locale:por_BRA,speech:0.75"`); chamadas seguintes com texto normal falam o
> conteúdo. Os callbacks de `voiceToText` chegam **fora da paint thread** → use `Component.onUI(...)`
> ao atualizar a UI. Na primeira execução no Android pode ser solicitada a instalação de pacotes de
> idioma HD.

## Exemplo completo (copiar, colar e rodar)

```java
package com.exemplo;

import dev.crossfly.ui.*;                   // Window, Component, Button, Label
import dev.crossfly.ui.layout.*;            // VerticalLayout
import dev.crossfly.device.*;               // Device, Device.VoiceToTextListener

/** Tela principal executável. Aponte o launcher (classname) e rode: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      Label resultado = new Label("");
      add(LAY_AUTO, resultado);

      Button falar = new Button("Falar (TTS)");
      falar.onAction(c ->
      {
         // TTS — configurar idioma/velocidade e depois falar
         Device.textToVoice("locale:por_BRA,speech:0.9");     // configuração (opcional, 1ª vez)
         Device.textToVoice("Olá! Bem-vindo ao aplicativo.");  // fala o texto
         resultado.setText("Falando...");
      });
      add(LAY_AUTO, falar);

      Button ouvir = new Button("Transcrever (STT)");
      ouvir.onAction(c ->
      {
         // STT — transcrever a fala do usuário (callbacks fora da paint thread)
         Device.voiceToText(new Device.VoiceToTextListener()
         {
            public void onStart()  { Component.onUI(() -> resultado.setText("Ouvindo...")); }
            public void onFinish() { Component.onUI(() -> resultado.setText("Pronto")); }
            public void onResult(String text)
            {
               Component.onUI(() -> resultado.setText("Reconhecido: " + text));
            }
            public void onError(int code, String msg)
            {
               Component.onUI(() -> resultado.setText("Erro: " + msg));
            }
         });
      });
      add(LAY_AUTO, ouvir);
   }
}
```

> O trecho abaixo mostra **só o miolo**. Para rodar, coloque-o no esqueleto `MainWindow` acima.

## Trecho mínimo

```java
// verificado na fonte: Device.java (textToVoice linha 387, voiceToText linha 340, VoiceToTextListener linha 397)
import dev.crossfly.device.*;              // Device, Device.VoiceToTextListener
import dev.crossfly.ui.*;                  // Component (onUI)

// 1) TTS — configurar idioma/velocidade e depois falar
Device.textToVoice("locale:por_BRA,speech:0.9");   // configuração (opcional, 1ª vez)
Device.textToVoice("Olá! Bem-vindo ao aplicativo."); // fala o texto

// 2) STT — transcrever a fala do usuário (callbacks fora da paint thread)
Device.voiceToText(new Device.VoiceToTextListener() {
   public void onStart()  { Component.onUI(() -> mostrarStatus("Ouvindo...")); }
   public void onFinish() { Component.onUI(() -> mostrarStatus("Pronto")); }
   public void onResult(String text) {
      Component.onUI(() -> preencherCampo(text));   // texto reconhecido
   }
   public void onError(int code, String msg) {
      Component.onUI(() -> mostrarErro(msg));
   }
});
```

## Aprofunde-se
- Guia de som e diversos: [Som e diversos](/docs/data-and-services/device-sound-and-misc)
- Receita irmã: [vibrar-beep-clipboard.md](/docs/cookbook/device/vibrar-beep-clipboard)