# jamendody — the Jamendo provider

Mounts [Jamendo](https://www.jamendo.com) 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](https://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

```text
/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`

```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.