3.7 KiB

Raw Blame History

SoundCloud — /soundcloud

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:

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.

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

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

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`

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

3.7 KiB Raw Blame History