ab3bd7c63a
The docs drifted behind three changes: the /queues + /bookmarks + /captures split folding into one /crabidy provider, three providers arriving (soundcloud, jamendo, abs) with nothing written about them, and the spectrum toggle moving off v to f when library visual mode took v/V. - The book gains a page per undocumented provider — /soundcloud, /jamendo, /abs — each with its tree, its playback path, every config option, and how to log in. The providers index and intro list all nine roots in the order the server actually serves them. - Every provider now documents its login: Tidal's device flow (and that a broken tidaly.toml is the one fatal provider config), audiobookshelf API keys, the optional SoundCloud token and where to read it out of a browser, YouTube cookie exports, Jamendo's shipped key, and "nothing to do" for fyyd and /fs. - fsdy's README described three server-managed mounts under ~/.config/crabidy that have not existed for a while; it now describes /crabidy over the state dir plus the shared content store, and how deletes there never touch store audio. - Stale /captures/<name> save paths in the tidaldy and ytdy READMEs are /crabidy/<name>. The TUI key table, the README walkthrough, and the spectrum section use f, and visual mode (v/V) is documented. - config.md and the README list all seven provider config files, say plainly that credentials are stored in cleartext, and cover the audio output device; the CLI page documents audio-devices and features. - No README or docs page references architecture/, quality/, or plan/ any more: the book describes the system as it is, and points at the crate READMEs for usage and config. - devenv-docs.nix was never committed even though devenv.nix imports it, so a fresh clone could not enter the shell at all. It is in now, which also makes the README's `devenv shell -- docs` work. Also fixes two ./store.md links in providers/fs.md that pointed one directory too shallow. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| src | ||
| tests | ||
| Cargo.toml | ||
| README.md | ||
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_idobtainable:/soundcloudis dropped with a warning, the server runs on. - A rotated/stale
client_id: re-scraped on the next start. - Rejected token:
likes/playlistsdisappear; nothing else changes.
Build the server without the soundcloud cargo feature to leave this
provider out of the binary entirely.