Digital Human Gateway SDK

数字人网关代理SDK，提供完整的数字人交互功能，包含数字人管理、音色管理、会话管理和TTS语音合成。

特性

• 🎭 数字人管理 - 获取数字人列表和详情
• 🎵 音色管理 - 获取音色列表和详情
• 🤝 会话管理 - 创建、验证和关闭会话
• 🎤 TTS语音合成 - 流式文本转语音，支持实时合成
• 🔌 Socket.IO代理 - 基于WebSocket的高效通信
• 🛡️ 自动重连 - 网络断线自动恢复
• 📊 状态监控 - 完整的连接和会话状态信息

安装

Node.js/ES Module 环境

npm install socket.io-client

浏览器环境

直接在HTML中引入打包后的文件：

<!-- 引入Socket.IO客户端 -->
<script src="https://cdn.socket.io/4.7.2/socket.io.min.js"></script>

<!-- 引入数字人网关SDK -->
<script src="./dist/digital-human-gateway-sdk.min.js"></script>

构建浏览器版本

如果需要在浏览器中直接使用，可以构建UMD版本：

# 安装构建依赖
npm install

# 构建生产版本
npm run build

# 构建开发版本（包含调试信息）
npm run build:dev

构建完成后会在 dist/ 目录生成 digital-human-gateway-sdk.min.js 文件。

更多构建说明请参考 BUILD_GUIDE.md

快速开始

1. Node.js/ES Module 环境

import DigitalHumanGatewaySDK, { TTSResultCallback } from './index.js';

// 初始化SDK
const sdk = new DigitalHumanGatewaySDK({
    gatewayUrl: 'http://localhost:3000',
    debug: true
});

// 获取数字人列表
const avatars = await sdk.getAvatars({ limit: 10 });
console.log('数字人列表:', avatars);

// 获取音色列表
const voices = await sdk.getVoices({ language: 'zh-CN' });
console.log('音色列表:', voices);

// 创建会话
const session = await sdk.createSession({
    avatarId: avatars.avatars[0].avatar_id,
    voiceId: voices.voices[0].voice_id,
    voiceConfig: {
        pitch_rate: 0,
        speech_rate: 0,
        volume: 80
    }
});
console.log('会话创建成功:', session.sessionId);

// 关闭会话
await sdk.closeSession();

2. 浏览器环境

<script>
// 直接使用全局变量 DigitalHumanGatewaySDK
const sdk = new DigitalHumanGatewaySDK({
    gatewayUrl: 'http://localhost:3000',
    debug: true
});

async function demo() {
    // 获取数字人列表
    const avatars = await sdk.getAvatars({ limit: 10 });
    console.log('数字人列表:', avatars);

    // 获取音色列表  
    const voices = await sdk.getVoices({ language: 'zh-CN' });
    console.log('音色列表:', voices);

    // 创建会话
    const session = await sdk.createSession({
        avatarId: avatars.avatars[0].avatar_id,
        voiceId: voices.voices[0].voice_id,
        voiceConfig: {
            pitch_rate: 0,
            speech_rate: 0,
            volume: 0
        }
    });
    console.log('会话创建成功:', session.sessionId);

    // 关闭会话
    await sdk.closeSession();
}

demo().catch(console.error);
</script>

3. TTS语音合成

// 创建TTS回调处理
class MyTTSCallback extends TTSResultCallback {
    onOpen() {
        console.log('TTS连接建立');
    }
    
    onComplete() {
        console.log('TTS合成完成');
    }
    
    onError(error) {
        console.error('TTS错误:', error);
    }
}

// 开始TTS合成
await sdk.startTTS('你好，欢迎使用数字人SDK！', {
    callback: new MyTTSCallback()
});

// 发送更多文本
sdk.sendTTSText('这是流式文本输入。');
sdk.sendTTSText('支持实时语音合成。');

// 完成合成
await sdk.completeTTS();

API 文档

DigitalHumanGatewaySDK

构造函数

new DigitalHumanGatewaySDK(options)

参数:

• options.gatewayUrl (string) - Gateway网关基础URL
• options.headers (object) - 自定义请求头
• options.timeout (number) - 请求超时时间（毫秒），默认10000
• options.debug (boolean) - 调试模式，默认false

数字人管理

getAvatars(options)

获取数字人列表。

参数:

• options.includeUnavailable (boolean) - 是否包含不可用的数字人
• options.tags (Array) - 标签过滤
• options.search (string) - 搜索关键词
• options.page (number) - 页码，默认1
• options.limit (number) - 每页数量，默认50

返回: Promise<object> - 数字人列表数据

{
    avatars: [
        {
            avatar_id: "avatar_001",
            name: "小美",
            description: "甜美女声数字人",
            tags: ["female", "young"],
            is_available: true,
            config: {}
        }
    ],
    total: 10,
    page: 1,
    limit: 50
}

getAvatarById(avatarId)

获取数字人详情。

参数:

• avatarId (string) - 数字人ID

返回: Promise<object> - 数字人详情

音色管理

getVoices(options)

获取音色列表。

参数:

• options.includeUnavailable (boolean) - 是否包含不可用的音色
• options.provider (string) - 语音提供商过滤
• options.language (string) - 语言过滤
• options.gender (string) - 性别过滤 ('male'|'female')
• options.tags (Array) - 标签过滤
• options.search (string) - 搜索关键词
• options.page (number) - 页码
• options.limit (number) - 每页数量

返回: Promise<object> - 音色列表数据

getVoiceById(voiceId)

获取音色详情。

参数:

• voiceId (string) - 音色ID

返回: Promise<object> - 音色详情

会话管理

createSession(options)

创建会话。

参数:

• options.avatarId (string) - 数字人ID
• options.voiceId (string) - 音色ID
• options.voiceConfig (object) - 音色配置
  • pitch_rate (number) - 语调调整 (0.5到2)
  • speech_rate (number) - 语速调整 (0.5到2)
  • volume (number) - 音量调整 (0~100)

返回: Promise<object> - 会话信息

{
    sessionId: "sess_123456",
    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    expiresAt: "2024-01-01T12:00:00Z"
}

closeSession(sessionId?)

关闭会话。

参数:

• sessionId (string, 可选) - 会话ID，不传则关闭当前会话

返回: Promise<boolean> - 是否成功关闭

getCurrentSession()

获取当前会话信息。

返回: object|null - 当前会话信息

validateSession(token?)

验证会话是否有效。

参数:

• token (string, 可选) - 会话Token，不传则验证当前会话

返回: Promise<object> - 会话验证结果

TTS语音合成

startTTS(text, options?)

开始TTS流式合成。

参数:

• text (string) - 初始文本
• options (object, 可选) - TTS配置选项

返回: Promise<TTSSpeechSynthesizer> - TTS客户端实例

sendTTSText(text)

发送TTS文本。

参数:

• text (string) - 要合成的文本

completeTTS(timeout?)

完成TTS合成。

参数:

• timeout (number, 可选) - 完成超时时间（毫秒），默认600000

返回: Promise<void>

cancelTTS()

取消TTS合成。

flushTTS()

清空TTS语音队列。

返回: Promise<void>

工具方法

getStatus()

获取SDK状态。

返回: object - SDK状态信息

cleanup()

清理资源。

TTSResultCallback

TTS结果回调基类，可继承并重写方法。

方法

• onOpen() - 连接建立时调用
• onClose() - 连接关闭时调用
• onComplete() - 语音合成完成时调用
• onError(error) - 发生错误时调用
• onEvent(message) - 接收到事件消息时调用
• onData(data) - 接收到数据时调用

AudioFormat

音频格式常量。

AudioFormat.WAV_16000HZ_MONO_16BIT
AudioFormat.WAV_22050HZ_MONO_16BIT
AudioFormat.WAV_24000HZ_MONO_16BIT
AudioFormat.MP3_16000HZ_MONO_128KBPS

完整示例

查看 examples/basic-usage.js 文件获取完整的使用示例。

运行示例：

node examples/basic-usage.js

错误处理

SDK提供了完善的错误处理机制：

try {
    const session = await sdk.createSession({
        avatarId: 'invalid_avatar',
        voiceId: 'invalid_voice'
    });
} catch (error) {
    console.error('创建会话失败:', error.message);
    
    // 错误类型判断
    if (error.message.includes('avatarId')) {
        console.log('数字人ID无效');
    }
}

注意事项

1. 依赖要求: 需要安装 socket.io-client 依赖
2. 网络要求: 确保能访问Gateway网关服务
3. 会话管理: 使用完毕后记得关闭会话以释放资源
4. 错误处理: 建议添加完善的错误处理逻辑
5. 资源清理: 程序退出前调用 cleanup() 方法清理资源

架构说明

客户端SDK -> Gateway代理 -> LiveTalking后端

• 客户端SDK: 提供统一的API接口
• Gateway代理: 负载均衡、会话管理、协议转换
• LiveTalking后端: 实际的数字人服务实例

支持分布式部署、负载均衡和自动故障恢复。

许可证

MIT License

更新日志

v1.0.0

• 初始版本
• 支持数字人和音色管理
• 支持会话管理
• 集成TTS语音合成功能
• 支持Socket.IO代理通信