Metadata-Version: 2.4
Name: pipecat-plugins-pinch
Version: 0.1.0
Summary: Pinch real-time speech-to-speech translation plugin for Pipecat
Project-URL: Homepage, https://www.startpinch.com
Project-URL: Documentation, https://www.startpinch.com/docs
Project-URL: Repository, https://github.com/pinch-eng/pipecat-plugins-pinch
Project-URL: Bug Tracker, https://github.com/pinch-eng/pipecat-plugins-pinch/issues
Author-email: Pinch <support@startpinch.com>
License: Apache-2.0
License-File: LICENSE
Keywords: pinch,pipecat,real-time,speech-to-speech,translation
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: loguru>=0.7.0
Requires-Dist: pinch-sdk>=0.1.1
Requires-Dist: pipecat-ai>=0.0.50
Provides-Extra: quality
Requires-Dist: numpy>=1.24.0; extra == 'quality'
Requires-Dist: soxr>=0.3.7; extra == 'quality'
Description-Content-Type: text/markdown

# pipecat-plugins-pinch

Real-time **voice translation** for [Pipecat](https://github.com/pipecat-ai/pipecat) powered by [Pinch](https://startpinch.com).

---

## Installation

```bash
pip install pipecat-plugins-pinch
```

Requires Python ≥ 3.10.

---

## Prerequisites

You need a **Pinch API key**. Get one at the [developers portal](https://portal.startpinch.com/dashboard/developers).

Set it in your environment:

```bash
export PINCH_API_KEY=pk_your_key_here
```

---

## How it fits into a Pipecat pipeline

`PinchTranslatorService` is a drop-in `FrameProcessor`. It sits between your transport's input and output — receiving `InputAudioRawFrame` from the user and emitting `OutputAudioRawFrame` (translated speech) and `TranscriptionFrame` (transcripts) downstream.

```
transport.input()
      │
      ▼
PinchTranslatorService        ← translate en-US → es-ES
      │
      ├─► OutputAudioRawFrame  → transport.output()  (translated audio)
      └─► TranscriptionFrame   → your handler        (transcripts)
```

---

## Usage

```python
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)
```

The plugin handles everything internally — calling the Pinch API, managing the translation session, resampling audio, and routing frames — so you don't need to configure anything beyond `TranslatorOptions`.

---

## Configuration

### `TranslatorOptions`

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

### `PinchTranslatorService`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `options` | `TranslatorOptions` | required | Language and voice configuration |
| `api_key` | `str \| None` | `None` | Pinch API key. Falls back to `PINCH_API_KEY` env var |

---

## Supported languages

Full list of language codes: [supported languages](https://www.startpinch.com/docs/supported-languages)

---

## Transcript frames

The plugin emits standard Pipecat transcript frames for both the original and translated speech. You can consume these in any downstream `FrameProcessor`.

```python
from pipecat.frames.frames import TranscriptionFrame, InterimTranscriptionFrame
from pipecat.processors.frame_processor import FrameProcessor, FrameDirection

class MyTranscriptHandler(FrameProcessor):
    async def process_frame(self, frame, direction):
        await super().process_frame(frame, direction)

        if isinstance(frame, TranscriptionFrame) and frame.user_id == "":
            print(f"Translated: {frame.text}")

        await self.push_frame(frame, direction)
```

---

## Links

- [Pinch](https://startpinch.com)
- [Pipecat documentation](https://docs.pipecat.ai)
- [Pipecat GitHub](https://github.com/pipecat-ai/pipecat)

---

## License

Apache 2.0 — see [LICENSE](LICENSE).
