Skip to content

fix(sound): stabilize wheel hover feedback and validate custom WAV - #172

Merged
SoftBlack42 merged 2 commits into
mainfrom
codex/sound-hover-stability
Sep 27, 2026
Merged

SoftBlack42 merged 2 commits into
mainfrom
codex/sound-hover-stability

Conversation

@SoftBlack42

@SoftBlack42 SoftBlack42 commented Sep 27, 2026 •

Copy link
Copy Markdown
Collaborator

Summary of Changes

This PR stabilizes StarPie's wheel hover sound scheduling and introduces robust RIFF/WAVE parsing and volume scaling for custom sound effects (addressing SP-SOUND-001).

1. Wheel Hover Feedback Stabilization

  • Interaction Session Isolation: Decoupled hover candidate selection and debounce tracking per active wheel interaction session (GestureController, StickyWheelSession, and preview canvas in SettingsWindow). Prevents stale candidates or active timers from one interaction leaking into another.
  • Pre-Claim Expiration & Cadence Guard: Discards hover candidates that expire while awaiting resources or synchronization locks (max allowed staleness: 150ms). Enforces an 80ms minimum playback interval to prevent rapid audio stutter during swift gesture sweeps.
  • Immediate Preemption: Terminal action execution (ActionExecute) immediately cancels pending hover candidates, ensuring immediate execution feedback.

2. Robust RIFF/WAVE Parsing & PCM Volume Scaling

  • Chunk-Based Hierarchy Traversal: Traverses RIFF/WAVE chunk structures dynamically to locate the data chunk instead of assuming a fixed 44-byte header offset.
  • Arbitrary Metadata Support: Handles optional metadata chunks (JUNK, LIST, INFO) whether located before or after the audio data chunk. Correctly respects odd-length chunk padding bytes.
  • Format & Byte-Rate Validation: Validates 16-bit uncompressed PCM (mono or stereo), non-zero sample rates, valid block alignment, and verifies byteRate == sampleRate * blockAlign with 64-bit overflow guards.
  • Safe Fallback & Non-Destructive Scaling: Rejects truncated, corrupted, or duplicate data chunks, recording descriptive fallback reasons in diagnostic properties and safely falling back to synthesized sounds. Audio samples are scaled non-destructively without mutating the source byte array.

3. Verification & Headless CI Integration

  • Sound Forensics Test Suite: Added a deterministic, headless test suite (275 tests in scratch/test_sound_forensics.cs) covering concurrency, race conditions, chunk parsing edge cases, and corruption fallbacks using mock sinks (--test-instance). Zero physical audio playback and zero UI interference during automated test execution.
  • Multi-Cycle Gate: Added scratch/run_10_cycles.ps1. Passed 10/10 consecutive test cycles (100% pass rate, 2,750 assertions without failure).
  • CI Workflow: Added the sound forensics test runner to .github/workflows/build-and-test.yml as a blocking Release-mode check on Windows.

Testing & Hardware Notice

Note

All unit and concurrency assertions were executed against headless mock playback sinks and test seams (TestMode = true).
While software-level scheduling races and buffer parsing bugs are fully validated by the automated test suite, real-world acoustic behavior can vary across physical sound cards, DACs, and audio drivers. Human verification with physical speakers/headphones on varied hardware setups is recommended prior to release tagging.

Rollback & Safety

  • If unexpected audio playback issues occur in user environments, users are advised to turn off sound effects using the sound toggle in Settings (or globally set EnableSoundEffects = false in config.json).
  • Changes maintain 100% backward compatibility with existing configuration schemas and require no SDK or contract modifications.

- Stabilize wheel hover sound scheduling:
  - Isolate hover candidate evaluation and debouncing per wheel interaction session.
  - Eliminate inter-session state leakage and lingering debounce timers across gestures, sticky sessions, and preview canvas.
  - Enforce minimum playback interval (80ms) and discard stale candidates before playback claim.
  - Guarantee immediate action execution preempts pending hover sounds without race conditions.
- Robust custom RIFF/WAVE parsing:
  - Parse RIFF/WAVE chunk hierarchy, correctly locating the 'data' chunk rather than assuming a fixed 44-byte header.
  - Support arbitrary metadata chunks (e.g., JUNK, LIST) before or after 'data', properly handling odd-sized chunk padding bytes.
  - Strictly validate format (16-bit PCM, 1 or 2 channels), byte rate (sampleRate * blockAlign with 64-bit overflow check), and chunk bounds.
  - Reject corrupted, truncated, or duplicate 'data' chunks, gracefully falling back to synthesized sounds with clear error recording.
  - Scale audio samples non-destructively without modifying source arrays.
- Test coverage and Headless CI:
  - Add comprehensive automated forensics test suite (275 tests) in scratch/test_sound_forensics.cs with headless mock sound sink and zero physical audio playback.
  - Provide scratch/run_10_cycles.ps1 for multi-cycle regression verification (10/10 cycles passed).
  - Integrate sound forensics suite into .github/workflows/build-and-test.yml as a blocking CI gate.
@SoftBlack42

Copy link
Copy Markdown
Collaborator Author

用户已报告本机人工验收通过。
自动化测试使用模拟播放后端;
原反馈设备尚未复测,不宣称所有设备问题均已解决。

@SoftBlack42
SoftBlack42 marked this pull request as ready for review September 27, 2026 03:56
@SoftBlack42
SoftBlack42 merged commit ca44fc8 into main Sep 27, 2026
1 check passed
@ztzpro
ztzpro deleted the codex/sound-hover-stability branch September 30, 2026 05:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant