# SpeechRecognition

![Status](https://img.shields.io/badge/status-stable-brightgreen)

Componente de reconhecimento de voz que integra a Web Speech API para transcrever a fala do usuário em texto, inserida diretamente em um `<textarea>` fornecido. Suporta também text-to-speech para leitura em voz alta do conteúdo do campo.

> **Nota:** Este componente é utilizado internamente pelo `TextAreaComponent` quando `speechRecognition: true`. Para uso em campos de texto simples, prefira o `TextAreaComponent`.

## Quando usar

- Campos de texto onde o usuário pode preferir ditar em vez de digitar
- Acessibilidade para usuários com dificuldade de digitação
- Formulários de observações ou descrições longas
- Ditado de textos longos em múltiplas sessões (`keepContext: true`)

## Quando não usar

- Ambientes sem suporte à Web Speech API (Firefox, Safari) — o componente não renderiza nesses browsers
- Campos de texto curtos onde a digitação é mais eficiente
- Contextos sem acesso ao microfone do dispositivo

## Instalação

```typescript
import { SpeechRecognitionModule } from '@seniorsistemas/angular-components/speech-recognition';

@NgModule({ imports: [SpeechRecognitionModule] })
export class MeuModule {}
```

## Uso básico

```html
<textarea #meuTextArea rows="5" placeholder="Digite ou use o microfone..."></textarea>
<s-speech-recognition
  [textAreaElement]="meuTextArea"
  (recognizedText)="onTextoReconhecido($event)"
></s-speech-recognition>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `textAreaElement` | `HTMLTextAreaElement` | — | Sim | Referência ao elemento `<textarea>` nativo que receberá o texto transcrito |
| `keepContext` | `boolean` | `false` | Não | Quando `true`, o texto reconhecido é adicionado ao texto existente em vez de substituí-lo |
| `speechRecognitionPlaceholder` | `string` | `''` | Não | Placeholder exibido no textarea durante o reconhecimento de voz |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `recognizedText` | `EventEmitter<string>` | Emitido quando o reconhecimento é concluído e aprovado pelo usuário. Emite o texto transcrito |

## Exemplos

### Uso padrão com textarea

```html
<div style="display: flex; align-items: flex-start; gap: 8px;">
  <textarea
    #textAreaRef
    rows="5"
    placeholder="Digite ou use o microfone..."
    style="flex: 1;"
  ></textarea>
  <s-speech-recognition
    [textAreaElement]="textAreaRef"
    [keepContext]="false"
    speechRecognitionPlaceholder="Ouvindo..."
    (recognizedText)="onReconhecido($event)"
  ></s-speech-recognition>
</div>
```

### Ditado acumulativo (keepContext)

```html
<div style="display: flex; align-items: flex-start; gap: 8px;">
  <textarea
    #textAreaRef
    rows="5"
    placeholder="Cada reconhecimento adiciona ao texto existente..."
    style="flex: 1;"
  ></textarea>
  <s-speech-recognition
    [textAreaElement]="textAreaRef"
    [keepContext]="true"
  ></s-speech-recognition>
</div>
```

## Acessibilidade

- Requer suporte do browser à Web Speech API (compatível com Chrome e Edge)
- Ao iniciar o reconhecimento, o textarea é bloqueado para edição até o usuário aprovar ou descartar o texto reconhecido
- Após o reconhecimento, botões de **Aprovar** e **Descartar** são exibidos, permitindo confirmação antes de aplicar o texto
- O botão de text-to-speech lê o conteúdo atual do textarea em voz alta, com controles de velocidade (0.5x, 1x, 1.5x, 2x)

## Componentes relacionados

- [`TextArea`](../text-area/README.md) — área de texto com Speech Recognition integrado via prop `speechRecognition`