Chat Voice Input

A composable voice input for chat composers, with a microphone button, live waveform, timer, and built-in loading, recording, and error states.

Use the AI SDK adapter, native browser speech recognition, or connect any service or local model through the Transcriber interface. The component coordinates capture, stopping, empty results, failures, and cleanup. Audio is never stored by the package.

Live demo

Install

pnpm add chat-voice-input

React 18 or newer is required.

Use the AI SDK transcriber

The optional AI SDK adapter streams 24 kHz PCM audio through Vercel AI Gateway:

pnpm add ai @ai-sdk/gateway

import { useState } from "react";
import ChatVoiceInput from "chat-voice-input";
import { createAiSdkTranscriber } from "chat-voice-input/ai-sdk";
import "chat-voice-input/style.css";

const transcriber = createAiSdkTranscriber();

function Composer() {
  const [value, setValue] = useState("");

  function appendTranscript(delta: string): void {
    setValue((current) => current + delta);
  }

  return (
    <>
      <textarea onChange={(event) => setValue(event.target.value)} value={value} />
      <ChatVoiceInput
        disabled={false}
        onDelta={appendTranscript}
        transcriber={transcriber}
      />
    </>
  );
}

ChatVoiceInput emits transcription deltas without owning or modifying the editor value. This example appends each delta verbatim; spacing and punctuation come from the transcriber. The consumer can instead decide where and how to apply each delta.

The adapter requests a short-lived token from POST /api/transcription. Add that route to your server:

import { createTranscriptionTokenResponse } from "chat-voice-input/server";

export function POST(): Promise<Response> {
  return createTranscriptionTokenResponse({
    apiKey: process.env.AI_GATEWAY_API_KEY,
  });
}

The provider requests the microphone immediately. The adapter starts capturing PCM and requests its token as soon as the stream is available. Audio captured while the token is pending is consumed when transcription connects.

Keep AI_GATEWAY_API_KEY on the server. Protect the token route with authentication and rate limiting because it spends against your Gateway account. Use tokenEndpoint to configure another route.

Use the native browser transcriber

For a setup without a backend, API key, or additional dependency, use the browser's built-in speech recognition:

import ChatVoiceInput, { createNativeTranscriber } from "chat-voice-input";

const transcriber = createNativeTranscriber();

Pass it to ChatVoiceInput exactly like the AI SDK adapter. You can optionally set the recognition language; otherwise it uses navigator.language:

const transcriber = createNativeTranscriber({ language: "es-ES" });

This adapter uses SpeechRecognition or webkitSpeechRecognition, so availability and transcription quality depend on the browser. On WebKit, speech recognition controls its own audio capture because the browser API cannot consume a provided MediaStream.

Use a custom transcriber

Implement the small Transcriber contract and pass the object to the component:

import type { Transcriber } from "chat-voice-input";

const transcriber: Transcriber = {
  async start({ stream, onDelta, signal }) {
    const recording = await startYourTranscription({ stream, onDelta, signal });

    return {
      stop: recording.stop,
      text: recording.text,
    };
  },
};

The provider opens and closes the microphone. The transcriber receives that stream with an abort signal and a callback for text deltas. It returns a stop function and a promise for the final text.

If your service needs PCM, use the same converter as the AI SDK adapter:

import { createPcmStream } from "chat-voice-input/audio";

const pcm = await createPcmStream(stream); // 24 kHz s16le by default

Pass { sampleRate } to select another rate. Closing the PCM stream releases only its audio graph; microphone ownership stays with the provider.

Compose your own layout

import ChatVoiceInput, { useChatVoiceInput } from "chat-voice-input";

<ChatVoiceInput.Provider
  disabled={disabled}
  onDelta={appendTranscript}
  transcriber={transcriber}
>
  <ChatVoiceInput.Error />
  <ChatVoiceInput.Waveform />
  <ChatVoiceInput.Timer />
  <ChatVoiceInput.Button />
</ChatVoiceInput.Provider>;

useChatVoiceInput() exposes status, stream, start, and stop. Every component is also available as a named export.

The optional stylesheet contains only the built-in control styles and exposes --chat-voice-input-button-background, --chat-voice-input-button-background-hover, and --chat-voice-input-muted for theming. The component does not own its surrounding layout.

Covered edge cases

ChatVoiceInputProvider handles every Transcriber through the same lifecycle. Adapters report microphone and transcription failures through that contract. Any failure shows Voice input is unavailable. and changes the button to Retry.

Scenario	Behavior
Voice input is disabled	Disables Start; does not call the transcriber
Waiting for microphone permission or transcriber start	Shows Loading; disables the button; shows no recording UI
Capture and transcription are active	Shows Stop, waveform, and timer
User denies microphone permission	Rejects the start; shows the error and Retry
Native transcriber is selected but unavailable	Rejects before requesting the microphone; shows the error and Retry
Microphone is unavailable or busy	Rejects the start; shows the error and Retry
Transcriber emits text	Calls onDelta immediately
User presses Stop	Stops capture; shows Loading until final text settles
Its containing form is submitted	Stops an active or pending session
Transcriber finishes on its own	Stops capture, emits final text if no deltas arrived, and returns to idle
Transcriber ends without text	Returns to idle without an error or delta
Remote transcriber is still connecting	Captures audio; shows recording only after the adapter confirms it started
Transcriber fails during recording	Aborts capture; does not retract emitted deltas; shows the error and Retry
Microphone disconnects during recording	Aborts transcription; does not retract emitted deltas; shows the error and Retry
Voice input is disabled or unmounted while active	Aborts capture and ignores late results

iOS limitation

In Safari on iOS and iPadOS, native SpeechRecognition can conflict with the component's microphone stream and mute an audio track. After stopping, later recording or recognition attempts may receive no audio. See the WebKit reports for SpeechRecognition muting an existing track and subsequent captures producing no audio. Prefer a stream-based transcriber such as the AI SDK adapter on these platforms.

Development

pnpm install
pnpm check
pnpm test
pnpm build

Run the demo with pnpm demo. Its selector switches between native browser transcription and the streaming AI SDK models available through AI Gateway.

License

MIT