> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinch

> Real-time speech-to-speech translation service powered by Pinch

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="pinch-eng" maintainerUrl="https://github.com/pinch-eng" repo="https://github.com/pinch-eng/pipecat-plugins-pinch" />

## Overview

`PinchTranslatorService` provides real-time speech-to-speech translation powered
by [Pinch](https://www.startpinch.com/). It is a drop-in `FrameProcessor` that
sits between your transport's input and output: it receives `InputAudioRawFrame`
from the user and emits `OutputAudioRawFrame` (translated speech) and
`TranscriptionFrame` (transcripts) downstream.

<CardGroup cols={2}>
  <Card title="Source Repository" icon="github" href="https://github.com/pinch-eng/pipecat-plugins-pinch">
    Source code, examples, and issues for the Pinch integration
  </Card>

  <Card title="PyPI Package" icon="cube" href="https://pypi.org/project/pipecat-plugins-pinch/">
    The `pipecat-plugins-pinch` package on PyPI
  </Card>

  <Card title="Pinch" icon="book" href="https://www.startpinch.com/">
    Learn more about Pinch real-time translation
  </Card>

  <Card title="API Keys" icon="key" href="https://portal.startpinch.com/dashboard/developers">
    Create and manage your Pinch API keys
  </Card>
</CardGroup>

## Installation

This is a community-maintained package distributed separately from `pipecat-ai`:

```bash theme={null}
pip install pipecat-plugins-pinch
```

Requires Python >= 3.10.

## Prerequisites

### Pinch Account Setup

Before using the Pinch translation service, you need:

1. **Pinch Account**: Sign up at [Pinch](https://www.startpinch.com/)
2. **API Key**: Get one from the [developers portal](https://portal.startpinch.com/dashboard/developers)

### Required Environment Variables

* `PINCH_API_KEY`: Your Pinch API key for authentication

## Configuration

<ParamField path="options" type="TranslatorOptions" required>
  Language and voice configuration for the translation session. See
  [TranslatorOptions](#translatoroptions) below.
</ParamField>

<ParamField path="api_key" type="str" default="None">
  Pinch API key. Falls back to the `PINCH_API_KEY` environment variable if not
  provided.
</ParamField>

### TranslatorOptions

Configuration passed via the `options` constructor argument using
`TranslatorOptions(...)`.

| Parameter         | Type  | Default   | Description                                                           |
| ----------------- | ----- | --------- | --------------------------------------------------------------------- |
| `source_language` | `str` | required  | BCP-47 code for the speaker's language (e.g. `"en-US"`).              |
| `target_language` | `str` | required  | BCP-47 code for the output language (e.g. `"es-ES"`).                 |
| `voice_type`      | `str` | `"clone"` | Voice used for translated output: `"clone"`, `"female"`, or `"male"`. |

<Note>
  For the full list of supported language codes, see [supported
  languages](https://www.startpinch.com/docs/supported-languages).
</Note>

## Usage

```python theme={null}
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.plugins.pinch import PinchTranslatorService, TranslatorOptions

async def main():
    # Replace with your preferred Pipecat transport (Daily, LiveKit, WebSocket, etc.)
    # transport = DailyTransport(...)

    translator = PinchTranslatorService(
        options=TranslatorOptions(
            source_language="en-US",
            target_language="es-ES",
            voice_type="clone",  # preserves the speaker's voice
        ),
        # api_key="pk_..."  # or set PINCH_API_KEY env var
    )

    pipeline = Pipeline([
        transport.input(),
        translator,
        transport.output(),
    ])

    task = PipelineTask(pipeline, params=PipelineParams(allow_interruptions=True))
    await PipelineRunner().run(task)
```

## Compatibility

Tested with `pipecat-ai >= 0.0.50`. Check the [source
repository](https://github.com/pinch-eng/pipecat-plugins-pinch) for the latest
tested version and changelog.