Kontrol S4 Mk3: add controller mapping

[acolombier]

Howdy Mixxx community!

Some irrelevant context

I have recently acquired some S4 MK3 gears, and like many as I could read online, I was somehow disappointed with the overall Traktor experience and the lack of capability, whilst extremely pleased with the hardware.

I decided to try Mixxx, which I had tried many years ago with some Reloop gears, sadly, when I plugged it (and fixed the udev rules...), the controller wasn't recognized out of the box, which was a bit of a bummer.

With this current mapping, I am now fully embracing these controllers again and thought I will share it with the community!

This work is continued from the great one that @Be-ing had started a few months back. A few mappings were changed from his first draft, but most of all, the wheel is now accurate, both in vinyl and turntable mode.

Sadly the screens won't work in the current state of Mixxx as @Be-ing mentioned it on Reddit. After further reverse engineering, I can confirm that the screens are driven by sending a 320x240 pixels matrix using a 16-bits color depth. While it could easily be driven by something external as this is not on the HID class (thus not locked), there is no way to integrate this smoothly within Mixxx (just yet at least, hopefully the team has plans for these additional vendor classes, which isn't unique to NI gears I believe). Perhaps if there is no immediate plans, a socket allowing a third party program to fetch metadata (RO) from Mixxx could be a nice step forward? This way, any vendor specific could be compiled into a third party program that would interact with these specific vendor classes.

Currently, I have kept the 20 quick FX selector, but IMO, it is far too much as there is no way to remember these 20 combinations. Furthermore, now that FX units are easier to interact with, I believe that 5-10 should be the max and I will likely do a different mode.

As it stands, they are a few mild issues limitation due to either missing features or bugs in Mixxx:

• [Feat] Many configurable settings (deck colors, number of quick FXs, loop move factor, ...) must be hard-coded, while it would be great if this could easily be changed in the settings UI, for example using the XML to define configurable items. (allow users to change mapping options from GUI without having to edit XML or JS #8135)
• [Feat] No control with preparation playlist (e.g ability to add the selected track to a selected/preparation playlist)
• [Feat] No control with the existing related search feature (e.g ability to search track with a similar key or BPM) due to missing engine controls.
• [Bug] Library browsing won't work with if Mixxx window doesn't have focus (Unable to move library cursor from a controller when the Mixxx window loses the focus #11285)
• [Bug] Missed HID instruction due to skipped frame (consecutively sent HID output messages are skipped #10828) leading to the left wheel ring to stay on upon shutdown (the workaround cannot apply there)

These limitations being unrelated to the mapping itself, I believe this could be considered production ready. I had a few sessions with it and it was a blast! It might not be 100% perfect but I believe this would be better than nothing and allow s4 owner to at least have something working at first. If the team thinks this would be acceptable, I will provide more docs as per the contribution guidelines.

I will report the bug (Library browsing), however I will hold for feature requests, as I don't want to overstep boundaries and request features that may be only interesting for me (or S4 MK3 owners). If you think they are fair requests tho, I'm happy to formulate them into issues, and potentially even help with them! :)

Documentation

Here is a very "quick-n-dirty" documentation for anyone that would like to try this mapping. If the Mixxx team would consider this PR for merging, I would be happy to work on this more and submit an other PR to the manual

Wheel mode

Wheel modes define how the wheel reacts when used. Here are all the various modes:

1. Vinyl mode (default): The wheel platter can be used for scratch. The wheel crown can be used to jog up or down the playback. This mode is on if the Turntable button is off but the Jog button is on
2. Jog mode: The wheel platter and crown can be used to jog up or down the playback. This mode is on if the Turntable button and the Jog button are off
3. Turntable mode: The wheel behaves as a 33.3 turntable. If the platter or crown are slowed down or speeded up, then it will scratch down or up the track. Warning: Because the scratch mode is used, if the track has been pitched up, the keylock will be ignored!. This mode is on if the Turntable button is on and the Jog button is off
4. Loop in: The wheel behaves similarly to CDJ. If the platter or crown are turned, it will move back or forth the start of the loop. Additionally, if the loop encoder is used, it will move the all loop back or forth. This mode is on if the Reverse button and the Wheel ring are blinking. This mode is only available if a loop is active, and will be turned off if the loop is deactivated
5. Loop out: The wheel linke for the loop in mode, but for the exit of the loop. If the platter or crown are turned, it will move back or forth the end of the loop. Additionally, if the loop encoder is used, it will move the all loop back or forth. This mode is on if the Flux button and the Wheel ring are blinking. This mode is only available if a loop is active, and will be turned off if the loop is deactivated

Move mode

Moves modes define how the move encoder reacts when used. Here are all the various modes:

1. Beat (default): The track will jump backward or forward by the number of beats selected
2. Grid: The track's detected beats will be move forward or backward on the waveform. This mode is on if Grid is kept pressed. (The Grid button will blink)
3. BPM: The track's detected BPM will be increased or decreased. This mode is on if Shift+Grid are kept pressed. (The Grid button will blink)
4. Keyboard: The keybaord's keys displayed on pads gets offseted to display higher or lower keys. This mode is on if Stems is kept pressed. (The Stems button will blink)

Mapping details

Button	Action	Lighting
Wheel platter	Scratch when in Vinyl mode and Turntable mode Jog when in Jog mode Move loop start when in Loop In mode Move loop end when in Loop Out mode	Static light rotation: Vinyl, Turntable or Jog mode on Ring blinking: Loop in or out mode on
Wheel crown	Jog when in Vinyl mode, otherwise same as wheel platter
Flux	Toggle flux mode On shift, set a loop end the currrent track position if no active loop, enable loop out wheel mode otherwise	Steady on while no shifting: Reverse enabled Steady on while shiftinh: loop is active Blinking, but flux steady off while shifting: loop in set Blinking, with flux steady on while shifting: loop in wheel mode active
Reverse	Toggle reverse mode On shift, set a loop in the currrent track position if no active loop, enable loop out wheel mode otherwise	Steady on while no shifting: Flux enabled Steady on while shifting: loop is active Blinking, with reverse steady on while shifting: loop out wheel mode active
Grid	Set the beatgrid at the current track position (on release, short press) Enable grid move mode while pressed Enable BPM move mode while pressed and shifting	On when over a detected beat Blinking when grid/BPM move is on Blkinking when grid move mode is enabled
Turntable	Toggle on or off the turntable mode	On: Turntable mode on, otherwise jog or vinyl
Jog	Toggle on or off the vinyl mode	On: Vinyl mode on, otherwise jog or turntable
Deck Select	Select a deck	The deck's main color will be the one of the selected deck
Shift	Shift controls for the all controller side, including effect unit	On or Off
Cue	Trigger the cue default effect Start or stop the track while shifting Select the cue as the play mode if keyboard move mode on	Depending of the cue default mode
Play/Pause	Play/Pause the track Long press: clone the playing track Shift+Long press: eject track	On if track is playing
Move	Beat jump forward (right) or backward by the number of selected beats Increase/Decrease the beats if turned while pressed Increase/decrease pitch when shifting Move backward/forward the grid when in grid move mode Increase/decrease BPM when in BPM move mode Move down/up the keyboard notes when in keyboard move mode
Loop	Enable/disable loop when pressed Reactivate exited loop/exit loop when pressed and shifted Halve/double the loop size Move 1 beat backward/forward when shifted On loop in/out wheel mode: move the loop with precision, left precision if shifted
Master	Make the curent deck sync leader (on release) Long press: Enabled/disable full range tempo fader	Steady on: the deck is sync leader Blinking: the tempo fader is in full range
Sync	Toggle the sync mode (on release) Toggle the keylock (on release) Long press: copy the BPM of the other deck Shift+Long press: copy the key of the other deck	On while no shift: Sync is on On while shift: Keylock is on
Tempo fader	While change the tempo only of the left indicator is either off or of the color of the deck. If green, it means the fader is out of sync with the software, bringing it down will eventually catch up. If white, it means the fader is out of sync with the software, bringing it up will eventually catch up.
Hotcues	Toggle the hotcues page Shift: toggle the second hotcue page	Deck color with dim off: Current page isn't related to hotcue Deck color with dim on: page 1 of hotcue White: page 2 of hotcue
Rec	Currently unused
Sampler	Toggle the sampler page and display samplers on the UI Off: Current page isn't related to samplern: sampler page is active
Mute	Currently unused
Stems	Toggle the keyboard (on release) while press: enable keyboard move mode	Deck color with dim off: Current page isn't related to keyboard deck color with dim on: Keyboard active
Green: keyboard play mode active
Pads	While in hotcue: press will activate shift+press will delete While in sample: press will play (load selected track if none are) shift+press will stop (if playing) or eject While in keyboard: will set the key to the selected note will play from the cue if in keyboard play mode	In hotcue: color of the cue In Sampler: Dim on, sample is playing, dim off sampler is stopped, off no sampler loaded In keyboard: keyboard color on each note, if Dim on, currently active note
FX 1st knob	Master volume/mix of the unit
FX 1st button	Trigger all effect Assign/de-assign effect to master while shifting and no focused effect Exit focused mode while shifting and focused effect	On if all effect are when no shifting On when effect is attached to master when shifting Blinking in effect focused mode
FX 2nd knob	Meta arg of the first selected effect First arg of the focused effect in effect focus mode
FX 3rd knob	Meta arg of the second selected effect Second arg of the focused effect in effect focus mode
FX 4th knob	Meta arg of the third selected effect Third arg of the focused effect in effect focus mode
FX 2nd button	Toggle first effect (short press) or trigger first effect (long press) and no focused effect Toggle first arg (short press) or trigger first arg (long press) of the focus effect if any	On if effect is active and no focused effect arg state
FX 3rd button	Toggle second effect (short press) or trigger second effect (long press) and no focused effect Toggle second arg (short press) or trigger cond arg (long press) of the focus effect if any	On if effect is active and no focused effect arg state
FX 4th button	Toggle third effect (short press) or trigger third effect (long press) and no focused effect Toggle third arg (short press) or trigger ird arg (long press) of the focus effect if any	On if effect is active and no focused effect arg state
Library knob	Move up/down in tracklist Move up/down in tree structure while shifted Move up/down in the context menu if playlist button is pressed Zoom in/out the waveform when in grid move mode Beatjump by 16 beats backward/forward if a track is being previewed using the button Star down/up the currently playing track while pressing the star button Sort by next/previous column while pressing the view button Expand the context-manu item when pressed while pressing the playlist button Load track when pressed or expand/collapse tree node when shifted (if view button is not pressed) Inverse the column sorting if view button is pressed
Preview button	Preview the currently selected track while pressed
Star button	Change the selected track color on short press (next color, or previous if shifted)
Star button	Change the selected track color on short press (next color, or previous if shifted)
Playlist button	Open or close a context menu for the currently selected track	On if there is a context-menu open, off otherwise
Mixer FX button	Toggle third effect (short press) or trigger third effect (long press) or assign the quick effect of FX select buttons are pressed	Dim on if the effect is active
FX Select button	Apply effect to all deck on release, if no mixer FX button have been pressed
Ext	Apply the current gain as default

[uklotzde]

Thanks for continuing @Be-ing's work! I appreciate the detailed documentation you added here, including a short description of your motivation.

I am happy to give your mapping a test run soon. Due to my inability to use JavaScript effectively I already lost hope to ever use the controller in Mixxx for its purpose. Until now it was just a costly piece of hardware for some USB HID experiments in Rust ;)

[uklotzde]

The PR should probably be rebased on and target the 2.4 release branch.

[Be-ing]

Thanks for picking this up. A few initial impressions:

• The jog wheel handling is much better, though turning on the motor makes playback slow down dramatically.
• The persistently blinking GRID button is annoying. Please don't blink it, or at least make that an option that's off by default.
• I don't think the LEDs of the REV and FLX buttons should be lit at all in their inactive state because the hardware only lights them up red :/ This makes them look out of place when the deck color is anything but red.

[Be-ing]

This was a joke. You can go ahead and remove this paragraph 😆

[Be-ing]

The handling of the GRID button is problematic. Shifting the beatgrid when releasing the button makes it difficult to align with the rhythm. I understand that's required to do something different while holding the button down, but nothing seems to happen when holding the button down or holding with shift. I suggest removing the alternative behavior when holding it down and only have an alternative behavior when holding with shift to allow the plain press to take effect on button down.

[acolombier]

• The jog wheel handling is much better, though turning on the motor makes playback slow down dramatically.

Hmmm interesting... Would you mind giving me some details on how I can reproduce it? I did use the motor a few hours ago during a quick set and didn't have any issues, could it be related to different Mixxx version perhaps?

• The persistently blinking GRID button is annoying. Please don't blink it, or at least make that an option that's off by default.

I personally like it but I appreciate it can be irritating for some. I will make it a setting. Sounds like my suggested feature request is getting some traction 😀

• I don't think the LEDs of the REV and FLX buttons should be lit at all in their inactive state because the hardware only lights them up red :/ This makes them look out of place when the deck color is anything but red.

I actually like the backlit feature, and like this similarity with CDJ/Pioneer look... I will make that a setting too. Do you think backlit should be something that can be disabled everywhere or just on those buttons?

[Be-ing]

Currently, I have kept the 20 quick FX selector, but IMO, it is far too much as there is no way to remember these 20 combinations. Furthermore, now that FX units are easier to interact with, I believe that 5-10 should be the max and I will likely do a different mode.

What do you mean? While 25 presets is a bit much to use, I don't know what else it would make sense to do with those buttons.

[Be-ing]

Do you think backlit should be something that can be disabled everywhere or just on those buttons?

Just those buttons because it throws off the visual consistency of the colors with the surrounding colors. For the rest of the buttons, I intentionally made use of the dimly lit colored state as the disabled state to strengthen the association with the color of the deck. I don't know why NI put full color LEDs in all the deck buttons except those two 🤷 (or if the hardware is there, why the firmware doesn't react appropriately).

[Be-ing]

The handling of the GRID button is problematic. Shifting the beatgrid when releasing the button makes it difficult to align with the rhythm. I understand that's required to do something different while holding the button down, but nothing seems to happen when holding the button down or holding with shift. I suggest removing the alternative behavior when holding it down and only have an alternative behavior when holding with shift to allow the plain press to take effect on button down.

Ah sorry, I misunderstood the documentation. I assumed holding the GRID button changed the behavior when the jog wheel moved, but it changes the behavior of the left encoder. Both the hold and hold + shift behaviors are useful and I have a suggestion that would allow keeping both of them while allowing the grid alignment to happen on button down. I suggest activating the beatgrid adjustment mode with shift + hold GRID, then use the left encoder for adjusting tempo and the right encoder for adjusting grid alignment (or switch the encoders around, doesn't really matter which is which).

[Be-ing]

Activating sync on button release is also a bit odd. How about moving keylock to the currently unused mute button so sync can be activated on button press?

[acolombier]

I am happy to give your mapping a test run soon. Due to my inability to use JavaScript effectively I already lost hope to ever use the controller in Mixxx for its purpose. Until now it was just a costly piece of hardware for some USB HID experiments in Rust ;)

I must say this is raising my curiosity and perhaps you might be able to help out a bit there!

An idea I had to drive the screens was to create a small binary (ideally in Rust, or in C otherwise) that would emulate a HID device (using UHID) and create a dummy mapping on Mixxx to forward bunch of data to it (e.g title, bpm, key, elapsed time, keylock state...)
This small program would then render an image out of this data and send it to the bulk endpoint.

I thought perhaps your experiment involved some of the above, in what case, if you had anything shared, it would be very appreciated as these are both things (uhid, libusb) I've never used before! :)

The PR should probably be rebased on and target the 2.4 release branch.

Sure thing, will do.

What do you mean? While 25 presets is a bit much to use, I don't know what else it would make sense to do with those buttons.

I think it is not very intuitive to access all 25 preset easily:

• Not sure you can remember the list of 25 quick effects defined in the settings
• The combination requires some brain gymnastic which I feel may be a little bit too much

My thought was to:

• Keep "filter" attached to the effect number one, so you can define a "filter-like" effect on the top of your list, that you know will always be there.
• Make 1 to 4 shiftable (from both decks) so you can have 8 effect.

This would also help with coloring which I find very hard to use at the minute - no way to tell if that "purple" each color is this effect or that one

Do you think backlit should be something that can be disabled everywhere or just on those buttons?

Just those buttons because it throws off the visual consistency of the colors with the surrounding colors. For the rest of the buttons, I intentionally made use of the dimly lit colored state as the disabled state to strengthen the association with the color of the deck. I don't know why NI put full color LEDs in all the deck buttons except those two shrug (or if the hardware is there, why the firmware doesn't react appropriately).

Fair enough, I will make a setting for that.

Ah sorry, I misunderstood the documentation. I assumed holding the GRID button changed the behavior when the jog wheel moved, but it changes the behavior of the left encoder. Both the hold and hold + shift behaviors are useful and I have a suggestion that would allow keeping both of them while allowing the grid alignment to happen on button down. I suggest activating the beatgrid adjustment mode with shift + hold GRID, then use the left encoder for adjusting tempo and the right encoder for adjusting grid alignment (or switch the encoders around, doesn't really matter which is which).

Likely a subjective opinion, but one thing I did with the loop encoder was to reduce its assignment to try and do little and all loop-related actions. I do use loops quite a lot and on the first mapping, I kept on making mistakes because of other action it had.

Also, the idea of the "Move mode" was to change effect of the move encoder only, but if you think strongly about it, I'm happy to make that configurable!

Activating sync on button release is also a bit odd. How about moving keylock to the currently unused mute button so sync can be activated on button press?

I was planning on making a second batch later and use the mute button already. You might have notice I did very little regarding to sampling just yet. My idea was something like:

• Hold mute + click sample: toggle volume
• Hold mute + hold sample: enable volume mode (a new move mode, so the volume can be precisely adjusted with the left encoder, similar in Traktor)
  For the record button, I thought I will do something with hotcues, allowing you to load an active tract as a sample from the selected hotcue (the selected hotcue becomes the sample's cue, or the loop if a lopped hotcue)

I still need more thought and tests of that.

However, shift+master is currently not mapped (only master release and long master), do you think it would be fine for keylocking?

[uklotzde]

I must say this is raising my curiosity and perhaps you might be able to help out a bit there!

An idea I had to drive the screens was to create a small binary (ideally in Rust, or in C otherwise) that would emulate a HID device (using UHID) and create a dummy mapping on Mixxx to forward bunch of data to it (e.g title, bpm, key, elapsed time, keylock state...) This small program would then render an image out of this data and send it to the bulk endpoint.

Unrelated to Mixxx. We added a generic control loop for handling HID I/O to Moiré and a hard-coded hack for attaching the S4MK3 as a device for testing.

Ctrla could provide a starting point for accessing the screens. Sending a static image or pattern to the screens once during initialization would probably be the first step for a PoC.

I am unsure if a standalone executable that serves as a reusable driver and protocol adapter (OSC?) is suitable for high-frequency I/O? But it is definitely worth exploring.

[acolombier]

With this push, unit tests should now pass. It looks like the sampler and effect feature isn't available while running test. Since arguably, this could also happen during runtime, I have made the code more resilient to this, meaning the tests should pass.

@Be-ing I have added the three settings as mentioned above. I will update the doc accordingly once you give me feedback on it. Do you think I should go ahead and formulate a feature request to allow easy tweaking in the preferences? (@uklotzde you input would also be appreciated)

* [Feat] Many configurable settings (deck colors, number of quick FXs, loop move factor, ...) must be hard-coded, while it would be great if this could easily be changed in the settings UI, for example using the XML to define configurable items.

Also pushed some refactor as suggested by @Be-ing + some I stumble across while self-reviewing it.

[Be-ing]

Likely a subjective opinion, but one thing I did with the loop encoder was to reduce its assignment to try and do little and all loop-related actions. I do use loops quite a lot and on the first mapping, I kept on making mistakes because of other action it had.
Also, the idea of the "Move mode" was to change effect of the move encoder only, but if you think strongly about it, I'm happy to make that configurable!

Holding Shift + GRID is something you have to do intentionally; I don't think you'd be doing that on accident while moving the loop encoder. So I don't think there's a risk of accidents using shift + GRID + loop encoder for an alternative action.

[Be-ing]

Do you think I should go ahead and formulate a feature request to allow easy tweaking in the preferences?

This is a long standing feature request: #8135

[acolombier]

Likely a subjective opinion, but one thing I did with the loop encoder was to reduce its assignment to try and do little and all loop-related actions. I do use loops quite a lot and on the first mapping, I kept on making mistakes because of other action it had.
Also, the idea of the "Move mode" was to change effect of the move encoder only, but if you think strongly about it, I'm happy to make that configurable!

Holding Shift + GRID is something you have to do intentionally; I don't think you'd be doing that on accident while moving the loop encoder. So I don't think there's a risk of accidents using shift + GRID + loop encoder for an alternative action.

I will try it out, and if it's not conclusive, I will make it a setting too.

[acolombier]

Ctrla could provide a starting point for accessing the screens. Sending a static image or pattern to the screens once during initialization would probably be the first step for a PoC.

Thanks for for heads up @uklotzde . I have implemented screen support for S4 Mk4 in ctlra and using a UHID, I managed to get a Mixxx mapping to "drive" the screen; the image render is handle in that standalone process, but the data comes from Mixxx.

Likely not something I can make to a production grade at the minute, but I guess it proves the concept.

Here is a small teaser:

output.mp4

[JoergAtGithub]

I have implemented screen support for S4 Mk4 in ctlra and using a UHID, I managed to get a Mixxx mapping to "drive" the screen; the image render is handle in that standalone process, but the data comes from Mixxx.

Cool! How does this external tool communicate with the device? I expect a USB bulk transfer -> Did you know, that Mixxx has USB bulk support using libusb. You could create an additional Bulk mapping for the S4, which just controls the displays, while the HID mapping keeps responisble for the controls.
Unfortunately there is only one bad example for bulk mappings in Mixxx: https://github.com/mixxxdj/mixxx/blob/main/res/controllers/common-bulk-midi.js
and furthermore, on Windows and MacOS you need a signed driver to get libusb to work. But the later should be the same with any other library.

PS: I recommend to continue the discussion about displays on the Zulip developer chat, to keep this PRs comments clean from unrelated comments.

[uklotzde]

Here is a small teaser:

Great, that's awesome 🚀

[JoergAtGithub]

To review a controller mapping, we need a documentation PR, to understand how the mapping is supposed to work. Details are described here: https://github.com/mixxxdj/mixxx/wiki/Contributing-Mappings#documenting-the-mapping
When both PRs are ready, we will merge them at the same time.

[acolombier]

Sure thing, I just wanted to see first if there was some interest in getting the mapping as-in before doing the documentation.
Am I correct in thinking that the documentation I have put in the PR should be fairly sufficient to make the Doc PR? (with maybe a labelled diagrams if I can find one)

[acolombier]

Thanks @Swiftb0y for that findings and the ES Lint fix. I have rebased the branch and fixed the undefined var. Pre-commit should be fine now.

Edit: Should I squash my commit or should I let you guys do it when merging?

[JoergAtGithub]

Please don't squash - if necessary we will do it immediately before merging. Otherwise we loose track, what's already addressed.

[JoergAtGithub]

LGTM! Thank you for your patience!

[uklotzde]

It would be cool if someone could merge 2.4 into main. Minor merge conflict.

[Swiftb0y]

resolved. waiting for CI on my fork to complete before pushing to upstream.

[Swiftb0y]

merged and pushed to upstream.