# Audio Path Tone Tester

Audio Path Tone Tester is a Windows audio-path diagnostic tool. It is not a
music player.

The app generates controlled 1 kHz test signals, sends them through a selected
Windows audio backend/device/format, and records initialization, runtime,
buffer, lifecycle, and error evidence for troubleshooting.

## Status

Version 0.1.0 is a release-candidate source tree prepared for GPLv3 public
publication.

The 2026-06-21 local acceptance baseline passed the ASIO-enabled Debug CTest
suite, the ASIO-enabled Release package smoke test, a short Lynx AES16e normal
all-path smoke, and a bounded 5-second Lynx high-load diagnostic rerun. Hardware
behavior remains device- and driver-specific; these results are not a guarantee
for other devices.

## Supported Diagnostic Paths

- MME PCM.
- DirectSound PCM.
- WASAPI shared PCM.
- WASAPI exclusive PCM and DoP carrier playback.
- Kernel Streaming PCM and DoP carrier playback where the selected pin/format
  supports it.
- ASIO PCM, ASIO DoP carrier playback, and ASIO native DSD when built with
  `ENABLE_ASIO=ON` and when the selected driver exposes the required format.

ASIO support is build-gated and distribution-gated. ASIO is used only as a
descriptive backend/API label. The product name does not contain ASIO, no ASIO
logo artwork is included in this public source folder, and vendor ASIO drivers
are not bundled.

## Safety Model

- Real-device operations require an explicit selected device.
- Default stop behavior keeps the stream warm or held instead of immediately
  releasing the device.
- Full release, reacquire loops, format cycling, automated diagnostics, and
  high-load diagnostics are bounded and guarded.
- The app does not change Windows global power, USB selective suspend, endpoint
  volume, default-device, or vendor-driver settings.
- ASIO control panels are not opened automatically.
- Kernel Streaming probe/start behavior is explicit and conservative.
- High-load diagnostics are off by default and require a separate risk
  acknowledgement.

## Basic Use

1. Select the target API.
2. Load devices for that API.
3. Select one output device.
4. Let the app build the capability matrix.
5. Select a playable or candidate matrix cell.
6. Set signal, buffer/scheduling, lifecycle, and logging conditions.
7. Run the test, stop it, optionally release the held device, and export the
   diagnostic bundle.

Kernel Streaming `data_range_match` rows are candidate evidence. They are not
confirmed playback support until stronger pin/start evidence is recorded.

## Diagnostic Output

Diagnostic bundles can include:

- `config.json`
- `playback.jsonl`
- `realtime.csv`
- `release.json`
- `summary.csv`
- `summary.txt`
- `device_dump.json`
- `device_snapshot.json`
- `format_probe.json`
- `build_metadata.json`
- `bundle_manifest.json`

Device names, endpoint IDs, and driver strings may appear in exported bundles.
Review bundles before sharing them publicly.

## License

This public source folder is prepared for publication under GPL-3.0-only. See
`COPYING` or `LICENSE`.

Third-party components:

- Dear ImGui is included under its license; see `docs/THIRD_PARTY.md` and
  `third_party/imgui/LICENSE.txt`.
- Steinberg ASIO SDK files needed for the optional `ENABLE_ASIO=ON` build are
  included under the SDK's GPLv3 path. See
  `ASIO-SDK_2.3.4_2025-10-15/ASIOSDK/LICENSE.txt`,
  `ASIO-SDK_2.3.4_2025-10-15/ASIOSDK/README.md`, and
  `docs/decisions/0002-asio-license-and-trademark.md`.

The public copyright holder notice is recorded in `NOTICE`.

## Build

Requirements:

- Windows 10/11 x64.
- CMake 3.23 or newer.
- Visual Studio 2022 or Visual Studio Build Tools 2022 with C++ desktop tools.
- Windows SDK.
- Ninja for the Ninja presets.

Default ASIO-disabled build:

```powershell
cmake --preset msvc-debug -DENABLE_ASIO=OFF
cmake --build --preset msvc-debug
ctest --preset msvc-debug
```

ASIO-enabled build:

```powershell
cmake --preset vs2026-ninja-asio-debug -DENABLE_ASIO=ON
cmake --build --preset vs2026-ninja-asio-debug
ctest --preset vs2026-ninja-asio-debug
```

The `vs2026-*` presets were used in the local acceptance environment. If your
machine uses Visual Studio 2022, use an equivalent developer shell and preset or
configure a local build directory with the same options.

## Packaging

The packaging target creates a one-file Windows executable under `dist/`.

ASIO-disabled package:

```powershell
cmake --build --preset vs2026-ninja-release --target package_onefile_smoke
```

ASIO-enabled binary distribution must also provide exact corresponding source
and configure the package gate with:

```powershell
-DAPTT_PACKAGE_ACK_ASIO_GPLV3_SOURCE=ON
-DAPTT_ASIO_CORRESPONDING_SOURCE_PACKAGE=<path-or-name>
-DAPTT_ASIO_CORRESPONDING_SOURCE_SHA256=<sha256>
```

See `docs/PACKAGING.md`.

## Publication Notes

Generated files, local tools, build outputs, release packages, diagnostic
bundles, logs, object files, PDB files, and local device smoke artifacts are not
part of this public source folder.

This repository does not provide legal advice. Review the GPLv3 source
availability, third-party notices, and Steinberg trademark constraints before
publishing binaries.
