edit | blame | history | raw

CODEGRAPH

Project

  • Product: Wails v3 / Go desktop dictation app.
  • Current branch purpose: Round 6 Cantonese language version real-user test package based on v2.2.0-build20260702.0303.
  • Protected macOS behavior: existing macOS App Store / local DMG build lines are not changed by this branch.

Core Entrypoints

  • privatevoice.src/main.go: process startup, data migration, logger, single-instance guard.
  • privatevoice.src/app.go: Wails app wiring, settings window, tray, recorder, hotkey loop, ASR init, paste orchestration.
  • privatevoice.src/embed.go: embeds frontend assets and app/tray icons.

Language And Model Registry

  • privatevoice.src/internal/model/profile.go: model and language IDs, model profile shape, install status types.
  • privatevoice.src/internal/model/registry.go: language profile order, model profiles, language profiles, and normalization.
  • privatevoice.src/internal/modelselection/selection.go: resolves current language and model, including manual-model fallback.
  • Round 6 Cantonese path:
  • Language ID: yue-HK, displayed as 粤语.
  • Default model: sensevoice-yue-2025-09-09.
  • Backend: SenseVoice with LanguageParam="yue".
  • The Cantonese language profile intentionally has no upgrade models, so Qwen3-ASR and X-ASR are not shown as Cantonese-specific options.

Platform Modules

  • Audio: privatevoice.src/internal/audio/recorder.go
  • Uses github.com/gen2brain/malgo.
  • Cross-platform capture target: 16 kHz, 16-bit, mono.
  • Hotkey:
  • macOS: privatevoice.src/internal/hotkey/hotkey_darwin.go
  • Windows: privatevoice.src/internal/hotkey/hotkey_windows.go
  • Text input:
  • macOS: privatevoice.src/internal/input/paste_darwin.go
  • Windows: privatevoice.src/internal/input/paste_windows.go
  • ASR engine:
  • macOS: privatevoice.src/internal/engine/engine_darwin.go
  • Windows: privatevoice.src/internal/engine/engine_windows.go
  • Linux: privatevoice.src/internal/engine/engine_linux.go
  • SenseVoice profiles may set Profile.LanguageParam; Cantonese uses yue.
  • Overlay:
  • macOS: privatevoice.src/internal/overlay/overlay_darwin.go
  • Windows: privatevoice.src/internal/overlay/overlay_windows.go

Windows Preview Scope

  • Windows preview supports SenseVoice only.
  • Non-SenseVoice models remain visible in settings but are disabled through model.IsModelSupportedInCurrentBuild.
  • Windows unsupported reason: windows_preview_unsupported.
  • Windows overlay remains native Win32/GDI+, with a larger translucent spectrum-style capsule indicator for recording states.
  • Build script: privatevoice.src/scripts/build-windows-preview.sh.
  • Evidence verifier: privatevoice.src/scripts/verify-windows-qa-evidence.sh.
  • Runtime package includes:
  • PrivateVoice Dictation.exe
  • onnxruntime.dll
  • sherpa-onnx-c-api.dll
  • sherpa-onnx-cxx-api.dll
  • RUN-WINDOWS-QA.cmd
  • QA-WINDOWS-PREVIEW.ps1
  • README-WINDOWS-PREVIEW.txt

macOS Local Package Scope

  • Local DMG script: privatevoice.src/scripts/build-local-macos.sh.
  • Universal DMG script: privatevoice.src/scripts/build-local-macos-universal.sh.
  • Local macOS package set for this branch:
  • arm64 DMG for Apple Silicon.
  • x86_64 DMG for Intel Mac.
  • universal DMG for Intel + Apple Silicon.
  • Mainline macOS local packages keep LSMinimumSystemVersion=14.0 and the default Qwen3-capable dependency line.
  • Monterey-compatible packages remain a separate build line through privatevoice.src/scripts/build-local-macos-monterey.sh.

Standard Verification Commands

Run from privatevoice.src:

npm --prefix frontend run build
go test ./...
GOOS=windows GOARCH=amd64 CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc CXX=x86_64-w64-mingw32-g++ go test -exec=/usr/bin/true ./...
./scripts/build-windows-preview.sh
./scripts/build-local-macos.sh arm64
./scripts/build-local-macos.sh x86_64
./scripts/build-local-macos-universal.sh
./scripts/verify-windows-qa-evidence.sh /path/to/qa-evidence-YYYYMMDD-HHMMSS.zip

Known Gaps

  • Windows runtime QA must still be performed on Windows 10/11 hardware.
  • Run RUN-WINDOWS-QA.cmd from the extracted preview package to collect WebView2/audio preflight, startup, engine, recording, recognition, paste, and Notepad target text evidence.
  • After evidence is returned, run verify-windows-qa-evidence.sh and require WINDOWS_QA_EVIDENCE_PASS before claiming the goal complete.
  • The Windows preview zip is unsigned and not an installer.
  • SmartScreen / Defender prompts are expected for local testing.