USDB Syncer

USDB Syncer is an app to download and synchronize UltraStar songs hosted on USDB. The project extensively uses the #VIDEO tag to automaticly 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.

Development

USDB Syncer is written in Python, and uses Poetry to manage its dependencies. The following explains how to set up a development environment.

Prerequisites

• git
• Python 3.12
• Poetry

Project Setup

Clone the project:

git clone https://github.com/bohning/usdb_syncer.git
cd usdb_syncer

Additionally requires extra packages when developing on Linux:

apt install -y gcc python3-dev libdbus-1-dev
pkg-config --cflags --libs dbus-1
# fix for installing dbus-python
export LDFLAGS="-lm"

Now make sure the Python 3.12 environment you installed Poetry to is activated and run:

poetry install
# optionally activate the venv
poetry shell

Run usdb_syncer

The package has a defined entry point for the GUI. Simply type in usdb_syncer in your terminal (poetry run usdb_syncer if you did not activate the venv).

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 tox (or poetry 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 tox -r to recreate tox's virtual environment.

The following tools are part of the test pipeline:

• isort: Automatically sorts your imports.

• black: Automatically and deterministically formats your code.

• mypy: Statically checks your type hints.

• pylint: Statically checks your code for errors and code smells.

• 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., 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:

• MAJOR version 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.
• MINOR version increments only involve adding backward compatible features.
• PATCH version 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.

Support

Troubleshooting

• may require extra packages on Linux

  apt update
  apt install libdbus-1-3

• The keyring package auto-detects an appropriate installed keyring backend (see PyPI - keyring). Thus may require following additional package if no backend can be detected, see #136

  apt install gnome-keyring

• 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 Distributions

Linux Build are generated on Ubuntu:latest, should run on Ubuntu >=22.04

known requirements:

• package glibc >= 2.35

  Therefore the following table (based on https://pkgs.org/search/?q=glibc, 8.7.2023) summarizes different Linux Distributions for having greater or equal version of glibc. For (likely) supported distributions the minimum OS Version is given that has a required glibc version. For (likely) unsupported distributions the recent highest Versions (if known) of Linux Distributions with its highest glibc version is given:

  	OS	OS Version	glibc
  ❌	AlmaLinux	9	2.34
  ❌	ALT Linux	P10	2.32
  ❌	Amazon Linux	2	2.26
  ✅	Arch Linux		2.37
  ❌	CentOS	9	2.34
  ❌	Enterprise Linux	7	2.24
  ✅	Debian	12 "Bookworm"	2.36
  ✅	Fedora	38	2.37
  ✅	KaOS		2.36
  ✅	Mageia	Cauldron	2.36
  ✅	OpenMandriva	Rolling & Cooker	2.37
  ✅	openSUSE Tumbleweed		2.37
  ❌	Oracle Linux	9	2.34
  ✅	PCLinuxOS		2.36
  ❌	Rocky Linux	9	2.34
  ✅	Slackware		2.37
  ✅	Solus		2.36
  ✅	Ubuntu	23.04	2.35
  ✅	Void Linux		2.36

  ❌ pretty sure not working

  ✅ should work

confirmed support:

• Ubuntu 23.04