This guide covers what you need to set up the project, run it locally, and contribute changes. For a high-level tour of how the codebase fits together, see architecture.md.
- Python 3.13 or later
- uv
- just
- libmpv
- Linux: install via your package manager
- Windows: download libmpv (mpv-dev-x86_64), extract it, and place the
libmpv-*.dllin the repository root
- Windows only: Git Bash —
justrecipes assume a POSIX shell
Clone the repository, then from the repo root:
just init # install dependencies and configure dev tooling
just build-develop # compile QML, data, and translations into rc_project.py
uv run main.py # launch the applicationWhenever you change files in data/, i18n/, or qt/qml/, re-run just build-develop so the resource bundle is regenerated. Configure your IDE to run it before launching the app.
| Recipe | What it does |
|---|---|
just test |
Run Python tests and QML tests (recompiles resources first) |
just prepare-tests |
Recompile resources for testing (runs build-develop then stages it) |
just test-python |
Run Python tests only — does not recompile |
just test-qml |
Run QML tests only — does not recompile |
just test-qml-debug TARGET |
Run a single QML test file matched by name (useful for iteration) |
just fmt |
Format and lint Python, QML, JSON, TOML, YAML, Markdown |
just lint-qml |
Run pyside6-qmllint |
just build-develop |
Recompile QML/data/i18n into the resource bundle |
just clean |
Remove all generated files |
just add-translation LOCALE |
Start a new translation (see internationalization.md) |
just update-translations |
Refresh existing .ts files from current source strings |
After changing production QML, data, or translation files, run just prepare-tests (or just test, which invokes it) so the resource bundle test runners load is up to date. When iterating on test code only, just test-qml and just test-python run directly without recompiling.
| Path | Contents |
|---|---|
mpvqc/ |
Python: services (business logic), viewmodels (Qt-exposed glue), application bootstrap |
qt/qml/ |
QML modules following a reverse-DNS layout, with unit tests colocated alongside sources |
test/ |
Python tests (pytest) — services and viewmodels in isolation |
testqml/ |
Test harness for QML integration tests: bridge, fixtures, injection overrides |
data/ |
Fonts, icons, default mpv.conf / input.conf, themes, build-info.toml |
i18n/ |
Translations as .ts source files; .qm binaries are generated |
build-aux/ |
Generator scripts: pyproject.toml files-list updater, qrc generator, lupdate project file |
docs/ |
These docs |
- architecture.md — high-level overview of how Python, QML, and the test harness fit together
- configuration.md — runtime environment variables
- internationalization.md — adding and updating translations
- releasing.md — release checklist