Joypad to OBS is a powerful plugin that turns any connected gamepad, joystick, or even custom Arduino devices into a fully functional macro controller for OBS Studio.
This plugin does not provide a visual overlay for your controller. Its purpose is to use your controller as a remote control for OBS, allowing you to bind buttons and axes to actions like switching scenes, muting audio, and controlling media. It provides a physical, tactile way to manage your stream without needing a dedicated macro pad.
- Control OBS with Your Gamepad: Map buttons and analog sticks to a wide range of OBS actions.
- Direct Hardware Access: No intermediate software needed. The plugin communicates directly with any controller recognized by the operating system (e.g., in Windows' "joy.cpl" Game Controllers panel).
- Platform Support: Primarily developed and tested for Windows. macOS and Linux input paths exist, but are currently experimental.
- Broad Device Compatibility:
- Windows Input Backends:
- XInput: Used for Xbox controllers and devices that expose an XInput interface.
- DirectInput: Used for HID/generic controllers and other non-XInput game controllers.
- Auto de-duplication: When both APIs expose the same physical controller, the plugin avoids duplicate entries/actions.
- Custom Hardware: Compatible with Arduino-based devices that appear as a standard joystick, allowing you to use potentiometers, encoders, and sliders to control OBS.
- Windows Input Backends:
- Intuitive UI: A dedicated "Tools" menu dialog to create, edit, and manage all your bindings.
- Dedicated OBS Dock: A compact dock panel with quick profile switching and gamepad listening on/off status/control.
- "Learn" Mode: Simply press a button or move an axis on your controller to assign it to an action.
- Advanced Axis Configuration: Calibrate axis range (Min/Max), set deadzones (Threshold), and invert axis direction for precise control.
- OBS Hotkey to Pause/Resume Controller Listening: Toggle all gamepad input processing on/off from OBS Hotkeys.
- OSD Feedback for Listening State: When the listening toggle hotkey is used, an OSD message shows whether listening is On or Off.
Joypad to OBS supports a comprehensive set of commands to manage your stream:
- Switch Scene: Instantly cut to a specific scene.
- Next Scene and Previous Scene: Cycle through the scene list.
- Toggle Studio Mode: Turn Studio Mode on/off.
- Transition Preview to Program: Trigger transition from Preview to Program.
- Toggle Source Visibility: Toggle visibility (show/hide) for a source.
- Set Source Visibility: Force source visibility to show or hide.
- Toggle Filter: Toggle enabled state of a source filter.
- Set Filter: Force a source filter enabled/disabled state.
- Toggle Source Mute: Toggle mute for an audio source.
- Set Source Mute: Force mute state on/off.
- Set Source Volume: Set a fixed dB value.
- Adjust Source Volume: Apply relative volume step up/down.
- Set Source Volume (Slider): Map axis input to volume percent with configurable gamma curve.
- Media Play/Pause
- Media Restart
- Media Stop
- Toggle Streaming: Start/stop streaming.
- Toggle Recording: Start/stop recording.
- Toggle Virtual Camera: Start/stop virtual camera.
Joypad to OBS provides an OBS Dock for quick control without opening the full settings window.
- Open it from View -> Docks -> Joypad to OBS.
- The dock shows the current Joypad profile in a dropdown.
- Switching profile from the dock updates the active profile immediately.
- The dock updates in real time when profile changes happen from hotkeys or other plugin UI.
- The dock includes a listening status button (on/off icon) to enable or disable controller input processing.
Joypad to OBS allows you to create and manage multiple profiles, each with its own set of bindings. This is useful for different games, scenes, or streaming setups.
- Create: Click the + button to create a new blank profile.
- Rename: Click the ✎ button to rename the current profile.
- Duplicate: Click the ❐ button to create a copy of the current profile.
- Remove: Click the - button to delete the current profile.
- Import/Export: Use the Import and Export buttons to share profiles or back them up as JSON files.
When you create a profile, the plugin automatically registers a corresponding OBS Hotkey. This allows you to switch between profiles using your keyboard or another device (like a Stream Deck).
- Go to File -> Settings -> Hotkeys in OBS.
- Search for "Joypad to OBS".
- You will see entries like
Joypad to OBS: Switch to profile 'MyProfile'. - Assign any key combination you like.
When triggered, the plugin will instantly load the bindings for that profile.
The plugin also registers a global hotkey:
Joypad to OBS: Toggle gamepad listening
Use it to quickly disable/enable all controller-triggered actions without removing bindings.
If OSD notifications are enabled, this hotkey also shows the current listening state (On/Off) on screen.
- OBS Studio: Version 28 or newer.
- Operating System: Windows 10/11 (recommended). macOS and modern Linux distributions are available in experimental mode.
- CMake: 3.28 or newer.
- PowerShell: 7.2+ (required for the local CI simulation script).
- Install the plugin: Download the latest release and copy the files to your OBS Studio plugins directory.
- Windows:
C:\Program Files\obs-studio\obs-plugins\64bit\ - macOS:
~/Library/Application Support/obs-studio/plugins/ - Linux:
~/.config/obs-studio/plugins/
- Windows:
- Open the configuration window: In OBS, go to the Tools menu and select Settings for Joypad to OBS.
- (Optional) Open the quick dock panel: In OBS, go to View -> Docks -> Joypad to OBS.
- Select a Profile: Choose the profile you want to edit from the dropdown menu, or create a new one.
- You can also switch the active profile directly from the dock dropdown.
- Use the dock status icon to quickly enable/disable controller listening.
- Add a new binding:
- Click the "Add Command" button.
- Click "Listen" and press the button or move the axis on your controller that you want to use.
- Select the Action you want to perform (e.g., "Switch Scene", "Set Source Mute").
- Configure the target (e.g., choose the specific scene or source).
- Click OK to save the binding.
- Your controller is now ready to control OBS!
- (Optional) In OBS Settings -> Hotkeys, assign
Joypad to OBS: Toggle gamepad listeningto quickly pause/resume controller input while streaming.
If you want to build the plugin yourself, clone the repository recursively and use CMake presets.
git clone --recursive https://github.com/FabioZumbi12/joypad-to-obs.git
cd joypad-to-obs
cmake --preset windows-x64
cmake --build --preset windows-x64This uses build_x64 and the RelWithDebInfo configuration, matching the project defaults and installer script.
git clone --recursive https://github.com/FabioZumbi12/joypad-to-obs.git
cd joypad-to-obs
cmake -S . -B build_x64
cmake --build build_x64 --config Release --target joypad-to-obsTo run a local build flow close to the windows-2022 GitHub Actions job, use:
pwsh -File .\scripts\ci-local-windows.ps1If you previously configured build_x64 with another Visual Studio generator/version, run with -CleanBuild to avoid CMake generator mismatch errors.
Useful options:
# Simulate fresh runner state (slowest, most faithful)
pwsh -File .\scripts\ci-local-windows.ps1 -CleanBuild -CleanDeps -CleanRelease
# Build only (skip packaging)
pwsh -File .\scripts\ci-local-windows.ps1 -Package:$false
# Enable verbose CI-like debug logs
pwsh -File .\scripts\ci-local-windows.ps1 -DebugLogsThis plugin is released under the GPLv2 license.
The source code, README text, and the repository banner in img/banner.svg are maintained as project-authored assets for this plugin repository.
If third-party assets, screenshots, icons, store text, or promotional images are used in future releases or plugin-directory submissions, they should only be published when the project has the required rights, attribution, and any policy-required disclosure.
If Joypad to OBS helps your workflow, consider supporting the project or following my work here:
https://linktr.ee/FabioZumbi12