crabidy/soundclouddy/README.md

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:

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

/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

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