# Jamendo — /jamendo

<!-- toc -->

Mounts [Jamendo](https://www.jamendo.com) at `/jamendo`: search a large
catalogue of Creative-Commons licensed music, play it, and browse the album a
track belongs to.

## Logging in

There is nothing to do. Jamendo has no user login — its public catalogue
needs only an **app key** (`client_id`) that identifies the *application*, not
you, and crabidy ships a working default. `/jamendo` mounts out of the box,
and the key it used is written into `jamendo.toml` so you can always see which
one is in force.

You may still want your own key, because Jamendo's rate limit is **per key**:
a shipped default is a shared budget, and a heavy user is better off with
their own.

1. Register at [devportal.jamendo.com](https://devportal.jamendo.com) and
   create an application.
2. Copy its **Client ID**.
3. Put it in `~/.config/crabidy/jamendo.toml`:

   ```toml
   client_id = "<your jamendo client id>"
   ```

4. Restart the server. A configured key always wins over the default.

No token refresh, no expiry, nothing to maintain. The key is treated as a
semi-secret: it is redacted from logs, but keep the file private.

## The tree

```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 a creatable node: press `%` and type a term, and the term becomes
a child node holding its results. Rename it (`e`) to re-run the search,
delete it (`d`) to drop it. Terms live in memory only, so a restart forgets
the list. See [Search](./search.md).

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

## Playback

Jamendo hands out a direct MP3 URL per track, which the player streams over
its ordinary HTTP path — no HLS, no helper binary, and seeking works.
Captures (`W`) download those files into the content store.

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

## Configuration — `jamendo.toml`

```toml
# The app key. Unset (or blank) uses the key crabidy ships with, which is
# written back here on first start so you can see what is in use. Replace it
# with your own from devportal.jamendo.com to get your own rate limit.
# client_id = "..."

# Optional, defaults shown.
audioformat       = "mp31"   # "mp31" (default) or "mp32" (see above)
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
```