Skip to content

Uploads

The Uploads API provides methods for uploading audio and image files to Audius storage nodes. These methods return CIDs (Content Identifiers) that you then pass to write methods like createTrack or updateTrack.

createAudioUpload(params)

Upload an audio file to a storage node. Returns the resulting CIDs and audio analysis metadata (duration, BPM, musical key).

Example:

import fs from 'fs'
 
const trackBuffer = fs.readFileSync('path/to/track.mp3')
 
const upload = audiusSdk.uploads.createAudioUpload({
  file: {
    buffer: Buffer.from(trackBuffer),
    name: 'track.mp3',
    type: 'audio/mpeg',
  },
  onProgress: ({ loaded, total }) => {
    console.log(`Upload progress: ${Math.round((loaded / total) * 100)}%`)
  },
  previewStartSeconds: 30,
})
 
const result = await upload.start()
console.log(result)

Params

Create an object with the following fields and pass it as the first argument.

NameTypeDescriptionRequired?
fileFileThe audio file to uploadRequired
onProgress(event: { loaded: number; total: number; transcode: number }) => voidA callback for tracking upload progressOptional
previewStartSecondsnumberStart time in seconds for generating a preview clipOptional
placementHostsstring[]A list of storage node hosts to prefer for placementOptional

Returns

Returns an object with:

  • abort — a function you can call to cancel the upload.
  • start() — a function that begins the upload and returns a Promise that resolves with:
{
  trackCid: string         // CID of the transcoded 320kbps audio
  previewCid?: string      // CID of the preview clip (if previewStartSeconds was provided)
  origFileCid: string      // CID of the original uploaded file
  origFilename: string     // Original filename
  duration: number         // Duration in seconds
  bpm?: number             // Detected BPM (beats per minute)
  musicalKey?: string      // Detected musical key
}

createImageUpload(params)

Upload an image file (e.g. cover art or profile picture) to a storage node. Returns the resulting CID.

Example:

import fs from 'fs'
 
const coverArtBuffer = fs.readFileSync('path/to/cover-art.png')
 
const upload = audiusSdk.uploads.createImageUpload({
  file: {
    buffer: Buffer.from(coverArtBuffer),
    name: 'cover-art.png',
    type: 'image/png',
  },
})
 
const coverArtCid = await upload.start()
console.log(coverArtCid) // CID string

Params

Create an object with the following fields and pass it as the first argument.

NameTypeDescriptionRequired?
fileFileThe image file to uploadRequired
onProgress(event: { loaded: number; total: number; transcode: number }) => voidA callback for tracking upload progressOptional
isBackdropbooleanSet to true for wide/banner images (e.g. profile banners). Default: falseOptional
placementHostsstring[]A list of storage node hosts to prefer for placementOptional

Returns

Returns an object with:

  • abort — a function you can call to cancel the upload.
  • start() — a function that begins the upload and returns a Promise resolving with the CID of the uploaded image (string).

Full Example: Upload and Create a Track

This example demonstrates the full workflow of uploading files via the Uploads API and then creating a track with the returned CIDs.

import fs from 'fs'
 
// Step 1: Upload the audio file
const trackBuffer = fs.readFileSync('path/to/track.mp3')
const audioUpload = audiusSdk.uploads.createAudioUpload({
  file: {
    buffer: Buffer.from(trackBuffer),
    name: 'track.mp3',
    type: 'audio/mpeg',
  },
  previewStartSeconds: 30,
})
const audioResult = await audioUpload.start()
 
// Step 2: Upload cover art
const coverArtBuffer = fs.readFileSync('path/to/cover-art.png')
const imageUpload = audiusSdk.uploads.createImageUpload({
  file: {
    buffer: Buffer.from(coverArtBuffer),
    name: 'cover-art.png',
    type: 'image/png',
  },
})
const coverArtCid = await imageUpload.start()
 
// Step 3: Create the track using the CIDs from the uploads.
// The audio upload result fields (trackCid, previewCid, origFileCid, etc.)
// match the metadata field names, so you can spread them directly.
const { data } = await audiusSdk.tracks.createTrack({
  userId: '7eP5n',
  metadata: {
    title: 'Monstera',
    description: 'Dedicated to my favorite plant',
    genre: 'Metal',
    mood: 'Aggressive',
    ...audioResult,
    coverArtSizes: coverArtCid,
  },
})