Summary
Currently, QMK supports user-defined RGB Matrix effects via:
RGB_MATRIX_CUSTOM_USERrgb_matrix_user.incRGB_MATRIX_EFFECT(...)
These effects receive valid RGB Matrix mode IDs inside QMK and can be activated from firmware using:
rgb_matrix_mode_noeeprom(RGB_MATRIX_CUSTOM_my_effect);
However, custom RGB Matrix effects are currently inaccessible through the VialRGB protocol.
Current limitation
As far as I understand, VialRGB only exposes effects that are registered in its internal vialrgb_effects.inc mapping table.
As a consequence:
VIALRGB_GET_SUPPORTED cannot report user-defined RGB Matrix effects.VIALRGB_SET_MODE cannot select user-defined RGB Matrix effects.- GUI applications cannot discover or activate effects defined through
RGB_MATRIX_CUSTOM_USER.
The effects themselves work correctly inside QMK and can be activated through custom keycodes or firmware logic. The limitation appears to be in the VialRGB protocol layer rather than in QMK.
Use case
A keyboard firmware may implement custom effects such as:
RGB_MATRIX_EFFECT(custom_lighting)
RGB_MATRIX_EFFECT(audio_visualizer)
RGB_MATRIX_EFFECT(dynamic_lights)
These effects are fully functional but currently cannot be selected from Vial-compatible software.
The only available workaround is assigning dedicated keycodes that call:
rgb_matrix_mode_noeeprom(...)
directly from firmware.
Suggested solutions
Option 1: Custom effect slots
Extend the protocol with a number of generic custom effect slots.
Example:
CUSTOM_EFFECT_1
CUSTOM_EFFECT_2
...
CUSTOM_EFFECT_16
Firmware could map these slots to actual QMK custom effects.
This would allow GUI software to remain protocol-compatible without needing to understand individual effect names.
Option 2: Enumerate custom effects
Extend VIALRGB_GET_SUPPORTED so firmware can report additional RGB Matrix modes beyond the built-in VialRGB table.
GUI software could then display those effects alongside the standard RGB Matrix effects.
Option 3: User-defined effect names
Allow firmware to optionally provide effect names.
Example:
custom_lighting
audio_visualizer
dynamic_lights
This would provide the best user experience but would require additional protocol support.
Why this matters
QMK officially supports custom RGB Matrix effects and many advanced keyboard projects rely on them.
Currently these effects are effectively invisible to the VialRGB ecosystem despite being first-class RGB Matrix modes inside QMK.
Providing a protocol-level mechanism to enumerate and select custom RGB Matrix effects would allow Vial-compatible tools to support them without requiring firmware-specific workarounds.
Summary
Currently, QMK supports user-defined RGB Matrix effects via:
RGB_MATRIX_CUSTOM_USERrgb_matrix_user.incRGB_MATRIX_EFFECT(...)These effects receive valid RGB Matrix mode IDs inside QMK and can be activated from firmware using:
However, custom RGB Matrix effects are currently inaccessible through the VialRGB protocol.
Current limitation
As far as I understand, VialRGB only exposes effects that are registered in its internal
vialrgb_effects.incmapping table.As a consequence:
VIALRGB_GET_SUPPORTEDcannot report user-defined RGB Matrix effects.VIALRGB_SET_MODEcannot select user-defined RGB Matrix effects.RGB_MATRIX_CUSTOM_USER.The effects themselves work correctly inside QMK and can be activated through custom keycodes or firmware logic. The limitation appears to be in the VialRGB protocol layer rather than in QMK.
Use case
A keyboard firmware may implement custom effects such as:
These effects are fully functional but currently cannot be selected from Vial-compatible software.
The only available workaround is assigning dedicated keycodes that call:
rgb_matrix_mode_noeeprom(...)directly from firmware.
Suggested solutions
Option 1: Custom effect slots
Extend the protocol with a number of generic custom effect slots.
Example:
Firmware could map these slots to actual QMK custom effects.
This would allow GUI software to remain protocol-compatible without needing to understand individual effect names.
Option 2: Enumerate custom effects
Extend
VIALRGB_GET_SUPPORTEDso firmware can report additional RGB Matrix modes beyond the built-in VialRGB table.GUI software could then display those effects alongside the standard RGB Matrix effects.
Option 3: User-defined effect names
Allow firmware to optionally provide effect names.
Example:
This would provide the best user experience but would require additional protocol support.
Why this matters
QMK officially supports custom RGB Matrix effects and many advanced keyboard projects rely on them.
Currently these effects are effectively invisible to the VialRGB ecosystem despite being first-class RGB Matrix modes inside QMK.
Providing a protocol-level mechanism to enumerate and select custom RGB Matrix effects would allow Vial-compatible tools to support them without requiring firmware-specific workarounds.