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