DotNetTtsWrapper 1.1.9

DotNet TTS Wrapper

A .NET NuGet package that provides a unified API for working with multiple cloud-based and local Text-to-Speech (TTS) services. Ported from js-tts-wrapper.

Repository: https://github.com/AACTools/dotnet-tts-wrapper
NuGet: dotnet add package DotNetTtsWrapper

Supported Engines

Word Timing Support

All engines return WordTimings on TtsSynthesisResult. Engines without native support get estimated timings automatically — no configuration needed.

Features

• Unified API: Single interface for 20+ TTS engines via TtsFactory.CreateClient()
• Streaming: IAsyncEnumerable<AudioChunkEventArgs> for real-time audio chunk streaming
• Word Timings: Real word boundary events from Azure/Google/ElevenLabs; automatic estimated fallback for all other engines via WordTimingEstimator
• SpeechMarkdown: Automatic conversion from SpeechMarkdown to SSML/plaintext per engine
• Credential Validation: CheckCredentialsAsync() on every engine, with synthesis fallback for engines with hardcoded voice lists
• Cross-platform: Windows, Linux, macOS (engine-dependent)
• Modern .NET: Built for .NET 8.0+ with RollForward=LatestMajor

Installation

dotnet add package DotNetTtsWrapper

Quick Start

using DotNetTtsWrapper.Models;
using DotNetTtsWrapper.Engines;

// Create a client (factory handles all engine types)
var creds = new OpenAICredentials { ApiKey = "sk-...", Model = "tts-1-hd" };
var client = TtsFactory.CreateClient("openai", creds);

// List voices
var voices = await client.GetVoicesAsync();
client.SetVoice("alloy");

// Synthesize to bytes (with word timings)
var result = await client.SynthToBytesAsync("Hello world!");
File.WriteAllBytes("output.mp3", result.AudioData);

// Word timings are always available (real or estimated)
foreach (var t in result.WordTimings)
    Console.WriteLine($"{t.Text}: {t.StartTime:F2}s - {t.EndTime:F2}s");

Engine Configuration

Azure

var creds = new AzureCredentials { SubscriptionKey = "key", Region = "eastus" };
var client = TtsFactory.CreateClient("azure", creds);

OpenAI (configurable model)

var creds = new OpenAICredentials { ApiKey = "sk-...", Model = "tts-1-hd" };
// Model defaults to "tts-1", set to "tts-1-hd" for higher quality
// OrganizationId optional: creds.OrganizationId = "org-...";

ElevenLabs (configurable model + voice settings)

var creds = new ElevenLabsCredentials {
    ApiKey = "...",
    ModelId = "eleven_multilingual_v2",  // or "eleven_monolingual_v1"
    Stability = 0.5f,
    SimilarityBoost = 0.75f
};

Google

var creds = new GoogleCredentials { ApiKey = "AIza..." };
// languageCode is derived from voice name automatically

AWS Polly (full Signature V4 authentication)

var creds = new PollyCredentials {
    AccessKeyId = "AKIA...",
    SecretAccessKey = "...",
    Region = "us-east-1"
};

SherpaOnnx (local offline TTS)

var creds = new SherpaOnnxCredentials {
    ModelFilePath = "/path/to/model.onnx",       // explicit paths
    TokensFilePath = "/path/to/tokens.txt",
    DataDirPath = "/path/to/espeak-ng-data",
    // OR use ModelPath directory convention:
    // ModelPath = "/path/to/model/directory",
    // ModelId = "vits-piper-en_US-amy-low"
};

Streaming

var streamResult = await client.SynthToStreamAsync("Long text to stream...");
await foreach (var chunk in streamResult.AudioStream)
{
    speaker.Write(chunk.AudioData, 0, chunk.AudioData.Length);
}
// streamResult.WordTimings available after completion

Word Boundary Events

// Real-time events during SpeakAsync
client.WordBoundary += (sender, e) => {
    Console.WriteLine($"Word: {e.Text}, Time: {e.StartTime:F2}s");
};
await client.SpeakAsync("Hello world!");

// Or access from synthesis result
var result = await client.SynthToBytesAsync("Hello world!");
var timings = result.WordTimings; // always populated (real or estimated)

Customizing Estimates

using DotNetTtsWrapper.Utils;

// Length-weighted estimate (default: 150 WPM)
var estimates = WordTimingEstimator.EstimateWordBoundaries(text, wordsPerMinute: 200);

// With known audio duration (scales proportionally)
var estimates = WordTimingEstimator.EstimateWordBoundaries(text, totalDurationSeconds: 5.2);

// Simple flat estimate (300ms per word)
var flat = WordTimingEstimator.EstimateWordBoundariesFlat(text);

SpeechMarkdown

The wrapper automatically converts SpeechMarkdown to engine-appropriate format:

// SpeechMarkdown is auto-detected and converted
await client.SpeakAsync("Hello (speed:x-fast)world(/speed)");

Each engine gets the correct platform mapping (Azure → Microsoft Azure, Google → Google Assistant, Polly → Amazon Alexa, etc.).

Requirements

• .NET 8.0+ runtime
• Windows required for SAPI engine; SherpaOnnx works on all platforms
• API keys/credentials for cloud engines

License

Ported from js-tts-wrapper with .NET-specific enhancements.

Related Projects

• VoiceGarden-SAPI — SAPI5 adapter using this library
• js-tts-wrapper — JavaScript/TypeScript version