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;
  };
};

---

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.

Name	Type	Description	Required?
ids	string[]	The IDs of the playlists	Required

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.

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	see code block below	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

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.

Name	Type	Description	Required?
coverArtFile	File	A file that will be used as the cover art for the playlist	Optional
metadata	see code sample below	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

{
  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.

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	see code block below	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

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.

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	see code block below	An object containing details about the favorite	Optional

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.

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	see code block below	An object containing details about the repost	Optional

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.

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
}

---