Feature: Audio Equalizer (DSP) Controller for Razer Kraken V4 Pro (PID 0x0568)

[Zenardi]

Overview

Implement a full 10-band Audio Equalizer control panel for the Razer Kraken V4 Pro OLED Hub (PID 0x0568). The feature must mirror Razer Synapse behavior and visual style — dark-themed, clean industrial UI with bright green accents — and must follow the existing synaptix-daemon D-Bus architecture.

---

UI / UX Specification

Top Level — Audio Mode Switcher

A rounded, segmented toggle control with two options:

• STEREO
• THX SPATIAL AUDIO

The active selection uses a green accent highlight.

---

Presets Bar

A horizontal row of selectable preset buttons (with icons), plus a Reset button on the far right (circular arrow icon):

Icon	Label	Notes
🎮	GAME	Preset curve for gaming
🎬	MOVIE	Preset curve for movies
🎵	MUSIC	Preset curve for music (default selected)
✏️	CUSTOM	Auto-selected when any band is manually adjusted
↺	Reset	Resets all bands to 0 dB

Behavior: Moving any single slider must automatically switch the preset selection to CUSTOM.

---

10-Band EQ Grid (Core Interaction)

Y-Axis (Gain)

Labeled grid lines at: +12 dB, +6 dB, 0 dB, -6 dB, -12 dB

X-Axis — 10 Vertical Sliders

Each slider maps to an integer gain value in the range -12 to +12.

#	Frequency	Band Group
1	31 Hz	SUB BASS
2	63 Hz	SUB BASS
3	125 Hz	BASS
4	250 Hz	BASS
5	500 Hz	LOW MIDS
6	1 kHz	MID RANGE
7	2 kHz	UPPER MIDS
8	4 kHz	UPPER MIDS
9	8 kHz	TREBLE
10	16 kHz	TREBLE

Band Group Labels (Bottom)

Text labels grouped below the frequency labels:
SUB BASS · BASS · LOW MIDS · MID RANGE · UPPER MIDS · TREBLE

Visualization Curve

A solid green polyline connects all 10 circular green slider thumbs, forming a real-time visual representation of the current EQ curve.

---

Known Preset Curves (i8 gain values per band)

These curves are approximations based on Razer Synapse defaults. Values must be verified against the reference USB captures.

Preset	31Hz	63Hz	125Hz	250Hz	500Hz	1kHz	2kHz	4kHz	8kHz	16kHz
GAME	+5	+4	+3	0	0	+2	+3	+4	+5	+4
MOVIE	+4	+3	+2	0	0	+1	+2	+3	+4	+3
MUSIC	+3	+4	+2	0	-1	0	+2	+3	+4	+3
CUSTOM	(user-defined)

---

D-Bus Interface Contract

The UI must act as a pure D-Bus client — no direct USB access. The anticipated interface from synaptix-daemon is:

Interface: org.synaptix.AudioDsp

Method	Signature	Description
SetActiveMode	(mode: String)	Sets audio mode: "stereo" or "thx"
SetBandGain	(frequency_hz: u32, gain_db: i8)	Sets gain for a single frequency band
ApplyFullDspCurve	(gains: Array<i8>[10])	Applies all 10 band gains atomically (used for preset loads)

Expected zbus Proxy (Frontend)

#[zbus::dbus_proxy(
    interface = "org.synaptix.AudioDsp",
    default_service = "org.synaptix.Daemon",
    default_path = "/org/synaptix/devices/kraken_v4_pro"
)]
trait AudioDsp {
    async fn set_active_mode(&self, mode: &str) -> zbus::Result<()>;
    async fn set_band_gain(&self, frequency_hz: u32, gain_db: i8) -> zbus::Result<()>;
    async fn apply_full_dsp_curve(&self, gains: &[i8]) -> zbus::Result<()>;
}

---

Implementation Plan

Step 1 — Data Contract (synaptix-protocol)

• Add AudioPreset enum: Game, Movie, Music, Custom
• Add AudioMode enum: Stereo, ThxSpatialAudio
• Add EqCurve struct: wraps [i8; 10] with named-band accessors
• Add preset constants (PRESET_GAME, PRESET_MOVIE, PRESET_MUSIC)

Step 2 — D-Bus Proxy (synaptix-ui)

• Define AudioDspProxy using zbus::dbus_proxy as shown above

Step 3 — TDD Verification (synaptix-protocol)

• test_preset_game_curve_has_10_bands
• test_preset_music_curve_values_are_in_range
• test_custom_preset_allows_arbitrary_values

Step 4 — Frontend Component (synaptix-ui / React + Tauri)

• EqSlider — vertical range input (-12 to +12) with green circular thumb
• EqGrid — 10 sliders + SVG polyline curve overlay
• PresetBar — segmented preset buttons, auto-switches to CUSTOM on manual edit
• AudioModeToggle — STEREO / THX SPATIAL AUDIO switcher
• EqPanel — composes all above, dispatches Tauri IPC → D-Bus calls

Step 5 — Daemon Backend (synaptix-daemon)

• Expose org.synaptix.AudioDsp D-Bus interface
• Implement USB payload construction for PID 0x0568 (verify against _reference_openrazer/)
• Wire ApplyFullDspCurve into the USB write path

---

Acceptance Criteria

• AudioPreset, AudioMode, and EqCurve types defined in synaptix-protocol
• All preset curves have exactly 10 bands, all values within [-12, +12]
• Selecting a preset updates all 10 sliders simultaneously via ApplyFullDspCurve
• Manually moving any slider switches the active preset to Custom
• Reset button sets all bands to 0 dB
• STEREO / THX toggle dispatches SetActiveMode via D-Bus
• SVG polyline curve updates in real-time as sliders move
• All new protocol types have passing unit tests
• cargo clippy and cargo fmt pass with no warnings

References

• Razer Kraken V4 Pro OLED Hub PID: 0x0568
• Reference: _reference_openrazer/ (for USB payload bytes only — do not port Python architecture)
• Existing haptics D-Bus proxy as implementation pattern