ElBruno.Whisper 0.2.0

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
• 📊 Progress reporting — track model downloads with real-time callbacks
• 🎯 English-optimized models — dedicated .en variants for best accuracy on English audio

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

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 in ASP.NET Core or other DI-enabled applications:

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

// Inject WhisperClient anywhere
public class TranscriptionService(WhisperClient whisper) { ... }

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

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

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

Made with ❤️ by Bruno Capuano (ElBruno)

• 📝 Blog: elbruno.com
• 📺 YouTube: youtube.com/elbruno
• 🔗 LinkedIn: linkedin.com/in/elbruno
• 𝕏 Twitter: twitter.com/elbruno
• 🎙️ Podcast: notienenombre.com