# Playback Troubleshooting Parameter Specification

This file classifies parameters for the future Windows playback
troubleshooting tool. It is a specification input for GUI, logging, diagnostics,
and tests. It is not an implementation.

## Classification Legend

- `GUI`: should be exposed as a user control or visible status field.
- `LOG`: should be written to the session log.
- `DERIVED`: should be computed from runtime data.
- `SAFETY`: should have conservative defaults, warnings, or guardrails.
- `DEFER`: useful later, but not required for the first implementation.

## Global Session Parameters

| Parameter | Class | Notes |
| --- | --- | --- |
| Session ID | LOG | Stable ID for correlating all events. |
| Local and UTC timestamps | LOG | Include start, stop, fault, and release times. |
| Application version and build ID | LOG | Required for reproducibility. |
| Process bitness | LOG | Important for ASIO driver compatibility. |
| Windows version | LOG | Include build number when available. |
| Backend mode | GUI, LOG | MME, DirectSound, WASAPI shared, WASAPI exclusive, Kernel Streaming, ASIO. |
| Device display name | GUI, LOG | User-facing selection. |
| Stable device/API ID | LOG | WASAPI endpoint ID, DirectSound GUID, waveOut ID, KS filter/pin identity, ASIO driver CLSID/name. |
| Known-problem device profile | GUI, LOG, SAFETY | Manual flag for XMOS/USB DACs or devices sensitive to stop/reopen. |
| Output channel selection | GUI, LOG | Include channel labels and mapping. |
| Run duration | GUI, LOG | Fixed duration or indefinite. |
| Stop reason | LOG | User stop, duration elapsed, error, invalidated device, underrun threshold. |

## Device Lifecycle Parameters

These parameters are required to prevent the application from making unstable
USB DAC or ASIO-driver behavior worse.

| Parameter | Class | Notes |
| --- | --- | --- |
| Hold mode | GUI, LOG, SAFETY | `Keep warm after stop`, `Hold initialized`, `Release after drain`, `Immediate release`. |
| Default hold mode | SAFETY | Default to keep-warm/hold-open for troubleshooting sessions. |
| Keep-alive stream enabled | GUI, LOG, SAFETY | Sends valid silence after signal stop. |
| Keep-alive format | LOG, SAFETY | PCM silence, valid DoP silence frames, or native DSD idle pattern. |
| Drain before stop | GUI, LOG, SAFETY | Enabled by default. |
| Drain timeout | GUI, LOG, SAFETY | Prevents infinite wait during broken driver states. |
| Release cooldown | GUI, LOG, SAFETY | Delay before releasing device resources. |
| Reacquire cooldown | GUI, LOG, SAFETY | Delay before attempting to reopen the same device. |
| Maximum reacquire attempts | GUI, LOG, SAFETY | Bounded retry count. |
| Rapid format cycling guard | GUI, LOG, SAFETY | Prevents repeated sample-rate/format changes without delay. |
| Lifecycle transition log | LOG | Discovered, reserved, prepared, running, draining, held, releasing, released, faulted. |
| Fully released warning | GUI, SAFETY | Explain that a released device can be suspended by OS/driver/hub behavior. |

## Signal Parameters

| Parameter | Class | Notes |
| --- | --- | --- |
| Waveform | GUI, LOG | Default and primary mode: 1 kHz sine. |
| Frequency override | GUI, LOG, SAFETY | Allow only as diagnostic option. |
| Amplitude dBFS | GUI, LOG, SAFETY | Conservative default. |
| Per-channel enable/mute | GUI, LOG | Useful for channel troubleshooting. |
| Phase inversion and phase offset | GUI, LOG | Useful for wiring/channel diagnostics. |
| Ramp-in and ramp-out duration | GUI, LOG, SAFETY | Enabled by default. |
| Preamble silence | GUI, LOG | Helps isolate initialization from signal start. |
| Dither for integer PCM | GUI, LOG, DEFER | Useful once PCM conversion exists. |

## PCM Format Parameters

| Parameter | Class | Notes |
| --- | --- | --- |
| Sample rate | GUI, LOG | Requested and accepted values. |
| Bit depth | GUI, LOG | Requested and accepted values. |
| Integer or floating-point format | GUI, LOG | Include IEEE float support. |
| Container bits and valid bits | GUI, LOG | Required for WAVEFORMATEXTENSIBLE. |
| Signedness and endianness | LOG | Usually implicit on Windows PCM, but log when relevant. |
| Channel count | GUI, LOG | Requested and accepted values. |
| Channel mask | GUI, LOG | Required for multichannel diagnostics. |
| Interleaved/internal layout | LOG | Useful for backend debugging. |

## DoP Parameters

| Parameter | Class | Notes |
| --- | --- | --- |
| DSD rate | GUI, LOG | DSD64, DSD128, DSD256, or supported set. |
| PCM carrier sample rate | GUI, LOG | Usually DSD rate dependent. |
| PCM carrier bit depth | GUI, LOG | Typically 24-bit in 32-bit container where supported. |
| DoP marker bytes | LOG, SAFETY | Validate marker alternation. |
| DSD byte order | GUI, LOG | Important for device compatibility. |
| Channel packing order | LOG | Required for reproducibility. |
| DoP silence frame generation | LOG, SAFETY | Keep-alive must remain valid DoP, not arbitrary PCM silence. |
| Unsupported-rate behavior | GUI, LOG, SAFETY | Fail clearly and avoid noise. |

## ASIO Native DSD Parameters

| Parameter | Class | Notes |
| --- | --- | --- |
| ASIO driver name and CLSID | GUI, LOG | Include process bitness compatibility. |
| Driver path or registry source | LOG | Only when safely available. |
| ASIO sample type | GUI, LOG | Include `ASIOSTDSDInt8LSB1`, `ASIOSTDSDInt8MSB1`, `ASIOSTDSDInt8NER8`. |
| Native DSD rate requested/accepted | GUI, LOG | Driver-specific. |
| DSD byte order and packing | GUI, LOG, SAFETY | Must match driver sample type. |
| Selected output channels | GUI, LOG | Include channel names. |
| Buffer min/max/preferred/granularity | GUI, LOG | Required before selecting buffer size. |
| Selected ASIO buffer size | GUI, LOG | Frames/samples and milliseconds where meaningful. |
| Input and output latency | LOG | From ASIO latency query. |
| Sample-rate query/set result | LOG | Include `ASE_NoClock` and similar failures. |
| `ASIOOutputReady` support | LOG | Use only if supported. |
| Time-info support | LOG | Include timestamp quality. |
| Driver callbacks | LOG | Reset, resync, buffer-size change, sample-rate change. |
| Control panel action | GUI, LOG, SAFETY | Manual only; never auto-open. |

## MME Parameters

| Parameter | Class | Notes |
| --- | --- | --- |
| `waveOut` device ID | GUI, LOG | Include mapper usage if selected. |
| Requested/accepted wave format | GUI, LOG | WAVEFORMATEX or WAVEFORMATEXTENSIBLE. |
| Buffer count | GUI, LOG | Expert control. |
| Buffer size frames/bytes/ms | GUI, LOG | Expert control. |
| Callback mode | GUI, LOG | Function/window/event as supported by implementation. |
| Prepared header count | LOG | Must match queue depth. |
| Queue depth | GUI, LOG, DERIVED | Key underrun diagnostic. |
| Drain versus reset behavior | GUI, LOG, SAFETY | Prefer drain; reset explicit only. |
| Write interval and error codes | LOG, DERIVED | Detect starvation. |

## DirectSound Parameters

| Parameter | Class | Notes |
| --- | --- | --- |
| Device GUID | GUI, LOG | Stable selection. |
| Cooperative level | GUI, LOG, SAFETY | Avoid changing during active session. |
| Primary buffer format | GUI, LOG | Where supported. |
| Secondary buffer format | GUI, LOG | Requested and accepted. |
| Secondary buffer size | GUI, LOG | Bytes, frames, milliseconds. |
| Notification interval | GUI, LOG | Expert control. |
| Play/write cursor polling interval | GUI, LOG | Important for underrun diagnosis. |
| Hardware/software path | LOG | If available. |
| Lost buffer restore events | LOG | Required for stability analysis. |
| Lock/unlock timing and failures | LOG, DERIVED | Detect stalls. |

## WASAPI Parameters

| Parameter | Class | Notes |
| --- | --- | --- |
| Endpoint ID and friendly name | GUI, LOG | Stable selection. |
| Data flow, role, form factor | LOG | Device context. |
| Shared/exclusive mode | GUI, LOG | Separate backend modes. |
| Event-driven/timer-driven mode | GUI, LOG | Expert control. |
| Requested format | GUI, LOG | User-selected format. |
| Mix format | GUI, LOG | Required for shared mode. |
| Accepted or closest-match format | LOG | From format negotiation. |
| Buffer duration | GUI, LOG | Requested and actual. |
| Periodicity | GUI, LOG | Exclusive mode expert control; event-driven exclusive mode requires this to match buffer duration. |
| Exclusive event wait timeout | GUI, LOG, SAFETY | Detects an event-driven stream that stops signaling instead of blocking indefinitely. |
| Exclusive buffer alignment retry | GUI, LOG, SAFETY | Allows one `AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED` correction using the aligned frame count and a fresh `IAudioClient`. |
| Engine/device period | LOG | Include default/min period where available. |
| Stream flags | GUI, LOG | Event callback, raw/no-effects where supported. |
| Audio session GUID/name | GUI, LOG | Useful for session diagnostics. |
| Stream category | GUI, LOG | Expert control if implemented. |
| Endpoint volume/mute snapshot | LOG, DEFER | Read-only, if safe. |
| `GetCurrentPadding` values | LOG, DERIVED | Core buffer diagnostic for timer/poll-driven streams; event-driven exclusive streams write whole event buffers. |
| Clock position/timestamps | LOG, DERIVED | Drift diagnostics. |
| Device invalidation events | LOG, SAFETY | Include disconnect reason when available. |

## Kernel Streaming Parameters

| Parameter | Class | Notes |
| --- | --- | --- |
| KS filter symbolic link/path | GUI, LOG, SAFETY | Explicit selected filter identity before any pin operation. |
| Selected pin ID | GUI, LOG, SAFETY | Explicit render/sink pin selection; do not auto-create pins from broad sweeps. |
| Pin dataflow and communication | GUI, LOG | Required to distinguish render, bridge, sink, and communication style. |
| Data range list | GUI, LOG | Log `KSDATARANGE`/audio range fields where available. |
| Requested/accepted data format | GUI, LOG | Include PCM sample rate, channels, valid bits, container bits, subtype, and specifier. |
| Pin create result | LOG, SAFETY | Include IOCTL/Win32/NTSTATUS-style error where available. |
| Allocator/framing fields | GUI, LOG | Frames, alignment, physical range, and allocator requirements where exposed. |
| Stream state transitions | GUI, LOG, SAFETY | Log acquire/pause/run/stop-style transitions and never state-cycle in an unbounded loop. |
| Write packet size and cadence | GUI, LOG, DERIVED | Needed for underrun/starvation troubleshooting. |
| Completion latency and pending I/O | LOG, DERIVED | Detect stalled or late KS write completion. |
| Pin invalidation/fault | LOG, SAFETY | Treat disconnect or driver failure as diagnostic state, not retry-loop trigger. |
| KS DoP carrier support | GUI, LOG, SAFETY | Only where exact PCM carrier format is accepted; keep-alive must use valid DoP silence. |

## Runtime Diagnostics

| Parameter | Class | Notes |
| --- | --- | --- |
| Frames generated/submitted/accepted | LOG, DERIVED | Per backend. |
| Buffer fill/padding | LOG, DERIVED | Backend-specific. |
| Callback count | LOG, DERIVED | Include missed/late callbacks. |
| Callback interval min/max/avg/p95/p99 | LOG, DERIVED | Required for dropout analysis. |
| Callback execution duration | LOG, DERIVED | Detect slow processing. |
| Write duration | LOG, DERIVED | Detect API stalls. |
| Underrun/xrun/starvation indicators | LOG, DERIVED | Use backend-specific terms. |
| Device position versus generated position | LOG, DERIVED | Drift and discontinuity. |
| Host/device clock drift | LOG, DERIVED | Where available. |
| Audio thread ID and priority | LOG | Include MMCSS task if used. |
| Process CPU estimate | LOG, DERIVED | Useful but not a substitute for ETW. |
| Memory allocations during callback | LOG, DERIVED, SAFETY | Target should be zero after start. |

## Logging Controls

| Parameter | Class | Notes |
| --- | --- | --- |
| Log directory and file name | GUI, LOG | User visible. |
| Log format | GUI, LOG | JSONL first; optional text/CSV later. |
| Log level | GUI, LOG | Include normal/verbose/callback-trace modes. |
| Initialization dump | GUI, LOG | Enabled by default. |
| Callback event logging | GUI, LOG, SAFETY | Can be high volume; expose rate/limit. |
| Periodic summary interval | GUI, LOG | Useful for long runs. |
| Raw API error codes | LOG | Include decoded messages. |
| Device capability snapshot | LOG | Before stream start. |
| Log rotation/overwrite behavior | GUI, LOG, SAFETY | Avoid accidental overwrite. |

## Stress And Reproduction Controls

| Parameter | Class | Notes |
| --- | --- | --- |
| Warm-up duration | GUI, LOG | Before measured signal. |
| Start delay | GUI, LOG | For repeatable capture setup. |
| Fixed random seed | GUI, LOG, DEFER | For future randomized diagnostics. |
| Buffer-size sweep | GUI, LOG, SAFETY | Later; must include cooldowns. |
| Sample-rate sweep | GUI, LOG, SAFETY | Later; must include cooldowns and disable rapid cycling. |
| Backend retry count | GUI, LOG, SAFETY | Bounded. |
| Artificial CPU load | GUI, LOG, SAFETY, DEFER | Off by default with clear limits. |
| API-specific scheduling settings | GUI, LOG | MME buffer count/duration, DirectSound secondary-buffer/chunk/polling, WASAPI shared/exclusive buffer and period requests, and ASIO output-ready behavior are exposed according to the selected API. |
| MMCSS task name/priority | GUI, LOG | Expose as an API-aware audio-thread scheduling control. Apply only on app-owned render/poll/stream-service threads unless a backend has a safe same-thread callback registration path; log task name, relative priority, thread ID, registration result, and revert result. |
| Dropout marker injection | GUI, LOG, DEFER | For validating logs, not first release. |

## Initial Defaults

- Backend: WASAPI shared for first safe smoke path, then explicit user choice.
- Hold mode: keep warm after stop during troubleshooting sessions.
- Amplitude: conservative default, with visible dBFS value.
- Ramp-in/ramp-out: enabled.
- Drain before stop: enabled.
- Immediate release: manual diagnostic option only.
- Reacquire attempts: bounded and logged.
- Format sweep: disabled until lifecycle cooldown behavior is implemented.
- DoP/native DSD: require explicit mode selection and warnings.
