# Python SDK Quickstart (legacy)

> **Legacy.** The Python SDK targets the older LiveKit-based `agent-falcon` backend. It still works and isn’t going away soon, but new integrations should use the [WebSocket API](/content/docs/api-reference/index.html) directly — it’s simpler and doesn’t require LiveKit.

This quickstart covers **two common usage patterns**:

a. **Async / file-based translation**

b. **Streaming / real-time translation**

## Prerequisites

#### Account & access

To use the Pinch SDK, you’ll need:

- Login to Pinch
- Get a valid **API key**

You can create and manage API keys from the [Pinch Developer Portal >](https://portal.startpinch.com/dashboard/developers)

> New accounts include free credits to get started.

#### Authentication

The Pinch SDK authenticates using the `PINCH_API_KEY` environment variable.

You can set this variable in one of two ways:

**Option 1: Set it directly in your environment**

macOS

```bash
export PINCH_API_KEY="pk_your_key_here"
```

Windows

```powershell
$env:PINCH_API_KEY="pk_your_key_here"
```

**Option 2: Use a `.env` file**

Create a `.env` file in your project directory:

```
PINCH_API_KEY=pk_your_key_here
```

> Keep your API key private.
> Do not commit it to GitHub or include it in client-side code.

* * *

## Install the SDK

#### Using pip

macOS

```bash
python3 -m pip install pinch-sdk
```

Windows

```powershell
python -m pip install pinch-sdk
```

Optional: audio helpers for resampling

If your input WAV files are **not** 16kHz or 48kHz, install audio helpers:

macOS

```bash
python3 -m pip install "pinch-sdk[audio]"
```

Windows

```powershell
python -m pip install "pinch-sdk[audio]"
```

#### Using uv

```
uv add pinch-sdk
```

#### Run the script (example scripts given below)

Run the script from your project directory:

macOS

```bash
python3 translate.py
```

Windows

```powershell
python translate.py
```

* * *

## Example scripts

## (a) Async / File-Based Translation

This approach is ideal when:

- you already have an audio file
- you want simple, one-shot translation

In this approach, you’ll run a Python script that:

- takes a WAV audio file as input
- generates a translated WAV audio file
- writes a transcript of the translated text

Create a small script in your project (for example, `translate.py`):

```
import asyncio
from pinch import PinchClient

async def main() -> None:
    client = PinchClient()  # reads PINCH_API_KEY

await client.translate_file(
        input_wav_path="input.wav",
        output_wav_path="output.wav",
        transcript_path="transcript.txt",
        source_language="en-US",  # default
        target_language="es-ES",  # default
        audio_output_enabled=True # default
    )

if __name__ == "__main__":
    asyncio.run(main())
```

#### Outputs

After the script completes, you’ll see:

- `output.wav` - translated speech audio
- `transcript.txt` - translated text transcript

#### Example transcript output

ORIGINAL TRANSCRIPT

Yes, I was just saying that the meeting was moved to Thursday afternoon.

TRANSLATED TRANSCRIPT

Sí, justo estaba diciendo que la reunión se trasladó al jueves por la tarde.

* * *

## (b) Streaming / Real-Time Translation

Streaming sessions are designed for low-latency, real-time use cases.

In this approach:

- audio is streamed in real-time
- transcripts + translated audio is returned in real-time

This example intentionally leaves playback or storage to the user’s preference.

#### Create a streaming session:

```
from pinch import PinchClient
from pinch.session import SessionParams

client = PinchClient()

session = client.create_session(
    SessionParams(
        source_language="en-US",
        target_language="es-ES",
    )
)
```

This session represents a live translation context.

#### Connect a streaming transport:

```
stream = await client.connect_stream(
    session,
    audio_output_enabled=True,
)
```

Once connected:

- the stream accepts incoming audio
- transcripts and translated audio are emitted as events

#### Stream audio into Pinch:

Audio is sent as raw PCM16 frames (for example, 20 ms chunks).

```
await stream.send_pcm16(
    pcm_bytes,
    sample_rate=16000,
    channels=1,
)
```

You can send audio from:

- a microphone
- a WAV file
- another real-time source

Pinch processes audio incrementally as it arrives.

#### Receive streaming outputs:

Pinch returns results as asynchronous events.

```
async for event in stream.events():
    if event.type == "transcript":
        # Transcript metadata + text
        print(
            event.kind,              # "original" | "translated"
            event.is_final,          # True/False for final vs interim
            event.language_detected, # e.g. "en-US" when available
            event.text,
        )

elif event.type == "audio":
        # Translated speech as raw PCM16 bytes
        pcm_bytes = event.pcm16_bytes
        sample_rate = event.sample_rate

# Forward, buffer, save, or play this audio as needed
```

> Audio is returned as data, not played automatically. Applications decide how to handle playback or storage.

#### Detected language in transcript events

For `event.type == "transcript"`, the SDK includes:

- `event.language_detected` - language code detected for that segment (for example, `en-US`)
- `event.kind` - whether the transcript is `original` or `translated`
- `event.is_final` - whether the transcript segment is final or interim

#### Close the stream:

```
await stream.aclose()
```

Closing the stream signals that no more audio will be sent.

* * *

## Input audio requirements

- Input must be **16-bit PCM WAV**
- Supported sample rates:
  - **16,000 Hz** (recommended)
  - **48,000 Hz**
- Other sample rates require resampling helpers:

macOS

```bash
python3 -m pip install "pinch-sdk[audio]"
```

Windows

```powershell
python -m pip install "pinch-sdk[audio]"
```

* * *

## Language configuration

By default, the SDK uses:

- `source_language = "en-US"`
- `target_language = "es-ES"`

You can override these values when calling `translate_file`.

Pinch uses **language codes** (for example `en-US`, `es-ES`) rather than language names.

See [Supported languages >](/content/docs/supported-languages/index.html) for valid input and output codes.

* * *

## SDK repository & examples

The Pinch Python SDK is open source and available on GitHub.

The repository includes:

- the full SDK source code
- sample example files
- instructions for running the example using `pip` or `uv`

For implementation details and up-to-date examples, refer to the repository:

- [GitHub >](https://github.com/pinch-eng/pinch-python-sdk)

* * *

## Troubleshooting

#### The script exits immediately or raises an auth error

**Common causes**

- `PINCH_API_KEY` is missing or invalid
- credits are not enabled on your account
- network connectivity issues

**What to check**

- Confirm the `PINCH_API_KEY` environment variable is set:

macOS

```bash
echo $PINCH_API_KEY
```

Windows

```powershell
echo $env:PINCH_API_KEY
```

- Verify the key is active in the Pinch Portal
- Ensure your account has available credits