### Minimal Example

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/QUICK_START.md

A basic example demonstrating how to check permissions, request them if needed, and start speech recognition.

```APIDOC
## Minimal Example

```typescript
// 1. Check permissions
let perms = await SpeechRecognition.checkPermissions();
if (perms.speechRecognition !== 'granted') {
  perms = await SpeechRecognition.requestPermissions();
}

// 2. Start listening
const result = await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 1
});

// 3. Get result
console.log('You said:', result.matches?.[0]);
```
```

--------------------------------

### Usage Example: Requesting and Using Permissions - TypeScript

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/permission-handling.md

Demonstrates how to request permissions and then use the `start()` method if granted. Logs the outcome.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

const perms = await SpeechRecognition.requestPermissions();

if (perms.speechRecognition === 'granted') {
  console.log('Permission granted; can now use start()');
  await SpeechRecognition.start();
} else {
  console.log('Permission denied:', perms.speechRecognition);
}
```

--------------------------------

### Minimal Speech Recognition Example

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/QUICK_START.md

A basic example demonstrating how to check permissions, request them if needed, start listening, and log the first recognized match.

```typescript
// 1. Check permissions
let perms = await SpeechRecognition.checkPermissions();
if (perms.speechRecognition !== 'granted') {
  perms = await SpeechRecognition.requestPermissions();
}

// 2. Start listening
const result = await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 1
});

// 3. Get result
console.log('You said:', result.matches?.[0]);
```

--------------------------------

### Minimal Example: Request Permissions and Start Listening

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/README.md

This snippet demonstrates how to request speech recognition permissions and then start listening for user input. It checks current permissions and requests them if not granted, then initiates listening and logs the first recognized match.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

// Request permissions
let perms = await SpeechRecognition.checkPermissions();
if (perms.speechRecognition !== 'granted') {
  perms = await SpeechRecognition.requestPermissions();
}

// Start listening
const result = await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 1
});

console.log('You said:', result.matches?.[0]);
```

--------------------------------

### Start Speech Recognition with Error Handling

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/errors.md

This example shows how to check for availability, request permissions, start speech recognition, and handle specific errors like missing permissions, unavailability, no speech detected, no match, or ongoing recognition.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function startSpeechRecognition() {
  try {
    // Check availability
    const available = await SpeechRecognition.available();
    if (!available.available) {
      console.log('Speech recognition not available');
      return;
    }

    // Check and request permissions
    let perms = await SpeechRecognition.checkPermissions();
    if (perms.speechRecognition !== 'granted') {
      perms = await SpeechRecognition.requestPermissions();
    }

    if (perms.speechRecognition !== 'granted') {
      console.log('Permissions not granted');
      return;
    }

    // Start listening
    const result = await SpeechRecognition.start({
      language: 'en-US',
      maxResults: 1,
      partialResults: false
    });

    if (result.matches && result.matches.length > 0) {
      console.log('Recognized:', result.matches[0]);
    }
  } catch (error) {
    // Handle specific errors
    const errorMsg = String(error);
    
    if (errorMsg.includes('Missing permission')) {
      console.error('Permissions were not granted');
    } else if (errorMsg.includes('not available')) {
      console.error('Speech recognition not available on this device');
    } else if (errorMsg.includes('No speech')) {
      console.error('No speech detected; please try again');
    } else if (errorMsg.includes('No match')) {
      console.error('Could not understand; please speak more clearly');
    } else if (errorMsg.includes('Ongoing')) {
      console.error('Speech recognition already in progress');
    } else {
      console.error('Speech recognition error:', error);
    }
  }
}

startSpeechRecognition();
```

--------------------------------

### start(options?)

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/INDEX.md

Starts the speech recognition service to listen for user input.

```APIDOC
## start(options?)

### Description
Starts the speech recognition service to listen for user input. Optional configuration can be provided.

### Method
`start(options?: UtteranceOptions)`

### Parameters
#### Request Body
- **options** (UtteranceOptions) - Optional - Configuration for speech recognition, such as language or prompt.

### Return Type
`Promise<{ matches?: string[] }>`

### Example
```typescript
const result = await SpeechRecognition.start({
  language: 'en-US'
});
console.log('Speech recognition results:', result.matches);
```
```

--------------------------------

### Complete Speech Recognition Event Example

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/events.md

This example shows how to request permissions, set up listeners for partial results and listening state, start recognition, and automatically stop after a delay. It also includes cleanup for the listeners.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function runSpeechRecognition() {
  const resultDiv = document.getElementById('result');
  const statusDiv = document.getElementById('status');

  try {
    // Ensure permissions
    let perms = await SpeechRecognition.checkPermissions();
    if (perms.speechRecognition !== 'granted') {
      perms = await SpeechRecognition.requestPermissions();
      if (perms.speechRecognition !== 'granted') {
        statusDiv.innerText = 'Permissions denied';
        return;
      }
    }

    // Setup listeners before starting
    const partialHandle = await SpeechRecognition.addListener('partialResults', (data) => {
      console.log('[Event] Partial result:', data.matches[0]);
      if (resultDiv) {
        resultDiv.innerText = data.matches[0];
      }
    });

    const stateHandle = await SpeechRecognition.addListener('listeningState', (data) => {
      console.log('[Event] State changed:', data.status);
      if (statusDiv) {
        statusDiv.innerText = data.status === 'started' ? '🎤 Listening...' : '✓ Done';
      }
    });

    // Start listening
    statusDiv.innerText = 'Starting...';
    await SpeechRecognition.start({
      language: 'en-US',
      maxResults: 1,
      partialResults: true,
      popup: false
    });

    // Auto-stop after 10 seconds
    setTimeout(async () => {
      console.log('Auto-stopping...');
      await SpeechRecognition.stop();

      // Cleanup
      await partialHandle.remove();
      await stateHandle.remove();

      console.log('Listening session ended');
    }, 10000);

  } catch (error) {
    console.error('Error:', error);
    statusDiv.innerText = 'Error: ' + String(error);
  }
}

// HTML
// <div id="result">Waiting...</div>
// <div id="status">Ready</div>
// <button onclick="runSpeechRecognition()">Start Listening</button>
```

--------------------------------

### Install Dependencies

Source: https://github.com/capacitor-community/speech-recognition/blob/master/CONTRIBUTING.md

Run this command to install project dependencies after cloning the repository.

```shell
npm install
```

--------------------------------

### Full Speech Recognition Configuration with Listeners

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/configuration.md

A comprehensive example demonstrating how to check availability and permissions, configure all options, start recognition, listen for partial results and state changes, and finally stop recognition and remove listeners. This example includes a timeout to simulate the end of speech recognition.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

// Check availability and permissions first
const available = await SpeechRecognition.available();
if (!available.available) {
  console.log('Not available');
  process.exit(1);
}

let perms = await SpeechRecognition.checkPermissions();
if (perms.speechRecognition !== 'granted') {
  perms = await SpeechRecognition.requestPermissions();
  if (perms.speechRecognition !== 'granted') {
    console.log('Permissions denied');
    process.exit(1);
  }
}

// Configure and start
await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 3,
  partialResults: true,
  popup: false
});

// Listen to partial results
const partialHandle = await SpeechRecognition.addListener('partialResults', (data) => {
  console.log('Partial result:', data.matches[0]);
});

// Listen to state changes
const stateHandle = await SpeechRecognition.addListener('listeningState', (data) => {
  console.log('State changed:', data.status);
});

// Simulate speech recognition ending after 10 seconds
setTimeout(async () => {
  await SpeechRecognition.stop();
  await partialHandle.remove();
  await stateHandle.remove();
}, 10000);
```

--------------------------------

### Installation

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/QUICK_START.md

Install the Speech Recognition plugin and sync your Capacitor project.

```APIDOC
## Installation

```bash
npm install @capacitor-community/speech-recognition
npx cap sync
```
```

--------------------------------

### start(options?)

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/web-implementation.md

Starts the speech recognition process. This method is not implemented on the web and will throw an error.

```APIDOC
## start(options?)

```typescript
start(options?: UtteranceOptions): Promise<{ matches?: string[] }>
```

**Throws:** `NotImplementedError` — "Method not implemented on web."
```

--------------------------------

### UI State Indicator Example

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/events.md

An example demonstrating how to use the 'listeningState' event to dynamically update a UI indicator. It includes starting recognition, showing a 'listening' message, and automatically stopping after a delay.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function setupListeningIndicator() {
  const indicator = document.getElementById('listening-indicator');

  const handle = await SpeechRecognition.addListener('listeningState', (data) => {
    if (indicator) {
      if (data.status === 'started') {
        indicator.style.display = 'block';
        indicator.innerText = '🎤 Listening...';
        indicator.style.color = 'green';
      } else {
        indicator.style.display = 'block';
        indicator.innerText = '🎤 Stopped';
        indicator.style.color = 'red';
      }
    }
  });

  // Start listening
  await SpeechRecognition.start({ partialResults: true });

  // Auto-stop after 10 seconds
  setTimeout(async () => {
    await SpeechRecognition.stop();
    await handle.remove();
    if (indicator) {
      indicator.style.display = 'none';
    }
  }, 10000);
}
```

--------------------------------

### Install Capacitor Speech Recognition Plugin

Source: https://github.com/capacitor-community/speech-recognition/blob/master/README.md

Use npm or yarn to install the plugin. After installation, sync native files with the Capacitor CLI.

```bash
npm install @capacitor-community/speech-recognition
```

```bash
yarn add @capacitor-community/speech-recognition
```

```bash
npx cap sync
```

--------------------------------

### Basic Speech Recognition Workflow

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/REFERENCE_GUIDE.md

Demonstrates the fundamental sequence of operations for using the speech recognition plugin: checking availability, requesting permissions, starting recognition, and handling results. This example assumes no listeners are used for cleanup.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

// 1. Check availability
const available = await SpeechRecognition.available();
if (!available.available) {
  console.log('Not available');
  return;
}

// 2-3. Check and request permissions
let perms = await SpeechRecognition.checkPermissions();
if (perms.speechRecognition !== 'granted') {
  perms = await SpeechRecognition.requestPermissions();
  if (perms.speechRecognition !== 'granted') {
    console.log('Permissions denied');
    return;
  }
}

// 4. Start listening with options
await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 1,
  partialResults: false
});

// 5. Wait for results
try {
  const result = await SpeechRecognition.start({
    language: 'en-US',
    maxResults: 1
  });
  console.log('Recognized:', result.matches?.[0]);
} catch (error) {
  console.error('Error:', error);
}

// 6-7. Clean up (if using listeners)
await SpeechRecognition.removeAllListeners();
```

--------------------------------

### Install Speech Recognition Plugin

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/QUICK_START.md

Install the plugin using npm and sync with Capacitor.

```bash
npm install @capacitor-community/speech-recognition
npx cap sync
```

--------------------------------

### Typical Speech-to-Text Flow

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/QUICK_START.md

This example demonstrates a complete flow for speech-to-text conversion, including checking availability, requesting permissions, and starting the recognition process. It handles potential errors and returns the first recognized match.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function speechToText() {
  try {
    // 1. Ensure available
    const avail = await SpeechRecognition.available();
    if (!avail.available) return null;

    // 2. Ensure permissions
    let perms = await SpeechRecognition.checkPermissions();
    if (perms.speechRecognition !== 'granted') {
      perms = await SpeechRecognition.requestPermissions();
      if (perms.speechRecognition !== 'granted') return null;
    }

    // 3. Listen
    const result = await SpeechRecognition.start({
      language: 'en-US',
      maxResults: 1
    });

    return result.matches?.[0];
  } catch (error) {
    console.error('Error:', error);
    return null;
  }
}

// Usage
const text = await speechToText();
console.log('Recognized:', text);
```

--------------------------------

### Capacitor Speech Recognition Example

Source: https://github.com/capacitor-community/speech-recognition/blob/master/README.md

Demonstrates the usage of various Speech Recognition methods including checking availability, starting recognition with options, listening for partial results, stopping recognition, and managing permissions.

```typescript
import { SpeechRecognition } from "@capacitor-community/speech-recognition";

SpeechRecognition.available();

SpeechRecognition.start({
  language: "en-US",
  maxResults: 2,
  prompt: "Say something",
  partialResults: true,
  popup: true,
});
// listen to partial results
SpeechRecognition.addListener("partialResults", (data: any) => {
  console.log("partialResults was fired", data.matches);
});

// stop listening partial results
SpeechRecognition.removeAllListeners();

SpeechRecognition.stop();

SpeechRecognition.getSupportedLanguages();

SpeechRecognition.checkPermissions();

SpeechRecognition.requestPermissions();

SpeechRecognition.hasPermission();

SpeechRecognition.requestPermission();
```

--------------------------------

### start()

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/speech-recognition-plugin.md

Starts listening for speech. This method can be configured to return only final results or to emit partial results as speech is recognized.

```APIDOC
## start(options?)

### Description
Starts listening for speech utterance. Behavior depends on the `partialResults` option:
- If `partialResults` is `false`: blocks until speech ends, then returns final matches.
- If `partialResults` is `true`: returns immediately and emits `partialResults` events as speech is processed. On Android, `partialResults` does not work if `popup` is `true`.

### Method
`start(options?: UtteranceOptions): Promise<{ matches?: string[] }> `

### Parameters
#### Options (`UtteranceOptions`)
- `language` (string, Optional) - Device locale - Language identifier (e.g. `en-US`). Must be a key from `getSupportedLanguages()`.
- `maxResults` (number, Optional) - `1` - Maximum number of results to return. Maximum value is `5`.
- `prompt` (string, Optional) - `undefined` - Prompt message to display on the dialog (Android only). Ignored on iOS and web.
- `popup` (boolean, Optional) - `false` - Show Android system speech recognition dialog (Android only). When `true`, on Android `partialResults` events are suppressed. Ignored on iOS and web.
- `partialResults` (boolean, Optional) - `false` - Emit `partialResults` event for each partial result as speech is recognized. If `false`, returns only the final result.

### Return Value
- `matches` (string[] | undefined) - Array of recognized text strings. Only present when `partialResults` is `false`. Undefined when `partialResults` is `true` (results come via `partialResults` event instead).

### Behavior Notes
- **Without partial results** (`partialResults: false`): Resolves when the user stops speaking and the system has final results.
- **With partial results** (`partialResults: true`): Resolves immediately; results arrive asynchronously via the `partialResults` listener event.
- **Permission requirement**: On iOS and Android, speech recognition and microphone permissions must be granted before calling `start()`. Call `checkPermissions()` and `requestPermissions()` first if needed.

### Usage Example
```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

// Final results only
const result = await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 3,
  partialResults: false
});
console.log('Final matches:', result.matches);

// With partial results
await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 5,
  partialResults: true,
  popup: false
});

SpeechRecognition.addListener('partialResults', (data) => {
  console.log('Partial match:', data.matches);
});
```
```

--------------------------------

### Basic Speech Recognition Start

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/configuration.md

Starts speech recognition using default settings. Ensure the plugin is imported.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

await SpeechRecognition.start();
```

--------------------------------

### Start Speech Recognition with Minimal Options

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/types.md

Initiates speech recognition with default settings. This is the simplest way to start the recognition process.

```typescript
await SpeechRecognition.start();
```

--------------------------------

### start(...)

Source: https://github.com/capacitor-community/speech-recognition/blob/master/README.md

Starts listening for utterances. If `partialResults` is true, events will be emitted for partial results until stopped.

```APIDOC
## start(...)

### Description
This method will start to listen for utterance.
if `partialResults` is `true`, the function respond directly without result and
event `partialResults` will be emit for each partial result, until stopped.

### Method
`start(options?: UtteranceOptions | undefined)`

### Parameters
#### Request Body
- **`options`** (UtteranceOptions) - Required - Options for the utterance, including language, max results, prompt, partial results, and popup.

### Returns
`Promise<{ matches?: string[]; }>`

### Example
```typescript
SpeechRecognition.start({
  language: "en-US",
  maxResults: 2,
  prompt: "Say something",
  partialResults: true,
  popup: true,
});
```
```

--------------------------------

### Install SwiftLint (macOS)

Source: https://github.com/capacitor-community/speech-recognition/blob/master/CONTRIBUTING.md

If you are on macOS, install SwiftLint using Homebrew for code linting.

```shell
brew install swiftlint
```

--------------------------------

### UtteranceOptions

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/types.md

Configuration options for the `start()` method, controlling various aspects of the speech recognition behavior.

```APIDOC
## Interface: UtteranceOptions

### Description
Configuration options for the `start()` method controlling speech recognition behavior.

### Fields
- `language` (string, optional) - Language identifier for recognition (e.g., `'en-US'`, `'es-ES'`). Must be a key from `getSupportedLanguages()`. Defaults to device default locale.
- `maxResults` (number, optional) - Maximum number of recognition results to return. Capped at `5` by platform limits. Defaults to `1`.
- `prompt` (string, optional) - Prompt message to display in the Android speech recognition dialog. Ignored on iOS and web.
- `popup` (boolean, optional) - Display the native Android speech recognition dialog. If `true`, `partialResults` events are suppressed on Android. Ignored on iOS and web. Defaults to `false`.
- `partialResults` (boolean, optional) - Enable `partialResults` events during recognition. When `true`, `start()` returns immediately and results arrive via the `partialResults` listener. When `false`, `start()` blocks until recognition ends and returns final results. Defaults to `false`.

### Used By
- `start(options?)` — Optional parameter type

### Examples
```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

// Minimal options
await SpeechRecognition.start();

// Final results only
const result = await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 3
});

// Partial results
await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 5,
  partialResults: true,
  popup: false
});

// With Android dialog
await SpeechRecognition.start({
  language: 'en-US',
  prompt: 'Say something...', 
  popup: true
});
```
```

--------------------------------

### Web Speech API Integration Example

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/web-implementation.md

An example demonstrating how to implement speech recognition on the web using the Web Speech API.

```APIDOC
## Web Speech API Integration Example

A basic implementation using the Web Speech API might look like:

```typescript
export class SpeechRecognitionWeb extends WebPlugin implements SpeechRecognitionPlugin {
  private recognition: any;

  constructor() {
    super();
    const SpeechRecognitionAPI = (window as any).SpeechRecognition || 
                                  (window as any).webkitSpeechRecognition;
    this.recognition = new SpeechRecognitionAPI();
  }

  async available(): Promise<{ available: boolean }> {
    return { available: !!this.recognition };
  }

  async start(options?: UtteranceOptions): Promise<{ matches?: string[] }> {
    if (!this.recognition) {
      throw new Error('Speech Recognition API not available');
    }

    if (options?.language) {
      this.recognition.lang = options.language;
    }

    return new Promise((resolve, reject) => {
      this.recognition.onresult = (event: any) => {
        const results = [];
        for (let i = 0; i < event.results.length; i++) {
          if (options?.maxResults && i >= options.maxResults) break;
          results.push(event.results[i][0].transcript);
        }
        resolve({ matches: results });
      };

      this.recognition.onerror = (event: any) => {
        reject(new Error(event.error));
      };

      this.recognition.start();
    });
  }

  async stop(): Promise<void> {
    if (this.recognition) {
      this.recognition.abort();
    }
  }

  // ... other methods ...
}
```
```

--------------------------------

### Permission Flow Patterns

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/permission-handling.md

Examples demonstrating different strategies for checking and requesting permissions.

```APIDOC
## Permission Flow Patterns

### Pattern 1: Check-Then-Use

Checks current permissions and proceeds only if granted.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function startListening() {
  const perms = await SpeechRecognition.checkPermissions();

  if (perms.speechRecognition === 'granted') {
    await SpeechRecognition.start();
  } else {
    console.log('Permissions required');
  }
}
```

### Pattern 2: Request-If-Needed

Requests permissions if they are not already granted.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function ensurePermissions() {
  let perms = await SpeechRecognition.checkPermissions();

  if (perms.speechRecognition !== 'granted') {
    perms = await SpeechRecognition.requestPermissions();
  }

  return perms.speechRecognition === 'granted';
}

async function startListening() {
  if (await ensurePermissions()) {
    await SpeechRecognition.start();
  }
}
```

### Pattern 3: Full Permission Handling with Feedback

A comprehensive approach that checks availability, current status, and requests permissions with feedback.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function initializeSpeechRecognition() {
  // Step 1: Check availability
  const available = await SpeechRecognition.available();
  if (!available.available) {
    console.error('Speech recognition not available on this device');
    return false;
  }

  // Step 2: Check current permissions
  let perms = await SpeechRecognition.checkPermissions();

  if (perms.speechRecognition === 'granted') {
    // Already granted
    console.log('Speech recognition permission already granted');
    return true;
  }

  if (perms.speechRecognition === 'denied') {
    // Permanently denied
    console.error('Permission denied; guide user to Settings');
    // Show UI directing user to enable in Settings
    return false;
  }

  // Step 3: Permission not yet determined; request it
  if (perms.speechRecognition === 'prompt' || 
      perms.speechRecognition === 'prompt-with-rationale') {
    console.log('Requesting permissions...');
    perms = await SpeechRecognition.requestPermissions();

    if (perms.speechRecognition === 'granted') {
      console.log('Permission granted!');
      return true;
    } else {
      console.error('Permission request denied');
      return false;
    }
  }

  return false;
}

// Use it
if (await initializeSpeechRecognition()) {
  await SpeechRecognition.start();
}
```
```

--------------------------------

### Web Speech API Integration Example

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/web-implementation.md

Provides a basic implementation of the SpeechRecognitionWeb class using the native Web Speech API. This example demonstrates how to handle speech recognition events and integrate with browser capabilities.

```typescript
export class SpeechRecognitionWeb extends WebPlugin implements SpeechRecognitionPlugin {
  private recognition: any;

  constructor() {
    super();
    const SpeechRecognitionAPI = (window as any).SpeechRecognition || 
                                  (window as any).webkitSpeechRecognition;
    this.recognition = new SpeechRecognitionAPI();
  }

  async available(): Promise<{ available: boolean }> {
    return { available: !!this.recognition };
  }

  async start(options?: UtteranceOptions): Promise<{ matches?: string[] }> {
    if (!this.recognition) {
      throw new Error('Speech Recognition API not available');
    }

    if (options?.language) {
      this.recognition.lang = options.language;
    }

    return new Promise((resolve, reject) => {
      this.recognition.onresult = (event: any) => {
        const results = [];
        for (let i = 0; i < event.results.length; i++) {
          if (options?.maxResults && i >= options.maxResults) break;
          results.push(event.results[i][0].transcript);
        }
        resolve({ matches: results });
      };

      this.recognition.onerror = (event: any) => {
        reject(new Error(event.error));
      };

      this.recognition.start();
    });
  }

  async stop(): Promise<void> {
    if (this.recognition) {
      this.recognition.abort();
    }
  }

  // ... other methods ...
}
```

--------------------------------

### Real-Time Results

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/QUICK_START.md

Example showing how to receive partial speech recognition results in real-time using event listeners.

```APIDOC
## Real-Time Results

```typescript
// Register listener before starting
const handle = await SpeechRecognition.addListener('partialResults', (data) => {
  console.log('Partial:', data.matches[0]);
});

// Start with partial results enabled
await SpeechRecognition.start({
  language: 'en-US',
  partialResults: true,
  popup: false  // Required on Android
});

// Stop when done
await SpeechRecognition.stop();
await handle.remove();
```
```

--------------------------------

### Start Speech Recognition

Source: https://github.com/capacitor-community/speech-recognition/blob/master/README.md

Starts listening for utterances. If `partialResults` is true, events will be emitted for each partial result until stopped.

```typescript
start(options?: UtteranceOptions | undefined) => Promise<{ matches?: string[]; }>
```

--------------------------------

### Start and Stop Listening

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/README.md

Methods to control the speech recognition service, starting it to listen for user speech and stopping it when done.

```APIDOC
## start(options?)

### Description
Starts listening for speech input from the user.

### Method
`start(options?: { language?: string; maxResults?: number })`

### Parameters
#### Options
- **language** (string) - Optional - The language code for recognition (e.g., 'en-US'). Defaults to the device's default language.
- **maxResults** (number) - Optional - The maximum number of recognition results to return. Defaults to 1.

### Returns
- `Promise<{ matches?: string[] }>` - A promise that resolves with an object containing an array of recognized text matches.
```

```APIDOC
## stop()

### Description
Stops the speech recognition service, ending the current listening session.

### Method
`stop()`

### Returns
- `Promise<void>` - A promise that resolves when the listening has been stopped.
```

--------------------------------

### Check Permissions

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/permission-handling.md

Checks if the application has the necessary permissions to use speech recognition. If permissions are 'granted', the `start()` method can be called.

```APIDOC
## checkPermissions()

### Description
Checks if the application has the necessary permissions to use speech recognition.

### Method
`checkPermissions()`

### Return Value
`PermissionStatus` - Indicates the current permission status. If the status is 'granted', the `start()` method can be invoked.
```

--------------------------------

### Define UtteranceOptions Interface

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/types.md

Configuration options for the start() method to control speech recognition behavior. Includes language, maxResults, prompt, popup, and partialResults.

```typescript
interface UtteranceOptions {
  language?: string;
  maxResults?: number;
  prompt?: string;
  popup?: boolean;
  partialResults?: boolean;
}
```

--------------------------------

### iOS listeningState Notifications

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/events.md

Illustrates how the 'listeningState' event is triggered on iOS. Use these to understand the native implementation of starting and stopping the audio engine.

```swift
self.notifyListeners("listeningState", data: ["status": "started"])
self.notifyListeners("listeningState", data: ["status": "stopped"])
```

--------------------------------

### Start Speech Recognition for Final Results

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/types.md

Starts speech recognition and waits for final results. Specifies language and maximum number of results.

```typescript
const result = await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 3
});
```

--------------------------------

### Permission Flow: Full Handling with Feedback - TypeScript

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/permission-handling.md

A comprehensive example that first checks availability, then current permissions. It handles 'granted', 'denied', and 'prompt' states, requesting permissions if necessary and providing console feedback.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function initializeSpeechRecognition() {
  // Step 1: Check availability
  const available = await SpeechRecognition.available();
  if (!available.available) {
    console.error('Speech recognition not available on this device');
    return false;
  }

  // Step 2: Check current permissions
  let perms = await SpeechRecognition.checkPermissions();

  if (perms.speechRecognition === 'granted') {
    // Already granted
    console.log('Speech recognition permission already granted');
    return true;
  }

  if (perms.speechRecognition === 'denied') {
    // Permanently denied
    console.error('Permission denied; guide user to Settings');
    // Show UI directing user to enable in Settings
    return false;
  }

  // Step 3: Permission not yet determined; request it
  if (perms.speechRecognition === 'prompt' || 
      perms.speechRecognition === 'prompt-with-rationale') {
    console.log('Requesting permissions...');
    perms = await SpeechRecognition.requestPermissions();

    if (perms.speechRecognition === 'granted') {
      console.log('Permission granted!');
      return true;
    } else {
      console.error('Permission request denied');
      return false;
    }
  }

  return false;
}

// Use it
if (await initializeSpeechRecognition()) {
  await SpeechRecognition.start();
}
```

--------------------------------

### Start Speech Recognition

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/speech-recognition-plugin.md

Initiates speech recognition. Configure options like language, maximum results, and whether to receive partial results. Permissions must be granted beforehand.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

// Final results only
const result = await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 3,
  partialResults: false
});
console.log('Final matches:', result.matches);

// With partial results
await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 5,
  partialResults: true,
  popup: false
});

SpeechRecognition.addListener('partialResults', (data) => {
  console.log('Partial match:', data.matches);
});
```

--------------------------------

### Utility Methods

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/README.md

Provides methods to check for speech recognition support, get supported languages, and determine if the service is currently active.

```APIDOC
## available()

### Description
Checks if the device supports speech recognition.

### Method
`available()`

### Returns
- `Promise<{ available: boolean }>` - A promise that resolves with an object indicating whether speech recognition is available on the device.
```

```APIDOC
## getSupportedLanguages()

### Description
Retrieves a list of language codes supported by the device's speech recognition engine.

### Method
`getSupportedLanguages()`

### Returns
- `Promise<{ languages: string[] }>` - A promise that resolves with an array of supported language codes.
```

```APIDOC
## isListening()

### Description
Checks if the speech recognition service is currently active and listening.

### Method
`isListening()`

### Returns
- `Promise<{ listening: boolean }>` - A promise that resolves with a boolean indicating whether the service is currently listening.
```

--------------------------------

### Real-Time Speech Recognition Results

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/QUICK_START.md

Example showing how to listen for partial speech recognition results in real-time. Remember to enable partialResults and disable the popup on Android.

```typescript
// Register listener before starting
const handle = await SpeechRecognition.addListener('partialResults', (data) => {
  console.log('Partial:', data.matches[0]);
});

// Start with partial results enabled
await SpeechRecognition.start({
  language: 'en-US',
  partialResults: true,
  popup: false  // Required on Android
});

// Stop when done
await SpeechRecognition.stop();
await handle.remove();
```

--------------------------------

### iOS Info.plist Setup for Speech Recognition

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/QUICK_START.md

Add these keys to your app's Info.plist file to request user permission for speech recognition and microphone access on iOS.

```xml
<key>NSSpeechRecognitionUsageDescription</key>
<string>Your reason here</string>
<key>NSMicrophoneUsageDescription</key>
<string>Your reason here</string>
```

--------------------------------

### Permission Flow: Check-Then-Use - TypeScript

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/permission-handling.md

Checks current permissions before attempting to start speech recognition. If permissions are not granted, it logs a message indicating they are required.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function startListening() {
  const perms = await SpeechRecognition.checkPermissions();

  if (perms.speechRecognition === 'granted') {
    await SpeechRecognition.start();
  } else {
    console.log('Permissions required');
  }
}
```

--------------------------------

### Start Speech Recognition with Android Dialog

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/types.md

Initiates speech recognition using the native Android dialog. Sets a custom prompt message and enables the popup.

```typescript
await SpeechRecognition.start({
  language: 'en-US',
  prompt: 'Say something...', 
  popup: true
});
```

--------------------------------

### Configure Speech Recognition Language

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/configuration.md

Starts speech recognition with a specific language. It's recommended to first check supported languages using getSupportedLanguages().

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

// Get supported languages
const langs = await SpeechRecognition.getSupportedLanguages();

// Start with specific language
await SpeechRecognition.start({
  language: 'es-ES'
});
```

--------------------------------

### Request Speech Recognition Permissions

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/errors.md

Check current permissions and request them if not granted before starting speech recognition. This ensures the user has explicitly allowed the necessary access.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

const perms = await SpeechRecognition.checkPermissions();
if (perms.speechRecognition !== 'granted') {
  const result = await SpeechRecognition.requestPermissions();
  if (result.speechRecognition === 'granted') {
    await SpeechRecognition.start();
  }
}
```

--------------------------------

### Start Speech Recognition for Partial Results

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/types.md

Enables partial results during speech recognition. Requires setting partialResults to true and popup to false. Results arrive via listener.

```typescript
await SpeechRecognition.start({
  language: 'en-US',
  maxResults: 5,
  partialResults: true,
  popup: false
});
```

--------------------------------

### Q&A Bot with Speech Input

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/common-patterns.md

Implement a simple question-answering bot that takes spoken questions and returns recognized text. Ensure proper setup with imports and asynchronous handling.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function askeQuestion(prompt: string): Promise<string | null> {
  console.log('Question:', prompt);

  const result = await SpeechRecognition.start({
    language: 'en-US',
    maxResults: 1,
    partialResults: false
  });

  return result.matches?.[0] ?? null;
}

async function qaSession() {
  const questions = [
    'What is your name?',
    'Where are you from?',
    'What is your favorite hobby?'
  ];

  const answers: Record<string, string> = {};

  for (const question of questions) {
    const answer = await askeQuestion(question);
    if (answer) {
      answers[question] = answer;
      console.log('You said:', answer);
    } else {
      console.log('No answer recognized');
    }

    // Wait 1 second between questions
    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  console.log('Summary:', answers);
}

// Usage
qaSession();

```

--------------------------------

### Get Supported Languages

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/QUICK_START.md

Retrieves a list of languages supported by the speech recognition service.

```APIDOC
## Supported Languages

### Description
Fetches the list of languages that the speech recognition engine can process.

### Method
`const langs = await SpeechRecognition.getSupportedLanguages();`

### Common Codes
`en-US`, `en-GB`, `es-ES`, `es-MX`, `fr-FR`, `de-DE`, `it-IT`, `pt-BR`, `zh-CN`, `ja-JP`
```

--------------------------------

### listeningState Event

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/events.md

Emitted when the listening state of the speech recognition changes (e.g., starts or stops).

```APIDOC
## listeningState Event

### Description
Emitted when the listening state of the speech recognition changes (e.g., starts or stops).

### Signature
```typescript
addListener(
  eventName: 'listeningState',
  listenerFunc: (data: { status: 'started' | 'stopped' }) => void
): Promise<PluginListenerHandle>
```

### Event Data

| Field | Type | Description |
|-------|------|-------------|
| `status` | `'started' | 'stopped'` | The current listening state. |

### When Fired

- When the speech recognition session starts.
- When the speech recognition session stops (either by user action or programmatically).

### Usage Example

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

const handle = await SpeechRecognition.addListener('listeningState', (data) => {
  console.log('Listening state changed:', data.status);
  // Example output:
  // "Listening state changed: started"
  // "Listening state changed: stopped"
});

// Remember to remove the listener when it's no longer needed
// await handle.remove();
```
```

--------------------------------

### Initialize Speech Recognition with Permissions

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/common-patterns.md

This snippet checks for speech recognition availability and handles permission states (granted, denied, prompt). It requests permissions if necessary before proceeding. Ensure the 'SpeechRecognition' import is present.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

async function initializeSpeechRecognition(): Promise<boolean> {
  // Check if available
  const available = await SpeechRecognition.available();
  if (!available.available) {
    console.error('Speech recognition not available');
    return false;
  }

  // Check permissions
  let perms = await SpeechRecognition.checkPermissions();

  if (perms.speechRecognition === 'granted') {
    console.log('Already have permissions');
    return true;
  }

  if (perms.speechRecognition === 'denied') {
    console.error('Permissions permanently denied');
    // User must enable in Settings
    return false;
  }

  // Request if not yet determined
  if (perms.speechRecognition === 'prompt' || 
      perms.speechRecognition === 'prompt-with-rationale') {
    perms = await SpeechRecognition.requestPermissions();
  }

  return perms.speechRecognition === 'granted';
}

// Usage
if (await initializeSpeechRecognition()) {
  console.log('Ready to use speech recognition');
} else {
  console.log('Cannot use speech recognition');
}
```

--------------------------------

### Automated Release Process

Source: https://github.com/capacitor-community/speech-recognition/blob/master/CONTRIBUTING.md

Execute this command to automatically update the plugin version and the CHANGELOG.md file. This is the first step in the publishing process.

```shell
npm run release
```

--------------------------------

### Publish to npm

Source: https://github.com/capacitor-community/speech-recognition/blob/master/CONTRIBUTING.md

After running the release script, execute this command to push changes to GitHub and publish the package to npm. Ensure you have the latest tags followed.

```shell
git push --follow-tags origin master && npm publish
```

--------------------------------

### addListener('listeningState', ...)

Source: https://github.com/capacitor-community/speech-recognition/blob/master/README.md

Called when the listening state of the speech recognition changes. This can indicate when the service starts or stops listening.

```APIDOC
## addListener listeningState

### Description
Called when listening state changed.

### Method
addListener

### Parameters
#### Event Name
- **`eventName`** (string) - Required - Must be 'listeningState'

#### Listener Function
- **`listenerFunc`** (function) - Required - A callback function that receives an object with a `status` property, which can be 'started' or 'stopped'.

### Returns
- Promise<PluginListenerHandle>
```

--------------------------------

### listeningState Event

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/events.md

This event is emitted when the listening state of the speech recognition service changes, indicating whether it has started or stopped listening.

```APIDOC
## listeningState Event

Emitted when the listening state changes (starts or stops).

### Signature

```typescript
addListener(
  eventName: 'listeningState',
  listenerFunc: (data: { status: 'started' | 'stopped' }) => void
): Promise<PluginListenerHandle>
```

### Event Data

| Field | Type | Description |
|-------|-------|-------------|
| `status` | `'started'` \| `'stopped'` | `'started'` when listening begins; `'stopped'` when listening ends. |

### When Fired

- **'started'**: Emitted when microphone input begins being recorded.
  - On iOS: After audio engine starts successfully.
  - On Android: When speech recognizer starts listening (after `onBeginningOfSpeech` callback).
  
- **'stopped'**: Emitted when listening ends.
  - On iOS: After `stop()` is called or when speech ends and audio engine stops.
  - On Android: After `stop()` is called or when recognition completes naturally.

### Platform Behavior

#### iOS

```swift
self.notifyListeners("listeningState", data: ["status": "started"])  // When audio engine starts
self.notifyListeners("listeningState", data: ["status": "stopped"]) // When audio engine stops
```

#### Android

```java
notifyListeners("listeningState", ret);  // "started" on onBeginningOfSpeech
notifyListeners("listeningState", ret);  // "stopped" on onEndOfSpeech or error
```

### Usage Example

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';

const handle = await SpeechRecognition.addListener('listeningState', (data) => {
  if (data.status === 'started') {
    console.log('Listening started');
    // Update UI to show "listening" indicator
  } else if (data.status === 'stopped') {
    console.log('Listening stopped');
    // Update UI to hide "listening" indicator
  }
});

// Start listening
await SpeechRecognition.start();

// ... later ...

await SpeechRecognition.stop();
await handle.remove();
```
```

--------------------------------

### Import Main Speech Recognition Instance

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/REFERENCE_GUIDE.md

Import the main SpeechRecognition instance for use in your application.

```typescript
import { SpeechRecognition } from '@capacitor-community/speech-recognition';
```

--------------------------------

### Request Permissions

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/README.md

Checks and requests speech recognition permissions from the user. It's recommended to call this before attempting to start speech recognition.

```APIDOC
## checkPermissions()

### Description
Checks the current status of speech recognition permissions.

### Method
`checkPermissions()`

### Returns
- `Promise<{ speechRecognition: 'granted' | 'denied' | 'prompt' | 'unavailable' }>` - An object indicating the permission status for speech recognition.
```

```APIDOC
## requestPermissions()

### Description
Requests speech recognition permissions from the user.

### Method
`requestPermissions()`

### Returns
- `Promise<{ speechRecognition: 'granted' | 'denied' | 'prompt' | 'unavailable' }>` - An object indicating the permission status after the request.
```

--------------------------------

### Build Plugin Web Assets

Source: https://github.com/capacitor-community/speech-recognition/blob/master/CONTRIBUTING.md

Use this script to build the plugin's web assets and generate API documentation. It compiles TypeScript to ESM JavaScript and bundles it into a single file for different application types.

```shell
npm run build
```

--------------------------------

### addListener('partialResults', ...)

Source: https://github.com/capacitor-community/speech-recognition/blob/master/README.md

Adds a listener for partial speech recognition results. This event is emitted when `partialResults` is enabled in the `start` method.

```APIDOC
## addListener('partialResults', ...)

### Description
Listen to partial results.

### Method
`addListener('partialResults', callback)`

### Parameters
#### Callback Function
- **`callback`** (function) - Function to be called with the partial results data.
  - **`data`** (object) - Contains the `matches` array with partial recognition results.

### Example
```typescript
SpeechRecognition.addListener('partialResults', (data: any) => {
  console.log('partialResults was fired', data.matches);
});
```
```

--------------------------------

### Lint and Format Code

Source: https://github.com/capacitor-community/speech-recognition/blob/master/CONTRIBUTING.md

Run these commands to check code formatting and quality. They integrate with ESLint, Prettier, and SwiftLint, and can auto-fix issues.

```shell
npm run lint
```

```shell
npm run fmt
```

--------------------------------

### Ensure Permissions

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/api-reference/permission-handling.md

A combined operation that first checks existing permissions and then requests them if necessary. It guides the user if permissions are ultimately denied.

```APIDOC
## ensurePermissions()

### Description
Ensures that the application has the required permissions for speech recognition by first checking and then requesting if needed.

### Method
`ensurePermissions()`

### Return Value
`PermissionStatus` - The final permission status. If the status is 'denied' after the process, the user should be guided accordingly.
```

--------------------------------

### File Structure Overview

Source: https://github.com/capacitor-community/speech-recognition/blob/master/_autodocs/INDEX.md

This code block outlines the directory structure of the speech-recognition plugin project.

```tree
output/
├── INDEX.md                          # This file
├── REFERENCE_GUIDE.md                # Overview and organization
├── types.md                          # Type definitions
├── configuration.md                  # Setup and options
├── errors.md                         # Error reference
├── common-patterns.md                # Usage examples and patterns
└── api-reference/
    ├── speech-recognition-plugin.md  # Main API reference
    ├── events.md                     # Event system
    ├── permission-handling.md        # Permission guide
    └── web-implementation.md         # Web platform stub
```