Skip to content

Home

Jump to bottom
Qourex edited this page Jun 28, 2026 · 2 revisions

Tip

Official Interactive Documentation: For the complete set of getting started guides, advanced options, and APIs, visit the official FasterWhisper.NET Documentation Site.

Developer Guide: Multi-Platform Support & .NET 10.0 Sample Suite

This page provides the architectural details, platform compatibility matrix, and setup instructions for FasterWhisper.NET. Following the recent upgrades, the SDK supports native cross-platform execution on desktop, server, and mobile devices (Android and iOS).

📋 Platform Support Matrix

FasterWhisper.NET utilizes a hybrid architecture consisting of a managed C# assembly (FasterWhisper.NET) wrapping the native C++ CTranslate2 inference engine and Silero VAD (via ONNX Runtime).

Operating System Architecture Package Math Backend RID (Runtime Identifier) Native Library Extension
Windows x64 CPU / GPU Intel MKL / CUDA + cuDNN win-x64 .dll
Linux x64 CPU / GPU OpenBLAS / CUDA + cuDNN linux-x64 .so
macOS x64 CPU Apple Accelerate osx-x64 .dylib
macOS arm64 CPU Apple Accelerate osx-arm64 .dylib
Android arm64-v8a CPU Eigen / Ruy android-arm64 .so
iOS arm64 CPU Apple Accelerate ios-arm64 .dylib (embedded framework)

Note: tvOS and WebAssembly (Browser) are not currently supported by the native interop layer.

📦 NuGet Packaging Architecture

The native binaries are bundled within the NuGet packages under target-specific folders. MSBuild automatically resolves the host platform at compile time and extracts the correct binaries into the output folder of your application.

1. FasterWhisper.NET (CPU Package)

Contains compiled native libraries for CPU execution, optimized with hardware-specific backends:

runtimes/
├── win-x64/native/qourex_fasterwhisper_native.dll
├── linux-x64/native/qourex_fasterwhisper_native.so, libctranslate2.so
├── osx-x64/native/qourex_fasterwhisper_native.dylib, libctranslate2.dylib
├── osx-arm64/native/qourex_fasterwhisper_native.dylib, libctranslate2.dylib
├── android-arm64/native/qourex_fasterwhisper_native.so, libctranslate2.so
└── ios-arm64/native/qourex_fasterwhisper_native.dylib, libctranslate2.dylib

2. FasterWhisper.NET.Gpu (GPU/CUDA Package)

Contains CUDA-enabled CTranslate2 builds for GPU acceleration on Windows and Linux:

runtimes/
├── win-x64/native/qourex_fasterwhisper_native.dll, ctranslate2.dll, cudnn*.dll, cublas*.dll
└── linux-x64/native/qourex_fasterwhisper_native.so, libctranslate2.so

🛠️ The .NET 10.0 Sample Suite

The samples/ directory contains 10 separate projects demonstrating integration patterns in various UI and server frameworks targeting .NET 10.0:

1. Console Applications (Cpu / Gpu)

  • Projects: Qourex.FasterWhisper.NET.Samples.Console.Cpu & .Gpu
  • Use Case: Lightweight command-line tools. Demonstrates asynchronous model downloading and basic WAV transcription.

2. ASP.NET Core Minimal APIs (Cpu / Gpu)

  • Projects: Qourex.FasterWhisper.NET.Samples.AspNetCore.Cpu & .Gpu
  • Architecture: Implements WhisperModel as a Singleton service. Demonstrates thread-safe request serialization using a semaphore lock to prevent concurrent reentrancy exceptions in the underlying native engine.
  • Execution: Exposes a POST /api/transcribe endpoint accepting multipart audio uploads.

3. Blazor Web Apps (Cpu / Gpu)

  • Projects: Qourex.FasterWhisper.NET.Samples.Blazor.Cpu & .Gpu
  • UI Features: Glassmorphic theme, Outfit typography, visual segment timeline mapping.
  • Rendering: Configured with @rendermode InteractiveServer to handle real-time downloading progress bars and event binding via SignalR.

4. Windows Forms (Cpu / Gpu)

  • Projects: Qourex.FasterWhisper.NET.Samples.WinForms.Cpu & .Gpu
  • Features: Built using the native .NET 10.0 WinForms Dark Mode (Application.SetColorMode(SystemColorMode.Dark)). Offloads CPU-intensive operations (model loading and transcription) to background threads using Task.Run and routes GUI updates using Progress<T> to maintain desktop responsiveness.

5. .NET MAUI (Cpu / Gpu)

  • Projects: Qourex.FasterWhisper.NET.Samples.Maui.Cpu & .Gpu
  • Targeting: CPU version targets Windows, iOS, Mac Catalyst, and Android. GPU version targets Windows only.
  • Mobile Workarounds:
    • Asset Extraction: Packaged raw files (like VAD models and audio assets) in mobile bundles cannot be accessed via standard file system paths. The samples extract raw resources to the local app cache path (FileSystem.CacheDirectory) at startup.
    • Unified File Pickers: Standardizes cross-platform WAV file picking filters for mobile and desktop environments.

📱 Mobile Platform Integration Details (Android & iOS)

Android Build Configuration

  1. Workloads: Ensure the .NET MAUI or Android workload is installed: 
    dotnet workload install android
  2. Permissions: Ensure your AndroidManifest.xml requests storage read permissions if you plan to pick external audio files: 
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

iOS Build Configuration

  1. Workloads: Ensure the ios workload is installed: 
    dotnet workload install ios
  2. Mathematical Backend: The iOS compilation pipeline utilizes the native Apple Accelerate framework. No external BLAS dependencies are packaged, ensuring a lightweight and battery-efficient footprint.
  3. Deployment: On physical iOS devices, code signing is required. Native .dylib files are automatically codesigned and embedded in the app bundle by the MSBuild pipeline.

Managing Large Model Assets on Mobile

Since model files (even the tiny model is ~75MB) are too large to package directly inside mobile app bundles, it is highly recommended to:

  1. Use the ModelDownloader API to download models dynamically to FileSystem.AppDataDirectory upon first launch.
  2. Display a progress bar during model initialization.

🔍 Troubleshooting

DllNotFoundException (Native Library Load Failures)

If you encounter a DllNotFoundException at runtime:

  • On Windows: Verify you have installed the Visual C++ Redistributable.
  • On GPU/CUDA: Ensure that the CUDA Toolkit (12.x) and cuDNN (9.x) libraries are present in your system environment PATH.
  • On Linux: Ensure libopenblas-dev or compatible BLAS libraries are installed on the host machine.
  • On Android/iOS: Ensure your project targets a supported 64-bit architecture (arm64-v8a / ios-arm64). 32-bit simulators or devices are not supported.

Clone this wiki locally