@iwhalecloud-lab/metamee-digital-picture2d-render

这是一个用于渲染数字人形象的JavaScript库，支持TTS（文字转语音）和口型同步动画。

功能特点

• 支持自定义数字人形象图片
• 支持TTS文字转语音
• 支持口型同步动画
• 支持队列播放
• 支持中断播放
• 支持自定义样式
• 支持前端渲染口型
• 支持自定义嘴型映射和音频分析精度
• 支持隐藏嘴型、debug模式

安装

npm install @iwhalecloud-lab/metamee-digital-picture2d-render

使用方法

1. 初始化

import { init } from '@iwhalecloud-lab/metamee-digital-picture2d-render';

// 初始化配置
const config = {
  id: 'avatar-container', // 挂载的DOM元素ID
  avatarImagePath: '/path/to/avatar/', // 形象图片路径
  avatarImageFileName: 'digital.gif', // 形象图片文件名
  avatarImagePlayFileName: 'digital-play.gif', // 播放中的形象图片文件名（可选）
  avatarMouthStartFileName: 'a.png', // 默认口型图片（可选，默认a.png）
  height: '400px', // 高度（可选）
  width: '300px', // 宽度（可选）
  avatarMouthStyle: 'width:25px;top:calc(50% + 15px);left:calc(50% - 23px);', // 口型图片样式（可选）
  render: 'server', // 渲染模式，可选'server'或'front'，默认'server'
  hideMouth: false, // 是否隐藏嘴型，默认false
  debug: false, // 是否开启debug模式，默认false
  mouthThrottleInterval: 200, // 嘴型切换节流间隔(ms)，默认200
  mouthTypeMappings: [ // 音量级别与嘴型的映射关系（可选）
    { threshold: 240, type: 'f' },
    { threshold: 180, type: 'd' },
    { threshold: 140, type: 'h' },
    { threshold: 100, type: 'e' },
    { threshold: 60, type: 'c' },
    { threshold: 20, type: 'b' },
    { threshold: -Infinity, type: 'x' }
  ],
  fftSize: 2048, // 音频分析精度，2的幂，默认2048
  options: {
    onSuccess: () => {
      console.log('初始化成功');
    },
    onError: (error) => {
      console.error('初始化失败:', error);
    }
  }
};

init(config);

2. 发送TTS请求

import { sendToTTS } from '@iwhalecloud-lab/metamee-digital-picture2d-render';

const ttsConfig = {
  url: 'https://api.example.com/tts', // TTS服务地址
  text: '你好，我是数字人', // 要转换的文本
  role: 'female', // 声音风格（可选）
  headers: {
    'Content-Type': 'application/json'
  },
  data: {}, // 额外参数（可选）
  options: {
    onSuccess: () => {
      console.log('TTS转换成功');
    },
    onError: (error) => {
      console.error('TTS转换失败:', error);
    }
  }
};

sendToTTS(ttsConfig);

3. 中断播放

import { abort } from '@iwhalecloud-lab/metamee-digital-picture2d-render';

// 中断当前播放和请求
abort();

API文档

init(config: InitConfig)

初始化数字人形象。

InitConfig 配置项

| 字段 | 类型 | 说明 | 是否必填 | 默认值 | | ---- | ---- | ---- | ---- | ---- | | id | string | 挂载的DOM元素ID | 是 | - | | avatarImagePath | string | 形象图片路径 | 是 | - | | avatarImageFileName | string | 形象图片文件名 | 是 | 'digital.gif' | | avatarImagePlayFileName | string | 播放时的形象图片文件名 | 否 | - | | avatarMouthStartFileName | string | 默认嘴型图片名 | 否 | 'a.png' | | height | string|number | 渲染高度 | 否 | - | | width | string|number | 渲染宽度 | 否 | - | | avatarMouthStyle | string | 嘴型图片样式 | 否 | - | | render | 'server'|'front' | 渲染模式 | 否 | 'server' | | hideMouth | boolean | 是否隐藏嘴型 | 否 | false | | debug | boolean | 是否debug模式 | 否 | false | | mouthThrottleInterval | number | 嘴型切换节流(ms) | 否 | 200 | | mouthTypeMappings | Array<{threshold:number,type:string}> | 音量与嘴型映射 | 否 | 见下方默认值 | | fftSize | number | 音频分析精度 | 否 | 2048 | | options | Options | 回调函数配置 | 否 | - |

默认mouthTypeMappings:

[
  { threshold: 240, type: 'f' },
  { threshold: 180, type: 'd' },
  { threshold: 140, type: 'h' },
  { threshold: 100, type: 'e' },
  { threshold: 60, type: 'c' },
  { threshold: 20, type: 'b' },
  { threshold: -Infinity, type: 'x' }
]

Options 回调配置

| 字段 | 类型 | 说明 | | ---- | ---- | ---- | | onSuccess | () => void | 成功回调 | | onError | (errMsg:any) => void | 失败回调 |

sendToTTS(config: ttsConfig)

发送TTS请求。

ttsConfig 配置项

| 字段 | 类型 | 说明 | 是否必填 | | ---- | ---- | ---- | ---- | | url | string | TTS服务地址 | 是 | | text | string | 要转换的文本 | 是 | | role | string | 声音风格 | 否 | | headers | HeadersInit | 请求头 | 否 | | data | any | 额外参数 | 否 | | options | Options | 回调函数配置 | 否 |

abort()

中断当前播放和请求。

注意事项

1. 确保提供的图片资源路径正确。
2. 口型图片命名需要按照a-z的格式，且需与mouthTypeMappings中的type对应。
3. 若使用前端渲染口型（render: 'front'），需保证浏览器支持Web Audio API。

浏览器支持

• Chrome
• Firefox
• Safari
• Edge

许可证

MIT