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.
Name | Type | Description | Required? |
---|---|---|---|
playlistId | string | The ID of the playlist | Required |
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;
};
};
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.
Name | Type | Description | Required? |
---|---|---|---|
playlistId | string | The ID of the playlist | Required |
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.
Name | Type | Description | Required? |
---|---|---|---|
time | GetTrendingPlaylistsTimeEnum | The time period for which to return trending playlists. Default value is GetTrendingPlaylistsTimeEnum.Week | Optional |
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.
Name | Type | Description | Required? |
---|---|---|---|
query | string | The query to search for | Required |
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.
Name | Type | Description | Required? |
---|---|---|---|
coverArtFile | File | A file that will be used as the cover art for the playlist | Optional |
metadata |
| An object containing the details of the playlist | Required |
onProgress | (progress: number) => void | A function that will be called with progress events as the image file uploads | Optional |
trackIds | Array<string> | An array of track IDs to be included in the playlist | Required |
userId | string | The ID of the user | Required |
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.
Name | Type | Description | Required? |
---|---|---|---|
coverArtFile | File | A file that will be used as the cover art for the playlist | Optional |
metadata |
| An object containing the details of the playlist | Required |
onProgress | (progress: number) => void | A function that will be called with progress events as the image file uploads | Optional |
trackFiles | Array<File> | An array of track audio files | Required |
trackMetadatas | UploadTrackMetadata [] | An array of track files | Optional |
userId | string | The ID of the user | Required |
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.
Name | Type | Default value | Required? |
---|---|---|---|
playlistId | string | N/A | Yes |
userId | string | N/A | Yes |
trackId | string | N/A | Yes |
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.
Name | Type | Default value | Required? |
---|---|---|---|
playlistId | string | N/A | Yes |
userId | string | N/A | Yes |
trackId | string | N/A | Yes |
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.
Name | Type | Description | Required? |
---|---|---|---|
playlistId | string | The ID of the playlist | Required |
userId | string | The ID of the User | Required |
coverArtFile | string | A file that will be used as the cover art for the playlist | Optional |
metadata |
| An object containing the details of the playlist | Required |
onProgress | (progress: number) => void | A function that will be called with progress events as the image file uploads | Optional |
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.
Name | Type | Description | Required? |
---|---|---|---|
playlistId | string | The ID of the playlist | Required |
userId | string | The ID of the User | Required |
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.
Name | Type | Description | Required? |
---|---|---|---|
playlistId | string | The ID of the playlist | Required |
userId | string | The ID of the User | Required |
metadata |
| An object containing details about the favorite | Optional |
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.
Name | Type | Description | Required? |
---|---|---|---|
playlistId | string | The ID of the playlist | Required |
userId | string | The ID of the User | Required |
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.
Name | Type | Description | Required? |
---|---|---|---|
playlistId | string | The ID of the playlist | Required |
userId | string | The ID of the User | Required |
metadata |
| An object containing details about the repost | Optional |
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.
Name | Type | Description | Required? |
---|---|---|---|
playlistId | string | The ID of the playlist | Required |
userId | string | The ID of the User | Required |
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.
Name | Type | Description | Required? |
---|---|---|---|
playlistId | string | The ID of the playlist | Required |
userId | string | The ID of the User | Required |
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;
}