@happyvertical/smrt-voice

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.6万

Voice profile management for AI-powered voice synthesis and cloning in the SMRT ecosystem

原始使用文档
文档目录8 节
  1. Installation
  2. Usage
  3. Runtime speech adapters
  4. API
  5. Models
  6. Types
  7. Key Computed Properties
  8. Dependencies

@happyvertical/smrt-voice

Voice profile management for AI-powered voice synthesis and cloning in the s-m-r-t ecosystem. Manages voice profiles, cloning samples, and TTS output with word-level timing for lip-sync.

Installation

pnpm add @happyvertical/smrt-voice

Usage

import { VoiceProfile, VoiceSample, VoiceOutput } from '@happyvertical/smrt-voice';

// Two mutually exclusive creation modes:

// 1. Voice design -- AI generates voice from a natural language prompt
const designed = new VoiceProfile({
  name: 'News Anchor',
  language: 'en-US',
  gender: 'male',
  designPrompt: 'Warm, authoritative male voice with clear enunciation',
  defaultSpeed: 1.0,   // 0.5 - 2.0
  defaultPitch: 0,     // -20 to 20 semitones
});
await designed.save();

// 2. Voice cloning -- replicate voice from audio sample(s)
const cloned = new VoiceProfile({
  name: 'Custom Voice',
  language: 'en-US',
  sampleAssetId: 'asset-123',
});
await cloned.save();

// Add training samples for cloning (minimum 3 seconds, quality != low)
const sample = new VoiceSample({
  voiceProfileId: cloned.id,
  assetId: 'asset-456',
  duration: 5.2,
  transcription: 'Hello, this is a test recording for voice cloning.',
  quality: 'high',
  sampleRate: 48000,
  format: 'wav',
  isPrimary: true,
});
await sample.save();

// TTS output with word-level timing for lip-sync
const output = new VoiceOutput({
  voiceProfileId: designed.id,
  sourceText: 'Welcome to the evening news.',
  audioAssetId: 'asset-789',
  duration: 2.8,
  wordTimings: [
    { word: 'Welcome', start: 0.0, end: 0.4 },
    { word: 'to', start: 0.4, end: 0.5 },
    { word: 'the', start: 0.5, end: 0.6 },
    { word: 'evening', start: 0.6, end: 1.0 },
    { word: 'news', start: 1.0, end: 1.3 },
  ],
});
// Look up which word is being spoken at a given timestamp
output.getWordAtTime(0.7); // { word: 'evening', start: 0.6, end: 1.0 }

Runtime speech adapters

@happyvertical/smrt-voice stores voice domain records. Runtime STT/TTS provider calls are owned by @happyvertical/speech.

import { getSpeech } from '@happyvertical/speech';
import { VoiceOutput, VoiceProfile } from '@happyvertical/smrt-voice';

const speech = await getSpeech({
  synthesizer: {
    type: 'qwen3-tts',
    baseUrl: 'http://qwen3-tts.qwen3-tts.svc.cluster.local',
  },
});

const profile = await VoiceProfile.find('voice-123');
const spoken = await speech.synthesize({
  text: 'Welcome to the evening news.',
  voice: profile.toSpeechVoice(),
});

const output = VoiceOutput.fromSynthesizedSpeech({
  sourceText: 'Welcome to the evening news.',
  voiceProfileId: profile.id,
  audioAssetId: 'asset-created-by-your-asset-store',
  speech: spoken,
});

API

Models

ExportDescription
VoiceProfileVoice identity with two modes: designPrompt (AI-generated) or sampleAssetId (cloned)
VoiceSampleAudio training data for voice cloning with quality rating
VoiceOutputGenerated TTS audio (extends Content) with word-level timing for lip-sync

Types

ExportDescription
VoiceProfileStatusLifecycle status: pending, processing, ready, failed
VoiceGenderGender classification: male, female, neutral
SampleQualityAudio quality rating: low, medium, high
WordTimingPer-word timing entry: { word, start, end } (seconds)
VoiceOutputMetadataAudio metadata: sampleRate, format, channels, bitDepth, provider, model
SpeechVoice, SynthesizedSpeech, TranscriptResultRuntime contracts re-exported from @happyvertical/speech
VoiceProfileOptionsProfile creation options
VoiceSampleOptionsSample creation options
VoiceOutputOptionsOutput creation options

Key Computed Properties

  • VoiceProfile.isCloned / isDesigned -- which creation mode is active
  • VoiceProfile.isReady -- status equals ready
  • VoiceProfile.toSpeechVoice() -- runtime voice contract for @happyvertical/speech
  • VoiceSample.meetsMinDuration -- duration >= 3 seconds
  • VoiceSample.isSuitableForCloning -- meets min duration AND quality != low
  • VoiceOutput.wordCount / wordsPerSecond -- computed from sourceText and duration
  • VoiceOutput.getWordAtTime(seconds) -- look up word being spoken at a timestamp
  • VoiceOutput.fromSynthesizedSpeech() -- normalize speech adapter output metadata/timings

Dependencies

  • @happyvertical/smrt-core -- ORM and code generation
  • @happyvertical/smrt-assets -- base asset management
  • @happyvertical/smrt-config -- configuration loading
  • @happyvertical/smrt-content -- content models (VoiceOutput extends Content)
  • @happyvertical/smrt-tenancy -- multi-tenant scoping
  • @happyvertical/speech -- runtime STT/TTS adapter contracts

版本与发布记录

@happyvertical/smrt-voice 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-voice 的常见问题

@happyvertical/smrt-voice 是什么?

Voice profile management for AI-powered voice synthesis and cloning in the SMRT ecosystem

如何安装 @happyvertical/smrt-voice?

在项目目录运行 npm install @happyvertical/smrt-voice,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-voice 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-voice 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-voice 可以商用吗?

@happyvertical/smrt-voice 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-voice 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-voice 在 2026/10/17 – 2026/11/15 这 30 天内被下载 15,918 次,日均约 531 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-voice 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 365 个版本,其中过去 12 个月发布了 365 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。