wehub-resource-sync
77 lines
3.8 KiB
Markdown
77 lines
3.8 KiB
Markdown
# SoundCloud Integration
|
|
|
|
cliamp supports [SoundCloud](https://soundcloud.com) as an opt-in provider. Search, paste-to-play, browse a profile, and (with a browser cookie hookup) stream subscriber-gated tracks. Powered by [yt-dlp](https://github.com/yt-dlp/yt-dlp), so it requires `yt-dlp` on `PATH`.
|
|
|
|
> SoundCloud closed its OAuth program to new applications in 2014, so the bring-your-own-`client_id` pattern Spotify uses isn't available. cliamp signs you in by reusing your browser's existing SoundCloud session — see [Sign in via browser cookies](#sign-in-via-browser-cookies) below.
|
|
|
|
## Enable
|
|
|
|
SoundCloud is **off by default**. To turn it on, add to `~/.config/cliamp/config.toml`:
|
|
|
|
```toml
|
|
[soundcloud]
|
|
enabled = true
|
|
```
|
|
|
|
Once enabled:
|
|
|
|
- **Search** with `Ctrl+F` while SoundCloud is the active provider — runs `scsearch:` against SoundCloud's public index.
|
|
- **Paste a URL** (`u`) — any `soundcloud.com/<artist>/<track>` URL plays.
|
|
- **Browse list with curated genres** — when no profile is configured, the playlists pane is seeded with **Trending**, **Hip-Hop**, **Electronic**, **House**, **Lo-Fi**, **Indie**, and **Pop**. These are search-backed virtual playlists (real-time scsearch results), not editorial charts — SoundCloud's official chart endpoints all 404 through yt-dlp at present.
|
|
|
|
## Browse a profile
|
|
|
|
Set a username to expose that profile's content in the browse pane:
|
|
|
|
```toml
|
|
[soundcloud]
|
|
enabled = true
|
|
user = "yourname"
|
|
```
|
|
|
|
This replaces the curated Browse list with three playlists for `soundcloud.com/yourname`:
|
|
|
|
- **Tracks** — everything the user has uploaded
|
|
- **Likes** — tracks they've liked
|
|
- **Reposts** — tracks they've reposted
|
|
|
|
Works for any public profile. No SoundCloud sign-in required at this level.
|
|
|
|
## Sign in via browser cookies
|
|
|
|
For private likes, hidden uploads, or SoundCloud Go+ subscriber-gated tracks, point yt-dlp at your browser's cookie jar:
|
|
|
|
```toml
|
|
[soundcloud]
|
|
enabled = true
|
|
user = "yourname"
|
|
cookies_from = "firefox" # also: chrome, chromium, brave, edge, opera, safari, vivaldi
|
|
```
|
|
|
|
cliamp passes `--cookies-from-browser <name>` to every yt-dlp invocation — search, browse, and playback. As long as you're signed into SoundCloud in that browser (no need to keep it open), yt-dlp acts as logged-in-you and can access content your account is authorized for.
|
|
|
|
This is the same mechanism `[ytmusic] cookies_from` uses. If you set both, the last one to initialize wins for the playback path; in practice users have one default browser they're signed into multiple sites with, so this is fine.
|
|
|
|
## CLI
|
|
|
|
```sh
|
|
cliamp https://soundcloud.com/forss/flickermood # play a track
|
|
cliamp https://soundcloud.com/forss/sets/album # play a set / playlist
|
|
cliamp https://soundcloud.com/forss # play a profile's tracks
|
|
cliamp --provider soundcloud # start with SoundCloud as the active provider
|
|
cliamp search-sc "lofi beats" # legacy: SoundCloud search from the shell
|
|
```
|
|
|
|
URL playback works regardless of the `[soundcloud]` toggle — yt-dlp resolves any SoundCloud link cliamp hands it. The `enabled` flag gates only the in-app provider entry.
|
|
|
|
## When playback fails
|
|
|
|
Some tracks 404 on SoundCloud's per-track format API even though the page and search index still show them. Common causes: subscriber-gated content (Go+), region-blocked streams, deleted-but-cached entries, or transient yt-dlp extractor glitches. cliamp surfaces yt-dlp's exit message and shows a status notification — *"Couldn't play X — track is gated, restricted, or unavailable."* — so you know it's an upstream issue rather than a cliamp bug.
|
|
|
|
If you hit this on tracks you expect to play, set `cookies_from` (above) and confirm you're signed into SoundCloud in that browser.
|
|
|
|
## Requirements
|
|
|
|
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) on `PATH`
|
|
- Optional: a browser with an active SoundCloud session, for `cookies_from`
|