Audioctl.exe v1.5.3.0

Audioctl.exe v1.5.3.0

This release introduces a major intelligence upgrade to the vendor learning engine and resolves a desktop visual artifact caused by the background console window.

Smart Vendor Engine Upgrades

• Profile-Aware Universal Spoofing: The multi-write FX engine now intelligently groups registry writes into distinct device "profiles". When a new device is discovered, the engine scores your live registry to find the best-fit profile and applies only the relevant writes for your specific hardware.
• Universal Fallback: Guaranteed backwards compatibility for older vendor_toggles.ini rules. If a device doesn't match a specific profile, the engine safely falls back to evaluating all writes collectively.
• Zero-Touch Priming: The learning engine now cross-references newly captured toggles against existing database rules. If a primed device perfectly matches an existing universal rule, the engine exits early without appending the device GUID, keeping your INI file clean and bloat-free.
• Strict Registry Truth Enforced: Hardened the registry writer to strictly mutate existing keys. This guarantees the program will never attempt to invent registry paths that your native audio driver hasn't naturally initialized itself.

GUI Polish

• Console Visual Artifact Fix: Resolved a Windows OS visual bug where launching the application as a standard (non-admin) user left a tiny, floating minimized console block on the desktop. The redundant background process window is now cleanly hidden entirely [20].

Audioctl.exe v1.5.2.0

Audioctl.exe v1.5.2.0

Performance Improvements

• Resolved critical slowdown in manufacturing environments caused by USB device enumeration
• Execution time reduced from 20-30s per action to <2s on systems with extensive device history

Technical Changes

• Optimized device enumeration to query only active endpoints
• Removed unnecessary registry lookups for disconnected devices

Audioctl.exe v1.5.1.2

This release focuses on GUI polish, resolving visual annoyances, and fixing a persistent issue with the application icon in the Windows Taskbar.

GUI Polish and Usability

• Taskbar Icon Fix: Resolved an issue where the application icon reverted to a generic "feather" or console icon when running as a non-admin frozen executable. The application now correctly forces the icon to override the PyInstaller bootloader identity.
• Snappy Volume Slider: The volume dialog slider now responds instantly to clicks (jump-to-position) and supports immediate dragging. This replaces the default incremental "step" behavior with custom mouse event bindings for a more modern feel.
• Visual Clean-up: Removed the dotted "focus ring" (ghost box) from the selected device row in the main list for a cleaner look.

Documentation

• Updated ENGINEERING_GUIDE.md and README.md with clearer instructions regarding CLI commands.
• Updated documentation images to reflect the UI changes.

Installation

Download and extract the Audioctl.exe_v1.5.1.2.zip file below.

• Extract the contents to a non-system folder (for example, C:\Tools\Audioctl). Avoid placing it inside Program Files. While the application will still run there, Windows may redirect the log file to an Audioctl folder inside AppData, which makes it harder to locate.

• No installation is required — the application runs as a standalone executable.

• The ZIP package includes:

  • audioctl.exe – Main application

  • audioctl_dbg_log.bat – Launches the application in verbose logging mode

  • vendor_toggles.ini – Configuration file used to define vendor FX toggles

For proper behavior and vendor FX toggle support, all files must remain in the same directory as the executable

Audioctl.exe v1.5.1.1

This release introduces a new embedded console for the GUI, resolves playback device reporting issues in the listen command, and fixes cross-shell compatibility for generated CLI strings.

New Features

• GUI Embedded Console: Added a scrollable text pane to the GUI that mirrors standard output and error streams. This allows users to view CLI feedback directly within the application window.
• Visual Styling: CLI commands printed to the console are now distinctly styled in blue text to differentiate them from standard output logs.
• Smart Selection: Text selection in the console now highlights only the text content (in blue), avoiding the selection of empty whitespace on newline-wrapped lines.
• Console Context Menu: The new embedded console supports a right-click menu where the "Copy" option is context-aware and only enables when text is actively selected.
• Auto-Minimize Console: On Windows, the application now attempts to minimize the external console window on startup to reduce desktop clutter while keeping the process accessible.

Bug Fixes

• Listen Command Reporting (Issue #34): The listen command now conditionally reports playback routing targets only when requested via the new --playback-target-id and --playback-target-name arguments. This preserves backward compatibility for existing scripts while allowing precise verification when needed.
• Invalid ID Fallback: If a provided Render ID is invalid, the system now gracefully falls back to "Default Playback Device" and issues a warning in the JSON output instead of failing silently.
• PowerShell Compatibility (Issue #36): Fixed an issue where generated CLI commands for FX names (like "Bass Boost") and GUIDs were not properly quoted. All tokens are now double-quoted to ensure they paste and execute correctly in PowerShell.

Documentation

• Updated the Engineering Guide (Sections 3.1, 4.8, 4.9) to document the new GUI architecture and JSON contracts.
• Updated README and CHANGELOG to reflect the v1.5.1.1 feature set.

Audioctl.exe v1.5.0.0

Windows Audio Control (audioctl) v1.5.0.0 — Release Notes

v1.5.0.0 is a major step forward for the project. The headline is that Enhancements/FX control is no longer “tied to one learned device GUID.” The backend is now much more universal and much harder to fool, while the GUI stays a thin wrapper over the CLI and feels faster and more reliable day‑to‑day.

The big one: Universal vendor toggles (registry signature is truth)

The vendor toggle engine now treats the live registry signature as the source of truth for whether a toggle applies to a device.

What that means in plain English:

• You can learn an Enhancements toggle or an FX effect toggle once.
• If another endpoint uses the same underlying driver mechanism (same registry layout/signature), audioctl can discover it and control it.
• You don’t have to keep manually adding GUIDs everywhere for the same driver family.
• If the signature isn’t present, audioctl won’t pretend it’s supported and won’t write “ghost” settings.

This is the change that makes the vendor DB reusable across different machines and devices without turning into a GUID maintenance nightmare.

Enhancements + FX subsystem: more complete, more reliable

This release brings the Enhancements system up to a full workflow instead of a one-off toggle.

• MAIN “Audio Enhancements” is vendor-first at runtime and validated by signature.
• FX effects are treated as first-class toggles with better discovery and state reporting.
• FX support benefits from the same universal signature model, so effects can be discovered and queried correctly on devices that match the signature, not only devices explicitly listed.

CLI: device selection by index is finally consistent

--index targeting is now stable across the CLI.

• audioctl list shows indices that match what other commands use.
• Selection logic was centralized so commands don’t re-index after filtering.
• Ambiguous match messages show the real usable indices instead of misleading local numbering.

Result: fewer “why did it target that device?” moments, and much safer automation.

GUI: faster, cleaner, and less fragile

The GUI stays CLI-driven (subprocess backend, no long-lived COM in the UI process), but usability is improved across the board.

Notable improvements:

• Device list display fixed so it doesn’t cut off (autosizing is now correct).
• UI cleanup: active-only view, removed the disabled/disconnected toggle, admin warning moved to the bottom status bar.
• Context menus feel much snappier because state is cached in the background instead of blocking on reads during right-click.
• Learn FX UI text is clearer and more consistent.
• Combobox autocomplete issues were fixed (no snapping around, no “stuck highlight” after selecting an item).

Windows copy/paste: “Print CLI commands” is now actually usable

The GUI’s command echoing is now designed for real Windows usage:

• No more POSIX single-quote output.
• Double quotes are used so the command matches Windows expectations.
• The --id value is always quoted so PowerShell doesn’t misparse MMDevice IDs.
• Frozen builds print commands starting with .\audioctl.exe ... so you can paste directly from the dist folder without needing PATH fixes.

This is a big quality-of-life improvement for anyone using the GUI as a command generator.

Debug logging that still works when elevated (UAC-safe)

Debug logging is much easier to use in real-world admin scenarios now.

• The debug launcher batch file was updated so AUDIOCTL_DEBUG=1 still applies even when launching elevated.
• [DBG ...] lines reliably appear in audioctl_gui.log under UAC.

Build and documentation improvements

• Build and engineering docs were updated and aligned around Python 3.13.12 for this release line.
• README and screenshots were refreshed to match current UI and features.
• Release packaging includes the vendor INI in the right place next to the EXE.

Audioctl.exe v1.4.7.2

Audioctl v1.4.7.2 Release Notes (includes 1.4.7.1 feature set)

Package: audioctl.exe_v1.4.7.2.zip
Binary: audioctl.exe (PyInstaller single-file)
Platforms: Windows 10/11 (x64)
Requires: No Python/runtime required. Some actions may need Administrator.

Versioning note: v1.4.7.2 is a documentation/commenting maintenance release on top of v1.4.7.1.
All functional features listed below are the 1.4.7.1 feature set, and 1.4.7.2 adds improved code/docs clarity with no intended behavior changes.

---

What’s new in 1.4.7.2 (maintenance)

Developer/maintainer improvements (no behavior changes)

• Large, human-readable inline comment pass across all Python modules to make future maintenance and debugging easier:
  • CLI command flow, selection rules, exit codes, and JSON output contracts.
  • COM lifecycle strategy (thread-local init/teardown), GC guards, and interface-definition caching rationale.
  • Registry/property key usage for Listen routing and SysFX diagnostics/learning.
  • Vendor toggle system details (INI schema, caching, multi-write FX semantics, learning/merge/delete behavior).
  • GUI design (CLI-subprocess architecture), background state caching, context menu label logic, and learn workflows.
  • Logging subsystem behavior (lazy init, exception hooks, faulthandler).
• docs refresh:
  • Expanded technical documentation for engineers.
  • Updated vendor toggles guide for clarity and accuracy.

---

What’s new in 1.4.7.1 (feature release included in 1.4.7.2)

Headline features

• CLI‑first control with a richer GUI on top.
• Learn your device’s Enhancements (SysFX) and per‑effect toggles (FX) so they become reliable, repeatable commands.
• Fast read‑only get- helpers* for scripts, overlays, and hotkeys.
• Safer, more predictable COM lifecycle to eliminate sporadic crashes/shutdown issues.

New

• Enhancements FX subsystem:

  • enhancements --learn-fx "FX_NAME": Guided two‑pass A/B learn (A/B then A2/B2) to stabilize vendor behavior.
  • enhancements --enable-fx|--disable-fx "FX_NAME": Toggle a learned effect for the current device.
  • enhancements --list-fx [--json]: List learned FX for a device.
  • enhancements --delete-fx "FX_NAME": Remove this device’s association to the learned FX.
  • INI supports multi‑write FX toggles (DWORD/SZ/BINARY), per‑toggle device scoping, decider_index, and quorum_threshold.

• Query helpers (read‑only; fast, no side effects):

  • get-volume: volume (0..100) and mute.
  • get-listen: “Listen to this device” (Capture only).
  • get-enhancements: vendor-only Enhancements state.
  • get-device-state: combined snapshot (volume, mute, listen, enhancements, FX list+states).

• Listen routing UX:

  • --playback-target-id and --playback-target-name accept the flag without a value to route to “Default Playback Device”.
  • Name‑based routing for Listen target.

Improvements

• COM stability: all device operations run inside a thread‑local COM context; interface definitions are cached once to avoid GC/vtable race conditions.
• PyInstaller friendliness: comtypes “post coinit” modules are forced to load so cleanup code is bundled.
• GUI upgrades:
  • Enhancement Effects submenu with live per‑effect states and one‑click toggles.
  • Non‑blocking learn flows for main Enhancements and FX (guided prompts).
  • Background, incremental get-device-state cache for fast, accurate context menu labels.
  • Suppresses “Print CLI commands” during learn to keep logs readable.
• Vendor INI handling:
  • Default path prefers the exe directory; if not writable, falls back to %LOCALAPPDATA%\audioctl\vendor_toggles.ini.
  • INI reads cached by (path, mtime) to avoid re‑parsing overhead.

CLI at a glance

Command map (full tree)

audioctl
 │ 
 ├─ list [--all] [--json]
 │ 
 ├─ set-default
 │  ├─ --playback-id/--playback-name [--playback-role console|multimedia|communications|all]
 │  └─ --recording-id/--recording-name [--recording-role console|multimedia|communications|all]
 │     [--index] [--regex]
 │ 
 ├─ set-volume
 │  └─ (--id | --name) [--flow Render|Capture] (--level 0..100 | --mute | --unmute)
 │     [--index] [--regex]
 │ 
 ├─ listen (Capture only)
 │  └─ (--id | --name) (--enable | --disable)
 │     [--playback-target-id [<RenderID>]] [--playback-target-name [<RenderName>]]
 │     [--index] [--regex]
 │ 
 ├─ enhancements
 │  ├─ Main switch:
 │  │  └─ (--id | --name) [--flow] (--enable | --disable | --learn)
 │  │     [--index] [--regex] [--prefer-hklm] [--vendor-ini PATH]
 │  │ 
 │  └─ FX operations:
 │     ├─ --list-fx [--json]
 │     ├─ --learn-fx "FX_NAME"
 │     ├─ --enable-fx "FX_NAME" | --disable-fx "FX_NAME"
 │     └─ --delete-fx "FX_NAME"
 │ 
 ├─ get-volume [--id|--name] [--flow] [--index] [--regex]
 │ 
 ├─ get-listen [--id|--name] [--index] [--regex]          (Capture)
 │ 
 ├─ get-enhancements [--id|--name] [--flow] [--index] [--regex]
 │ 
 ├─ get-device-state [--id|--name] [--flow] [--index] [--regex] [--vendor-ini PATH]
 │ 
 ├─ diag-sysfx [--id|--name] [--flow] [--index] [--regex]
 │ 
 ├─ diag-mmdevices [--id|--name] [--flow] [--index] [--regex]
 │ 
 ├─ discover-enhancements [--id|--name] [--flow] [--index] [--regex]
 │  └─ [--output-dir DIR] [--ini-snippet FILE]
 │ 
 └─ wait (--id|--name) [--flow] [--timeout] [--index] [--regex]

---

Quick start

List devices (JSON):

audioctl list --json

Set defaults (all roles):

audioctl set-default --playback-id "{RENDER-ID}" --playback-role all
audioctl set-default --recording-id "{CAPTURE-ID}" --recording-role all

Volume/mute + read‑only check:

audioctl set-volume --id "{RENDER-ID}" --level 25
audioctl set-volume --id "{RENDER-ID}" --mute
audioctl get-volume --id "{RENDER-ID}"

Listen routing:

# Default Playback Device via "flag‑only"
audioctl listen --id "{CAPTURE-ID}" --enable --playback-target-name
# Or specific render device by name
audioctl listen --id "{CAPTURE-ID}" --enable --playback-target-name "Speakers"

Enhancements (main):

# Learn the vendor toggle (manual A/B)
audioctl enhancements --id "{RENDER-ID}" --flow Render --learn
# Then toggle
audioctl enhancements --id "{RENDER-ID}" --flow Render --enable

FX lifecycle:

audioctl enhancements --id "{RENDER-ID}" --flow Render --learn-fx "BassBoost"
audioctl enhancements --id "{RENDER-ID}" --flow Render --enable-fx "BassBoost"
audioctl enhancements --id "{RENDER-ID}" --list-fx --json
audioctl enhancements --id "{RENDER-ID}" --delete-fx "BassBoost"

State snapshot (great for overlays/GUI):

audioctl get-device-state --id "{RENDER-ID}" --flow Render

---

Installation

1. Download audioctl.exe_v1.4.7.2.zip.
2. Extract audioctl.exe to a folder you can write to (e.g., %LOCALAPPDATA%\Programs\audioctl or your desktop/tools folder).
3. Optional: add that folder to your PATH for easy CLI use.
4. Double‑click audioctl.exe to launch the GUI, or run it from a console for CLI.

Note: “Vendor Learn” writes to vendor_toggles.ini. If the exe directory is not writable, the tool uses %LOCALAPPDATA%\audioctl\vendor_toggles.ini.

---

Requirements & permissions

• Windows 10/11 (x64). No Python required.
• Some operations may require Administrator:
  • Listen routing target writes (HKLM).
  • Enhancements when the vendor only honors HKLM (use --prefer-hklm).
• All mutating commands target active endpoints only.

---

Known limitations

• Enhancements are vendor‑first at runtime. If no vendor entry exists for the endpoint, use enhancements --learn first.
• Some virtual/audio middleware devices may expose non‑DWORD or proprietary FX signals; use discover-enhancements if --learn cannot verify.

---

Security & integrity

• Built with PyInstaller; some antivirus engines may flag generic single‑file EXEs.
• Verify provenance (download source) and optionally compute a checksum:
  • Example (PowerShell): Get-FileHash .\audioctl.exe -Algorithm SHA256

---

Support & docs

• README, technical notes, and vendor toggles guide are in the repository docs/.
• Issues/feedback: open an issue on the project tracker.

---

Enjoy reliable, scriptable Windows audio controls that are CLI‑first with a helpful GUI.

Audioctl.exe V1.4.7.1

Audioctl v1.4.7.1 - Release Notes

Package: Audioctl.exe_v1.4.7.1.zip
Binary: audioctl.exe (PyInstaller single-file)
Platforms: Windows 10/11 (x64)
Requires: No Python/runtime required. Some actions may need Administrator.

---

What’s new in 1.4.7.1

Headline features

• CLI‑first control with a richer GUI on top.
• Learn your device’s Enhancements (SysFX) and per‑effect toggles (FX) so they become reliable, repeatable commands.
• Fast read‑only “get-*” helpers for scripts, overlays, and hotkeys.
• Safer, more predictable COM lifecycle to eliminate sporadic crashes/shutdown issues.

New

• Enhancements FX subsystem:
  • enhancements --learn-fx "FX_NAME": Guided two‑pass A/B learn (A/B then A2/B2) to stabilize vendor behavior.
  • enhancements --enable-fx|--disable-fx "FX_NAME": Toggle a learned effect for the current device.
  • enhancements --list-fx [--json]: List learned FX for a device.
  • enhancements --delete-fx "FX_NAME": Remove this device’s association to the learned FX.
  • INI supports multi‑write FX toggles (DWORD/SZ/BINARY), per‑toggle device scoping, decider_index, and quorum_threshold.
• Query helpers (read‑only; fast, no side effects):
  • get-volume: volume (0..100) and mute.
  • get-listen: “Listen to this device” (Capture only).
  • get-enhancements: vendor-only Enhancements state.
  • get-device-state: combined snapshot (volume, mute, listen, enhancements, FX list+states).
• Listen routing UX:
  • --playback-target-id and --playback-target-name accept the flag without a value to route to “Default Playback Device”.
  • Name‑based routing for Listen target.

Improvements

• COM stability: all device operations run inside a thread‑local COM context; interface definitions are cached once to avoid GC/vtable race conditions.
• PyInstaller friendliness: comtypes “post coinit” modules are forced to load so cleanup code is bundled.
• GUI upgrades:
  • Enhancement Effects submenu with live per‑effect states and one‑click toggles.
  • Non‑blocking learn flows for main Enhancements and FX (guided prompts).
  • Background, incremental get-device-state cache for fast, accurate context menu labels.
  • Suppresses “Print CLI commands” during learn to keep logs readable.
• Vendor INI handling:
  • Default path prefers the exe directory; if not writable, falls back to %LOCALAPPDATA%\audioctl\vendor_toggles.ini.
  • INI reads cached by (path, mtime) to avoid re‑parsing overhead.

Fixes

• Listen routing that sometimes “looked” applied but wasn’t now writes the HKLM Properties value Windows actually uses (Admin may be required).
• Eliminated sporadic access violations during shutdown/right‑click by guarding raw vtable usage and relying on comtypes‑managed cleanup.

---

CLI at a glance

audioctl
├─ list [--all] [--json]
├─ set-default --playback-id/--playback-name [--playback-role ...]
│            │ └─ --recording-id/--recording-name [--recording-role ...]
│            └─ [--index] [--regex]
├─ set-volume (--id|--name) [--flow Render|Capture] (--level|--mute|--unmute) [--index] [--regex]
├─ listen (Capture) (--id|--name) (--enable|--disable)
│          [--playback-target-id [<RenderID>]] [--playback-target-name [<RenderName>]]
│          [--index] [--regex]
├─ enhancements
│  ├─ main: (--id|--name) [--flow] (--enable|--disable|--learn) [--index] [--regex] [--prefer-hklm] [--vendor-ini PATH]
│  └─ FX:   --list-fx [--json] | --learn-fx "FX_NAME" | --enable-fx "FX_NAME" | --disable-fx "FX_NAME" | --delete-fx "FX_NAME"
├─ get-volume [--id|--name] [--flow] [--index] [--regex]
├─ get-listen [--id|--name] [--index] [--regex]               (Capture)
├─ get-enhancements [--id|--name] [--flow] [--index] [--regex]
├─ get-device-state [--id|--name] [--flow] [--index] [--regex] [--vendor-ini PATH]
├─ diag-sysfx [--id|--name] [--flow] [--index] [--regex]
├─ diag-mmdevices [--id|--name] [--flow] [--index] [--regex]
├─ discover-enhancements [--id|--name] [--flow] [--index] [--regex] [--output-dir] [--ini-snippet]
└─ wait (--id|--name) [--flow] [--timeout] [--index] [--regex]

---

Quick start

List devices (JSON):

audioctl list --json

Set defaults (all roles):

audioctl set-default --playback-id "{RENDER-ID}" --playback-role all
audioctl set-default --recording-id "{CAPTURE-ID}" --recording-role all

Volume/mute + read‑only check:

audioctl set-volume --id "{RENDER-ID}" --level 25
audioctl set-volume --id "{RENDER-ID}" --mute
audioctl get-volume --id "{RENDER-ID}"

Listen routing:

# Default Playback Device via "flag‑only"
audioctl listen --id "{CAPTURE-ID}" --enable --playback-target-name
# Or specific render device by name
audioctl listen --id "{CAPTURE-ID}" --enable --playback-target-name "Speakers"

Enhancements (main):

# Learn the vendor toggle (manual A/B)
audioctl enhancements --id "{RENDER-ID}" --flow Render --learn
# Then toggle
audioctl enhancements --id "{RENDER-ID}" --flow Render --enable

FX lifecycle:

audioctl enhancements --id "{RENDER-ID}" --flow Render --learn-fx "BassBoost"
audioctl enhancements --id "{RENDER-ID}" --flow Render --enable-fx "BassBoost"
audioctl enhancements --id "{RENDER-ID}" --list-fx --json
audioctl enhancements --id "{RENDER-ID}" --delete-fx "BassBoost"

State snapshot (great for overlays/GUI):

audioctl get-device-state --id "{RENDER-ID}" --flow Render

---

Installation

1. Download Audioctl.exe_v1.4.7.1.zip.
2. Extract audioctl.exe to a folder you can write to (e.g., %LOCALAPPDATA%\Programs\audioctl or your desktop/tools folder).
3. Optional: add that folder to your PATH for easy CLI use.
4. Double‑click audioctl.exe to launch the GUI, or run it from a console for CLI.

Note: “Vendor Learn” writes to vendor_toggles.ini. If the exe directory is not writable, the tool uses %LOCALAPPDATA%\audioctl\vendor_toggles.ini.

---

Requirements & permissions

• Windows 10/11 (x64). No Python required.
• Some operations may require Administrator:
  • Listen routing target writes (HKLM).
  • Enhancements when the vendor only honors HKLM (use --prefer-hklm).
• All mutating commands target active endpoints only.

---

Known limitations

• Enhancements are vendor‑first at runtime. If no vendor entry exists for the endpoint, use enhancements --learn first.
• Some virtual/audio middleware devices may expose non‑DWORD or proprietary FX signals; use discover-enhancements if --learn cannot verify.

---

Security & integrity

• Built with PyInstaller; some antivirus engines may flag generic single‑file EXEs.
• Verify provenance (download source) and optionally compute a checksum:
  • Example (PowerShell): Get-FileHash .\audioctl.exe -Algorithm SHA256

---

Support & docs

• README, technical notes, and vendor toggles guide are in the repository Docs/.
• Issues/feedback: open an issue on the project tracker.

---

Changelog (since v1.4.3.2)

• Added: FX list/learn/enable/disable/delete, query helpers, listen routing by name/flag‑only.
• Improved: COM stability, GUI with FX submenu and non‑blocking learn, vendor INI handling (path fallback, caching).
• Fixed: Listen route reflects in Windows via correct HKLM value; resolved sporadic shutdown crashes.

Enjoy reliable, scriptable Windows audio controls that are CLI‑first with a helpful GUI.