# SoundCloud — /soundcloud

<!-- toc -->

Mounts SoundCloud at `/soundcloud`: search the public catalogue, paste a
track or playlist link to resolve it, and — if you configure a token — browse
your own likes and playlists.

## Logging in (optional)

SoundCloud 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 then writes back
into `soundcloud.toml` so later starts reuse it. Nothing to do.

A login only adds two nodes — `likes` and `playlists`. To enable them, put an
OAuth token in `~/.config/crabidy/soundcloud.toml`:

```toml
oauth_token = "<your soundcloud oauth token>"
```

The token is the value 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). There is no device-code flow — SoundCloud does not offer public API
registration any more, so this is the available route.

Restart the server after adding it: `likes` and `playlists` appear at the
provider root. If the token is rejected or expires, those two nodes are the
only thing lost — search, resolve, and playback keep working.

```admonish warning
The token is a live session credential for your account. It is redacted from
logs and from every debug dump, but `soundcloud.toml` holds it in cleartext —
keep the file private, and revoke the session in SoundCloud's settings if it
leaks.
```

## The tree

```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 that URL points at
├── likes                   your liked tracks        (only with a token)
└── playlists               your playlists           (only with a token)
    └── <playlist>          its tracks
```

Both `search` and `resolve` are creatable nodes: press `%` and type a search
term or paste a URL. The entry becomes a child node you can rename (`e`,
which re-runs it) or delete (`d`). Entries live in memory, so a server
restart forgets the list — navigating back to a remembered path recreates it.
See [Search](./search.md).

Tracks and playlists are addressed canonically by id
(`/soundcloud/track/<id>`, `/soundcloud/playlist/<id>`), whichever browse
node you reached them through, so a queued track keeps working after you
delete the search term that found it.

## Playback

SoundCloud serves audio as **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 never appears in logs. Seeking
within an HLS track is not supported (the stream is forward-only); everything
else — play, pause, next, capture — behaves normally.

## Configuration — `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
```

If SoundCloud rotates its web app and the stored `client_id` stops working,
the provider re-scrapes on the next start; if it cannot obtain one at all,
`/soundcloud` is dropped with a warning and the server runs on.