abourget / shuttle-go

Contour Design Shuttle Pro V2 drivers for Linux, in Go, with modifiers and just more slick.

Linux driver for Contour Design Shuttle Pro V2

The goal of this project is to use the Shuttle Pro V2 with the Lightworks Non-Linear Video Editor, but shuttle-go allows you to control anything. It has support for:

• Sending keyboard events (with the default xdotool driver)
• Sending Open Source Control messages (with the ocs:// driver)
• Executing any command through bash -c (with the exec driver)

This program supports having modifiers for your Shuttle Pro V2 buttons. So you can multiple the functionality of your buttons. For example, you can have different bindings for B1+F1 and F1.

Layout

Buttons layout on the Contour Design Shuttle Pro v2:

           F1   F2   F3   F4

        F5   F6   F7   F8   F9


                (Shuttle)
        S-7 .. S-1  S0  S1 .. S7

     M1        JogL    JogR        M2



              B2        B3
            B1            B4

N.B. Contour Design Shuttle Pro v1 has the same buttons layout

Slow Jog

In addition to JogL and JogR, you can define bindings for SlowJogL and SlowJogR. For example, you can use a slow jog use to nudge by one frame at a time.

If you wish to not use slow jog, set the slow_jog key to 0 in the configuration for this app. Otherwise, slow_jog represents the minimum number of milliseconds between two events to be considered slow. It defaults to 200 ms.

Lightworks

Avoid Lightworks key bindings with modifiers however. Capital letters are great as they cannot be combined, and are more direct and they are less likely to conflict with your other bindings and Lightworks recognizes them.

Drivers

See sample_config.json for example configuration of each driver.

xdotool (default)

The key names to use in the X11 bindings are found here: https://www.cl.cam.ac.uk/~mgk25/ucs/keysymdef.h or you can view them locally in /usr/include/X11/keysymdef.h (stripped of the XK_ prefix).

You need to install the xdotool package before using this driver (default).

exec

Any bindings triggered will execute the corresponding command through /bin/bash -c "your command"

osc://host:port

In the configuration, use "driver": "osc://host:port", then all your bindings can be of the format: /osc/address/path param1 param2 param3.

You can send multiple messages with one key by separating those bindings by + (that's a space, a plus sign, and another space).

A special /sleep 0.123 message can be added, and it interpreted by shuttle-go as a sleep between two OSC messages. Use that if your program goes berzerk when messages are too close.

Run

With:

sudo shuttle-go /dev/input/by-id/usb-Contour_Design_ShuttlePRO_v2-event-if00

For ShuttlePRO_v1

shuttle-go /dev/input/by-id/usb-Contour_Design_ShuttlePRO-event-if00

N.B. Running shuttle-go as sudo will cause shuttle-go to look for a valid config file in

/root/.shuttle-go.json

Without sudo, shuttle-go will look for a valid config file in the current user's home dir

~/.shuttle-go.json 

Install in udev with:

As root, write file /etc/udev/rules.d/01-shuttle-go.rules with contents:

ACTION=="add", ATTRS{name}=="Contour Design ShuttlePRO v2", MODE="0644"
ACTION=="remove", ATTRS{name}=="Contour Design ShuttlePRO v2", RUN+="/usr/bin/pkill shuttle-go"

For ShuttlePRO_v1

ACTION=="add", ATTRS{name}=="Contour Design ShuttlePRO", MODE="0644"
ACTION=="remove", ATTRS{name}=="Contour Design ShuttlePRO", RUN+="/usr/bin/pkill shuttle-go"

Then run, as root:

udevadm control --reload-rules && udevadm trigger

From that point on, plug in the device, and run shuttle-go in any terminal (provided shuttle-go is in your $PATH).

License

MIT

TODO

• Don't require xdotool

  • Use xgb's xtest package and send the FakeInput directly there..

• Watch the configuration file, and reload on change.

• Have a default SlowJog configuration.

• Make it auto-run on plug, with udev rules like:

    ACTION=="add", ATTRS{name}=="Contour Design ShuttlePRO v2", ENV{MINOR}=="79", RUN+="/home/abourget/go/src/github.com/abourget/shuttle-go/udev-start.sh"
    ACTION=="remove", ATTRS{name}=="Contour Design ShuttlePRO v2", RUN+="/usr/bin/pkill shuttle-go"

shuttle-go's Issues

Pressed keys and general settings

Hello! I just recently found this software, it is awesome! Thanks for the hard work!

Is there a way to continue sending the key while a button is down? I am trying to configure a button to, for example, increase volume. However, the output in the terminal only shows two states, up and down, so I think I'm unable to succeed.

I have no coding experience at all, but I can understand something (I was able to compile it, lol). I can however contribute with templates. I am currently working on two for Krita and Blender, but I have yet to find how to contribute to the project with that at least.

It would also be good to have a "general" setting to, for example, always use the shuttle or the jog as scroll down/up.

Thanks! And sorry if it is not the proper way of reporting something!

using several contour shuttle devices simultaneously

Hi,
is it possible to use two or more shuttle pro v2 simultaneously ?
or at least using a shuttle pro v1, a shuttle pro v2 and express at once ?

greets and Thanks
notger

keybinding - definitions ?

I have xdotools installed

when making my button layout in .shuttle-go.json i come across some weired (or at least for me unclear behaviours).

i tried to keep the keynames from ym local /usr/include/X11/keysymdef.h (but found out that you made them availeable wihout the XK_ trough the definitions.go)

interesting is that sometimes it needs the XK_ to make the button work sometimes not,...and i do not understand the pattern behind it........do you have any idea ?......i use a german keyboardlayout on my keayboard if that plays any role in that..
here are some bindings i trie with a comment if they wok or not

            "bindings": {

                "F1": "XF86AudioMute //works",
                "F2": "Micmute // doesnt work",
                "M1+F2": "Control+Shift+F12 //Bildschirm aus // works",
                "F3": "XF86MonBrightnessDown //works",
                "F4": "XF86MonBrightnessUp //works",
                "M1+F1": "XF86AudioMedia // doesnt work",
    
                "F5": "XF86AudioRewind // doesnt work",
                "F6": "XF86AudioPrev // doesnt work",
                "F7": "PlayPause //Play oder XF86AudioPlay // doesnt work",
                "F8": "NextSong // XF86AudioNext // both do not work",
                "F9": "Forward // XF86XKAudioForward // both do not work",
                
                "M1": "ScrollDown // doesnt work",
                "M2": "XK_Scroll_Up/D // doesnt work",

                "B1": "Control+F10 //Fenster aller Arbeitsflächen zeigen //works",
                "B2": "Control+Shift+y // Zwischenablage anzeige //works",
                "B3": "Control+Shift+Tab // zwischen Aktivitäten wechseln //works",
                "B4": "Control+Shift+d // Desktop anzeigen //works",
       
                "B3+F2": "XF86MonBrightnessUp // works",
                "B3+F1": "XF86MonBrightnessDown // works",

                "JogL": "XF86AudioLowerVolume // leiser // works",
                "JogR": "XF86AudioRaiseVolume // lauter // works",

                "S-7": "shift+Left // fastrewind in sayonara // works",
                "S-1": "Control+minus // zoomout //works",
                "S1": "Control+plus // zoomin // doesnt work",
                "S7": "shift+Right // fastforward in sayonara // works"
            }
        },

Via the Shuttlo-go debugging all the Buttons show the "right" xdotool key definitions
interesting is that if i try xev | grep --line-buffered keysym
only the shuttle-buttons that work correct get printed

    state 0x0, keycode 36 (keysym 0xff0d, Return), same_screen YES,
    state 0x0, keycode 173 (keysym 0x1008ff16, XF86AudioPrev), same_screen YES,
    state 0x0, keycode 176 (keysym 0x1008ff3e, XF86AudioRewind), same_screen YES,
    state 0x0, keycode 176 (keysym 0x1008ff3e, XF86AudioRewind), same_screen YES,
    state 0x0, keycode 233 (keysym 0x1008ff02, XF86MonBrightnessUp), same_screen YES,
    state 0x0, keycode 232 (keysym 0x1008ff03, XF86MonBrightnessDown), same_screen YES,
    state 0x0, keycode 121 (keysym 0x1008ff12, XF86AudioMute), same_screen YES,
    state 0x0, keycode 37 (keysym 0xffe3, Control_L), same_screen YES,

pressing for expample

                "M1": "ScrollDown // doesnt work",
                "M2": "XK_Scroll_Up/D // doesnt work",

does not print anything with xev | grep --line-buffered keysym

I guess my understanding and basic knowledge is on the Limit here.
So i say Thanks for some Support

Works with ShuttlePro v1

Thank you for this code. Solely FYI:

shuttle-go also works with the original ShuttlePro. Swap the v2 device name with v1's:

/dev/input/by-id/usb-Contour_Design_ShuttlePRO-event-if00

and your code works as designed.

I'm working on keybindings for Blender. By default sample_config.json handles Video Sequencer timeline Zoom In (JogL) and Zoom Out (JogR) and transport start / stop (B4).

Happy to have the Shuttle back in the mix. Many thanks.

multiply shuttle and jogwheel

Hi, is it possible to multiply jogwheel or shuttle

like M1+JogL or M1+S1
cause if i try it like that it does actually not multiply functionality.
And could anyone of you help me with the shuttle-go.json
i would like to implement a kind of if -> then function
in that kind
if ->any windwoclass name like Lightworks, kdlive,......fits use the following button-functions
if none of them fits -> use the default functions like jogwheel-systemaudio, F1 systemMute, media-Play,....

thanks alot notger

PS.: this is a great think thanks for bringing the shuttlepro to linuxworld

Can the installation instruction please be dumbed down?

I would really like it to work. I use Ubuntu; but mostly Windows.

I use my ShuttlePRO v2 primarily for mouse clicking on Windows: M1 = left mouse click and M2 = double click. It would really help.

Not able to install

I get this error when doing go get -v github.com/abourget/shuttle-go:

github.com/abourget/shuttle-go
# github.com/abourget/shuttle-go
../../go/src/github.com/abourget/shuttle-go/osc.go:13:8: server.Handle undefined (type *osc.Server has no field or method Handle)

I am on archlinux.

Keys M1 and M2 not working anymore

Hi,
I just bought a brand new Shuttle Pro V2
Unfortunately the M1 and M2 key is not detectet by shuttle-go anymore. Maybe Contour has changed the keycodes because with the recent windows-driver all is working well.
If necessary I'm willing to assist in finding the new codes.

Kind regards
Harald

Brilliant! Really wishing for Udev triggering.

I have no real issue, I love this software. It makes the Shuttle devices much more useful in Kdenlive due to the button assignments. However, the one thing I really would like is the ability to trigger it from Udev. I have tried every method I could come up with and nothing seems to work. Any ideas for the future?

Thank you so much for this, It has really helped me out immensely.

Jaaxx

Please add reading of /etc/shuttle-go.json config

I'd like to package shuttle-go and provide a default config, to make it runnable without requiring user's attention to finish setup. Package scripts can't touch user's $HOME, so the default config must be delivered somewhere else (and typically this is /etc/). That's why I'm suggesting to read the default config from /etc/shuttle-go.json when $HOME/.shuttle-go.json does not exists.