78 lines
3.2 KiB
Markdown
78 lines
3.2 KiB
Markdown
# 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.
|