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.
Requirements: Python 3.13, uv, and (optional,
runtime only) ffmpeg + graphviz.
uv sync
PYTHONPATH=./src/main/python uv run python src/main/python/app.pyThe PYTHONPATH prefix matches how CI invokes the app and tests — the source
root is src/main/python, not the repo root.
PYTHONPATH=./src/main/python uv run pytest --cov=./src/main/pythonTests live in src/test/python/ and run on every push via
.github/workflows/test.yaml across Linux, macOS and Windows.
Release binaries are produced by PyInstaller from beqdesigner.spec:
uv pip install pyinstaller
uv run pyinstaller --clean --log-level=INFO beqdesigner.specOn 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.
| 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) |
Forms are edited as .ui files in Qt Designer and compiled to Python with
pyuic6:
cd src/main/python/ui
uv run pyuic6 foo.ui -o foo.pySee src/main/python/ui/convert.sh and convert.bat for batch scripts. uv
creates its virtualenv at .venv in the repo root by default, so
convert.sh resolves pyuic6 there; convert.bat is still hard-coded to a
contributor's own environment and will need adjusting to your own venv path.
Generated .py files are checked in — regenerate them whenever the .ui
changes. Do not hand-edit the generated files.
qtpyis used as the Qt abstraction layer but the environment is pinned to PyQt6 at the top ofapp.py. Import fromqtpy.*, notPyQt6.*, 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
QSettingsunder~/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 to0.0.0-alpha.1.
- 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