Skip to main content

Playlists

getPlaylist

getPlaylist(params)

Get a playlist by id.

Example:

const { data: playlist } = await audiusSdk.playlists.getPlaylist({
playlistId: 'D7KyD',
})

console.log(playlist)

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
playlistIdstringThe ID of the playlistRequired

Returns

Returns a Promise containing an object with a data field. data contains information about the playlist as described below.

{
artwork?: {
_1000x1000?: string;
_150x150?: string;
_480x480?: string;
};
coverArtSizes?: string;
description?: string;
favoriteCount: number;
id: string;
isAlbum: boolean;
isImageAutogenerated?: boolean;
isPrivate: boolean;
permalink?: string;
playlistContents: {
metadataTimestamp: number;
timestamp: number;
trackId: string;
};
playlistName: string;
repostCount: number;
totalPlayCount: number;
user: {
albumCount: number;
artistPickTrackId?: string;
bio?: string;
coverPhoto?: {
_2000?: string;
_640?: string;
};
doesFollowCurrentUser?: boolean;
ercWallet: string;
followeeCount: number;
followerCount: number;
handle: string;
id: string;
isAvailable: boolean;
isDeactivated: boolean;
isVerified: boolean;
location?: string;
name: string;
playlistCount: number;
profilePicture?: {
_1000x1000?: string;
_150x150?: string;
_480x480?: string;
};
repostCount: number;
splWallet: string;
supporterCount: number;
supportingCount: number;
totalAudioBalance: number;
trackCount: number;
};
};

getBulkPlaylists

getBulkPlaylists(params)

Get a list of playlists by id.

Example:

const { data: playlists } = await audiusSdk.playlists.getBulkPlaylists({
id: ['D7KyD', '68yPZb'],
})

console.log(playlists)

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
idsstring[]The IDs of the playlistsRequired

Returns

Returns an array of playlists, see getPlaylist.


getPlaylistTracks

getPlaylistTracks(params)

Get the tracks in a playlist.

Example:

const { data: tracks } = await audiusSdk.playlists.getPlaylistTracks({
playlistId: 'D7KyD',
})

console.log(tracks)

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
playlistIdstringThe ID of the playlistRequired

Returns

The return type is the same as getBulkTracks


getTrendingPlaylists

getTrendingPlaylists(params)

Get the top trending playlists on Audius

Example:

const { data: playlists } = await audiusSdk.playlists.getTrendingPlaylists()

console.log(playlists)

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
timeGetTrendingPlaylistsTimeEnumThe time period for which to return trending playlists. Default value is GetTrendingPlaylistsTimeEnum.WeekOptional

Returns

Returns a Promise containing an object with a data field. data contains information about the playlists as described below.

{
artwork?: {
_1000x1000?: string;
_150x150?: string;
_480x480?: string;
};
coverArtSizes?: string;
description?: string;
favoriteCount: number;
id: string;
isAlbum: boolean;
isImageAutogenerated?: boolean;
isPrivate: boolean;
permalink?: string;
playlistContents: {
metadataTimestamp: number;
timestamp: number;
trackId: string;
};
playlistName: string;
repostCount: number;
totalPlayCount: number;
user: {
albumCount: number;
artistPickTrackId?: string;
bio?: string;
coverPhoto?: {
_2000?: string;
_640?: string;
};
doesFollowCurrentUser?: boolean;
ercWallet: string;
followeeCount: number;
followerCount: number;
handle: string;
id: string;
isAvailable: boolean;
isDeactivated: boolean;
isVerified: boolean;
location?: string;
name: string;
playlistCount: number;
profilePicture?: {
_1000x1000?: string;
_150x150?: string;
_480x480?: string;
};
repostCount: number;
splWallet: string;
supporterCount: number;
supportingCount: number;
totalAudioBalance: number;
trackCount: number;
};
}[]

searchPlaylists

searchPlaylists(params)

Search for playlists.

Example:

const { data: playlists } = await audiusSdk.playlists.searchPlaylists({
query: 'skrillex',
})
console.log(playlists)

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
querystringThe query to search forRequired

Returns

The return type is the same as getTrendingPlaylists


createPlaylist

createPlaylist(params, advancedOptions?)

Create a playlist from existing tracks

Example:

import fs from 'fs'

const coverArtBuffer = fs.readFileSync('path/to/cover-art.png')

const { playlistId } = await audiusSdk.playlists.createPlaylist({
coverArtFile: {
buffer: Buffer.from(coverArtBuffer),
name: 'coverArt',
},
metadata: {
description: 'The best tracks for Fido.',
playlistName: 'Music for Dogs',
isPrivate: true,
},
onProgress: (progress) => {
console.log('Progress: ', progress / 100)
},
trackIds: ['yyNwXq7', 'KVx2xpO', 'YJ7Wxpm'],
userId: '7eP5n',
})

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
coverArtFileFileA file that will be used as the cover art for the playlistOptional
metadatasee code block belowAn object containing the details of the playlistRequired
onProgress(progress: number) => voidA function that will be called with progress events as the image file uploadsOptional
trackIdsArray<string>An array of track IDs to be included in the playlistRequired
userIdstringThe ID of the userRequired
createPlaylist metadata payload
{
playlistName: string;
description?: string;
isPrivate?: boolean;
}

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the playlist ID (playlistId), as well as the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string;
blockNumber: number;
playlistId: string
}

uploadPlaylist

uploadPlaylist(params, advancedOptions?)

Upload the specified tracks and combine them into a new playlist.

A playlist is a living thing that can change and grow over time. Playlists can contain a user's own tracks, as well as tracks uploaded by others.

See uploadAlbum to upload an album instead of a playlist.

Example:

import { Mood, Genre } from '@audius/sdk'
import fs from 'fs'

const coverArtBuffer = fs.readFileSync('path/to/cover-art.png')
const trackBuffer1 = fs.readFileSync('path/to/track1.mp3')
const trackBuffer2 = fs.readFileSync('path/to/track2.mp3')
const trackBuffer3 = fs.readFileSync('path/to/track3.mp3')

const { playlistId } = await audiusSdk.playlists.uploadPlaylist({
userId: '7eP5n',
coverArtFile: {
buffer: Buffer.from(coverArtBuffer),
name: 'coverArt',
},
metadata: {
playlistName: 'Songs of the Forest',
description: 'A playlist full of forest energy.',
genre: Genre.ELECTRONIC,
mood: Mood.TENDER,
tags: 'nature',
},
trackMetadatas: [
{
title: 'Oak',
},
{
title: 'Sycamore',
},
{
title: 'Bush',
},
],
trackFiles: [
{
buffer: Buffer.from(trackBuffer1),
name: 'OakTrmp3',
},
{
buffer: Buffer.from(trackBuffer2),
name: 'SycamoreTrmp3',
},
{
buffer: Buffer.from(trackBuffer3),
name: 'BushTrmp3',
},
],
})

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
coverArtFileFileA file that will be used as the cover art for the playlistOptional
metadatasee code sample belowAn object containing the details of the playlistRequired
onProgress(progress: number) => voidA function that will be called with progress events as the image file uploadsOptional
trackFilesArray<File>An array of track audio filesRequired
trackMetadatasUploadTrackMetadata[]An array of track filesOptional
userIdstringThe ID of the userRequired
{
genre: Genre;
playlistName: string;
description?: string;
license?: string;
mood?: Mood;
releaseDate?: Date;
tags?: string;
upc?: string;
}

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the new playlist's ID (playlistId), as well as the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string
blockNumber: number
playlistId: string
}

addTrackToPlaylist

addTrackToPlaylist(params, advancedOptions?)

Add a single track to the end of a playlist. For more control, use updatePlaylist.

Example:


await audiusSdk.playlists.addTrackToPlaylist({
playlistId: 'x5pJ3Az'
userId: "7eP5n",
trackId: 'yyNwXq7'
});

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDefault valueRequired?
playlistIdstringN/AYes
userIdstringN/AYes
trackIdstringN/AYes

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string
blockNumber: number
playlistId: string
}

removeTrackFromPlaylist

removeTrackFromPlaylist(params, advancedOptions?)

Removes a single track at the given index of playlist. For more control, use updatePlaylist.

Example:

await audiusSdk.playlists.removeTrackFromPlaylist({
playlistId: 'x5pJ3Az'
trackIndex: 2,
userId: "7eP5n",
});

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDefault valueRequired?
playlistIdstringN/AYes
userIdstringN/AYes
trackIdstringN/AYes

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string
blockNumber: number
}

updatePlaylist

updatePlaylist(params, advancedOptions?)

Update a playlist. If cover art or any metadata fields are not provided, their values will be kept the same as before.

Example:

import fs from 'fs'

const coverArtBuffer = fs.readFileSync('path/to/updated-cover-art.png')

const { playlistId } = await audiusSdk.playlists.updatePlaylist({
playlistId: 'x5pJ3Az',
coverArtFile: {
buffer: Buffer.from(coverArtBuffer),
name: 'coverArt',
},
metadata: {
description: 'The best tracks for Fido. Updated with new cover art and tracks!!!',
playlistContents: [
{
timestamp: 1687328748, // The date/time the track was added to the playlist
trackId: 'yyNwXq7',
},
{ timestamp: Date.now(), trackId: 'lvG4Nyl' },
{ timestamp: 1687328748, trackId: 'KVx2xpO' },
{ timestamp: Date.now(), trackId: 'JZAQx5z' },
],
},
onProgress: (progress) => {
console.log('Progress: ', progress / 100)
},
userId: '7eP5n',
})

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
playlistIdstringThe ID of the playlistRequired
userIdstringThe ID of the UserRequired
coverArtFilestringA file that will be used as the cover art for the playlistOptional
metadatasee code block belowAn object containing the details of the playlistRequired
onProgress(progress: number) => voidA function that will be called with progress events as the image file uploadsOptional
updatePlaylist metadata payload
{
playlistName?: string;
description?: string;
playlistContents?: {trackId: string, time: number}[],
license?: string;
mood?: Mood;
releaseDate?: Date;
tags?: string;
upc?: string;
}

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string
blockNumber: number
}

deletePlaylist

deletePlaylist(params, advancedOptions?)

Delete a playlist

Example:

await audiusSdk.playlists.deletePlaylist({
playlistId: 'x5pJ3Az'
userId: "7eP5n",
});

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
playlistIdstringThe ID of the playlistRequired
userIdstringThe ID of the UserRequired

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string
blockNumber: number
}

favoritePlaylist

favoritePlaylist(params, advancedOptions?)

Favorites a playlist

Example:

await audiusSdk.playlists.favoritePlaylist({
playlistId: 'x5pJ3Az'
userId: "7eP5n",
});

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
playlistIdstringThe ID of the playlistRequired
userIdstringThe ID of the UserRequired
metadatasee code block belowAn object containing details about the favoriteOptional
favoritePlaylist metadata payload
{
isSaveOfRepost: boolean
}

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string
blockNumber: number
}

unfavoritePlaylist

unfavoritePlaylist(params, advancedOptions?)

Unfavorite a playlist

Example:

await audiusSdk.playlists.unfavoritePlaylist({
playlistId: 'x5pJ3Az'
userId: "7eP5n",
});

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
playlistIdstringThe ID of the playlistRequired
userIdstringThe ID of the UserRequired

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string
blockNumber: number
}

repostPlaylist

repostPlaylist(params, advancedOptions?)

Repost a playlist

Example:

await audiusSdk.playlists.repostPlaylist({
playlistId: 'x5pJ3Az'
userId: "7eP5n",
});

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
playlistIdstringThe ID of the playlistRequired
userIdstringThe ID of the UserRequired
metadatasee code block belowAn object containing details about the repostOptional
repostPlaylist metadata payload
{
isRepostOfRepost: boolean
}

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string
blockNumber: number
}

unrepostPlaylist

unrepostPlaylist(params, advancedOptions?)

Unrepost a playlist

Example:

await audiusSdk.playlists.unrepostPlaylist({
playlistId: 'x5pJ3Az'
userId: "7eP5n",
});

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
playlistIdstringThe ID of the playlistRequired
userIdstringThe ID of the UserRequired

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string
blockNumber: number
}

publishPlaylist

publishPlaylist(params, advancedOptions?)

Changes a playlist from hidden (private) to public.

Example:

await audiusSdk.playlists.publishPlaylist({
playlistId: 'x5pJ3Az'
userId: "7eP5n",
});

params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

NameTypeDescriptionRequired?
playlistIdstringThe ID of the playlistRequired
userIdstringThe ID of the UserRequired

advancedOptions

You can pass an optional advancedOptions object as the second argument.

Returns

Returns a Promise containing an object with the block hash (blockHash) and block number (blockNumber) for the transaction.

{
blockHash: string
blockNumber: number
}