Skip to content

Commit 6cb4b6f

Browse files
rickyromborickyrombo
authored
Update TracksApi, UsersApi docs, add UploadsApi docs (#13781)
Also fixes: - UploadsApi `start` method wasn't a function - Looks like we can just pass bearerToken as part of the api config, no middleware necessary!
1 parent f1ad6ae commit 6cb4b6f

11 files changed

Lines changed: 728 additions & 594 deletions

File tree

‎.changeset/purple-experts-allow.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@audius/sdk": patch
3+
---
4+
5+
Fix UploadsApi to make start() a function

‎docs/docs/developers/sdk/advanced-options.mdx‎

Lines changed: 0 additions & 43 deletions
This file was deleted.

‎docs/docs/developers/sdk/tracks.mdx‎

Lines changed: 379 additions & 126 deletions
Large diffs are not rendered by default.

‎docs/docs/developers/sdk/uploads.mdx‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
---
2+
id: uploads
3+
title: Uploads
4+
pagination_label: Uploads
5+
sidebar_label: Uploads
6+
description: Audius Protocol Documentation
7+
---
8+
9+
import Tabs from '@theme/Tabs'
10+
import TabItem from '@theme/TabItem'
11+
12+
---
13+
14+
The Uploads API provides methods for uploading audio and image files to Audius storage nodes. These
15+
methods return CIDs (Content Identifiers) that you then pass to write methods like
16+
[`createTrack`](/developers/sdk/tracks#createtrack) or
17+
[`updateTrack`](/developers/sdk/tracks#updatetrack).
18+
19+
:::tip
20+
21+
File uploads are a separate step from track/playlist creation. You first upload your files using the
22+
Uploads API to get CIDs, then pass those CIDs as metadata when creating or updating content.
23+
24+
:::
25+
26+
---
27+
28+
## createAudioUpload
29+
30+
> #### createAudioUpload(`params`)
31+
32+
Upload an audio file to a storage node. Returns the resulting CIDs and audio analysis metadata
33+
(duration, BPM, musical key).
34+
35+
<Tabs
36+
block={true}
37+
defaultValue="request"
38+
values={[
39+
{ label: 'Params', value: 'request' },
40+
{ label: 'Example', value: 'example' },
41+
{ label: 'Response', value: 'response' },
42+
]}
43+
>
44+
<TabItem value="request">
45+
46+
Create an object with the following fields and pass it as the first argument.
47+
48+
| Name | Type | Description | Required? |
49+
| :-------------------- | :---------------------------------------- | :--------------------------------------------------- | :----------- |
50+
| `file` | `File` | The audio file to upload | **Required** |
51+
| `onProgress` | `(loaded: number, total: number) => void` | A callback for tracking upload progress | _Optional_ |
52+
| `previewStartSeconds` | `number` | Start time in seconds for generating a preview clip | _Optional_ |
53+
| `placementHosts` | `string[]` | A list of storage node hosts to prefer for placement | _Optional_ |
54+
55+
</TabItem>
56+
<TabItem value="example">
57+
58+
```ts
59+
import fs from 'fs'
60+
61+
const trackBuffer = fs.readFileSync('path/to/track.mp3')
62+
63+
const upload = audiusSdk.uploads.createAudioUpload({
64+
file: {
65+
buffer: Buffer.from(trackBuffer),
66+
name: 'track.mp3',
67+
type: 'audio/mpeg',
68+
},
69+
onProgress: (loaded, total) => {
70+
console.log(`Upload progress: ${Math.round((loaded / total) * 100)}%`)
71+
},
72+
previewStartSeconds: 30,
73+
})
74+
75+
const result = await upload.start()
76+
console.log(result)
77+
```
78+
79+
</TabItem>
80+
<TabItem value="response">
81+
82+
The method returns an object with:
83+
84+
- `abort` — a function you can call to cancel the upload.
85+
- `start()` — a function that begins the upload and returns a `Promise` that resolves with the
86+
upload result once complete.
87+
88+
The resolved value of `start()` contains:
89+
90+
```ts
91+
{
92+
trackCid: string // CID of the transcoded 320kbps audio
93+
previewCid?: string // CID of the preview clip (if previewStartSeconds was provided)
94+
origFileCid: string // CID of the original uploaded file
95+
origFilename: string // Original filename
96+
duration: number // Duration in seconds
97+
bpm?: number // Detected BPM (beats per minute)
98+
musicalKey?: string // Detected musical key
99+
}
100+
```
101+
102+
</TabItem>
103+
</Tabs>
104+
105+
---
106+
107+
## createImageUpload
108+
109+
> #### createImageUpload(`params`)
110+
111+
Upload an image file (e.g. cover art or profile picture) to a storage node. Returns the resulting
112+
CID.
113+
114+
<Tabs
115+
block={true}
116+
defaultValue="request"
117+
values={[
118+
{ label: 'Params', value: 'request' },
119+
{ label: 'Example', value: 'example' },
120+
{ label: 'Response', value: 'response' },
121+
]}
122+
>
123+
<TabItem value="request">
124+
125+
Create an object with the following fields and pass it as the first argument.
126+
127+
| Name | Type | Description | Required? |
128+
| :--------------- | :---------------------------------------- | :---------------------------------------------------------------------------- | :----------- |
129+
| `file` | `File` | The image file to upload | **Required** |
130+
| `onProgress` | `(loaded: number, total: number) => void` | A callback for tracking upload progress | _Optional_ |
131+
| `isBackdrop` | `boolean` | Set to `true` for wide/banner images (e.g. profile banners). Default: `false` | _Optional_ |
132+
| `placementHosts` | `string[]` | A list of storage node hosts to prefer for placement | _Optional_ |
133+
134+
</TabItem>
135+
<TabItem value="example">
136+
137+
```ts
138+
import fs from 'fs'
139+
140+
const coverArtBuffer = fs.readFileSync('path/to/cover-art.png')
141+
142+
const upload = audiusSdk.uploads.createImageUpload({
143+
file: {
144+
buffer: Buffer.from(coverArtBuffer),
145+
name: 'cover-art.png',
146+
type: 'image/png',
147+
},
148+
})
149+
150+
const coverArtCid = await upload.start()
151+
console.log(coverArtCid) // CID string
152+
```
153+
154+
</TabItem>
155+
<TabItem value="response">
156+
157+
The method returns an object with:
158+
159+
- `abort` — a function you can call to cancel the upload.
160+
- `start()` — a function that begins the upload and returns a `Promise` resolving with the CID of
161+
the uploaded image (`string`).
162+
163+
</TabItem>
164+
</Tabs>
165+
166+
---
167+
168+
## Full Example: Upload and Create a Track
169+
170+
This example demonstrates the full workflow of uploading files via the Uploads API and then creating
171+
a track with the returned CIDs.
172+
173+
```ts
174+
import { Mood, Genre } from '@audius/sdk'
175+
import fs from 'fs'
176+
177+
// Step 1: Upload the audio file
178+
const trackBuffer = fs.readFileSync('path/to/track.mp3')
179+
const audioUpload = audiusSdk.uploads.createAudioUpload({
180+
file: {
181+
buffer: Buffer.from(trackBuffer),
182+
name: 'track.mp3',
183+
type: 'audio/mpeg',
184+
},
185+
previewStartSeconds: 30,
186+
})
187+
const audioResult = await audioUpload.start()
188+
189+
// Step 2: Upload cover art
190+
const coverArtBuffer = fs.readFileSync('path/to/cover-art.png')
191+
const imageUpload = audiusSdk.uploads.createImageUpload({
192+
file: {
193+
buffer: Buffer.from(coverArtBuffer),
194+
name: 'cover-art.png',
195+
type: 'image/png',
196+
},
197+
})
198+
const coverArtCid = await imageUpload.start()
199+
200+
// Step 3: Create the track using the CIDs from the uploads.
201+
// The audio upload result fields (trackCid, previewCid, origFileCid, etc.)
202+
// match the metadata field names, so you can spread them directly.
203+
const { data } = await audiusSdk.tracks.createTrack({
204+
userId: '7eP5n',
205+
metadata: {
206+
title: 'Monstera',
207+
description: 'Dedicated to my favorite plant',
208+
genre: Genre.METAL,
209+
mood: Mood.AGGRESSIVE,
210+
...audioResult,
211+
coverArtCid: coverArtCid,
212+
},
213+
})
214+
```

0 commit comments

Comments
 (0)