Overview

Our service performs the download process passively and asynchronously, and the audio URLs are temporary.

• Passively means an audio file doesn’t exist in our storage when its URL is requested for the first time, and its download process will be activated once the service receives a GET or HEAD HTTP request of its URL. (For your convinience, the endpoint /v1/track/metadata will always activate the processes of audios that are of the highest quality in the endpoint’s response.)

• Asynchronously means the download endpoint /v1/track/metadata just generates audio URLs without waiting the audio files to be ready.

• Temporary means that an audio URL only works for a period of time after its creation. Specifically, it will be expired in 6 hours (its parameter expire indicates the expiration). After that, our service will clean the cached file and the URL’s response will always be an empty body with status 403. You MUST timely download the files instead of just saving the URLs.

To download an audio file, please follow the code examples below.

Customizable Parameters

Currently, the only customizable parameter is attachment, which affects browsers’ behavior.

This parameter is unset by default. By appending &attachment to an audio URL upon sending a GET request, the client will receive a response header Content-Disposition: attachment if the file is ready. The header tells browsers to directly download the file without opening it on a new tab when a file link is clicked.

Frontend Code Example

Open Chrome DevTools under RapidAPI. Paste, modify and execute the code below in the console for a simple test.

let audioUrl = 'https://scd.dlod.link/...' // Replace this URL with yours.
let fileName = 'audio-file-name.extension' // Replace the name and the extension with yours.

/**
 * Download an audio file in the default directory.
 * @param {string} url Audio URL.
 * @param {string} name File name with extension. If a file with the same name exists, the browser will postfix it with something like "(1)".
 */
async function download(url, name) {

  // Regularly checks the progress until it equals `1`.
  while (true) {
    let headRes = await fetch(url, { method: 'HEAD' })
    switch (headRes.status) {
      case 202: // Queuing or processing
      case 200: // Completed
        break
      case 403: // Invalid or expired
        throw new Error('The URL is invalid or expired.')
      default: // Unknown
        throw new Error(`Unknown error. Status: ${headRes.status}.`)
    }
    let isQueuing = headRes.headers.get('x-scd-is-queuing') === 'true'
    if (isQueuing) {
      console.log('Queuing...')
    } else {
      let progress = Number(headRes.headers.get('x-scd-progress'))
      console.log(`Processing: ${(progress * 100).toFixed(1)}%`)
      if (progress === 1) {
        console.log(`File size: ${headRes.headers.get('content-length')} bytes`)
        break
      }
    }
    // Waits for 1 second (1000 milliseconds).
    await new Promise(x => setTimeout(x, 1000))
  }

  // Now the URL has become a normal URL of an audio file.
  console.log('Downloading...')

  // Use `XMLHttpRequest` instead of `fetch` to query download progress.
  // We just use `fetch` here to simply demonstrate the usage.
  let getRes = await fetch(url, { method: 'GET' })

  // Response header arrives.
  switch (getRes.status) {
    case 200: // OK
      break
    case 403: // Expired
      throw new Error('The URL is expired.')
    default: // Unknown
      throw new Error(`Unknown error. Status: ${getRes.status}.`)
  }

  // Waits the file to arrive.
  let blob = await getRes.blob()
  console.log('Download completed')

  // Saves the file.
  console.log('Saving file... (click "allow" if the browser asks for download permission)')
  let el = document.createElement('a')
  el.href = URL.createObjectURL(blob)
  el.download = name
  el.click()
  URL.revokeObjectURL(el.href)

}

download(audioUrl, fileName)