supercollider/hidapi

A Simple library for communicating with USB and Bluetooth HID devices on Linux, Mac, and Windows.

SuperCollider

SuperCollider is a platform for audio synthesis and algorithmic composition, used by musicians, artists, and researchers working with sound. It consists of:

• scsynth, a real-time audio server with hundreds of unit generators ("UGens") for audio analysis, synthesis, and processing
• supernova, an alternative server to scsynth with support for parallel DSP on multi-core processors
• sclang, an interpreted programming language that controls the servers
• scide, an editing environment for sclang with an integrated help system

sclang comes with its own package manager, called Quarks. scsynth and supernova both support third-party plugins via C and C++ APIs.

SuperCollider is written in C++17 using several third-party libraries, including Qt and Boost. It can be used on Windows, macOS, a variety of Linux and BSD distributions, Raspberry Pi, and BeagleBone Black.

Install

macOS and Windows builds for stable releases are provided at our downloads page. See the macOS README and Windows README for instructions on usage, and how to build SC yourself.

To get the latest stable version, Linux users will need to build SuperCollider themselves. See the Linux README for instructions.

See the Raspberry Pi and BeagleBone Black READMEs for instructions on building on those platforms.

Platform support

SuperCollider is tested with:

• Windows 10 (32- and 64-bit) and MSVC 2019
• macOS 12 and Xcode 13.4.1
• Ubuntu 22.04 and gcc 12

SuperCollider is known to support these platforms:

• Windows Vista, 7, 8, 10, 11
• macOS 10.14-12.x
• Ubuntu 18.04-22.04

We also provide a legacy macOS binary for macOS 10.11 and above using Qt 5.9.

SuperCollider has guaranteed support for:

• Windows 10, 11
• MSVC 2017, 2019
• macOS 11, 12
• Xcode 11-13
• Debian >= 11
• Ubuntu 20.04, 22.04
• Fedora 36, 37
• Arch Linux
• gcc >= 9
• clang >= 11
• Qt >= 5.11

For more information on platform support guarantees, see the project Wiki.

Learn

The official docs can be viewed in the SuperCollider IDE's built-in documentation browser. You can also view them online at doc.sccode.org.

We recommend the following resources for learning SC:

• A Gentle Introduction to SuperCollider, a free ebook by Bruno Ruviaro
• Eli Fieldsteel's video tutorials
• Getting Started with SC
• Nick Collins' SC tutorial
• SCCode.org, a repository of user-submitted examples

Discuss

You can join our forum at scsynth.org or our Slack channel.

You can also view the archives for the old mailing lists at sc-users and sc-dev.

Please read our adopted code of conduct, which applies to all the above communities.

Contribute

Development of SuperCollider happens here on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving SuperCollider.

Code of Conduct

Please read our adopted code of conduct before contributing, so that you can understand what actions will and will not be tolerated.

Contributing Guide

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.

Good First Issues

To help you get your feet wet and get you familiar with our contribution process, we have a list of good first issues that contain bugs which have a relatively limited scope. This is a great place to get started. You can also ask on our developer's mailing list, on Slack, or on the forum.

Requests for Comment

SuperCollider uses a Requests for Comment (RFC) system to propose, design, and discuss 'big' changes. Submitting a new RFC or discussing an existing one is a great way to get involved, especially if you are looking for a way to contribute that doesn't involve writing code or using a terminal. You can learn more at the RFC repository.

License

SuperCollider is free software available under Version 3 the GNU General Public License. See COPYING for details.

hidapi's Issues

New release + question on difference to libusb/hidapi

I'm in the process of updating SuperCollider for pkgsrc.

The updated version requires this library. The latest tag / released version is from 2011. Can you please tag a new release?

(Follow-up question: Do you intend to / have already merged back to https://github.com/libusb/hidapi which is the new upstream for hidapi? (ie: is this hidapi a requirement, or can the libusb one be used, and if not, what is the difference?))

Thanks.

Use upstream hidapi 0.14.0 with hid_get_report_descriptor on all platforms

This hidapi version was forked by @tonyrog from a very old version of signal11/hidapi. It adds support for reading and parsing HID Report Descriptors for Linux/BSD (and adds hidapi2osc).
Since version 0.14.0 upstream libusb/hidapi has a function hid_get_report_descriptor which returns the HID Report Descriptor on all operating systems including Windows and macOS.
This means that you could use the code

hidapi/hidapi_parser/hidapi_parser.c

Lines 1150 to 1163 in 7affd87

	#ifdef LINUX_FREEBSD
	unsigned char descr_buf[HIDAPI_MAX_DESCRIPTOR_SIZE];
	int res;
	res = hid_get_report_descriptor( devd, descr_buf, HIDAPI_MAX_DESCRIPTOR_SIZE );
	if (res < 0){
	printf("Unable to read report descriptor\n");
	return NULL;
	} else {
	desc = (struct hid_dev_desc *) malloc( sizeof( struct hid_dev_desc ) );
	desc->device = devd;
	hid_parse_report_descriptor( descr_buf, res, desc );
	return desc;
	}
	#endif

on all operating systems, with upstream libusb/hidapi 0.14.0 https://github.com/libusb/hidapi/releases/tag/hidapi-0.14.0

And you get of cause all the other features, which were added to hidapi since the time of the fork, like support for Feature Reports, HID over Bluetooth LE, I2C and SPI, and a standard CMake build setup.

usage tables are inconsistent and incomplete

This repository currently includes some custom YAML files to store the usage metadata for HID. This is how you get useful descriptions of the control data coming from your devices. The report just has numbers, this metadata has the names. There's a "Digitizer" page with "Touchscreen" and "X" and "Y". The semantics are in the HID report structure (how many "X" and "Y" axes does a touchscreen send?)

SuperCollider reads these files as-needed in HIDUsage.getUsageDescription, but they're an incomplete and inconsistent representation of the official tables. I just wrote some tests for the HIDUsage class and discovered that the usage/page names in SuperCollider's version are underscored some places, truncated in others -- there's no consistent formatting scheme. In addition, the usage tables are incomplete, and it looks like they were last updated around 2016. They were likely built by hand -- the committer is not a Github user or I'd @ them to ask.

The official doc -- which anyone developing HID code will find super useful for its detailed descriptions of the usage data -- includes a JSON attachment that has all the data, updated annually. I think SuperCollider ought to just use that.