USDB Syncer
USDB Syncer is an app to download and synchronize UltraStar songs hosted on USDB.
The project extensively uses the #VIDEO tag to automatically retrieve the resources (audio, video, images, etc...) to make the UltraStar song complete.
Once a song is downloaded it can be synchronized (new notes, audio, video, images...) by redownloading the song. If a resource didn't change it's skipped.
Installation
There are three ways to run USDB Syncer:
- To run from source, see Development.
- Use your favourite package manager to install the Python package, e.g. pipx:
pipx install usdb_syncer - We provide ready-to-run executables for all major operating systems.
[!NOTE] We publish pre-releases on PyPI based on the main branch. If you need a feature early, check out those. For pipx, use
pipx install --pip-args="--pre" usdb_syncer
[!IMPORTANT]
Linux users should check Linux Compatibility as additional configuration is usually required.
Development
USDB Syncer is written in Python, and uses uv to manage its dependencies. The following explains how to set up a development environment.
Prerequisites
- git
- Python 3.12 (3.11 should work as well)
- uv
Project Setup
Clone the project:
git clone https://github.com/bohning/usdb_syncer.git
cd usdb_syncer
Install dependencies:
uv sync
Run usdb_syncer
The package has a defined entry point for the GUI. Simply run:
uv run usdb_syncer
Run tests
tox makes it easy to run the full CI pipeline on your local machine, i.e., if the pipeline passes on your machine there is a good chance it will also pass on the build server.
Run uv run tox to execute the test pipeline. The tox pipelines are configured in the tox.ini file.
Configurations for specific tools in the pipeline are maintained in the pyproject.toml file.
Tox is configured to create its own virtual environments, install test dependencies and the package you are developing, and run all tests.
If you changed the test requirements or want to perform a clean run for some reason, you can run uv run tox -r to recreate tox's virtual environment.
The following tools are part of the test pipeline:
-
mypy: Statically checks your type hints.
-
ruff: A linter and code formatter.
-
pytest: Provides a framework for functional unit tests.
-
unittest: A built-in objective unittest framework with extensive support for mocking.
If you don't want to run the whole test pipeline, you can also use single commands from the pipeline, e.g., uv run pytest. The tools will automatically pick up the correct configuration from the pyproject.toml file.
Versioning
USDB Syncer uses semantic versioning (semver) as versioning scheme.
However, since USDB Syncer is not a library/API but a user-facing application, we use MAJOR, MINOR and PATCH
versions according to the following scheme:
MAJORversion increments mean a breaking change for the end user, be it the need to install additional (3rd party) tools or changes that make it necessary to make changes to the already downloaded songs.MINORversion increments only involve adding backward compatible features.PATCHversion increments bring bugfixes.
We will try to avoid MAJOR version increments whenever possible, but since the project is still in the
startup phase, they cannot be completely ruled out.
Addons
USDB Syncer supports simple addons. Consult addons/README.md for detailed information.
Support
Troubleshooting
-
With Qt issues, set the
QT_DEBUG_PLUGINSenvironment variable to 1, then re-run. It will output diagnostics while running. -
The
keyringpackage auto-detects an appropriate installed keyring backend (see PyPI - keyring). This may require following additional package if no backend can be detected, see #136With KDE, a Wallet may have to be activated in the system settings.
With gnome, install gnome-keyring
apt install gnome-keyring
You can also disable the keyring entirely by setting
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring. The Syncer will not be able to store your USDB password in that case. -
One user using KDE Plasma experiencing an issue with the menu bar solved it by forcing XWayland instead of Wayland being used:
env WAYLAND_DISPLAY=.
Linux Compatibility
Required packages
The bundle contains most of the required packages. You will need to supply video libraries (which should be included for your desktop already) as well as pipewire and portaudio.
If you do encounter a warning or an error, set export QT_DEBUG_PLUGINS=1 to see the exact library you are missing.
More packages are required when running from source or the official Python package:
Ubuntu/Debian
apt install libgssapi-krb5-2 libgl1 libegl1 libva2 libva-drm2 libva-x11-2 libpipewire-0.3-0 libportaudio2 libxkbcommon0 libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxrandr2 libfontconfig1
Fedora
dnf install libglvnd-glx libglvnd-egl fontconfig libxkbcommon libXrandr libxkbcommon-x11 xcb-util-cursor xcb-util-wm xcb-util-keysyms libva pipewire portaudio
Arch
pacman -Sy fontconfig libxkbcommon libxkbcommon-x11 xcb-util-cursor xcb-util-wm xcb-util-keysyms pipewire portaudio
You can also use the corresponding wayland libraries. We will fix issues related to wayland, but we don't test on wayland, which is why problems may be more frequent.
Compatibility
The wheels are pure Python with no extension modules, and are thus only restricted by the Python version.
Linux bundles are generated on an AlmaLinux 9 host. They should be compatible with any modern distribution. If not, please open an issue.
They are linked against glibc 2.34. The current glibc version can be checked with:
ldd --version
We confirm support automatically for these distros:
- Ubuntu 22.04 (Deadsnakes PPA), 24.04, 25.10
- Debian 12, 13
- Fedora 42, 43
- Arch
The following distros are officially unsupported:
- Ubuntu 20.04
- Debian 11
1 maintainer
Metadata
1 maintainer
Release files for usdb-syncer 0.25.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| usdb_syncer-0.25.0.tar.gz | 2.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| usdb_syncer-0.25.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.8 MB
Release files / usdb_syncer-0.25.0.tar.gz
| Download URL | usdb_syncer-0.25.0.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
16fafbcf9169deaf13552bbb5abe00b5930b0f01406e4b222e6f8e1967690f7c
|
|
BLAKE2b-256 checksum How to use checksums |
847b2f046a47a7d979a903943c4e7587b224c8a39be5385d87f1d495f0fd4ee7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 20, 2026.
Transparency logRelease files / usdb_syncer-0.25.0-py3-none-any.whl
| Download URL | usdb_syncer-0.25.0-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e2a98712424221caa53425237d060fa9e715187d4820995f1cdd18a95f48948
|
|
BLAKE2b-256 checksum How to use checksums |
00041702343762b54aceac81ec0925822ae6891546b57386b968b6188ccf38a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 20, 2026.
Transparency log
