https://github.com/3ll3d00d/beqdesigner
https://github.com/3ll3d00d/beqdesigner
audio-analysis python3 qt5 signal-processing
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/3ll3d00d/beqdesigner
- Owner: 3ll3d00d
- License: mit
- Created: 2018-08-16T21:01:34.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2026-03-08T21:21:35.000Z (3 months ago)
- Last Synced: 2026-03-09T02:41:24.928Z (3 months ago)
- Topics: audio-analysis, python3, qt5, signal-processing
- Language: Python
- Size: 14.7 MB
- Stars: 32
- Watchers: 5
- Forks: 5
- Open Issues: 30
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/3ll3d00d/beqdesigner/actions)
# BEQDesigner
A Qt desktop app for designing, analysing and applying Bass EQ (BEQ) filters for
movie soundtracks.
**User documentation lives at [beqdesigner.readthedocs.io](https://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](https://python-poetry.org/), and (optional,
runtime only) `ffmpeg` + `graphviz`.
```sh
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
```sh
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`:
```sh
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`:
```sh
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:
- Concepts (what BEQ is, pre- vs post-bass-management): `docs/index.md`,
`docs/concepts.md`, `docs/workflow/`
- Install instructions for release binaries:
- Release/download page: