feat(macos): add gamepad support using libvirtualhid

CMakeLists.txt

@@ -9,9 +9,18 @@ project(Sunshine VERSION 0.0.0
         DESCRIPTION "Self-hosted game stream host for Moonlight"
         HOMEPAGE_URL "https://app.lizardbyte.dev/Sunshine")
 
-# Minimum separately installed Virtual HID Driver version supported by this build.
+# Minimum separately installed Virtual HID Broker version supported by this build.
 set(LIBVIRTUALHID_MINIMUM_VERSION "2026.914.1218.10")
 list(APPEND SUNSHINE_DEFINITIONS LIBVIRTUALHID_MINIMUM_VERSION="${LIBVIRTUALHID_MINIMUM_VERSION}")
+if(APPLE)
+    # macOS bundle versions have three components; the Windows driver uses four.
+    if(LIBVIRTUALHID_MINIMUM_VERSION MATCHES "^([0-9]+\\.[0-9]+\\.[0-9]+)\\.[0-9]+$")
+        set(LIBVIRTUALHID_MACOS_MINIMUM_VERSION "${CMAKE_MATCH_1}")
+    else()
+        set(LIBVIRTUALHID_MACOS_MINIMUM_VERSION "${LIBVIRTUALHID_MINIMUM_VERSION}")
+    endif()
+    list(APPEND SUNSHINE_DEFINITIONS LIBVIRTUALHID_MACOS_MINIMUM_VERSION="${LIBVIRTUALHID_MACOS_MINIMUM_VERSION}")
+endif()
 
 set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)

README.md

@@ -56,55 +56,57 @@ LizardByte has the full documentation hosted on [Read the Docs](https://docs.liz
         <td>Generic</td>
         <td>🟡<sup>1</sup></td>
         <td>✅</td>
-        <td>❌</td>
-        <td>✅</td>
+        <td>✅<sup>2</sup></td>
+        <td>✅<sup>3</sup></td>
     </tr>
     <tr>
         <td>DualShock / DS4 (PlayStation 4)</td>
         <td>🟡<sup>1</sup></td>
         <td>✅</td>
-        <td>❌</td>
-        <td>✅</td>
+        <td>✅<sup>2</sup></td>
+        <td>✅<sup>3</sup></td>
     </tr>
     <tr>
         <td>DualSense / DS5 (PlayStation 5)</td>
         <td>🟡<sup>1</sup></td>
         <td>✅</td>
-        <td>❌</td>
-        <td>✅</td>
+        <td>✅<sup>2</sup></td>
+        <td>✅<sup>3</sup></td>
     </tr>
     <tr>
         <td>Nintendo Switch Pro</td>
         <td>🟡<sup>1</sup></td>
         <td>✅</td>
-        <td>❌</td>
-        <td>✅</td>
+        <td>✅<sup>2</sup></td>
+        <td>✅<sup>3</sup></td>
     </tr>
     <tr>
         <td>Xbox 360</td>
         <td>🟡<sup>1</sup></td>
         <td>✅</td>
-        <td>❌</td>
-        <td>✅</td>
+        <td>✅<sup>2</sup></td>
+        <td>✅<sup>3</sup></td>
     </tr>
     <tr>
         <td>Xbox One</td>
         <td>🟡<sup>1</sup></td>
         <td>✅</td>
-        <td>❌</td>
-        <td>✅</td>
+        <td>✅<sup>2</sup></td>
+        <td>✅<sup>3</sup></td>
     </tr>
     <tr>
         <td>Xbox Series</td>
         <td>🟡<sup>1</sup></td>
         <td>✅</td>
-        <td>❌</td>
-        <td>✅</td>
+        <td>✅<sup>2</sup></td>
+        <td>✅<sup>3</sup></td>
     </tr>
 </table>
 
 > [!NOTE]
 > <sup>1</sup> Missing motion, touchpad input, battery state, RGB LEDs, adaptive triggers, and raw HID output reports.
+> <sup>2</sup> Requires the separately installed and licensed Virtual HID Broker.
+> <sup>3</sup> All profiles are available through the separately installed and licensed Virtual HID Broker. Xbox 360 and DualShock 4 can also use ViGEmBus.
 
 <table>
     <caption id="encoding_api">Encoding API</caption>

cmake/packaging/common.cmake

@@ -16,9 +16,17 @@ set(CPACK_PACKAGE_ICON ${PROJECT_SOURCE_DIR}/sunshine.png)
 set(CPACK_PACKAGE_FILE_NAME "${CMAKE_PROJECT_NAME}")
 set(CPACK_STRIP_FILES YES)
 
+# Keep macOS assets in the Runtime component so app assets are installed
+# before macos.cmake signs the finished bundle.
+set(_sunshine_common_asset_component)
+if(APPLE)
+    set(_sunshine_common_asset_component COMPONENT Runtime)
+endif()
+
 # install common assets
 install(DIRECTORY "${SUNSHINE_SOURCE_ASSETS_DIR}/common/assets/"
         DESTINATION "${SUNSHINE_ASSETS_DIR}"
+        ${_sunshine_common_asset_component}
         PATTERN "web" EXCLUDE)
 # copy assets to build directory, for running without install
 file(GLOB_RECURSE ALL_ASSETS
@@ -31,7 +39,8 @@ endforeach()
 
 # install built vite assets
 install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/assets/web"
-        DESTINATION "${SUNSHINE_ASSETS_DIR}")
+        DESTINATION "${SUNSHINE_ASSETS_DIR}"
+        ${_sunshine_common_asset_component})
 
 # platform specific packaging
 if(WIN32)

docs/configuration.md

@@ -319,12 +319,12 @@ supported on the current platform.
     <tr>
         <td>Description</td>
         <td colspan="2">
-            Controls which virtual gamepad drivers Sunshine may use. The Web UI and startup notification continue to
-            request a choice while this option is not set. If Sunshine detects an active Virtual HID Driver license,
-            it automatically sets this option to `all` when it is missing.
+            Controls which virtual gamepad backend Sunshine may use on Windows and macOS. On Windows, the Web UI and
+            startup notification request a choice while this option is not set. If Sunshine detects an active Virtual
+            HID Broker license on Windows, it automatically sets this option to `all` when it is missing.
             @warning{ViGEmBus has limited gamepad features, supports only Xbox 360 and DualShock 4 emulation, and has
-            reached end of life. Selecting `vigembus` also suppresses Virtual HID Driver startup notifications.}
-            @note{This option applies only to Windows.}
+            reached end of life. Selecting `vigembus` also suppresses Virtual HID Broker startup notifications.}
+            @note{`all` and `vigembus` apply only to Windows. On macOS, an unset value uses Virtual HID Broker.}
         </td>
     </tr>
     <tr>
@@ -340,17 +340,21 @@ supported on the current platform.
             @endcode</td>
     </tr>
     <tr>
-        <td rowspan="3">Choices</td>
+        <td rowspan="4">Choices</td>
         <td>all</td>
-        <td>Prefer Virtual HID Driver when it is available and licensed, with ViGEmBus as a limited fallback.</td>
+        <td>Windows only: prefer Virtual HID Broker when it is available and licensed, with ViGEmBus as a limited fallback.</td>
     </tr>
     <tr>
         <td>virtualhid</td>
-        <td>Use only Virtual HID Driver. An active paid license is required; ViGEmBus fallback is disabled.</td>
+        <td>Use Virtual HID Broker for gamepads. An active paid license is required; Windows ViGEmBus fallback is disabled.</td>
     </tr>
     <tr>
         <td>vigembus</td>
-        <td>Use only ViGEmBus for gamepads and hide Virtual HID Driver status and licensing details.</td>
+        <td>Windows only: use ViGEmBus for gamepads and hide Virtual HID Broker status and licensing details.</td>
+    </tr>
+    <tr>
+        <td>none</td>
+        <td>Disable virtual gamepads on Windows and macOS without changing keyboard or mouse input. Suppress broker and driver choice notices.</td>
     </tr>
 </table>
 
@@ -360,8 +364,9 @@ supported on the current platform.
     <tr>
         <td>Description</td>
         <td colspan="2">
-            The type of gamepad to emulate on the host.
-            @note{This option applies to FreeBSD, Linux, and Windows.}
+            The type of gamepad to emulate on the host. Automatic selection uses the controller type
+            reported by the client. If the type is unknown, Sunshine can select a PlayStation-style
+            controller from reported motion or touchpad support; otherwise it uses an Xbox-style controller.
             @note{When gamepad_driver is `vigembus` on Windows, only auto, x360, and ds4 are available.}
         </td>
     </tr>

docs/getting_started.md

@@ -400,7 +400,19 @@ brew uninstall sunshine
 ### macOS
 
 > [!IMPORTANT]
-> Sunshine on macOS is experimental. Gamepads do not work.
+> Virtual gamepads require the separately installed, licensed
+> [Virtual HID Broker](https://github.com/LizardByte/libvirtualhid/releases/latest).
+
+To use gamepads, download the macOS universal libvirtualhid DMG from the link above. Open it and run
+**Install libvirtualhid.command** to install Virtual HID Broker. In **System Settings > Privacy & Security >
+Device Control and Data Access**, add `/Applications/VirtualHIDBroker.app` and enable it. Restart the broker if
+you changed this permission with `sudo launchctl kickstart -k system/dev.lizardbyte.app.libvirtualhid`.
+Activate the machine license in Sunshine’s
+**Troubleshooting > Virtual HID Broker License** section. In **Configuration > Input**, turn on **Enable Gamepad Input**
+and choose the emulated gamepad. The Gamepad Backend setting can be set to **None** to disable gamepads without affecting
+keyboard or mouse input. Sunshine’s menu bar **Virtual HID Broker** submenu shows the license status and links
+for license management and downloads. Sunshine’s DMG does not contain the broker. Keyboard and mouse input use the
+standard macOS synthetic-input permission path.
 
 #### DMG
 
@@ -569,15 +581,15 @@ and enter its device name in the [audio_sink](configuration.md#audio_sink) field
 
 ### Windows
 Sunshine supports two virtual gamepad backends on Windows. You can install the
-[Virtual HID Driver](https://github.com/LizardByte/libvirtualhid/releases/latest) separately as an optional paid upgrade
-for a driver-backed Raw Input keyboard and mouse plus full virtual gamepad support. ViGEmBus remains available as a
-limited alternative for Xbox 360 and DualShock 4 gamepads, but it has reached end of life.
+[Virtual HID Broker](https://github.com/LizardByte/libvirtualhid/releases/latest) separately as an optional paid upgrade.
+Its Windows package includes a broker service and user-mode driver for a Raw Input keyboard and mouse plus full virtual
+gamepad support. ViGEmBus remains available as a limited alternative for Xbox 360 and DualShock 4 gamepads, but it has reached end of life.
 
-When Virtual HID Driver is used, Sunshine requires version `2026.914.1218.10` or newer.
+When Virtual HID Broker is used, Sunshine requires libvirtualhid version `2026.914.1218.10` or newer.
 
-Compared with the ViGEmBus fallback, Virtual HID Driver can create Xbox One, Xbox Series, DualSense, Nintendo Switch
+Compared with the ViGEmBus fallback, Virtual HID Broker can create Xbox One, Xbox Series, DualSense, Nintendo Switch
 Pro, and Generic gamepads in addition to Xbox 360 and DualShock 4. It can also expose controller-specific features such
-as motion, touchpads, LEDs, and adaptive triggers when supported. Virtual HID Driver is actively developed and
+as motion, touchpads, LEDs, and adaptive triggers when supported. Virtual HID Broker is actively developed and
 supported by the LizardByte team.
 
 With a compatible driver and active license, normal key transitions are exposed through a real HID keyboard so
@@ -589,15 +601,16 @@ Relative mouse movement, buttons, and scrolling are exposed as a real HID
 mouse so applications using Raw Input can receive them. Absolute mouse positioning continues to use Windows input
 injection. When the driver-backed mouse cannot be created, libvirtualhid retains its legacy SendInput fallback.
 
-The Virtual HID Driver requires an active paid machine license for driver-backed devices, including gamepads and the Raw
+The Virtual HID Broker requires an active paid machine license for driver-backed devices, including gamepads and the Raw
 Input keyboard and mouse. Sunshine shows the current license status and actions on the Web UI Troubleshooting page and
-in the **Virtual HID Driver** system tray submenu. In **Configuration > Input**, choose whether Sunshine may use **All
-Available Drivers**, only **Virtual HID Driver**, or only **ViGEmBus**. Sunshine continues to show the selection prompt
-until this setting is saved. If an active Virtual HID Driver license is already present, Sunshine selects **All Available
-Drivers** automatically. That policy prefers Virtual HID Driver. When its license is not valid, Sunshine falls back to
+in the **Virtual HID Broker** system tray submenu. In **Configuration > Input**, choose whether Sunshine may use **All
+Available Drivers**, only **Virtual HID Broker**, or only **ViGEmBus**. Sunshine continues to show the selection prompt
+until this setting is saved. If an active Virtual HID Broker license is already present, Sunshine selects **All Available
+Drivers** automatically. That policy prefers Virtual HID Broker. When its license is not valid, Sunshine falls back to
 ViGEmBus for Xbox 360 and DualShock 4 gamepads and to SendInput for keyboard and mouse. Selecting only **ViGEmBus**
-suppresses Virtual HID Driver startup notifications and limits the available emulated gamepads to Xbox 360 and
-DualShock 4. Sunshine recreates the shared keyboard and mouse after a successful license action, so switching between
+suppresses Virtual HID Broker startup notifications and limits the available emulated gamepads to Xbox 360 and
+DualShock 4. **None** disables all virtual gamepads and their startup notices without affecting keyboard or mouse
+input. Sunshine recreates the shared keyboard and mouse after a successful license action, so switching between
 the HID and SendInput paths does not require restarting Sunshine.
 
 After installing or updating virtual input drivers, it is recommended to restart your computer.

docs/troubleshooting.md

@@ -306,6 +306,18 @@ Some users have reported stuttering issues when streaming games running within G
 
 ## macOS
 
+### No gamepad detected
+Confirm **Enable Gamepad Input** is on under **Configuration > Input**. Install
+[Virtual HID Broker](https://github.com/LizardByte/libvirtualhid/releases/latest) separately from Sunshine,
+using the macOS installer in its universal DMG. Confirm that `/Applications/VirtualHIDBroker.app` is allowed in
+**System Settings > Privacy & Security > Device Control and Data Access**, and activate a machine license under
+**Troubleshooting > Virtual HID Broker License** in Sunshine. The menu bar **Virtual HID Broker** submenu also
+shows license status and links for license management and downloads. If the broker or license is unavailable, the
+Troubleshooting page shows the broker response. Sunshine can show a startup notice when gamepad input is enabled
+and the broker or license is unavailable. Choose **None** under **Configuration > Input > Gamepad Backend** to disable
+virtual gamepads and that notice without affecting keyboard or mouse input. Reconnect the Moonlight session after choosing
+a different emulated gamepad profile.
+
 ### Dynamic session lookup failed
 If you get this error:
 
@@ -321,46 +333,47 @@ launchctl load -w /Library/LaunchAgents/org.freedesktop.dbus-session.plist
 
 ### No gamepad detected
 Sunshine supports two virtual gamepad backends on Windows. You can install the
-[Virtual HID Driver](https://github.com/LizardByte/libvirtualhid/releases/latest) separately as an optional paid upgrade
-for a driver-backed Raw Input keyboard and mouse plus full virtual gamepad support. ViGEmBus is a limited alternative
-for Xbox 360 and DualShock 4 support that has reached end of life. If you use the
+[Virtual HID Broker](https://github.com/LizardByte/libvirtualhid/releases/latest) separately as an optional paid upgrade.
+Its Windows package includes a broker service and user-mode driver for a Raw Input keyboard and mouse plus full virtual
+gamepad support. ViGEmBus is a limited alternative for Xbox 360 and DualShock 4 support that has reached end of life. If you use the
 [ViGEmBus fallback](https://github.com/nefarius/ViGEmBus/releases/latest), you must use version 1.17 or newer.
 
-When Virtual HID Driver is used, Sunshine requires version `2026.914.1218.10` or newer.
+When Virtual HID Broker is used, Sunshine requires libvirtualhid version `2026.914.1218.10` or newer.
 
-Virtual HID Driver adds Xbox One, Xbox Series, DualSense, Nintendo Switch Pro, and Generic gamepads, plus advanced
+Virtual HID Broker adds Xbox One, Xbox Series, DualSense, Nintendo Switch Pro, and Generic gamepads, plus advanced
 controller features such as motion, touchpads, LEDs, and adaptive triggers when supported. Unlike the discontinued
-ViGEmBus project, Virtual HID Driver is actively developed and supported by the LizardByte team.
+ViGEmBus project, Virtual HID Broker is actively developed and supported by the LizardByte team.
 
-An active paid Virtual HID Driver machine license is required before Sunshine can create driver-backed libvirtualhid
+An active paid Virtual HID Broker machine license is required before Sunshine can create driver-backed libvirtualhid
 devices, including gamepads and the Raw Input keyboard and mouse. Use the message on the Web UI home page, the startup
-tray notification, or **Get/Manage License** in the **Virtual HID Driver** tray submenu to open the license section on
-the Troubleshooting page. In **Configuration > Input**, select **All Available Drivers**, only **Virtual HID Driver**, or
+tray notification, or **Get/Manage License** in the **Virtual HID Broker** tray submenu to open the license section on
+the Troubleshooting page. In **Configuration > Input**, select **All Available Drivers**, only **Virtual HID Broker**, or
 only **ViGEmBus**. Sunshine keeps prompting until this setting is saved, but automatically selects **All Available
-Drivers** when it detects an existing active Virtual HID Driver license. Whenever the Virtual HID Driver license is not
+Drivers** when it detects an existing active Virtual HID Broker license. Whenever the Virtual HID Broker license is not
 valid, **All Available Drivers** falls back to a compatible ViGEmBus installation for Xbox 360 and DualShock 4 gamepads
-and to SendInput for keyboard and mouse. Selecting only **ViGEmBus** suppresses Virtual HID Driver startup notifications
-and hides its status and license details from the Troubleshooting page.
+and to SendInput for keyboard and mouse. Selecting only **ViGEmBus** suppresses Virtual HID Broker startup notifications
+and hides its status and license details from the Troubleshooting page. Selecting **None** disables all virtual
+gamepads and suppresses broker and driver choice notices without affecting keyboard or mouse input.
 
 After installation, it is recommended to restart your computer.
 
 ### Games do not detect keyboard input
-With a compatible Virtual HID Driver and active license, Sunshine sends normal key transitions through a real HID
+With a compatible Virtual HID Broker and active license, Sunshine sends normal key transitions through a real HID
 keyboard so games using Raw Input can receive them. Unicode text input and keys outside the supported HID keyboard
 page continue to use Windows input injection. When the driver-backed keyboard cannot be created because the driver,
 broker, or license is unavailable, libvirtualhid falls back to SendInput.
 
-Check the Virtual HID Driver version and license sections on the Web UI Troubleshooting page. Sunshine recreates the
+Check the libvirtualhid driver version and Virtual HID Broker license on the Web UI Troubleshooting page. Sunshine recreates the
 shared keyboard and mouse after a successful license activation, validation, or deactivation, so you do not need to
 restart Sunshine merely to switch between the HID and SendInput paths.
 
 ### Games do not detect mouse input
-With a compatible Virtual HID Driver and active license, Sunshine sends relative mouse movement, buttons, and scrolling
+With a compatible Virtual HID Broker and active license, Sunshine sends relative mouse movement, buttons, and scrolling
 through a real HID device so games using Raw Input can receive them. Absolute positioning still uses Windows input
 injection. When the driver-backed mouse cannot be created, libvirtualhid falls back to SendInput; the Windows cursor may
 still move even though a game that listens only for Raw Input receives nothing.
 
-Check the Virtual HID Driver version and license sections on the Web UI Troubleshooting page even when controller input
+Check the libvirtualhid driver version and Virtual HID Broker license on the Web UI Troubleshooting page even when controller input
 is disabled. The same live refresh used by the keyboard path also switches the mouse between HID and SendInput without
 requiring a Sunshine restart.