SophonTalk Services

SophonTalk 的核心服务库，提供了音频特征提取、数据集加载等功能。

安装

npm install sophontalk-services
# 或者
pnpm add sophontalk-services

使用方法

特征提取 (FeatureExtractor)

FeatureExtractor 使用 Web Worker 在后台线程中处理音频数据，提取 Mel 频谱特征。

import { FeatureExtractor } from 'sophontalk-services';

// 1. 创建实例
const extractor = new FeatureExtractor();

// 2. 准备音频数据 (AudioBuffer)
// 例如从 AudioContext 解码得到
const audioContext = new AudioContext();
const response = await fetch('path/to/audio.wav');
const arrayBuffer = await response.arrayBuffer();
const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);

// 3. 提取特征
try {
  const result = await extractor.process(audioBuffer);
  console.log('特征数据:', result.features);
  console.log('维度信息:', result.dimensions);
} catch (error) {
  console.error('特征提取失败:', error);
}

// 4. 销毁实例 (不再使用时)
extractor.dispose();

数据集工具 (Dataset)

提供了加载数据集和一些辅助计算函数。

import { loadDataset, calculatePingPongState, getBorder } from 'sophontalk-services';

// 加载数据集
// 默认加载 /complete_dataset.json 和 /processed_images.zip
// 也可以指定 URL
try {
  const { dataset, zipBuffer } = await loadDataset({
    jsonUrl: '/path/to/dataset.json',
    zipUrl: '/path/to/images.zip'
  });
  console.log('数据集信息:', dataset.dataset_info);
} catch (error) {
  console.error('加载数据集失败:', error);
}

// 计算 Ping-Pong 循环播放的下一帧索引
const { nextIndex, nextDirection } = calculatePingPongState(currentIndex, numFrames, direction);

// 获取裁剪边框大小
const border = getBorder(96); // 支持 96 或 128

推理引擎 (InferenceEngine)

InferenceEngine 封装了 ONNX Runtime 推理的 Web Worker 逻辑。

import { InferenceEngine } from 'sophontalk-services';

// 1. 创建实例并设置回调
const engine = new InferenceEngine({
  onReady: () => console.log('模型加载完成'),
  onStart: (totalFrames) => console.log('开始推理，总帧数:', totalFrames),
  onFrame: (frame, index) => {
    // frame 是 ImageBitmap，使用后请尽快绘制并关闭以释放内存
    // ctx.drawImage(frame, 0, 0);
    // frame.close();
  },
  onDone: () => console.log('推理完成'),
  onError: (err) => console.error('推理错误:', err)
});

// 2. 初始化 (需要加载好的资源)
// dataset, zipBuffer 来自 loadDataset
// blendingMask 是 ImageBitmap
engine.init({
  modelPath: '/model.onnx',
  dataset: dataset,
  zipBuffer: zipBuffer,
  blendingMask: blendingMask,
  wasmPaths: '/' // 可选，指定 onnxruntime wasm 文件路径
});

// 3. 运行推理 (需要 FeatureExtractor 的输出)
engine.run({
  audioFeatures: features,
  audioDimensions: dimensions
});

// 4. 停止或销毁
engine.stop();
engine.terminate();

构建

本项目使用 Vite 进行构建。

# 安装依赖
pnpm install

# 构建库文件
pnpm build:lib

构建产物位于 dist-lib 目录下。

• dist-lib/sophontalk-services.js: ESM 格式入口
• dist-lib/sophontalk-services.cjs: CJS 格式入口
• dist-lib/types: 类型定义文件

依赖

本库依赖以下包，请确保在使用环境中安装：

• vue (虽然标记为外部依赖，但部分类型可能引用)
• onnxruntime-web
• jszip
• fft.js
• @alexanderolsen/libsamplerate-js