CI & packaging¶
GitHub Actions¶
Python CI, Tauri Build and Docs run on ubuntu-latest. Python CI and Tauri Build run on every
push and pull request; Docs runs when docs/, overrides/ or mkdocs.yml change. Release runs
on version tags (see Releases).
- Python 3.13,
pip install -r amp/requirements.lock ruff check amp/backend/python -m pytest -m "not integration" --cov=backend --cov-report=xml(fromamp/)- Upload
coverage.xmlto Codecov (needs theCODECOV_TOKENsecret; failures don't fail the job)
- WebKitGTK and friends via apt, stable Rust, Rust cache
- Python 3.13 +
requirements.lock, thenpython scripts/build_sidecar.py --smoke - Node 24,
npm ci,npm test(vitest) npx tauri build --bundles deb, the.debuploaded as an artifact
- Python 3.13,
pip install -r docs/requirements.txt mkdocs build --strict- On
masteronly: deploy the site to GitHub Pages
Integration tests don't run in CI (they need YouTube). The smoke test's search does hit YouTube from the runner, which can behave differently from a home connection.
Lint¶
.ruff.toml at the repo root: pyflakes, pycodestyle errors, bugbear and bandit rules, tests
excluded. fastapi.Depends/Query/Header are declared immutable for B008. An inline noqa must
give its reason, e.g. # noqa: S311 - backoff jitter, not crypto.
Coverage¶
Configured in amp/pyproject.toml ([tool.coverage.*]): source backend, tests omitted,
branch coverage. fail_under = 60 is a regression floor; raise it as coverage grows.
The sidecar¶
Release builds don't use Python from the system: the backend is frozen by PyInstaller into one executable that Tauri bundles as a sidecar.
pyinstaller amp-backend.spec --noconfirm→dist/amp-backend[.exe]- Reads the host target triple from
rustc -vV. - Copies it to
frontend/src-tauri/binaries/amp-backend-<triple>[.exe], the namebundle.externalBinexpects. --smoke: starts the copy on a free port with a temporary data dir, checks/api/healthand a search, closes its stdin and checks that it exits.
What amp-backend.spec takes care of
collect_submodules("backend"): a hand-written list of hidden imports missed modules.collect_data_files("yt_dlp_ejs")(the JS solver's scripts) andytmusicapilocales.console=True: the backend needs real stdin/stdout pipes for--parent-watchand log forwarding, and uvicorn's logging breaks on aNonestdout. No window appears because Tauri spawns it withCREATE_NO_WINDOW.- One-file mode: data can't live next to
__file__(a temporary extraction folder), hence the frozen data dir default.
Tauri checks that the sidecar file exists even for tauri dev, though the dev build runs
the venv. Rebuild it after any dependency change, yt-dlp especially, or the installed app keeps
the old copy.
Node.js isn't bundled: the installed app needs it on PATH.
Building the app¶
cd amp
python scripts/build_release.py [--exe-only] [--bundles LIST] [--skip-sidecar] [--smoke]
python scripts/build_release.py --run # AMP-build-and-run.bat at the repo root
- Runs
build_sidecar.py(with--smokeif asked), andnpm ciifnode_modulesis missing. npx tauri build(--no-bundlewith--exe-only,--bundles LISTwhen given).- Copies
target/release/amp[.exe](renamedAMP), theamp-backend[.exe]Tauri put next to it and any*.dllthere intobuild/AMP-<version>-<os>-<arch>/, archives that folder (.zipon Windows,.tar.gzelsewhere), and copies the installers intobuild/installers/.
The Rust toolchain here is x86_64-pc-windows-gnu: that target loads WebView2Loader.dll at
startup instead of linking it in (msvc does), so AMP.exe without the DLL next to it fails with
"WebView2Loader.dll was not found".
--run rebuilds the sidecar when a file under backend/, the spec or requirements.lock is newer
than binaries/amp-backend-*, and the app when a frontend or src-tauri source (sidecar included)
is newer than build/AMP-…/AMP.exe; then it starts that exe. No installer, no archive.
The version comes from tauri.conf.json. build/ at the repo root is gitignored (not to be
confused with amp/build/, PyInstaller's work folder).
Installers aren't signed (SmartScreen warns, macOS Gatekeeper asks), and antivirus tools may flag the one-file sidecar; switching the spec to one-folder mode is the fix if that becomes a problem.
Releases¶
.github/workflows/release.yml runs on a v* tag push (or by hand). Each runner calls
build_release.py --smoke --bundles …:
| Runner | Bundles |
|---|---|
windows-latest |
msi,nsis |
macos-latest (Apple Silicon) |
app,dmg |
ubuntu-22.04 |
deb,appimage (oldest runner, for older glibc) |
On a tag, a last job downloads everything and creates a draft GitHub release with
CHANGELOG.md as its notes. Run by hand, it only uploads the files as workflow artifacts.
To release: bump the version in tauri.conf.json, Cargo.toml and package.json, add a
CHANGELOG.md entry, commit, git tag vX.Y.Z && git push origin vX.Y.Z, then publish the draft.
Dependency upgrades¶
- Python:
requirements.txtholds ranges (major versions capped, except yt-dlp). After upgrading, run the unit suite, thenpip freeze > requirements.lock. CI installs from the lock. - yt-dlp:
pip install -U "yt-dlp[default]", run the integration download test, refresh the lock, rebuild the sidecar. If extraction slows down or fails, re-measure the player clients. - Frontend:
npm install,npm run build,npm test;package-lock.jsonis committed. - Rust:
Cargo.lockis committed;cargo updatethennpx tauri build.
Documentation¶
This site is built with MkDocs Material from docs/ and mkdocs.yml at the repo root:
pip install -r docs/requirements.txt
mkdocs serve # http://127.0.0.1:8000, live reload
mkdocs build --strict # fails on broken links
mkdocs serve uses port 8000 by default, like a manually started backend: pass
-a 127.0.0.1:8001 if both run at once.