EncoderEQComponent.py

# http://remotescripts.blogspot.com
"""
Customized APC40 control surface script
Copyright (C) 2010 Hanz Petrov <hanz.petrov@gmail.com>
Additional modification for Ableton Live 9 - Fabrizio Poce 2013 - <http://www.fabriziopoce.com/>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
"""

# emacs-mode: -*- python-*-
# http://remotescripts.blogspot.com

import Live
from _Framework.ControlSurfaceComponent import ControlSurfaceComponent
from _Framework.ButtonElement import ButtonElement
from _Framework.EncoderElement import EncoderElement
from _Framework.MixerComponent import MixerComponent 

from _Generic.Devices import *

# 4 ticks x 100ms/tick = 400ms, matching ToggleMomentaryChannelStripComponent.py:8
# so the EQ kill-switch dual behavior feels identical to the v1.0 Solo / Mute one.
LONG_PRESS_DELAY = 4

EQ_DEVICES = {# Eq8 has 8 bands; we use bands 1, 2, 8 → Low / Mid / High so the Highs
              # land on the topmost band (last in the spectrum) per UAT 2026-05-04.
              'Eq8': {'Gains': ['1 Gain A', '2 Gain A', '8 Gain A'],
                      'Cuts': ['1 Filter On A', '2 Filter On A', '8 Filter On A']},
              'FilterEQ3': {'Gains': ['GainLo','GainMid','GainHi'],
                            'Cuts': ['LowOn','MidOn','HighOn']},
              'AudioEffectGroupDevice': {'Gains': [('Macro %i' % (index + 2)) for index in range(3) ], #last 3 buttons of top row
                                         'Cuts': [('Macro %i' % (index + 6)) for index in range(3) ]}, #last 3 buttons of bottom row
              # Channel EQ (Live 11+) — band gains land on the same encoders as FilterEQ3 (5/6/7) for muscle-memory
              # consistency. Channel EQ has no per-band on/off, so 'Cuts' is empty and the kill buttons stay dark.
              # Mid Freq / Output Gain / Highpass On are wired separately by EncoderEQComponent (see CHANNEL_EQ_EXTRAS).
              'ChannelEq': {'Gains': ['Low Gain', 'Mid Gain', 'High Gain'],
                            'Cuts': []},
              }

# Eq8 extras — controls that take the top row of the Track Control section
# (encoders 0/1/2/3) plus encoder 4 (Output, directly below encoder 0):
#   - Encoder 0 (top-left)         → Scale
#   - Encoder 1 / 2 / 3 (top row)  → Low / Mid / High band frequency (bands 1, 2, 8)
#   - Encoder 4 (bottom-left)      → Output
#   - Encoders 5 / 6 / 7 (bottom)  → Low / Mid / High gain — already wired via EQ_DEVICES['Eq8'].Gains
# Parameter names are best-effort; on first detection EncoderEQComponent dumps them
# to Log.txt under '[Eq8]' so they can be verified after one UAT activation.
EQ8_EXTRAS = {
    'Scale': 'Scale',
    # Verified via Log.txt dump on UAT 2026-05-04 — Eq8's output trim is
    # named 'Output' (same as ChannelEq). 'Output Gain' was the initial
    # guess and silently no-op'd on encoder 4.
    'Output': 'Output',
    'LowFreq': '1 Frequency A',
    'MidFreq': '2 Frequency A',
    'HighFreq': '8 Frequency A',
}

# Channel EQ extras — controls that don't fit the gain/cut shape:
#   - Encoder 0 ("very first encoder in the first row")    → Mid Freq (the user's "split frequency")
#   - Encoder 4 ("encoder to the left" of the band knobs)  → Output (output trim)
#   - Pan button (buttons[0], directly below encoder 4)    → Highpass on/off (replaces the lock button while ChannelEq is active)
# Parameter names verified via Log.txt dump on UAT 2026-05-04 — the output trim
# is named 'Output' (not 'Output Gain' as initially guessed).
CHANNEL_EQ_EXTRAS = {
    'Output': 'Output',
    'MidFreq': 'Mid Freq',
    'HighpassOn': 'Highpass On',
}
FILTER_DEVICES = {# Live 9/10 Auto Filter (legacy class). Live 11+ uses AutoFilter2 below.
                  'AutoFilter': {'Frequency': 'Frequency',
                                 'Resonance': 'Resonance'},
                  # Live 11+ Auto Filter (rebuilt class, same param names).
                  'AutoFilter2': {'Frequency': 'Frequency',
                                  'Resonance': 'Resonance'},
                  'Operator': {'Frequency': 'Filter Freq',
                               'Resonance': 'Filter Res'},
                  'OriginalSimpler': {'Frequency': 'Filter Freq',
                                      'Resonance': 'Filter Res'},
                  'MultiSampler': {'Frequency': 'Filter Freq',
                                   'Resonance': 'Filter Res'},
                  'UltraAnalog': {'Frequency': 'F1 Freq',
                                  'Resonance': 'F1 Resonance'},
                  'StringStudio': {'Frequency': 'Filter Freq',
                                   'Resonance': 'Filter Reso'},
                  'AudioEffectGroupDevice': {'Frequency': 'Macro 1',
                                             'Resonance': 'Macro 5'}}#,
                  #'FilterEQ3': {'Frequency': 'FreqLo',
                                #'Resonance': 'FreqHi'}}

class TrackEQComponent(ControlSurfaceComponent):
    """ Class representing a track's EQ, it attaches to the last EQ device in the track """

    def __init__(self):
        ControlSurfaceComponent.__init__(self)
        self._track = None
        self._device = None
        self._gain_controls = None
        self._cut_buttons = None
        return

    def disconnect(self):
        if self._gain_controls != None:
            for control in self._gain_controls:
                control.release_parameter()

            self._gain_controls = None
        if self._cut_buttons != None:
            for button in self._cut_buttons:
                button.remove_value_listener(self._cut_value)

        self._cut_buttons = None
        if self._track != None:
            self._track.remove_devices_listener(self._on_devices_changed)
            self._track = None
        self._device = None
        if self._device != None:
            device_dict = EQ_DEVICES[self._device.class_name]
            if 'Cuts' in list(device_dict.keys()):
                cut_names = device_dict['Cuts']
                for cut_name in cut_names:
                    parameter = get_parameter_by_name(self._device, cut_name)
                    if parameter != None and parameter.value_has_listener(self._on_cut_changed):
                        parameter.remove_value_listener(self._on_cut_changed)

        return

    def on_enabled_changed(self):
        self.update()

    def set_track(self, track):
        if not (track == None or isinstance(track, Live.Track.Track)):
            raise AssertionError
        if self._track != None:
            self._track.remove_devices_listener(self._on_devices_changed)
            if self._gain_controls != None and self._device != None:
                for control in self._gain_controls:
                    control.release_parameter()

        self._track = track
        self._track != None and self._track.add_devices_listener(self._on_devices_changed)
        self._on_devices_changed()
        return

    def set_cut_buttons(self, buttons):
        if not (buttons == None or isinstance(buttons, tuple)):
            raise AssertionError
        if buttons != self._cut_buttons and self._cut_buttons != None:
            for button in self._cut_buttons:
                button.remove_value_listener(self._cut_value)

        self._cut_buttons = buttons
        if self._cut_buttons != None:
            for button in self._cut_buttons:
                button.add_value_listener(self._cut_value, identify_sender=True)

        self.update()
        return

    def set_gain_controls(self, controls):
        if not (controls == None or isinstance(controls, tuple)):
            raise AssertionError
        if self._device != None and self._gain_controls != None:
            for control in self._gain_controls:
                control.release_parameter()

        if controls != None:
            for control in controls:
                if not isinstance(control, EncoderElement):
                    raise AssertionError

        self._gain_controls = controls
        self.update()
        return

    def update(self):
        super(TrackEQComponent, self).update()
        if self.is_enabled() and self._device != None:
            device_dict = EQ_DEVICES[self._device.class_name]
            if self._gain_controls != None:
                gain_names = device_dict['Gains']
                for index in range(len(self._gain_controls)):
                    self._gain_controls[index].release_parameter()
                    if len(gain_names) > index:
                        parameter = get_parameter_by_name(self._device, gain_names[index])
                        if parameter != None:
                            self._gain_controls[index].connect_to(parameter)

            if self._cut_buttons != None and 'Cuts' in list(device_dict.keys()):
                cut_names = device_dict['Cuts']
                for index in range(len(self._cut_buttons)):
                    self._cut_buttons[index].turn_off()
                    if len(cut_names) > index:
                        parameter = get_parameter_by_name(self._device, cut_names[index])
                        if parameter != None:
                            if parameter.value == 0.0:
                                self._cut_buttons[index].turn_on()
                            if not parameter.value_has_listener(self._on_cut_changed):
                                parameter.add_value_listener(self._on_cut_changed)

        else:
            if self._cut_buttons != None:
                for button in self._cut_buttons:
                    if button != None:
                        button.turn_off()

            if self._gain_controls != None:
                for control in self._gain_controls:
                    control.release_parameter()

        return

    def _cut_value(self, value, sender):
        if not sender in self._cut_buttons:
            raise AssertionError
        if not value in range(128):
            raise AssertionError
        if self.is_enabled() and self._device != None:
            if not sender.is_momentary() or value != 0:
                device_dict = EQ_DEVICES[self._device.class_name]
                if 'Cuts' in list(device_dict.keys()):
                    cut_names = device_dict['Cuts']
                    index = list(self._cut_buttons).index(sender)
                    parameter = index in range(len(cut_names)) and get_parameter_by_name(self._device, cut_names[index])
                    parameter.value = parameter != None and parameter.is_enabled and float(int(parameter.value + 1) % 2)
        return

    def _on_devices_changed(self):
        if self._device != None:
            device_dict = EQ_DEVICES[self._device.class_name]
            if 'Cuts' in list(device_dict.keys()):
                cut_names = device_dict['Cuts']
                for cut_name in cut_names:
                    parameter = get_parameter_by_name(self._device, cut_name)
                    if parameter != None and parameter.value_has_listener(self._on_cut_changed):
                        parameter.remove_value_listener(self._on_cut_changed)

        self._device = None
        if self._track != None:
            for index in range(len(self._track.devices)):
                device = self._track.devices[-1 * (index + 1)]
                if device.class_name in list(EQ_DEVICES.keys()):
                    self._device = device
                    break

        self.update()
        return

    def _on_cut_changed(self):
        if not self._device != None:
            raise AssertionError
        raise 'Cuts' in list(EQ_DEVICES[self._device.class_name].keys()) or AssertionError
        cut_names = self.is_enabled() and self._cut_buttons != None and EQ_DEVICES[self._device.class_name]['Cuts']
        for index in range(len(self._cut_buttons)):
            self._cut_buttons[index].turn_off()
            if len(cut_names) > index:
                parameter = get_parameter_by_name(self._device, cut_names[index])
                if parameter != None and parameter.value == 0.0:
                    self._cut_buttons[index].turn_on()

        return

class TrackFilterComponent(ControlSurfaceComponent):
    """ Class representing a track's filter, attaches to the last filter in the track """

    def __init__(self):
        ControlSurfaceComponent.__init__(self)
        self._track = None
        self._device = None
        self._freq_control = None
        self._reso_control = None
        return

    def disconnect(self):
        if self._freq_control != None:
            self._freq_control.release_parameter()
            self._freq_control = None
        if self._reso_control != None:
            self._reso_control.release_parameter()
            self._reso_control = None
        if self._track != None:
            self._track.remove_devices_listener(self._on_devices_changed)
            self._track = None
        self._device = None
        return

    def on_enabled_changed(self):
        self.update()

    def set_track(self, track):
        if not (track == None or isinstance(track, Live.Track.Track)):
            raise AssertionError
        if self._track != None:
            self._track.remove_devices_listener(self._on_devices_changed)
            if self._device != None:
                if self._freq_control != None:
                    self._freq_control.release_parameter()
                if self._reso_control != None:
                    self._reso_control.release_parameter()
        self._track = track
        self._track != None and self._track.add_devices_listener(self._on_devices_changed)
        self._on_devices_changed()
        return

    def set_filter_controls(self, freq, reso):
        if not isinstance(freq, EncoderElement):
            raise AssertionError
        if not isinstance(freq, EncoderElement):
            raise AssertionError
        if self._device != None:
            self._freq_control != None and self._freq_control.release_parameter()
        self._reso_control != None and self._reso_control.release_parameter()
        self._freq_control = freq
        self._reso_control = reso
        self.update()
        return

    def update(self):
        super(TrackFilterComponent, self).update()
        if self.is_enabled() and self._device != None:
            device_dict = FILTER_DEVICES[self._device.class_name]
            if self._freq_control != None:
                self._freq_control.release_parameter()
                parameter = get_parameter_by_name(self._device, device_dict['Frequency'])
                if parameter != None:
                    self._freq_control.connect_to(parameter)
            if self._reso_control != None:
                self._reso_control.release_parameter()
                parameter = get_parameter_by_name(self._device, device_dict['Resonance'])
                if parameter != None:
                    self._reso_control.connect_to(parameter)
        return

    def _on_devices_changed(self):
        self._device = None
        if self._track != None:
            for index in range(len(self._track.devices)):
                device = self._track.devices[-1 * (index + 1)]
                if device.class_name in list(FILTER_DEVICES.keys()):
                    self._device = device
                    break

        self.update()
        return

class SpecialTrackEQComponent(TrackEQComponent): #added to override _cut_value

    def __init__(self, parent):
        TrackEQComponent.__init__(self)
        self._ignore_cut_buttons = False
        self._parent = parent
        # Toggle / momentary state for the EQ kill switches in TRACK CONTROL MODE 3
        # (Shift + Send B). Mirrors the v1.0 Solo / Mute state machine in
        # ToggleMomentaryChannelStripComponent. State arrays are sized to match
        # the wired cut-button count by set_cut_buttons.
        self._cut_ticks_delay = []
        self._cut_state_before_press = []
        self._cut_momentary_active = []
        self._register_timer_callback(self._on_timer)

    def disconnect(self):
        # Revert any in-flight momentary holds so the parameter doesn't get stuck
        # in the just-pressed state.
        if self._cut_buttons is not None and self._device is not None:
            device_dict = EQ_DEVICES.get(self._device.class_name, {})
            cut_names = device_dict.get('Cuts', [])
            for i in range(len(self._cut_buttons)):
                if i < len(self._cut_momentary_active) and self._cut_momentary_active[i]:
                    if i < len(cut_names):
                        parameter = get_parameter_by_name(self._device, cut_names[i])
                        if parameter is not None:
                            try:
                                parameter.value = self._cut_state_before_press[i]
                            except Exception:
                                pass
                    self._cut_momentary_active[i] = False
        try:
            self._unregister_timer_callback(self._on_timer)
        except Exception:
            pass
        TrackEQComponent.disconnect(self)

    def set_cut_buttons(self, buttons):
        # Revert any momentary hold on the OUTGOING buttons before swapping —
        # otherwise the captured state gets dropped when the array is resized.
        if self._cut_buttons is not None and self._device is not None:
            device_dict = EQ_DEVICES.get(self._device.class_name, {})
            cut_names = device_dict.get('Cuts', [])
            for i in range(len(self._cut_buttons)):
                if i < len(self._cut_momentary_active) and self._cut_momentary_active[i]:
                    if i < len(cut_names):
                        parameter = get_parameter_by_name(self._device, cut_names[i])
                        if parameter is not None:
                            try:
                                parameter.value = self._cut_state_before_press[i]
                            except Exception:
                                pass
        TrackEQComponent.set_cut_buttons(self, buttons)
        n = len(buttons) if buttons is not None else 0
        self._cut_ticks_delay = [-1] * n
        self._cut_state_before_press = [0.0] * n
        self._cut_momentary_active = [False] * n

    def _on_timer(self):
        if not self.is_enabled():
            return
        for i in range(len(self._cut_ticks_delay)):
            if self._cut_ticks_delay[i] > -1:
                if self._cut_ticks_delay[i] == 0:
                    self._cut_momentary_active[i] = True
                self._cut_ticks_delay[i] -= 1

    def _cut_value(self, value, sender):
        assert (sender in self._cut_buttons)
        assert (value in range(128))
        if self._ignore_cut_buttons:
            return
        if not (self.is_enabled() and self._device is not None):
            return
        device_dict = EQ_DEVICES[self._device.class_name]
        if 'Cuts' not in device_dict:
            return
        cut_names = device_dict['Cuts']
        index = list(self._cut_buttons).index(sender)
        if index >= len(cut_names) or index >= len(self._cut_ticks_delay):
            return
        parameter = get_parameter_by_name(self._device, cut_names[index])
        if parameter is None:
            return
        if value != 0:
            # Press — capture pre-press state, toggle, start countdown.
            try:
                self._cut_state_before_press[index] = float(parameter.value)
            except Exception:
                return
            if parameter.value > 0:
                parameter.value = 0
            else:
                parameter.value = 1
            if self._device.class_name == 'AudioEffectGroupDevice':
                parameter.value = parameter.value * 127
            self._cut_ticks_delay[index] = LONG_PRESS_DELAY
        else:
            # Release — if hold crossed the threshold, revert to captured state.
            if self._cut_momentary_active[index]:
                try:
                    parameter.value = self._cut_state_before_press[index]
                except Exception:
                    pass
                self._cut_momentary_active[index] = False
            self._cut_ticks_delay[index] = -1



    def update(self):
        if (self.is_enabled() and (self._device != None)):
            device_dict = EQ_DEVICES[self._device.class_name]
            if (self._gain_controls != None):
                gain_names = device_dict['Gains']
                for index in range(len(self._gain_controls)):
                    self._gain_controls[index].release_parameter()
                    if (len(gain_names) > index):
                        parameter = get_parameter_by_name(self._device, gain_names[index])
                        if (parameter != None):
                            self._gain_controls[index].connect_to(parameter)

            if ((self._cut_buttons != None) and ('Cuts' in list(device_dict.keys()))):
                cut_names = device_dict['Cuts']
                for index in range(len(self._cut_buttons)):
                    self._cut_buttons[index].turn_off()
                    if (len(cut_names) > index):
                        parameter = get_parameter_by_name(self._device, cut_names[index])
                        if (parameter != None):
                            # LED on = band ON (parameter.value > 0). Same convention
                            # for every device — Eq8, FilterEQ3, AudioEffectGroupDevice.
                            # The original code inverted the rule for FilterEQ3 ("LED on
                            # means kill engaged"), which conflicted with Eq8 / AEG
                            # ("LED on means band passing") — UAT 2026-05-04 reported
                            # the inversion as a bug.
                            if (parameter.value > 0.0):
                                self._cut_buttons[index].turn_on()
                            if (not parameter.value_has_listener(self._on_cut_changed)):
                                parameter.add_value_listener(self._on_cut_changed)

        else:
            if (self._cut_buttons != None):
                for button in self._cut_buttons:
                    if (button != None):
                        button.turn_off()

            if (self._gain_controls != None):
                for control in self._gain_controls:
                    control.release_parameter()

        #self._rebuild_callback()

    def _on_cut_changed(self):
        assert (self._device != None)
        assert ('Cuts' in list(EQ_DEVICES[self._device.class_name].keys()))
        if (self.is_enabled() and (self._cut_buttons != None)):
            cut_names = EQ_DEVICES[self._device.class_name]['Cuts']
            for index in range(len(self._cut_buttons)):
                self._cut_buttons[index].turn_off()
                if (len(cut_names) > index):
                    parameter = get_parameter_by_name(self._device, cut_names[index])
                    if (parameter != None):
                        # Standard convention across all devices: LED on = band ON.
                        # Symmetric with the same rule in update() above.
                        if (parameter.value > 0.0):
                            self._cut_buttons[index].turn_on()

    def _on_devices_changed(self):
        if (self._device != None):
            device_dict = EQ_DEVICES[self._device.class_name]
            if ('Cuts' in list(device_dict.keys())):
                cut_names = device_dict['Cuts']
                for cut_name in cut_names:
                    parameter = get_parameter_by_name(self._device, cut_name)
                    if ((parameter != None) and parameter.value_has_listener(self._on_cut_changed)):
                        parameter.remove_value_listener(self._on_cut_changed)

        self._device = None
        if (self._track != None):
            for index in range(len(self._track.devices)):
                device = self._track.devices[(-1 * (index + 1))]
                if (device.class_name in list(EQ_DEVICES.keys())):
                    self._device = device
                    break

        self.update()

class SpecialTrackFilterComponent(TrackFilterComponent): #added to override _cut_value
    __module__ = __name__
    __doc__ = " Class representing a track's filter, attaches to the last filter in the track "

    def __init__(self, parent):
        TrackFilterComponent.__init__(self)
        self._parent = parent                        


    def update(self):
        if (self.is_enabled() and (self._device != None)):
            device_dict = FILTER_DEVICES[self._device.class_name]
            if (self._freq_control != None):
                self._freq_control.release_parameter()
                parameter = get_parameter_by_name(self._device, device_dict['Frequency'])
                if (parameter != None):
                    self._freq_control.connect_to(parameter)
            if (self._reso_control != None):
                self._reso_control.release_parameter()
                parameter = get_parameter_by_name(self._device, device_dict['Resonance'])
                if (parameter != None):
                    self._reso_control.connect_to(parameter)
        #self._rebuild_callback()


    def _on_devices_changed(self):
        self._device = None
        if (self._track != None):
            for index in range(len(self._track.devices)):
                device = self._track.devices[(-1 * (index + 1))]
                if (device.class_name in list(FILTER_DEVICES.keys())):
                    self._device = device
                    break

        self.update()        

class EncoderEQComponent(ControlSurfaceComponent):
    __module__ = __name__
    __doc__ = " Class representing encoder EQ component "

    def __init__(self, mixer, parent, messenger=None):
        ControlSurfaceComponent.__init__(self)
        assert isinstance(mixer, MixerComponent)
        self._param_controls = None
        self._mixer = mixer
        self._buttons = []
        self._param_controls = None
        self._lock_button = None
        self._last_mode = 0
        self._is_locked = False
        self._ignore_buttons = False
        self._track = None
        self._strip = None
        self._parent = parent
        # Status-bar messenger + transition tracker (quick-260505-sb9).
        # EQ Smart Control mode is "active" whenever the selected track
        # has an EQ-recognized device (Eq8 / FilterEQ3 / ChannelEq /
        # AudioEffectGroupDevice) AND we are enabled. Track the last
        # active device so the messenger fires once per real transition.
        self._messenger = messenger
        self._last_active_eq_device = None
        # Hardware-side param-message listeners (quick-260505-sb9 Task 3).
        # Each entry: (control, callback). Built in _setup_*_extras /
        # _setup_eq8_extras / _track_filter binding paths; torn down at the
        # head of _update_controls_and_buttons (full-rebuild model) and in
        # disconnect.
        self._param_message_listeners = []
        self._track_eq = SpecialTrackEQComponent(parent)
        self._track_filter = SpecialTrackFilterComponent(parent)
        # Channel EQ (Live 11+) state — extras that don't fit the gain/cut shape.
        self._channel_eq_device = None
        self._highpass_button = None
        self._highpass_parameter = None
        self._highpass_listener_attached = False
        # FilterEQ3 state — Pan button toggles the device's Slope parameter (24 ↔ 48 dB/oct).
        self._slope_button = None
        self._slope_parameter = None
        self._slope_listener_attached = False
        self._filter_eq3_logged = False  # one-shot Log.txt dump of FilterEQ3 param names
        # Eq8 state — top-row encoders (0/1/2/3) + encoder 4 take Scale / band freqs / Output.
        # Encoders 5 and 7 (Low / High Gain) optionally swap to Q on filter types without a
        # gain parameter (LP / HP / Notch); a value listener on each band's Filter Type
        # parameter re-evaluates the swap when the user changes type in Live's UI.
        self._eq8_device = None
        self._eq8_filter_type_listeners = []  # parameters we listen to for filter-type changes

    def disconnect(self):
        # Hardware-side param-message listeners (quick-260505-sb9).
        # Tear down BEFORE the framework teardowns to avoid stale fires
        # against half-disconnected encoders.
        self._teardown_param_message_listeners()
        self._teardown_channel_eq_extras()
        self._teardown_slope_button()
        self._teardown_eq8_extras()
        self._param_controls = None
        self._mixer = None
        self._buttons = None
        self._param_controls = None
        self._lock_button = None
        self._track = None
        self._strip = None
        self._parent = None
        self._track_eq = None
        self._track_filter = None
        self._channel_eq_device = None
        self._eq8_device = None
        self._messenger = None
        self._last_active_eq_device = None

    def update(self):
        pass


    def refresh_button_leds(self):
        # Quick-260505-lqz iteration: repaint kill-state + Pan-button LEDs
        # without re-running the full _update_controls_and_buttons setup.
        # Used by EncoderUserModesComponent on Shift-release to restore
        # kill-state LEDs after the single-active-LED indicator overrode
        # them during Shift hold. Pan-button mapping (highpass / slope /
        # lock) varies by EQ device class — each restorer is a no-op when
        # its respective binding isn't active.
        if not self.is_enabled():
            return
        if self._track_eq is not None:
            self._track_eq.update()
        # Pan-button LED restore — only one of these is "active" at a time
        # per the device-class branching in _update_controls_and_buttons.
        self._update_highpass_led()
        self._update_slope_led()
        if self._lock_button is not None:
            if self._is_locked:
                self._lock_button.turn_on()
            else:
                self._lock_button.turn_off()


    def set_controls_and_buttons(self, controls, buttons):
        assert ((controls == None) or (isinstance(controls, tuple) and (len(controls) == 8)))
        self._param_controls = controls
        assert ((buttons == None) or (isinstance(buttons, tuple)) or (len(buttons) == 4))
        self._buttons = buttons
        # NB: Pan button (buttons[0]) wiring is decided per-track inside
        # _update_controls_and_buttons so Channel EQ can claim it as the
        # Highpass switch — non-ChannelEq tracks fall back to lock.
        self._update_controls_and_buttons()


    def _update_controls_and_buttons(self):
        if self._param_controls is None or self._buttons is None:
            return
        # Tear down hardware-side param-message listeners FIRST so the
        # full-rebuild path below can re-attach against the new bindings
        # without orphaning the old ones (quick-260505-sb9).
        self._teardown_param_message_listeners()
        if self._is_locked != True:
            self._track = self.song().view.selected_track

        # EQ + sends wiring (always on, regardless of EQ device subclass).
        self._track_eq.set_track(self._track)
        cut_buttons = [self._buttons[1], self._buttons[2], self._buttons[3]]
        self._track_eq.set_cut_buttons(tuple(cut_buttons))
        self._track_eq.set_gain_controls(tuple([
            self._param_controls[5], self._param_controls[6], self._param_controls[7]
        ]))

        # Pan-button + encoder role hierarchy (per device class on the active EQ):
        #   ChannelEq  → encoders 0/4 = Mid Freq / Output, Pan = Highpass
        #   FilterEQ3  → Pan = Slope toggle (24 ↔ 48 dB/oct), encoders 0/4 = AutoFilter
        #   Eq8        → encoders 0/1/2/3 = Scale / 3× band Freq, encoder 4 = Output, Pan = lock
        #   anything   → encoders 0/4 = AutoFilter, Pan = lock (default)
        # Tear down ALL conditional bindings before deciding which to set up,
        # so switching tracks between device classes leaves no stale listener.
        eq_device = getattr(self._track_eq, '_device', None)
        eq_class = getattr(eq_device, 'class_name', None) if eq_device is not None else None
        channel_eq = self._detect_channel_eq()

        # Status-bar feedback (quick-260505-sb9). EQ Smart Control is
        # "active" whenever the track has an EQ-recognized device. Fire
        # show_mode once per real transition; identical-text dedup in
        # the messenger covers any spurious double-fire.
        active_device = channel_eq if channel_eq is not None else eq_device
        if self._messenger is not None:
            try:
                if active_device is not None and self._last_active_eq_device is None:
                    self._messenger.show_mode('EQ Smart Control', True)
                elif active_device is None and self._last_active_eq_device is not None:
                    self._messenger.show_mode('EQ Smart Control', False)
            except Exception:
                pass
        self._last_active_eq_device = active_device
        if channel_eq is not None:
            self._track_filter.set_track(None)
            self._teardown_channel_eq_extras()
            self._teardown_slope_button()
            self._teardown_eq8_extras()
            self._channel_eq_device = channel_eq
            self._setup_channel_eq_extras(channel_eq)
            self.set_lock_button(None)
        else:
            self._teardown_channel_eq_extras()
            self._channel_eq_device = None
            if eq_class == 'Eq8':
                # Eq8 takes encoders 0..4. Disable AutoFilter so it doesn't fight for 0/4.
                self._track_filter.set_track(None)
                self._teardown_slope_button()
                self._teardown_eq8_extras()
                self._eq8_device = eq_device
                self._setup_eq8_extras(eq_device)
                self.set_lock_button(self._buttons[0])
            elif eq_class == 'FilterEQ3':
                self._track_filter.set_track(self._track)
                self._track_filter.set_filter_controls(
                    self._param_controls[0], self._param_controls[4]
                )
                self._teardown_eq8_extras()
                self._eq8_device = None
                self._teardown_slope_button()
                self._setup_slope_button(self._buttons[0], eq_device)
                self.set_lock_button(None)
            else:
                self._track_filter.set_track(self._track)
                self._track_filter.set_filter_controls(
                    self._param_controls[0], self._param_controls[4]
                )
                self._teardown_eq8_extras()
                self._eq8_device = None
                self._teardown_slope_button()
                self.set_lock_button(self._buttons[0])

        if self._is_locked != True:
            self._strip = self._mixer._selected_strip
        if self._strip is not None:
            # On Eq8 the top-row encoders (1/2/3) drive band frequencies — must
            # NOT be re-bound to Send A/B/C, which would steal them right after
            # _setup_eq8_extras connects them. Pass None for sends so the strip
            # doesn't fight for the encoders. Other modes keep sends on 1/2/3.
            if eq_class == 'Eq8':
                self._strip.set_send_controls(None)
            else:
                self._strip.set_send_controls(tuple([
                    self._param_controls[1], self._param_controls[2], self._param_controls[3]
                ]))


    # --- Status-bar param-message wiring (quick-260505-sb9) --------------

    def _attach_param_message_listener(self, control, param):
        """Hook a hardware-side value listener on `control`. See
        DrumRackModeComponent / EncoderAutoFilterComponent for the
        identical pattern."""
        if self._messenger is None or control is None or param is None:
            return
        try:
            cb = self._messenger.make_hardware_value_callback(lambda p=param: p)
            control.add_value_listener(cb)
            self._param_message_listeners.append((control, cb))
        except Exception:
            pass

    def _teardown_param_message_listeners(self):
        for ctrl, cb in self._param_message_listeners:
            try:
                ctrl.remove_value_listener(cb)
            except Exception:
                pass
        self._param_message_listeners = []

    # --- Channel EQ helpers (Live 11+) -----------------------------------

    def _detect_channel_eq(self):
        if self._track is None:
            return None
        try:
            devices = list(self._track.devices)
        except Exception:
            return None
        for device in reversed(devices):
            if getattr(device, 'class_name', None) == 'ChannelEq':
                return device
        return None

    def _setup_channel_eq_extras(self, channel_eq):
        try:
            self._param_controls[0].release_parameter()
        except Exception:
            pass
        try:
            self._param_controls[4].release_parameter()
        except Exception:
            pass
        midfreq = get_parameter_by_name(channel_eq, CHANNEL_EQ_EXTRAS['MidFreq'])
        if midfreq is not None:
            try:
                self._param_controls[0].connect_to(midfreq)
                self._attach_param_message_listener(self._param_controls[0], midfreq)
            except Exception:
                pass
        output = get_parameter_by_name(channel_eq, CHANNEL_EQ_EXTRAS['Output'])
        if output is not None:
            try:
                self._param_controls[4].connect_to(output)
                self._attach_param_message_listener(self._param_controls[4], output)
            except Exception:
                pass
        self._setup_highpass_button(self._buttons[0], channel_eq)

    def _teardown_channel_eq_extras(self):
        if self._param_controls is not None:
            try:
                self._param_controls[0].release_parameter()
            except Exception:
                pass
            try:
                self._param_controls[4].release_parameter()
            except Exception:
                pass
        self._teardown_highpass_button()

    def _setup_highpass_button(self, button, channel_eq):
        self._teardown_highpass_button()
        if button is None or channel_eq is None:
            return
        hp = get_parameter_by_name(channel_eq, CHANNEL_EQ_EXTRAS['HighpassOn'])
        if hp is None:
            return
        self._highpass_button = button
        self._highpass_parameter = hp
        try:
            button.add_value_listener(self._highpass_value)
        except Exception:
            pass
        try:
            hp.add_value_listener(self._on_highpass_changed)
            self._highpass_listener_attached = True
        except Exception:
            pass
        self._update_highpass_led()

    def _teardown_highpass_button(self):
        if self._highpass_button is not None:
            try:
                self._highpass_button.remove_value_listener(self._highpass_value)
            except Exception:
                pass
            self._highpass_button = None
        if self._highpass_listener_attached and self._highpass_parameter is not None:
            try:
                self._highpass_parameter.remove_value_listener(self._on_highpass_changed)
            except Exception:
                pass
        self._highpass_listener_attached = False
        self._highpass_parameter = None

    def _highpass_value(self, value):
        if value == 0:
            return
        if self._highpass_parameter is None:
            return
        try:
            cur = float(self._highpass_parameter.value)
            self._highpass_parameter.value = 0.0 if cur > 0 else 1.0
        except Exception:
            pass
        # Status-bar feedback (quick-260505-sb9). Read post-toggle value.
        if self._messenger is not None:
            try:
                on = float(self._highpass_parameter.value) > 0
                self._messenger.show_event('Highpass: ' + ('on' if on else 'off'))
            except Exception:
                pass

    def _on_highpass_changed(self):
        self._update_highpass_led()

    def _update_highpass_led(self):
        if self._highpass_button is None or self._highpass_parameter is None:
            return
        try:
            if float(self._highpass_parameter.value) > 0:
                self._highpass_button.turn_on()
            else:
                self._highpass_button.turn_off()
        except Exception:
            pass

    # --- FilterEQ3 Slope toggle (Pan button on FilterEQ3 tracks) -----------

    def _setup_slope_button(self, button, filter_eq3):
        # One-shot Log.txt dump on first FilterEQ3 detection so the parameter
        # name guess is self-verifying — same pattern as the Channel EQ dump
        # in 5248cce that caught 'Output Gain' vs 'Output' (5660914).
        if not self._filter_eq3_logged:
            self._filter_eq3_logged = True
            try:
                self._parent.log_message('[FilterEQ3] params on detected device:')
                for p in filter_eq3.parameters:
                    self._parent.log_message('[FilterEQ3]   ' + repr(p.name))
            except Exception as e:
                self._parent.log_message('[FilterEQ3] params introspection failed: ' + str(e))
        self._teardown_slope_button()
        if button is None or filter_eq3 is None:
            return
        slope = get_parameter_by_name(filter_eq3, 'Slope')
        if slope is None:
            return
        self._slope_button = button
        self._slope_parameter = slope
        try:
            button.add_value_listener(self._slope_value)
        except Exception:
            pass
        try:
            slope.add_value_listener(self._on_slope_changed)
            self._slope_listener_attached = True
        except Exception:
            pass
        self._update_slope_led()

    def _teardown_slope_button(self):
        if self._slope_button is not None:
            try:
                self._slope_button.remove_value_listener(self._slope_value)
            except Exception:
                pass
            self._slope_button = None
        if self._slope_listener_attached and self._slope_parameter is not None:
            try:
                self._slope_parameter.remove_value_listener(self._on_slope_changed)
            except Exception:
                pass
        self._slope_listener_attached = False
        self._slope_parameter = None

    def _slope_value(self, value):
        if value == 0:
            return
        if self._slope_parameter is None:
            return
        try:
            cur = float(self._slope_parameter.value)
            self._slope_parameter.value = 0.0 if cur > 0 else 1.0
        except Exception:
            pass
        # Status-bar feedback (quick-260505-sb9). FilterEQ3 slope is a
        # 24/48 dB/oct toggle -- show the human-readable value, not 0/1.
        if self._messenger is not None:
            try:
                on = float(self._slope_parameter.value) > 0
                self._messenger.show_event('Slope: ' + ('48 dB/oct' if on else '24 dB/oct'))
            except Exception:
                pass

    def _on_slope_changed(self):
        self._update_slope_led()

    def _update_slope_led(self):
        # LED on = 48 dB/oct (the steeper / "doubled" slope, matching how
        # Live's UI darkens the Slope button when 48 is engaged).
        if self._slope_button is None or self._slope_parameter is None:
            return
        try:
            if float(self._slope_parameter.value) > 0:
                self._slope_button.turn_on()
            else:
                self._slope_button.turn_off()
        except Exception:
            pass

    # --- Eq8 top-row encoder takeover (Scale + 3× band freq + Output) ------

    def _setup_eq8_extras(self, eq8_device):
        # Release the five encoders we're about to take over so any prior
        # AutoFilter / appointed-device binding is dropped first.
        for idx in (0, 1, 2, 3, 4):
            try:
                self._param_controls[idx].release_parameter()
            except Exception:
                pass
        # Top row of the Track Control 2x4 grid: 0=Scale, 1=LowFreq, 2=MidFreq, 3=HighFreq.
        # Bottom row: 4=Output (the encoder directly below 0). Encoders 5/6/7 are
        # already wired to gains via _track_eq.set_gain_controls.
        connections = (
            (0, EQ8_EXTRAS['Scale']),
            (1, EQ8_EXTRAS['LowFreq']),
            (2, EQ8_EXTRAS['MidFreq']),
            (3, EQ8_EXTRAS['HighFreq']),
            (4, EQ8_EXTRAS['Output']),
        )
        for idx, param_name in connections:
            parameter = get_parameter_by_name(eq8_device, param_name)
            if parameter is not None:
                try:
                    self._param_controls[idx].connect_to(parameter)
                    self._attach_param_message_listener(self._param_controls[idx], parameter)
                except Exception:
                    pass
        # Bands 1 and 8: if the gain parameter is disabled (filter type has no gain
        # control — LP / HP / Notch), bind the gain encoder to Q instead.
        self._eq8_apply_q_overrides(eq8_device)
        # Listen for filter-type changes so the gain↔Q swap re-evaluates in real time.
        self._eq8_attach_filter_type_listeners(eq8_device)

    # EQ8 filter-type values that have no gain control (per Live's UI):
    #   0 = 48 dB Low Cut, 1 = 12 dB Low Cut, 4 = Notch,
    #   6 = 12 dB High Cut, 7 = 48 dB High Cut.
    # Types 2 (Low Shelf), 3 (Bell), 5 (High Shelf) DO have gain.
    # NB: parameter.is_enabled is unreliable here — Live keeps the gain
    # parameter `is_enabled = True` even on no-gain filter types, which is
    # why the original 1eff437 implementation always fell into the gain
    # branch (UAT 2026-05-04). Reading the filter-type value directly is
    # the reliable test.
    EQ8_NO_GAIN_TYPES = (0, 1, 4, 6, 7)

    def _eq8_apply_q_overrides(self, eq8_device):
        # band → encoder index that drives this band's gain (per the EQ_DEVICES['Eq8'].Gains
        # mapping: bands 1, 2, 8 land on encoders 5, 6, 7 respectively).
        for band, encoder_idx in ((1, 5), (8, 7)):
            gain_param = get_parameter_by_name(eq8_device, '%i Gain A' % band)
            ft_param = get_parameter_by_name(eq8_device, '%i Filter Type A' % band)
            if gain_param is None:
                continue
            ft_value = -1
            if ft_param is not None:
                try:
                    ft_value = int(ft_param.value)
                except Exception:
                    ft_value = -1
            no_gain = ft_value in self.EQ8_NO_GAIN_TYPES
            if not no_gain:
                # Filter type has gain — bind the encoder to the gain parameter.
                # (Re-assert even when _track_eq.set_gain_controls already wired
                # it, so a previous Q override gets replaced when the user
                # switches the band to a type with gain.)
                try:
                    self._param_controls[encoder_idx].release_parameter()
                    self._param_controls[encoder_idx].connect_to(gain_param)
                    self._attach_param_message_listener(self._param_controls[encoder_idx], gain_param)
                except Exception:
                    pass
            else:
                # Filter type has no gain — bind to Q instead.
                q_param = get_parameter_by_name(eq8_device, '%i Q A' % band)
                if q_param is not None:
                    try:
                        self._param_controls[encoder_idx].release_parameter()
                        self._param_controls[encoder_idx].connect_to(q_param)
                        self._attach_param_message_listener(self._param_controls[encoder_idx], q_param)
                    except Exception:
                        pass

    def _eq8_attach_filter_type_listeners(self, eq8_device):
        # Detach any existing listeners first, then re-attach against the (possibly
        # new) device's filter-type parameters.
        self._eq8_detach_filter_type_listeners()
        for band in (1, 8):
            ft_param = get_parameter_by_name(eq8_device, '%i Filter Type A' % band)
            if ft_param is None or not hasattr(ft_param, 'add_value_listener'):
                continue
            try:
                ft_param.add_value_listener(self._on_eq8_filter_type_changed)
                self._eq8_filter_type_listeners.append(ft_param)
            except Exception:
                pass

    def _eq8_detach_filter_type_listeners(self):
        for param in self._eq8_filter_type_listeners:
            if hasattr(param, 'remove_value_listener'):
                try:
                    param.remove_value_listener(self._on_eq8_filter_type_changed)
                except Exception:
                    pass
        self._eq8_filter_type_listeners = []

    def _on_eq8_filter_type_changed(self):
        # User flipped a tracked band's filter type — re-evaluate gain↔Q binding.
        if self._eq8_device is not None:
            self._eq8_apply_q_overrides(self._eq8_device)

    def _teardown_eq8_extras(self):
        self._eq8_detach_filter_type_listeners()
        if self._param_controls is None:
            return
        # Release encoders 0..4 (extras) AND 5/7 (gain↔Q overrides) so the next
        # mode/track can re-bind them cleanly. Encoder 6 (Mid Gain) stays on
        # _track_eq's gain wiring — never overridden.
        for idx in (0, 1, 2, 3, 4, 5, 7):
            try:
                self._param_controls[idx].release_parameter()
            except Exception:
                pass


    def on_track_list_changed(self):
        self.on_selected_track_changed()


    def on_selected_track_changed(self):
        if self.is_enabled():
            if self._is_locked != True:
                self._update_controls_and_buttons()


    def on_enabled_changed(self):
        # When the EncoderUserModesComponent disables this sub-mode, treat it
        # as a mode-exit if we were previously messaged-as-active. Mirrors
        # the pattern used in EncoderAutoFilterComponent.
        if not self.is_enabled():
            if self._messenger is not None and self._last_active_eq_device is not None:
                try:
                    self._messenger.show_mode('EQ Smart Control', False)
                except Exception:
                    pass
            self._last_active_eq_device = None
        self.update()

    def set_lock_button(self, button):
        assert ((button == None) or isinstance(button, ButtonElement))
        if (self._lock_button != None):
            self._lock_button.remove_value_listener(self._lock_value)
            self._lock_button = None
        self._lock_button = button
        if (self._lock_button != None):
            self._lock_button.add_value_listener(self._lock_value)
            if self._is_locked:
                self._lock_button.turn_on()
            else:
                self._lock_button.turn_off()            


    def _lock_value(self, value):
        assert (self._lock_button != None)
        assert (value != None)
        assert isinstance(value, int)
        if ((not self._lock_button.is_momentary()) or (value != 0)):
        #if (value != 0):
            if self._ignore_buttons == False:
                if self._is_locked:
                    self._is_locked = False
                    self._mixer._is_locked = False
                    self._lock_button.turn_off()
                    self._mixer.on_selected_track_changed()
                    self.on_selected_track_changed()
                else:
                    self._is_locked = True
                    self._mixer._is_locked = True
                    self._lock_button.turn_on()



# local variables:
# tab-width: 4