BEQDesigner

A Qt desktop app for designing, analysing and applying Bass EQ (BEQ) filters for movie soundtracks.

User documentation lives at beqdesigner.readthedocs.io. Start there if you want to know what BEQ is, how to install a release build, or how to use the app. This README is for developers working on the source.

Developer quickstart

Requirements: Python 3.13, Poetry, and (optional, runtime only) ffmpeg + graphviz.

poetry env use python3.13
poetry install
PYTHONPATH=./src/main/python poetry run python src/main/python/app.py

The PYTHONPATH prefix matches how CI invokes the app and tests — the source root is src/main/python, not the repo root.

Tests

PYTHONPATH=./src/main/python poetry run pytest --cov=./src/main/python

Tests live in src/test/python/ and run on every push via .github/workflows/test.yaml across Linux, macOS and Windows.

Building the app bundle

Release binaries are produced by PyInstaller from beqdesigner.spec:

poetry run pip install pyinstaller
poetry run pyinstaller --clean --log-level=INFO beqdesigner.spec

On macOS this yields dist/beqdesigner.app. On Linux a virtual X server is required (Xvfb) — see the Create distribution step in test.yaml for the exact invocation used in CI.

Project layout

Path	Contents
src/main/python/app.py	Entry point — creates QApplication and BeqDesigner main window
src/main/python/ui/	Qt Designer .ui files and their generated .py equivalents, plus view code
src/main/python/model/	Non-UI logic: filters, signals, IIR, ffmpeg, minidsp, jriver, htp1, checker, preferences, …
src/main/python/acoustics/	DSP helpers (smoothing, weighting, standards)
src/main/python/mpl.py, svg.py, style/	Matplotlib integration, SVG export, mpl styles
src/test/python/	pytest suite + fixtures
beqdesigner.spec	PyInstaller build recipe (Windows / Linux / macOS branches)
.github/workflows/	test.yaml (CI) and create-app.yaml (release builds)
docs/	Source for the readthedocs site (MkDocs)

Working with Qt Designer files

Forms are edited as .ui files in Qt Designer and compiled to Python with pyuic6:

cd src/main/python/ui
poetry run pyuic6 foo.ui -o foo.py

See src/main/python/ui/convert.sh and convert.bat for batch scripts (the paths in them are hard-coded to a contributor's venv — regenerate the pyuic6 path from your own poetry env info --path).

Generated .py files are checked in — regenerate them whenever the .ui changes. Do not hand-edit the generated files.

Conventions worth knowing

• qtpy is used as the Qt abstraction layer but the environment is pinned to PyQt6 at the top of app.py. Import from qtpy.*, not PyQt6.*, in new code.
• Logging goes through an in-memory RollingLogger (model/log.py) surfaced via Help → Logs in the UI — there is no on-disk log file, so run from a terminal to see tracebacks.
• User settings are stored via QSettings under ~/Library/Preferences/com.3ll3d00d.beqdesigner.plist (macOS) / registry (Windows) / ~/.config/3ll3d00d/beqdesigner.conf (Linux).
• Version string is read from src/main/python/VERSION — CI writes the short git SHA into this file at build time; running from source without it falls back to 0.0.0-alpha.1.

Further reading

• User guide, workflows and UI reference: https://beqdesigner.readthedocs.io/
• Concepts (what BEQ is, pre- vs post-bass-management): docs/index.md, docs/concepts.md, docs/workflow/
• Install instructions for release binaries: https://beqdesigner.readthedocs.io/en/latest/install/
• Release/download page: https://github.com/3ll3d00d/beqdesigner/releases