tts

Camb.ai MARS text-to-speech service implementation.

This module provides TTS functionality using Camb.ai’s MARS model family, offering high-quality text-to-speech synthesis with streaming support.

Features:

• MARS models: mars-flash (fast), mars-pro (high quality)

• 140+ languages supported

• Real-time streaming via official SDK

• Model-specific sample rates: mars-pro (48kHz), mars-flash (22.05kHz)

pipecat.services.camb.tts.language_to_camb_language(language: Language) → str | None

Convert a Pipecat Language enum to Camb.ai language code.

Parameters:

language – The Language enum value to convert.

Returns:

The corresponding Camb.ai language code (BCP-47 format), or None if not supported.

class pipecat.services.camb.tts.CambTTSSettings(model: str | None | _NotGiven = <factory>, extra: dict[str, ~typing.Any]=<factory>, voice: int | _NotGiven = <factory>, language: Language | str | None | _NotGiven = <factory>, user_instructions: str | None | _NotGiven = <factory>)

Bases: TTSSettings

Settings for CambTTSService.

Parameters:

• voice – Camb.ai voice ID. Overrides TTSSettings.voice (str) because Camb.ai uses integer voice IDs.

• user_instructions – Custom instructions for mars-instruct model only. Ignored for other models. Max 1000 characters.

voice: int | _NotGiven

user_instructions: str | None | _NotGiven

class pipecat.services.camb.tts.CambTTSService(*, api_key: str, voice_id: int | None = None, model: str | None = None, timeout: float = 60.0, sample_rate: int | None = None, params: InputParams | None = None, settings: CambTTSSettings | None = None, **kwargs)

Bases: TTSService

Camb.ai MARS text-to-speech service using the official SDK.

Converts text to speech using Camb.ai’s MARS TTS models with support for multiple languages.

Models:

• mars-flash: Fast inference, 22.05kHz output (default)

• mars-pro: High quality, 48kHz output

Example:

# Basic usage with mars-flash (fast)
tts = CambTTSService(
    api_key="your-api-key",
    settings=CambTTSService.Settings(
        model="mars-flash"
    )
)

# High quality with mars-pro
tts = CambTTSService(
    api_key="your-api-key",
    settings=CambTTSService.Settings(
        voice=12345,
        model="mars-pro",
    )
)

Settings

alias of CambTTSSettings

class InputParams(*, language: Language | None = Language.EN, user_instructions: Annotated[str | None, MaxLen(max_length=1000)] = None)

Bases: BaseModel

Input parameters for Camb.ai TTS configuration.

Deprecated since version 0.0.105: Use settings=CambTTSService.Settings(...) instead.

Parameters:

• language – Language for synthesis (BCP-47 format). Defaults to English.

• user_instructions – Custom instructions for mars-instruct model only. Ignored for other models. Max 1000 characters.

language: Language | None

user_instructions: str | None

__init__(*, api_key: str, voice_id: int | None = None, model: str | None = None, timeout: float = 60.0, sample_rate: int | None = None, params: InputParams | None = None, settings: CambTTSSettings | None = None, **kwargs)

Initialize the Camb.ai TTS service.

Parameters:

• api_key – Camb.ai API key for authentication.

• voice_id –

  Voice ID to use.

  Deprecated since version 0.0.105: Use settings=CambTTSService.Settings(voice=...) instead.

• model –

  TTS model to use. Options: “mars-flash” (fast), “mars-pro” (high quality).

  Deprecated since version 0.0.105: Use settings=CambTTSService.Settings(model=...) instead.

• timeout – Request timeout in seconds. Defaults to 60.0 (minimum recommended by Camb.ai).

• sample_rate – Audio sample rate in Hz. If None, uses model-specific default.

• params –

  Additional voice parameters. If None, uses defaults.

  Deprecated since version 0.0.105: Use settings=CambTTSService.Settings(...) instead.

• settings – Runtime-updatable settings. When provided alongside deprecated parameters, settings values take precedence.

• **kwargs – Additional arguments passed to parent TTSService.

can_generate_metrics() → bool

Check if this service can generate processing metrics.

Returns:

True, as Camb.ai service supports metrics generation.

language_to_service_language(language: Language) → str | None

Convert a Language enum to Camb.ai language format.

Parameters:

language – The language to convert.

Returns:

The Camb.ai-specific language code, or None if not supported.

async start(frame: StartFrame)

Start the Camb.ai TTS service.

Parameters:

frame – The start frame containing initialization parameters.

async run_tts(text: str, context_id: str) → AsyncGenerator[Frame, None]

Generate speech from text using Camb.ai’s TTS API.

Parameters:

• text – The text to synthesize into speech (max 3000 characters).

• context_id – The context ID for tracking audio frames.

Yields:

Frame – Audio frames containing the synthesized speech.