Help

SpeakerLab simulates the low-frequency behaviour of a loudspeaker driver in an enclosure from its Thiele/Small parameters. You design on the left half of the loop; its companion apps SweepLab (acoustic measurement) and ampMeasure (impedance measurement) cover the right half — and SpeakerLab imports their results so you can compare simulation against the cabinet you actually built.

The three things in a project

• Drivers — the loudspeaker units, described by their parameters.

• Variants — enclosure designs using those drivers. Each variant has a type (sealed, vented, passive radiator, bandpass, transmission line), its own parameters, and optionally a DSP filter chain. All visible variants are overlaid in the charts, each with the eye toggle in the sidebar.

• Measurements — imported measured curves (SPL or impedance), overlaid dashed against the simulation.

A new document opens with an example driver and two variants so every control has something to act on. Documents are .speakerlab packages containing plain JSON — they diff cleanly under version control.

Getting started in five minutes

1. Enter your driver. Select a variant, and in the inspector edit the driver — or use Add (+) → New Driver from Datasheet Text… and paste the parameter block from a datasheet. SpeakerLab needs at least Fs, Qms, Qes, Re, Sd and Vas; it picks up Le, Xmax and Pe when present.

2. Pick a box. Set the variant's Type and volume. For vented boxes, Tune to fs sets the port length for you.

3. Read the charts. Switch between SPL, Impedance, Excursion, Air Velocity and Group Delay above the chart. Every value updates live as you drag or type.

4. Compare. Duplicate the variant (right-click in the sidebar), change one thing, and look at both curves.

5. Check the limits. The Excursion tab shows Xmax as a dashed line; Air Velocity marks the 17 m/s port-chuffing limit.

Drivers

The driver form shows both parameter sets and keeps them consistent in both directions:

• Edit fs, Qms, Qes or Vas and the mechanical fundamentals (Mms, Cms, Rms, Bl) are recomputed.

• Edit the fundamentals directly and the derived T/S values update.

Voice-coil inductance. Le with exponent n = 1 is an ideal inductor. Real drivers fit measured impedance better with the semi-inductance model (n ≈ 0.6–0.8): the blocked impedance is modelled as Le·(jω)ⁿ. If you have a datasheet Le measured at 1 kHz and want to use n < 1, the coefficient is converted so the magnitude at 1 kHz is preserved.

Units in the form: Vas in litres, Sd in cm², Mms in grams, Cms in mm/N, Le in mH, Xmax in mm (peak, one direction).

Enclosure types

Sealed. Volume and absorption Q (Qa). The inspector shows the resulting system resonance fc and total Q (Qtc) — but the plotted response always comes from the full network, including losses and voice-coil inductance, not from the textbook alignment.

Vented. Volume, port diameter, length and count, with the three-loss model: Ql (leakage, default 7), Qa (absorption), Qp (port loss). End corrections are selectable per port end (flanged 0.85 / free 0.61). The tuning frequency fb is displayed live; Tune to fs computes the port length for fb = fs. Watch the Air Velocity chart — above roughly 17 m/s peak, ports become audible.

Passive radiator. Instead of a port: the PR's area Sp, moving mass Mmp, compliance Cmp and losses Rmp. Two frequencies are displayed: fp, the PR's own resonance — this is where the characteristic output notch sits — and fb, the system tuning. Tune Mmp to fs computes the mass. The Excursion chart shows PR excursion as a dashed line — with passive radiators, the PR (not the cone) usually runs out of travel first.

Bandpass (4th order). A sealed rear chamber and a ported front chamber; all output leaves through the port. Both chamber volumes, the port, and per-chamber losses are adjustable; fb of the front chamber sets the passband centre.

Transmission line. The line is a list of segments from the closed end to the mouth, each with length, start/end area and stuffing density — a straight, tapered, expanding or stepped line is just different segment values. The schematic cross-section above the table shows the profile, the shading shows stuffing density, and the red marker shows the driver position.

• Driver position places the driver anywhere along the line (offset-driver TML / MLTL). Placing it around one third of the length suppresses the third harmonic ripple — the classic trick.

• Stuffing uses an empirical fibrous-absorber model (Miki by default, Delany–Bazley selectable) with a material picker (polyester fill, long-fibre wool, fiberglass) that maps density in kg/m³ to flow resistivity. Real lines are stuffed heavily at the closed end and lightly at the mouth — model that with per-segment densities.

• Terminus can be unflanged, flanged, or closed.

• The displayed ¼-wave fq is the unstuffed quarter-wave frequency; stuffing lowers the effective tuning.

The multiple impedance peaks of a line are its fingerprint — comparing them against a measured impedance sweep is the single best model validation.

Charts

• All charts share a log frequency axis with labels at 10 / 20 / 50 / 100… and a fine dotted grid.

• Hover shows a cursor with the values of every visible variant at that frequency.

• On the SPL chart, the selected variant additionally shows its radiator breakdown — cone and port/terminus contributions as dashed lines. The deep notch where cone and port cancel is real physics, not an artifact.

• Measured curves appear long-dashed in their own colours.

• Impedance is always plotted unfiltered — a DSP chain in front of the amplifier does not change the speaker's impedance.

Simulation reference conditions: 2.83 V RMS at 1 m in half space, 25 °C — all adjustable in the inspector's Simulation section (frequency range too).

Filter chain

Each variant has an ordered list of filter stages applied to the drive voltage, before the driver model — so excursion, velocity, group delay and headroom all follow automatically. This is the point: a naive tool that just tilts the SPL curve would hide the excursion a bass boost actually causes.

• Stage types: high/low-pass (Butterworth, Linkwitz-Riley, Bessel, Chebyshev, orders 1–8), peaking EQ, shelves, all-pass, delay, gain, polarity, Linkwitz transform, and raw biquad coefficients pasted from an existing DSP setup.

• Adding a Linkwitz transform on a sealed box prefills f₀/Q₀ from the currently simulated alignment — enter your target ft/Qt and you're done.

• The footer shows the headroom cost live: "Headroom: 18.3 dB unfiltered → 9.1 dB filtered (Xmax limited at 24 Hz)". This is the number DSP bass extension usually hides.

• With an active chain, the charts keep the unfiltered response visible dimmed, plus a dotted trace of the chain response itself.

• Export Chain… produces biquad coefficients at your sample rate — plain text, C header, JSON (lossless round-trip) or the chain's response as FRD. Coefficients are bilinear-transformed with frequency prewarping and stability-checked; the sign convention is stated in the file header and switchable for DSPs that expect pre-negated a1/a2.

Importing measured data

Import (toolbar) accepts:

• FRD / ZMA / CSV / TXT — frequency, magnitude, optional phase; tab, space, semicolon or comma separated; comment lines and decimal commas are handled. .zma files import as impedance, everything else as SPL.

• .ameas bundles from SweepLab and ampMeasure — all far-field, near-field and impedance measurements come in at once, and if the bundle contains derived Thiele/Small parameters, the driver is imported too.

Imported curves appear in the sidebar with visibility toggles and are stored inside the document.

Fitting the model to a measured impedance

Once a cabinet is built, measure its impedance (ampMeasure) and import the sweep. With a variant selected, the inspector shows Fit to Measured Impedance: choose the curve, the frequency band, and which parameters to free —

• Sealed: absorption Qa

• Vented / bandpass: Ql, Qa, Qp

• Passive radiator: Ql, Qa

• Transmission line: stuffing density scale (the effective flow resistivity)

Fit runs a Nelder–Mead optimisation and applies the result, reporting the RMS error before and after. After the fit, the simulated SPL of variants you never built is worth trusting — that's the whole loop.

Exporting

• SPL as FRD, impedance as ZMA (with phase) — for crossover tools, or back into SweepLab as an overlay target.

• CSV with every computed quantity.

• Chart as PNG — follows your light/dark theme.

• Filter chains: see above.

Settings

⌘, or the gear in the toolbar: appearance (System / Light / Dark).

Conventions

Troubleshooting

My vented box shows a huge dip in SPL near tuning on the cone trace. That's the cone breakdown trace — the cone really does stand nearly still at fb while the port does the work. Look at the solid total line.

Measured SPL sits at a different level than simulated. Check that the measurement's drive voltage and distance match the Simulation settings (2.83 V, 1 m by default), and that the measurement was SPL-calibrated.

The fit doesn't converge. Restrict the band to where the box actually shows structure (typically 10–400 Hz), make sure the curve is an impedance measurement of the finished, stuffed cabinet, and free only the parameters you're unsure about — fewer is more stable.

A pasted datasheet won't import. The parser needs Fs, Qms, Qes, Re, Sd and Vas with recognisable labels. The error message lists exactly which ones it couldn't find.