The Hugging Face repository root should contain manifest.json directly at the top level. Put it beside models/, engines/, and checksums/:

drbaph/Higgs-Audio-v3-Studio/
  manifest.json
  engines/
    audiocpp_engine.dll
    cublas64_13.dll
    cublasLt64_13.dll
    VCOMP140.DLL
    MSVCP140.dll
    VCRUNTIME140.dll
    VCRUNTIME140_1.dll
  engines_linux/
    libaudiocpp_engine.so
    libcudart.so.13
    libcublas.so.13
    libcublasLt.so.13
  models/
    higgs-q8_0/
      q8_0.gguf
      config/tokenizer/chat-template assets
    higgs-q6_k/
      q6_k.gguf
      config/tokenizer/chat-template assets
    higgs-q5_k/
      q5_k.gguf
      config/tokenizer/chat-template assets
    higgs-q4_k_m/
      q4_k_m.gguf
      config/tokenizer/chat-template assets
    higgs-bf16/
      bf16.gguf
      config/tokenizer/chat-template assets
  checksums/
    SHA256SUMS.txt

Upload your local Hugging Face staging folder with this same structure to the Hugging Face repo root so the runtime links resolve under /resolve/main/....

Primary target:

• Windows 11 x64
• Tauri 2 / WebView2 desktop runtime
• Visual Studio 2022 MSVC toolchain for source builds
• NVIDIA RTX GPU with CUDA 13 support for the prebuilt CUDA engine
• Current NVIDIA driver compatible with CUDA 13
• Recommended: RTX 30-series, 40-series, or 50-series GPU with enough VRAM for the selected quantization

Likely compatible:

• Windows 10 x64 with current WebView2 and NVIDIA drivers
• Other CUDA-capable NVIDIA GPUs if the DLL was built for their CUDA architecture

Not the focus of this desktop package:

• CPU-only generation
• macOS desktop packaging

Linux desktop packaging lives on the separate linux branch.

Tauri Web UI
  -> Rust command layer
    -> libloading + Windows DLL search path setup
      -> audiocpp_engine.dll C API
        -> ported Higgs Audio v3 C++ runtime
          -> ggml / CUDA backend
            -> Higgs Audio v3 TTS, voice clone, continuation

Important boundary:

• UI code lives in desktop/src.
• Reference microphone state, device selection, live metering, and recorder controls live in desktop/src/referenceRecorder.ts instead of the application bootstrap.
• Rust command glue lives in desktop/src-tauri/src.
• Native C ABI lives in app/desktop_api/audiocpp_api.h.
• Native DLL implementation lives in app/desktop_api/audiocpp_api.cpp.
• Higgs model code lives under src/models/higgs_tts.

Long-running inference runs on Rust blocking worker threads so the WebView stays responsive while the native engine is generating audio.

The three Windows packages run the same application, but they use two different storage modes:

The portable release is self-contained for all Studio-managed writable data. Keep the complete folder together and launch the EXE from a writable location. The portable.flag marker switches engine/model downloads, settings, saved speakers, reference caches, recordings, temporary audio, and WebView data into the portable directory:

Higgs Audio v3 Studio 0.3.0 Portable/
  Higgs Audio v3 Studio.exe
  portable.flag
  resources/
    engine/                       # empty until Download Engine DLLs is used
    higgs-assets/                 # bundled Higgs config/tokenizer assets
    api-console/                  # bundled browser API test console
  models/
    higgs-q8_0/                   # downloaded GGUF plus model assets
    whisper/                      # optional Whisper downloads
  data/
    speakers/                     # identities, images, audio, transcripts, caches
    temp/                         # prepared/recorded reference audio
    webview/                      # settings, API key, and WebView2 profile

The portable package includes Higgs support assets and the API test console, but does not bundle the native engine/runtime DLLs or multi-gigabyte GGUF weights. Download Engine DLLs fetches the engine package from Hugging Face into resources/engine/. Model and Whisper downloads are stored under models/. Moving the complete portable directory to another writable drive keeps its data with it.

NSIS and MSI are installed builds. Their signed application files and bundled read-only resources live in the Windows installation directory, while mutable downloads and user data are deliberately stored in writable per-user folders. This avoids Access is denied errors under Program Files. NSIS is the normal guided setup EXE; MSI uses Windows Installer and is useful for managed deployment, repair, or MSI-based uninstall tooling. Their runtime behavior is otherwise the same.

For development, place the engine DLL in desktop/src-tauri/resources/engine/. Engine discovery also checks bundled resources and compatible system-installed CUDA/MSVC runtime folders.

Speaker Gallery identities are optional. Voice Clone, Continue Speech, and Multi Speaker can use a saved identity, but users can still upload one-off reference audio without saving it. One-off voice-clone references and Speaker Gallery uploads are automatically prepared as WAV and capped to the first 30 seconds so long accidental uploads do not waste inference setup time. Continue Speech keeps the full source audio because that workflow may intentionally continue longer material.

The same reference slots can record from a microphone without leaving the app. Choose an input device, press record, and watch the live level waveform. Stopping the recording prepares a mono WAV and replaces that slot only after the file has been finalized successfully. Recording is available in Voice Clone, Continue Speech, Speaker Gallery, and every Multi Speaker voice card. Whisper transcription remains optional; the recorder does not perform speaker diarization.

When a speaker identity is created or edited, the app keeps its files in the user app data speaker store. Each speaker gets a folder named from the speaker name and internal ID, with:

speakers/
  Speaker_Name_persona_id/
    manifest.json
    reference.wav/mp3/flac
    display.png/jpg/webp
    transcript.txt
    notes.txt
    cache/
      speaker.hspkcache

Export opens a picker so you can choose exactly which speaker identities to include. The portable .zip contains manifest.json plus one speakers/<speaker-name>_<id>/ folder per selected identity. Import reads that ZIP, unpacks the audio/image assets back into the app speaker store, and restores the speaker identity list.

Speaker export/import includes identity metadata, reference audio, transcript, notes, display images, and the saved .hspkcache reference-code cache when it exists. The cache is created after the first saved-speaker inference and is used again by Voice Clone, Continue Speech, Multi Speaker, and saved-speaker API jobs. The file stores discrete codec IDs rather than model KV tensors. The official Q4_K_M, Q5_K, Q6_K, Q8_0, and BF16 builds made from the same source model with the default higgs_tts quantization policy can therefore share one speaker cache because that policy preserves the codec encoder tensors. Regenerate the cache for a different model/codec revision, fine-tune, or custom --policy all quant. Model-internal KV-prefix/activation caches are intentionally not serialized because those are model and quant specific.

The app can run a local API server from the API tab. The default base URL is:

http://127.0.0.1:7077/v1

Every /v1 route requires:

Authorization: Bearer <your-api-key>

Useful routes:

Finished-file routes accept response_format: "wav" or response_format: "mp3" and return audio/wav or audio/mpeg directly.

/v1/higgs/audio/stream emits NDJSON events such as queued, start, progress, audio, final, done, and error. Audio chunks are delivered as wavBase64 fields so simple clients can parse progress and audio from one response stream. The live chunks are WAV. The final event respects response_format: it returns wavBase64 for WAV or mp3Base64 for MP3.

For script playback, read the HTTP response line-by-line. When event is audio, base64-decode wavBase64 and feed those WAV bytes to your player or audio queue. When event is final, check encoding. Save wavBase64 when it is wav-base64, or mp3Base64 when it is mp3-base64.

Minimal Python stream reader:

import base64
import json
import requests

with requests.post(url, headers=headers, json=payload, stream=True, timeout=600) as r:
    r.raise_for_status()
    for line in r.iter_lines(decode_unicode=True):
        if not line:
            continue
        event = json.loads(line)
        if event["event"] == "audio":
            wav_chunk = base64.b64decode(event["wavBase64"])
            # Push wav_chunk to your audio playback queue here.
        elif event["event"] == "final":
            if event.get("encoding") == "mp3-base64":
                open("final.mp3", "wb").write(base64.b64decode(event["mp3Base64"]))
            else:
                open("final.wav", "wb").write(base64.b64decode(event["wavBase64"]))

The API tab includes examples for curl, Python, JavaScript, and PowerShell. The Test Console button opens a bundled, self-contained test harness in the system browser with the current API base URL; the app also copies the current API key to the clipboard for pasting into the console. The console can run health/status checks and exercise plain TTS, reference or saved-speaker cloning, continuation, WAV/MP3 finished responses, and NDJSON streaming. Its Command Centre can be popped out into a separate window with filters for info, warnings, errors, requests, and jobs. If the main studio window is minimized to the system tray, the popped-out Command Centre remains visible. Speaker Gallery changes are hot-synced into the running API, so saved speaker IDs do not require an API restart after create/edit/delete.

1. Download the portable release package from GitHub Releases.

2. Put it in a normal writable folder, for example:

   C:\AI\Higgs-Audio-v3-Studio\
   

3. Keep the resources/ folder beside Higgs Audio v3 Studio.exe.

4. Keep portable.flag beside the executable. This marker prevents the portable app from writing its runtime data into the Windows user profile.

5. Run Higgs Audio v3 Studio.exe.

6. The portable app creates and uses only these local writable folders:

   Higgs Audio v3 Studio 0.3.0 Portable/
     Higgs Audio v3 Studio.exe
     portable.flag
     resources/engine/       # populated by Download Engine DLLs
     models/                 # Higgs and Whisper downloads
     data/speakers/          # saved speaker identities and caches
     data/temp/              # prepared and recorded reference audio
     data/webview/           # settings, API key, and WebView2 state
   

7. If the engine package is missing, click Download Engine DLLs.

8. Use the Model panel to download or browse to a Higgs model.

9. Load the engine and model.

1. Download the NSIS *_x64-setup.exe for a normal guided installation, or the *_x64_en-US.msi for Windows Installer/managed deployment.
2. Install normally. Both packages install the same app and bundled resources.
3. Launch the app from the Start Menu.
4. Download or browse to the engine/model files from inside the app. Downloads, settings, speakers, and temporary files use writable per-user locations, not the protected application installation folder.

The model selector expects model folders, not loose files. A good downloaded folder layout is:

models/
  higgs-q8_0/
    q8_0.gguf
    chat_template.jinja
    config.json
    higgs_audio_v2_tokenizer_config.json
    tokenizer.json
    tokenizer_config.json
  higgs-q6_k/
    q6_k.gguf
  higgs-q5_k/
    q5_k.gguf
  higgs-q4_k_m/
    q4_k_m.gguf
  higgs-bf16/
    bf16.gguf

Higgs Audio v3 Q8_0 is the recommended model in the app. In-app Higgs model downloads now fetch the whole selected model folder: the .gguf file plus chat_template.jinja, config.json, higgs_audio_v2_tokenizer_config.json, tokenizer.json, and tokenizer_config.json. The progress bar shows the current file and per-file download progress, for example File 1/6: q8_0.gguf.

Recommended VRAM:

Use Browse... if a model is somewhere else. In-app model downloads use a user-writable folder by default:

C:\Users\<you>\audiocpp\models\

For Whisper auto-transcription, use the Whisper panel on the left:

1. Select a Whisper preset.
2. The recommended default is base.en-q8_0.
3. The smaller turbo option large-v3-turbo-q5_0 is also highlighted.
4. Click Download, or click Browse... and select an existing ggml-*.bin.

Known-good Windows build inputs:

From the repository root:

# Build the desktop DLL for a CUDA release preset.
.\scripts\build_windows.ps1 `
  -Preset windows-cuda-release `
  -Target audiocpp_engine `
  -Jobs 16

To force CUDA architectures:

.\scripts\build_windows.ps1 `
  -Preset windows-cuda-release `
  -Target audiocpp_engine `
  -CudaArchitectures "86;89;120" `
  -Jobs 16

Common architecture targets:

The DLL is written to:

build/windows-cuda-release/bin/audiocpp_engine.dll

For development, copy it to:

desktop/src-tauri/resources/engine/audiocpp_engine.dll

The native DLL is for development and the Hugging Face engines/ package. It is intentionally not embedded in NSIS, MSI, or portable application releases.

To produce MSI, NSIS, and a self-contained portable folder in one pass, use:

.\scripts\package_windows_release.ps1

The script adds portable.flag only to the portable folder. It optionally runs UPX on the copied portable executable when upx.exe is available; installer builds continue to use Tauri's normal MSI/NSIS compression and storage paths. Engine DLLs are intentionally excluded from every application package and are downloaded from the Hugging Face engines/ folder on demand.

From the repository root:

cd desktop
npm install
npm run build:vite
cd src-tauri
cargo check
cd ..
npm run build

Fast local app run:

cd desktop
npx tauri dev

Build only the frontend:

cd desktop
npm run build:vite

Build the Tauri app without generating installer bundles:

cd desktop
npx tauri build --no-bundle

Full Tauri build output is under:

desktop/src-tauri/target/release/
desktop/src-tauri/target/release/bundle/

Useful checks:

# Frontend TypeScript + Vite production build
cd desktop
npm run build:vite

# Rust command layer
cd src-tauri
cargo check
cd ..\..

# Native DLL target
.\scripts\build_windows.ps1 -Preset windows-cuda-release -Target audiocpp_engine

Expected behavior:

• The app opens to the main TTS workflow.
• Download Engine DLLs downloads audiocpp_engine.dll plus the required CUDA/MSVC runtime DLLs.
• Higgs model downloads show File n/6 and download the selected model folder assets plus GGUF weights.
• Load Engine changes the engine chip from unloaded to loaded.
• Load Model enables generation after a valid model folder is selected.
• Voice clone and multi-speaker workflows require reference audio. New uploaded clone/Speaker Gallery references are auto-cropped to 30 seconds.
• Microphone input selection, live recording waveform, stop, replace, and remove controls work in Voice Clone, Continue Speech, Speaker Gallery, and Multi Speaker voice cards.
• Reference trim controls preview a selected range, enforce the 30-second cloning limit, write a new WAV, and refresh the reference/cache state used by generation.
• Multi-speaker generation checks all speech lines before starting. If a line points to a missing speaker or a speaker without a reference voice, the app stops immediately and tells you which line to fix.
• Whisper auto-transcription requires a selected ggml-*.bin Whisper model.
• OGG/Opus and WebM/Opus references should load directly. Corrupt, empty, unsupported multi-stream, or unsupported multichannel Opus files return a specific decode error instead of an empty waveform.
• Generation progress shows Tokens current / maximum beside elapsed time when token telemetry is available.
• Test Console opens the bundled API harness in the default browser and pre-fills the current API root URL.

Port 1420 is already in use

Another Vite dev server is already running.

Check the port:

Get-NetTCPConnection -LocalPort 1420 -ErrorAction SilentlyContinue |
  Select-Object LocalAddress,LocalPort,State,OwningProcess

Stop the old process or run the app after that server exits.

Engine library not found

The app could not find audiocpp_engine.dll.

Fix one of these:

• Click Download Engine DLLs.
• Copy the DLL beside the release executable.
• In dev, copy it to desktop/src-tauri/resources/engine/audiocpp_engine.dll.

Load Model is disabled

Load the engine first, then select a valid model folder.

The app lists folders containing model weights such as model.gguf or model.safetensors. Loose files in the root models/ folder will not appear as full model entries.

CUDA DLL load errors

Version 0.2.31 added an engine dependency preflight. If Windows cannot load audiocpp_engine.dll, the app checks common loader dependencies first and shows a repair dialog listing missing DLLs such as nvcuda.dll, cublas64_13.dll, cublasLt64_13.dll, vcruntime140.dll, vcruntime140_1.dll, msvcp140.dll, or VCOMP140.DLL.

Make sure:

• NVIDIA driver is current.
• Click Download Engine DLLs, or make sure CUDA Toolkit 13.x runtime DLLs required by the engine are on PATH.
• Click Download Engine DLLs, or install Microsoft Visual C++ Redistributable 2015-2022 x64.
• The engine DLL was built for your GPU architecture.

VRAM spikes during generation

Short VRAM spikes can happen during inference. They usually come from temporary workspace buffers, KV cache allocation, CUDA/ggml scratch allocations, audio codec stages, or graph execution setup. A quantized model can still need extra transient memory while generating.

Seeing the card jump close to full VRAM for a moment does not always mean the model weights themselves need that much memory. CUDA/ggml can reserve large workspace and scratch regions sized for the current graph/session, and Windows or NVML may report that reserved memory as used. The Higgs generator decode graph allocates KV cache for the requested maximum token cap, so very high max_tokens values can reserve much more VRAM up front even when the text is short.

Version 0.2.31 and later releases Higgs runtime graphs and codec graphs after each request, releases them when streaming is cancelled or errors out, checks cancel inside the native decode loop, and sends per-stage native VRAM diagnostics to the Command Centre. Use those vram stage=... log lines to see whether a spike comes from reference encoding, generator decode graph allocation, streaming codec decode, final codec decode, or cleanup. The packaged CUDA engine now uses F16 decode KV cache by default to reduce cache VRAM pressure, with an F32 diagnostic fallback available for troubleshooting.

If you run out of memory:

• Use a smaller or lower-quantized model.
• Close other GPU-heavy apps.
• Reduce max tokens; the UI default is 1024.
• Disable longform chunking or use smaller chunks.
• Try a smaller reference clip.

Whisper auto-transcribe does nothing

Select a Whisper model in the left Whisper panel. The recommended default is base.en-q8_0. The model file should be a ggml-*.bin from whisper.cpp.

Downloads do not start

Check that the URL is a direct Hugging Face resolve/main/... URL, not a browser blob/main/... page.

Good:

https://huggingface.co/user/repo/resolve/main/path/file.bin

Not good for direct app download:

https://huggingface.co/user/repo/blob/main/path/file.bin

App links open inside the app instead of browser

Links should be routed through the Rust open_external_url command. If a new link is added, wire it through that command instead of using an in-app WebView navigation.