### Python SDK Setup and Real-time TTS Example

Source: https://soniox.com/docs/tts/get-started

Set up a Python virtual environment, install dependencies, and run a real-time Text-to-Speech example using the WebSocket API.

```bash
cd python_sdk

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Real-time TTS example (WebSocket)
python soniox_sdk_realtime.py --line "Hello from Soniox realtime Text-to-Speech."
```

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

### Node.js SDK Setup and Real-time TTS Example

Source: https://soniox.com/docs/tts/get-started

Install Node.js dependencies and run a real-time Text-to-Speech example using the WebSocket API.

```bash
cd nodejs_sdk

# Install dependencies
npm install

# Real-time TTS example (WebSocket)
node soniox_sdk_realtime.js --line "Hello from Soniox realtime Text-to-Speech."
```

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

### Node.js Client Setup and Real-time TTS Example

Source: https://soniox.com/docs/tts/get-started

Install Node.js dependencies and run a real-time Text-to-Speech example using the WebSocket API.

```bash
cd nodejs

# Install dependencies
npm install

# Real-time TTS example (WebSocket)
node soniox_realtime.js --line "Hello from Soniox websocket Text-to-Speech."
```

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

### Python Client Setup and Real-time TTS Example

Source: https://soniox.com/docs/tts/get-started

Set up a Python virtual environment, install requirements, and execute a real-time Text-to-Speech example via WebSocket.

```bash
cd python

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Real-time TTS example (WebSocket)
python soniox_realtime.py --line "Hello from Soniox websocket Text-to-Speech."
```

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

### Set up Node.js SDK Environment and Run Examples

Source: https://soniox.com/docs/stt/get-started

Install Node.js SDK dependencies and run real-time and asynchronous transcription examples using the provided command-line arguments.

```bash
cd nodejs_sdk

# Install dependencies
npm install

# Real-time examples
node soniox_sdk_realtime.js --audio_path ../assets/coffee_shop.mp3

# Async examples
node soniox_sdk_async.js --audio_url "https://soniox.com/media/examples/coffee_shop.mp3"
node soniox_sdk_async.js --audio_path ../assets/coffee_shop.mp3
```

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

### Clone Repository and Install Dependencies

Source: https://soniox.com/docs/integrations/twilio

Clone the example repository and install the necessary Python dependencies.

```bash
git clone https://github.com/soniox/soniox-twilio-realtime-transcription.git
cd soniox-twilio-realtime-transcription
pip install -r requirements.txt
```

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

### Set up Python SDK Environment and Run Examples

Source: https://soniox.com/docs/stt/get-started

Configure the Python SDK environment by creating a virtual environment, activating it, and installing dependencies. Then, run real-time and asynchronous transcription examples.

```bash
cd python_sdk

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Real-time examples
python soniox_sdk_realtime.py --audio_path ../assets/coffee_shop.mp3

# Async examples
python soniox_sdk_async.py --audio_url "https://soniox.com/media/examples/coffee_shop.mp3"
python soniox_sdk_async.py --audio_path ../assets/coffee_shop.mp3
```

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

### Set up Node.js Project Environment and Run Examples

Source: https://soniox.com/docs/stt/get-started

Install Node.js project dependencies and execute real-time and asynchronous transcription scripts. Examples include processing audio from URLs or local files.

```bash
cd nodejs

# Install dependencies
npm install

# Real-time examples
node soniox_realtime.js --audio_path ../assets/coffee_shop.mp3

# Async examples
node soniox_async.js --audio_url "https://soniox.com/media/examples/coffee_shop.mp3"
node soniox_async.js --audio_path ../assets/coffee_shop.mp3
```

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

### Set up Python Project Environment and Run Examples

Source: https://soniox.com/docs/stt/get-started

Configure a Python project environment for running real-time and asynchronous speech-to-text examples. This includes setting up a virtual environment and installing requirements.

```bash
cd python

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Real-time examples
python soniox_realtime.py --audio_path ../assets/coffee_shop.mp3

# Async examples
python soniox_async.py --audio_url "https://soniox.com/media/examples/coffee_shop.mp3"
python soniox_async.py --audio_path ../assets/coffee_shop.mp3
```

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

### Full Agent Workflow Example

Source: https://soniox.com/docs/llms-full.txt

This comprehensive example includes setup, context, mock calendar, and detailed agent implementations for a dental appointment booking system. It showcases advanced features like context objects and detailed instructions.

```python
import asyncio
import logging
from datetime import date

from dotenv import load_dotenv

from livekit.agents import (
    Agent,
    AgentSession,
    JobContext,
    TurnHandlingOptions,
    WorkerOptions,
    cli,
    function_tool,
    get_job_context,
)
from livekit.plugins import openai, silero, soniox
from livekit.plugins.soniox import (
    ContextGeneralItem,
    ContextObject,
    STTOptions,
)

load_dotenv()
logger = logging.getLogger("voice-agent")

TODAY = date.today().isoformat()

CLINIC_CONTEXT = ContextObject(
    terms=["Bright Smile Dental", "checkup", "cavity", "crown", "X-ray"],
    general=[
        ContextGeneralItem(key="domain", value="Dental practice"),
        ContextGeneralItem(key="topic", value="Booking an appointment"),
    ],
)


class DentalCalendar:
    """Mock calendar. Replace with your real booking system."""

    # The same four times are offered every day.
    DAILY_SCHEDULE = ["09:00", "10:30", "14:00", "15:30"]

    def __init__(self) -> None:
        # ISO datetimes that are already booked.
        self.booked: set[str] = {"2026-05-12T10:30"}
        self._next_confirmation = 1000

    async def find_slots(self, date: str) -> list[str]:
        """Return open ISO datetimes for the given date."""
        slots_for_day = [f"{date}T{time}" for time in self.DAILY_SCHEDULE]
        return [slot for slot in slots_for_day if slot not in self.booked]

    async def book(self, name: str, slot: str, reason: str) -> str:
        """Mark a slot as booked and return a confirmation ID."""
        self.booked.add(slot)
        self._next_confirmation += 1
        return f"DENT-{self._next_confirmation}"


calendar = DentalCalendar()


class GreetAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions=(
                "You are a friendly receptionist at Bright Smile Dental. "
                "Greet the caller and ask for their full name. "
                "Once they provide it, call collect_name. "
                "Keep replies short and natural. They will be spoken aloud."
            ),
        )

    async def on_enter(self) -> None:
        self.session.generate_reply(
            instructions="Greet the caller and ask for their full name."
        )

    @function_tool
    async def collect_name(self, name: str) -> Agent:
        """Record the caller's name and hand off to the booking agent.

```

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

### Python SDK: Text-to-Speech Example

Source: https://soniox.com/docs/api-reference/tts/websocket-api

Example of using the Python SDK for text-to-speech functionality. Ensure you have completed the 'Get started' steps.

```python
from soniox import SonioxClient

client = SonioxClient(api_key="YOUR_API_KEY")

with open("audio.wav", "wb") as f:
    for chunk in client.audio.speech_to_text_stream("audio.wav"):
        f.write(chunk)

```

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

### Run Node.js SDK Text-to-Speech Examples

Source: https://soniox.com/docs/llms-full.txt

Install Node.js dependencies and run real-time (WebSocket) and RESTful Text-to-Speech examples using the Soniox Node.js SDK.

```sh
cd nodejs_sdk

# Install dependencies
npm install

# Real-time TTS example (WebSocket)
node soniox_sdk_realtime.js --line "Hello from Soniox realtime Text-to-Speech."

# REST TTS example
node soniox_sdk_rest.js --text "Hello from Soniox REST Text-to-Speech."
```

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

### Run Node.js Text-to-Speech Examples

Source: https://soniox.com/docs/llms-full.txt

Install Node.js dependencies and run real-time (WebSocket) and RESTful Text-to-Speech examples using direct Node.js scripts.

```sh
cd nodejs

# Install dependencies
npm install

# Real-time TTS example (WebSocket)
node soniox_realtime.js --line "Hello from Soniox websocket Text-to-Speech."

# REST TTS example
node soniox_rest.js --text "Hello from Soniox REST Text-to-Speech."
```

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

### Python SDK REST TTS Example

Source: https://soniox.com/docs/tts/get-started

Run a Text-to-Speech example using the REST API with the Python SDK. Ensure environment setup and dependencies are installed.

```bash
python soniox_sdk_rest.py --text "Hello from Soniox REST Text-to-Speech."
```

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

### Node.js SDK: Text-to-Speech Example

Source: https://soniox.com/docs/api-reference/tts/websocket-api

Example of using the Node.js SDK for text-to-speech functionality. Ensure you have completed the 'Get started' steps.

```javascript
import { SonioxClient } from "soniox";

const client = new SonioxClient({ apiKey: "YOUR_API_KEY" });

const stream = await client.audio.speechToTextStream("audio.wav");

for await (const chunk of stream) {
  // process chunk
}

```

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

### Python Client REST TTS Example

Source: https://soniox.com/docs/tts/get-started

Run a Text-to-Speech example using the REST API with the Python client. Ensure environment setup and dependencies are installed.

```bash
python soniox_rest.py --text "Hello from Soniox REST Text-to-Speech."
```

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

### Install and Run ngrok Tunnel

Source: https://soniox.com/docs/sdk/node-SDK/stt/webhooks

Install ngrok, authenticate with your token, and start a tunnel to expose your local server. This provides a stable public URL for webhook testing.

```bash
# macOS
brew install ngrok

# Authenticate (one-time setup)
ngrok config add-authtoken <your-token>

# Start a tunnel to your local server on port 3000
ngrok http 3000
```

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

### Node.js SDK REST TTS Example

Source: https://soniox.com/docs/tts/get-started

Run a Text-to-Speech example using the REST API with the Node.js SDK. Ensure dependencies are installed.

```bash
node soniox_sdk_rest.js --text "Hello from Soniox REST Text-to-Speech."
```

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

### Install and Run Cloudflare Tunnel

Source: https://soniox.com/docs/sdk/node-SDK/stt/webhooks

Install the Cloudflare Tunnel CLI and start a tunnel to expose your local development server. This is useful for testing webhooks locally by providing a public URL.

```bash
# macOS
brew install cloudflared

# Start a tunnel to your local server on port 3000
cloudflared tunnel --url http://localhost:3000
```

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

### Install React SDK with bun

Source: https://soniox.com/docs/sdk/react-SDK

Install the Soniox React SDK using bun.

```bash
bun add @soniox/react
```

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

### Real-time TTS Generation with Node SDK (Single Stream)

Source: https://soniox.com/docs/llms-full.txt

Quickstart example for real-time TTS using the Node SDK. It sends all text at once and collects the resulting audio chunks.

```typescript
import { writeFileSync } from "node:fs";
import { SonioxNodeClient } from "@soniox/node";

const client = new SonioxNodeClient();

const stream = await client.realtime.tts({
  voice: "Adrian",
  model: "tts-rt-v1",
  language: "en",
  audio_format: "wav",
});

// Send all the text and mark the stream as finished.
stream.sendText(
  "Hello from Soniox real-time text-to-speech. This is a single-stream example.",
  { end: true },
);

// Collect audio as it arrives.
const chunks: Uint8Array[] = [];
for await (const chunk of stream) {
  chunks.push(chunk);
}

const audio = Buffer.concat(chunks);
writeFileSync("tts_realtime.wav", audio);

console.log(`Wrote ${audio.byteLength} bytes`);
```

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

### Install React Native SDK with bun

Source: https://soniox.com/docs/sdk/react-native-SDK

Install the Soniox React and Client packages using bun.

```bash
bun add @soniox/react @soniox/client
```

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

### Install React SDK with npm

Source: https://soniox.com/docs/sdk/react-SDK

Install the Soniox React SDK using npm.

```bash
npm install @soniox/react
```

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

### Run Soniox Realtime Session (JavaScript)

Source: https://soniox.com/docs/llms-full.txt

This JavaScript example demonstrates how to set up and run a realtime Soniox session. It handles audio streaming, session events, and error management. Ensure you have the necessary Node.js environment and dependencies installed.

```javascript
              // Flush any remaining tokens after the session ends.
              const utterance = buffer.markEndpoint();
              if (utterance) {
                console.log(renderUtterance(utterance));
              }
              console.log("Session finished.");
            });

            session.on("error", (err) => {
              console.error("Session error:", err);
            });

            // Connect to the Soniox realtime API.
            console.log("Connecting to Soniox...");
            await session.connect();
            console.log("Session started.");

            // Stream the audio file and finish when done.
            await session.sendStream(
              fs.createReadStream(audioPath, { highWaterMark: 3840 }),
              { pace_ms: 120, finish: true },
            );
          }

          async function main() {
            const { values: argv } = parseArgs({
              options: {
                audio_path: { type: "string" },
                audio_format: { type: "string", default: "auto" },
                translation: { type: "string", default: "none" },
              },
            });

            if (!argv.audio_path) {
              throw new Error("Missing --audio_path argument.");
            }

            await runSession(argv.audio_path, argv.audio_format, argv.translation);
          }

          main().catch((err) => {
            console.error("Error:", err.message);
            process.exit(1);
          });

          
```

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

### Install Soniox Vercel AI SDK Provider

Source: https://soniox.com/docs/integrations/vercel-ai-sdk

Install the necessary package using npm.

```bash
npm install @soniox/vercel-ai-sdk-provider
```

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

### Install React SDK with yarn

Source: https://soniox.com/docs/sdk/react-SDK

Install the Soniox React SDK using yarn.

```bash
yarn add @soniox/react
```

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

### Install React SDK with pnpm

Source: https://soniox.com/docs/sdk/react-SDK

Install the Soniox React SDK using pnpm.

```bash
pnpm add @soniox/react
```

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

### Configure and Run the Application Entrypoint

Source: https://soniox.com/docs/llms-full.txt

This snippet demonstrates the main entry point for the application, setting up the AgentSession with specific configurations for VAD, STT, LLM, TTS, and turn handling. It then starts the session with a GreetAgent and runs the application using cli.run_app.

```python
async def entrypoint(ctx: JobContext) -> None:
    await ctx.connect()

    session = AgentSession(
        vad=silero.VAD.load(),
        stt=soniox.STT(
            params=STTOptions(
                language_hints=["en"],
                context=CLINIC_CONTEXT,
                max_endpoint_delay_ms=1000,
            ),
        ),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=soniox.TTS(voice="Maya"),
        turn_handling=TurnHandlingOptions(
            turn_detection="stt",
            interruption={"mode": "vad"},
        ),
    )

    await session.start(agent=GreetAgent(), room=ctx.room)


if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

```

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

### Node.js Client REST TTS Example

Source: https://soniox.com/docs/tts/get-started

Run a Text-to-Speech example using the REST API with the Node.js client. Ensure dependencies are installed.

```bash
node soniox_rest.js --text "Hello from Soniox REST Text-to-Speech."
```

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

### Basic Pipeline Setup

Source: https://soniox.com/docs/llms-full.txt

Initializes the LLM context and aggregators, then defines a pipeline with input, STT, aggregators, LLM, TTS, output, and assistant aggregator.

```python
context = LLMContext()
user_aggregator, assistant_aggregator = LLMContextAggregatorPair(context)

pipeline = Pipeline([
    transport.input(),
    stt,
    user_aggregator,
    llm,
    tts,
    transport.output(),
    assistant_aggregator,
])

task = PipelineTask(pipeline)
```

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

### Set up Soniox Client and Run Session

Source: https://soniox.com/docs/translation/stt-translation/rt-translation

Configure the Soniox client, parse command-line arguments for audio input and translation settings, and initiate a real-time translation session. Ensure the SONIOX_API_KEY environment variable is set.

```python
def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--audio_path", type=str)
    parser.add_argument("--audio_format", default="auto")
    parser.add_argument("--translation", default="none")
    args = parser.parse_args()

    api_key = os.environ.get("SONIOX_API_KEY")
    if api_key is None:
        raise RuntimeError("Missing SONIOX_API_KEY.")

    client = SonioxClient()

    run_session(client, args.audio_path, args.audio_format, args.translation)


if __name__ == "__main__":
    main()
```

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

### Quickstart: Generate Speech to File

Source: https://soniox.com/docs/sdk/python-SDK/tts/rest-speech-generation

Use the `generate_to_file` method for writing audio output directly to disk. This is a convenient way to save generated speech.

```python
import asyncio
from soniox import AsyncSonioxClient

async def main() -> None:
    client = AsyncSonioxClient()
    try:
        written = await client.tts.generate_to_file(
            "tts_async_output.wav",
            text="Hello from the Soniox Python SDK async TTS example.",
            model="tts-rt-v1",
            language="en",
            voice="Adrian",
            audio_format="wav",
        )
        print(f"Wrote {written} bytes")
    finally:
        await client.aclose()

asyncio.run(main())
```

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

### Quickstart: Async Translation with Audio URL

Source: https://soniox.com/docs/sdk/node-SDK/stt/async-translation

Initiates an asynchronous translation job from an audio URL and waits for completion. Useful for translating pre-existing audio files hosted online.

```javascript
const job = await client.stt.translate({
  audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
  to: 'es',
  wait: true,
});

console.log(job.translation?.translation_text);
```

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

### Install Soniox LiveKit Agent

Source: https://soniox.com/docs/integrations/livekit/migrate

Install the Soniox extra for LiveKit Agents using pip. This command ensures you have the necessary packages to integrate Soniox with your LiveKit setup.

```bash
pip install "livekit-agents[soniox]~=1.5"
```

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

### Command-line Examples (Shell)

Source: https://soniox.com/docs/llms-full.txt

Demonstrates how to run the JavaScript SDK script from the terminal for various operations like transcribing files or deleting data.

```sh
# Transcribe file from URL
node soniox_sdk_async.js --audio_url "https://soniox.com/media/examples/coffee_shop.mp3"

# Transcribe from local file
node soniox_sdk_async.js --audio_path ../assets/coffee_shop.mp3

# Delete all uploaded files
node soniox_sdk_async.js --delete_all_files

# Delete all transcriptions
node soniox_sdk_async.js --delete_all_transcriptions
```

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

### Quickstart: Generate Speech to File

Source: https://soniox.com/docs/sdk/node-SDK/tts/rest-speech-generation

The simplest way to generate speech. The SDK handles API calls, response streaming, and writing to a file. The API key is read from the SONIOX_API_KEY environment variable.

```typescript
import { SonioxNodeClient } from "@soniox/node";

// The API key is read from the SONIOX_API_KEY environment variable.
const client = new SonioxNodeClient();

const bytesWritten = await client.tts.generateToFile("hello.wav", {
  text: "Hello from the Soniox Node SDK text-to-speech example.",
  voice: "Adrian",
  model: "tts-rt-v1",
  language: "en",
  audio_format: "wav",
});

console.log(`Wrote ${bytesWritten} bytes`);
```

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

### AudioSource Interface and Example

Source: https://soniox.com/docs/sdk/web-SDK/reference/types

Defines the platform-agnostic interface for audio sources, including methods for starting, stopping, pausing, and resuming capture. Includes examples of built-in and custom implementations.

```typescript
// Built-in browser source
const source = new MicrophoneSource();

// Custom source (e.g., React Native)
class MyAudioSource implements AudioSource {
  async start(handlers: AudioSourceHandlers) { ... }
  stop() { ... }
}
```

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

### Quickstart: Generate Speech and Play Audio

Source: https://soniox.com/docs/sdk/web-SDK/tts/rest-speech-generation

Initializes the SonioxClient with a configuration resolver for temporary keys and generates speech from text. The resulting audio is played directly in the browser.

```typescript
import { SonioxClient } from "@soniox/client";

const client = new SonioxClient({
  config: async () => {
    const res = await fetch("/tts-tmp-key");
    const { api_key } = await res.json();
    return { api_key };
  },
});

const audio = await client.tts.generate({
  text: "Hello from the Soniox Web SDK text-to-speech example.",
  voice: "Adrian",
  model: "tts-rt-v1",
  language: "en",
  audio_format: "wav",
});

const blob = new Blob([audio], { type: "audio/wav" });
const audioEl = new Audio(URL.createObjectURL(blob));
await audioEl.play();
```

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

### Generate to File (Quickstart)

Source: https://soniox.com/docs/sdk/python-SDK/tts/rest-speech-generation

Demonstrates the `generate_to_file` method for writing audio output directly to disk using the asynchronous client.

```APIDOC
## Generate to File (Quickstart)

### Description
Use the `generate_to_file` method for writing audio output directly to disk.

### Method
`await client.tts.generate_to_file()`

### Parameters
- **filename** (string) - Required - The name of the file to write the audio to.
- **text** (string) - Required - The text to convert to speech.
- **model** (string) - Optional - The TTS model to use (e.g., "tts-rt-v1").
- **language** (string) - Optional - The language of the text (e.g., "en").
- **voice** (string) - Optional - The voice to use for generation (e.g., "Adrian").
- **audio_format** (string) - Optional - The format of the audio output (e.g., "wav").

### Request Example
```python
import asyncio
from soniox import AsyncSonioxClient

async def main() -> None:
    client = AsyncSonioxClient()
    try:
        written = await client.tts.generate_to_file(
            "tts_async_output.wav",
            text="Hello from the Soniox Python SDK async TTS example.",
            model="tts-rt-v1",
            language="en",
            voice="Adrian",
            audio_format="wav",
        )
        print(f"Wrote {written} bytes")
    finally:
        await client.aclose()

asyncio.run(main())
```
```

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

### Configure Server Environment

Source: https://soniox.com/docs/integrations/twilio

Copy the example environment file and update it with your Twilio and Soniox API credentials.

```bash
cp .env.example .env
```

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

### Example: Refresh SonioxTranscription

Source: https://soniox.com/docs/sdk/node-SDK/reference/classes

Demonstrates how to get a transcription and then refresh it to obtain the latest status information.

```typescript
let transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
transcription = await transcription.refresh();
console.log(transcription.status);
```

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

### Run Python SDK Text-to-Speech Examples

Source: https://soniox.com/docs/llms-full.txt

Set up a Python virtual environment and run real-time (WebSocket) and RESTful Text-to-Speech examples using the Soniox Python SDK.

```sh
cd python_sdk

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Real-time TTS example (WebSocket)
python soniox_sdk_realtime.py --line "Hello from Soniox realtime Text-to-Speech."

# REST TTS example
python soniox_sdk_rest.py --text "Hello from Soniox REST Text-to-Speech."
```

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

### AudioSource start() Method

Source: https://soniox.com/docs/sdk/web-SDK/reference/types

Starts capturing audio and delivering chunks via the provided handlers. Throws specific errors if capture cannot begin due to permissions, device issues, or unsupported features.

```typescript
start(handlers): Promise<void>;
```

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

### Run Python Text-to-Speech Examples

Source: https://soniox.com/docs/llms-full.txt

Set up a Python virtual environment and run real-time (WebSocket) and RESTful Text-to-Speech examples using direct Python scripts.

```sh
cd python

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Real-time TTS example (WebSocket)
python soniox_realtime.py --line "Hello from Soniox websocket Text-to-Speech."

# REST TTS example
python soniox_rest.py --text "Hello from Soniox REST Text-to-Speech."
```

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

### Get Files Count Response (200 OK)

Source: https://soniox.com/docs/api-reference/stt/files/get_files_count

Example of a successful response containing the total number of files and a breakdown by source.

```json
{
  "playground": 8,
  "public_api": 42,
  "total": 50
}
```

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

### Run Two-way Translation with Node.js SDK

Source: https://soniox.com/docs/translation/get-started

Execute a two-way speech-to-text translation example using the Node.js SDK. Ensure you install the necessary dependencies.

```bash
cd nodejs_sdk

# Install dependencies
npm install
```

```javascript
node soniox_sdk_realtime.js --audio_path ../assets/two_way_translation.mp3 --translation two_way
```

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

### AudioSource.start()

Source: https://soniox.com/docs/llms-full.txt

Starts capturing audio and delivers chunks via handlers.onData. Throws errors if capture cannot begin.

```APIDOC
## start()

### Description
Start capturing audio.

### Method
`start(handlers): Promise<void>;`

### Parameters
#### Parameters
- `handlers` (AudioSourceHandlers) - Callbacks for audio data and errors

### Returns
`Promise<void>`

### Throws
- `AudioPermissionError` if microphone access is denied
- `AudioDeviceError` if no audio device is found
- `AudioUnavailableError` if audio capture is not supported
```

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

### Run One-way Translation with Node.js SDK

Source: https://soniox.com/docs/translation/get-started

Execute a one-way speech-to-text translation example using the Node.js SDK. Ensure you install the necessary dependencies.

```bash
cd nodejs_sdk

# Install dependencies
npm install
```

```javascript
node soniox_sdk_realtime.js --audio_path ../assets/coffee_shop.mp3 --translation one_way
```

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

### SonioxClient Initialization and Real-time Recording

Source: https://soniox.com/docs/llms-full.txt

Demonstrates how to initialize the SonioxClient with an asynchronous configuration and how to perform real-time speech-to-text recording using the microphone. Includes examples for both high-level recording and low-level session access.

```typescript
// Recommended: async config with region
const client = new SonioxClient({
  config: async () => {
    const res = await fetch('/api/soniox-config', { method: 'POST' });
    return await res.json(); // { api_key, region }
  },
});

// High-level: record from microphone
const recording = client.realtime.record({ model: 'stt-rt-v4' });
recording.on('result', (r) => console.log(r.tokens));
await recording.stop();

// Low-level: direct session access
const session = client.realtime.stt({ model: 'stt-rt-v4' }, { api_key: key });
await session.connect();
```

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

### Get Transcriptions Response Example

Source: https://soniox.com/docs/api-reference/stt/transcriptions/get_transcriptions

This snippet shows a successful response when retrieving a list of transcriptions. It includes details of a single transcription and a cursor for pagination.

```json
{
  "transcriptions": [
    {
      "id": "73d4357d-cad2-4338-a60d-ec6f2044f721",
      "status": "completed",
      "created_at": "2024-11-26T00:00:00Z",
      "model": "stt-async-preview",
      "audio_url": "https://soniox.com/media/examples/coffee_shop.mp3",
      "file_id": null,
      "filename": "coffee_shop.mp3",
      "language_hints": [
        "en",
        "fr"
      ],
      "context": "extra context for the transcription",
      "audio_duration_ms": 16079,
      "error_message": null,
      "webhook_url": "https://example.com/webhook",
      "webhook_auth_header_name": "Authorization",
      "webhook_auth_header_value": "******************",
      "webhook_status_code": null,
      "client_reference_id": "some_internal_id"
    }
  ],
  "next_page_cursor": "cursor_or_null"
}
```

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

### Full LiveKit Agent Example with Tools and Context

Source: https://soniox.com/docs/llms-full.txt

A comprehensive example demonstrating a LiveKit agent for a dental practice. It includes setting up context, defining a mock calendar, and implementing tools for checking availability and booking appointments.

```python
import asyncio
import logging
from datetime import date

from dotenv import load_dotenv

from livekit.agents import (
    Agent,
    AgentSession,
    JobContext,
    TurnHandlingOptions,
    WorkerOptions,
    cli,
    function_tool,
    get_job_context,
)
from livekit.plugins import openai, silero, soniox
from livekit.plugins.soniox import (
    ContextGeneralItem,
    ContextObject,
    STTOptions,
)

load_dotenv()
logger = logging.getLogger("voice-agent")

TODAY = date.today().isoformat()

CLINIC_CONTEXT = ContextObject(
    terms=["Bright Smile Dental", "checkup", "cavity", "crown", "X-ray"],
    general=[
        ContextGeneralItem(key="domain", value="Dental practice"),
        ContextGeneralItem(key="topic", value="Booking an appointment"),
    ],
)


class DentalCalendar:
    """Mock calendar. Replace with your real booking system."""

    # The same four times are offered every day.
    DAILY_SCHEDULE = ["09:00", "10:30", "14:00", "15:30"]

    def __init__(self) -> None:
        # ISO datetimes that are already booked.
        self.booked: set[str] = {"2026-05-12T10:30"}
        self._next_confirmation = 1000

    async def find_slots(self, date: str) -> list[str]:
        """Return open ISO datetimes for the given date."""
        slots_for_day = [f"{date}T{time}" for time in self.DAILY_SCHEDULE]
        return [slot for slot in slots_for_day if slot not in self.booked]

    async def book(self, name: str, slot: str, reason: str) -> str:
        """Mark a slot as booked and return a confirmation ID."""
        self.booked.add(slot)
        self._next_confirmation += 1
        return f"DENT-{self._next_confirmation}"


calendar = DentalCalendar()


class Receptionist(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions=(
                f"Today's date is {TODAY}. "
                "You are a friendly receptionist at Bright Smile Dental. "
                "Keep replies short and natural. They will be spoken aloud. "
                "Resolve relative dates based on today. "
                "When booking, confirm name, date, time, and reason before "
                "calling the tool."
            ),
        )

    async def on_enter(self) -> None:
        self.session.generate_reply(
            instructions="Greet the caller and ask how you can help."
        )

    @function_tool
    async def check_availability(self, date: str) -> str:
        """Look up open appointment slots for a given date.

        Args:
            date: ISO date, e.g. "2026-05-12".
        """
        self.session.say("Let me check the schedule.")
        slots = await calendar.find_slots(date)
        if not slots:
            return f"No slots available on {date}; fully booked."
        return f"Open slots on {date}: {', '.join(slots)}."

    @function_tool
    async def book_appointment(self, name: str, slot: str, reason: str) -> str:
        """Book a confirmed appointment.

        Only call after the patient has confirmed the date, time, and reason.

        Args:
            name: Patient's full name.

```

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

### MicrophoneSource.start()

Source: https://soniox.com/docs/llms-full.txt

Requests microphone access and begins recording audio.

```APIDOC
## start()

### Description
Request microphone access and start recording.

### Signature
```ts
start(handlers: AudioSourceHandlers): Promise<void>
```

### Parameters
#### Path Parameters
- **handlers** (AudioSourceHandlers) - Required - Handlers for audio events.

### Returns
`Promise<void>`

### Throws
- AudioUnavailableError if getUserMedia or MediaRecorder is not supported.
- AudioPermissionError if microphone access is denied.
- AudioDeviceError if no microphone is found.
```

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

### Run Two-way Translation with Node.js (Standalone)

Source: https://soniox.com/docs/translation/get-started

Execute a two-way speech-to-text translation example using a standalone Node.js script. Ensure you install the necessary dependencies.

```bash
cd nodejs

# Install dependencies
npm install
```

```javascript
node soniox_realtime.js --audio_path ../assets/two_way_translation.mp3 --translation two_way
```

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

### Run One-way Translation with Node.js (Standalone)

Source: https://soniox.com/docs/translation/get-started

Execute a one-way speech-to-text translation example using a standalone Node.js script. Ensure you install the necessary dependencies.

```bash
cd nodejs

# Install dependencies
npm install
```

```javascript
node soniox_realtime.js --audio_path ../assets/coffee_shop.mp3 --translation one_way
```

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

### MicrophoneSource.start()

Source: https://soniox.com/docs/sdk/web-SDK/reference/classes

Requests microphone access and begins recording audio. This method handles the necessary browser permissions and initializes the audio capture process. It returns a Promise that resolves upon successful start, or throws specific errors if microphone access is unavailable, denied, or if no microphone is found.

```APIDOC
## start(handlers)

### Description
Requests microphone access and begins recording audio. This method handles the necessary browser permissions and initializes the audio capture process. It returns a Promise that resolves upon successful start, or throws specific errors if microphone access is unavailable, denied, or if no microphone is found.

### Parameters
Parameter| Type  
---|---  
`handlers`| `AudioSourceHandlers`  

### Returns
`Promise<void>`

### Throws
AudioUnavailableError if getUserMedia or MediaRecorder is not supported
AudioPermissionError if microphone access is denied
AudioDeviceError if no microphone is found
```

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

### Example Timestamp Response

Source: https://soniox.com/docs/stt/concepts/timestamps

This JSON structure shows how timestamps are provided for each token. Note that a single word can be split into multiple tokens, each with its own start and end time.

```json
{
  "tokens": [
    {"text": "Beau", "start_ms": 300, "end_ms": 420},
    {"text": "ti",   "start_ms": 420, "end_ms": 540},
    {"text": "ful",  "start_ms": 540, "end_ms": 780}
  ]
}
```

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

### Get Segments from Transcript

Source: https://soniox.com/docs/sdk/node-SDK/reference/classes

Groups tokens into segments based on specified grouping keys like speaker or language. A new segment starts when any of the group_by fields change.

```typescript
const transcript = await transcription.getTranscript();

// Group by both speaker and language (default)
const segments = transcript.segments();

// Group by speaker only
const bySpeaker = transcript.segments({ group_by: ['speaker'] });

for (const s of segments) {
    console.log(`[Speaker ${s.speaker}] ${s.text}`);
}
```

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

### Basic Pipecat Pipeline Setup

Source: https://soniox.com/docs/integrations/pipecat/voice-agent

Initializes a Pipecat pipeline with Soniox STT and TTS services, an OpenAI LLM, and Soniox context objects for language.

```python
import os

from pipecat.pipeline.pipeline import Pipeline
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.services.soniox.stt import (
    SonioxContextObject,
    SonioxContextGeneralItem,
    SonioxSTTService,
)
from pipecat.services.soniox.tts import SonioxTTSService
from pipecat.transcriptions.language import Language

```

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

### Example: Get SonioxTranscription Transcript

Source: https://soniox.com/docs/sdk/node-SDK/reference/classes

Illustrates fetching a transcription's transcript, including checking for its existence and logging the text. It also shows how to force a re-fetch from the API.

```typescript
const transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
if (transcription) {
    const transcript = await transcription.getTranscript();
    if (transcript) {
        console.log(transcript.text);
    }
}

// Force re-fetch from API
const freshTranscript = await transcription.getTranscript({ force: true });
```

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

### Run Asynchronous Soniox Example

Source: https://soniox.com/docs/llms-full.txt

This command executes an asynchronous Soniox example script. It requires the path to an audio file and a translation mode.

```bash
node soniox_async.js --audio_path ../assets/two_way_translation.mp3 --translation two_way
```

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

### Run Two-way Translation with Python SDK

Source: https://soniox.com/docs/translation/get-started

Execute a two-way speech-to-text translation example using the Python SDK. This requires setting up a virtual environment and installing dependencies.

```bash
cd python_sdk

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

```python
python soniox_sdk_realtime.py --audio_path ../assets/two_way_translation.mp3 --translation two_way
```

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

### Argument Parser Setup

Source: https://soniox.com/docs/llms-full.txt

Sets up an argument parser for command-line arguments, specifically for audio URL and audio path inputs for transcription.

```python
def main():
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--audio_url", help="Public URL of the audio file to transcribe."
    )
    parser.add_argument(
        "--audio_path", help="Path to a local audio file to transcribe."
    )
```

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

### Run One-way Translation with Python SDK

Source: https://soniox.com/docs/translation/get-started

Execute a one-way speech-to-text translation example using the Python SDK. This requires setting up a virtual environment and installing dependencies.

```bash
cd python_sdk

# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

```python
python soniox_sdk_realtime.py --audio_path ../assets/coffee_shop.mp3 --translation one_way
```

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

### Full Bot Code Example with Tools

Source: https://soniox.com/docs/llms-full.txt

This comprehensive example demonstrates setting up a Pipecat pipeline with custom tools for a dental appointment booking system. It includes mock calendar logic, tool definitions for checking availability and booking appointments, and the necessary imports for services and transports.

```python
import os

from dotenv import load_dotenv

from pipecat.adapters.schemas.function_schema import FunctionSchema
from pipecat.adapters.schemas.tools_schema import ToolsSchema
from pipecat.frames.frames import LLMRunFrame, TTSSpeakFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from pipecat.runner.types import RunnerArguments
from pipecat.runner.utils import create_transport
from pipecat.services.llm_service import FunctionCallParams
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.services.soniox.stt import (
    SonioxContextObject,
    SonioxContextGeneralItem,
    SonioxSTTService,
)
from pipecat.services.soniox.tts import SonioxTTSService
from pipecat.transcriptions.language import Language
from pipecat.transports.base_transport import BaseTransport, TransportParams
from pipecat.transports.daily.transport import DailyParams
from pipecat.transports.websocket.fastapi import FastAPIWebsocketParams

load_dotenv(override=True)


# Replace this with your real calendar or booking system.
class DentalCalendar:
    booked: set[str] = {"2026-05-12T10:30"}

    async def find_slots(self, date: str) -> list[str]:
        all_slots = [f"{date}T{t}" for t in ("09:00", "10:30", "14:00", "15:30")]
        return [s for s in all_slots if s not in self.booked]

    async def book(self, name: str, slot: str, reason: str) -> str:  # name and reason unused in mock
        self.booked.add(slot)
        return f"DENT-{abs(hash(slot)) % 10000:04d}"


calendar = DentalCalendar()


# Tool handlers can do anything Python can: API calls, database queries,
# RAG lookups, file I/O. Here they hit the mock calendar above.
async def check_availability(params: FunctionCallParams):
    slots = await calendar.find_slots(params.arguments["date"])
    await params.result_callback({"slots": slots})


async def book_appointment(params: FunctionCallParams):
    cid = await calendar.book(
        name=params.arguments["name"],
        slot=params.arguments["slot"],
        reason=params.arguments["reason"],
    )
    await params.result_callback({"confirmation_id": cid, "status": "booked"})


tools = ToolsSchema(
    standard_tools=[
        FunctionSchema(
            name="check_availability",
            description=(
                "Look up open appointment slots. Call this whenever the patient "
                "asks about availability or mentions a preferred date."
            ),
            properties={
                "date": {"type": "string", "description": "ISO date, e.g. 2026-05-12"},
            },
            required=["date"],
        ),
        FunctionSchema(
            name="book_appointment",
            description=(
                "Book a confirmed appointment. Only call after the patient has "
                "explicitly confirmed the date, time, and reason."
            ),
            properties={
                "name": {"type": "string"},
                "slot": {"type": "string", "description": "ISO datetime, e.g. 2026-05-12T10:30"},
                "reason": {"type": "string"},
            },
            required=["name", "slot", "reason"],
        ),
    ]
)


transport_params = {
    "daily": lambda: DailyParams(audio_in_enabled=True, audio_out_enabled=True),
    "twilio": lambda: FastAPIWebsocketParams(audio_in_enabled=True, audio_out_enabled=True),

```

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

### Generate Speech with Default Settings (Node.js)

Source: https://soniox.com/docs/tts/rt/real-time-generation

Use the Node.js SDK to generate speech with default WAV output settings. This is a quick way to get started with real-time TTS.

```bash
node soniox_sdk_realtime.js --line "Hello from Soniox realtime Text-to-Speech."
```

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

### API Key Configuration Example

Source: https://soniox.com/docs/llms-full.txt

Demonstrates how to configure the API key for the Soniox Client. It shows both static key usage and an asynchronous function for fetching fresh keys, which is recommended for production.

```typescript
type ApiKeyConfig = string | () => Promise<string>;

```

```typescript
// Static key (for demos or SSR-injected keys)
const client = new SonioxClient({ api_key: 'temp:...' });

// Async function (recommended for production)
const client = new SonioxClient({
  api_key: async () => {
    const res = await fetch('/api/get-temporary-key', { method: 'POST' });
    const { api_key } = await res.json();
    return api_key;
  },
});
```