Skip to content

Latest commit

 

History

History

libs

README.md

Getting Started with the Audius SDK

Overview

The Audius JavaScript (TypeScript) SDK allows you to easily interact with the Audius protocol. Use the SDK to:

  • 🔍 Search and display users, tracks, and playlists
  • 🎵 Stream and upload tracks
  • ❤️ Favorite, repost, and curate playlists
  • ✍️ Allow your users to log in with their Audius account and act on their behalf

...and much more!

Set Up Your Developer App

  1. Create an Audius account if you do not have one already.

  2. Head to the Settings page and select "Manage Your Apps." Follow the prompts to create a new developer app and get your Audius API Key and API Secret.

:::tip

Make sure you save your API Secret somewhere safe — treat it like a password.

:::

Install the SDK

Node.js

If your project is in a Node.js environment, run this in your terminal:

npm install web3 @audius/sdk

@audius/sdk on NPM

HTML + JS

Otherwise, include the SDK script tag in your web page. The Audius SDK will then be assigned to window.audiusSdk.

<script src="https://cdn.jsdelivr.net/npm/web3@latest/dist/web3.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@audius/sdk@latest/dist/sdk.min.js"></script>

Initialize the SDK

Initialize the SDK with your API key.

If you plan to write data to Audius (e.g. upload a track, favorite a playlist, etc.), then pass in your API secret as well.

Node.js example

import { sdk } from '@audius/sdk'

const audiusSdk = sdk({
  apiKey: 'Your API Key goes here',
  apiSecret: 'Your API Secret goes here'
})

HTML + JS example

const audiusSdk = window.audiusSdk({ apiKey: 'Your API key goes here' })

:::warning

Do NOT include your API secret if you are running the SDK on the frontend, as this will expose your secret.

:::

Make your first API call using the SDK

Once you have the initialized SDK instance, it's smooth sailing to making your first API calls.

:::note

If you included your API secret in the previous step, you'll be able do both reads (e.g. fetching a playlist) and writes (e.g. reposting a playlist) to Audius. Otherwise, you'll be able to read data only.

:::

// Fetch your first track!
const track = await audiusSdk.tracks.getTrack({ trackId: 'D7KyD' })
console.log(track, 'Track fetched!')

// If you initialized the SDK with your API secret, you can write data as well.
// For example, to favorite the track above:
const userId = (
  await audiusSdk.users.getUserByHandle({
    handle: 'Your Audius handle goes here'
  })
).data?.id
const track = await audiusSdk.tracks.favoriteTrack({
  trackId: 'D7KyD',
  userId
})

Full Node.js example

import { sdk } from '@audius/sdk'

const audiusSdk = sdk({
  apiKey: 'Your API Key goes here',
  apiSecret: 'Your API Secret goes here'
})

const track = await audiusSdk.tracks.getTrack({ trackId: 'D7KyD' })
console.log(track, 'Track fetched!')

const userId = (
  await audiusSdk.users.getUserByHandle({
    handle: 'Your Audius handle goes here'
  })
).data?.id

const track = await audiusSdk.tracks.favoriteTrack({
  trackId: 'D7KyD',
  userId
})
console.log('Track favorited!')

:::note

Writing data (such as uploading or favoriting a track) is only possible if you provide an apiSecret

:::

:::note

If you are using the sdk in a browser environment you will need to do:

import Web3 from 'web3'
window.Web3 = Web3

:::

:::note

If your bundler doesn't automatically polyfill node libraries (like when using create-react-app v5) you will need to use the web3 script tag instead of the web3 npm package.

:::

Full HTML + JS example

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/web3@latest/dist/web3.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/@audius/sdk@latest/dist/sdk.min.js"></script>
    <script>
      const fn = async () => {
        const audiusSdk = window.audiusSdk({
          apiKey: 'Your API Key goes here'
        })
        const track = await audiusSdk.tracks.getTrack({ trackId: 'D7KyD' })
        console.log(track, 'Track fetched!')
      }

      fn()
    </script>
  </head>
  <body>
    <h1>Example content</h1>
  </body>
</html>

What's next?