Depdub 节点.js SDK

安装并使用 Depdub Node.js SDK 用于文本到语音生成,并有流支持.

安装

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

所需经费: 节点.js 18+(使用本地 fetch(中文(简体) )

初始化

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' });

构造参数

协议比较

使用 网络安全套 (默认)用于实时流回和低纬度回放. 使用 HTTP 密码 需要的时候 voiceReference 即时语音克隆或 sampleRate 带有非mp3格式.

区域终点

启用欧盟 { eu: true } 或者说 DD_EU=1。 。 。 .

连接

对于 WebSocket 协议,请拨 connect() 在使用前 generateToBuffer(), (中文(简体) ), generateToFile(),或 generateTo()。对于增量文本流,调用 asyncStreamConnect()。对于 HTTP 协议和 REST 方法,不需要连接步骤.

connect() — 打开 WebSocket 连接

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

回返情况: Promise<WebSocket> ——已打开的WebSocket连接.

参数

无参数 .

asyncConnect() -别提了 connect()

await deepdub.asyncConnect();

回返情况: Promise<WebSocket> ——已打开的WebSocket连接.

参数

无参数 .

disconnect() — 关闭 WebSocket 连接

await deepdub.connect();

// ...generate audio...

deepdub.disconnect();

打电话 disconnect() 当你完成 WebSocket。 如果你跳过它,打开的连接可以使节点.js进程保持活性.

回返情况: void

参数

无参数 .

文字对语言

tts() - 同步生成

生成语音并接收完整的音频 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);

回返情况: Promise<Buffer> ——指定格式的二进制音频数据.

参数

所有通用 TTS 参数的完整示例

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);

从音频引用语音克隆

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() ——逆向生成

提交 TTS 请求并接收一个 URL 供以后检索 .

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}`);

稍后用相同的方式获取音频 x-api-key 头曰.

回返情况: Promise<{ url: string }> - 具有下列特性的物体: url 键指向生成的音频.

参数

网络口袋 TTS

generateToBuffer() — 生成为缓冲

生成音频并接收 Buffer 音频数据。 WebSocket生成默认返回WAV.

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 生成默认为 format: 'wav'启用 { protocol: 'http' } 基于 HTTP 的客户端 generateToBuffer() 与 voiceReference 或者说 sampleRate 用于非mp3格式.

回返情况: Promise<Buffer> ——生成音频数据.

参数

generateToFile() — 生成为文件

生成音频并直接保存到文件 .

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();

回返情况: Promise<Buffer | void> ——为HTTP协议生成了音频数据,或者当WebSocket文件写入完成后解决.

参数

generateTo() – 低级生成辅助器

生成音频到选中输出类型 。 大多数应用程序应当使用 generateToBuffer() 或者说 generateToFile() 换句话说.

await deepdub.connect();

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

deepdub.disconnect();

回返情况: Promise<Buffer | void> ——生成用于缓冲输出的音频,或当文件输出完成后解析.

参数

流出块

用于实时播放的音频数据递增接收 :

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();

无头块

从每个块取出 WAV 信头用于原始PCM 数据 :

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() ——流体发电

在 WebSocket 上流音频块用于低频回放 。 如果没有WebSocket连接, asyncTts() 自动打开; 调用 disconnect() 当完成.

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();

当流出WAV输出时,将每个块保存为自己的WAV文件. 不要将 WAV 块与 Buffer.concat(),因为每个块都有自己的WAV头.

仪: Buffer ——生成的音频块.

参数

流出输入

用于实时文本流, 使用 asyncStreamConnect() 打开流入的 WebSocket, 以渐进方式发送文本 asyncStreamText(),以 asyncStreamEnd(),然后用 asyncStreamRecvAudio() 直到它回来 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();

对于 format: 'wav',每个音频块是一个独立的WAV文件. 将块单独保存, 而不是将其缩入一个文件 .

流入法

流程输入支持 wav, (中文(简体) ), s16le,以及 mulaw 输出格式.

同时代人

在同一 WebSocket 连接上并行运行多代 :

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();

语音管理

listVoices() — 列出所有语音提示

const voices = await deepdub.listVoices();

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

回返情况: Promise<{ voicePrompts: VoicePrompt[] }> - 具有下列特性的物体: voicePrompts 键中包含语音提示对象.

参数

addVoice() ——上传语音样本

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)}`);

回返情况: Promise<object> ——创建语音提示信息.

参数

CLI 参考

# 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

环境变量

处理错误

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);
  }
}

对于 WebSocket 操作,服务器错误被抛出为 Error 包含服务器消息,例如利率限制或信用值不足.

可用模式

测试

需要实时API测试 DEEPDUB_API_KEY 内 .env数字 :

npm test
npm run test:readme

设定 DEEPDUB_VOICE_REFERENCE_FILE 以启用可选语音引用测试. 设定 DEEPDUB_RUN_ADD_VOICE=1 包括创建持续语音提示的README实例.

个人套房: node test/test-tts.js, (中文(简体) ), node test/test-async-tts.js, (中文(简体) ), node test/test-eu-region.js等 (中文(简体) ).