smfetch

Web interface for downloading simfiles from Zenius-i-Vanisher and StepManiaOnline.

Usage

usage: smfetch [-h] [-p PORT]

smfetch web interface

options:
  -h, --help       show this help message and exit
  -p, --port PORT  port for the web interface (default: 8095)

Starts a web interface at http://localhost:<port>.

Features

Update tracking

smfetch remembers which packs you have installed and when, then watches Zenius' latest official and latest user listings for changes to those packs. When a chart is revised or added, it is downloaded individually into the pack it belongs to — no re-downloading a whole pack for one chart.

• Review before applying. Detections collect in the Updates view. You choose what to pull and when; nothing downloads on its own.
• One entry per chart. If a chart changes several times between applies it stays a single pending item that advances to the newest version, so applying fetches the latest revision once. If a chart changes again while its download is running it stays pending for the next pass, rather than being silently marked current.
• Adopting what you already have. Scan the songs directory to find pack folders smfetch did not install and link them to their Zenius category by name match. Charts already on disk are treated as current, so only changes published after linking are reported.
• StepManiaOnline packs too. The two sites carry many of the same packs, so a pack downloaded from StepManiaOnline can be linked to its Zenius counterpart and updated from there. Linking records the origin separately, so the pack still shows where it came from. Song folders are matched by name when linking — attitude on disk against Attitude on Zenius — so an update replaces the song already installed instead of dropping a second copy beside it. A chart the pack does not have yet arrives under its Zenius title.

Update checking joins on a Zenius pack, so a pack with no link is never checked. The Installed Packs view marks those unlinked and offers to link them.

Checks run on a configurable interval (6 hours by default) and on demand. The user listing only reaches back about a week, so an interval of a day or less is worthwhile if you follow user packs.

Zenius-i-Vanisher

• Song search — search by song name and/or artist, select and download individual charts
• Pack search — filter official or user packs, download selected packs
• Bundles — one-click download of arcade, spinoff, or all official packs

StepManiaOnline

• Title search — search packs that contain a chart with a song title
• Artist search — search packs that contain a chart by an artist
• Pack search — filter all packs by name

Interface

The UI is dependency-free HTML, CSS and JavaScript served straight from the package — no build step, and no network fetches at runtime. It follows your system light/dark preference and has a manual toggle.

Storage Defaults

Installed packs and pending updates live in library.json inside the config directory. Deleting it only loses update history — nothing on disk is touched, and a scan will re-adopt your packs.

Development

make run      # start the app
make format   # ruff format
make check    # ruff lint + ty
make test     # pytest
make install  # clean, format, check, sync, test

The test suite is fully offline and takes well under a second. Scrapers run against trimmed captures of real Zenius pages in tests/fixtures/, so changes to the parsing are checked against the markup the site actually serves; the rest runs against a scriptable fake site with Zenius' clock pinned, and any unexpected request fails the test rather than reaching the network. Config, songs and library state are redirected to a temporary directory, so running the tests never touches your real collection.

Notes on upstream timestamps

Zenius reports ages relative to its own clock ("2.6 days ago") and exact times only on an individual simfile's page. smfetch derives the site's clock offset from a recent simfile so relative ages resolve to absolute times, screens the listings cheaply with those, and confirms anything that looks changed against the exact timestamp before recording it. Rounded ages carry real slop — a value in weeks is only good to a few hours — so comparisons allow a tolerance scaled to the unit, which is what keeps unchanged charts from reappearing as updates.