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!
-
Create an Audius account if you do not have one already.
-
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.
:::
If your project is in a Node.js environment, run this in your terminal:
npm install web3 @audius/sdkOtherwise, 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 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.
import { sdk } from '@audius/sdk'
const audiusSdk = sdk({
apiKey: 'Your API Key goes here',
apiSecret: 'Your API Secret goes here'
})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.
:::
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
})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.
:::
<!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>-
Get authorization to access your app's users' Audius accounts
-
Explore the API docs to see what else you can do with the Audius SDK