deepdub-tts

Deepdub TTS

Use this skill to make Deepdub TTS integration frictionless and production-ready.

First Move

1. Identify the project surface: JavaScript/TypeScript, Python, CLI script, backend route, frontend proxy, or raw REST.
2. Prefer official SDKs over hand-written HTTP unless the project cannot add dependencies.
3. Read existing config patterns before editing. Add DEEPDUB_API_KEY to env docs, never hardcode user keys.
4. Pick a voice source:
   • Existing voice: voicePromptId
   • Instant voice cloning: voiceReference from an audio file, buffer, or base64
   • Demo: use a documented preset and the free trial key only in examples/docs
5. Leave the user with a runnable command that produces an audio file or endpoint response.

Defaults

• Auth: DEEPDUB_API_KEY
• Trial key for demos only: dd-00000000000000000000000065c9cbfe
• Common demo voice: Promo / Commercials, 50a537cf-1ec8-4714-b07e-c589ab76be4b
• Storyteller voice: bd1b00bb-be1c-4679-8eaa-0fcbfd4ff773
• Locale: en-US unless user asks otherwise
• Format: mp3 for REST/file downloads, wav for WebSocket streaming
• Node SDK: npm install @deepdub/node
• Python SDK: pip install deepdub
• US REST: https://restapi.deepdub.ai/api/v1
• EU REST: https://restapi.eu.deepdub.ai/api/v1
• Enable EU SDK endpoints with { eu: true } in Node or DD_EU=1 in env

Prefer the SDK default model unless the user asks for a specific model. Node SDK 2.x documents dd-etts-3.2 as the latest default. The public quickstart and Python SDK examples commonly use dd-etts-3.0.

JavaScript Pattern

For simple server-side generation, use HTTP mode so mp3, sampleRate, and voiceReference work consistently:

const fs = require("node:fs");
const { DeepdubClient } = require("@deepdub/node");

const deepdub = new DeepdubClient(process.env.DEEPDUB_API_KEY, {
  protocol: "http",
});

const audio = await deepdub.tts("Hello from Deepdub.", {
  voicePromptId: process.env.DEEPDUB_VOICE_PROMPT_ID,
  locale: "en-US",
  format: "mp3",
});

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

Use WebSocket mode when the app needs low-latency chunks:

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

const deepdub = new DeepdubClient(process.env.DEEPDUB_API_KEY);
await deepdub.connect();

try {
  await deepdub.generateToFile("output.wav", "Streaming speech.", {
    voicePromptId: process.env.DEEPDUB_VOICE_PROMPT_ID,
    locale: "en-US",
    onChunk: (chunk) => console.log(`chunk ${chunk.length}`),
  });
} finally {
  deepdub.disconnect();
}

Python Pattern

from pathlib import Path
from deepdub import DeepdubClient

client = DeepdubClient()

audio = client.tts(
    text="Hello from Deepdub.",
    voice_prompt_id="bd1b00bb-be1c-4679-8eaa-0fcbfd4ff773",
    locale="en-US",
    format="mp3",
)

Path("output.mp3").write_bytes(audio)

For streaming:

import asyncio
from pathlib import Path
from deepdub import DeepdubClient

async def main():
    client = DeepdubClient()
    audio = bytearray()
    async with client.async_connect() as conn:
        async for chunk in conn.async_tts(
            text="Streaming audio in real time.",
            voice_prompt_id="bd1b00bb-be1c-4679-8eaa-0fcbfd4ff773",
            locale="en-US",
            format="wav",
            sample_rate=16000,
        ):
            audio.extend(chunk)

    Path("streamed.wav").write_bytes(audio)

asyncio.run(main())

CLI And REST

When a user wants a terminal-only path, prefer the packaged CLI first:

npx @deepdub/agent-plugin tts \
  --text "Hello from Deepdub" \
  --voice-prompt-id bd1b00bb-be1c-4679-8eaa-0fcbfd4ff773 \
  --out output.mp3

Raw REST fallback:

curl -X POST https://restapi.deepdub.ai/api/v1/tts \
  -H "Content-Type: application/json" \
  -H "x-api-key: $DEEPDUB_API_KEY" \
  -d '{
    "targetText": "Hello from Deepdub",
    "locale": "en-US",
    "voicePromptId": "bd1b00bb-be1c-4679-8eaa-0fcbfd4ff773"
  }' \
  --output output.mp3

Implementation Checklist

• Install the SDK with the project's package manager.
• Add env docs: DEEPDUB_API_KEY, optionally DEEPDUB_VOICE_PROMPT_ID, DD_EU.
• Validate that exactly one of voicePromptId/voice_prompt_id or voiceReference/voice_reference is provided.
• Use duration or tempo, not both.
• Group accent settings together: base locale, target locale, and ratio.
• Return or write binary bytes without UTF-8/string conversion.
• Close WebSocket clients with disconnect() or an async context manager.
• Handle 401 invalid key, 402 insufficient credits, 429 rate limits, and 400 validation errors.
• Add a smoke test that mocks the SDK unless live API credentials are explicitly present.

More Detail

• For parameters, endpoints, and voice management, read reference.md.
• For copy-paste snippets and scaffolding prompts, read examples.md.
• To create starter files from a project, run node plugin/skills/deepdub-tts/scripts/scaffold-deepdub.js --language js --out ./deepdub-demo.