unitts

🌏 This README is in English. 点击查看中文文档 (中文说明)

UNITTS

UNITTS is a unified Text-to-Speech (TTS) library written in TypeScript, providing a unified API interface to support multiple TTS service providers.

✨ Features

• 🔌 Unified Interface: Consistent API experience for all TTS providers
• 🧩 Adapter Pattern: Seamlessly connect to different TTS services via adapters
• 🌊 Streaming Support: Supports streaming and incremental TTS synthesis
• 🔧 Middleware Support: Onion-model middleware architecture, supports logging, timing, etc.
• 📦 TypeScript: Full type support and type safety
• 🚀 Extensibility: Easily add new TTS providers
• ⚡ High Performance: Asynchronous processing and streaming output

🚀 Quick Start

Installation

npm install unitts
# or
pnpm add unitts
# or
yarn add unitts

Basic Usage

import { TTSRelay } from 'unitts';
import { MinimaxProviderAdapter } from 'unitts/adapters';

// Create TTS relay instance
const ttsRelay = new TTSRelay();

// Register Minimax adapter
const minimaxAdapter = new MinimaxProviderAdapter('your-api-key', 'your-group-id');
ttsRelay.registerAdapter('minimax', minimaxAdapter);

// Text-to-speech
const result = await ttsRelay.synthesize('minimax', {
  text: 'Hello, welcome to UNITTS!',
  voice: 'female-tianmei',
  model: 'speech-02-hd',
  format: 'mp3',
});

console.log('Audio ID:', result.id);
console.log('Audio Data:', result.data); // Base64 encoded audio data

📚 Supported TTS Providers

Currently supports the following TTS providers:

Provider	Status	Description
Minimax	✅ Ready	Minimax TTS service
Tencent	✅ Ready	Tencent Cloud TTS service
Elevenlabs	✅ Ready	Elevenlabs TTS service
OpenAI	🚧 WIP	GPT series TTS service
Anthropic	🚧 WIP	Claude TTS service
Google Gemini	🚧 WIP	Gemini TTS service
Lovo.ai	🚧 WIP

🔧 Usage Examples

Streaming Synthesis

import { TTSRelay } from 'unitts';
import { MinimaxProviderAdapter } from 'unitts/adapters';

const ttsRelay = new TTSRelay();
const minimaxAdapter = new MinimaxProviderAdapter('your-api-key', 'your-group-id');
ttsRelay.registerAdapter('minimax', minimaxAdapter);

// Streaming synthesis
const stream = ttsRelay.synthesizeStream('minimax', {
  text: 'This is a streaming TTS synthesis example',
  voice: 'male-qn-qingse',
  model: 'speech-02-hd',
  format: 'mp3',
  stream: true,
});

for await (const chunk of stream) {
  console.log('Audio chunk:', chunk.id, chunk.data.length);
  if (chunk.final) {
    console.log('Synthesis complete!');
    break;
  }
}

Incremental Synthesis

// Incremental synthesis - suitable for real-time text streams
async function* textGenerator() {
  const sentences = ['Hello,', 'welcome to', 'UNITTS!'];
  for (const sentence of sentences) {
    yield sentence;
    await new Promise((resolve) => setTimeout(resolve, 1000));
  }
}

const stream = ttsRelay.synthesizeIncremental('minimax', textGenerator(), {
  voice: 'female-tianmei',
  model: 'speech-02-hd',
  format: 'mp3',
});

for await (const chunk of stream) {
  console.log('Incremental audio chunk:', chunk.id);
}

Middleware Support

import { LoggingMiddleware, TimingMiddleware } from 'unitts/middleware';

// Add logging middleware
ttsRelay.use(new LoggingMiddleware());

// Add timing middleware
ttsRelay.use(new TimingMiddleware());

// All TTS calls will go through middleware
const result = await ttsRelay.synthesize('minimax', {
  text: 'Test middleware feature',
  voice: 'female-tianmei',
});

Provider-specific Parameters

// Use Minimax-specific parameters
const result = await ttsRelay.synthesize('minimax', {
  text: 'Test provider-specific parameters',
  voice: 'female-tianmei',
  format: 'mp3',
  extra: {
    // Minimax-specific parameters
    speed: 1.2,
    vol: 0.8,
    pitch: 0,
    timber_weights: [{ voice_id: 'female-tianmei', weight: 1 }],
  },
});

📖 API Documentation

TTSRelay

The main TTS relay class, providing a unified API interface.

Methods

• registerAdapter(provider, adapter) - Register a TTS provider adapter
• use(middleware) - Add middleware
• synthesize(provider, params, options?) - Text-to-speech
• synthesizeStream(provider, params, options?) - Streaming text-to-speech
• synthesizeIncremental(provider, textStream, params, options?) - Incremental text-to-speech
• listProviders() - List registered providers

Unified Parameters (UnifiedTTSParams)

interface UnifiedTTSParams {
  text: string; // Text to synthesize
  model?: string; // Model name
  voice?: string; // Voice ID
  pitch?: number; // Pitch (-20 to 20)
  emotion?: string; // Emotion
  rate?: number; // Speed (0.5 to 2.0)
  volume?: number; // Volume (0 to 1)
  format?: string; // Audio format (mp3, wav, pcm, etc.)
  sampleRate?: number; // Sample rate
  stream?: boolean; // Whether to output as stream
  extra?: any; // Provider-specific parameters
}

Unified Response (UnifiedTTSAudio)

interface UnifiedTTSAudio {
  id: string; // Audio ID
  data: string; // Base64 encoded audio data
  model?: string; // Model used
  object: 'tts.audio'; // Object type
  metadata?: Record<string, any>; // Metadata
  final: boolean; // Is this the final chunk
  originalResponse?: any; // Original response
}

🔌 Add a New TTS Provider

UNITTS uses the adapter pattern, making it easy to add new TTS providers:

• Create Client: Create a new provider client under src/clients/
• Implement Adapter: Create an adapter under src/adapters/ and implement the IProviderAdapter interface
• Type Definitions: Add provider-specific types in src/types/unified.ts
• Register Export: Export the new adapter in the relevant index.ts file

For detailed development guide, see Development Docs.

🧪 Testing

# Run all tests
pnpm test

# Run tests and watch for file changes
pnpm test:watch

# Run a single test
pnpm test:run

🔨 Build

# Build the project
pnpm build

# Build in watch mode
pnpm build:watch

# Clean build files
pnpm clean

📝 Examples

See more usage examples in the examples directory:

• Basic Usage
• Streaming Synthesis
• Incremental Synthesis
• Multi-provider Usage
• Provider-specific Parameters

🤝 Contributing

Contributions are welcome! Please follow these steps:

• Fork this repository
• Create your feature branch (git checkout -b feature/AmazingFeature)
• Commit your changes (git commit -m 'Add some AmazingFeature')
• Push to the branch (git push origin feature/AmazingFeature)
• Open a Pull Request

📄 License

This project is open-sourced under the MIT License.

👨‍💻 Author

• boilcy - Project creator - [e-mail]

🙏 Acknowledgements

Thanks to all the developers who contributed to this project!

If you find this project useful, please give it a ⭐!