ElBruno.Whisper

ElBruno.Whisper

Run local Whisper speech-to-text in .NET 🎤

Transcribe audio to text in .NET using OpenAI's Whisper model. Powered by ONNX Runtime with automatic model download from HuggingFace.

Features

• 📦 Automatic model download — models are fetched from HuggingFace on first use
• 🔊 Multiple model sizes — tiny → base → small → medium → large (pick your speed/accuracy tradeoff)
• 🚀 Zero friction — works out of the box with sensible defaults (tiny.en)
• 🌍 Multilingual support — transcribe 99+ languages with multilingual models
• 💉 DI-friendly — register with AddWhisper() in ASP.NET Core
• 🧵 Concurrent transcription — share one client with configurable queueing and pooled inference sessions
• 📊 Progress reporting — track model downloads with real-time callbacks
• 🎯 English-optimized models — dedicated .en variants for best accuracy on English audio
• ⏱️ Timestamp-aware results — opt into segment and word timings for subtitle and caption workflows

Installation

dotnet add package ElBruno.Whisper

Quick Start

using ElBruno.Whisper;

// Create client (downloads tiny.en model on first run)
using var client = await WhisperClient.CreateAsync();

var result = await client.TranscribeAsync("audio.wav");
Console.WriteLine(result.Text);

First Run

The first time you create a WhisperClient, the model is downloaded from HuggingFace to your local cache directory (~75 MB - 3 GB depending on model size). This typically takes 10-60 seconds depending on your internet connection and chosen model.

Track download progress:

using var client = await WhisperClient.CreateAsync(
    progress: new Progress<ElBruno.HuggingFace.DownloadProgress>(p =>
    {
        if (p.Stage == ElBruno.HuggingFace.DownloadStage.Downloading)
            Console.WriteLine($"{p.CurrentFile}: {p.PercentComplete:F0}%");
        else
            Console.WriteLine($"{p.Stage}: {p.Message}");
    })
);

Subsequent runs load instantly from cache (%LOCALAPPDATA%/ElBruno/Whisper/models).

Model Selection

Whisper offers various model sizes. English-optimized models (.en suffix) are smaller and faster for English audio:

using var client = await WhisperClient.CreateAsync(new WhisperOptions
{
    Model = KnownWhisperModels.WhisperSmallEn
});

var result = await client.TranscribeAsync("english-audio.wav");
Console.WriteLine(result.Text);

Available Models

Size	English	Multilingual	Parameters	Approx Size	Speed
tiny	tiny.en	tiny	39M	75 MB	⚡⚡⚡⚡⚡
base	base.en	base	74M	140 MB	⚡⚡⚡⚡
small	small.en	small	244M	460 MB	⚡⚡⚡
medium	medium.en	medium	769M	1.5 GB	⚡⚡
large	—	large	1550M	3.0 GB	⚡

Use English-optimized (.en) models for:

• English audio only (slightly smaller, faster, better accuracy on English)

Use Multilingual models for:

• Non-English audio
• Mixed-language content
• Language auto-detection

Progress Tracking

Monitor both file downloads and transcription progress:

var downloadProgress = new Progress<ElBruno.HuggingFace.DownloadProgress>(p =>
{
    if (p.Stage == ElBruno.HuggingFace.DownloadStage.Downloading)
        Console.Write($"\r⬇️ {p.PercentComplete:F0}%");
    else
        Console.WriteLine($"\n✓ {p.Message}");
});

using var client = await WhisperClient.CreateAsync(progress: downloadProgress);

var result = await client.TranscribeAsync("audio.wav");
Console.WriteLine($"✓ Transcribed: {result.Text}");

Dependency Injection

Register Whisper options in ASP.NET Core or other DI-enabled applications:

builder.Services.AddWhisper(options =>
{
    options.Model = KnownWhisperModels.WhisperBaseEn;
    options.Concurrency.MaximumConcurrentRequests = 2;
});

AddWhisper() registers WhisperOptions. Create and share a WhisperClient yourself where you control startup and disposal.

Thread Safety and Concurrency

WhisperClient can now be shared across concurrent callers. By default it still processes one transcription at a time. Raise the concurrency limit to allow parallel work and reuse pooled ONNX sessions:

using var client = await WhisperClient.CreateAsync(new WhisperOptions
{
    Model = KnownWhisperModels.WhisperTinyEn,
    Concurrency = new WhisperConcurrencyOptions
    {
        MaximumConcurrentRequests = 2,
        QueueTimeout = TimeSpan.FromSeconds(15),
        EnableSessionPooling = true
    }
});

var results = await Task.WhenAll(
    client.TranscribeAsync("audio-1.wav"),
    client.TranscribeAsync("audio-2.wav"));

If all inference slots are busy longer than QueueTimeout, TranscribeAsync throws TimeoutException. Cancelling the request also aborts queue waiting and the next safe decode checkpoint.

Transcription Result

The TranscriptionResult includes:

var result = await client.TranscribeAsync("audio.wav");

Console.WriteLine(result.Text);                    // Transcribed text
Console.WriteLine(result.DetectedLanguage);       // Detected language (for multilingual models)
Console.WriteLine(result.Duration);               // Audio duration

Enable timestamps to access both segment-level and word-level timing metadata:

using var client = await WhisperClient.CreateAsync(new WhisperOptions
{
    EnableTimestamps = true
});

var result = await client.TranscribeAsync("audio.wav");

foreach (var segment in result.Segments ?? [])
{
    Console.WriteLine($"[{segment.Start:mm\\:ss\\.ff} - {segment.End:mm\\:ss\\.ff}] {segment.Text}");

    foreach (var word in segment.Words)
    {
        Console.WriteLine($"  {word.Start:mm\\:ss\\.ff} - {word.End:mm\\:ss\\.ff}: {word.Text}");
    }
}

Word timings are derived from the timestamped transcript spans produced by Whisper. If a model returns text without explicit spans, the library falls back to a single full-duration segment and derives word timings within that range.

Troubleshooting

Model download fails?

• Check your internet connection
• For private HuggingFace models, set the HF_TOKEN environment variable

Out of memory?

• Use a smaller model (tiny or base instead of medium/large)
• Transcribe shorter audio files in chunks

For detailed troubleshooting, see docs.

Samples

Sample	Description
HelloWhisper	Minimal console transcription
BlazorWhisper	Blazor app with audio recording and real-time transcription

Documentation

• Getting Started — installation, first steps, configuration
• API Reference — full API documentation
• Architecture — design decisions and internal structure
• Testing Guide — running tests, test organization, CI/CD pipeline
• Test Audio Files — audio resources for testing and transcription validation
• Image Prompts — prompts for generating blog and social media images
• Publishing — NuGet package publishing with OIDC

Building from Source

git clone https://github.com/elbruno/ElBruno.Whisper
cd ElBruno.Whisper
dotnet build ElBruno.Whisper.slnx
dotnet test ElBruno.Whisper.slnx --filter "Category!=Integration"

Testing

The repository includes comprehensive unit and integration tests:

Quick test run (unit tests, no model download):

dotnet test ElBruno.Whisper.slnx --filter "Category!=Integration"

Full test run (includes integration with real models):

dotnet test ElBruno.Whisper.slnx

Test audio files are provided in testdata/audio/ for validation and transcription testing. For details, see the Testing Guide.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Related Projects

• ElBruno.LocalLLMs — Run local LLMs in .NET
• ElBruno.HuggingFace — HuggingFace model utilities for .NET

🙏 Acknowledgments

• ONNX Runtime — inference engine
• OpenAI Whisper — speech-to-text model
• Hugging Face — model hosting and community
• ONNX Community — ONNX model conversions

👋 About the Author

Hi! I'm ElBruno 🧡, a passionate developer and content creator exploring AI, .NET, and modern development practices.

Made with ❤️ by ElBruno

If you like this project, consider following my work across platforms:

• 📻 Podcast: No Tienen Nombre — Spanish-language episodes on AI, development, and tech culture
• 💻 Blog: ElBruno.com — Deep dives on embeddings, RAG, .NET, and local AI
• 📺 YouTube: youtube.com/elbruno — Demos, tutorials, and live coding
• 🔗 LinkedIn: @elbruno — Professional updates and insights
• 𝕏 Twitter: @elbruno — Quick tips, releases, and tech news