{"id":18824619,"url":"https://github.com/ematech/opencontourshuttle","last_synced_at":"2025-04-14T01:31:14.998Z","repository":{"id":148464936,"uuid":"345841190","full_name":"EMATech/OpenContourShuttle","owner":"EMATech","description":"A multiplatform userland driver for Contour Shuttle Devices","archived":false,"fork":false,"pushed_at":"2023-11-08T06:23:53.000Z","size":3883,"stargazers_count":18,"open_issues_count":0,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-27T15:47:52.636Z","etag":null,"topics":["contour","hid","hidapi","material-design","pyside6","python","python3","qt6-gui","shuttleprov2","shuttlexpress","usb-hid","userland","windows"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EMATech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":"rdoursenaud","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2021-03-09T01:03:24.000Z","updated_at":"2024-11-15T19:56:19.000Z","dependencies_parsed_at":"2023-08-07T21:06:44.108Z","dependency_job_id":"3d4e6a24-9b6e-478f-a363-48ad9309811e","html_url":"https://github.com/EMATech/OpenContourShuttle","commit_stats":null,"previous_names":["ematech/opencontourshuttle"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EMATech%2FOpenContourShuttle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EMATech%2FOpenContourShuttle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EMATech%2FOpenContourShuttle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EMATech%2FOpenContourShuttle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EMATech","download_url":"https://codeload.github.com/EMATech/OpenContourShuttle/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248807518,"owners_count":21164696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["contour","hid","hidapi","material-design","pyside6","python","python3","qt6-gui","shuttleprov2","shuttlexpress","usb-hid","userland","windows"],"created_at":"2024-11-08T00:56:57.584Z","updated_at":"2025-04-14T01:31:14.437Z","avatar_url":"https://github.com/EMATech.png","language":"Python","readme":"Open Contour Shuttle\n====================\n\nA multiplatform userland driver, configuration editor, event manager \u0026 generator for Contour ShuttleXpress \u0026 ShuttlePRO v2.\n\n![GUI prototype](GUIprototype.png)\n\n\nStatus\n------\n\nProof of concept!\n\nWelcoming any contributions, especially:\n\n- comments\n- tests: particularly on platforms other than Microsoft Windows or versions earlier than 11\n- implement currently unsupported hardware:\n    - ShuttlePRO v2\n\nFeatures / TODO list\n--------------------\n\n- [ ] Device support\n    - [x] ShuttleXpress\n    - [ ] **(WIP)** ShuttlePRO v2\n\n- [ ] Platform support\n    - [x] Microsoft Windows\n        - [x] GUI\n        - [x] Tray icon shortcut to GUI\n        - [ ] Run as a [windows service](http://thepythoncorner.com/dev/how-to-create-a-windows-service-in-python/)?\n        - [ ] Add configurator to control panel?\n    - [x] Apple Mac OS X\n    - [ ] GNU/Linux\n    - [ ] Android?\n    - [ ] Apple iOS/iPadOS?\n\n- [x] State management engine\n    - [x] Find and open device\n        - [x] USB HID via hidapi\n    - [x] Decode raw values\n        - [x] Observer pattern Events\n    - [ ] **(WIP)** Central broker\n    - [ ] Responders plugin system\n\n\n- [ ] **(WIP)** GUI\n    - [x] Qt6 via PySide6\n    - [X] Main window\n    - [x] Icon\n    - [x] Title\n    - [x] System tray icon\n    - [x] Display state graphically\n    - [x] Status\n        - [x] Connection\n        - [x] Events\n    - [x] ~~Menu?~~\n    - [x] About window\n    - [x] Log window\n        - [x] Aggregate \u0026 display logs\n        - [x] Clear logs\n        - [ ] Write logs to file\n    - [ ] Configuration UI\n        - [ ] Generate configurations\n        - [ ] Load existing configurations\n        - [ ] Write/Store configurations\n    - [ ] Emulation mode when no hardware is connected\n    - [ ] Separate from the engine\n    - [ ] Custom graphical widgets?\n        - [ ] Wheel (Rotating image with color tick)\n        - [ ] Dial (Rotating image)\n        - [ ] Button (Depict depressed state)\n\n### Events\n\nState changes.\n\n- [x] USB:\n    - [x] connected\n    - [x] disconnected\n- [x] Buttons 1 to 5:\n    - [x] press\n    - [x] release\n- [x] Wheel:\n    - [x] centered (position 0)\n    - [x] position change (-7 to 7)\n    - [x] direction: up\n    - [x] direction: down\n- [x] Dial:\n    - [x] direction: up\n    - [x] direction: down\n    - [x] absolute position (0 to 255)\n\n### Observers\n\nGets notified upon events\n\n- [x] GUI\n- [ ] **(WIP)** Responder plugins Broker\n\n### Broker\n\nMaps events observation to responses depending on the current configuration and available responder plugins.\n\n- [ ] Configuration system\n    - [ ] Formats support\n        - [ ] Custom?\n            - [ ] Comments\n        - [ ] [Official driver configurations](https://contourdesign.fr/support/windows-shuttle-settings/)\n            - [ ] Parse\n            - [ ] Generate\n    - [ ] macros (generate multiple events)\n\n- [ ] Responder plugins\n    - [ ] API specification\n    - [ ] Sample implementation\n\n- [ ] runtime profiles support\n    - [ ] configure multiple profiles\n        - [ ] default global\n        - [ ] named\n            - [ ] (optional) linked to one or more specific external states:\n                - [ ] application in focus\n                - [ ] current desktop/monitor?\n                - [ ] session/user?\n                - [ ] external trigger event?\n    - [ ] (auto?) switch profiles dynamically\n        - [ ] using buttons\n        - [ ] detect running application\n            - [ ] Microsoft Windows\n                - [ ] win32ui\n            - [ ] Mac OS X\n            - [ ] GNU/Linux\n\n### Responders\n\nPlugin based system.\n\nGenerates external events triggered by the broker.\n\n- [ ] **(POC)** generate keyboard strokes and/or modifiers\n    - [x] ~~SendKeys?~~\n    - [x] ~~pywin32 shell.SendKeys?~~\n    - [ ] **(POC)** pynput! (Also support mouse)\n    - [ ] Frequency (Once/Hold…)\n\n- [ ] **(POC)** generate mouse events\n    - [ ] **(POC)** pynput! (Also support mouse)\n    - [ ] click\n    - [ ] wheel\n\n- [ ] generate MIDI\n    - [ ] Arbitrary (User defined)\n    - [ ] MCU compatible\n    - [ ] HUI compatible\n\n- [ ] generate OSC\n\n- [ ] call APIs?\n\n- [ ] launch applications\n    - ?\n\nContour format settings\n-----------------------\n\nMay be used as samples for interoperability.\n\n### Contour\n\n- [Microsoft Windows](https://www.contourdesign.com/windows-shuttle-settings/)\n- [Mac OS X](https://www.contourdesign.com/mac-shuttle-settings/)\n\n### GitHub\n\n- [ShuttleProSettings](https://github.com/Rolias/ShuttleProSettings)\n    - Camtasia Studio 8 *Microsoft Windows*\n    - Reaper *Apple Mac OS X*\n- [camtasia-shuttlepro-settings](https://github.com/digitaldrummerj/camtasia-shuttlepro-settings/blob/master/Camtasia%20Studio%209.pref)\n    - Camtasia Studio 9 *Microsoft Windows*\n\nSimilar and/or related projects\n---------------------------\n\n\n\u003c!-- BEGIN Template\n\n### []()\n\n\n\n- Language: \n- License: \n- OS: \n- Dependencies: \n\nEND Template --\u003e\n\n### [Contour-ShuttlePRO-V1-Linux-Custom-Implementation](https://github.com/c0deous/Contour-ShuttlePRO-V1-Linux-Custom-Implementation)\n\nA simple barebones driver written in Python for the Contour ShuttlePRO V1 Control Surface.\n\n- Language: Python\n- License: Unspecified/Proprietary (Copyright 2016 c0deous?)\n- OS: GNU/Linux\n- Dependencies: python-evdev\n\n### [cncjs-pendant-shuttle](https://github.com/bensuffolk/cncjs-pendant-shuttle)\n\nA cncjs pendant to connect a Contour Design ShuttleXpress to the raspberry pi that is running cncjs.\n\n- Language: Javascript/NodeJS\n- License: MIT (Copyright (c) 2021 Ben Suffolk)\n- OS: GNU/Linux\n- Dependencies: udev, cnjs, shuttle-control-usb\n\n### [kh750remote](https://github.com/floxch/kh750remote)\n\nNeumann KH 750 DSP remote control with Contour ShuttleXpress.\n\n- Language: Javascript/NodeJS\n- License: MIT (Copyright (c) 2021 floxch)\n- OS: Multiplatform?\n- Dependencies: multicast-dns, node-hid, node-notifier, node-osc\n\n### [LightroomShuttlePro](https://github.com/abrilevskiy/LightroomShuttlePro)\n\nLightroom plugin for support contourdesign ShuttlePro v2.\n\n- Language: C++/Lua\n- License: GPL-3.0  (Copyright 2018 abrilevskiy?) + Proprietary (Copyright (c) 2003 Contour Design, Inc. \u0026 Copyright\n  2016 Adobe Systems Incorporated)\n- OS: Microsoft Windows\n- Dependencies: ShuttleSDK.dll\n\n### [node-red-contrib-shuttlexpress](https://github.com/legacymachine/node-red-contrib-shuttlexpress)\n\nNode-RED nodes for USB ShuttleXpress device.\n\n- Language: Javascript/NodeJS\n- License: MIT (Copyright (c) 2019 legacymachine aka Legacy Machine Works, LLC aka Josh Dudley)\n- OS: Multiplatform\n- Dependencies: node-hid\n\n### [node-shuttlexpress](https://github.com/legacymachine/node-shuttlexpress)\n\nNodeJS API for USB ShuttleXpress Device.\n\n- Language: Javascript/NodeJS\n- License: MIT (Copyright (c) 2019 legacymachine aka Legacy Machine Works, LLC aka Josh Dudley)\n- OS: Multiplatform\n- Dependencies: node-hid\n\n### [shuttle](https://github.com/jeamland/shuttle)\n\nA little Swift program to make a ShuttleXpress do what I want.\n\n- Language: Swift\n- License: BSD-2-Clause (Copyright (c) 2016, Benno Rice)\n- OS: Apple Mac OS X\n- Dependencies: Mac OS X 10.12 SDK\n\n### [Shuttle](https://github.com/1div0/Shuttle)\n\nControlling Ardour with Open Sound Control from Contour Design ShuttlePRO \u0026 ShuttlePRO v2.\n\n- Language: C\n- License: GPL-2.0 (Copyright (C) 2001-2007 Dan Dennedy)\n- OS: GNU/Linux\n- Dependencies: liblo\n\n### [shuttle-go](https://github.com/abourget/shuttle-go)\n\nContour Design Shuttle Pro V2 drivers for Linux, in Go, with modifiers and just more slick.\n\n- Language: Go\n- License: MIT (Copyright (c) 2017 Alexandre Bourget)\n- OS: GNU/Linux\n- Dependencies: udev\n\n### [ShuttleControlUSB](https://github.com/hopejr/ShuttleControlUSB)\n\nA Library to use Contour Design ShuttleXpress and ShuttlePro v2 in Node.js projects without the driver.\n\n- Language: Javascript/NodeJS\n- License: MIT (Copyright (c) 2020 James Hope)\n- OS: Multiplatform?\n- Dependencies: node-hid, usb-detection, udev\n\n### [shuttled](https://github.com/Shamanon/shuttled)\n\nShuttlePro fork.\n\nDaemon for Contour Shuttle devices to translate button/jogwheel events to keystrokes sent to uinput.\n\n- Language: C\n- License: GPL-3.0 (Copyright 2013 Eric Messick, Copyleft 2015 Joshua Besneatte)\n- OS: GNU/Linux\n- Dependencies: libx11, libxtst, udev, uinput\n\n### [shuttleevent](https://github.com/pmjdebruijn/shuttleevent)\n\nShuttlePRO fork.\n\nUser program for interpreting key, shuttle, and jog events from a Contour Design ShuttlePRO v2\n\n- Language: C\n- License: GPL-3.0 (Copyright 2013 Eric Messick, Copyright 2018 Albert Graef, Copyright 2019 Pascal de Bruijn)\n- OS: GNU/Linux\n- Dependencies: libx11, libxtst, udev\n\n### [ShuttleGRBL](https://github.com/Duffmann/ShuttleGRBL)\n\nContour's ShuttleExpress for jogging a GRBL CNC machine under cncjs and Linux using USB/hidraw.\n\n- Language: Javascript/NodeJS\n- License: MIT (Copyright (c) 2020 Duffmann aka Nelio Santos)\n- OS: GNU/Linux\n- Dependencies: commander, inquirer, jsonwebtoken, lodash.get, node-hid, serialport, socket.io-client, udev, vorpal\n\n### [shuttleit](https://github.com/irontoby/shuttleit)\n\nEvent handler for Contour Design ShuttleXpress.\n\n- Language: Perl\n- License: Apache-2.0 (Copyright 2015 Tobias Johnson)\n- OS: GNU/Linux\n- Dependencies: udev\n\n### [shuttlemidi](https://github.com/dg1psi/shuttlemidi)\n\nSends MIDI from the Shuttle Contour to SDR Console.\n\n- Language: Go\n- License: Apache-2.0 (Copyright 2021 dg1psi)\n- OS: Multiplatform?\n- Dependencies: hidapi, loopmidi\n\n### [ShuttleNET](https://github.com/EddieMac74/ShuttleNET)\n\nA simple .NET wrapper for the Contour Shuttle SDK. Written in C#.\n\n- Language: C#\n- License: Unspecified/Proprietary (Copyright © Edward MacDonald 2018)\n- OS: Microsoft Windows?\n- Dependencies: ShuttleSDK.dll\n\n### [shuttlepro](https://github.com/russells-crockpot/shuttlepro)\n\nA python app to allow usage of the Contour ShuttlePro V2 in Linux.\n\n- Language: Python\n- License: Unspecified/Proprietary (Copyright 2020 Brendan McGloin?)\n- OS: GNU/Linux\n- Dependencies: click, evdev, Xlib\n\n### [ShuttlePRO](https://github.com/nanosyzygy/ShuttlePRO)\n\nUser program for interpreting key, shuttle, and jog events from a Contour Design ShuttlePRO v2.\n\n- Language: C\n- License: GPL-3.0 (Copyright 2013 Eric Messick)\n- OS: GNU/Linux\n- Dependencies: libx11, libxtst, udev\n\n### [ShuttlePRO](https://github.com/SERVCUBED/ShuttlePRO)\n\nShuttlePRO fork.\n\nUser program for interpreting key, shuttle, and jog events from a Contour Design ShuttlePRO v2\n\n- Language: C\n- License: GPL-3.0 (Copyright 2013 Eric Messick, Copyright 2018 Albert Graef, Copyright 2020 Ben Blain)\n- OS: GNU/Linux\n- Dependencies: libjack, libx11, libxtst, udev\n\n### [ShuttlePro-M](https://github.com/w5pny/ShuttlePRO-M)\n\nShuttlePro fork.\n\nUser program for interpreting key, shuttle, and jog events from a Contour Design ShuttlePRO v2.\n\n- Language: C\n- License: GPL-3.0 (Copyright 2013 Eric Messick, Copyright 2020 Harry G McGavran Jr)\n- OS: GNU/Linux\n- Dependencies: udev\n\n### [shuttleprov2_linux_driver](https://github.com/rmt/shuttleprov2_linux_driver)\n\nA Linux userspace \"driver\" for the ShuttlePro V2 device, and some tools to read events from a wacom tablet.\n\n- Language: D\n- License: LGPL-3.0 (Copyright 2013 Robert Thomson)\n- OS: GNU/Linux\n- Dependencies: None\n\n### [shuttleroom](https://github.com/7Pass/shuttleroom)\n\nLightroom plugin to use ShuttleXpress controller for Develop.\n\n- Language: C#\n- License: Unspecified/Proprietary (Copyright 2020 Ngoc Van Tran?)\n- OS: Microsoft Windows, Ubuntu?\n- Dependencies: .NET Core 3.1.100, ShuttleSDK64.dll\n\n### [shuttle-xpress-android](https://github.com/freshollie/shuttle-xpress-android)\n\nAndroid Library for interfacing with a Contour Design Shuttle Xpress 🕹️.\n\n- Language: Java\n- License: Apache-2.0 (Copyright 2017 Oliver Bell)\n- OS: Android\n- Dependencies: API 17\n\n### [ShuttleXpress](https://github.com/threedaymonk/shuttlexpress)\n\nUse a Contour ShuttleXpress in Linux.\n\n- Language: Scheme\n- License: Unspecified/Proprietary (Copyright 2012 Paul Battley?)\n- OS: GNU/Linux\n- Dependencies: Xlib, udev\n\n### [Shuttlexpress-MPD](https://github.com/matthew-wolf-n4mtt/shuttlexpress-mpd)\n\nShuttlexpress-MPD is a Music Player Daemon (MPD) client that uses a Contour ShuttleXpress to control the status of the\nplayback of an MPD instance.\n\n- Language: C\n- License: GPL-2.0 (Copyright 2019 Matthew J. Wolf)\n- OS: GNU/Linux\n- Dependencies: mpd, udev, systemd\n\n### [widget-shuttlexpress](https://github.com/chilipeppr/widget-shuttlexpress)\n\nThe ShuttleXpress widget helps you setup your own ShuttleXpress jog dial USB device and enables audio feedback as you\ntoggle the buttons on the device.\n\n- Language: Javascript/HTML/CSS\n- License: Unspecified/Proprietary (Copyright 2016 John Lauer?)\n- OS: ChiliPeppr\n- Dependencies: ChiliPeppr\n\nDevelopment log\n---------------\n\n### Finding the right library for Microsoft Windows\n\n#### Attempt 1\n\nUsing [pyUSB](https://pypi.org/project/pyusb/)\n\nCan’t access device without a kernel driver.\n\nKernel driver has been generated using [libusb-win32](https://sourceforge.net/projects/libusb-win32/), but you need to\ndisable driver signature enforcement before installing.\n\nThe easier way is to use [Zadig](https://zadig.akeo.ie/).\n\n#### Attempt 2\n\nUsing [pyWinUSB](https://pypi.org/project/pywinusb/)\n\nCan get HID without driver installation on Microsoft Windows!\n\nLet’s continue…\n\nSuccess!\n\nBut...\n\n#### Attempt 3\n\nUsing [cython-hidapi](https://pypi.org/project/hidapi/)\n\nCrossplatform (Microsoft Windows, Mac OS X, GNU/Linux)\n\nSuccess on Microsoft Windows without prior driver installation!\nHope it’s the same on other platforms.\n\n### Building a GUI\n\n#### PySide6 (QT6)\n\nPrototype UI done\n\n### Exploring patterns\n\nSettled for an observer pattern with a central broker and separate plugin based responders.\n\n\nLegal notice\n------------\n\n### License\n\nCopyright 2021 Raphaël Doursenaud\n\nThis software is released under the terms of the GNU General Public License, version 3.0 or later (GPL-3.0-or-later).\n\nSee [LICENSE](LICENSE).\n\n### Dependencies \u0026 License Acknowledgment\n\n- [Python](https://python.org) v3.10  \n  Used under the terms of the PSF License Agreement.\n- libusb [hidapi](https://github.com/libusb/hidapi)  \n  Copyright Alan Ott, Signal 11 Software.  \n  Used under the terms of the GNU General Public License, version 3.0 (GPL-3.0).\n- via Trezor [cython-hidapi](https://github.com/trezor/cython-hidapi)  \n  Copyright Pavol Rusnak, SatoshiLabs.  \n  Used under the terms of the GNU General Public License, version 3.0 (GPL-3.0).\n- Qt [PySide6](https://www.pyside.org)  \n  Used under the terms of the GNU Lesser General Public License v3.0 (LGPL-3.0).\n- UN-GCPDS [Qt-Material](https://github.com/UN-GCPDS/qt-material)  \n  Used under the BSD-2-Clause License.\n- [Material Design Icons](https://materialdesignicons.com)  \n  Used under the Pictogrammers Free License.\n\n### Trademarks\n\nContour, ShuttleXpress and ShuttlePro are trademarks of Contour Innovations LLC in the United States of America.\n\nThese are not registered or active trademarks in the European Union and France where I reside.\n\n#### Other\n\nOther trademarks are property of their respective owners and used fairly for descriptive and nominative purposes only.\n","funding_links":["https://github.com/sponsors/rdoursenaud"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fematech%2Fopencontourshuttle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fematech%2Fopencontourshuttle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fematech%2Fopencontourshuttle/lists"}