Antra - Moses Yebei

Abstract

A desktop music library builder that turns Spotify, Youtube Music Apple Music, Amazon Music, Tidal, Qobuz, and Deezer links into fully tagged local library in FLAC, ALAC, AAC, or MP3.

The Problem

Building a local music library from streaming service links is fragmented: each service has its own URL scheme, metadata quality, and download method. Users end up with untagged files, messy folder structures, and no way to get a coherent, media-server-ready collection. Antra solves this by turning links from Spotify, YouTube Music, Apple Music, Amazon Music, Tidal, Qobuz, and Deezer into a fully tagged local library in FLAC, ALAC, AAC, or MP3.

What This Does

Antra is a desktop application with a Python backend (antra/) and a Wails-based GUI (antra-wails/). It fetches track metadata, downloads audio, tags files with title, artist, album, artwork, genre, and lyrics, then files them into an Artist / Album structure ready for Navidrome, Jellyfin, or Plex.

The core logic lives in antra/core/ — service.py orchestrates sources, engine.py handles downloads and errors, and resolver.py tracks source success. Each streaming service has a fetcher in antra/sources/ (e.g., amazon.py, apple.py, tidal.py). The GUI layer in antra-wails/ wraps the Python backend via Go bindings.

How It Is Wired

Execution starts at main in antra/__main__.py:502, which reaches 400 functions. From there, run (line 685) dispatches to either process_library_mode or process_resources. The shortest path to an external effect is main -> cleanup_project_junk (filesystem via shutil.rmtree), and process_resources -> fetch_playlist_tracks -> _fetch_spotfetch_tracks (network via SpotFetchFetcher).

The most-connected module is antra/core/models.py — 36 modules import it, making it the highest-blast-radius file. antra/core/service.py is the hub for orchestration (58 functions, 31 imports), while antra/sources/amazon.py is the most complex source (42 functions, calls out to network, filesystem, and subprocesses). The call graph shows search is called from 58 places, TrackMetadata from 30, and resolve from 16 — changing these ripples widely.

The module graph has no circular dependencies, which keeps refactoring tractable. antra/core/models.py is a stable hub (instability 0), while antra/core/service.py (0.94) and antra/core/engine.py (0.93) are highly unstable — they depend on everything else, so changes to them are low-risk but changes to their dependencies are not.

How To Use It

Setup: Clone with git clone https://github.com/moses-y/Antra. The repo has requirements-desktop.txt and requirements-runtime.txt for Python, and antra-wails/go.mod for the Go backend.
Configuration: .env.example shows required env vars. The GUI is configured via antra-wails/wails.json.
Running it: The Python CLI entry point is python -m antra. The desktop app builds via build_desktop.py (Wails). No Dockerfile or Makefile exists, so build commands are not documented in-repo.

Real-World Use

A user pastes a Spotify playlist link into the GUI. The backend resolves the URL via antra/core/spotify.py, fetches track metadata, downloads audio, tags it with antra/utils/tagger.py, and files it into Artist/Album/ via antra/utils/organizer.py. The result is a media-server-ready library without manual tagging.

Code Health & Issues

Static analysis found 100 issues (29 high, 71 medium) across 6 kinds. Key findings:

High - No test suite: 90 source files, zero test files. Any change ships with no regression signal.
High - Unpinned GitHub Actions: .github/workflows uses softprops/action-gh-release@v2 — a tag can be moved, risking token exposure.
Med - Broad exception handling: 24 instances of bare except in antra/utils/runtime.py, antra/core/config.py, and antra/core/amazon_music_fetcher.py.
Med - Deep nesting: 24 files with max indentation depth 10, notably antra/core/apple_fetcher.py and antra/core/spotify.py.
Med - No dependency scan or Dependabot in CI.
Med - Duplicated code: 190 repeated 6-line blocks across 30 files.
Low - No job timeouts in CI, missing .editorconfig and .gitattributes.

The Bottom Line

Antra is a functional, well-structured music library builder with a solid module layout and no circular dependencies. The lack of tests and unpinned CI actions are the main risks for anyone maintaining it. It is useful for users who want a self-hosted, tagged library from streaming links; engineers should add tests and pin CI before relying on it.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

135 files

Python69
Go10
JSON7
TypeScript6
JavaScript3
YAML2

ReactSvelteExpress

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["antra<br/>66 modules"] g1["antra-wails<br/>9 modules"] g2["antra_shared<br/>2 modules"] g0 -->|1| g2

Module dependencies

The 10 most depended-upon modules of 78, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_antra_core_models["models"] n1_antra_utils_matching["matching"] n2_antra_sources_base["base"] n3_antra_utils_runtime["runtime"] n4_antra_core_config["config"] n5_antra_core_apple_fetcher["apple_fetcher"] n6_antra_core_spotify["spotify"] n7_ra_core_amazon_music_fetcher["amazon_music_fetcher"] n8_antra_utils_lyrics["lyrics"] n9_antra_sources_odesli["odesli"] n7_ra_core_amazon_music_fetcher --> n0_antra_core_models n5_antra_core_apple_fetcher --> n0_antra_core_models n5_antra_core_apple_fetcher --> n1_antra_utils_matching n6_antra_core_spotify --> n0_antra_core_models n6_antra_core_spotify --> n1_antra_utils_matching n2_antra_sources_base --> n0_antra_core_models n8_antra_utils_lyrics --> n0_antra_core_models

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium3

low2

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

softprops/action-gh-release@v2

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a test suite; this repository has nonehigh90 occurrences

90 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Enable Dependabot or Renovatemedium

5 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/release.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow

.github/workflows/release.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.