Deepdub Node.js SDK

Install and use the Deepdub Node.js SDK for text-to-speech generation with streaming support.

Installation

npm install --save @deepdub/node
# or
yarn add @deepdub/node

Requirements: Node.js 18+ (uses native fetch)

Initialization

const { DeepdubClient } = require('@deepdub/node');

// Option 1: Pass API key directly
const deepdub = new DeepdubClient('dd-your-api-key');

// Option 2: Use DEEPDUB_API_KEY environment variable
require('dotenv').config();
const deepdubFromEnv = new DeepdubClient();

// HTTP protocol supports voiceReference and sampleRate with all formats
const deepdubHttp = new DeepdubClient('dd-your-api-key', { protocol: 'http' });

Constructor parameters

Protocol comparison

Use WebSocket (default) for real-time streaming and low-latency playback. Use HTTP when you need voiceReference for instant voice cloning or sampleRate with non-mp3 formats.

Region endpoints

Enable EU with { eu: true } or DD_EU=1.

Connection

For WebSocket protocol, call connect() before using generateToBuffer(), generateToFile(), or generateTo(). For incremental text streaming, call asyncStreamConnect(). For HTTP protocol and REST methods, no connection step is needed.

connect() — Open a WebSocket connection

const deepdub = new DeepdubClient('dd-your-api-key');
await deepdub.connect();

Returns: Promise<WebSocket> — the opened WebSocket connection.

Parameters

No parameters.

asyncConnect() — Alias for connect()

await deepdub.asyncConnect();

Returns: Promise<WebSocket> — the opened WebSocket connection.

Parameters

No parameters.

disconnect() — Close the WebSocket connection

await deepdub.connect();

// ...generate audio...

deepdub.disconnect();

Call disconnect() when you are done with the WebSocket. If you skip it, the open connection keeps the Node.js process alive.

Returns: void

Parameters

No parameters.

Text-to-Speech

tts() — Synchronous generation

Generate speech and receive the complete audio as a Buffer.

const fs = require('fs');

const audio = await deepdub.tts('Hello, welcome to Deepdub!', {
  voicePromptId: 'your-voice-id',
  model: 'dd-etts-3.2',
  locale: 'en-US',
  format: 'mp3',
});

fs.writeFileSync('output.mp3', audio);

Returns: Promise<Buffer> — binary audio data in the specified format.

Parameters

Full example with all common TTS parameters

const audio = await deepdub.tts('This demonstrates common TTS parameters.', {
  voicePromptId: 'your-voice-id',
  model: 'dd-etts-3.2',
  locale: 'en-US',
  format: 'mp3',
  temperature: 0.7,
  variance: 0.6,
  tempo: 1.1,
  seed: 42,
  promptBoost: true,
  sampleRate: 44100,
  accentBaseLocale: 'en-US',
  accentLocale: 'fr-FR',
  accentRatio: 0.3,
});

require('fs').writeFileSync('output.mp3', audio);

Voice cloning from audio reference

const audio = await deepdub.tts('Cloning a voice from an audio sample.', {
  voiceReference: './reference_audio.mp3',
  model: 'dd-etts-3.2',
  locale: 'en-US',
});

require('fs').writeFileSync('cloned_output.mp3', audio);

ttsRetro() — Retroactive generation

Submit a TTS request and receive a URL for later retrieval.

const response = await deepdub.ttsRetro('Generate this audio for later retrieval.', {
  voicePromptId: 'your-voice-id',
  model: 'dd-etts-3.2',
  locale: 'en-US',
});

const audioUrl = response.url;
console.log(`Audio available at: ${audioUrl}`);

Fetch the audio later with the same x-api-key header.

Returns: Promise<{ url: string }> — an object with a url key pointing to the generated audio.

Parameters

WebSocket TTS

generateToBuffer() — Generate to buffer

Generate audio and receive a Buffer of audio data. WebSocket generation returns WAV by default.

const deepdub = new DeepdubClient('dd-your-api-key');
await deepdub.connect();

const buffer = await deepdub.generateToBuffer('Hello, welcome to Deepdub!', {
  locale: 'en-US',
  voicePromptId: 'your-voice-id',
});

console.log(`Generated ${buffer.length} bytes of audio`);
deepdub.disconnect();

WebSocket generation defaults to format: 'wav'. Use { protocol: 'http' } on the client for HTTP-based generateToBuffer() with voiceReference or sampleRate for non-mp3 formats.

Returns: Promise<Buffer> — generated audio data.

Parameters

generateToFile() — Generate to file

Generate audio and save directly to a file.

const deepdub = new DeepdubClient('dd-your-api-key');
await deepdub.connect();

await deepdub.generateToFile('./output.wav', 'Hello, welcome to Deepdub!', {
  locale: 'en-US',
  voicePromptId: 'your-voice-id',
});

deepdub.disconnect();

Returns: Promise<Buffer | void> — generated audio data for HTTP protocol, or resolves when the WebSocket file write completes.

Parameters

generateTo() — Low-level generation helper

Generate audio to a selected output type. Most applications should use generateToBuffer() or generateToFile() instead.

await deepdub.connect();

const buffer = await deepdub.generateTo('buffer', 'Hello from the low-level API.', {
  locale: 'en-US',
  voicePromptId: 'your-voice-id',
});

deepdub.disconnect();

Returns: Promise<Buffer | void> — generated audio for buffer output, or resolves when file output completes.

Parameters

Streaming chunks

Receive audio data incrementally for real-time playback:

const deepdub = new DeepdubClient('dd-your-api-key');
await deepdub.connect();

const buffer = await deepdub.generateToBuffer('Streaming audio in real time!', {
  locale: 'en-US',
  voicePromptId: 'your-voice-id',
  model: 'dd-etts-3.2',
  onChunk: (chunk) => {
    console.log(`Received ${chunk.length} bytes`);
    // Stream to an audio player, network response, etc.
  },
});

deepdub.disconnect();

Headerless chunks

Strip WAV headers from each chunk for raw PCM data:

const fs = require('fs');
const deepdub = new DeepdubClient('dd-your-api-key');
await deepdub.connect();

const audioPlayer = fs.createWriteStream('raw-audio.pcm');

await deepdub.generateToBuffer('Raw PCM streaming.', {
  locale: 'en-US',
  voicePromptId: 'your-voice-id',
  headerless: true,
  onChunk: (chunk) => {
    audioPlayer.write(chunk);
  },
});

audioPlayer.end();
deepdub.disconnect();

asyncTts() — Streaming generation

Stream audio chunks over WebSocket for low-latency playback. If no WebSocket is connected, asyncTts() opens one automatically; call disconnect() when finished.

const fs = require('fs');
const deepdub = new DeepdubClient('dd-your-api-key');

fs.mkdirSync('streamed-chunks', { recursive: true });

let chunkIndex = 0;
for await (const chunk of deepdub.asyncTts('Streaming audio in real time!', {
  voicePromptId: 'your-voice-id',
  model: 'dd-etts-3.2',
  locale: 'en-US',
  format: 'wav',
})) {
  const filename = `streamed-chunks/chunk-${String(chunkIndex).padStart(3, '0')}.wav`;
  fs.writeFileSync(filename, chunk);
  console.log(`Received chunk: ${chunk.length} bytes`);
  chunkIndex += 1;
}

deepdub.disconnect();

When streaming WAV output, save each chunk as its own WAV file. Do not concatenate WAV chunks with Buffer.concat(), because each chunk has its own WAV header.

Yields: Buffer — audio chunks as they are generated.

Parameters

Streaming Input

For real-time text streaming, use asyncStreamConnect() to open the streaming-input WebSocket, send text incrementally with asyncStreamText(), signal completion with asyncStreamEnd(), then drain audio with asyncStreamRecvAudio() until it returns null.

const fs = require('fs');
const deepdub = new DeepdubClient('dd-your-api-key');

await deepdub.asyncStreamConnect({
  model: 'dd-etts-3.2',
  locale: 'en-US',
  voicePromptId: 'your-voice-id',
  format: 'wav',
  sampleRate: 16000,
});

fs.mkdirSync('streamed-input-chunks', { recursive: true });

await deepdub.asyncStreamText('Hello, ');
await deepdub.asyncStreamText('this is streamed ');
await deepdub.asyncStreamText('text input.');
await deepdub.asyncStreamEnd();

let chunkIndex = 0;
while (true) {
  const audio = await deepdub.asyncStreamRecvAudio({ timeoutMs: 3000 });
  if (audio === null) {
    break;
  }

  const filename = `streamed-input-chunks/chunk-${String(chunkIndex).padStart(3, '0')}.wav`;
  fs.writeFileSync(filename, audio);
  chunkIndex += 1;
}

deepdub.disconnectStreaming();

For format: 'wav', each audio chunk is a standalone WAV file. Save chunks individually instead of concatenating them into one file.

Streaming input methods

Streaming input supports wav, s16le, and mulaw output formats.

Concurrent generations

Run multiple generations in parallel on the same WebSocket connection:

const deepdub = new DeepdubClient('dd-your-api-key');
await deepdub.connect();

const sentences = [
  'First sentence to generate.',
  'Second sentence in parallel.',
  'Third sentence simultaneously.',
];

await Promise.all(
  sentences.map((text, index) =>
    deepdub.generateToFile(`./output_${index}.wav`, text, {
      locale: 'en-US',
      voicePromptId: 'your-voice-id',
      model: 'dd-etts-3.2',
    })
  )
);

deepdub.disconnect();

Voice Management

listVoices() — List all voice prompts

const voices = await deepdub.listVoices();

for (const voice of voices.voicePrompts ?? []) {
  console.log(`${voice.id}: ${voice.name ?? voice.title ?? 'Untitled'}`);
}

Returns: Promise<{ voicePrompts: VoicePrompt[] }> — an object with a voicePrompts key containing voice prompt objects.

Parameters

addVoice() — Upload a voice sample

const response = await deepdub.addVoice({
  data: './voice_sample.wav',
  name: 'Professional Narrator',
  gender: 'female',
  locale: 'en-US',
  publish: false,
  speakingStyle: 'Neutral',
  age: 30,
});

console.log(`Created voice: ${JSON.stringify(response)}`);

Returns: Promise<object> — created voice prompt information.

Parameters

CLI Reference

# List available voices
deepdub list-voices

# Upload a new voice
deepdub add-voice \
  --file path/to/audio.mp3 \
  --name "My Voice" \
  --gender male \
  --locale en-US

# Generate text-to-speech
deepdub tts \
  --text "Hello from the CLI!" \
  --voice-prompt-id your-voice-id \
  --out output.mp3

# Set API key via flag or environment
deepdub --api-key dd-your-key tts --text "Hello!" --voice-prompt-id your-id
export DEEPDUB_API_KEY=dd-your-key

Environment Variables

Error Handling

try {
  const audio = await deepdub.tts('Hello!', {
    voicePromptId: 'your-voice-id',
  });
} catch (error) {
  if (error.status === 401) {
    console.error('Invalid API key');
  } else if (error.status === 400) {
    console.error('Invalid request parameters:', error.message);
  } else {
    console.error('API error:', error.message);
  }
}

For WebSocket operations, server errors are thrown as Error with the server message, such as rate limits or insufficient credits.

Available Models

Tests

Live API tests require DEEPDUB_API_KEY in .env:

npm test
npm run test:readme

Set DEEPDUB_VOICE_REFERENCE_FILE to a real reference audio file to enable the optional voice reference test. Set DEEPDUB_RUN_ADD_VOICE=1 to include README examples that create persisted voice prompts.

Individual suites: node test/test-tts.js, node test/test-async-tts.js, node test/test-eu-region.js, etc.