Development

Development

Documentation home

The application uses a Python server and plain JavaScript. Standalone packaging and release checks are described in native builds.

Tagcast 0.70.0 includes artist profiles: local account-specific favourites, native artist ratings and optional, lazily cached TheAudioDB biographies. These use the same server and frontend, with Python's standard-library SQLite and no new runtime dependency. See ratings and favourites and background texts for user instructions. The Electron shell shares those files unchanged; its lifecycle and navigation tests run with node --test electron/tests/*.test.cjs. Node.js is only needed to develop or build the desktop shell, not to use a packaged download or the Python/browser route.

src/tagcast/static/dark.css is generated from src/tagcast/static/style.css by tools/build_dark_css.py. After a style change, run the generator and its consistency check; do not edit the generated file by hand.

uv run --frozen pytest -q
uv run --frozen ruff check src tests tools
python3 tools/release_info.py
python3 tools/build_dark_css.py --check
for f in src/tagcast/static/*.js; do node --check "$f"; done
node --test tests/frontend.test.cjs

Without uv, Python tests can also run with PYTHONPATH=src python3 -m unittest discover -s tests -v. After changing styles, regenerate with python3 tools/build_dark_css.py.

To try the connected flow with separate test settings and no real account:

python3 tests/mock_ibroadcast.py 9555 &
TAGCAST_IBROADCAST_BASE=http://127.0.0.1:9555 TAGCAST_HOME=/tmp/tagcast-test \
  IBROADCAST_CLIENT_ID=test PYTHONPATH=src python3 -m tagcast.app

API notes

Built on ibroadcast-python for OAuth device-code and PKCE browser-redirect flows, token refresh and the request format. The requested scopes are user.library:read, user.library:write and user.account:read.

The public API reference documents library reads, ratings and native tags (createtag, tagtracks, updatetag, deletetags); trash is supported by ibroadcast-python. Metadata modes (update_album, update_track, create_artist) and artwork modes (set_artwork, set_artist_artwork, get_artwork and artwork upload) partly follow the official web editor script, inspected on 2026-10-04. Year and disc are sent as strings and track number as track_no, matching the web editor. These write modes are not all publicly documented; server refusals and partial results are reported explicitly.

During Tagcast's app review, iBroadcast Support confirmed that these metadata and artwork operations are acceptable for third-party apps and that the existing sidebar logo placement is sufficient. Play and skip reporting are recommended, but optional; Tagcast's play reporting remains off by default.

Automated write tests use the mock iBroadcast server, which lets the save, read-back, trash, rating and artwork flows run without a real account. Passing mock tests does not establish compatibility with every live-service response. Audio streaming follows iBroadcast's web-player format, with the token kept in the local server.

Documentation maintenance

The Wiki has its own versioned Git repository:

git clone https://github.com/cyberdeliaAI/tagcast.wiki.git

Edit the relevant page, check relative Wiki links and use repository/raw URLs for images and source documents. Keep the repository README concise. The full pre-Wiki guide remains in the 0.60.0 README.

Media and press

The media kit contains the cassette logo, SVG and transparent PNG exports, wordmarks for light/dark backgrounds, screenshots and the GitHub social preview. Download all media as a ZIP.

Development credits

Developed by Cyberdelia, with AI-assisted development using Claude (Anthropic) and ChatGPT / Codex (OpenAI).

License

MIT for Tagcast code. The official Powered by iBroadcast logos belong to iBroadcast and are displayed unchanged under its branding guidelines. Tagcast is an independent project and not affiliated with iBroadcast.