Class Tracks

Track namespace — fetch, update, delete tracks and their metadata.

See

https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks

Index

Constructors

Methods

createComment delete getComments getLikes getPreviewUrl getRelated getRelatedPage getReposts getStreams getStreamUrl getTrack getTracks update updateStorefront upload

Constructors

constructor

new Tracks(getToken: TokenGetter, refreshCtx?: AutoRefreshContext): Tracks
Parameters
- getToken: TokenGetter
- OptionalrefreshCtx: AutoRefreshContext
Returns Tracks
- Defined in src/client/SoundCloudClient.ts:990

Methods

createComment

createComment(
    trackId: string | number,
    body: string,
    timestamp?: number,
    options?: TokenOption,
): Promise<SoundCloudComment>
Post a comment on a track.
Parameters
- trackId: string | number
  The track's numeric ID or URN
- body: string
  The comment text
- Optionaltimestamp: number
  Position in the track in milliseconds where the comment is placed
- Optionaloptions: TokenOption
  Optional token override
Returns Promise<SoundCloudComment>
The created comment object
Throws
When the API returns an error
Example
```
const comment = await sc.tracks.createComment(123456, 'Great track!', 30000);
console.log(comment.id);
```
See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/post_tracks__track_id__comments
- Defined in src/client/SoundCloudClient.ts:1098

delete

delete(trackId: string | number, options?: TokenOption): Promise<void>
Delete a track.
Parameters
- trackId: string | number
  The track's numeric ID or URN
- Optionaloptions: TokenOption
  Optional token override
Returns Promise<void>
Throws
When the API returns an error
Example
```
await sc.tracks.delete(123456);
```
See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/delete_tracks__track_id_
- Defined in src/client/SoundCloudClient.ts:1257

getComments

getComments(
    trackId: string | number,
    limit?: number,
    options?: TokenOption,
): Promise<SoundCloudPaginatedResponse<SoundCloudComment>>
Get comments on a track.
Parameters
- trackId: string | number
  The track's numeric ID or URN
- Optionallimit: number
  Maximum number of comments per page
- Optionaloptions: TokenOption
  Optional token override
Returns Promise<SoundCloudPaginatedResponse<SoundCloudComment>>
Paginated list of comments

Throws
When the API returns an error

See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__comments
- Defined in src/client/SoundCloudClient.ts:1075

getLikes

getLikes(
    trackId: string | number,
    limit?: number,
    options?: TokenOption,
): Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
Get users who have liked (favorited) a track.
Parameters
- trackId: string | number
  The track's numeric ID or URN
- Optionallimit: number
  Maximum number of users per page
- Optionaloptions: TokenOption
  Optional token override
Returns Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
Paginated list of users who liked the track

Throws
When the API returns an error

See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__favoriters
- Defined in src/client/SoundCloudClient.ts:1119

getPreviewUrl

getPreviewUrl(trackId: string | number, options?: TokenOption): Promise<string>
302 preview URL for a track (GET /tracks/{id}/preview).
Parameters
- trackId: string | number
- Optionaloptions: TokenOption
Returns Promise<string>
See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__preview
- Defined in src/client/SoundCloudClient.ts:1196

getRelated

getRelated(
    trackId: string | number,
    limit?: number,
    options?: TokenOption,
): Promise<SoundCloudTrack[]>
First page of related tracks as an array (unwraps official { collection, next_href }). Sends linked_partitioning=true&access=playable per official examples. Use getRelatedPage when you need next_href.
Parameters
- trackId: string | number
- Optionallimit: number
- Optionaloptions: TokenOption
Returns Promise<SoundCloudTrack[]>
- Defined in src/client/SoundCloudClient.ts:1162

getRelatedPage

getRelatedPage(
trackId: string | number,
options?: TokenOption & { access?: string; limit?: number },
): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>
Official paginated related-tracks response.
Parameters
- trackId: string | number
- Optionaloptions: TokenOption & { access?: string; limit?: number }
Returns Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>
See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__related
- Defined in src/client/SoundCloudClient.ts:1172

getReposts

getReposts(
    trackId: string | number,
    limit?: number,
    options?: TokenOption,
): Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
Get users who have reposted a track.
Parameters
- trackId: string | number
  The track's numeric ID or URN
- Optionallimit: number
  Maximum number of users per page
- Optionaloptions: TokenOption
  Optional token override
Returns Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
Paginated list of users who reposted the track

Throws
When the API returns an error

See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__reposters
- Defined in src/client/SoundCloudClient.ts:1135

getStreams

getStreams(
trackId: string | number,
options?: TokenOption,
): Promise<SoundCloudStreams>
Get stream URLs for a track.
Parameters
- trackId: string | number
  The track's numeric ID or URN
- Optionaloptions: TokenOption
  Optional token override
Returns Promise<SoundCloudStreams>
Object containing available stream URLs (HLS, MP3, preview)
Throws
When the track is not found or not streamable
Example
```
const streams = await sc.tracks.getStreams(123456);
console.log(streams.hls_mp3_128_url);
```
See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__streams
- Defined in src/client/SoundCloudClient.ts:1059

getStreamUrl

getStreamUrl(trackId: string | number, options?: TokenOption): Promise<string>
302 stream URL for a track (GET /tracks/{id}/stream).
Parameters
- trackId: string | number
- Optionaloptions: TokenOption
Returns Promise<string>
See
https://developers.soundcloud.com/docs/api/guide
- Defined in src/client/SoundCloudClient.ts:1186

getTrack

getTrack(
trackId: string | number,
options?: TokenOption,
): Promise<SoundCloudTrack>
Get a track by ID.
Parameters
- trackId: string | number
  The track's numeric ID or URN
- Optionaloptions: TokenOption
  Optional token override
Returns Promise<SoundCloudTrack>
The track object with full metadata
Throws
When the track is not found or the API returns an error
Example
```
const track = await sc.tracks.getTrack(123456);
console.log(track.title, track.duration);
```
See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id_
- Defined in src/client/SoundCloudClient.ts:1009

getTracks

getTracks(
ids: (string | number)[],
options?: TokenOption,
): Promise<SoundCloudTrack[]>
Fetch multiple tracks by their IDs in a single request.
Parameters
- ids: (string | number)[]
  Array of track IDs (numeric or string URNs)
- Optionaloptions: TokenOption
  Optional token override
Returns Promise<SoundCloudTrack[]>
Array of track objects (may be shorter than ids if some tracks are unavailable)
Throws
When the API returns an error

Throws
When more than 200 IDs are provided

Remarks
SoundCloud's API likely caps at ~200 IDs per request. Passing more than 200 IDs will throw immediately without making a network request.
Example
```
const tracks = await sc.tracks.getTracks([123456, 234567, 345678]);
tracks.forEach(t => console.log(t.title));
```
See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks
- Defined in src/client/SoundCloudClient.ts:1035

update

update(
    trackId: string | number,
    params: UpdateTrackParams,
    options?: TokenOption,
): Promise<SoundCloudTrack>
Update a track's metadata.
Parameters
- trackId: string | number
  The track's numeric ID or URN
- params: UpdateTrackParams
  Fields to update (title, description, genre, etc.)
- Optionaloptions: TokenOption
  Optional token override
Returns Promise<SoundCloudTrack>
The updated track object
Throws
When the API returns an error
Example
```
const updated = await sc.tracks.update(123456, { title: 'New Title', genre: 'Electronic' });
console.log(updated.title);
```
See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/put_tracks__track_id_
- Defined in src/client/SoundCloudClient.ts:1238

updateStorefront

updateStorefront(
    trackId: string | number,
    params: StorefrontUpdateParams,
    options?: TokenOption,
): Promise<SoundCloudStorefront>
Create or replace a track storefront. Omitted optional fields are cleared.
Parameters
- trackId: string | number
- params: StorefrontUpdateParams
- Optionaloptions: TokenOption
Returns Promise<SoundCloudStorefront>
See
https://github.com/soundcloud/api/blob/master/openapi/api.yaml
- Defined in src/client/SoundCloudClient.ts:1216

upload

upload(
params: UploadTrackParams,
options?: TokenOption,
): Promise<SoundCloudTrack>
Upload a new track (multipart). Requires a user token.
Parameters
- params: UploadTrackParams
- Optionaloptions: TokenOption
Returns Promise<SoundCloudTrack>
See
https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/post_tracks
- Defined in src/client/SoundCloudClient.ts:1206

Class Tracks

See

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns Tracks

Methods

createComment

Parameters

Returns Promise<SoundCloudComment>

Throws

Example

See

delete

Parameters

Returns Promise<void>

Throws

Example

See

getComments

Parameters

Returns Promise<SoundCloudPaginatedResponse<SoundCloudComment>>

Throws

See

getLikes

Parameters

Returns Promise<SoundCloudPaginatedResponse<SoundCloudUser>>

Throws

See

getPreviewUrl

Parameters

Returns Promise<string>

See

getRelated

Parameters

Returns Promise<SoundCloudTrack[]>

getRelatedPage

Parameters

Returns Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>

See

getReposts

Parameters

Returns Promise<SoundCloudPaginatedResponse<SoundCloudUser>>

Throws

See

getStreams

Parameters

Returns Promise<SoundCloudStreams>

Throws

Example

See

getStreamUrl

Parameters

Returns Promise<string>

See

getTrack

Parameters

Returns Promise<SoundCloudTrack>

Throws

Example

See

getTracks

Parameters

Returns Promise<SoundCloudTrack[]>

Throws

Throws

Remarks

Example

See

update

Parameters

Returns Promise<SoundCloudTrack>

Throws

Example

See

updateStorefront

Parameters