If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Const-me/Whisper shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Looks unmaintained — solo project with stale commits

• MPL-2.0 licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Const-me/Whisper repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Const-me/Whisper.

What it runs against: a local clone of Const-me/Whisper — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Const-me/Whisper | Confirms the artifact applies here, not a fork | | 2 | License is still MPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 675 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Const-me/Whisper. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Const-me/Whisper.git
#   cd Whisper
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Const-me/Whisper and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Const-me/Whisper(\\.git)?\\b" \\
  && ok "origin remote is Const-me/Whisper" \\
  || miss "origin remote is not Const-me/Whisper (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "ComLightLib/comLightServer.h" \\
  && ok "ComLightLib/comLightServer.h" \\
  || miss "missing critical file: ComLightLib/comLightServer.h"
test -f "ComputeShaders/flashAttention.hlsl" \\
  && ok "ComputeShaders/flashAttention.hlsl" \\
  || miss "missing critical file: ComputeShaders/flashAttention.hlsl"
test -f "Examples/WhisperDesktop/AppState.cpp" \\
  && ok "Examples/WhisperDesktop/AppState.cpp" \\
  || miss "missing critical file: Examples/WhisperDesktop/AppState.cpp"
test -f "ComputeShaders/ComputeShaders.cpp" \\
  && ok "ComputeShaders/ComputeShaders.cpp" \\
  || miss "missing critical file: ComputeShaders/ComputeShaders.cpp"
test -f "ComLightLib/server/Object.hpp" \\
  && ok "ComLightLib/server/Object.hpp" \\
  || miss "missing critical file: ComLightLib/server/Object.hpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 675 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~645d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Const-me/Whisper"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A high-performance Windows GPU-accelerated inference engine for OpenAI's Whisper speech-to-text model, using DirectCompute (compute shaders in Direct3D 11) instead of CUDA/PyTorch. It achieves 2.3× speedup over PyTorch with a 431 KB DLL footprint, supporting mixed F16/F32 precision and real-time audio capture with voice activity detection. Monolithic Visual Studio solution: ComLightLib/ provides lightweight COM wrapper abstractions; ComputeShaders/ contains 50+ HLSL compute shaders (convolution, attention, activation operators); Whisper.dll exposes a COM-style C++ API; separate GUI (WhisperDesktop.exe) and C# wrapper (WhisperNet on NuGet) layer on top.

Windows developers and end-users who need fast, lightweight speech-to-text inference on consumer GPUs without deep learning framework dependencies; primarily GPU-accelerated ML application builders targeting Windows desktops with NVIDIA/AMD/Intel discrete graphics.

Production-ready: single active maintainer (Const-me) with pre-built releases (WhisperDesktop.zip), C#/PowerShell bindings published on NuGet, and extensive compute shader implementations. Architecture is stable, but Windows-only constraint and single maintainer create continuity risk.

Moderate risk from single-maintainer dependency and Windows-only platform lock-in (no Linux/macOS support). DirectCompute requires D3D 11 feature level 10.0+, limiting older GPU support. No visible CI/CD pipeline in file list; dependency on Media Foundation (OS-level) and older Visual Studio project formats (.vcxproj) may cause build fragility across Windows versions.

No recent commit data visible in provided file list, but repo has stable releases (WhisperDesktop.zip in Releases) and published NuGet packages (WhisperNet). PowerShell scripting support was added in v1.10. Project appears in maintenance mode rather than active feature development.

Clone: git clone https://github.com/Const-me/Whisper.git. Open Whisper.sln in Visual Studio 2019+. Run build (requires Windows SDK, DirectX SDK). For binary: download WhisperDesktop.zip from Releases, unzip, run WhisperDesktop.exe (downloads ggml-medium.bin model on first launch).

Daily commands: Native: Build Whisper.sln in Visual Studio → Whisper.dll outputs to bin/. GUI: Run WhisperDesktop.exe (or compile from source). C#: Add NuGet package WhisperNet, instantiate via COM: var whisper = new Whisper(); whisper.LoadModel(modelPath);. PowerShell: Import module from WhisperPS/, use cmdlets like Invoke-WhisperTranscribe.

• ComLightLib/comLightServer.h — COM interop abstraction layer enabling C# callers to invoke GPU-accelerated whisper inference; all contributors must understand the COM-Light protocol for multi-language integration
• ComputeShaders/flashAttention.hlsl — Core attention mechanism shader; performance-critical kernel that directly impacts transcription accuracy and speed
• Examples/WhisperDesktop/AppState.cpp — Main application state machine orchestrating model loading, audio capture, and inference; entry point for understanding the complete transcription workflow
• ComputeShaders/ComputeShaders.cpp — Shader compilation and DirectCompute pipeline initialization; responsible for loading HLSL kernels and binding GPU resources
• ComLightLib/server/Object.hpp — Base COM object template implementing reference counting and interface marshalling; foundation for all server-side components exposed to .NET clients
• Examples/TranscribeCS/TranscribeCS.cs — C# interop layer demonstrating how to call GPU inference from managed code; reference implementation for binding to the COM-Light server
• ComputeShaders/mulMatDotMain.hlsl — Matrix multiplication kernel used throughout transformer layers; performance bottleneck for inference throughput

Add a new GPU kernel for a transformer layer

1. Create a new .hlsl file in ComputeShaders/ following HLSL compute shader conventions (use groupshared memory, optimize for 8×8 or 16×16 thread groups) (ComputeShaders/yourKernel.hlsl)
2. Include common utilities like groupReduce.hlsli or miscUtils.hlsli for shared reduction and helper functions (ComputeShaders/groupReduce.hlsli)
3. Register the shader in ComputeShaders.cpp by calling the shader compilation API and adding a dispatch function (ComputeShaders/ComputeShaders.cpp)
4. Expose a COM method in the server interface to call the new kernel from C# (ComLightLib/comLightServer.h)
5. Implement the COM method in your server object, binding GPU resources and calling the shader dispatch (ComLightLib/server/Object.hpp)

Add a new C# example or tool

1. Create a new .cs project in Examples/ with a reference to ComLightLib for COM interop (Examples/YourNewTool/YourNewTool.csproj)
2. Import ComLightClient.h via COM reference to access the GPU inference server (Examples/YourNewTool/Program.cs)
3. Follow the pattern in TranscribeCS.cs to load models, set parameters, and run inference (Examples/TranscribeCS/TranscribeCS.cs)
4. For microphone input, use NAudio or similar; see MicrophoneCS.cs for example (Examples/MicrophoneCS/MicrophoneCS.cs)

Optimize a shader for a new GPU generation or target FLOPs

1. Identify the kernel in ComputeShaders/ that needs optimization (e.g., flashAttention.hlsl, mulMatDotMain.hlsl) (ComputeShaders/flashAttention.hlsl)
2. Profile using GPU debuggers; reduce register pressure, increase thread occupancy, and use tiled/compatibility variants (e.g., flashAttentionCompat1.hlsl, flashAttentionCompat2.hlsl) (ComputeShaders/flashAttentionCompat1.hlsl)
3. Test with fp64Utils.hlsli and groupReduce64.hlsli for high-precision variants if needed (ComputeShaders/fp64Utils.hlsli)
4. Update shader selection logic in ComputeShaders.cpp to choose optimized variants at runtime based on GPU capabilities (ComputeShaders/ComputeShaders.cpp)

Add a new transcription UI dialog to WhisperDesktop

1. Create a new .h/.cpp pair in Examples/WhisperDesktop/ inheriting from standard WinForms dialog patterns (see LoadModelDlg.h, CaptureDlg.h for reference) (Examples/WhisperDesktop/LoadModelDlg.h)
2. Register the dialog in AppState.cpp as a new tab or screen state (Examples/WhisperDesktop/AppState.cpp)
3. Use TranscribeCallbacks.cs pattern to receive inference progress and results asynchronously (Examples/MicrophoneCS/TranscribeCallbacks.cs)
4. Call the COM server methods via comLightClient.h to perform transcription (ComLightLib/comLightClient.h)

• DirectCompute (Direct3D 11 Compute Shaders) — Vendor-agnostic GPGPU abstraction supporting NVIDIA, AMD, Intel on Windows; more portable than CUDA while maintaining high performance
• HLSL — Direct3D native shader language; allows fine-grained control over thread groups, shared memory, and GPU memory hierarchy for kernel optimization
• COM-Light (custom COM subset) — Lightweight interop between C++ GPU code and .NET managed clients (C#, VB.NET); avoids heavy WinRT/CLR marshalling overhead
• WinForms (C# UI) — Rapid prototyping of desktop UI; simpler than WPF for this inference-focused application
• C++ for core GPU logic — Direct access to DirectX 11 API and low-level memory management; necessary for GPU resource binding and high-performance kernel dispatch

• Windows-only platform (no Linux/macOS native support)
  • Why: Leverages DirectCompute as a stable, well-documented GP
  • Consequence: undefined

Windows SDK & DirectX: Requires Windows SDK (check DXGI format R16_FLOAT support for F16 precision—limited on older GPUs). Media Foundation: Audio codec support excludes Ogg Vorbis; some professional ASIO-only devices unsupported. Model format: Only accepts ggml-*.bin models (not PyTorch .pt); download correct model size or runtime will fail with silent HRESULT errors. Build toolchain: Uses older .vcxproj format (no CMake), may require Visual Studio 2019+. Threading: COM-Light uses free-threaded marshaller—do not mix apartment models without testing.

• DirectCompute (Compute Shaders in Direct3D 11) — Core GPU compute abstraction used instead of CUDA; vendor-agnostic but Windows-only, critical to understanding performance characteristics and GPU memory management
• Flash Attention — Optimized attention algorithm implemented in flashAttention.hlsl—major performance win for transformer inference, trades memory for speed via IO-awareness
• Mixed Precision (F16/F32) — Whisper uses half-precision floats where safe (activations) and full precision for gradients/accumulators; requires understanding DXGI_FORMAT_R16_FLOAT hardware support and numerical stability tradeoffs
• COM (Component Object Model) and COM-Light — API is exposed via COM-style interfaces (ObjectRoot.hpp, refcounting); ComLightLib is a lightweight COM shim enabling C# and PowerShell interop without full COM runtime overhead
• Mel-Spectrogram Feature Extraction — Implemented via convolution shaders (convolutionMain.hlsl)—Whisper's preprocessing layer that converts raw audio waveforms to frequency domain; critical to model accuracy
• Voice Activity Detection (VAD) — Real-time audio filtering based on Moattar & Homayoonpoor 2009 algorithm; reduces noise/silence for live transcription (Capture Screen feature)
• Windows Media Foundation — Abstracts audio/video codec handling and microphone I/O; enables format support (MP3, WAV, FLAC) and real-time capture but limits codec support (no Ogg Vorbis)

• ggerganov/whisper.cpp — Parent project—C++ port of OpenAI's Whisper without GPU acceleration, this repo is the DirectCompute-optimized Windows variant of it
• openai/whisper — Original PyTorch/Python reference implementation this entire project is descended from
• Const-me/Whisper.Net — Official C# bindings and NuGet package (WhisperNet) for consuming Whisper.dll from .NET applications
• NVIDIA/NVIDIA-NVDEC-samples — GPU video decoding alternative if adding hardware-accelerated video→audio extraction to bypass Media Foundation

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for HLSL compute shader compilation and validation

The ComputeShaders directory contains 50+ .hlsl files but there's no evidence of automated testing for shader compilation, correctness, or DirectCompute compatibility across different GPU architectures. This is critical for a GPGPU inference project since shader bugs directly impact model accuracy. A test suite would validate shader output against reference implementations and catch regressions early.

• [ ] Create ComputeShaders/Tests/ directory with C++ test harness using Google Test or Catch2
• [ ] Implement shader compilation tests for each major shader group (matMul variants, attention, normalization, convolution)
• [ ] Add numerical validation tests comparing shader output against CPU reference implementations for small input matrices
• [ ] Add tests for edge cases (zero-sized inputs, fp64 precision, different matrix dimensions)
• [ ] Integrate tests into a CI/CD pipeline to run on each commit

Document ComLightLib architecture and COM interface usage patterns

ComLightLib is a lightweight COM framework used throughout the project (client/, server/, interfaceMap.h, RefCounter.hpp, etc.), but ComLightLib/Readme.txt provides minimal guidance. New contributors cannot understand how to properly implement the COM interfaces (Object.hpp, ObjectRoot.hpp) or extend the object model. Specific documentation with code examples would dramatically reduce onboarding friction.

• [ ] Create ComLightLib/ARCHITECTURE.md explaining the threading model (freeThreadedMarshaller.cpp usage)
• [ ] Document the Object.hpp and ObjectRoot.hpp inheritance pattern with a working example
• [ ] Add a guide to interfaceMap.h showing how to declare and implement new interfaces
• [ ] Document the RefCounter.hpp memory management strategy and when to use CComPtr.hpp
• [ ] Add 2-3 minimal example implementations showing common COM patterns used in the codebase

Add GPU capability detection and shader variant selection logic

The file structure shows multiple variants of critical shaders (e.g., flashAttention.hlsl, flashAttentionCompat1/2/3.hlsl; norm.hlsl, normCompat.hlsl, normFixed.hlsl, normFixed64.hlsl). There's no visible automated mechanism to select the appropriate shader variant based on GPU compute capability, DirectX feature level, or precision requirements. This forces manual configuration and risks runtime failures on unsupported hardware.

• [ ] Create ComputeShaders/ShaderVariantSelector.h to query GPU capabilities (DirectX feature level, shader model version, fp64 support)
• [ ] Implement logic to map GPU capabilities to appropriate shader variants across all shader families
• [ ] Add validation to ensure selected shader variants are compatible with detected hardware
• [ ] Update ComputeShaders.cpp to auto-select variants instead of requiring manual specification
• [ ] Document shader variant compatibility matrix in ComputeShaders/Readme.txt

• Add unit tests for HLSL compute kernels in ComputeShaders/ (currently no visible test harness)—start with addRepeat.hlsl and verify output against CPU reference implementation
• Document the ComLightLib COM-Light abstraction layer: create examples in a new ComLightLib/examples/ folder showing how to wrap new C++ classes as COM objects (currently only Whisper.dll uses it)
• Extend WhisperPS PowerShell module with progress callbacks for long transcriptions—hook into underlying COM IProgress interface and expose as PowerShell event

The Whisper GPGPU inference project demonstrates moderate security posture. Key concerns include: (1) lack of input validation for GPU compute shader operations, (2) no apparent model file integrity verification for user downloads, (3) COM-based architecture without explicit security boundaries, and (4) potential buffer management issues in HLSL shaders. The codebase is a C++ port focused on performance rather than security. No critical vulnerabilities were identified, but several medium-risk issues require attention, particularly around model distribution and GPU memory safety. The project would benefit from formal security review of the GPU compute pipeline and COM inter-process communication mechanisms.

• Medium · Use of DirectCompute without Input Validation — ComputeShaders/ directory, particularly convolution and matrix multiplication shaders. The codebase relies heavily on DirectCompute (Direct3D 11 compute shaders) for GPU-accelerated inference. Compute shaders process untrusted input data (audio files) without explicit mention of input validation. Malformed or malicious audio files could potentially cause undefined behavior or resource exhaustion on the GPU. Fix: Implement strict input validation for audio file format, dimensions, and data ranges before processing in compute shaders. Add bounds checking and sanitization of input buffers.
• Medium · Model File Download Without Integrity Verification — WhisperDesktop application (model download functionality). The README indicates users download model files (e.g., 'ggml-medium.bin') from external sources. No mention of checksum verification, signature validation, or HTTPS enforcement is present. This creates a risk of man-in-the-middle attacks or supply chain compromise. Fix: Implement cryptographic hash verification (SHA-256 or better) for downloaded models. Use HTTPS with certificate pinning. Maintain a signed list of valid model checksums.
• Medium · COM-Based Architecture Without Explicit Security Boundaries — ComLightLib/server/ directory, particularly Object.hpp and ObjectRoot.hpp. The codebase uses ComLightLib, a COM-based architecture for inter-process communication. The server components (ObjectRoot.hpp, RefCounter.hpp) do not show explicit access control or permission checks. COM objects could be instantiated by untrusted processes. Fix: Implement explicit security descriptors for COM object creation. Use AppID registry entries with proper DCOM security configuration. Restrict instantiation to authorized callers only.
• Low · Potential Buffer Overflow in HLSL Shader Operations — ComputeShaders/*.hlsl files, particularly those with dynamic indexing. Multiple HLSL compute shaders (flashAttention.hlsl, mulMatTiled.hlsl, etc.) perform matrix operations with thread group dispatch. If group dimensions are not properly validated, out-of-bounds memory access could occur in GPU memory. Fix: Add validation of thread group dimensions and buffer sizes before dispatch. Use HLSL bounds checking features. Implement assertions for array access bounds.
• Low · Missing Exception Handling in C++ Components — ComputeShaders/ComputeShaders.cpp and other C++ implementation files. While Exception.hpp exists in ComLightLib, the visible .cpp files and project structure do not show comprehensive exception handling. Unhandled exceptions in audio processing or GPU operations could lead to crashes or information disclosure. Fix: Implement comprehensive try-catch blocks around GPU operations and external API calls. Log exceptions securely without exposing sensitive information.
• Low · Potential Information Disclosure via Unencrypted Microphone Capture — Examples/MicrophoneCS/ directory. The MicrophoneCS example captures live audio from microphone. No indication of encryption or secure handling of captured audio data in memory or at rest. Fix: Implement secure memory handling for audio buffers (use SecureString or equivalent). Encrypt captured audio if stored. Clear sensitive buffers after use.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.