# useSpeechRecognition
URL: /docs/native/hooks/use-speech-recognition

Live speech-to-text for React Native with the same API as the web hook, backed by the optional expo-speech-recognition module.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-speech-recognition
```

**Dependencies:**
- [expo-speech-recognition](https://www.npmjs.com/package/expo-speech-recognition)

`expo-speech-recognition` is an **optional peer** with a config plugin, so it needs a development build — see [Speech Recognition](/docs/native/expo/speech-recognition) for the setup. The module is loaded lazily with a guarded `require()`: in Expo Go (or when it isn't installed) `isSupported` is `false`, `start` / `stop` are no-ops, and `DocyrusAgentChatInputMicButton` hides itself. `start()` asks for microphone + speech permissions first; a denial sets `error` to `'not-allowed'`.

## Usage

```tsx
import {
  DocyrusAgentChatInput,
  DocyrusAgentChatInputDefaultBody,
  DocyrusAgentChatInputMicButton,
  useDocyrusAgentMicTranscription
} from '@/components/docyrus-native/docyrus-agent';
import { useSpeechRecognition } from '@/hooks/docyrus-native/use-speech-recognition';

function MicTool() {
  const mic = useDocyrusAgentMicTranscription();
  const speech = useSpeechRecognition({ lang: 'en-US', ...mic.speechHandlers });

  return ;
}

```

`DocyrusAgentChatInputMic` is the same thing pre-wired.

## API Reference

### UseSpeechRecognitionArgs

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `lang` | `string` | device locale | BCP-47 tag (`en-US`, `tr-TR`) |
| `continuous` | `boolean` | `true` | Keep listening after each result |
| `interimResults` | `boolean` | `true` | Stream partial transcripts |
| `onTranscript` | `(chunks: { final: string; interim: string }) => void` | - | Every result: cumulative final text + pending interim |
| `onStart` | `() => void` | - | Session started |
| `onEnd` | `() => void` | - | Session ended (stop, error or timeout) |

### UseSpeechRecognitionResult

| Field | Type | Description |
|-------|------|-------------|
| `isSupported` | `boolean` | Module installed, linked and recognition available |
| `isRecording` | `boolean` | Session active |
| `transcript` | `string` | Cumulative final transcript of the session |
| `start` / `stop` / `toggle` | `() => void` | Control the session |
| `reset` | `() => void` | Clear the transcript |
| `error` | `string \| null` | Last native error code (`'not-allowed'`, `'no-speech'`, …) |

`isSpeechRecognitionAvailable()` is exported as a plain function for non-hook checks.