# <a href="https://palabra.ai"><img src="https://avatars.githubusercontent.com/u/199107821?s=32" alt="Palabra AI" align="center"></a> Palabra AI Python SDK
[](https://github.com/PalabraAI/palabra-ai-python/actions/workflows/test.yml)
[](https://github.com/PalabraAI/palabra-ai-python/actions/workflows/release.yml)
[](https://github.com/PalabraAI/palabra-ai-python)
[](https://pypi.org/project/palabra-ai/)
[](https://pepy.tech/projects/palabra-ai)
[](https://github.com/PalabraAI/palabra-ai-python/pkgs/container/palabra-ai-python)
[](https://opensource.org/licenses/MIT)
[//]: # ([](https://codecov.io/gh/PalabraAI/palabra-ai-python))
🌍 **Python SDK for Palabra AI's real-time speech-to-speech translation API**
🚀 Break down language barriers and enable seamless communication across 25+ languages
## Overview 📋
🎯 **The Palabra AI Python SDK provides a high-level API for integrating real-time speech-to-speech translation into your Python applications.**
✨ **What can Palabra.ai do?**
- ⚡ Real-time speech-to-speech translation with near-zero latency
- 🎙️ Auto voice cloning - speak any language in YOUR voice
- 🔄 Two-way simultaneous translation for live discussions
- 🚀 Developer API/SDK for building your own apps
- 🎯 Works everywhere - Zoom, streams, events, any platform
- 🔒 Zero data storage - your conversations stay private
🔧 **This SDK focuses on making real-time translation simple and accessible:**
- 🛡️ Uses WebRTC and WebSockets under the hood
- ⚡ Abstracts away all complexity
- 🎮 Simple configuration with source/target languages
- 🎤 Supports multiple input/output adapters (microphones, speakers, files, buffers)
📊 **How it works:**
1. 🎤 Configure input/output adapters
2. 🔄 SDK handles the entire pipeline
3. 🎯 Automatic transcription, translation, and synthesis
4. 🔊 Real-time audio stream ready for playback
💡 **All with just a few lines of code!**
## Installation 📦
### From PyPI 📦
```bash
pip install palabra-ai
```
### macOS SSL Certificate Setup 🔒
If you encounter SSL certificate errors on macOS like:
```
SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate
```
**Option 1: Install Python certificates** (recommended)
```zsh
/Applications/Python\ $(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")/Install\ Certificates.command
```
**Option 2: Use system certificates**
```bash
pip install pip-system-certs
```
This will configure Python to use your system's certificate store.
## Quick Start 🚀
### Real-time microphone translation 🎤
```python
from palabra_ai import (PalabraAI, Config, SourceLang, TargetLang,
EN, ES, DeviceManager)
palabra = PalabraAI()
dm = DeviceManager()
mic, speaker = dm.select_devices_interactive()
cfg = Config(SourceLang(EN, mic), [TargetLang(ES, speaker)])
palabra.run(cfg)
```
⚙️ **Set your API credentials as environment variables:**
```bash
export PALABRA_API_KEY=your_api_key
export PALABRA_API_SECRET=your_api_secret
```
## Examples 💡
### File-to-file translation 📁
```python
from palabra_ai import (PalabraAI, Config, SourceLang, TargetLang,
FileReader, FileWriter, EN, ES)
palabra = PalabraAI()
reader = FileReader("./speech/es.mp3")
writer = FileWriter("./es2en_out.wav")
cfg = Config(SourceLang(ES, reader), [TargetLang(EN, writer)])
palabra.run(cfg)
```
### Multiple target languages 🌐
```python
from palabra_ai import (PalabraAI, Config, SourceLang, TargetLang,
FileReader, FileWriter, EN, ES, FR, DE)
palabra = PalabraAI()
config = Config(
source=SourceLang(EN, FileReader("presentation.mp3")),
targets=[
TargetLang(ES, FileWriter("spanish.wav")),
TargetLang(FR, FileWriter("french.wav")),
TargetLang(DE, FileWriter("german.wav"))
]
)
palabra.run(config)
```
### Customizable output 📝
📋 **Add a transcription of the source and translated speech.**
⚙️ **Configure output to provide:**
- 🔊 Audio only
- 📝 Transcriptions only
- 🎯 Both audio and transcriptions
```python
from palabra_ai import (
PalabraAI,
Config,
SourceLang,
TargetLang,
FileReader,
EN,
ES,
)
from palabra_ai.base.message import TranscriptionMessage
async def print_translation_async(msg: TranscriptionMessage):
print(repr(msg))
def print_translation(msg: TranscriptionMessage):
print(str(msg))
palabra = PalabraAI()
cfg = Config(
source=SourceLang(
EN,
FileReader("speech/en.mp3"),
print_translation # Callback for source transcriptions
),
targets=[
TargetLang(
ES,
# You can use only transcription without audio writer if you want
# FileWriter("./test_output.wav"), # Optional: audio output
on_transcription=print_translation_async # Callback for translated transcriptions
)
],
silent=True, # Set to True to disable verbose logging to console
)
palabra.run(cfg)
```
#### Transcription output options: 📊
1️⃣ **Audio only** (default):
```python
TargetLang(ES, FileWriter("output.wav"))
```
2️⃣ **Transcription only**:
```python
TargetLang(ES, on_transcription=your_callback_function)
```
3️⃣ **Audio and transcription**:
```python
TargetLang(ES, FileWriter("output.wav"), on_transcription=your_callback_function)
```
💡 **The transcription callbacks receive `TranscriptionMessage` objects containing the transcribed text and metadata.**
🔄 **Callbacks can be either synchronous or asynchronous functions.**
### Integrate with FFmpeg (streaming) 🎬
```python
import io
from palabra_ai import (PalabraAI, Config, SourceLang, TargetLang,
BufferReader, BufferWriter, AR, EN, RunAsPipe)
ffmpeg_cmd = [
'ffmpeg',
'-i', 'speech/ar.mp3',
'-f', 's16le', # 16-bit PCM
'-acodec', 'pcm_s16le',
'-ar', '48000', # 48kHz
'-ac', '1', # mono
'-' # output to stdout
]
pipe_buffer = RunAsPipe(ffmpeg_cmd)
es_buffer = io.BytesIO()
palabra = PalabraAI()
reader = BufferReader(pipe_buffer)
writer = BufferWriter(es_buffer)
cfg = Config(SourceLang(AR, reader), [TargetLang(EN, writer)])
palabra.run(cfg)
print(f"Translated audio written to buffer with size: {es_buffer.getbuffer().nbytes} bytes")
with open("./ar2en_out.wav", "wb") as f:
f.write(es_buffer.getbuffer())
```
### Using buffers 💾
```python
import io
from palabra_ai import (PalabraAI, Config, SourceLang, TargetLang,
BufferReader, BufferWriter, AR, EN)
from palabra_ai.internal.audio import convert_any_to_pcm16
en_buffer, es_buffer = io.BytesIO(), io.BytesIO()
with open("speech/ar.mp3", "rb") as f:
en_buffer.write(convert_any_to_pcm16(f.read()))
palabra = PalabraAI()
reader = BufferReader(en_buffer)
writer = BufferWriter(es_buffer)
cfg = Config(SourceLang(AR, reader), [TargetLang(EN, writer)])
palabra.run(cfg)
print(f"Translated audio written to buffer with size: {es_buffer.getbuffer().nbytes} bytes")
with open("./ar2en_out.wav", "wb") as f:
f.write(es_buffer.getbuffer())
```
### Using default audio devices 🔊
```python
from palabra_ai import PalabraAI, Config, SourceLang, TargetLang, DeviceManager, EN, ES
dm = DeviceManager()
reader, writer = dm.get_default_readers_writers()
if reader and writer:
palabra = PalabraAI()
config = Config(
source=SourceLang(EN, reader),
targets=[TargetLang(ES, writer)]
)
palabra.run(config)
```
### Async API ⚡
```python
import asyncio
from palabra_ai import PalabraAI, Config, SourceLang, TargetLang, FileReader, FileWriter, EN, ES
async def translate():
palabra = PalabraAI()
config = Config(
source=SourceLang(EN, FileReader("input.mp3")),
targets=[TargetLang(ES, FileWriter("output.wav"))]
)
await palabra.run(config)
asyncio.run(translate())
```
## I/O Adapters & Mixing 🔌
### Available adapters 🛠️
🎯 **The Palabra AI SDK provides flexible I/O adapters that can combined to:**
- 📁 **FileReader/FileWriter**: Read from and write to audio files
- 🎤 **DeviceReader/DeviceWriter**: Use microphones and speakers
- 💾 **BufferReader/BufferWriter**: Work with in-memory buffers
- 🔧 **RunAsPipe**: Run command and represent as pipe (e.g., FFmpeg stdout)
### Mixing examples 🎨
🔄 **Combine any input adapter with any output adapter:**
#### 🎤➡️📁 Microphone to file - record translations
```python
config = Config(
source=SourceLang(EN, mic),
targets=[TargetLang(ES, FileWriter("recording_es.wav"))]
)
```
#### 📁➡️🔊 File to speaker - play translations
```python
config = Config(
source=SourceLang(EN, FileReader("presentation.mp3")),
targets=[TargetLang(ES, speaker)]
)
```
#### 🎤➡️🔊📁 Microphone to multiple outputs
```python
config = Config(
source=SourceLang(EN, mic),
targets=[
TargetLang(ES, speaker), # Play Spanish through speaker
TargetLang(ES, FileWriter("spanish.wav")), # Save Spanish to file
TargetLang(FR, FileWriter("french.wav")) # Save French to file
]
)
```
#### 💾➡️💾 Buffer to buffer - for integration
```python
input_buffer = io.BytesIO(audio_data)
output_buffer = io.BytesIO()
config = Config(
source=SourceLang(EN, BufferReader(input_buffer)),
targets=[TargetLang(ES, BufferWriter(output_buffer))]
)
```
#### 🔧➡️🔊 FFmpeg pipe to speaker
```python
pipe = RunAsPipe(ffmpeg_process.stdout)
config = Config(
source=SourceLang(EN, BufferReader(pipe)),
targets=[TargetLang(ES, speaker)]
)
```
## Features ✨
### Real-time translation ⚡
🎯 Translate audio streams in real-time with minimal latency
💬 Perfect for live conversations, conferences, and meetings
### Voice cloning 🗣️
🎭 Preserve the original speaker's voice characteristics in translations
⚙️ Enable voice cloning in the configuration
### Device management 🎮
🎤 Easy device selection with interactive prompts or programmatic access:
```python
dm = DeviceManager()
# Interactive selection
mic, speaker = dm.select_devices_interactive()
# Get devices by name
mic = dm.get_mic_by_name("Blue Yeti")
speaker = dm.get_speaker_by_name("MacBook Pro Speakers")
# List all devices
input_devices = dm.get_input_devices()
output_devices = dm.get_output_devices()
```
## Supported languages 🌍
### Speech recognition languages 🎤 (Source)
🇸🇦 Arabic (AR), 🌐 Bashkir (BA), 🇧🇾 Belarusian (BE), 🇧🇬 Bulgarian (BG), 🇧🇩 Bengali (BN), 🌐 Catalan (CA), 🇨🇿 Czech (CS), 🏴 Welsh (CY), 🇩🇰 Danish (DA), 🇩🇪 German (DE), 🇬🇷 Greek (EL), 🇬🇧 English (EN), 🌐 Esperanto (EO), 🇪🇸 Spanish (ES), 🇪🇪 Estonian (ET), 🌐 Basque (EU), 🇮🇷 Persian (FA), 🇫🇮 Finnish (FI), 🇫🇷 French (FR), 🇮🇪 Irish (GA), 🌐 Galician (GL), 🇮🇱 Hebrew (HE), 🇮🇳 Hindi (HI), 🇭🇷 Croatian (HR), 🇭🇺 Hungarian (HU), 🌐 Interlingua (IA), 🇮🇩 Indonesian (ID), 🇮🇹 Italian (IT), 🇯🇵 Japanese (JA), 🇰🇷 Korean (KO), 🇱🇹 Lithuanian (LT), 🇱🇻 Latvian (LV), 🇲🇳 Mongolian (MN), 🇮🇳 Marathi (MR), 🇲🇾 Malay (MS), 🇲🇹 Maltese (MT), 🇳🇱 Dutch (NL), 🇳🇴 Norwegian (NO), 🇵🇱 Polish (PL), 🇵🇹 Portuguese (PT), 🇷🇴 Romanian (RO), 🇷🇺 Russian (RU), 🇸🇰 Slovak (SK), 🇸🇮 Slovenian (SL), 🇸🇪 Swedish (SV), 🇰🇪 Swahili (SW), 🇮🇳 Tamil (TA), 🇹🇭 Thai (TH), 🇹🇷 Turkish (TR), 🌐 Uyghur (UG), 🇺🇦 Ukrainian (UK), 🇵🇰 Urdu (UR), 🇻🇳 Vietnamese (VI), 🇨🇳 Chinese (ZH)
### Translation languages 🔄 (Target)
🇸🇦 Arabic (AR), 🇦🇿 Azerbaijani (AZ), 🇧🇾 Belarusian (BE), 🇧🇬 Bulgarian (BG), 🇧🇦 Bosnian (BS), 🌐 Catalan (CA), 🇨🇿 Czech (CS), 🏴 Welsh (CY), 🇩🇰 Danish (DA), 🇩🇪 German (DE), 🇬🇷 Greek (EL), 🇬🇧 English (EN), 🇦🇺 English Australian (EN_AU), 🇨🇦 English Canadian (EN_CA), 🇬🇧 English UK (EN_GB), 🇺🇸 English US (EN_US), 🇪🇸 Spanish (ES), 🇲🇽 Spanish Mexican (ES_MX), 🇪🇪 Estonian (ET), 🇫🇮 Finnish (FI), 🇵🇭 Filipino (FIL), 🇫🇷 French (FR), 🇨🇦 French Canadian (FR_CA), 🌐 Galician (GL), 🇮🇱 Hebrew (HE), 🇮🇳 Hindi (HI), 🇭🇷 Croatian (HR), 🇭🇺 Hungarian (HU), 🇮🇩 Indonesian (ID), 🇮🇸 Icelandic (IS), 🇮🇹 Italian (IT), 🇯🇵 Japanese (JA), 🇰🇿 Kazakh (KK), 🇰🇷 Korean (KO), 🇱🇹 Lithuanian (LT), 🇱🇻 Latvian (LV), 🇲🇰 Macedonian (MK), 🇲🇾 Malay (MS), 🇳🇱 Dutch (NL), 🇳🇴 Norwegian (NO), 🇵🇱 Polish (PL), 🇵🇹 Portuguese (PT), 🇧🇷 Portuguese Brazilian (PT_BR), 🇷🇴 Romanian (RO), 🇷🇺 Russian (RU), 🇸🇰 Slovak (SK), 🇸🇮 Slovenian (SL), 🇷🇸 Serbian (SR), 🇸🇪 Swedish (SV), 🇰🇪 Swahili (SW), 🇮🇳 Tamil (TA), 🇹🇷 Turkish (TR), 🇺🇦 Ukrainian (UK), 🇵🇰 Urdu (UR), 🇻🇳 Vietnamese (VI), 🇨🇳 Chinese (ZH), 🇨🇳 Chinese Simplified (ZH_HANS), 🇹🇼 Chinese Traditional (ZH_HANT)
### Available language constants 📚
```python
from palabra_ai import (
# English variants - 1.5+ billion speakers (including L2)
EN, EN_AU, EN_CA, EN_GB, EN_US,
# Chinese variants - 1.3+ billion speakers
ZH, ZH_HANS, ZH_HANT, # ZH_HANS and ZH_HANT for translation only
# Hindi & Indian languages - 800+ million speakers
HI, BN, MR, TA, UR,
# Spanish variants - 500+ million speakers
ES, ES_MX,
# Arabic variants - 400+ million speakers
AR, AR_AE, AR_SA,
# French variants - 280+ million speakers
FR, FR_CA,
# Portuguese variants - 260+ million speakers
PT, PT_BR,
# Russian & Slavic languages - 350+ million speakers
RU, UK, PL, CS, SK, BG, HR, SR, SL, MK, BE,
# Japanese & Korean - 200+ million speakers combined
JA, KO,
# Southeast Asian languages - 400+ million speakers
ID, VI, MS, FIL, TH,
# Germanic languages - 150+ million speakers
DE, NL, SV, NO, DA, IS,
# Romance languages (other) - 100+ million speakers
IT, RO, CA, GL,
# Turkic & Central Asian languages - 200+ million speakers
TR, AZ, KK, UG,
# Baltic languages - 10+ million speakers
LT, LV, ET,
# Other European languages - 50+ million speakers
EL, HU, FI, EU, CY, MT,
# Middle Eastern languages - 50+ million speakers
HE, FA,
# African languages - 100+ million speakers
SW,
# Asian languages (other) - 50+ million speakers
MN, BA,
# Constructed languages
EO, IA,
# Other languages
GA, BS
)
```
**Note**: Source languages (for speech recognition) and target languages (for translation) have different support. The SDK automatically validates language compatibility when creating `SourceLang` and `TargetLang` objects.
## Development status 🛠️
### Current status ✅
- ✅ Core SDK functionality
- ✅ GitHub Actions CI/CD
- ✅ Docker packaging
- ✅ Python 3.11, 3.12, 3.13 support
- ✅ PyPI publication (coming soon)
- ✅ Documentation site (coming soon)
- ⏳ Code coverage reporting (setup required)
### Current dev roadmap 🗺️
- ⏳ TODO: global timeout support for long-running tasks
- ⏳ TODO: support for multiple source languages in a single run
- ⏳ TODO: fine cancelling on cancel_all_tasks()
- ⏳ TODO: error handling improvements
### Build status 🏗️
- 🧪 **Tests**: Running on Python 3.11, 3.12, 3.13
- 📦 **Release**: Automated releases with Docker images
- 📊 **Coverage**: Tests implemented, reporting setup needed
## Requirements 📋
- 🐍 Python 3.11+
- 🔑 Palabra AI API credentials (get them at [palabra.ai](https://palabra.ai))
## Support 🤝
- 📚 Documentation: [https://docs.palabra.ai](https://docs.palabra.ai)
- 🐛 Issues: [GitHub Issues](https://github.com/PalabraAI/palabra-ai-python/issues)
- 📧 Email: info@palabra.ai
## License 📄
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
© Palabra.ai, 2025 | 🌍 Breaking down language barriers with AI 🚀
Raw data
{
"_id": null,
"home_page": null,
"name": "palabra-ai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "api-client, dubbing, palabra-ai, speech-translation, voice-synthesis",
"author": null,
"author_email": "Andrei Kobyshev <a.kobyshev@palabra.ai>",
"download_url": "https://files.pythonhosted.org/packages/0c/68/202dfcaf393010fa4107b405f83ff1fe22bcf111cd3e1315e3e2b964aa1b/palabra_ai-0.3.1.tar.gz",
"platform": null,
"description": "# <a href=\"https://palabra.ai\"><img src=\"https://avatars.githubusercontent.com/u/199107821?s=32\" alt=\"Palabra AI\" align=\"center\"></a> Palabra AI Python SDK\n\n[](https://github.com/PalabraAI/palabra-ai-python/actions/workflows/test.yml)\n[](https://github.com/PalabraAI/palabra-ai-python/actions/workflows/release.yml)\n[](https://github.com/PalabraAI/palabra-ai-python)\n[](https://pypi.org/project/palabra-ai/)\n[](https://pepy.tech/projects/palabra-ai)\n[](https://github.com/PalabraAI/palabra-ai-python/pkgs/container/palabra-ai-python)\n[](https://opensource.org/licenses/MIT)\n\n[//]: # ([](https://codecov.io/gh/PalabraAI/palabra-ai-python))\n\n\ud83c\udf0d **Python SDK for Palabra AI's real-time speech-to-speech translation API** \n\ud83d\ude80 Break down language barriers and enable seamless communication across 25+ languages\n\n## Overview \ud83d\udccb\n\n\ud83c\udfaf **The Palabra AI Python SDK provides a high-level API for integrating real-time speech-to-speech translation into your Python applications.**\n\n\u2728 **What can Palabra.ai do?**\n- \u26a1 Real-time speech-to-speech translation with near-zero latency\n- \ud83c\udf99\ufe0f Auto voice cloning - speak any language in YOUR voice\n- \ud83d\udd04 Two-way simultaneous translation for live discussions\n- \ud83d\ude80 Developer API/SDK for building your own apps\n- \ud83c\udfaf Works everywhere - Zoom, streams, events, any platform\n- \ud83d\udd12 Zero data storage - your conversations stay private\n\n\ud83d\udd27 **This SDK focuses on making real-time translation simple and accessible:**\n- \ud83d\udee1\ufe0f Uses WebRTC and WebSockets under the hood\n- \u26a1 Abstracts away all complexity\n- \ud83c\udfae Simple configuration with source/target languages\n- \ud83c\udfa4 Supports multiple input/output adapters (microphones, speakers, files, buffers)\n\n\ud83d\udcca **How it works:**\n1. \ud83c\udfa4 Configure input/output adapters\n2. \ud83d\udd04 SDK handles the entire pipeline\n3. \ud83c\udfaf Automatic transcription, translation, and synthesis\n4. \ud83d\udd0a Real-time audio stream ready for playback\n\n\ud83d\udca1 **All with just a few lines of code!**\n\n## Installation \ud83d\udce6\n\n### From PyPI \ud83d\udce6\n```bash\npip install palabra-ai\n```\n\n### macOS SSL Certificate Setup \ud83d\udd12\n\nIf you encounter SSL certificate errors on macOS like:\n```\nSSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate\n```\n\n**Option 1: Install Python certificates** (recommended)\n```zsh\n/Applications/Python\\ $(python3 -c \"import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')\")/Install\\ Certificates.command\n```\n\n**Option 2: Use system certificates**\n```bash\npip install pip-system-certs\n```\n\nThis will configure Python to use your system's certificate store.\n\n## Quick Start \ud83d\ude80\n\n### Real-time microphone translation \ud83c\udfa4\n\n```python\nfrom palabra_ai import (PalabraAI, Config, SourceLang, TargetLang,\n EN, ES, DeviceManager)\n\npalabra = PalabraAI()\ndm = DeviceManager()\nmic, speaker = dm.select_devices_interactive()\ncfg = Config(SourceLang(EN, mic), [TargetLang(ES, speaker)])\npalabra.run(cfg)\n```\n\n\u2699\ufe0f **Set your API credentials as environment variables:**\n```bash\nexport PALABRA_API_KEY=your_api_key\nexport PALABRA_API_SECRET=your_api_secret\n```\n\n## Examples \ud83d\udca1\n\n### File-to-file translation \ud83d\udcc1\n\n```python\nfrom palabra_ai import (PalabraAI, Config, SourceLang, TargetLang,\n FileReader, FileWriter, EN, ES)\n\npalabra = PalabraAI()\nreader = FileReader(\"./speech/es.mp3\")\nwriter = FileWriter(\"./es2en_out.wav\")\ncfg = Config(SourceLang(ES, reader), [TargetLang(EN, writer)])\npalabra.run(cfg)\n```\n\n### Multiple target languages \ud83c\udf10\n\n```python\nfrom palabra_ai import (PalabraAI, Config, SourceLang, TargetLang,\n FileReader, FileWriter, EN, ES, FR, DE)\n\npalabra = PalabraAI()\nconfig = Config(\n source=SourceLang(EN, FileReader(\"presentation.mp3\")),\n targets=[\n TargetLang(ES, FileWriter(\"spanish.wav\")),\n TargetLang(FR, FileWriter(\"french.wav\")),\n TargetLang(DE, FileWriter(\"german.wav\"))\n ]\n)\npalabra.run(config)\n```\n\n### Customizable output \ud83d\udcdd\n\n\ud83d\udccb **Add a transcription of the source and translated speech.** \n\u2699\ufe0f **Configure output to provide:**\n- \ud83d\udd0a Audio only\n- \ud83d\udcdd Transcriptions only\n- \ud83c\udfaf Both audio and transcriptions\n\n```python\nfrom palabra_ai import (\n PalabraAI,\n Config,\n SourceLang,\n TargetLang,\n FileReader,\n EN,\n ES,\n)\nfrom palabra_ai.base.message import TranscriptionMessage\n\n\nasync def print_translation_async(msg: TranscriptionMessage):\n print(repr(msg))\n\n\ndef print_translation(msg: TranscriptionMessage):\n print(str(msg))\n\n\npalabra = PalabraAI()\ncfg = Config(\n source=SourceLang(\n EN,\n FileReader(\"speech/en.mp3\"),\n print_translation # Callback for source transcriptions\n ),\n targets=[\n TargetLang(\n ES,\n # You can use only transcription without audio writer if you want\n # FileWriter(\"./test_output.wav\"), # Optional: audio output\n on_transcription=print_translation_async # Callback for translated transcriptions\n )\n ],\n silent=True, # Set to True to disable verbose logging to console\n)\npalabra.run(cfg)\n```\n\n#### Transcription output options: \ud83d\udcca\n\n1\ufe0f\u20e3 **Audio only** (default):\n```python\nTargetLang(ES, FileWriter(\"output.wav\"))\n```\n\n2\ufe0f\u20e3 **Transcription only**:\n```python\nTargetLang(ES, on_transcription=your_callback_function)\n```\n\n3\ufe0f\u20e3 **Audio and transcription**:\n```python\nTargetLang(ES, FileWriter(\"output.wav\"), on_transcription=your_callback_function)\n```\n\n\ud83d\udca1 **The transcription callbacks receive `TranscriptionMessage` objects containing the transcribed text and metadata.** \n\ud83d\udd04 **Callbacks can be either synchronous or asynchronous functions.**\n\n### Integrate with FFmpeg (streaming) \ud83c\udfac\n\n```python\nimport io\nfrom palabra_ai import (PalabraAI, Config, SourceLang, TargetLang,\n BufferReader, BufferWriter, AR, EN, RunAsPipe)\n\nffmpeg_cmd = [\n 'ffmpeg',\n '-i', 'speech/ar.mp3',\n '-f', 's16le', # 16-bit PCM\n '-acodec', 'pcm_s16le',\n '-ar', '48000', # 48kHz\n '-ac', '1', # mono\n '-' # output to stdout\n]\n\npipe_buffer = RunAsPipe(ffmpeg_cmd)\nes_buffer = io.BytesIO()\n\npalabra = PalabraAI()\nreader = BufferReader(pipe_buffer)\nwriter = BufferWriter(es_buffer)\ncfg = Config(SourceLang(AR, reader), [TargetLang(EN, writer)])\npalabra.run(cfg)\n\nprint(f\"Translated audio written to buffer with size: {es_buffer.getbuffer().nbytes} bytes\")\nwith open(\"./ar2en_out.wav\", \"wb\") as f:\n f.write(es_buffer.getbuffer())\n```\n\n### Using buffers \ud83d\udcbe\n\n```python\nimport io\nfrom palabra_ai import (PalabraAI, Config, SourceLang, TargetLang,\n BufferReader, BufferWriter, AR, EN)\nfrom palabra_ai.internal.audio import convert_any_to_pcm16\n\nen_buffer, es_buffer = io.BytesIO(), io.BytesIO()\nwith open(\"speech/ar.mp3\", \"rb\") as f:\n en_buffer.write(convert_any_to_pcm16(f.read()))\npalabra = PalabraAI()\nreader = BufferReader(en_buffer)\nwriter = BufferWriter(es_buffer)\ncfg = Config(SourceLang(AR, reader), [TargetLang(EN, writer)])\npalabra.run(cfg)\nprint(f\"Translated audio written to buffer with size: {es_buffer.getbuffer().nbytes} bytes\")\nwith open(\"./ar2en_out.wav\", \"wb\") as f:\n f.write(es_buffer.getbuffer())\n```\n\n### Using default audio devices \ud83d\udd0a\n\n```python\nfrom palabra_ai import PalabraAI, Config, SourceLang, TargetLang, DeviceManager, EN, ES\n\ndm = DeviceManager()\nreader, writer = dm.get_default_readers_writers()\n\nif reader and writer:\n palabra = PalabraAI()\n config = Config(\n source=SourceLang(EN, reader),\n targets=[TargetLang(ES, writer)]\n )\n palabra.run(config)\n```\n\n### Async API \u26a1\n\n```python\nimport asyncio\nfrom palabra_ai import PalabraAI, Config, SourceLang, TargetLang, FileReader, FileWriter, EN, ES\n\nasync def translate():\n palabra = PalabraAI()\n config = Config(\n source=SourceLang(EN, FileReader(\"input.mp3\")),\n targets=[TargetLang(ES, FileWriter(\"output.wav\"))]\n )\n await palabra.run(config)\n\nasyncio.run(translate())\n```\n\n## I/O Adapters & Mixing \ud83d\udd0c\n\n### Available adapters \ud83d\udee0\ufe0f\n\n\ud83c\udfaf **The Palabra AI SDK provides flexible I/O adapters that can combined to:**\n\n- \ud83d\udcc1 **FileReader/FileWriter**: Read from and write to audio files\n- \ud83c\udfa4 **DeviceReader/DeviceWriter**: Use microphones and speakers\n- \ud83d\udcbe **BufferReader/BufferWriter**: Work with in-memory buffers\n- \ud83d\udd27 **RunAsPipe**: Run command and represent as pipe (e.g., FFmpeg stdout)\n\n### Mixing examples \ud83c\udfa8\n\n\ud83d\udd04 **Combine any input adapter with any output adapter:**\n\n#### \ud83c\udfa4\u27a1\ufe0f\ud83d\udcc1 Microphone to file - record translations\n```python\nconfig = Config(\n source=SourceLang(EN, mic),\n targets=[TargetLang(ES, FileWriter(\"recording_es.wav\"))]\n)\n```\n\n#### \ud83d\udcc1\u27a1\ufe0f\ud83d\udd0a File to speaker - play translations\n```python\nconfig = Config(\n source=SourceLang(EN, FileReader(\"presentation.mp3\")),\n targets=[TargetLang(ES, speaker)]\n)\n```\n\n#### \ud83c\udfa4\u27a1\ufe0f\ud83d\udd0a\ud83d\udcc1 Microphone to multiple outputs\n```python\nconfig = Config(\n source=SourceLang(EN, mic),\n targets=[\n TargetLang(ES, speaker), # Play Spanish through speaker\n TargetLang(ES, FileWriter(\"spanish.wav\")), # Save Spanish to file\n TargetLang(FR, FileWriter(\"french.wav\")) # Save French to file\n ]\n)\n```\n\n#### \ud83d\udcbe\u27a1\ufe0f\ud83d\udcbe Buffer to buffer - for integration\n```python\ninput_buffer = io.BytesIO(audio_data)\noutput_buffer = io.BytesIO()\n\nconfig = Config(\n source=SourceLang(EN, BufferReader(input_buffer)),\n targets=[TargetLang(ES, BufferWriter(output_buffer))]\n)\n```\n\n#### \ud83d\udd27\u27a1\ufe0f\ud83d\udd0a FFmpeg pipe to speaker\n```python\npipe = RunAsPipe(ffmpeg_process.stdout)\nconfig = Config(\n source=SourceLang(EN, BufferReader(pipe)),\n targets=[TargetLang(ES, speaker)]\n)\n```\n\n## Features \u2728\n\n### Real-time translation \u26a1\n\ud83c\udfaf Translate audio streams in real-time with minimal latency \n\ud83d\udcac Perfect for live conversations, conferences, and meetings\n\n### Voice cloning \ud83d\udde3\ufe0f\n\ud83c\udfad Preserve the original speaker's voice characteristics in translations \n\u2699\ufe0f Enable voice cloning in the configuration\n\n### Device management \ud83c\udfae\n\ud83c\udfa4 Easy device selection with interactive prompts or programmatic access:\n\n```python\ndm = DeviceManager()\n\n# Interactive selection\nmic, speaker = dm.select_devices_interactive()\n\n# Get devices by name\nmic = dm.get_mic_by_name(\"Blue Yeti\")\nspeaker = dm.get_speaker_by_name(\"MacBook Pro Speakers\")\n\n# List all devices\ninput_devices = dm.get_input_devices()\noutput_devices = dm.get_output_devices()\n```\n\n## Supported languages \ud83c\udf0d\n\n### Speech recognition languages \ud83c\udfa4 (Source)\n\ud83c\uddf8\ud83c\udde6 Arabic (AR), \ud83c\udf10 Bashkir (BA), \ud83c\udde7\ud83c\uddfe Belarusian (BE), \ud83c\udde7\ud83c\uddec Bulgarian (BG), \ud83c\udde7\ud83c\udde9 Bengali (BN), \ud83c\udf10 Catalan (CA), \ud83c\udde8\ud83c\uddff Czech (CS), \ud83c\udff4 Welsh (CY), \ud83c\udde9\ud83c\uddf0 Danish (DA), \ud83c\udde9\ud83c\uddea German (DE), \ud83c\uddec\ud83c\uddf7 Greek (EL), \ud83c\uddec\ud83c\udde7 English (EN), \ud83c\udf10 Esperanto (EO), \ud83c\uddea\ud83c\uddf8 Spanish (ES), \ud83c\uddea\ud83c\uddea Estonian (ET), \ud83c\udf10 Basque (EU), \ud83c\uddee\ud83c\uddf7 Persian (FA), \ud83c\uddeb\ud83c\uddee Finnish (FI), \ud83c\uddeb\ud83c\uddf7 French (FR), \ud83c\uddee\ud83c\uddea Irish (GA), \ud83c\udf10 Galician (GL), \ud83c\uddee\ud83c\uddf1 Hebrew (HE), \ud83c\uddee\ud83c\uddf3 Hindi (HI), \ud83c\udded\ud83c\uddf7 Croatian (HR), \ud83c\udded\ud83c\uddfa Hungarian (HU), \ud83c\udf10 Interlingua (IA), \ud83c\uddee\ud83c\udde9 Indonesian (ID), \ud83c\uddee\ud83c\uddf9 Italian (IT), \ud83c\uddef\ud83c\uddf5 Japanese (JA), \ud83c\uddf0\ud83c\uddf7 Korean (KO), \ud83c\uddf1\ud83c\uddf9 Lithuanian (LT), \ud83c\uddf1\ud83c\uddfb Latvian (LV), \ud83c\uddf2\ud83c\uddf3 Mongolian (MN), \ud83c\uddee\ud83c\uddf3 Marathi (MR), \ud83c\uddf2\ud83c\uddfe Malay (MS), \ud83c\uddf2\ud83c\uddf9 Maltese (MT), \ud83c\uddf3\ud83c\uddf1 Dutch (NL), \ud83c\uddf3\ud83c\uddf4 Norwegian (NO), \ud83c\uddf5\ud83c\uddf1 Polish (PL), \ud83c\uddf5\ud83c\uddf9 Portuguese (PT), \ud83c\uddf7\ud83c\uddf4 Romanian (RO), \ud83c\uddf7\ud83c\uddfa Russian (RU), \ud83c\uddf8\ud83c\uddf0 Slovak (SK), \ud83c\uddf8\ud83c\uddee Slovenian (SL), \ud83c\uddf8\ud83c\uddea Swedish (SV), \ud83c\uddf0\ud83c\uddea Swahili (SW), \ud83c\uddee\ud83c\uddf3 Tamil (TA), \ud83c\uddf9\ud83c\udded Thai (TH), \ud83c\uddf9\ud83c\uddf7 Turkish (TR), \ud83c\udf10 Uyghur (UG), \ud83c\uddfa\ud83c\udde6 Ukrainian (UK), \ud83c\uddf5\ud83c\uddf0 Urdu (UR), \ud83c\uddfb\ud83c\uddf3 Vietnamese (VI), \ud83c\udde8\ud83c\uddf3 Chinese (ZH)\n\n### Translation languages \ud83d\udd04 (Target)\n\ud83c\uddf8\ud83c\udde6 Arabic (AR), \ud83c\udde6\ud83c\uddff Azerbaijani (AZ), \ud83c\udde7\ud83c\uddfe Belarusian (BE), \ud83c\udde7\ud83c\uddec Bulgarian (BG), \ud83c\udde7\ud83c\udde6 Bosnian (BS), \ud83c\udf10 Catalan (CA), \ud83c\udde8\ud83c\uddff Czech (CS), \ud83c\udff4 Welsh (CY), \ud83c\udde9\ud83c\uddf0 Danish (DA), \ud83c\udde9\ud83c\uddea German (DE), \ud83c\uddec\ud83c\uddf7 Greek (EL), \ud83c\uddec\ud83c\udde7 English (EN), \ud83c\udde6\ud83c\uddfa English Australian (EN_AU), \ud83c\udde8\ud83c\udde6 English Canadian (EN_CA), \ud83c\uddec\ud83c\udde7 English UK (EN_GB), \ud83c\uddfa\ud83c\uddf8 English US (EN_US), \ud83c\uddea\ud83c\uddf8 Spanish (ES), \ud83c\uddf2\ud83c\uddfd Spanish Mexican (ES_MX), \ud83c\uddea\ud83c\uddea Estonian (ET), \ud83c\uddeb\ud83c\uddee Finnish (FI), \ud83c\uddf5\ud83c\udded Filipino (FIL), \ud83c\uddeb\ud83c\uddf7 French (FR), \ud83c\udde8\ud83c\udde6 French Canadian (FR_CA), \ud83c\udf10 Galician (GL), \ud83c\uddee\ud83c\uddf1 Hebrew (HE), \ud83c\uddee\ud83c\uddf3 Hindi (HI), \ud83c\udded\ud83c\uddf7 Croatian (HR), \ud83c\udded\ud83c\uddfa Hungarian (HU), \ud83c\uddee\ud83c\udde9 Indonesian (ID), \ud83c\uddee\ud83c\uddf8 Icelandic (IS), \ud83c\uddee\ud83c\uddf9 Italian (IT), \ud83c\uddef\ud83c\uddf5 Japanese (JA), \ud83c\uddf0\ud83c\uddff Kazakh (KK), \ud83c\uddf0\ud83c\uddf7 Korean (KO), \ud83c\uddf1\ud83c\uddf9 Lithuanian (LT), \ud83c\uddf1\ud83c\uddfb Latvian (LV), \ud83c\uddf2\ud83c\uddf0 Macedonian (MK), \ud83c\uddf2\ud83c\uddfe Malay (MS), \ud83c\uddf3\ud83c\uddf1 Dutch (NL), \ud83c\uddf3\ud83c\uddf4 Norwegian (NO), \ud83c\uddf5\ud83c\uddf1 Polish (PL), \ud83c\uddf5\ud83c\uddf9 Portuguese (PT), \ud83c\udde7\ud83c\uddf7 Portuguese Brazilian (PT_BR), \ud83c\uddf7\ud83c\uddf4 Romanian (RO), \ud83c\uddf7\ud83c\uddfa Russian (RU), \ud83c\uddf8\ud83c\uddf0 Slovak (SK), \ud83c\uddf8\ud83c\uddee Slovenian (SL), \ud83c\uddf7\ud83c\uddf8 Serbian (SR), \ud83c\uddf8\ud83c\uddea Swedish (SV), \ud83c\uddf0\ud83c\uddea Swahili (SW), \ud83c\uddee\ud83c\uddf3 Tamil (TA), \ud83c\uddf9\ud83c\uddf7 Turkish (TR), \ud83c\uddfa\ud83c\udde6 Ukrainian (UK), \ud83c\uddf5\ud83c\uddf0 Urdu (UR), \ud83c\uddfb\ud83c\uddf3 Vietnamese (VI), \ud83c\udde8\ud83c\uddf3 Chinese (ZH), \ud83c\udde8\ud83c\uddf3 Chinese Simplified (ZH_HANS), \ud83c\uddf9\ud83c\uddfc Chinese Traditional (ZH_HANT)\n\n### Available language constants \ud83d\udcda\n\n```python\nfrom palabra_ai import (\n # English variants - 1.5+ billion speakers (including L2)\n EN, EN_AU, EN_CA, EN_GB, EN_US,\n\n # Chinese variants - 1.3+ billion speakers\n ZH, ZH_HANS, ZH_HANT, # ZH_HANS and ZH_HANT for translation only\n\n # Hindi & Indian languages - 800+ million speakers\n HI, BN, MR, TA, UR,\n\n # Spanish variants - 500+ million speakers\n ES, ES_MX,\n\n # Arabic variants - 400+ million speakers\n AR, AR_AE, AR_SA,\n\n # French variants - 280+ million speakers\n FR, FR_CA,\n\n # Portuguese variants - 260+ million speakers\n PT, PT_BR,\n\n # Russian & Slavic languages - 350+ million speakers\n RU, UK, PL, CS, SK, BG, HR, SR, SL, MK, BE,\n\n # Japanese & Korean - 200+ million speakers combined\n JA, KO,\n\n # Southeast Asian languages - 400+ million speakers\n ID, VI, MS, FIL, TH,\n\n # Germanic languages - 150+ million speakers\n DE, NL, SV, NO, DA, IS,\n\n # Romance languages (other) - 100+ million speakers\n IT, RO, CA, GL,\n\n # Turkic & Central Asian languages - 200+ million speakers\n TR, AZ, KK, UG,\n\n # Baltic languages - 10+ million speakers\n LT, LV, ET,\n\n # Other European languages - 50+ million speakers\n EL, HU, FI, EU, CY, MT,\n\n # Middle Eastern languages - 50+ million speakers\n HE, FA,\n\n # African languages - 100+ million speakers\n SW,\n\n # Asian languages (other) - 50+ million speakers\n MN, BA,\n\n # Constructed languages\n EO, IA,\n\n # Other languages\n GA, BS\n)\n```\n\n**Note**: Source languages (for speech recognition) and target languages (for translation) have different support. The SDK automatically validates language compatibility when creating `SourceLang` and `TargetLang` objects.\n\n## Development status \ud83d\udee0\ufe0f\n\n### Current status \u2705\n- \u2705 Core SDK functionality\n- \u2705 GitHub Actions CI/CD\n- \u2705 Docker packaging\n- \u2705 Python 3.11, 3.12, 3.13 support\n- \u2705 PyPI publication (coming soon)\n- \u2705 Documentation site (coming soon)\n- \u23f3 Code coverage reporting (setup required)\n\n### Current dev roadmap \ud83d\uddfa\ufe0f\n- \u23f3 TODO: global timeout support for long-running tasks\n- \u23f3 TODO: support for multiple source languages in a single run\n- \u23f3 TODO: fine cancelling on cancel_all_tasks()\n- \u23f3 TODO: error handling improvements\n\n### Build status \ud83c\udfd7\ufe0f\n- \ud83e\uddea **Tests**: Running on Python 3.11, 3.12, 3.13\n- \ud83d\udce6 **Release**: Automated releases with Docker images\n- \ud83d\udcca **Coverage**: Tests implemented, reporting setup needed\n\n## Requirements \ud83d\udccb\n\n- \ud83d\udc0d Python 3.11+\n- \ud83d\udd11 Palabra AI API credentials (get them at [palabra.ai](https://palabra.ai))\n\n## Support \ud83e\udd1d\n\n- \ud83d\udcda Documentation: [https://docs.palabra.ai](https://docs.palabra.ai)\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/PalabraAI/palabra-ai-python/issues)\n- \ud83d\udce7 Email: info@palabra.ai\n\n## License \ud83d\udcc4\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u00a9 Palabra.ai, 2025 | \ud83c\udf0d Breaking down language barriers with AI \ud83d\ude80\n",
"bugtrack_url": null,
"license": null,
"summary": "Client library for Palabra AI's real-time speech translation, dubbing, and voice synthesis APIs across 25+ languages.",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://docs.palabra.ai",
"Homepage": "https://palabra.ai",
"Issues": "https://github.com/PalabraAI/palabra-ai-python/issues",
"Repository": "https://github.com/PalabraAI/palabra-ai-python"
},
"split_keywords": [
"api-client",
" dubbing",
" palabra-ai",
" speech-translation",
" voice-synthesis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "681d2056b35ca8f799f5a3d6e3068d1e74b66610e0dfe2fdae374dad5b2eba42",
"md5": "e8bf0bd9c34ff02168c765cc0d6b6674",
"sha256": "ef7afcaad43e073db569d2f5a5bb86e5d57cb4282fac1952067fd00872b2b9cb"
},
"downloads": -1,
"filename": "palabra_ai-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e8bf0bd9c34ff02168c765cc0d6b6674",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 67226,
"upload_time": "2025-08-08T03:48:51",
"upload_time_iso_8601": "2025-08-08T03:48:51.254613Z",
"url": "https://files.pythonhosted.org/packages/68/1d/2056b35ca8f799f5a3d6e3068d1e74b66610e0dfe2fdae374dad5b2eba42/palabra_ai-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0c68202dfcaf393010fa4107b405f83ff1fe22bcf111cd3e1315e3e2b964aa1b",
"md5": "752c0126f30036a233681fbcd33b7444",
"sha256": "5365715d57a2529c8375f007abe138d8ec16208419528759237148c0e681f688"
},
"downloads": -1,
"filename": "palabra_ai-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "752c0126f30036a233681fbcd33b7444",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 1524774,
"upload_time": "2025-08-08T03:48:53",
"upload_time_iso_8601": "2025-08-08T03:48:53.123484Z",
"url": "https://files.pythonhosted.org/packages/0c/68/202dfcaf393010fa4107b405f83ff1fe22bcf111cd3e1315e3e2b964aa1b/palabra_ai-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 03:48:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PalabraAI",
"github_project": "palabra-ai-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "palabra-ai"
}
JSON
