SoundCloud
SoundCloud (soundcloud.com) — live track search over SoundCloud's own catalogue, reading one track URL back to its full detail (artwork, description,…
SoundCloud (soundcloud.com) — live track search over SoundCloud's own catalogue, reading one track URL back to its full detail (artwork, description, genre, release date, label), and reading a set/playlist/album URL back to its tracks IN THE CURATOR'S ORDER. Returns the artist, public track URL, duration and play count. Direct JSON API, no browser.
Domain: soundcloud.com
Also known as: SoundCloud, soundcloud, sound cloud
Prefer the capability
bowmark.music covers this provider and routes around it when it is having a bad day. Reach for this page when you need soundcloud.com specifically.
Call it directly
bowmark.providers.soundcloud.search(query: string, limit?: number): Promise<ScTrack[]>
bowmark.providers.soundcloud.getTrack(track: string | ScTrack): Promise<ScTrackDetail>
bowmark.providers.soundcloud.getPlaylist(playlist: string | ScPlaylist, limit?: number): Promise<ScPlaylist>Functions
| Function | What it does |
|---|---|
search | Searches SoundCloud's catalogue for tracks matching a free-text query and returns up to limit rows (default 20, max 200) in SoundCloud's own relevance order. |
getTrack | Reads one soundcloud.com track URL — a soundcloud.com/<account>/<track> string, or a row search returned — and returns its full metadata: title, artist, duration, plays, likes, artwork,… |
getPlaylist | Reads a SoundCloud set URL — soundcloud.com/<account>/sets/<name>, a playlist, album, EP or compilation — and returns the set plus its tracks IN THE CURATOR'S ORDER, which is the whole… |
Types
// SoundCloud's OWN row shape — not the `music` capability contract.
interface ScTrack {
id: number // SoundCloud's numeric track id
title: string // the track title as uploaded
artist: string // the uploading account's display name
url: string // public track page on soundcloud.com
durationMs: number // track length in milliseconds
playCount: number | null // plays; null when the track doesn't expose a count
}
// What getTrack adds on top: the fields a search row never carried.
interface ScTrackDetail extends ScTrack {
artworkUrl: string | null // cover image; null when uploaded without one
description: string | null // uploader's notes — a mix's tracklist lives here
genre: string | null
likeCount: number | null // null when not reported (never 0)
releaseDate: string | null // the publisher's release date, not the upload date
publisherArtist: string | null // label credit ("Aphex Twin") vs the account ("aphextwin")
labelName: string | null
}
// A set — playlist, album, EP or compilation. SoundCloud stores all four as one
// kind and tells them apart with isAlbum/setType.
interface ScPlaylist {
id: number
title: string
url: string // public set page on soundcloud.com
curator: string // the account that published the set
description: string | null
artworkUrl: string | null
genre: string | null
isAlbum: boolean // true for a release, false for an assembled playlist
setType: string | null // "album" | "ep" | "compilation" | null
trackCount: number // the SET's own count — compare against tracks.length
durationMs: number // the WHOLE set's runtime, not the sum of tracks
likeCount: number | null
createdAt: string | null
tracks: ScTrack[] // IN THE CURATOR'S ORDER
}Examples
const tracks = await bowmark.providers.soundcloud.search("aphex twin", 5);
return tracks[0] ?? null;// Search, then read the top hit's full detail — getTrack takes the row directly.
const [top] = await bowmark.providers.soundcloud.search("selected ambient works", 5);
if (!top) return null;
const detail = await bowmark.providers.soundcloud.getTrack(top);
return { title: detail.title, by: detail.publisherArtist ?? detail.artist, released: detail.releaseDate, notes: detail.description };Related
music | Music (catalogue search) — the capability this provider backs. |