Soniox
SDKs

React SDK

Build speech-to-text and text-to-speech workflows in React with real-time APIs.

Soniox React SDK provides React hooks and components for real-time speech-to-text and text-to-speech, built on top of the Web SDK. It lets you:

  • Capture audio from the user's microphone with a single hook
  • Stream audio to Soniox in real time
  • Receive transcription and translation results as reactive state
  • Generate speech from text with a single useTts hook

Quickstart

Install

Install via your preferred package manager:

npm install @soniox/react
yarn add @soniox/react
pnpm add @soniox/react
bun add @soniox/react

Set up your temporary API key endpoint

In client environment (browser, mobile app, React Native, etc.), you don't want to expose your API key to the client. For this reason, you can create a temporary API key endpoint on your server and use it to issue temporary API keys for the client.

For example, you can use our Node SDK to create a temporary API key endpoint.

import express from 'express';
import { SonioxNodeClient } from '@soniox/node';

const app = express();
const client = new SonioxNodeClient(); // reads SONIOX_API_KEY from env

// Create a temporary API key endpoint
app.post('/tmp-key', async (_req, res) => {
  try {
    const { api_key, expires_at } = await client.auth.createTemporaryKey({
      usage_type: 'transcribe_websocket',
      expires_in_seconds: 300, // 1..3600
    });

    res.json({ api_key, expires_at });
  } catch (err) {
    res.status(500).json({ error: err instanceof Error ? err.message : 'Failed to create temporary key' });
  }
});

app.listen(3000, () => {
  console.log('Server listening on http://localhost:3000');
});

Read more about our Node SDK and Temporary API keys

Create your first real-time session

import { SonioxProvider, useRecording } from "@soniox/react";

// Fetch a temporary API key (and optional region / URL overrides) from your server
async function fetchSttConfig() {
  const res = await fetch("/tmp-key", { method: "POST" });
  const { api_key } = await res.json();
  return { api_key };
}

function App() {
  return (
    // Wrap your app with a SonioxProvider and pass a config resolver
    <SonioxProvider config={fetchSttConfig}>
      <Transcription />
    </SonioxProvider>
  );
}

function Transcription() {
  // Create a recording session
  const { state, finalText, partialText, start, stop } = useRecording({
    model: "stt-rt-v4",
  });

  return (
    <div>
      <p>
        <span>{finalText}</span>
        <span style={{ color: "gray" }}>{partialText}</span>
      </p>
      <p>State: {state}</p>
      {state === "recording" || state === "connecting" || state === "starting" ? (
        <button onClick={() => void stop()}>Stop</button>
      ) : (
        <button onClick={start}>Start</button>
      )}
    </div>
  );
}

Learn more about Real-time transcription

Generate your first speech

import { useRef } from "react";
import { useTts } from "@soniox/react";

async function fetchTtsConfig() {
  // Your server should issue a temporary key with usage_type: 'tts_rt'
  const res = await fetch("/tts-tmp-key");
  const { api_key } = await res.json();
  return { api_key };
}

function SpeakButton() {
  const audioRef = useRef<Uint8Array[]>([]);

  const { speak, isSpeaking } = useTts({
    config: fetchTtsConfig,
    voice: "Adrian",
    audio_format: "wav",
    onAudio: (chunk) => audioRef.current.push(chunk),
    onTerminated: () => {
      const blob = new Blob(audioRef.current, { type: "audio/wav" });
      new Audio(URL.createObjectURL(blob)).play();
      audioRef.current = [];
    },
  });

  return (
    <button onClick={() => speak("Hello from Soniox React SDK!")} disabled={isSpeaking}>
      Speak
    </button>
  );
}

Learn more about Real-time speech generation.

Next.js example

Transcription and translation example with temporary API key generation.

Next steps

Types

Soniox Client SDK — Types Reference

Real-time transcription

Create and manage real-time speech-to-text sessions with the Soniox React SDK