91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
# soundclouddy — the SoundCloud provider
|
|
|
|
Mounts SoundCloud at **`/soundcloud`** in the crabidy library: search the
|
|
public catalogue, resolve a track or playlist link, and — with a token — your
|
|
own likes and playlists.
|
|
|
|
## Logging in (optional)
|
|
|
|
This is the one provider that works with **no credentials at all**. Public
|
|
browsing and playback need only a `client_id`, which the provider scrapes
|
|
from SoundCloud's own web app on first start and writes back into
|
|
`soundcloud.toml` so later starts reuse it. Nothing to do.
|
|
|
|
A login adds exactly two nodes, `likes` and `playlists`. To enable them, put
|
|
an OAuth token in the config:
|
|
|
|
```toml
|
|
oauth_token = "<your soundcloud oauth token>"
|
|
```
|
|
|
|
The token is what SoundCloud's own web app uses for your session; read it out
|
|
of a logged-in browser — the `oauth_token` cookie on `soundcloud.com`, or the
|
|
`Authorization: OAuth …` header on any API request in the network tab.
|
|
SoundCloud no longer offers public API registration, so there is no
|
|
device-code flow to use instead.
|
|
|
|
Restart the server; `likes` and `playlists` appear. If the token is rejected
|
|
or expires, only those two nodes are lost — search, resolve, and playback
|
|
keep working.
|
|
|
|
**The token is a live session credential.** It is redacted from `Debug` and
|
|
never logged, but `soundcloud.toml` stores it in cleartext. Keep the file
|
|
private, and revoke the session in SoundCloud's settings if it leaks.
|
|
|
|
## How it works
|
|
|
|
```text
|
|
/soundcloud
|
|
├── search create a search term with `%`
|
|
│ └── <term> matching tracks
|
|
├── resolve create an entry from a soundcloud.com URL
|
|
│ └── <url> the track or playlist it points at
|
|
├── likes your liked tracks (token only)
|
|
└── playlists your playlists (token only)
|
|
└── <playlist> its tracks
|
|
```
|
|
|
|
`search` and `resolve` are creatable: press `%` and type a term or paste a
|
|
URL. The entry becomes a child node, renamable (`e`, re-runs it) and
|
|
deletable (`d`). Entries live in memory, so a restart forgets the list;
|
|
navigating to a remembered path recreates it.
|
|
|
|
Tracks and playlists are addressed canonically by id
|
|
(`/soundcloud/track/<id>`, `/soundcloud/playlist/<id>`) whatever browse node
|
|
you reached them through, so a queued track survives deleting the search term
|
|
that found it.
|
|
|
|
**Playback is HLS.** The provider resolves a signed `.m3u8` media URL and the
|
|
player streams its MP3 segments in order as one continuous stream. That URL
|
|
is a short-lived secret and is never logged. Seeking inside an HLS track is
|
|
not supported (the stream is forward-only); everything else, captures
|
|
included, behaves normally.
|
|
|
|
## Configuration — `~/.config/crabidy/soundcloud.toml`
|
|
|
|
```toml
|
|
# Scraped and written back by the provider — you normally never touch these.
|
|
# Delete them to force a fresh scrape on the next start.
|
|
# client_id = "..."
|
|
# app_version = "..."
|
|
|
|
# Optional login: adds the `likes` and `playlists` nodes.
|
|
# oauth_token = "..."
|
|
|
|
# Optional, defaults shown.
|
|
# search_results = 50 # tracks per search term
|
|
# playlist_tracks = 500 # tracks hydrated per playlist
|
|
# call_timeout_secs = 30 # per-request timeout
|
|
# hls_deadline_secs = 300 # total deadline for fetching one HLS stream
|
|
```
|
|
|
|
## Failure behavior
|
|
|
|
- No `client_id` obtainable: `/soundcloud` is dropped with a warning, the
|
|
server runs on.
|
|
- A rotated/stale `client_id`: re-scraped on the next start.
|
|
- Rejected token: `likes`/`playlists` disappear; nothing else changes.
|
|
|
|
Build the server without the `soundcloud` cargo feature to leave this
|
|
provider out of the binary entirely.
|