# rftools/calculators/audio.py
# AUTO-GENERATED by scripts/generate_stubs.py — DO NOT EDIT
# Regenerate with: python scripts/generate_stubs.py --frontend-dir /path/to/frontend
"""
Typed stubs for the 'audio' category (17 calculators).

Functions:
    audio_power_amplifier(...) -> CalculatorResult
    speaker_crossover(...) -> CalculatorResult
    room_modes(...) -> CalculatorResult
    speaker_sensitivity(...) -> CalculatorResult
    headphone_power(...) -> CalculatorResult
    audio_snr(...) -> CalculatorResult
    op_amp_slew_rate(...) -> CalculatorResult
    audio_transformer(...) -> CalculatorResult
    cable_capacitance_rolloff(...) -> CalculatorResult
    subwoofer_box(...) -> CalculatorResult
    tweeter_capacitor(...) -> CalculatorResult
    class_d_efficiency(...) -> CalculatorResult
    audio_adc_snr(...) -> CalculatorResult
    equalizer_q_factor(...) -> CalculatorResult
    amplifier_clipping(...) -> CalculatorResult
    audio_delay_time(...) -> CalculatorResult
    power_amplifier_gain(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


def _client() -> _rftools.Client:
    return _rftools._get_default_client()


def audio_power_amplifier(vcc: float = 12.0, rl: float = 8.0, efficiency: float = 70.0, gain: float = 26.0) -> CalculatorResult:
    """
    Audio Power Amplifier Calculator

    Category: audio

    Calculate audio amplifier output power, efficiency, THD class estimate, SNR, and input sensitivity for Class A, AB, and D amplifiers.

    Parameters
    ----------
    vcc : float
        Supply Voltage (V) (default: 12.0)
    rl : float
        Speaker Impedance (Ω) (default: 8.0)
    efficiency : float
        Amplifier Efficiency (%) (default: 70.0)
    gain : float
        Voltage Gain (dB) (default: 26.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'poutMax', 'poutRMS', 'thd_level', 'snr', 'inputSensitivity'
    """
    inputs = {"vcc": vcc, "rl": rl, "efficiency": efficiency, "gain": gain}
    return _client().calculate('audio-power-amplifier', inputs)


def speaker_crossover(crossoverFreq: float = 3000.0, wooferImpedance: float = 8.0, tweeterImpedance: float = 8.0, order: float = 2.0) -> CalculatorResult:
    """
    Passive Speaker Crossover Calculator

    Category: audio

    Calculate passive 2-way speaker crossover component values for 1st order (6dB/oct) and 2nd order Butterworth (12dB/oct) networks.

    Parameters
    ----------
    crossoverFreq : float
        Crossover Frequency (Hz) (default: 3000.0)
    wooferImpedance : float
        Woofer Impedance (Ω) (default: 8.0)
    tweeterImpedance : float
        Tweeter Impedance (Ω) (default: 8.0)
    order : float
        Filter Order (default: 2.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'wooferL', 'wooferC', 'tweeterC', 'tweeterL', 'slopeDb'
    """
    inputs = {"crossoverFreq": crossoverFreq, "wooferImpedance": wooferImpedance, "tweeterImpedance": tweeterImpedance, "order": order}
    return _client().calculate('speaker-crossover', inputs)


def room_modes(length: float = 5.0, width: float = 3.5, height: float = 2.5, speedOfSound: float = 343.0, rt60: float = 0.4) -> CalculatorResult:
    """
    Room Acoustic Modes

    Category: audio

    Calculate room axial resonant frequencies and Schroeder frequency for acoustic treatment and speaker placement.

    Parameters
    ----------
    length : float
        Room Length (m) (default: 5.0)
    width : float
        Room Width (m) (default: 3.5)
    height : float
        Room Height (m) (default: 2.5)
    speedOfSound : float
        Speed of Sound (m/s) (default: 343.0)
    rt60 : float
        Reverberation Time (RT60) (s) (default: 0.4)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'flLength', 'flWidth', 'flHeight', 'schroeder', 'volume'
    """
    inputs = {"length": length, "width": width, "height": height, "speedOfSound": speedOfSound, "rt60": rt60}
    return _client().calculate('room-modes', inputs)


def speaker_sensitivity(sensitivity: float = 89.0, power: float = 50.0, distance: float = 3.0) -> CalculatorResult:
    """
    Speaker Sensitivity & SPL

    Category: audio

    Calculate speaker SPL at any power and distance from the rated sensitivity (dB/W/m) specification.

    Parameters
    ----------
    sensitivity : float
        Speaker Sensitivity (dB/W/m) (default: 89.0)
    power : float
        Amplifier Power (W) (default: 50.0)
    distance : float
        Listening Distance (m) (default: 3.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'splAtPower', 'splAtDistance'
    """
    inputs = {"sensitivity": sensitivity, "power": power, "distance": distance}
    return _client().calculate('speaker-sensitivity', inputs)


def headphone_power(impedance: float = 300.0, sensitivity: float = 100.0, targetSpl: float = 110.0) -> CalculatorResult:
    """
    Headphone Amplifier Power

    Category: audio

    Calculate the amplifier output power, voltage, and current required to drive headphones to a target SPL.

    Parameters
    ----------
    impedance : float
        Headphone Impedance (Ω) (default: 300.0)
    sensitivity : float
        Headphone Sensitivity (dB/mW) (default: 100.0)
    targetSpl : float
        Target SPL (dB) (default: 110.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'requiredPowerMw', 'requiredPowerW', 'requiredVoltageRms', 'requiredCurrentMa'
    """
    inputs = {"impedance": impedance, "sensitivity": sensitivity, "targetSpl": targetSpl}
    return _client().calculate('headphone-power', inputs)


def audio_snr(signalLevel: float = 0.0, noiseFloor: float = -90.0) -> CalculatorResult:
    """
    Audio SNR & Dynamic Range

    Category: audio

    Calculate audio signal-to-noise ratio, dynamic range, and equivalent noise bits from signal and noise floor levels.

    Parameters
    ----------
    signalLevel : float
        Signal Level (dBV) (default: 0.0)
    noiseFloor : float
        Noise Floor (dBV) (default: -90.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'snr', 'dynamicRange', 'snrLinear', 'noiseBits'
    """
    inputs = {"signalLevel": signalLevel, "noiseFloor": noiseFloor}
    return _client().calculate('audio-snr', inputs)


def op_amp_slew_rate(slewRate: float = 13.0, amplitude: float = 5.0, frequency: float = 20000.0) -> CalculatorResult:
    """
    Op-Amp Slew Rate & Full-Power Bandwidth

    Category: audio

    Calculate op-amp full-power bandwidth from slew rate and signal amplitude, and verify the op-amp can handle your signal without slew-rate distortion.

    Parameters
    ----------
    slewRate : float
        Op-Amp Slew Rate (V/μs) (default: 13.0)
    amplitude : float
        Signal Peak Amplitude (V) (default: 5.0)
    frequency : float
        Signal Frequency (Hz) (default: 20000.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'fullPowerBandwidth', 'minSlewRateRequired', 'slewMargin'
    """
    inputs = {"slewRate": slewRate, "amplitude": amplitude, "frequency": frequency}
    return _client().calculate('op-amp-slew-rate', inputs)


def audio_transformer(primaryImpedance: float = 600.0, secondaryImpedance: float = 8.0, primaryVoltage: float = 1.0, primaryCurrent: float = 0.001) -> CalculatorResult:
    """
    Audio Transformer Turns Ratio

    Category: audio

    Calculate audio transformer turns ratio for impedance matching between source and load, plus secondary voltage and current.

    Parameters
    ----------
    primaryImpedance : float
        Primary Impedance (Ω) (default: 600.0)
    secondaryImpedance : float
        Secondary Impedance (Ω) (default: 8.0)
    primaryVoltage : float
        Primary Voltage (RMS) (V) (default: 1.0)
    primaryCurrent : float
        Primary Current (RMS) (A) (default: 0.001)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'turnsRatio', 'secondaryVoltage', 'secondaryCurrent', 'powerTransferred'
    """
    inputs = {"primaryImpedance": primaryImpedance, "secondaryImpedance": secondaryImpedance, "primaryVoltage": primaryVoltage, "primaryCurrent": primaryCurrent}
    return _client().calculate('audio-transformer', inputs)


def cable_capacitance_rolloff(sourceImpedance: float = 10000.0, cableCapacitancePf: float = 100.0, cableLengthM: float = 5.0) -> CalculatorResult:
    """
    Cable Capacitance High-Frequency Rolloff

    Category: audio

    Calculate the high-frequency rolloff (-3 dB point) caused by cable capacitance interacting with source impedance.

    Parameters
    ----------
    sourceImpedance : float
        Source Impedance (Ω) (default: 10000.0)
    cableCapacitancePf : float
        Cable Capacitance (pF/m) (default: 100.0)
    cableLengthM : float
        Cable Length (m) (default: 5.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'totalCapacitancePf', 'cutoffFrequency', 'rolloffAt20k'
    """
    inputs = {"sourceImpedance": sourceImpedance, "cableCapacitancePf": cableCapacitancePf, "cableLengthM": cableLengthM}
    return _client().calculate('cable-capacitance-rolloff', inputs)


def subwoofer_box(vas: float = 50.0, qts: float = 0.35, fs: float = 35.0) -> CalculatorResult:
    """
    Subwoofer Enclosure Volume

    Category: audio

    Calculate optimal subwoofer box (sealed and ported) volume and port tuning frequency from Thiele-Small parameters (Vas, Qts, Fs).

    Parameters
    ----------
    vas : float
        Vas (Equivalent Volume) (L) (default: 50.0)
    qts : float
        Qts (Total Q) (default: 0.35)
    fs : float
        Fs (Resonant Frequency) (Hz) (default: 35.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'vbSealed', 'vbVented', 'portTuning', 'f3Sealed'
    """
    inputs = {"vas": vas, "qts": qts, "fs": fs}
    return _client().calculate('subwoofer-box', inputs)


def tweeter_capacitor(tweetImpedance: float = 8.0, crossoverFreq: float = 3000.0) -> CalculatorResult:
    """
    Tweeter Protection Capacitor

    Category: audio

    Calculate the capacitor value for a first-order tweeter high-pass filter to protect tweeters from low-frequency damage.

    Parameters
    ----------
    tweetImpedance : float
        Tweeter Impedance (Ω) (default: 8.0)
    crossoverFreq : float
        Crossover Frequency (Hz) (default: 3000.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'capacitanceMicroF', 'reactanceAt1k', 'rolloffAt100Hz'
    """
    inputs = {"tweetImpedance": tweetImpedance, "crossoverFreq": crossoverFreq}
    return _client().calculate('tweeter-capacitor', inputs)


def class_d_efficiency(outputPower: float = 50.0, supplyVoltage: float = 36.0, loadImpedance: float = 8.0, rdson: float = 50.0, mosfetCount: float = 4.0, quiescentCurrent: float = 30.0) -> CalculatorResult:
    """
    Class D Amplifier Efficiency

    Category: audio

    Estimate Class D amplifier efficiency from MOSFET conduction losses and quiescent current at a given output power.

    Parameters
    ----------
    outputPower : float
        Output Power (W) (default: 50.0)
    supplyVoltage : float
        Supply Voltage (V) (default: 36.0)
    loadImpedance : float
        Load Impedance (Ω) (default: 8.0)
    rdson : float
        MOSFET RDS(on) (mΩ) (default: 50.0)
    mosfetCount : float
        Number of MOSFETs (default: 4.0)
    quiescentCurrent : float
        Quiescent Current (mA) (default: 30.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'efficiency', 'conductionLoss', 'quiescentLoss', 'totalLoss', 'totalInput'
    """
    inputs = {"outputPower": outputPower, "supplyVoltage": supplyVoltage, "loadImpedance": loadImpedance, "rdson": rdson, "mosfetCount": mosfetCount, "quiescentCurrent": quiescentCurrent}
    return _client().calculate('class-d-efficiency', inputs)


def audio_adc_snr(bitDepth: float = 24.0, oversamplingRatio: float = 1.0) -> CalculatorResult:
    """
    ADC Bit Depth to Dynamic Range

    Category: audio

    Calculate the theoretical SNR and dynamic range of an audio ADC from its bit depth, and the improvement from oversampling.

    Parameters
    ----------
    bitDepth : float
        Bit Depth (bits) (default: 24.0)
    oversamplingRatio : float
        Oversampling Ratio (×) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'theoreticalSnr', 'oversamplingGain', 'totalSnr', 'dynamicRange'
    """
    inputs = {"bitDepth": bitDepth, "oversamplingRatio": oversamplingRatio}
    return _client().calculate('audio-adc-snr', inputs)


def equalizer_q_factor(centerFreq: float = 1000.0, bandwidth: float = 200.0) -> CalculatorResult:
    """
    Equalizer Filter Q & Bandwidth

    Category: audio

    Calculate equalizer Q factor from center frequency and bandwidth, or convert between Q, octaves, and frequency limits.

    Parameters
    ----------
    centerFreq : float
        Center Frequency (Hz) (default: 1000.0)
    bandwidth : float
        Bandwidth (−3 dB) (Hz) (default: 200.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'qFactor', 'octaves', 'lowerFreq', 'upperFreq'
    """
    inputs = {"centerFreq": centerFreq, "bandwidth": bandwidth}
    return _client().calculate('equalizer-q-factor', inputs)


def amplifier_clipping(supplyVoltage: float = 36.0, loadImpedance: float = 8.0, headroom: float = 100.0) -> CalculatorResult:
    """
    Amplifier Clipping Level

    Category: audio

    Calculate amplifier clipping voltage, power, and dBV level from supply voltage and load impedance.

    Parameters
    ----------
    supplyVoltage : float
        Supply Voltage (±V or single) (V) (default: 36.0)
    loadImpedance : float
        Load Impedance (Ω) (default: 8.0)
    headroom : float
        Headroom Reserve (%) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'maxOutputVoltage', 'rmsVoltage', 'clippingPower', 'clippingLevel'
    """
    inputs = {"supplyVoltage": supplyVoltage, "loadImpedance": loadImpedance, "headroom": headroom}
    return _client().calculate('amplifier-clipping', inputs)


def audio_delay_time(bpm: float = 120.0, noteValue: float = 4.0, distance: float = 10.0, speedOfSound: float = 343.0) -> CalculatorResult:
    """
    Audio Delay & Echo Time Calculator

    Category: audio

    Calculate musically-synced delay times from BPM and note value, plus acoustic propagation delay from speaker distance.

    Parameters
    ----------
    bpm : float
        Tempo (BPM) (bpm) (default: 120.0)
    noteValue : float
        Note Division (default: 4.0)
    distance : float
        Speaker Distance (m) (default: 10.0)
    speedOfSound : float
        Speed of Sound (m/s) (default: 343.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'beatMs', 'noteDelayMs', 'propagationMs'
    """
    inputs = {"bpm": bpm, "noteValue": noteValue, "distance": distance, "speedOfSound": speedOfSound}
    return _client().calculate('audio-delay-time', inputs)


def power_amplifier_gain(inputVoltage: float = 1.0, outputVoltage: float = 28.0, inputPower: float = 0.1, outputPower: float = 100.0) -> CalculatorResult:
    """
    Power Amplifier Gain Calculator

    Category: audio

    Calculate power amplifier voltage gain (V/V and dB) and power gain from input/output voltage and power measurements.

    Parameters
    ----------
    inputVoltage : float
        Input Voltage (RMS) (V) (default: 1.0)
    outputVoltage : float
        Output Voltage (RMS) (V) (default: 28.0)
    inputPower : float
        Input Power (mW) (default: 0.1)
    outputPower : float
        Output Power (W) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'voltageGain', 'voltageGainDb', 'powerGain', 'powerGainDb'
    """
    inputs = {"inputVoltage": inputVoltage, "outputVoltage": outputVoltage, "inputPower": inputPower, "outputPower": outputPower}
    return _client().calculate('power-amplifier-gain', inputs)

