crabidy/jamendody/README.md

jamendody — the Jamendo provider

Mounts Jamendo at /jamendo in the crabidy library: search a large catalogue of Creative-Commons licensed music, play it, and browse the album a track came from.

Logging in

Nothing to do. Jamendo has no user login — the public catalogue needs only an app key (client_id) identifying the application, not you, and this crate ships a working default (DEFAULT_CLIENT_ID). /jamendo mounts with no configuration, and init writes the key it used into jamendo.toml so the effective value is always visible.

Bring your own key if you use Jamendo heavily — the rate limit is per key, so the shipped default is a shared budget:

1. Register at devportal.jamendo.com and create an application.
2. Copy its Client ID into ~/.config/crabidy/jamendo.toml as client_id.
3. Restart the server. A configured key always wins over the default.

Nothing expires and there is no refresh flow. The key is redacted from Debug and never logged, but keep the file private.

How it works

/jamendo
├── search                  create a search term with `%`
│   └── <term>              matching tracks
├── track/<id>              a single track (canonical address)
└── album/<id>              an album and its tracks (canonical address)

search is creatable: press % and type a term, and the term becomes a child node holding its results. e renames it (re-running the search), d deletes it. Terms live in memory, so a restart forgets the list.

Tracks and albums are addressed by id whatever browse node you reached them through, so a queued track survives deleting the search term that found it. From a track you can navigate to its album to hear the rest.

Playback is a direct MP3 URL streamed over the player's ordinary HTTP path — no HLS, no helper binary, and seeking works. Captures (W) download those files into the content store.

Configuration — ~/.config/crabidy/jamendo.toml

# The app key. Unset (or blank) uses the key this crate ships with, which is
# written back here on first start. Replace it with your own from
# devportal.jamendo.com for your own rate limit.
# client_id = "..."

# Optional, defaults shown.
# audioformat = "mp31"      # "mp31" (default) or "mp32"; see below
# search_results = 50       # tracks per search term (Jamendo caps at 200)
# album_tracks = 200        # tracks listed per album
# call_timeout_secs = 30    # per-request timeout

mp31 is Jamendo's freely streamable MP3. mp32 (higher bitrate) is not reliably provisioned for the streaming URL and comes back empty for many tracks, which is why it is not the default; a Pro account can set it explicitly. When a track has no audio in the requested format the provider falls back rather than failing the listing.

Failure behavior

• Missing or empty client_id: the shipped default is used.
• A revoked or rate-limited key: listings error, the provider stays mounted.
• API or network failure: the affected listing errors, the provider stays.

Build the server without the jamendo cargo feature to leave this provider out of the binary entirely.