langchain-camb

LangChain integration for CAMB AI - multilingual audio and localization services supporting 140+ languages.

Installation

pip install langchain-camb

Quick Start

from langchain_camb import CambToolkit, CambTTSTool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

# Set your API key
import os
os.environ["CAMB_API_KEY"] = "your-api-key"

# Use individual tools
tts = CambTTSTool()
audio_path = tts.invoke({
    "text": "Hello, world!",
    "language": "en-us",
    "voice_id": 147320
})
print(f"Audio saved to: {audio_path}")

# Or use the toolkit with a LangChain agent
toolkit = CambToolkit()
agent = create_react_agent(ChatOpenAI(), toolkit.get_tools())

result = agent.invoke({
    "messages": [{"role": "user", "content": "Say 'Good morning' in Spanish"}]
})

Available Tools

Tool Examples

Text-to-Speech

from langchain_camb import CambTTSTool

tts = CambTTSTool()
result = tts.invoke({
    "text": "Hello, how are you today?",
    "language": "en-us",
    "voice_id": 147320,
    "speech_model": "mars-flash",  # or "mars-pro", "mars-instruct"
    "speed": 1.0,  # 0.5 to 2.0
    "output_format": "file_path"  # or "base64", "bytes"
})

Translation

from langchain_camb import CambTranslationTool

translator = CambTranslationTool()
result = translator.invoke({
    "text": "Hello, how are you?",
    "source_language": 1,   # English (en-us)
    "target_language": 54,  # Spanish (es-es)
    "formality": 1  # 1=formal, 2=informal
})
print(result)  # "Hola, ¿cómo está usted?"

Transcription

from langchain_camb import CambTranscriptionTool

transcriber = CambTranscriptionTool()
result = transcriber.invoke({
    "audio_url": "https://example.com/audio.mp3",
    "language": 1  # English
})
# Returns JSON with text, segments, and speaker identification

Voice Cloning

from langchain_camb import CambVoiceCloneTool

cloner = CambVoiceCloneTool()
result = cloner.invoke({
    "voice_name": "My Custom Voice",
    "audio_file_path": "/path/to/sample.wav",  # 2+ seconds
    "gender": 2,  # 1=Male, 2=Female
    "description": "A warm, friendly voice"
})
# Returns new voice_id to use with TTS

Text-to-Sound

from langchain_camb import CambTextToSoundTool

sound_gen = CambTextToSoundTool()
result = sound_gen.invoke({
    "prompt": "Upbeat electronic music with a driving beat",
    "duration": 30,
    "audio_type": "music"  # or "sound"
})

Audio Separation

from langchain_camb import CambAudioSeparationTool

separator = CambAudioSeparationTool()
result = separator.invoke({
    "audio_file_path": "/path/to/mixed_audio.mp3"
})
# Returns JSON with paths to vocals and background audio

Using the Toolkit

The CambToolkit bundles all tools and allows filtering:

from langchain_camb import CambToolkit

# All tools
toolkit = CambToolkit()
tools = toolkit.get_tools()

# TTS-focused toolkit
tts_toolkit = CambToolkit(
    include_tts=True,
    include_voice_list=True,
    include_translation=False,
    include_transcription=False,
    include_translated_tts=False,
    include_voice_clone=False,
    include_text_to_sound=False,
    include_audio_separation=False,
)

# Translation-focused toolkit
translation_toolkit = CambToolkit(
    include_tts=False,
    include_translated_tts=True,
    include_translation=True,
    include_transcription=True,
    include_voice_list=False,
    include_voice_clone=False,
    include_text_to_sound=False,
    include_audio_separation=False,
)

Language Codes

CAMB AI uses integer language codes. Common codes:

Use client.languages.get_source_languages() for the full list of 140+ languages.

For TTS, use BCP-47 codes like "en-us", "es-es", "fr-fr".

Configuration

API Key

Set your API key via environment variable or parameter:

# Environment variable
import os
os.environ["CAMB_API_KEY"] = "your-api-key"

# Or pass directly
tool = CambTTSTool(api_key="your-api-key")
toolkit = CambToolkit(api_key="your-api-key")

Timeouts and Polling

For async operations (transcription, text-to-sound, etc.):

tool = CambTranscriptionTool(
    timeout=60.0,         # HTTP request timeout
    max_poll_attempts=60, # Max polling attempts
    poll_interval=2.0,    # Seconds between polls
)

Agent Integration

LangGraph ReAct Agent

from langchain_camb import CambToolkit
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

toolkit = CambToolkit()
agent = create_react_agent(ChatOpenAI(model="gpt-4"), toolkit.get_tools())

# TTS
result = agent.invoke({
    "messages": [{"role": "user", "content": "Say 'Hello world' in a friendly tone"}]
})

# Translation
result = agent.invoke({
    "messages": [{"role": "user", "content": "Translate 'Good morning' to French and German"}]
})

# Transcription
result = agent.invoke({
    "messages": [{"role": "user", "content": "Transcribe https://example.com/audio.mp3"}]
})

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run unit tests
pytest tests/unit/

# Run integration tests (requires CAMB_API_KEY)
CAMB_API_KEY=your-key pytest tests/integration/ -m integration

# Lint
ruff check .

# Type check
mypy langchain_camb/

License

MIT