SuperCollider’s HID class lets users connect many types of game controllers without additional software installations. While establishing a connection between a human input device and SuperCollider is easy, decoding the mapping system requires time and effort. A user needs to press a button in the controller, monitor the ID number assigned to the specific button, and then document the result for further use. The good news is that once a user figures out and shares the mapping structure of a device, there is no need to repeat the discovery procedure until the next major OS update.
The chart below shows the control surface-to-SuperCollider mapping of four game controllers: DualShock 4 for PlayStation 4, DualSense for PlayStation 5, Logitech FS310, and Xbox Wireless Controller. It lists elements (ID numbers corresponding to a specific control surface in a device) and their value range for HIDFunc.element command. With the element numbers and ranges below, one can map the incoming data from a controller to various parameters available in SuperCollider.
Element Numbers and Range of Game Controllers
Sony DualShock (PS4) | Sony DualSense (PS5) | Logitech FA310 Mode D | Microsoft Xbox | |
Bluetooth | Bluetooth | USB | Bluetooth | |
ID (1356, 2508) | ID (1356, 3302) | ID (1133,49686) | ID (1118, 765) | |
Control Surface [sony | xbox] | Element#, (value) | Element#, (value) | Element#, (value) | Element#, (value) |
Square | X | 0, (0 or 1) | 0, (0 or 1) | 0, (0 or 1) | 13, (0 or 1) |
X | A | 1, (0 or 1) | 1, (0 or 1) | 1, (0 or 1) | 10, (0 or 1) |
O | B | 2, (0 or 1) | 2, (0 or 1) | 2, (0 or 1) | 11, (0 or 1) |
Triangle | Y | 3, (0 or 1) | 3, (0 or 1) | 3, (0 or 1) | 14, (0 or 1) |
L1 | LB | 4, (0 or 1) | 4, (0 or 1) | 4, (0 or 1) | 16, (0 or 1) |
R1 | RB | 5, (0 or 1) | 5, (0 or 1) | 5, (0 or 1) | 17, (0 or 1) |
L2 | LT button | 6, (0 or 1) | 6, (0 or 1) | 6, (0 or 1) | not found yet |
R2 | RT button | 7, (0 or 1) | 7, (0 or 1) | 7, (0 or 1) | not found yet |
Share | Back | 8, (0 or 1) | 8, (0 or 1) | 8, (0 or 1) | 25, (0 or 1) |
Options | Start | 9, (0 or 1) | 9, (0 or 1) | 9, (0 or 1) | 21, (0 or 1) |
L3 | LSB button | 10, (0 or 1) | 10, (0 or 1) | 10, (0 or 1) | not found yet |
R3 | RSB button | 11, (0 or 1) | 11, (0 or 1) | 11, (0 or 1) | not found yet |
Logo | 12, (0 or 1) | 12, (0 or 1) | not found yet | not found yet |
Trackpad button | 13, (0 or 1) | 13, (0 or 1) | N/A | N/A |
L3 | LSB x-axis | 14, (0 to 255) | 14, (0 to 255) | 13, (0 to 255) | 0, (0-65535) |
L3 | LSB y-axis | 15, (0 to 255) | 15, (0 to 255) | 14, (0 to 255) | 1, (0-65535) |
R3 | RSB x-axis | 16, (0 to 255) | 16, (0 to 255) | 15, (0 to 255) | 2, (0-65535) |
R3 | RSB y-axis | 17, (0 to 255) | 17, (0 to 255) | 16, (0 to 255) | 3, (0-65535) |
L2 | LT continuous | 19, (0 to 255) | 19, (0 to 255) | not found yet | 26, (0-1023) |
R2 | RT continuous | 20, (0 to 255) | 20, (0 to 255) | not found yet | 27, (0-1023) |
up | 18, (0) | 18, (0) | 17, (0) | 28, (1) |
up+right | 18, (1) | 18, (1) | 17, (1) | 28, (2) |
right | 18, (2) | 18, (2) | 17, (2) | 28, (3) |
right+down | 18, (3) | 18, (3) | 17, (3) | 28, (4) |
down | 18, (4) | 18, (4) | 17, (4) | 28, (5) |
down+left | 18, (5) | 18, (5) | 17, (5) | 28, (6) |
left | 18, (6) | 18, (6) | 17, (6) | 28, (7) |
left+up | 18, (7) | 18, (7) | 17, (7) | 28, (8) |
release | 18, (8) | 18, (8) | 17, (8) | 28, (0) |
Analysis of Element Numbers and Range
The number of available control surfaces, as well as their ranges, varies between the brands. However, all game controllers have three types of input methods.
- Button: sends 1 when pressed and 0 when released.
- Directional Pad: assigns eight integers for eight directions and one integer for the release/unpressed state. The release state is mapped to value 8 in the Sony and Logitech controllers, while it is assigned to 0 in the Xbox controller.
- Continuous Control: sends a range of numbers like a slider or a knob in a MIDI controller. All but the Xbox controller sends data ranging from 0-255. The Xbox controller has two types of ranges (0-65535 and 0-1023).
More expensive controllers have more features, such as motion sensors and microphone input, but the HID class does not detect them. The number of game controller features available for HID seems to depend on the hosting OS’s version. In 2018, HID received DualShock’s motion sensor and trackpad data when connected to a Macintosh with a USB cable (source). After a few OSX updates, I could not replicate the result in 2025. It is possible that additional input methods could be detected if an external app or extension is installed. I did not test the possibility as my goal is to avoid additional technical steps.
Demo SuperCollider Patches
Readers can test, study, and modify the controller mapping structure with the .scd files provided in the link above. All four files, one for each model of the controller, have the same parts: 1. Controller initialization 2. Connection tester 3. Controller-to-sound example. The coding style is based on the example section of the HIDFunc manual.
The Controller initialization section consists of arrays and functions that connect and monitor signals from the game controller. The most important commands in this section are HID.findAvailable, HID.open, and HIDFunc.element. These commands detect the available devices, connect the specific device with the device’s unique ID number, and determine what SuperCollider should do when a control surface is triggered. The rest are functions built to use those three commands efficiently. The users must evaluate the codes inside the first parenthesis labeled //1. Controller Initializations to make the second section of the codes work.
After the initialization, evaluate the codes inside the second parenthesis labeled //2. Test the Controller. It is important to evaluate one line of code at a time for better testing. When a ~whichsurface(element #) function is evaluated, an array containing an element number, control surface name, and value will appear on the post screen. For example, after establishing a connection with a DualSene controller using HID_DualSense_Demo.scd, evaluate the line ~whichsurface.(3). It will activate the triangle button of the controller. Pressing the triangle button will post [ 0, Triangle, 1 ], and releasing the button will post [ 3, Trianle, 0 ] on the Post window. Press command+period or select Menu-> Language-> Stop to stop receiving the messages from the controller.
Note that arguments (|…args|) inside the HIDFunc element receive an array of numbers from the connected controller. The first number in the array, args[0], receives normalized data ranging from 0.0 to 1.0 as a float. The second number, args[1], receives raw data ranging from 0 to any number as an integer. The demo files use the integer, but users can use the float argument interchangeably.
The last group of commands under //3. Audio Example maps the controller to a SynthDef’s parameter. The codes inside HIDFunc.element maps a button to change the volume of white noise and a continuous controller to change the panning. Modify the numbers inside the brackets [ ] at the end of the HIDFunc.element( ) to map different buttons and continuous controllers. Note that the method .linlin is used to map the range of 0 to 255 or 65535 to -1.0 to 1.0 in this example code.
Summary and Application
I share the mapping of four controllers so that others do not have to repeat the procedure and move faster to the creative phase. My previous sharing of the game controller mapping was in 2018, and it is available as a published document in The Journal Emille. The article is now outdated and only applicable to DualShock. The current findings discussed here also have limitations: the mappings were tested in SuperCollider 13.0 running in Mac OSX Sequoia only. I was not successful in connecting the controllers to SuperCollider on Windows. I also did not figure out the mappings for Max or other programs.
Once connected via HID in SuperCollider, a game controller becomes an expressive instrument for laptop performance despite the above limitations. Performers can incorporate years, if not decades, of gaming muscle memories to play music. For demonstration, the links below are my two compositions for a game controller quartet. Interested music technologists can download SuperCollider patches and scores from the links below to play the music using the game controllers analyzed in this article. Previous experience in SuperCollider is not needed to play the piece.
