gui_settings.py

"""DropGain preferences page."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any

import tkinter as tk

import customtkinter as ctk

from analysis import (
    BASS_TREATMENT_CHOICES,
    BASS_TREATMENT_LEVEL_TRIM,
    BASS_TREATMENT_LOW_END_EQ,
    BASS_TREATMENT_OFF,
    MAX_LOW_END_EQ_MAX_DB,
    MIN_LOW_END_EQ_MAX_DB,
    MAX_LOW_END_EQ_SHELF_HZ,
    MIN_LOW_END_EQ_SHELF_HZ,
    LOSSLESS_MIN_ABS_GAIN_DB,
    MAX_LOUD_SECTION_HOP_SECONDS,
    MAX_ANALYSIS_WORKER_THREADS,
    MAX_LOUD_SECTION_WINDOW_SECONDS,
    MAX_BASS_MAX_BOOST_REDUCTION_DB,
    MAX_BASS_PENALTY_THRESHOLD_DB,
    MIN_LOUD_SECTION_HOP_SECONDS,
    MIN_ANALYSIS_WORKER_THREADS,
    MIN_LOUD_SECTION_WINDOW_SECONDS,
    MIN_BASS_MAX_BOOST_REDUCTION_DB,
    MIN_BASS_PENALTY_THRESHOLD_DB,
    LIMITER_ENGINE_CHOICES,
    MP3_MIN_ABS_GAIN_DB,
    normalize_bass_treatment,
    NORMALIZATION_MODE_CHOICES,
    OUTPUT_FORMAT_MODE_CHOICES,
    PROCESSED_SUFFIX,
    default_csv_path,
    output_format_mode_tooltip,
)
from gui_theme import (
    ACCENT,
    ACCENT_HOVER,
    BG_CARD,
    BG_FIELD,
    BG_MAIN,
    BORDER_COLOR,
    BUTTON_CORNER_RADIUS,
    BUTTON_SECONDARY_ACTIVE,
    BUTTON_SECONDARY_BG,
    BUTTON_SECONDARY_HOVER,
    BUTTON_TEXT_DARK,
    CARD_CORNER_RADIUS,
    ERROR_FG,
    FG_MAIN,
    FG_MUTED,
    ICE_DIM,
    PAGE_PADX,
    PREFERENCES_LAYOUT_DEBOUNCE_MS,
    PREFERENCES_SINGLE_COLUMN_WIDTH,
    PREFERENCES_TWO_COLUMN_WIDTH,
    SECTION_GAP,
    SPACE_3,
    SUCCESS_FG,
    TYPE_BODY,
    TYPE_LABEL,
)
from gui_utils import apply_hand_cursor, logical_widget_width, pointer_inside_widget, wire_ctk_button_press

if TYPE_CHECKING:
    from gui_tk import App

# Slightly larger than the global type scale for readable settings on HiDPI displays.
SETTINGS_TITLE = 18
SETTINGS_HEAD = TYPE_BODY
SETTINGS_TEXT = TYPE_BODY
SETTINGS_HINT = TYPE_LABEL


class CTkNumberInput(ctk.CTkFrame):
    """Small CustomTkinter numeric input with minus/plus controls."""

    _INCOMPLETE = {"", "-", ".", "-.", "+", "+."}

    def __init__(
        self,
        master: Any,
        *,
        variable: tk.Variable,
        from_: float,
        to: float,
        increment: float,
        width: int = 76,
        integer: bool = False,
        entry_font: Any = None,
        button_font: Any = None,
        app: Any = None,
    ) -> None:
        super().__init__(master, fg_color="transparent")
        self._variable = variable
        self._from = float(from_)
        self._to = float(to)
        self._increment = float(increment)
        self._integer = integer
        self._app = app
        self._syncing = False
        # CTkEntry calls textvariable.get() on every edit. DoubleVar/IntVar raise TclError while the box is empty, so the entry holds a StringVar.
        self._text = tk.StringVar(master=self, value=self._format_value(self._read_variable()))
        self._text_trace: str | None = None
        self._var_trace: str | None = None

        self.btn_minus = ctk.CTkButton(
            self,
            text="−",
            width=26,
            height=30,
            fg_color=BUTTON_SECONDARY_BG,
            hover_color=BUTTON_SECONDARY_HOVER,
            border_width=0,
            text_color=FG_MAIN,
            font=button_font or ("Segoe UI", 13, "bold"),
            command=lambda: self._step(-self._increment),
            corner_radius=BUTTON_CORNER_RADIUS,
        )
        self.btn_minus.pack(side="left")

        self.entry = ctk.CTkEntry(
            self,
            textvariable=self._text,
            width=width,
            height=30,
            fg_color=BG_FIELD,
            border_color=BORDER_COLOR,
            text_color=FG_MAIN,
            font=entry_font or ("Segoe UI", 12),
        )
        self.entry.pack(side="left", padx=4)
        self.entry.bind("<Button-1>", self._on_click)
        self.entry.bind("<FocusIn>", self._on_focus_in)
        self.entry.bind("<FocusOut>", self._commit_text)
        self.entry.bind("<Return>", self._commit_text)
        self._text_trace = self._text.trace_add("write", self._on_text_changed)
        self._var_trace = self._variable.trace_add("write", self._on_variable_changed)

        self.btn_plus = ctk.CTkButton(
            self,
            text="+",
            width=26,
            height=30,
            fg_color=BUTTON_SECONDARY_BG,
            hover_color=BUTTON_SECONDARY_HOVER,
            border_width=0,
            text_color=FG_MAIN,
            font=button_font or ("Segoe UI", 13, "bold"),
            command=lambda: self._step(self._increment),
            corner_radius=BUTTON_CORNER_RADIUS,
        )
        self.btn_plus.pack(side="left")

        for step_button in (self.btn_minus, self.btn_plus):
            apply_hand_cursor(step_button)
            step_button._dropgain_accent = False  # type: ignore[attr-defined]
            if self._app is not None:
                self._app._wire_button_hover(step_button)

            def _restore_stepper(b: ctk.CTkButton = step_button) -> None:
                b.configure(fg_color=BUTTON_SECONDARY_BG, hover_color=BUTTON_SECONDARY_BG)
                tween = getattr(b, "_dropgain_button_tween", None)
                if tween is not None and pointer_inside_widget(b):
                    tween(True)

            wire_ctk_button_press(
                step_button,
                lambda: BUTTON_SECONDARY_ACTIVE,
                restore=_restore_stepper if self._app is not None else lambda b=step_button: b.configure(
                    fg_color=BUTTON_SECONDARY_BG,
                    hover_color=BUTTON_SECONDARY_HOVER,
                ),
            )

    def configure_state(self, state: str) -> None:
        cursor = "hand2" if state == "normal" else ""
        self.btn_minus.configure(state=state, cursor=cursor)
        self.btn_plus.configure(state=state, cursor=cursor)
        self.entry.configure(state=state)

    def destroy(self) -> None:
        if self._text_trace is not None:
            self._text.trace_remove("write", self._text_trace)
            self._text_trace = None
        if self._var_trace is not None:
            self._variable.trace_remove("write", self._var_trace)
            self._var_trace = None
        super().destroy()

    def _read_variable(self) -> float:
        try:
            return float(self._variable.get())
        except (tk.TclError, ValueError, TypeError):
            return self._from

    def _format_value(self, value: float) -> str:
        if self._integer:
            return str(int(round(value)))
        return str(round(float(value), 3))

    def _parse(self, raw: str, *, strict_integer: bool = True) -> float | None:
        text = raw.strip()
        if text in self._INCOMPLETE:
            return None
        if self._integer and strict_integer:
            body = text[1:] if text[0] in "+-" else text
            if not body.isdigit():
                return None
        try:
            return float(text)
        except ValueError:
            return None

    @staticmethod
    def _same(left: float, right: float) -> bool:
        return abs(float(left) - float(right)) < 1e-9

    def _on_text_changed(self, *_args: object) -> None:
        if self._syncing:
            return
        parsed = self._parse(self._text.get())
        if parsed is None or self._same(parsed, self._read_variable()):
            return
        stored = int(round(parsed)) if self._integer else parsed
        self._syncing = True
        try:
            self._variable.set(stored)
        finally:
            self._syncing = False

    def _on_variable_changed(self, *_args: object) -> None:
        if self._syncing:
            return
        try:
            value = float(self._variable.get())
        except (tk.TclError, ValueError, TypeError):
            return
        parsed = self._parse(self._text.get())
        if parsed is not None and self._same(parsed, value):
            return
        formatted = self._format_value(value)
        if self._text.get() == formatted:
            return
        self._syncing = True
        try:
            self._text.set(formatted)
        finally:
            self._syncing = False

    def _on_click(self, _event: object = None) -> str:
        self.entry.focus_set()
        self.entry.after_idle(self._select_all)
        return "break"

    def _on_focus_in(self, _event: object = None) -> None:
        self.entry.after_idle(self._select_all)

    def _select_all(self) -> None:
        try:
            self.entry.select_range(0, "end")
            self.entry.icursor("end")
        except tk.TclError:
            return

    def _commit_value(self, value: float, *, clamp: bool) -> None:
        if clamp:
            value = min(self._to, max(self._from, value))
        stored = int(round(value)) if self._integer else round(float(value), 3)
        formatted = self._format_value(stored)
        self._syncing = True
        try:
            if not self._same(stored, self._read_variable()):
                self._variable.set(stored)
            if self._text.get() != formatted:
                self._text.set(formatted)
        finally:
            self._syncing = False

    def _commit_text(self, _event: object = None) -> None:
        parsed = self._parse(self._text.get(), strict_integer=False)
        self._commit_value(self._read_variable() if parsed is None else parsed, clamp=False)

    def _step(self, delta: float) -> None:
        parsed = self._parse(self._text.get(), strict_integer=False)
        current = self._read_variable() if parsed is None else parsed
        self._commit_value(current + delta, clamp=True)


class PreferencesPage(ctk.CTkFrame):
    """Preferences page with grouped settings cards."""

    def __init__(self, app: App, master: Any) -> None:
        super().__init__(master, fg_color=BG_MAIN, corner_radius=0)
        self.app = app
        self._number_inputs: list[CTkNumberInput] = []
        self._bass_trim_inputs: list[CTkNumberInput] = []
        self._setting_card_frames: list[ctk.CTkFrame] = []
        self._preferences_single_column = False
        self._layout_after_id: str | None = None
        self._controls_state: str | None = None

        self.grid_columnconfigure(0, weight=1)
        self.grid_rowconfigure(0, weight=1)

        body = ctk.CTkFrame(self, fg_color=BG_MAIN, corner_radius=0)
        body.grid(row=0, column=0, sticky="nsew", padx=PAGE_PADX, pady=(SECTION_GAP, SECTION_GAP))
        body.grid_columnconfigure((0, 1), weight=1)
        self.body = body

        header = ctk.CTkFrame(body, fg_color="transparent")
        header.grid(row=0, column=0, columnspan=2, sticky="ew", pady=(0, 8))
        header.grid_columnconfigure(0, weight=1)

        app._label(
            header,
            text="Settings",
            bg=BG_MAIN,
            size=SETTINGS_TITLE,
            weight="bold",
            accent=True,
        ).grid(
            row=0, column=0, sticky="w"
        )

        self.lbl_system_check_status = app._label(
            header,
            text="",
            color=FG_MUTED,
            bg=BG_MAIN,
            size=SETTINGS_HINT,
            justify="left",
        )
        self.lbl_system_check_status.grid(row=1, column=0, sticky="w", pady=(6, 0))
        self.lbl_system_check_status.grid_remove()
        self.system_check_results_frame = ctk.CTkFrame(header, fg_color="transparent")
        self.system_check_results_frame.grid(row=2, column=0, sticky="ew", pady=(2, 4))
        self.system_check_results_frame.grid_columnconfigure(0, weight=1)
        self.system_check_results_frame.grid_remove()
        self.system_check_results_frame.bind(
            "<Configure>",
            self._on_system_check_results_configure,
            add="+",
        )

        loudness_card = self._card(body, row=1, column=0)
        self._build_output_loudness_card(loudness_card)

        format_card = self._card(body, row=1, column=1)
        self._build_output_format_card(format_card)

        analysis_card = self._card(body, row=2, column=0)
        self._build_analysis_card(analysis_card)

        reporting_card = self._card(body, row=2, column=1)
        self._build_reporting_card(reporting_card)

        render_card = self._card(body, row=3, column=0)
        self._build_render_rules_card(render_card)

        bass_card = self._card(body, row=3, column=1)
        self._build_bass_card(bass_card)

        self.bind("<Configure>", self._on_page_configure, add="+")
        self.after_idle(self.refresh_layout)

        footer = ctk.CTkFrame(self, fg_color="transparent")
        footer.grid(row=1, column=0, sticky="ew", padx=PAGE_PADX, pady=(0, SPACE_3))
        footer_button_height = 40
        btn_reset_defaults = app._button(
            footer,
            text="Reset Defaults",
            command=app._reset_defaults,
        )
        btn_reset_defaults.configure(
            height=footer_button_height,
            corner_radius=BUTTON_CORNER_RADIUS,
        )
        btn_reset_defaults.pack(side="left")
        self.btn_system_check = app._button(
            footer,
            text="Check Limiter / System",
            command=app._run_system_check,
        )
        self.btn_system_check.configure(
            height=footer_button_height,
            corner_radius=BUTTON_CORNER_RADIUS,
        )
        self.btn_system_check.pack(side="left", padx=(8, 0))
        self._build_supporter_box(footer, footer_button_height)

        app.lbl_output_format_hint = self.lbl_output_format_hint
        app.mode_menu = self.mode_menu
        app.limiter_engine_menu = self.limiter_engine_menu
        app.output_format_menu = self.output_format_menu
        app.chk_allow_risky_true_peak_boost = self.chk_allow_risky_true_peak_boost
        app.chk_apply_render_gain_threshold = self.chk_apply_render_gain_threshold
        app.chk_write_csv = self.chk_write_csv
        app._number_inputs = self._number_inputs
        app._refresh_output_format_hint()
        app._refresh_settings_summary()

    def refresh_from_app(self) -> None:
        self.app._refresh_output_format_hint()
        self.app._refresh_settings_summary()

    def commit_number_inputs(self) -> None:
        for number_input in self._number_inputs:
            number_input._commit_text()

    def refresh_layout(self) -> None:
        self._schedule_preferences_layout()

    def settle_layout_for_reveal(self) -> None:
        """Cancel debounced relayout and settle Preferences while hidden."""
        if self._layout_after_id is not None:
            try:
                self.after_cancel(self._layout_after_id)
            except Exception:
                pass
            self._layout_after_id = None
        self.update_idletasks()
        self._update_preferences_layout(logical_widget_width(self))
        self.update_idletasks()

    def _schedule_preferences_layout(self) -> None:
        if self._layout_after_id is not None:
            try:
                self.after_cancel(self._layout_after_id)
            except Exception:
                pass
        self._layout_after_id = self.after(
            PREFERENCES_LAYOUT_DEBOUNCE_MS,
            self._apply_scheduled_preferences_layout,
        )

    def _apply_scheduled_preferences_layout(self) -> None:
        self._layout_after_id = None
        self._update_preferences_layout(logical_widget_width(self))

    def _on_page_configure(self, event: tk.Event) -> None:
        if event.widget is not self:
            return
        self._schedule_preferences_layout()

    def _update_preferences_layout(self, logical_w: int) -> None:
        if logical_w <= 0:
            return
        if self._preferences_single_column:
            single_column = logical_w < PREFERENCES_TWO_COLUMN_WIDTH
        else:
            single_column = logical_w < PREFERENCES_SINGLE_COLUMN_WIDTH
        if single_column == self._preferences_single_column:
            return
        self._preferences_single_column = single_column
        self._apply_preferences_layout(single_column)

    def _apply_preferences_layout(self, single_column: bool) -> None:
        body = self.body
        if single_column:
            # Clear stale columnspan after switching from two-column layout
            body.grid_columnconfigure(0, weight=1, minsize=0)
            body.grid_columnconfigure(1, weight=0, minsize=0)
            for index, outer in enumerate(self._setting_card_frames):
                outer.grid(
                    row=index + 1,
                    column=0,
                    columnspan=1,
                    sticky="nsew",
                    padx=0,
                    pady=(0, 14),
                )
        else:
            body.grid_columnconfigure(0, weight=1, minsize=0)
            body.grid_columnconfigure(1, weight=1, minsize=0)
            card_count = len(self._setting_card_frames)
            for index, outer in enumerate(self._setting_card_frames):
                row = (index // 2) + 1
                column = index % 2
                if index == card_count - 1 and card_count % 2 == 1:
                    outer.grid(
                        row=row,
                        column=0,
                        columnspan=2,
                        sticky="nsew",
                        padx=0,
                        pady=(0, 14),
                    )
                else:
                    outer.grid(
                        row=row,
                        column=column,
                        columnspan=1,
                        sticky="nsew",
                        padx=(0, 7) if column == 0 else (7, 0),
                        pady=(0, 14),
                    )

    def set_controls_state(self, state: str) -> None:
        # Avoid redundant reconfigure on +/- clicks (idle refresh retriggers this)
        if state == self._controls_state:
            return
        self._controls_state = state

        for number_input in self._number_inputs:
            number_input.configure_state(state)
        for widget in (
            self.mode_menu,
            self.limiter_engine_menu,
            self.bass_treatment_menu,
            self.output_format_menu,
            self.chk_allow_risky_true_peak_boost,
            self.chk_apply_render_gain_threshold,
            self.chk_include_subfolders,
            self.chk_include_source_format,
            self.chk_write_csv,
            self.csv_display,
            self.btn_system_check,
        ):
            widget.configure(state=state)
        self._sync_bass_treatment_controls()

    def _show_amount_cell(self, cell: ctk.CTkFrame, number_input: CTkNumberInput, visible: bool) -> None:
        if visible:
            cell.grid()
            number_input.configure_state("normal")
        else:
            cell.grid_remove()

    def _sync_bass_treatment_controls(self, treatment: str | None = None) -> None:
        if self._controls_state == "disabled":
            return
        if treatment is None:
            treatment = str(self.app.var_bass_treatment.get())
        treatment = normalize_bass_treatment(treatment)
        threshold_state = "normal" if treatment != BASS_TREATMENT_OFF else "disabled"
        for number_input in self._bass_trim_inputs:
            number_input.configure_state(threshold_state)
        self._show_amount_cell(
            self._level_trim_amount_cell,
            self._level_trim_amount,
            treatment == BASS_TREATMENT_LEVEL_TRIM,
        )
        self._show_amount_cell(
            self._low_end_eq_amount_cell,
            self._low_end_eq_amount,
            treatment == BASS_TREATMENT_LOW_END_EQ,
        )
        self._show_amount_cell(
            self._low_end_eq_corner_cell,
            self._low_end_eq_corner,
            treatment == BASS_TREATMENT_LOW_END_EQ,
        )

    def _on_bass_treatment_selected(self, choice: str) -> None:
        self._sync_bass_treatment_controls(choice)

    def _card(self, parent: Any, *, row: int, column: int) -> ctk.CTkFrame:
        padx = (0, 7) if column == 0 else (7, 0)
        outer = ctk.CTkFrame(
            parent,
            fg_color=BG_CARD,
            border_color=BORDER_COLOR,
            border_width=1,
            corner_radius=CARD_CORNER_RADIUS,
        )
        self._setting_card_frames.append(outer)
        outer.grid(row=row, column=column, sticky="nsew", padx=padx, pady=(0, 14))
        inner = ctk.CTkFrame(outer, fg_color="transparent")
        inner.pack(fill="both", expand=True, padx=14, pady=14)
        inner.grid_columnconfigure(0, weight=1)
        return inner

    def _build_supporter_box(self, footer: Any, height: int) -> None:
        box = ctk.CTkFrame(footer, fg_color="transparent")
        box.pack(side="right")
        self._supporter_box = box

        self.supporter_code_var = tk.StringVar()
        self.supporter_entry = self.app._entry(
            box,
            textvariable=self.supporter_code_var,
            width=200,
            height=height,
            size=SETTINGS_HINT,
        )
        self.supporter_entry.configure(
            placeholder_text="Supporter code",
            placeholder_text_color=FG_MUTED,
        )
        self.btn_supporter_register = self.app._button(
            box,
            text="Register",
            command=self._on_register_supporter,
        )
        self.btn_supporter_register.configure(height=height, width=88)
        self.btn_supporter_remove = self.app._button(
            box,
            text="Remove",
            command=self._on_remove_supporter,
        )
        self.btn_supporter_remove.configure(height=height, width=80)
        self.lbl_supporter_status = self.app._label(
            box,
            text="",
            color=FG_MUTED,
            bg=BG_MAIN,
            size=SETTINGS_HINT,
            anchor="e",
        )
        self._refresh_supporter_status()

    def _show_supporter_message(self, text: str, color: str) -> None:
        self.lbl_supporter_status.configure(
            text=text,
            text_color=color,
            font=self.app._font(SETTINGS_HINT),
        )
        self._layout_supporter_box("message")

    def _layout_supporter_box(self, mode: str) -> None:
        self.supporter_entry.pack_forget()
        self.btn_supporter_register.pack_forget()
        self.btn_supporter_remove.pack_forget()
        self.lbl_supporter_status.pack_forget()
        if mode == "registered":
            self.btn_supporter_remove.pack(side="right")
            self.lbl_supporter_status.pack(side="right", padx=(0, 8))
            return
        self.btn_supporter_register.pack(side="right")
        self.supporter_entry.pack(side="right", padx=(0, 8))
        if mode == "message":
            self.lbl_supporter_status.pack(side="right", padx=(0, 8))

    def _refresh_supporter_status(self) -> None:
        supporter = self.app._supporter
        if supporter is None:
            self.lbl_supporter_status.configure(text="", text_color=FG_MUTED)
            self._layout_supporter_box("editor")
            return
        self.lbl_supporter_status.configure(
            text="registered",
            text_color=SUCCESS_FG,
            font=self.app._font(SETTINGS_HINT),
        )
        self._layout_supporter_box("registered")

    def _on_register_supporter(self) -> None:
        try:
            self.app._register_supporter_code(self.supporter_code_var.get())
        except ValueError as exc:
            self._show_supporter_message(str(exc), ERROR_FG)
            self.app._logger.info("Supporter code rejected")
            return
        except OSError:
            self._show_supporter_message("Could not save the supporter code.", ERROR_FG)
            self.app._logger.exception("Failed to save supporter code")
            return
        self.supporter_code_var.set("")
        self._refresh_supporter_status()
        self.app._logger.info("Supporter code accepted")

    def _on_remove_supporter(self) -> None:
        try:
            self.app._clear_supporter_registration()
        except OSError:
            self._show_supporter_message("Could not remove the supporter code.", ERROR_FG)
            self.app._logger.exception("Failed to remove supporter code")
            return
        self.supporter_code_var.set("")
        self._refresh_supporter_status()
        self.app._logger.info("Supporter code removed")

    def _subheading(self, parent: Any, row: int, text: str, *, columnspan: int = 1) -> None:
        self.app._label(
            parent,
            text=text,
            color=FG_MUTED,
            bg=BG_CARD,
            size=SETTINGS_HEAD,
            weight="bold",
        ).grid(row=row, column=0, columnspan=columnspan, sticky="w", pady=(0, 10))

    def _labeled_number(
        self,
        parent: Any,
        row: int,
        column: int,
        label: str,
        variable: tk.Variable,
        from_: float,
        to: float,
        increment: float,
        unit: str = "",
        *,
        integer: bool = False,
        width: int = 64,
        padx: tuple[int, int] = (0, 12),
        tooltip: str = "",
        columnspan: int = 1,
        remember: list[CTkNumberInput] | None = None,
    ) -> ctk.CTkFrame:
        cell = ctk.CTkFrame(parent, fg_color="transparent")
        cell.grid(row=row, column=column, columnspan=columnspan, sticky="w", padx=padx, pady=(2, 4))
        self.app._label(cell, text=label, color=FG_MUTED, bg=BG_CARD, size=SETTINGS_TEXT).pack(side="left")
        number_input = CTkNumberInput(
            cell,
            variable=variable,
            from_=from_,
            to=to,
            increment=increment,
            integer=integer,
            width=width,
            entry_font=self.app._font(SETTINGS_TEXT),
            button_font=self.app._font(SETTINGS_TEXT, "bold"),
            app=self.app,
        )
        number_input.pack(side="left", padx=(7, 4))
        self._number_inputs.append(number_input)
        if remember is not None:
            remember.append(number_input)
        if unit:
            self.app._label(cell, text=unit, color=FG_MUTED, bg=BG_CARD, size=SETTINGS_TEXT).pack(side="left")
        if tooltip:
            self.app._add_tooltip(cell, tooltip)
        return cell

    def _inline_number(
        self,
        parent: Any,
        variable: tk.Variable,
        from_: float,
        to: float,
        increment: float,
        unit: str = "",
        *,
        integer: bool = False,
        width: int = 64,
        tooltip: str = "",
    ) -> CTkNumberInput:
        wrapper = ctk.CTkFrame(parent, fg_color="transparent")
        wrapper.pack(side="left")
        number_input = CTkNumberInput(
            wrapper,
            variable=variable,
            from_=from_,
            to=to,
            increment=increment,
            integer=integer,
            width=width,
            entry_font=self.app._font(SETTINGS_TEXT),
            button_font=self.app._font(SETTINGS_TEXT, "bold"),
            app=self.app,
        )
        number_input.pack(side="left")
        self._number_inputs.append(number_input)
        if unit:
            self.app._label(wrapper, text=unit, color=FG_MUTED, bg=BG_CARD, size=SETTINGS_TEXT).pack(side="left", padx=(4, 0))
        if tooltip:
            self.app._add_tooltip(wrapper, tooltip)
        return number_input

    def _build_output_loudness_card(self, card: ctk.CTkFrame) -> None:
        self._subheading(card, 0, "OUTPUT LOUDNESS")

        loudness_row = ctk.CTkFrame(card, fg_color="transparent")
        loudness_row.grid(row=1, column=0, sticky="ew", pady=(0, 12))
        loudness_row.grid_columnconfigure(0, weight=1)
        loudness_row.grid_columnconfigure(1, weight=0, minsize=188)

        target_cell = ctk.CTkFrame(loudness_row, fg_color="transparent")
        target_cell.grid(row=0, column=0, sticky="nw", padx=(0, 12))
        self.app._label(
            target_cell, text="Target loudest section", color=FG_MUTED, bg=BG_CARD, size=SETTINGS_TEXT
        ).pack(anchor="w", pady=(0, 8))
        target_inputs = ctk.CTkFrame(target_cell, fg_color="transparent")
        target_inputs.pack(anchor="w")
        self._inline_number(
            target_inputs,
            self.app.var_target_low,
            -20.0,
            0.0,
            0.1,
            tooltip=(
                "Lower edge of the acceptable loudness range for the loudest section. "
                "Tracks below this may be boosted so you do not need to ride trim during a set."
            ),
        )
        self.app._label(target_inputs, text="to", color=FG_MUTED, bg=BG_CARD, size=SETTINGS_TEXT).pack(side="left", padx=8)
        self._inline_number(
            target_inputs,
            self.app.var_target_high,
            -20.0,
            0.0,
            0.1,
            "LUFS",
            tooltip=(
                "Upper edge of the target loudness range. Tracks above this may be turned down. "
                "For loud EDM, keeping Low and High close gives a more consistent library."
            ),
        )

        self._labeled_number(
            loudness_row,
            0,
            1,
            "Peak ceiling",
            self.app.var_peak_ceiling,
            -12.0,
            0.0,
            0.1,
            "dBTP",
            padx=(0, 0),
            tooltip=(
                "True-peak safety ceiling for boosted or rendered files. -1.0 dBTP leaves practical headroom "
                "for club playback and lossy encoding. Limiter-assisted Pro-L 2 and LoudMax apply a small "
                "internal output pad for ISP overshoot; clean gain follows this value as set."
            ),
        )

        self.app._label(card, text="Processing mode", color=FG_MUTED, bg=BG_CARD, size=SETTINGS_TEXT).grid(
            row=2, column=0, sticky="w", pady=(0, 8)
        )
        mode_cell = ctk.CTkFrame(card, fg_color="transparent")
        mode_cell.grid(row=3, column=0, sticky="ew")
        mode_cell.grid_columnconfigure(0, weight=1)
        self.mode_menu = ctk.CTkOptionMenu(
            mode_cell,
            variable=self.app.var_normalization_mode,
            values=list(NORMALIZATION_MODE_CHOICES),
            fg_color=BG_FIELD,
            button_color=BG_CARD,
            button_hover_color=ICE_DIM,
            dropdown_fg_color=BG_FIELD,
            dropdown_hover_color=ICE_DIM,
            dropdown_text_color=FG_MAIN,
            text_color=FG_MAIN,
            font=self.app._font(TYPE_BODY),
            dropdown_font=self.app._font(TYPE_BODY),
            height=32,
        )
        self.mode_menu.grid(row=0, column=0, sticky="ew")
        self.app._add_tooltip(
            mode_cell,
            "Limiter-assisted can boost into a limiter plugin while respecting the true-peak ceiling. "
            "Clean gain only applies gain changes that stay under the ceiling without limiter help.",
        )

        self.app._label(card, text="Limiter engine", color=FG_MUTED, bg=BG_CARD, size=SETTINGS_TEXT).grid(
            row=4, column=0, sticky="w", pady=(12, 8)
        )
        limiter_engine_cell = ctk.CTkFrame(card, fg_color="transparent")
        limiter_engine_cell.grid(row=5, column=0, sticky="ew")
        limiter_engine_cell.grid_columnconfigure(0, weight=1)
        self.limiter_engine_menu = ctk.CTkOptionMenu(
            limiter_engine_cell,
            variable=self.app.var_limiter_engine,
            values=list(LIMITER_ENGINE_CHOICES),
            fg_color=BG_FIELD,
            button_color=BG_CARD,
            button_hover_color=ICE_DIM,
            dropdown_fg_color=BG_FIELD,
            dropdown_hover_color=ICE_DIM,
            dropdown_text_color=FG_MAIN,
            text_color=FG_MAIN,
            font=self.app._font(TYPE_BODY),
            dropdown_font=self.app._font(TYPE_BODY),
            height=32,
        )
        self.limiter_engine_menu.grid(row=0, column=0, sticky="ew")
        self.app._add_tooltip(
            limiter_engine_cell,
            "Which limiter plugin renders limiter-assisted rows.",
        )

    def _build_output_format_card(self, card: ctk.CTkFrame) -> None:
        self._subheading(card, 0, "OUTPUT FORMAT")

        self.output_format_menu = ctk.CTkOptionMenu(
            card,
            variable=self.app.var_output_format_mode,
            values=list(OUTPUT_FORMAT_MODE_CHOICES),
            command=self.app._on_output_format_mode_selected,
            fg_color=BG_FIELD,
            button_color=BG_CARD,
            button_hover_color=ICE_DIM,
            dropdown_fg_color=BG_FIELD,
            dropdown_hover_color=ICE_DIM,
            dropdown_text_color=FG_MAIN,
            text_color=FG_MAIN,
            font=self.app._font(TYPE_BODY),
            dropdown_font=self.app._font(TYPE_BODY),
            height=32,
        )
        self.output_format_menu.grid(row=1, column=0, sticky="ew", pady=(0, 8))
        self.app._add_tooltip(card, output_format_mode_tooltip(), wraplength=320)

        self.lbl_output_format_hint = self.app._label(
            card,
            text="",
            color=FG_MUTED,
            bg=BG_CARD,
            size=SETTINGS_HINT,
            justify="left",
        )
        self.lbl_output_format_hint.grid(row=2, column=0, sticky="ew")
        self.lbl_output_format_hint.grid_remove()
        self._bind_card_wraplength(card, self.lbl_output_format_hint)

        self.chk_include_source_format = ctk.CTkCheckBox(
            card,
            text="Include source format in filename",
            variable=self.app.var_include_source_format,
            fg_color=ACCENT,
            hover_color=ACCENT_HOVER,
            border_color=BORDER_COLOR,
            text_color=FG_MAIN,
            checkmark_color=BUTTON_TEXT_DARK,
            checkbox_width=18,
            checkbox_height=18,
            font=self.app._font(SETTINGS_TEXT),
        )
        self.chk_include_source_format.grid(row=3, column=0, sticky="w", pady=(12, 0))
        self.app._add_tooltip(
            self.chk_include_source_format,
            "On: when the output format changes, the source format stays in the name "
            "(Track_flac_DG.aiff). Off: the name is Track_DG.aiff. If that name is already "
            "used, later files become Track_DG (1), Track_DG (2).",
        )

    def _build_analysis_card(self, card: ctk.CTkFrame) -> None:
        self._subheading(card, 0, "ANALYSIS")
        grid = ctk.CTkFrame(card, fg_color="transparent")
        grid.grid(row=1, column=0, sticky="ew")
        grid.grid_columnconfigure((0, 1), weight=1)

        self._labeled_number(
            grid, 0, 0, "Window", self.app.var_window,
            MIN_LOUD_SECTION_WINDOW_SECONDS, MAX_LOUD_SECTION_WINDOW_SECONDS, 5.0, "sec",
            tooltip=(
                "Length of each segment used to find the loudest musical section. "
                "30 seconds is a good EDM default because it captures a drop or chorus instead of a tiny transient."
            ),
        )
        self._labeled_number(
            grid, 0, 1, "Hop", self.app.var_hop,
            MIN_LOUD_SECTION_HOP_SECONDS, MAX_LOUD_SECTION_HOP_SECONDS, 5.0, "sec",
            padx=(0, 0),
            tooltip=(
                "How far the analysis window moves each step. Lower values scan more precisely but take longer; "
                "higher values are faster but may miss the exact loudest drop."
            ),
        )
        self._labeled_number(
            grid, 1, 0, "Analysis workers", self.app.var_workers,
            MIN_ANALYSIS_WORKER_THREADS, MAX_ANALYSIS_WORKER_THREADS, 1.0, "",
            integer=True,
            padx=(0, 0),
            tooltip=(
                "Number of files analyzed at once. Higher can speed up scanning on strong CPUs, "
                "but can also make the computer feel busy. Limiter rendering stays single-threaded."
            ),
        )

        self.chk_include_subfolders = ctk.CTkCheckBox(
            card,
            text="Include subfolders",
            variable=self.app.var_include_subfolders,
            fg_color=ACCENT,
            hover_color=ACCENT_HOVER,
            border_color=BORDER_COLOR,
            text_color=FG_MAIN,
            checkmark_color=BUTTON_TEXT_DARK,
            checkbox_width=18,
            checkbox_height=18,
            font=self.app._font(SETTINGS_TEXT),
        )
        self.chk_include_subfolders.grid(row=2, column=0, sticky="w", pady=(12, 0))
        self.app._add_tooltip(
            self.chk_include_subfolders,
            "On: analyze audio in the source folder and every folder inside it. "
            "Off: only files sitting directly in the source folder.",
        )

    def _build_render_rules_card(self, card: ctk.CTkFrame) -> None:
        self._subheading(card, 0, "RENDER RULES")
        grid = ctk.CTkFrame(card, fg_color="transparent")
        grid.grid(row=1, column=0, sticky="ew")
        grid.grid_columnconfigure((0, 1), weight=1)

        self.app._label(
            grid,
            text="Minimum gain change to render",
            color=FG_MUTED,
            bg=BG_CARD,
            size=SETTINGS_TEXT,
        ).grid(row=0, column=0, columnspan=2, sticky="w", pady=(0, 6))

        self._labeled_number(
            grid, 1, 0, "MP3", self.app.var_mp3_threshold, 0.0, 6.0, 0.05, "dB",
            tooltip=(
                "Minimum gain change before an MP3 is rendered. MP3 defaults higher because re-encoding is lossy."
            ),
        )
        self._labeled_number(
            grid, 1, 1, "Lossless", self.app.var_lossless_threshold, 0.0, 6.0, 0.05, "dB",
            padx=(0, 0),
            tooltip="Minimum gain change before FLAC, WAV, or AIFF files are rendered.",
        )

        self._labeled_number(
            grid, 2, 0, "Max limiter reduction", self.app.var_max_reduction, 0.0, 20.0, 0.1, "dB",
            tooltip=(
                "Maximum amount DropGain is allowed to turn down an overly loud track. "
                "This prevents extreme level changes from changing the intended energy of the master."
            ),
        )

        self.chk_apply_render_gain_threshold = ctk.CTkCheckBox(
            grid,
            text="Apply gain thresholds when rendering",
            variable=self.app.var_apply_render_gain_threshold,
            fg_color=ACCENT,
            hover_color=ACCENT_HOVER,
            border_color=BORDER_COLOR,
            text_color=FG_MAIN,
            checkmark_color=BUTTON_TEXT_DARK,
            font=self.app._font(SETTINGS_TEXT),
        )
        self.chk_apply_render_gain_threshold.grid(row=3, column=0, columnspan=2, sticky="w", pady=(12, 0))
        self.app._add_tooltip(
            self.chk_apply_render_gain_threshold,
            "Off by default for batch runs: render every track that passes safety checks. "
            "On: skip small gain-only changes using the MP3 and lossless thresholds above.",
        )

        self.chk_allow_risky_true_peak_boost = ctk.CTkCheckBox(
            grid,
            text="Allow boosting when true-peak measurement failed (risky)",
            variable=self.app.var_allow_risky_true_peak_boost,
            fg_color=ACCENT,
            hover_color=ACCENT_HOVER,
            border_color=BORDER_COLOR,
            text_color=FG_MAIN,
            checkmark_color=BUTTON_TEXT_DARK,
            checkbox_width=18,
            checkbox_height=18,
            font=self.app._font(SETTINGS_TEXT),
        )
        self.chk_allow_risky_true_peak_boost.grid(row=4, column=0, columnspan=2, sticky="w", pady=(8, 0))
        self.app._add_tooltip(
            self.chk_allow_risky_true_peak_boost,
            "Only use this when you trust the source file and accept the clipping risk.",
        )

    def _build_bass_card(self, card: ctk.CTkFrame) -> None:
        self._subheading(card, 0, "BASS")
        grid = ctk.CTkFrame(card, fg_color="transparent")
        grid.grid(row=1, column=0, sticky="ew")
        grid.grid_columnconfigure((0, 1), weight=1)

        bass_treatment_cell = ctk.CTkFrame(grid, fg_color="transparent")
        bass_treatment_cell.grid(row=0, column=0, columnspan=2, sticky="ew", pady=(0, 4))
        bass_treatment_cell.grid_columnconfigure(0, weight=1)
        self.bass_treatment_menu = ctk.CTkOptionMenu(
            bass_treatment_cell,
            variable=self.app.var_bass_treatment,
            values=list(BASS_TREATMENT_CHOICES),
            command=self._on_bass_treatment_selected,
            fg_color=BG_FIELD,
            button_color=BG_CARD,
            button_hover_color=ICE_DIM,
            dropdown_fg_color=BG_FIELD,
            dropdown_hover_color=ICE_DIM,
            dropdown_text_color=FG_MAIN,
            text_color=FG_MAIN,
            font=self.app._font(TYPE_BODY),
            dropdown_font=self.app._font(TYPE_BODY),
            height=32,
        )
        self.bass_treatment_menu.grid(row=0, column=0, sticky="ew")
        self.app._add_tooltip(
            bass_treatment_cell,
            (
                "Off leaves the loudness decision unchanged. "
                "Level trim pulls broadband gain back on bass-heavy tracks. "
                "Low-end EQ applies a low shelf at the Low-end EQ corner instead, then measures loudness and true peak again. "
                "Only one of those can be active.\n"
                "The amount comes from bass in the loudest LUFS section only. "
                "LUFS discounts low end, so a bassier part outside that window does not raise the cut or trim. "
                "The result is still applied to the whole file.\n"
                "Low-end EQ changes the analyzed audio, so that mode, its max cut, its corner, and the thresholds "
                "below need a new analysis when they change."
            ),
            wraplength=420,
        )

        self._level_trim_amount_cell = self._labeled_number(
            grid, 1, 0, "Max bass-aware trim", self.app.var_bass_max_reduction,
            MIN_BASS_MAX_BOOST_REDUCTION_DB, MAX_BASS_MAX_BOOST_REDUCTION_DB, 0.1, "dB",
            tooltip=(
                "Broadband pullback when bass strength reaches Full. "
                "Between Start and Full the pullback is a fraction of this value: halfway gets half. "
                "Below Start it is 0.\n"
                "It can reduce a boost, deepen a cut, or pull down an in-target track."
            ),
        )
        self._level_trim_amount = self._number_inputs[-1]
        self._low_end_eq_amount_cell = self._labeled_number(
            grid, 1, 0, "Max low-end EQ", self.app.var_low_end_eq_max,
            MIN_LOW_END_EQ_MAX_DB, MAX_LOW_END_EQ_MAX_DB, 0.1, "dB",
            tooltip=(
                "Shelf cut when bass strength reaches Full. "
                "Between Start and Full the cut is a fraction of this value: halfway gets half. "
                "Below Start the cut is 0.\n"
                "The corner sets where that cut sits in frequency. "
                "Changes require a new analysis."
            ),
        )
        self._low_end_eq_amount = self._number_inputs[-1]
        self._low_end_eq_corner_cell = self._labeled_number(
            grid, 1, 1, "Low-end EQ corner", self.app.var_low_end_eq_shelf_hz,
            MIN_LOW_END_EQ_SHELF_HZ, MAX_LOW_END_EQ_SHELF_HZ, 1, "Hz",
            padx=(0, 0),
            integer=True,
            tooltip=(
                "Halfway point of the low shelf. "
                "At 80 Hz, a 6 dB cut is about 5.2 dB at 50 Hz, 3 dB at 80 Hz, and about 1 dB at 120 Hz.\n"
                "Changing this requires a new analysis."
            ),
        )
        self._low_end_eq_corner = self._number_inputs[-1]

        lbl_bass_trim_thresholds = self.app._label(
            grid,
            text="When to trim bass-heavy tracks",
            color=FG_MUTED,
            bg=BG_CARD,
            size=SETTINGS_TEXT,
        )
        lbl_bass_trim_thresholds.grid(row=2, column=0, columnspan=2, sticky="w", pady=(12, 6))
        self.app._add_tooltip(
            lbl_bass_trim_thresholds,
            (
                "These two numbers are bass_strength_db in the results table: "
                "how many dB more energy sits in 30-100 Hz than in 400-8000 Hz.\n"
                "Start is no cut. Full is the whole Max for the selected mode. "
                "Between them the amount grows, so halfway gets half the Max."
            ),
            wraplength=420,
        )

        self._labeled_number(
            grid, 3, 0, "Bass trim start", self.app.var_bass_penalty_start,
            MIN_BASS_PENALTY_THRESHOLD_DB, MAX_BASS_PENALTY_THRESHOLD_DB, 0.5, "dB",
            remember=self._bass_trim_inputs,
            tooltip=(
                "bass_strength_db (30-100 Hz versus 400-8000 Hz) where the response starts. "
                "At the default +7.5 dB, a track at +7 dB gets nothing, and +9 dB gets about a quarter of the Max.\n"
                "Raise this if normal EDM bass keeps getting trimmed."
            ),
        )
        self._labeled_number(
            grid, 3, 1, "Bass trim full", self.app.var_bass_penalty_full,
            MIN_BASS_PENALTY_THRESHOLD_DB, MAX_BASS_PENALTY_THRESHOLD_DB, 0.5, "dB",
            padx=(0, 0),
            remember=self._bass_trim_inputs,
            tooltip=(
                "bass_strength_db where the track gets the whole Max. "
                "Between Start and Full the amount grows: at the defaults, +10.75 dB is halfway from +7.5 to +14 and gets half the Max.\n"
                "Lower Full if those tracks should get the full amount."
            ),
        )
        self._sync_bass_treatment_controls()

    def _build_reporting_card(self, card: ctk.CTkFrame) -> None:
        self._subheading(card, 0, "REPORTING")

        self.lbl_reporting_hint = self.app._label(
            card,
            text=(
                f"By default, safe copies are saved beside originals with the {PROCESSED_SUFFIX} suffix. "
                "Use the output folder on the Process page to redirect copies elsewhere."
            ),
            color=FG_MUTED,
            bg=BG_CARD,
            size=SETTINGS_TEXT,
            justify="left",
        )
        self.lbl_reporting_hint.grid(row=1, column=0, sticky="ew", pady=(0, 12))
        self._bind_card_wraplength(card, self.lbl_reporting_hint)

        csv_cell = ctk.CTkFrame(card, fg_color="transparent")
        csv_cell.grid(row=2, column=0, sticky="ew")
        csv_cell.grid_columnconfigure(0, weight=1)

        self.chk_write_csv = ctk.CTkCheckBox(
            csv_cell,
            text="Write CSV report",
            variable=self.app.var_write_csv,
            fg_color=ACCENT,
            hover_color=ACCENT_HOVER,
            border_color=BORDER_COLOR,
            text_color=FG_MAIN,
            checkmark_color=BUTTON_TEXT_DARK,
            checkbox_width=18,
            checkbox_height=18,
            font=self.app._font(SETTINGS_TEXT),
        )
        self.chk_write_csv.grid(row=0, column=0, sticky="w")
        self.app._add_tooltip(
            self.chk_write_csv,
            "Write a CSV report with the analysis and render decisions. Helpful for auditing a library, "
            "checking warnings, or reviewing which tracks DropGain would change.",
        )

        self.csv_display = ctk.CTkEntry(
            csv_cell,
            textvariable=self.app.var_csv,
            state="disabled",
            fg_color=BG_FIELD,
            border_color=BORDER_COLOR,
            text_color=FG_MAIN,
            font=self.app._font(TYPE_BODY),
        )
        self.csv_display.grid(row=1, column=0, sticky="ew", pady=(8, 0))
        self.app._label(
            csv_cell,
            text=f"Default path: {default_csv_path(self.app.var_folder.get().strip())}",
            color=FG_MUTED,
            bg=BG_CARD,
            size=SETTINGS_HINT,
        ).grid(row=2, column=0, sticky="w", pady=(4, 0))

    def _bind_card_wraplength(self, card: Any, label: ctk.CTkLabel) -> None:
        def on_configure(event: tk.Event) -> None:
            if event.widget is not card:
                return
            wrap = max(int(event.width) - 4, 0)
            if wrap <= 0:
                return
            last_wrap = getattr(label, "_dropgain_wraplength", None)
            if last_wrap is not None and abs(last_wrap - wrap) < 8:
                return
            label._dropgain_wraplength = wrap  # type: ignore[attr-defined]
            label.configure(wraplength=wrap)

        card.bind("<Configure>", on_configure, add="+")

    def _update_system_check_result_wraplengths(self, width: int) -> None:
        if width <= 0:
            return
        wrap = max(width - 4, 80)
        for label in self.system_check_results_frame.winfo_children():
            last_wrap = getattr(label, "_dropgain_wraplength", None)
            if last_wrap is not None and abs(last_wrap - wrap) < 8:
                continue
            label._dropgain_wraplength = wrap  # type: ignore[attr-defined]
            label.configure(wraplength=wrap)

    def _on_system_check_results_configure(self, event: tk.Event) -> None:
        if event.widget is not self.system_check_results_frame:
            return
        self._update_system_check_result_wraplengths(int(event.width))

    def show_system_check_results(self, results: list[tuple[str, bool, str]]) -> None:
        if all(ok for _, ok, _ in results):
            heading = "All checks passed"
            color = SUCCESS_FG
        else:
            heading = "Some checks failed"
            color = ERROR_FG

        lines: list[str] = []
        for name, ok, detail in results:
            symbol = "✓" if ok else "✗"
            lines.append(f"{symbol} {name}: {detail}" if detail else f"{symbol} {name}")

        self.lbl_system_check_status.configure(
            text=heading,
            text_color=color,
        )
        for child in self.system_check_results_frame.winfo_children():
            child.destroy()
        split_at = (len(lines) + 1) // 2
        for row, row_lines in enumerate((lines[:split_at], lines[split_at:])):
            if not row_lines:
                continue
            label = self.app._label(
                self.system_check_results_frame,
                text="  |  ".join(row_lines),
                color=color,
                bg=BG_MAIN,
                size=SETTINGS_HINT,
                anchor="w",
                justify="left",
                wraplength=1,
            )
            label.grid(
                row=row,
                column=0,
                sticky="ew",
                pady=(0, 1),
            )
        self.lbl_system_check_status.grid(row=1, column=0, sticky="w", pady=(6, 0))
        self.system_check_results_frame.grid(row=2, column=0, sticky="ew", pady=(2, 4))
        self.system_check_results_frame.update_idletasks()
        self._update_system_check_result_wraplengths(self.system_check_results_frame.winfo_width())