Audio Processing API

Scalable audio REST API to convert, trim, concatenate, optimize, and compress audio files.

Usage

1 Upload your input

To process audio, your input file (audio/video file) must be uploaded to your account or accessible via a URL.

2 Build your audio URL

Build the audio transformation you need by adding querystring params to the URL.

3 Play your audio

To play your audio, simply navigate to the URL you created in step 2.

1 Upload your input

To process audio, the input file must be uploaded to your account, or accessible via a URL:

Use the Bytescale Dashboard to upload a file manually.

Use the Upload Widget, Bytescale SDKs or Bytescale API to upload a file programmatically.

Create external HTTP folders to process files hosted externally.

Get the input file's /raw/ URL before continuing.

2 Build your audio URL

To build an audio processing URL:

Get the /raw/ URL for your input file.

Replace /raw/ with /audio/.

Add the querystring parameters documented on this page, e.g.:

https://upcdn.io

Account

/W142hJk/

API

audio

File Path

/example.mp3

Parameters

?br=96

3 Play your audio

Play your audio by navigating to the URL from step 2.

By default, your audio will be encoded to AAC.

The HTTP response will be an HTML webpage with an embedded audio player that's hardcoded to play your audio.

You can change this behaviour — e.g. to return an audio file instead of an audio player — using the parameters documented on this page.

Examples

Embed Code

Read the docs

MP3 Output

Read the docs

AAC Output

Read the docs

WAV Output

Read the docs

HLS Output

Read the docs

HLS-RT Output

Read the docs

Metadata

Read the docs

Example #1: Embedding an audio file

To embed audio in a webpage using Video.js:

<!DOCTYPE html>
<html>
<head>
  <link href="https://unpkg.com/video.js@7/dist/video-js.min.css" rel="stylesheet">
  <script src="https://unpkg.com/video.js@7/dist/video.min.js"></script>
  <style type="text/css">
    .audio-container {
      height: 316px;
      max-width: 600px;
    }
  </style>
</head>
<body>
  <div class="audio-container">
    <video-js
      class="vjs-fill vjs-big-play-centered"
      controls
      preload="auto">
      <p class="vjs-no-js">To play this audio please enable JavaScript.</p>
    </video-js>
  </div>
  <script>
    var vid = document.querySelector('video-js');
    var player = videojs(vid, {responsive: true});
    player.on('loadedmetadata', function() {
      // Begin playing from the start of the audio. (Required for 'f=hls-aac-rt'.)
      player.currentTime(player.seekable().start(0));
    });
    player.src({
      src: 'https://upcdn.io/W142hJk/audio/example.mp3!f=hls-aac-rt&br=80&br=256',
      type: 'application/x-mpegURL'
    });
  </script>
</body>
</html>

Audio encoded using f=hls-aac-rt takes ~10 seconds to play initially and ~100ms on all subsequent requests.

Example #3: Creating MP3 audio

To create an MP3 file:

Upload an input file (e.g. an audio or video file) or create an external file source.

Replace /raw/ with /audio/ in the file's URL, and then append ?f=mp3 to the URL.

Navigate to the URL (i.e. request the URL using a simple GET request).

Wait for status: "Succeeded" in the JSON response.

The result will contain a URL to the MP3 file:

https://upcdn.io/W142hJk/audio/example.mp3?f=mp3

{
  "jobUrl": "https://api.bytescale.com/v2/accounts/W142hJk/jobs/ProcessFileJob/01H3211XMV1VH829RV697VE3WM",
  "jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
  "jobId": "01H3211XMV1VH829RV697VE3WM",
  "jobType": "ProcessFileJob",
  "accountId": "W142hJk",
  "created": 1686916626075,
  "lastUpdated": 1686916669389,
  "status": "Succeeded",
  "summary": {
    "result": {
      "type": "Artifact",
      "artifact": "/audio.mp3",
      "artifactUrl": "https://upcdn.io/W142hJk/audio/example.mp3!f=mp3&a=/audio.mp3"
    }
  }
}

Example #4: Creating AAC audio

To create an AAC file:

Upload an input file (e.g. an audio or video file) or create an external file source.

Replace /raw/ with /audio/ in the file's URL, and then append ?f=aac to the URL.

Navigate to the URL (i.e. request the URL using a simple GET request).

Wait for status: "Succeeded" in the JSON response.

The result will contain a URL to the AAC file:

https://upcdn.io/W142hJk/audio/example.mp3?f=aac

{
  "jobUrl": "https://api.bytescale.com/v2/accounts/W142hJk/jobs/ProcessFileJob/01H3211XMV1VH829RV697VE3WM",
  "jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
  "jobId": "01H3211XMV1VH829RV697VE3WM",
  "jobType": "ProcessFileJob",
  "accountId": "W142hJk",
  "created": 1686916626075,
  "lastUpdated": 1686916669389,
  "status": "Succeeded",
  "summary": {
    "result": {
      "type": "Artifact",
      "artifact": "/audio.aac",
      "artifactUrl": "https://upcdn.io/W142hJk/audio/example.mp3!f=aac&a=/audio.aac"
    }
  }
}

Example #2: Creating WAV audio

To create a WAV file:

Upload an input file (e.g. an audio or video file) or create an external file source.

Replace /raw/ with /audio/ in the file's URL, and then append ?f=wav-riff to the URL.

Navigate to the URL (i.e. request the URL using a simple GET request).

Wait for status: "Succeeded" in the JSON response.

The result will contain a URL to the WAV file:

https://upcdn.io/W142hJk/audio/example.mp3?f=wav-riff

{
  "jobUrl": "https://api.bytescale.com/v2/accounts/W142hJk/jobs/ProcessFileJob/01H3211XMV1VH829RV697VE3WM",
  "jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
  "jobId": "01H3211XMV1VH829RV697VE3WM",
  "jobType": "ProcessFileJob",
  "accountId": "W142hJk",
  "created": 1686916626075,
  "lastUpdated": 1686916669389,
  "status": "Succeeded",
  "summary": {
    "result": {
      "type": "Artifact",
      "artifact": "/audio.wav",
      "artifactUrl": "https://upcdn.io/W142hJk/audio/example.mp3!f=wav-riff&a=/audio.wav"
    }
  }
}

Example #5: Creating HLS audio with multiple bitrates

To create an HTTP Live Streaming (HLS) file:

Upload an input file (e.g. an audio or video file) or create an external file source.

Replace /raw/ with /audio/ in the file's URL, and then append ?f=hls-aac to the URL.

Add parameters from the Audio Transcoding API or Audio Compression API

You can create adaptive bitrate (ABR) audio by specifying multiple groups of bitrate and/or sample rate parameters. The end-user's audio player will automatically switch to the most appropriate variant during playback. By default, a single 96 kbps variant is produced.

You can specify up to 10 variants. Each variant's parameters must be adjacent on the querystring. For example: br=80&sr=24&br=256&sr=48 specifies 2 variants, whereas br=80&br=256&sr=24&sr=48 specifies 3 variants (which would most likely be a mistake). You can add next=true between groups of parameters to forcefully split them into separate variants.

Navigate to the URL (i.e. request the URL using a simple GET request).

Wait for status: "Succeeded" in the JSON response.

The result will contain a URL to the HTTP Live Streaming (HLS) file:

https://upcdn.io/W142hJk/audio/example.mp3?f=hls-aac&br=80&br=256

{
  "jobUrl": "https://api.bytescale.com/v2/accounts/W142hJk/jobs/ProcessFileJob/01H3211XMV1VH829RV697VE3WM",
  "jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
  "jobId": "01H3211XMV1VH829RV697VE3WM",
  "jobType": "ProcessFileJob",
  "accountId": "W142hJk",
  "created": 1686916626075,
  "lastUpdated": 1686916669389,
  "status": "Succeeded",
  "summary": {
    "result": {
      "type": "Artifact",
      "artifact": "/audio.m3u8",
      "artifactUrl": "https://upcdn.io/W142hJk/audio/example.mp3!f=hls-aac&br=80&br=256&a=/audio.m3u8"
    }
  }
}

Example #6: Creating HLS audio with real-time encoding

Real-time encoding allows you to return HLS manifests (.m3u8 files) while they're being transcoded.

The benefit of real-time encoding is the ability to play web-optimized audio files within seconds of uploading them, rather than having to wait for audio transcoding jobs to complete.

To create HTTP Live Streaming (HLS) audio with real-time encoding:

Complete the steps from creating HLS audio.

Replace f=hls-aac with f=hls-aac-rt.

The result will be an M3U8 file that's dynamically updated as new segments finish transcoding:

https://upcdn.io/W142hJk/audio/example.mp4?f=hls-aac-rt

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-STREAM-INF:BANDWIDTH=2038521,AVERAGE-BANDWIDTH=2038521,CODECS="mp4a.40.2"
example.mp3!f=hls-aac-rt&a=/0f/manifest.m3u8

Example #7: Extracting audio metadata

The Audio Metadata API allows you to extract the audio file's duration, codec, and more.

To extract an audio file's duration using JavaScript:

<!DOCTYPE html>
<html>
<body>
  <p>Please wait, loading audio metadata...</p>
  <script>
    async function getAudioDuration() {
      const response = await fetch("https://upcdn.io/W142hJk/audio/example.mp4?f=meta");
      const jsonData = await response.json();
      const audioTrack = (jsonData.tracks ?? []).find(x => x.type === "Audio");
      if (audioTrack === undefined) {
        alert("Cannot find audio metadata.")
      }
      else {
        alert(`Duration (seconds): ${audioTrack.duration}`)
      }
    }
    getAudioDuration().then(() => {}, e => alert(`Error: ${e}`))
  </script>
</body>
</html>

Supported Inputs

The Audio Processing API can transcode audio from video and audio files:

Supported Input Audio

The Audio Processing API can transcode audio from the following audio inputs:

File Extension(s)	Audio Container	Audio Codecs
.wma, .asf	Advanced Systems Format (ASF)	WMA, WMA2, WMA Pro
.fla, .flac	FLAC	FLAC
.mp3	MPEG-1 Layer 3	MP3
.ts, .m2ts	MPEG-2 TS	MP2, PCM
.aac, .mp4, .m4a	MPEG-4	AAC
.mka	Matroska Audio Container	Opus, FLAC
.oga	OGA	Opus, Vorbis, FLAC
.wav	Waveform Audio File	PCM

Supported Input Videos

The Audio Processing API can transcode audio from the following video inputs:

File Extension(s)	Video Container	Video Codecs
.m2v, .mpeg, .mpg	No Container	AVC (H.264), DV/DVCPRO, HEVC (H.265), MPEG-1, MPEG-2
.3g2	3G2	AVC (H.264), H.263, MPEG-4 part 2
.3gp	3GP	AVC (H.264), H.263, MPEG-4 part 2
.wmv	Advanced Systems Format (ASF)	VC-1
.flv	Adobe Flash	AVC (H.264), Flash 9 File, H.263
.avi	Audio Video Interleave (AVI)	Uncompressed, Canopus HQ, DivX/Xvid, DV/DVCPRO, MJPEG
.m3u8	HLS (MPEG-2 TS segments)	AVC (H.264), HEVC (H.265), MPEG-2
.mxf	Interoperable Master Format (IMF)	Apple ProRes, JPEG 2000 (J2K)
.mxf	Material Exchange Format (MXF)	Uncompressed, AVC (H.264), AVC Intra 50/100, Apple ProRes (4444, 4444 XQ, 422, 422 HQ, LT, Proxy), DV/DVCPRO, DV25, DV50, DVCPro HD, JPEG 2000 (J2K), MPEG-2, Panasonic P2, SonyXDCam, SonyXDCam MPEG-4 Proxy, VC-3
.mkv	Matroska	AVC (H.264), MPEG-2, MPEG-4 part 2, PCM, VC-1
.mpg, .mpeg, .m2p, .ps	MPEG Program Streams (MPEG-PS)	MPEG-2
.m2t, .ts, .tsv	MPEG Transport Streams (MPEG-TS)	AVC (H.264), HEVC (H.265), MPEG-2, VC-1
.dat, .m1v, .mpeg, .mpg, .mpv	MPEG-1 System Streams	MPEG-1, MPEG-2
.mp4, .mpeg4	MPEG-4	Uncompressed, DivX/Xvid, H.261, H.262, H.263, AVC (H.264), AVC Intra 50/100, HEVC (H.265), JPEG 2000, MPEG-2, MPEG-4 part 2, VC-1
.mov, .qt	QuickTime	Uncompressed, Apple ProRes (4444, 4444 XQ, 422, 422 HQ, LT, Proxy), DV/DVCPRO, DivX/Xvid, H.261, H.262, H.263, AVC (H.264), AVC Intra 50/100, HEVC (H.265), JPEG 2000 (J2K), MJPEG, MPEG-2, MPEG-4 part 2, QuickTime Animation (RLE)
.webm	WebM	VP8, VP9

Audio Metadata API

Use the Audio Metadata API to extract the duration, codec, and other information from an audio file.

Instructions:

Replace raw with audio in your audio URL.
Append ?f=meta to the URL.
The result will be a JSON payload describing the audio's tracks (see below).

Example audio metadata JSON response:

{
  "tracks": [
    {
      "bitRate": 159980,
      "bitRateMode": "VBR",
      "channels": 2,
      "codec": "AAC",
      "codecId": "mp4a-40-2",
      "frameCount": 35875,
      "frameRate": 46.875,
      "samplingRate": 48000,
      "title": "Stereo",
      "type": "Audio"
    }
  ]
}

Audio Transcoding API

Use the Audio Transcoding API to transcode your audio to a specific format.

Output Format f

Use the f parameter to change the output format of the audio:

Format	Transcoding	Compression	Browser Support
f=mp3	async	good	all
f=aac	async	excellent	all
f=wav-riff	async	none	none
f=wav-rf64	async	none	none
f=hls-aac	async	excellent	requires SDK
f=hls-aac-rt	real-time	excellent	requires SDK

Which output format should I use?

Use f=hls-aac-rt to create web-optimized audio that plays while it's being transcoded.

Omit the f parameter to get a shareable link to your audio (encoded in AAC).

Which audio SDK should I use?

For f=hls-* formats you need to use an audio player SDK that supports HLS (e.g. Video.js). For other formats you can use HTML5's <audio> element.

What is async transcoding?

Asynchronous transcoding means Bytescale will return a JSON response that initially contains "status": "Running". You must poll the URL until "status": "Succeeded" is returned, at which point the JSON response will contain the URL to the encoded audio.

What is real-time transcoding?

Real-time transcoding means Bytescale will stream the audio to your device while it's being transcoded: instead of receiving a JSON response you will receive an M3U8 response. This allows you to start playing transcoded audio within seconds of uploading it.