Camb.ai TypeScript SDK

The official TypeScript SDK for interacting with Camb AI's powerful voice and audio generation APIs. Create expressive speech, unique voices, and rich soundscapes with just a few lines of code. Works seamlessly in Node.js environments (18+).

✨ Features

• Dubbing: Dub your videos into multiple languages with voice cloning!
• Expressive Text-to-Speech: Convert text into natural-sounding speech using a wide range of pre-existing voices.
• Generative Voices: Create entirely new, unique voices from text prompts and descriptions.
• Soundscapes from Text: Generate ambient audio and sound effects from textual descriptions.
• Live Transcription: Stream microphone (browser or Node) or file audio over a WebSocket and receive cumulative interim transcripts, word-level timing, and typed events.
• Realtime Speech-to-Speech Translation: Stream speech over a WebSocket and receive the translation as live text and synthesized speech.
• Access to voice cloning, translation, and more (refer to full API documentation).

📦 Installation

Install the SDK using npm (requires Node.js 18+):

npm install @camb-ai/sdk

🔑 Authentication & Accessing Clients

To use the Camb AI SDK, you'll need an API key. You can authenticate it by:

import { CambClient } from "@camb-ai/sdk";

// Initialize the client
const client = new CambClient({ apiKey: "YOUR_CAMB_API_KEY" });

Client with Custom Hosting Provider (e.g. Baseten, Vertex)

Baseten

To deploy the model go to models from baseten example: https://www.baseten.co/library/mars6/ and deploy then perform setup like below

import { CambClient, CambApi, saveStreamToFile } from "@camb-ai/sdk";
import * as fs from "fs";

// Initialize client with Baseten provider
const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
  ttsProvider: "baseten",
  providerParams: {
    api_key: process.env.BASETEN_API_KEY,
    mars_pro_url: process.env.BASETEN_URL,
  },
});

async function main() {
  try {
    // Read reference audio file (you need to provide this)
    const referenceAudioPath =
      process.env.REFERENCE_AUDIO_PATH || "reference.wav";

    if (!fs.existsSync(referenceAudioPath)) {
      console.error(`Reference audio file not found: ${referenceAudioPath}`);
      console.log(
        "Please provide a reference audio file or set REFERENCE_AUDIO_PATH environment variable",
      );
      return;
    }

    const referenceAudio = fs
      .readFileSync(referenceAudioPath)
      .toString("base64");

    console.log("Generating speech with Baseten provider...");
    const requestPayload = {
      text: "Hello World and my dear friends",
      language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
      speech_model:
        CambApi.CreateStreamTtsRequestPayload.SpeechModel.Mars81FlashBeta,
      voice_id: 1, // Required but ignored when using custom hosting provider
      additional_body_parameters: {
        reference_audio: referenceAudio,
        reference_language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs, // required
      },
    };

    const response = await client.textToSpeech.tts(requestPayload);

    const outputFile = "baseten_output.wav";
    await saveStreamToFile(response, outputFile);
    console.log(
      `✓ Audio generated with Baseten provider and saved to ${outputFile}`,
    );
  } catch (error) {
    console.error("Error:", error.message);
    if (error.body) {
      console.error("Details:", error.body);
    }
  }
}

main();

🚀 Getting Started: Examples

NOTE: For more examples and full ready to run files refer to the examples/ directory.

1. Text-to-Speech (TTS)

Convert text into spoken audio using one of Camb AI's high-quality voices.

Supported Models & Sample Rates

| Model Name | Sample Rate | Description | | :---------------- | :----------- | :------------------------------------------------------------------------------------------- | | mars-pro | 48kHz | High-fidelity, professional-grade speech synthesis. Ideal for long-form content and dubbing. | | mars-instruct | 22.05kHz | Optimized for instruction-following and nuance control. | | mars-flash | 22.05kHz | Low-latency model optimized for real-time applications and conversational AI. |

a) Get Audio and Save to File

import { CambClient, CambApi, saveStreamToFile } from "@camb-ai/sdk";

// Initialize client (ensure API key is set)
const client = new CambClient({ apiKey: "YOUR_CAMB_API_KEY" });

const response = await client.textToSpeech.tts({
  text: "Hello from Camb AI! This is a test of our Text-to-Speech API.",
  voice_id: 20303, // Example voice ID, get from client.voiceCloning.listVoices()
  language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
  speech_model:
    CambApi.CreateStreamTtsRequestPayload.SpeechModel.Mars81FlashBeta, // options: mars-pro, mars-flash, mars-instruct, mars-8-pro-beta, mars-8-flash-beta, mars-8, mars-8-flash, mars-8-instruct, mars-7, mars-6
  output_configuration: {
    format: "wav",
  },
});

await saveStreamToFile(response, "tts_output.wav");
console.log("Success! Audio saved to tts_output.wav");

b) Using Mars Flash (Low Latency)

For applications requiring faster responses, switch to mars-flash (22.05kHz).

const response = await client.textToSpeech.tts({
  text: "Hey! I can respond much faster.",
  language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
  speech_model: CambApi.CreateStreamTtsRequestPayload.SpeechModel.MarsFlash,
  voice_id: 20303,
  output_configuration: {
    format: "wav",
  },
});

await saveStreamToFile(response, "fast_output.wav");

c) List Available Voices

You can list available voices to find a voice_id that suits your needs:

const voices = await client.voiceCloning.listVoices();
console.log(`Found ${voices.length} voices:`);

for (const voice of voices.slice(0, 5)) {
  // Print first 5 as an example
  console.log(
    `  - ID: ${voice.id}, Name: ${voice.voice_name}, Gender: ${voice.gender}, Language: ${voice.language}`,
  );
}

2. Text-to-Voice (Generative Voice)

Create completely new and unique voices from a textual description of the desired voice characteristics.

import { CambClient } from "@camb-ai/sdk";

const client = new CambClient({ apiKey: "YOUR_CAMB_API_KEY" });

try {
  console.log("Generating a new voice and speech...");
  // Returns 3 sample URLs
  const result = await client.textToVoice.createTextToVoice({
    text: "Crafting a truly unique and captivating voice that carries a subtle air of mystery, depth, and gentle warmth.",
    voice_description:
      "A smooth, rich baritone voice layered with a soft echo, ideal for immersive storytelling and emotional depth.",
  });
  console.log(result);
} catch (error) {
  console.error(`Exception when calling textToVoice: ${error}`);
}

3. Text-to-Audio (Sound Generation)

Generate sound effects or ambient audio from a descriptive prompt.

import { CambClient, saveStreamToFile } from "@camb-ai/sdk";

const client = new CambClient({ apiKey: "YOUR_CAMB_API_KEY" });

const response = await client.textToAudio.createTextToAudio({
  prompt: "A gentle breeze rustling through autumn leaves in a quiet forest.",
  duration: 10,
  audio_type: "sound",
});

const taskId = response.task_id;
if (taskId) {
  while (true) {
    const status = await client.textToAudio.getTextToAudioStatus({
      task_id: taskId,
    });
    console.log(`Status: ${status.status}`);

    if (status.status === "SUCCESS") {
      const result = await client.textToAudio.getTextToAudioResult({
        run_id: status.run_id,
      });
      await saveStreamToFile(result, "sound_effect.mp3");
      console.log("Success! Sound effect saved to sound_effect.mp3");
      break;
    }

    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
}

4. End-to-End Dubbing

Dub videos into different languages with voice cloning and translation capabilities.

import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({ apiKey: "YOUR_CAMB_API_KEY" });

const response = await client.dub.endToEndDubbing({
  video_url: "your_accessible_video_url",
  source_language: CambApi.Languages.EN_US, // Check client.languages.getSourceLanguages()
  target_language: CambApi.Languages.HI_IN, // Example target language
});

const taskId = response.task_id;
console.log(`Dub Task created with ID: ${taskId}`);

while (true) {
  const statusResponse = await client.dub.getDubbingStatus({ task_id: taskId });
  console.log(`Current Status: ${statusResponse.status}`);

  if (statusResponse.status === "SUCCESS") {
    const dubbedRunInfo = await client.dub.getDubbedRunInfo({
      run_id: statusResponse.run_id,
    });
    console.log(`Dubbed Audio URL: ${dubbedRunInfo.audio_url}`);
    console.log(`Transcript: ${dubbedRunInfo.transcript}`);
    console.log(`Dubbed Video URL: ${dubbedRunInfo.video_url}`);
    break;
  }

  await new Promise((resolve) => setTimeout(resolve, 5000));
}

5. Live Transcription (Streaming WebSocket)

Stream audio over a single WebSocket and receive cumulative interim transcripts, word-level timing, and typed events. The session ships a microphone helper for both browser (AudioWorklet) and Node (node-record-lpcm16) environments, and the same on(event) dispatcher as the Python SDK.

import { CambClient, Microphone, ServerMessageType, bindTranscriptPrinter } from "@camb-ai/sdk";

const client = new CambClient({ apiKey: process.env.CAMB_API_KEY });

const session = await client.liveTranscription.connect({
  model: "boli-v5",
  language: "en-us",
  sampleRate: 16000,
});

session.on(ServerMessageType.Ready, () => console.log("Ready"));

const printer = bindTranscriptPrinter(session);

session.on(ServerMessageType.Closed, (info) => {
  printer.newline();
  console.log(`Closed: code=${info.code} reason=${info.reason}`);
});

await session.waitUntilReady();

// Node:
const mic = Microphone.fromNode({ sampleRate: 16000 });
await mic.start();
await session.pipe(mic);

// Browser:
// const mic = await Microphone.fromBrowser({ sampleRate: 16000 });
// await mic.start();
// await session.pipe(mic);

Optional peer deps:

# Node header-based auth on the WebSocket upgrade
npm install ws

# Node microphone capture (requires the host `sox` binary)
npm install node-record-lpcm16

Prefer streaming a file (no audio device dependency)? See examples/live-transcription-file.js. For the full event catalog (Ready, Results, Final, Error, Closed), configuration options, and extensibility notes, see the Live Transcription tutorial and SDK guide.

6. Realtime Speech-to-Speech Translation (Streaming WebSocket)

Speak (or stream a file) in one language and receive the translation as live text and synthesized speech over a single WebSocket. Audio is PCM16 mono at 24 kHz in both directions.

import { CambClient, Microphone, RealtimeServerEventType } from "@camb-ai/sdk";

const client = new CambClient({ apiKey: process.env.CAMB_API_KEY });

const session = await client.realtime.connect({
  sourceLanguage: "en-us",
  targetLanguage: "de-de",
});

session.on(RealtimeServerEventType.TextDone, (event) =>
  console.log(`[translation] ${event.text}`),
);

session.on(RealtimeServerEventType.AudioDelta, (event) => {
  // event.data is raw PCM16 mono 24 kHz — play it through your speakers
});

await session.waitUntilReady();

const mic = Microphone.fromNode({ sampleRate: 24000 });
await mic.start();
await session.stream(mic);

Runnable examples: examples/realtime-translation-microphone.js (mic in, translated speech out) and examples/realtime-translation-file.js (WAV in, translated WAV out — no audio device needed). For the full event list and configuration, see the Realtime Speech Translation tutorial and the WebSocket API reference.

⚙️ Advanced Usage & Other Features

The Camb AI SDK offers a wide range of capabilities beyond these examples, including:

• Voice Cloning
• Translated TTS
• Audio Dubbing
• Transcription (async file/URL jobs)
• Live Transcription (streaming WebSocket — see Example 5 above)
• Realtime Speech-to-Speech Translation (streaming WebSocket — see Example 6 above)
• And more!

Please refer to the Official Camb AI API Documentation for a comprehensive list of features and advanced usage patterns.

📚 TypeScript Support

This SDK is written in TypeScript and includes full type definitions. You can use it in TypeScript projects with full IntelliSense support:

import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({ apiKey: "YOUR_CAMB_API_KEY" });

// Full type safety
const response: AsyncIterable<Uint8Array> = await client.textToSpeech.tts({
  text: "Hello world",
  language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
  speech_model:
    CambApi.CreateStreamTtsRequestPayload.SpeechModel.Mars81FlashBeta,
  voice_id: 20303,
});

📖 Examples

Check out the examples/ directory for complete, runnable examples:

• basic-tts.js - Basic text-to-speech example
• text-to-audio.js - Sound generation example
• dubbing.js - Video dubbing workflow
• baseten-provider.js - Using custom hosting providers
• live-transcription-microphone.js - Stream microphone audio over the WebSocket (uses node-record-lpcm16)
• live-transcription-file.js - Stream a local WAV at real-time pace (no audio device required)

🔗 Links

• Documentation
• GitHub Repository
• Python SDK

License

This project is licensed under the MIT License - see the LICENSE file for details.