Qevoxyl — Documentation Bundle (v1.3.0)

Overview

Qevoxyl is a desktop speech-to-text utility with a clean CustomTkinter UI. It records audio (or loads existing WAV/MP3), runs offline transcription using OpenAI Whisper, and can read the transcript aloud via optional Online TTS (cloud) or offline/system TTS when you keep Online TTS off.

Key Features

v1.3.0 Highlights

Building

Prerequisites

• Python 3.13 (x64)
• Microsoft VC++ 2015–2022 Redistributable (x64)
• Optional: git

Verify Python:

py -3.13 -V

Environment Setup

# Create venv (optional but recommended)
py -3.13 -m venv .venv
. .venv\Scripts\Activate

# Upgrade pip & install deps
python -m pip install --upgrade pip
python -m pip install -r requirements.txt   # or install the list below

# Ensure ffmpeg shim is available
python -m pip install imageio-ffmpeg

Typical packages:

customtkinter pillow numpy sounddevice soundfile pygame
edge_tts aiohttp pyttsx3 comtypes
torch openai-whisper imageio-ffmpeg pyinstaller

Build (PyInstaller, one-folder)

We ship one-folder (not one-file) to reduce AV heuristics and improve startup time.

# Clean previous artifacts (optional)
Remove-Item -Recurse -Force .\build, .\dist -ErrorAction SilentlyContinue

# Build using the spec
python -m PyInstaller --clean .\app.spec

Result:

dist\Qevoxyl\Qevoxyl.exe        <-- run this

What the Spec Does (high level)

• Collects resource folders: icon, images, models, recordings, theme, utils, voice
• Bundles Whisper assets/* (e.g., mel_filters.npz)
• Optionally includes models\ffmpeg-bin\ffmpeg.exe
• Adds version info + manifest
• UPX disabled for Torch DLL reliability

Local Run

# From project root
.\dist\Qevoxyl\Qevoxyl.exe
# or auto-transcribe a file
.\dist\Qevoxyl\Qevoxyl.exe "C:\path\audio.wav"

Logs & Settings (dev)

• Logs: %LOCALAPPDATA%\Qevoxyl\logs\app.log
• Settings: %LOCALAPPDATA%\Qevoxyl\settings.json
• Runtime data: %LOCALAPPDATA%\Qevoxyl\{models, recordings, voice}

Troubleshooting (build/runtime)

PyInstaller

• “pyinstaller not recognized” → python -m PyInstaller app.spec
• Icon missing → ensure icon/qevoxyl_icon.ico exists or update icon= in spec
• Don’t pass --onefile when using a .spec file

Whisper/Torch

• mel_filters.npz not found → ensure collect_data_files('whisper', includes=['assets/*']) in spec
• Torch DLL issues → keep UPX disabled; install the VC++ Redistributable

Audio

• No input devices → check Windows Privacy (Microphone for desktop apps); close apps holding the mic
• Empty recording → verify correct device/sample rate

FFmpeg

• Ensure imageio-ffmpeg installed
• Runtime fallback copies FFmpeg into models\ffmpeg-bin and prepends PATH

Performance Tips

• CPU-only → use tiny/base for speed; small balanced; medium/large are heavy
• GPU present → Whisper uses fp16; CPU path uses fp32
• For lower latency, transcribe shorter segments
• Future: consider faster-whisper (CTranslate2) for faster CPU inference/smaller footprint

Packaging

PyInstaller Output

• Mode: one-folder
• Output: dist\Qevoxyl\Qevoxyl.exe

Why one-folder?

• Lower AV heuristics than one-file SFX
• Faster cold start
• Easier to inspect shipped files

Inno Setup Installer (per-user, no UAC)

• Script: Qevoxyl.iss
• Output: output\Qevoxyl-Setup-<version>.exe

Key traits

• Installs to %LOCALAPPDATA%\Qevoxyl
• Optional tasks: Desktop shortcut; Startup shortcut (preferred over HKCU\...\Run); Explorer context menu for .wav/.mp3

Context Menu (per-user)

HKCU\Software\Classes\SystemFileAssociations\.{wav|mp3}\shell\Qevoxyl.Transcribe
Command: "{app}\Qevoxyl.exe" "%1"

Startup (per-user)

{userstartup}\Qevoxyl.lnk  ->  "{app}\Qevoxyl.exe"

Code Signing (optional but recommended)

SignTool=signtool sign /a /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /d "Qevoxyl 1.3.0" $f
SignedUninstaller=yes

• Replace with your cert settings if you have one.
• Signs both the installer and uninstaller.
• To also sign the app EXE, run signtool on dist\Qevoxyl\Qevoxyl.exe before building the installer.

Publishing & Checksums

# Installer
certutil -hashfile .\output\Qevoxyl-Setup-1.3.0.exe SHA256

# App binary
certutil -hashfile .\dist\Qevoxyl\Qevoxyl.exe SHA256

Web Assets (optional, offline fonts)

• Use offline Poppins (assets/fonts/poppins.css + WOFF2 variable files) if hosting docs
• Avoid external font CDNs for zero external requests
• Publish the installer hash on your site (Download section)

AV-Friendlier Packaging Defaults

• One-folder (not one-file)
• UPX disabled
• Startup via Startup shortcut, not Run key
• Clear version info + manifest in EXE (set in app.spec)
• Keep installer tasks opt-in
• Keep product/URL metadata consistent (EXE, installer, website)

Security & Privacy

Privacy (summary)

• Offline by default — transcription runs locally; audio/text aren’t uploaded.
• Local storage — %LOCALAPPDATA%\Qevoxyl\{models, recordings, voice, logs, settings.json}.
• Optional network
  • First-time model download
  • Online TTS only if enabled (off by default). When enabled, text you choose to speak may be sent to a TTS service to synthesize audio.

See privacy.html for the full user-facing policy.

Runtime Security Choices

• Per-user install to %LOCALAPPDATA% (no admin/UAC)
• Startup via Startup shortcut (not HKCU\...\Run)
• No hidden background network activity
• Logs are local; you control what you share if requesting support

Code Signing (recommended)

• Sign dist\Qevoxyl\Qevoxyl.exe and the installer for better reputation
• Use EV Code Signing for best SmartScreen trust (OV is an ok start)
• Timestamp signatures (/tr + /td)
• Keep Publisher common name consistent across releases and your website

Reducing AV False Positives

• Ship one-folder builds (avoid one-file SFX stubs)
• Disable UPX (Torch DLLs often trigger when packed)
• Avoid registry Run entries; use Startup shortcut
• Provide version info + manifest (already in app.spec)
• Publish SHA-256 checksums
• If flagged:
  • Rebuild clean; verify hashes
  • Submit false-positive to Microsoft
  • Keep cert/publisher stable over time for reputation accrual

Verifying Integrity

# Verify installer
certutil -hashfile .\output\Qevoxyl-Setup-1.3.0.exe SHA256

# Verify app exe
certutil -hashfile .\dist\Qevoxyl\Qevoxyl.exe SHA256

If signed: Right-click → Properties → Digital Signatures → verify signature and timestamp.

Support & Reporting

• Site: https://qevoxyl.com.ng
• Logs for bug reports: %LOCALAPPDATA%\Qevoxyl\logs\app.log

Changelog

1.3.0

• Reset/New Session (Ctrl+N) — cancels active work, clears UI, new target filename, resets timer.
• Session guard — prevents stale background threads from updating the UI after reset.
• Editable transcript — transcription results are left editable by default.
• Persistent settings — appearance, model, and Online TTS toggle saved in settings.json.
• Online/Offline TTS — toggle in UI; online uses cloud TTS (off by default), offline uses system voice.
• FFmpeg hardening — imageio-ffmpeg resolution with local fallback copy into models\ffmpeg-bin.
• Packaging — PyInstaller one-folder build with version resource & manifest; Inno script with code-signing hook and Startup shortcut (no Run key).
• Docs/Site — updated landing page, changelog page, and privacy policy; optional offline Poppins font bundle.

1.2.0

• Added Explorer right-click (“Transcribe with Qevoxyl”) for .wav/.mp3.
• Stable PyInstaller spec (bundles whisper/assets; UPX disabled).
• StdIO guard for console-less builds (prevents tqdm crashes).
• Persistent per-user data paths and logs.

Support

• Website: https://qevoxyl.yoklearn.com
• Logs for bug reports: %LOCALAPPDATA%\Qevoxyl\logs\app.log