Skip to main content

Uploading Audio Snippets

This guide walks you through uploading audio preview snippets and associating them with release items. This process requires three sequential API calls: getting a signed URL, uploading the audio file, and registering the snippet.

Prerequisites​

  • A release item with a tracklist already created
  • The item's _id (itemRef)
  • Audio file in MP3 format (max 5MB)

Overview​

The process involves:

  1. Get Signed URL: Request a signed URL for uploading your audio snippet
  2. Upload Audio File: Upload the audio file to the signed URL (direct to S3/storage)
  3. Register Snippet: Register the uploaded snippet with the release item

Step-by-Step Instructions​

Step 1: Request Signed URL​

Request a signed URL for uploading your audio snippet from the Admin API. You'll need the item's _id (itemRef) and the track position.

GraphQL Mutation:

mutation ItemAudioUpload($itemRef: ID!, $signedUrlInput: SignedUrlInput) {
  itemAudioUpload(itemRef: $itemRef, signedUrlInput: $signedUrlInput) {
    signedUrl
    key
  }
}

Variables:

{
  "itemRef": "507f1f77bcf86cd799439011",
  "signedUrlInput": {
    "position": "A1"
  }
}

Response:

{
  "data": {
    "itemAudioUpload": {
      "signedUrl": "https://creators-audio-snippets-xxx.s3.amazonaws.com/path/to/file.mp3?X-Amz-Algorithm=...",
      "key": "custom/1768154279/A1.mp3"
    }
  }
}

Step 2: Upload Audio File to S3​

Upload your audio file directly to the signed URL from the previous step using a PUT request. The file must be MP3 format and under 5MB.

Request Parameters:

  • Method: PUT
  • URL: [signedUrl from Step 1]
  • Headers:
    • Content-Type: audio/mpeg
    • Cache-Control: max-age=31536000
    • x-amz-acl: public-read
  • Body: Binary audio file data

Success Response:

HTTP 200 OK

Status code 200 indicates a successful upload. Ensure you follow the request format and set the x-amz-acl value to public-read.

Step 3: Register the Uploaded Snippet​

After successfully uploading the file, register the snippet with the release item using the key from Step 1, the same itemRef, and the track position.

GraphQL Mutation:

mutation ItemAudioUpload($itemRef: ID!, $registerAudioInput: RegisterAudioInput) {
  itemAudioUpload(itemRef: $itemRef, registerAudioInput: $registerAudioInput) {
    uri
  }
}

Variables:

{
  "itemRef": "507f1f77bcf86cd799439011",
  "registerAudioInput": {
    "key": "custom/1768154279/A1.mp3",
    "position": "A1"
  }
}

Response:

{
  "data": {
    "itemAudioUpload": {
      "uri": "https://creators-audio-snippets...custom/1768154279/A1.mp3?version=1"
    }
  }
}

Error Handling​

Common Errors​

"Item not found" or "Release not found"

  • Ensure the release item exists and is saved
  • Verify you're using the correct item _id (itemRef)
  • Check that you have permission to access the item

"Track position must be filled"

  • Ensure the track position matches a track in the release's tracklist
  • Position format should match your tracklist (e.g., "A1", "1", "01")

"File rejected - Format allowed mp3 - File size max 5MB"

  • Ensure the file is in MP3 format
  • Check file size is under 5MB
  • Verify Content-Type header is audio/mpeg

Upload fails (403/404 on PUT request)

  • Signed URLs expire after a short time - get a new one if expired
  • Ensure you're using the exact signed URL from Step 1
  • Check that all required headers are included, especially x-amz-acl: public-read

"Invalid url response" or "Invalid key"

  • Ensure you're using the key from Step 1 in Step 3
  • Verify the key matches the uploaded file location
  • Use the same itemRef in both Step 1 and Step 3

Important Notes​

The track position must match exactly with a track in your release's tracklist (common formats: "A1", "B1", "1", "01"). Only MP3 files are supported with a maximum size of 5MB. Use the same itemRef in both Step 1 and Step 3. Use the key returned from Step 1 in Step 3's registerAudioInput. You can upload multiple snippets for different tracks by repeating this process with different positions.

Uploading Image Files for Items​

The same three-step process applies to uploading image files for items, with the following differences:

  • Use the itemImageSignedUrl mutation to get a signed URL
  • Use the itemImageRegister mutation to register the uploaded image

Next Steps​