{"id":15282480,"url":"https://github.com/patrickkfkan/soundcloud-fetch","last_synced_at":"2026-01-04T08:45:55.701Z","repository":{"id":129306792,"uuid":"326049186","full_name":"patrickkfkan/soundcloud-fetch","owner":"patrickkfkan","description":"Fetches SoundCloud resources through API v2.","archived":false,"fork":false,"pushed_at":"2023-09-21T15:54:30.000Z","size":534,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-05T13:50:11.742Z","etag":null,"topics":["api","scraper","soundcloud"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patrickkfkan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-01T20:15:57.000Z","updated_at":"2024-05-11T19:23:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"b2a6eaa0-c19f-42fe-9528-c4b2c276a535","html_url":"https://github.com/patrickkfkan/soundcloud-fetch","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickkfkan%2Fsoundcloud-fetch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickkfkan%2Fsoundcloud-fetch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickkfkan%2Fsoundcloud-fetch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickkfkan%2Fsoundcloud-fetch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrickkfkan","download_url":"https://codeload.github.com/patrickkfkan/soundcloud-fetch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245136354,"owners_count":20566586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","scraper","soundcloud"],"created_at":"2024-09-30T14:26:22.747Z","updated_at":"2026-01-04T08:45:55.659Z","avatar_url":"https://github.com/patrickkfkan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# soundcloud-fetch\n\nFetches SoundCloud resources through API v2.\n\nThis project was created primarily for use with the [SoundCloud plugin for Volumio](https://github.com/patrickkfkan/volumio-soundcloud). Its scope of application might therefore be limited. If you need a more general-purpose API, you might want to take a look at [soundcloud.ts](https://github.com/Tenpi/soundcloud.ts).\n\n```\nnpm i --save soundcloud-fetch\n```\n\n```\nimport SoundCloud from 'soundcloud-fetch';\n\nconst api = new SoundCloud({\n  accessToken: ...\n});\n\nconst album = await api.getPlaylistOrAlbum(...);\nconst myLikes = await api.me.getLikes({ type: 'track'});\n...\n\n```\n\n## API\n\n### Constructor\n\n\u003ccode\u003enew SoundCloud([args])\u003c/code\u003e\n\nConstructs an instance of the SoundCloud API.\n\n`args`: (*optional*)\n- `clientId`: (string) (*optional*) Client ID for making API requests. If not specified, value will be obtained from SoundCloud website.\n- `accessToken`: (string) (*optional*) Token for accessing your private resources. See [How to obtain an access token](https://github.com/patrickkfkan/soundcloud-fetch/wiki/How-to-obtain-an-access-token).\n- `locale`: (string) (*optional*) Locale code as defined in [Constants](./docs/api/modules/Constants.md).\n\n### Config\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetClientId()\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\n**Returns**\n\nThe Client ID used by the API.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003e\u003ci\u003estatic\u003c/i\u003e generateClientId()\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the Client ID from SoundCloud website. Normally, you don't have to call this method as it is automatically called during initialization of the API (unless you provided one yourself in constructor args).\n\n**Returns**\n\nClient ID from SoundCloud website.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003esetLocale([locale])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nSets the locale.\n\n**Params**\n\n- `locale`: (string) (*optional*) The locale to set. If `undefined`, the locale will be determined by SoundCloud.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003esetAccessToken([value])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nSets the access token.\n\n**Params**\n\n- `value`: (string) (*optional*) The access token to be used by the API. If `undefined`, access to your private resources will trigger an error.\n\n---\n\u003c/details\u003e\n\n### Selections\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetMixedSelections([options])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches mixed selections.\n\n**Params**\n\n`options`: (*optional*)\n- `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [Selection](./docs/api/classes/Selection.md) objects.\n\n---\n\u003c/details\u003e\n\n### Playlists / Albums / Tracks\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetPlaylistOrAlbum(id)\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches a playlist or album with the given `id`.\n\nIn SoundCloud, an album is a type of playlist with overlapping and distinct properties. To check whether an item returned by this method is a playlist or album, inspect its `type` property or use `instanceof`:\n\n```\nconst item = await api.getPlaylistOrAlbum(id);\n\nif (item \u0026\u0026 item.type === Album.type) { // \u003c-- item is an Album\n  const album = item as Album; // Type assertion\n  const genre = album.genre;   // Access Album-specific properties\n}\n\n// or\n\nif (item instanceof Album) {\n  const genre = item.genre;  // No need to do type assertion here\n}\n```\n\n**Params**\n\n- `id`: (number) The ID of the playlist or album to fetch.\n\n**Returns**\n\nPromise that resolves to an instance of [Album](./docs/api/classes/Album.md) or [Playlist](./docs/api/classes/Playlist.md), or `null` if fetched result is neither an album nor a playlist.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetSystemPlaylist(id)\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches a system playlist with the given `id`.\n\n**Params**\n\n- `id`: (string) The ID of the system playlist to fetch.\n\n**Returns**\n\nPromise that resolves to an instance of [SystemPlaylist](./docs/api/classes/SystemPlaylist.md), or `null` if fetched result is not a system playlist.\n\n---\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetPlaylistsByUser(userId, [options])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the playlists created by the user with the given `userId`. The fetched items do **not** include albums.\n\n**Params**\n\n- `userId`: (number) The ID of the user.\n- `options`: (*optional*)\n  - `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [Playlist](./docs/api/classes/Playlist.md) objects.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetAlbumsByUser(userId, [options])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the albums created by the user with the given `userId`. The fetched items do **not** include playlists.\n\n**Params**\n\n- `userId`: (number) The ID of the user.\n- `options`: (*optional*)\n  - `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [Album](./docs/api/classes/Album.md) objects.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetTopFeaturedTracks([options])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the top-featured tracks.\n\n**Params**\n\n`options` (*optional*)\n- `genre`: (string) (*optional*) The genre of tracks to fetch.\n- `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [Track](./docs/api/classes/Track.md) objects.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetTracks(ids)\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the track(s) with the given `ids`.\n\n**Params**\n\n- `ids`: (number | number[]) The IDs of the tracks to fetch. If `ids` is a number, as oppose to an array of numbers, then result will contain a single track matching it.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [Track](./docs/api/classes/Track.md) objects.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetTracksByUser(userId, [options])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the tracks uploaded by the user with the given `userId`.\n\n**Params**\n\n- `userId`: (number) The ID of the user.\n- `options`: (*optional*)\n  - `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [Track](./docs/api/classes/Track.md) objects.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetTrack(id)\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the track with the given `id`.\n\n**Params**\n\n- `ids`: (number) The ID of the track to fetch.\n\n**Returns**\n\nPromise that resolves to a [Track](./docs/api/classes/Track.md) object, or `null` if no result.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetLikesByUser(userId, options)\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the items liked by the user with the given `userId`.\n\n**Params**\n\n- `userId`: (number) The ID of the user.\n- `options`:\n  - `type`: (string) The type of resource to fetch. Can be one of the following values: `track` | `playlistAndAlbum`.\n  - `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [Like](./docs/api/classes/Like.md) objects. For each `Like`:\n- if `type` is `track`, `Like.item` points to a [Track](./docs/api/classes/Track.md) object;\n- if `type` is `playlistAndAlbum`, `Like.item` points to an [Album](./docs/api/classes/Album.md) or [Playlist](./docs/api/classes/Playlist.md) object.\n\nNote that `Like.item` can also be `null` if the item could not be parsed.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetStreamingUrl(transcodingUrl)\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the streaming URL from `transcodingUrl`.\n\nTranscoding URLs are embedded in the `mediaInfo.transcodings` property of a `Track` object. See [example](./examples/getTrackAndStreamingUrl.ts).\n\n**Params**\n\n- `transcodingUrl`: (string) The transcoding URL for a `Track`.\n\n**Returns**\n\nPromise that resolves to the streaming URL, or `null` if no result.\n\n---\n\u003c/details\u003e\n\n### Users\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetUser(id)\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the user given by `id`.\n\n**Params**\n\n- `id`: (number) The ID of the user to fetch.\n\n**Returns**\n\nPromise that resolves to a [User](./docs/api/classes/User.md) object, or `null` if no result.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egetFollowing(userId, [options])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the list of users followed by the user with the given `userId`.\n\n**Params**\n\n- `userId`: (number) The ID of the user.\n- `options`: (*optional*)\n  - `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [User](./docs/api/classes/User.md) objects.\n\n---\n\u003c/details\u003e\n\n### Search\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003esearch(q, options)\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nPerforms a search.\n\n**Params**\n\n- `q`: (string) Search query.\n- `options`:\n  - `type`: (string) The type of resource to search for. Can be one of the following values: `playlist` | `album` | `track` | `user`.\n  - `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [Playlist](./docs/api/classes/Playlist.md), [Album](./docs/api/classes/Album.md), [Track](./docs/api/classes/Track.md) or [User](./docs/api/classes/User.md) objects (depending on `type` you passed in `options`) matching the given search query.\n\n---\n\u003c/details\u003e\n\n### Private resources\n\nThese methods require a valid access token, which you can provide in the constructor or through `setAccessToken()`. Private resources methods are grouped under `me`:\n\n```\nimport SoundCloud from 'soundcloud-fetch';\n\nconst api = new SoundCloud({\n  accessToken: ...\n});\n\nconst profile = await api.me.getProfile();\n...\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eme.getProfile()\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches your user profile.\n\n**Returns**\n\nPromise that resolves to a [User](./docs/api/classes/User.md) object representing your user profile, or `null` if no result.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eme.getPlayHistory(options)\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches items from your play history.\n\n**Params**\n\n- `options`:\n  - `type`: (string) The type of resource to fetch. Can be one of the following values: `track` | `set`.\n  - `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [PlayHistoryItem](./docs/api/classes/PlayHistoryItem.md) objects. For each `PlayHistoryItem`:\n- if `type` is `track`, `PlayHistoryItem.item` points to a [Track](./docs/api/classes/Track.md) object;\n- if `type` is `set`, `PlayHistoryItem.item` points to an [Album](./docs/api/classes/Album.md), [Playlist](./docs/api/classes/Playlist.md) or [SystemPlaylist](./docs/api/classes/SystemPlaylist.md) object.\n\nNote that `PlayHistoryItem.item` can also be `null` if the item could not be parsed.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eme.getLibraryItems([options])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches items from your library.\n\n**Params**\n\n- `options`: (*optional*)\n  - `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [LibraryItem](./docs/api/classes/LibraryItem.md) objects. Each `LibraryItem` wraps around an [Album](./docs/api/classes/Album.md), [Playlist](./docs/api/classes/Playlist.md) or [SystemPlaylist](./docs/api/classes/SystemPlaylist.md) object, as well as `null` if an item could not be parsed. You can obtain the wrapped item through `LibraryItem.item`, as well as inspect the `itemType` property to get its exact type (such as whether it is liked).\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eme.getLikes(options)\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches items you have liked.\n\nThis is a convenience method that passes your User ID to `getLikesByUser(userId, options)`, and thus have the same return type and `options` param as that method.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eme.getStations([options])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the artist stations added to your library. An artist station is represented by a `SystemPlaylist`.\n\n\u003e Note that `me.getLibraryItems()` also returns artist stations. If you are presenting results from both method calls, you might want to check the type of `SystemPlaylist` through its `playlistType` property to filter out overlaps.\n\n**Params**\n\n- `options`: (*optional*)\n  - `limit`: (number) (*optional*) The number of items to return.\n\n**Returns**\n\nPromise that resolves to a [Collection](#collections) of [LibraryItem](./docs/api/classes/LibraryItem.md) objects. Use `LibraryItem.item` to obtain the `SystemPlaylist` object representing an artist station.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eme.getFollowing([options])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nFetches the users you are following.\n\nThis is a convenience method that passes your User ID to `getFollowing(userId, [options])`, and thus have the same return type and `options` param as that method.\n\n---\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eme.addToPlayHistory(trackOrUrn, [setOrUrn])\u003c/code\u003e\u003c/summary\u003e\n\u003cbr /\u003e\n\nAdds the track given by `trackOrUrn`, and optionally the album, playlist or system playlist given by `setOrUrn`, to your play history.\n\n**Params**\n\n- `trackOrUrn`: (`Track` | string) The track or URN of the track to add to play history. You can obtain the URN of a `Track` through its `apiInfo.urn` property.\n- `setOrUrn`: (`Album` | `Playlist` | `SystemPlaylist` | string) (*optional*) The album, playlist, system playlist or URN of system playlist to add to play history. You can obtain the URN of a `SystemPlaylist` through its `apiInfo.urn` property.\n\nNote that albums and playlists do not have URNs, at least not from data returned by SoundCloud. If you must pass an URN for an album or playlist, you can provide a string in the following format (this is what the API generates internally):\n\n```\n// Substitute \u003cid\u003e with playlist or album ID\nsoundcloud:playlists:\u003cid\u003e\n```\n\n---\n\u003c/details\u003e\n\n### Fetching tracks of playlists, albums and system playlists\n\nYou will note that the `Playlist`, `Album` and `SystemPlaylist` classes do not define a `tracks` property. To obtain the tracks of these items, call the `getTracks()` method:\n\n```\nconst api = new SoundCloud();\nconst playlist = api.getPlaylistOrAlbum(...);\nif (playlist) {\n  const tracks = await playlist.getTracks();\n  ...\n}\n```\n\nIn the above example, `getTracks()` returns an array of `Track` objects.\n\n### Accessing underlying data\n\nCall `getJSON()` to access the underlying data of a fetched item:\n\n```\nconst api = new SoundCloud();\nconst track = await api.getTrack(...);\nif (track) {\n  // Gets the 'track_authorization' field of underlying data\n  const trackAuthorization = track.getJSON\u003cstring\u003e('track_authorization');\n\n  // Gets the full underlying data\n  const fullData = track.getJSON();\n}\n```\n\n## Collections\n\nWhen a method returns a collection of items, it does so through an instance of the [Collection](./docs/api/classes/Collection.md) class. A `Collection` has the following key properties:\n\n- `items`: (Array) The items fetched.\n- `continuation`: ([CollectionContinuation](./docs/api/classes/CollectionContinuation.md) | `null`) An object encapsulating the data required by the API for fetching the next set of items; `null` if there are no more items available.\n\nThe `continuation` property can be used to obtain further items as follows:\n\n```\nconst api = new SoundCloud();\nconst tracks = await api.getTopFeaturedTracks();\nif (tracks.continuation) { // More items available\n  const moreTracks = await api.getContinuation(tracks.continuation);\n  ...\n}\n```\n\nIn the above example, `getContinuation()` returns another instance of `Collection` containing the next set of `Track` objects.\n\n# Changelog\n\n1.0.2:\n- Fix connection error in `getClientId()`\n\n1.0.1:\n- Apply access token in `getStreamingUrl()`\n\n1.0.0:\n- Initial release\n\n# License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrickkfkan%2Fsoundcloud-fetch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrickkfkan%2Fsoundcloud-fetch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrickkfkan%2Fsoundcloud-fetch/lists"}