AutoVolume

AutoVolume is a Windows-focused C++ audio utility for making playback loudness more consistent on a real Windows machine.

The repository currently has two explicit product tracks:

• User-mode mixer-control prototype
  • observes the default playback output with WASAPI loopback
  • performs near-real-time loudness analysis
  • recommends or applies conservative control through Windows audio APIs
  • this is the practical public-release path today
• Experimental APO / inline dBFS path
  • targets a host-specific endpoint-effect APO (EFX)
  • aims to keep Windows master/session mixer state unchanged during APO validation
  • currently intended for advanced test users, not ordinary one-click public installs

For the Chinese version of this overview, see README.zh-CN.md.

Current Status

• Container builds with CMake + MSVC and smoke tests are in place.
• The user-mode package already has install/uninstall scripts and is suitable for GitHub Releases.
• The APO package now includes test-signing support, binding diagnostics, runtime-config hot reload, fixed-gain validation, loudness mapping, and a guided test-environment flow.
• Distribution of the APO package to other machines still follows a test-environment model rather than a formally signed public-driver model.

Repository Layout

• src/audio/: endpoint, loopback, session, and loudness logic
• src/apo/: experimental APO runtime and configuration logic
• src/tools/: APO packaging and host validation tools
• tests/: smoke coverage for config, packaging, cleanup, and test-signing
• docs/: user-facing build and package notes

Build

Container-based development remains the default:

cmake -S . -B build-container -G Ninja
cmake --build build-container
ctest --test-dir build-container --output-on-failure

Release build:

cmake -S . -B build-release -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build-release

See docs/build.md for more detailed build and packaging notes. The Chinese version is docs/build.zh-CN.md.

User-Mode Release Package

Build the public user-mode package:

.\make-dist.cmd

Output:

dist\AutoVolume\

It currently includes:

• Install-AutoVolume.cmd
• Install-AutoVolume.ps1
• Uninstall-AutoVolume.cmd
• Uninstall-AutoVolume.ps1
• run-auto-volume.cmd
• build-release\autovolume_console.exe

This install flow only writes to the current user's profile under %LocalAppData%\Programs\AutoVolume, creates current-user Start Menu entries, and does not touch APO, drivers, certificates, or system boot policy.

APO Test Package

Build the experimental test-signed APO package:

.\make-testsigned-apo-package.cmd

Output:

dist\AutoVolumeApoPackage\

Important scripts:

• Verify-AutoVolumePackage.ps1
• Prepare-AutoVolumeApoTestEnvironment.ps1
• Reset-AutoVolumeApoTestEnvironment.ps1
• Setup-AutoVolumePostRebootValidation.ps1
• Run-AutoVolumePostRebootValidation.ps1
• Inspect-AutoVolumeApoBinding.ps1
• Verify-InstalledAutoVolumeApo.ps1
• Set-AutoVolumeApoRuntimeConfig.ps1
• Test-AutoVolumeApoFixedGain.ps1

Recommended advanced-user flow:

1. Run Verify-AutoVolumePackage.ps1
2. Preview Prepare-AutoVolumeApoTestEnvironment.ps1
3. Apply it in elevated PowerShell if the preview looks correct
4. Reboot and let the one-shot task install and verify
5. Use Reset-AutoVolumeApoTestEnvironment.ps1 -Apply when you want to remove the test environment again

This route is meant for advanced users who accept certificate import, testsigning, reboot-based setup, and host-specific diagnostics.

GitHub Actions

The repository now includes:

• .github/workflows/ci.yml
  • builds on windows-latest
  • runs ctest
  • assembles a user-mode distribution artifact
• .github/workflows/release.yml
  • manual GitHub Release workflow
  • reads release.md as the release body
  • publishes the user-mode zip by default
  • can optionally publish a host-parameterized test-signed APO zip

Release Rules

• release.md is the draft body for the next GitHub Release.
• Any commit that changes user-visible behavior, packaging, workflows, or release assets should also update release.md.
• The Release workflow blocks if release.md still contains the template placeholder.
• After a successful release, the workflow resets release.md back to the template.
• Release notes should be maintained in both Chinese and English sections.

Important Boundaries

• Windows per-session volume remains scalar, not a true dB API.
• Endpoint/master volume can be controlled in dB terms through IAudioEndpointVolume.
• The user-mode prototype is not the final inline dBFS architecture.
• A package being present in Driver Store is not proof that the APO is active on the current playback endpoint.

Further Reading

• Build and package notes: docs/build.md