Thrum

Thrum is a Windows controller application. It reads supported PlayStation and Nintendo controllers — DualShock 4, DualSense, DualSense Edge, DualShock 3, Switch Pro, and Joy-Con (left, right, and joined) — applies per-profile mappings, and presents virtual controllers that games recognise: Xbox 360, DualShock 4, DualSense, DualSense Edge, and Switch 2 Pro. Virtual output is provided by the VIIPER backend. Thrum also turns game and desktop audio into DualSense haptic feedback, forwards adaptive-trigger effects, and adds a fail-closed driver-safety layer that refuses to run virtual-device features on a kernel driver package it cannot positively identify.

Two caveats on that paragraph, because it describes intent and the current release falls short of it in two known ways:

• Virtual DualSense output does not work on the pinned backend. VIIPER v0.0.6 refuses to create it (unknown device type: dualsense); Xbox 360 output works. This is an upstream regression with a rollback pending — see issues #70 and #79.
• Audio haptics reach the pad over Bluetooth only. On USB they still need a virtual controller, which runs into the point above. See issue #65.

Status

Pre-release, version 0.9.0-beta.1. This repository was seeded on 2026-07-25 from the DS4Windows lineage.

The user-facing identity is rebranded: the assembly and executable are Thrum, settings live in %APPDATA%\Thrum, and the window titles and log banner say Thrum. What remains on the DS4Windows name is internal — the solution and project files (DS4WindowsWPF.sln, DS4WindowsTests), the DS4Windows namespaces, and the DS4WinWPF root namespace. That is why the build commands below still reference DS4Windows paths.

Running alongside a real DS4Windows install works but is not a supported configuration: both will contend for the same physical controller.

The first release is out: v0.9.0-beta.1, a pre-release. It is a self-contained win-x64 zip, so it does not need the .NET 8 Desktop Runtime installed. There is still no installer.

The build is unsigned, so Windows shows "Windows protected your PC". Verify what you downloaded against the SHA-256 published with the release rather than trusting or ignoring that warning. NOTICE.txt and COPYING are attached to the release as separate files because the archive does not yet contain them (issue #75).

Read the release notes before installing: they list what is verified on real hardware and — deliberately at equal length — what is not.

To publish the same self-contained package from source:

dotnet publish .\DS4Windows\DS4WinWPF.csproj -c Release -r win-x64 --self-contained true

Lineage and attribution

Thrum continues the DS4Windows line of work and is not a replacement for the projects it builds on:

• DS4Windows — originated by Jays2Kings, carried forward by Ryochan7, then Schmaldeo, then hbashton, together with the wider DS4Windows contributor community. This repository imports the full history of hbashton/DS4Windows and tracks it as an upstream (see docs/dev/ADR-0002-upstream-tracking.md).
• VIIPER — the virtual-controller backend, by hbashton (hbashton/VIIPER), GPL-3.0. Thrum consumes VIIPER as a pinned release binary and never vendors its source (see docs/dev/ADR-0001-repo-topology.md).
• usbip-win2 — the kernel USB/IP driver VIIPER depends on, by vadimgrn (vadimgrn/usbip-win2), BSD-2-Clause. It is an external prerequisite: Thrum does not contain, redistribute, or sign it.
• HidHide — an external, optional prerequisite used to hide physical controllers from games.
• Protocol research — controller-protocol work shared publicly by egormanga (SAxense) and awalol (DS5Dongle), among others.

Full third-party attribution is in NOTICE.txt.

Driver safety

Virtual controllers on Windows require a kernel driver. VIIPER's is usbip-win2, and the Thrum maintainers classify every currently published release of it as experimental, not production-approved.

This is not a formality. A request-lifetime race in usbip-win2 has been reproduced and confirmed at source level: virtual USB audio endpoint teardown can overlap in-flight isochronous completions, corrupting kernel heap and producing bugchecks 0xA / 0x139. Controller-only emulation (no audio, mic, or advanced-haptics endpoints) does not exercise that path. The defect is filed upstream as usbip-win2 issue #181.

Thrum's response is a read-only driver diagnostic, already present in this tree (DS4Windows/DS4Control/Viiper/Validation/, entry point -viiperdriverdiagnostic). It inspects the installed driver package against a pinned manifest — exact package versions, INF driver versions, Authenticode subject — and reports what it finds. It performs no elevation, no device I/O, and no install or teardown. Its verdict is fail-closed: a package the manifest does not list is treated as unvalidated, never as acceptable. "Signed" is not "kernel-safe"; the manifest decides admission, not the signature.

That diagnostic is wired into a runtime gate, and has been since Phase 2 — this paragraph previously said it was future work, contradicting the opening section of this very file. Virtual-device creation is refused until the experimental driver is explicitly acknowledged, and the audio-class features that reach the known race are default-off behind a second flag (ViiperExperimentalAcknowledged, AllowExperimentalAudioEndpoints; both default false). Both were validated in the VM and are exercised on every run.

What remains genuinely future work is production approval, which stays blocked until an upstream release carries the fix. Our fix for the corruption is merged upstream as usbip-win2 PR #182, alongside the maintainer's own root-cause fix — but no released build contains either, so every published release is still classed experimental and the gate still reports Production approved: no.

Crash dumps from this ecosystem contain kernel memory. Read SECURITY.md before reporting a crash, and never attach a dump to a public issue.

Building

Requirements: Windows, the .NET 8 SDK, and Python 3.10+ only if you also want the packaging step. x64 is the canonical platform; VIIPER is x64-only.

dotnet restore
dotnet build .\DS4WindowsWPF.sln -c Release -p:Platform=x64

Run the test suite:

dotnet test .\DS4WindowsTests\DS4WindowsTests.csproj -c Release -p:Platform=x64

License

Thrum is licensed under the GNU General Public License, version 3 or later (GPL-3.0-or-later). The complete license text is in COPYING.

The corresponding source for any Thrum build is this repository at the release tag that produced it — for the current release, tag v0.9.0-beta.1 (commit 8132946). For a build you made yourself, it is this repository at the commit you built.