Add auto model download from HuggingFace on first launch

Author: seyeong-han

PR_DESCRIPTION.md

@@ -0,0 +1,60 @@
+# Add Voxtral Realtime Windows WPF Application
+
+## Summary
+
+Adds a Windows WPF (.NET 8) desktop application for Voxtral Realtime — a real-time speech-to-text transcription tool powered by ExecuTorch. This is the Windows counterpart to the existing macOS SwiftUI application.
+
+## Key Features
+
+- **Real-time transcription** — Live speech-to-text using the Voxtral model running locally via ExecuTorch
+- **Dictation mode** — Speak and auto-paste transcribed text into any target application via clipboard
+- **Silence detection** — Peak-based audio level monitoring with configurable silence threshold and timeout for auto-stop
+- **Text processing pipeline** — Post-processing with configurable text replacements and snippet expansion
+- **Session history** — Persistent transcript storage with search and browsing
+- **Global hotkey** — System-wide keyboard shortcut to start/stop transcription
+- **MVVM architecture** — Clean separation using `CommunityToolkit.Mvvm` with `ObservableObject` view models
+
+## Architecture
+
+```
+VoxtralRealtime/
+├── Models/           # Data models (Session, Snippet, ReplacementEntry, Enums)
+├── Converters/       # WPF value converters
+├── Services/         # Core services
+│   ├── RunnerBridge.cs         # ExecuTorch model bridge
+│   ├── AudioCaptureService.cs  # NAudio-based mic capture
+│   ├── ClipboardPasteService.cs # Win32 clipboard + paste
+│   ├── GlobalHotkeyService.cs  # System-wide hotkey registration
+│   ├── TextPipeline.cs         # Post-processing pipeline
+│   ├── PersistenceService.cs   # JSON file storage
+│   └── AppLogger.cs            # File-based logging
+├── ViewModels/       # MVVM view models
+│   ├── TranscriptStoreViewModel.cs  # Central state management
+│   ├── DictationViewModel.cs        # Dictation flow + silence monitor
+│   ├── SettingsViewModel.cs         # App configuration
+│   ├── ReplacementStoreViewModel.cs # Text replacements
+│   └── SnippetStoreViewModel.cs     # Text snippets
+├── Views/            # WPF XAML views
+│   ├── MainWindow              # Shell with sidebar + detail layout
+│   ├── WelcomeView             # Home/landing page
+│   ├── TranscriptView          # Live transcript display
+│   ├── SidebarView             # Navigation sidebar
+│   ├── RecordingControlsBar    # Toolbar (transcribe/pause/done)
+│   ├── DictationWindow         # Floating dictation overlay
+│   ├── AudioLevelControl       # Real-time audio level meter
+│   ├── SettingsView            # Configuration UI
+│   └── *ManagementViews        # Replacement & snippet editors
+└── Resources/        # Styles and assets
+```
+
+## Also Included
+
+- `.gitignore` updated with .NET/C# build artifact rules (`bin/`, `obj/`, `publish/`, etc.)
+- `build.bat` for release builds
+- `upload_models.py` helper for model distribution
+- `README.md` with setup and build instructions
+
+## Test Plan
+
+- Built and tested manually on Windows 10/11 with .NET 8
+- Verified real-time transcription, dictation auto-paste, silence detection, and session persistence

voxtral_realtime/windows/README.md

@@ -6,9 +6,10 @@ This is the Windows equivalent of the [macOS Voxtral Realtime app](../macos/).
 
 ## Quick Start
 
-Download `VoxtralRealtime-Setup.exe` from the [Releases](https://github.com/meta-pytorch/executorch-examples/releases) page and run the installer. Everything is bundled -- the app, runner, model weights, and tokenizer. No additional downloads required.
-
-After install, launch from the Start Menu or desktop shortcut and click "Start Transcription".
+1. Download `VoxtralRealtime-Setup.exe` from the [Releases](https://github.com/meta-pytorch/executorch-examples/releases) page and run the installer
+2. Launch from the Start Menu or desktop shortcut
+3. Click **"Load Model"** — the app will automatically download the required model files (~5.2 GB) from HuggingFace on first launch
+4. Once loaded, click **"Start Transcription"**
 
 ### Requirements
 
@@ -23,6 +24,7 @@ After install, launch from the Start Menu or desktop shortcut and click "Start T
 - **Text Snippets** - Voice-triggered templates for common text blocks
 - **Dictation Mode** - Ctrl+Space global hotkey, floating overlay, auto-paste to any app, auto-stop on 2s silence
 - **Audio Level Visualization** - Real-time waveform display
+- **Auto Model Download** - Model weights are downloaded from HuggingFace on first launch with progress tracking
 
 ## Keyboard Shortcuts
 
@@ -41,24 +43,19 @@ For developers who want to build the app themselves.
 
 - [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
 - Pre-built `voxtral_realtime_runner.exe` (see [Building the Runner](#building-the-runner))
-- Model files from HuggingFace (see [Model Files](#model-files))
-
-### Model Files
-
-```powershell
-pip install huggingface_hub
-huggingface-cli download younghan-meta/Voxtral-Mini-4B-Realtime-2602-ExecuTorch-CUDA-Windows --local-dir voxtral_rt_exports
-huggingface-cli download mistralai/Voxtral-Mini-4B-Realtime-2602 tekken.json --local-dir voxtral_tokenizer
-```
 
 ### Building the Runner
 
+Build the `voxtral_realtime_runner.exe` from the [ExecuTorch](https://github.com/pytorch/executorch) repo:
+
 ```bash
 cd executorch
 cmake --preset voxtral-realtime-cuda
 cmake --build --preset voxtral-realtime-cuda
 ```
 
+The runner will be at `cmake-out/examples/models/voxtral_realtime/Release/voxtral_realtime_runner.exe`.
+
 ### Build and Run
 
 ```powershell
@@ -68,16 +65,26 @@ dotnet build --configuration Release
 dotnet run --project VoxtralRealtime --configuration Release
 ```
 
+Model files will be auto-downloaded on first launch to the `models/` directory next to the executable. To download them manually instead:
+
+```powershell
+pip install huggingface_hub
+huggingface-cli download younghan-meta/Voxtral-Mini-4B-Realtime-2602-ExecuTorch-CUDA-Windows --local-dir models
+huggingface-cli download mistralai/Voxtral-Mini-4B-Realtime-2602 tekken.json --local-dir models
+```
+
 ### Publish Standalone Executable
 
+Create a single self-contained exe (no .NET runtime required on target machine):
+
 ```powershell
 cd VoxtralRealtime
 dotnet publish VoxtralRealtime --configuration Release --runtime win-x64 --self-contained true /p:PublishSingleFile=true /p:IncludeNativeLibrariesForSelfExtract=true /p:DebugType=none -o publish
 ```
 
 ### Create Installer
 
-Builds a self-contained installer that bundles the app, runner, model weights, and tokenizer:
+Builds an installer that bundles the app and runner. Model weights are downloaded automatically on first launch.
 
 ```powershell
 # 1. Install Inno Setup (one-time)
@@ -87,19 +94,20 @@ winget install JRSoftware.InnoSetup
 cd VoxtralRealtime
 dotnet publish VoxtralRealtime --configuration Release --runtime win-x64 --self-contained true /p:PublishSingleFile=true /p:IncludeNativeLibrariesForSelfExtract=true /p:DebugType=none -o publish
 
-# 3. Build the installer
+# 3. Build the installer (set EXECUTORCH_ROOT to your ExecuTorch repo path)
 cd ..
-ISCC installer.iss
+$env:EXECUTORCH_ROOT = "C:\path\to\executorch"
+& "$env:LOCALAPPDATA\Programs\Inno Setup 6\ISCC.exe" installer.iss
 ```
 
 The output `installer-output\VoxtralRealtime-Setup.exe` includes:
 - App executable (self-contained, no .NET runtime needed)
 - `voxtral_realtime_runner.exe` + `aoti_cuda_shims.dll`
-- Model weights (`model.pte`, `preprocessor.pte`, `aoti_cuda_blob.ptd`)
-- Tokenizer (`tekken.json`)
 - Start Menu and optional desktop shortcuts
 - Clean uninstall via Windows Settings
 
+Model weights (`model.pte`, `preprocessor.pte`, `aoti_cuda_blob.ptd`, `tekken.json`) are **not bundled** — they are downloaded from HuggingFace on first launch, keeping the installer small (~49 MB).
+
 ## Architecture
 
 The app wraps the `voxtral_realtime_runner.exe` C++ binary via stdin/stdout pipes:

voxtral_realtime/windows/VoxtralRealtime/VoxtralRealtime/Models/Enums.cs

@@ -16,6 +16,7 @@ public enum SessionState
 public enum ModelState
 {
     Unloaded,
+    Downloading,
     Loading,
     Ready
 }

voxtral_realtime/windows/VoxtralRealtime/VoxtralRealtime/Services/ModelDownloadService.cs

@@ -0,0 +1,123 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// All rights reserved.
+// This source code is licensed under the BSD-style license found in the
+// LICENSE file in the root directory of this source tree.
+
+using System.IO;
+using System.Net.Http;
+
+namespace VoxtralRealtime.Services;
+
+public record DownloadProgress(
+    string FileName,
+    long BytesDownloaded,
+    long TotalBytes,
+    int FileIndex,
+    int TotalFiles);
+
+public class ModelDownloadService
+{
+    private static readonly HttpClient Http = new()
+    {
+        Timeout = TimeSpan.FromHours(2)
+    };
+
+    public static readonly string DefaultCacheDir = Path.Combine(
+        Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
+        "VoxtralRealtime", "models");
+
+    private static readonly (string RepoId, string FileName)[] ModelFiles =
+    {
+        ("younghan-meta/Voxtral-Mini-4B-Realtime-2602-ExecuTorch-CUDA-Windows", "model.pte"),
+        ("younghan-meta/Voxtral-Mini-4B-Realtime-2602-ExecuTorch-CUDA-Windows", "preprocessor.pte"),
+        ("younghan-meta/Voxtral-Mini-4B-Realtime-2602-ExecuTorch-CUDA-Windows", "aoti_cuda_blob.ptd"),
+        ("mistralai/Voxtral-Mini-4B-Realtime-2602", "tekken.json"),
+    };
+
+    public event Action<DownloadProgress>? ProgressChanged;
+
+    public List<string> GetMissingFiles(string cacheDir)
+    {
+        var missing = new List<string>();
+        foreach (var (_, fileName) in ModelFiles)
+        {
+            var path = Path.Combine(cacheDir, fileName);
+            if (!File.Exists(path))
+                missing.Add(fileName);
+        }
+        return missing;
+    }
+
+    public async Task DownloadAllAsync(string cacheDir, CancellationToken ct = default)
+    {
+        Directory.CreateDirectory(cacheDir);
+
+        int fileIndex = 0;
+        int totalFiles = ModelFiles.Length;
+
+        foreach (var (repoId, fileName) in ModelFiles)
+        {
+            fileIndex++;
+            var destPath = Path.Combine(cacheDir, fileName);
+
+            if (File.Exists(destPath))
+            {
+                ProgressChanged?.Invoke(new DownloadProgress(
+                    fileName, 1, 1, fileIndex, totalFiles));
+                continue;
+            }
+
+            var url = $"https://huggingface.co/{repoId}/resolve/main/{fileName}";
+            await DownloadFileAsync(url, destPath, fileName, fileIndex, totalFiles, ct);
+        }
+    }
+
+    private async Task DownloadFileAsync(
+        string url, string destPath, string fileName,
+        int fileIndex, int totalFiles, CancellationToken ct)
+    {
+        var tmpPath = destPath + ".tmp";
+
+        try
+        {
+            using var response = await Http.GetAsync(url, HttpCompletionOption.ResponseHeadersRead, ct);
+            response.EnsureSuccessStatusCode();
+
+            var totalBytes = response.Content.Headers.ContentLength ?? -1;
+
+            await using var stream = await response.Content.ReadAsStreamAsync(ct);
+            await using var fileStream = new FileStream(tmpPath, FileMode.Create, FileAccess.Write, FileShare.None, 81920);
+
+            var buffer = new byte[81920];
+            long bytesRead = 0;
+            int read;
+
+            while ((read = await stream.ReadAsync(buffer, ct)) > 0)
+            {
+                await fileStream.WriteAsync(buffer.AsMemory(0, read), ct);
+                bytesRead += read;
+
+                ProgressChanged?.Invoke(new DownloadProgress(
+                    fileName, bytesRead, totalBytes, fileIndex, totalFiles));
+            }
+
+            await fileStream.FlushAsync(ct);
+        }
+        catch
+        {
+            try { File.Delete(tmpPath); } catch { }
+            throw;
+        }
+
+        File.Move(tmpPath, destPath, overwrite: true);
+    }
+
+    public static string FormatBytes(long bytes)
+    {
+        if (bytes < 0) return "?";
+        if (bytes < 1024) return $"{bytes} B";
+        if (bytes < 1024 * 1024) return $"{bytes / 1024.0:F0} KB";
+        if (bytes < 1024L * 1024 * 1024) return $"{bytes / (1024.0 * 1024):F1} MB";
+        return $"{bytes / (1024.0 * 1024 * 1024):F2} GB";
+    }
+}

voxtral_realtime/windows/VoxtralRealtime/VoxtralRealtime/ViewModels/SettingsViewModel.cs

@@ -12,24 +12,22 @@ namespace VoxtralRealtime.ViewModels;
 
 public partial class SettingsViewModel : ObservableObject
 {
-    private static readonly string DefaultRunnerPath = Path.Combine(
-        @"C:\Users\younghan\project\executorch",
-        @"cmake-out\examples\models\voxtral_realtime\Release\voxtral_realtime_runner.exe");
+    private static readonly string AppDir = AppDomain.CurrentDomain.BaseDirectory;
 
-    private static readonly string DefaultModelPath = Path.Combine(
-        @"C:\Users\younghan\project\executorch",
-        @"voxtral_rt_exports_wsl\model.pte");
-
-    private static readonly string DefaultPreprocessorPath = Path.Combine(
-        @"C:\Users\younghan\project\executorch",
-        @"voxtral_rt_exports_wsl\preprocessor.pte");
-
-    private static readonly string DefaultDataPath = Path.Combine(
-        @"C:\Users\younghan\project\executorch",
-        @"voxtral_rt_exports_wsl\aoti_cuda_blob.ptd");
+    // Models directory: always next to the exe (install dir or dev dir).
+    // Models are either bundled by the installer or auto-downloaded on first launch.
+    public static readonly string ModelsDir = Path.Combine(AppDir, "models");
 
+    private static readonly string DefaultRunnerPath =
+        Path.Combine(AppDir, "runner", "voxtral_realtime_runner.exe");
+    private static readonly string DefaultModelPath =
+        Path.Combine(ModelsDir, "model.pte");
+    private static readonly string DefaultPreprocessorPath =
+        Path.Combine(ModelsDir, "preprocessor.pte");
+    private static readonly string DefaultDataPath =
+        Path.Combine(ModelsDir, "aoti_cuda_blob.ptd");
     private static readonly string DefaultTokenizerPath =
-        @"C:\Users\younghan\models\Voxtral-Mini-4B-Realtime-2602\tekken.json";
+        Path.Combine(ModelsDir, "tekken.json");
 
     [ObservableProperty] private string _runnerPath = DefaultRunnerPath;
     [ObservableProperty] private string _modelPath = DefaultModelPath;
@@ -71,15 +69,23 @@ private void Load()
         var data = PersistenceService.Load<SettingsData>(PersistenceService.SettingsPath);
         if (data == null) return;
 
-        RunnerPath = data.RunnerPath ?? DefaultRunnerPath;
-        ModelPath = data.ModelPath ?? DefaultModelPath;
-        TokenizerPath = data.TokenizerPath ?? DefaultTokenizerPath;
-        PreprocessorPath = data.PreprocessorPath ?? DefaultPreprocessorPath;
-        DataPath = data.DataPath ?? DefaultDataPath;
+        // Only restore saved paths if the files actually exist;
+        // otherwise fall back to defaults (triggers auto-download).
+        RunnerPath = FileOrDefault(data.RunnerPath, DefaultRunnerPath);
+        ModelPath = FileOrDefault(data.ModelPath, DefaultModelPath);
+        TokenizerPath = FileOrDefault(data.TokenizerPath, DefaultTokenizerPath);
+        PreprocessorPath = FileOrDefault(data.PreprocessorPath, DefaultPreprocessorPath);
+        DataPath = FileOrDefault(data.DataPath, DefaultDataPath);
         SilenceThreshold = data.SilenceThreshold;
         SilenceTimeoutSeconds = data.SilenceTimeoutSeconds;
     }
 
+    private static string FileOrDefault(string? saved, string fallback)
+    {
+        if (!string.IsNullOrEmpty(saved) && File.Exists(saved)) return saved;
+        return fallback;
+    }
+
     private class SettingsData
     {
         [JsonPropertyName("runnerPath")] public string? RunnerPath { get; set; }