SupAudio

The SupAudio object represents an audio file. It can be created from either a URL or a Blob.

Example Audio

SupAudio: {
  filename: "a.mp3",
  url: "https://user-uploads.cdn.overworld.xyz/k49lv3f90remnuqln1i8xt9p.mp3"
}

---

Properties

name

type: string | undefined

The original filename of the audio file, if available.

url

type: string

Gets the CDN URL for the audio file. If the audio was created from a Blob, the Blob will be automatically uploaded and a URL will be generated.

blob

type: Blob

Gets the audio data as a Blob. If the audio was created from a URL, the audio will be downloaded and returned as a Blob.

---

Output

Returning an Audio from a patch’s main() function will display an audio player in the message.

function main() {
  return sup.audio(
    "https://user-uploads.cdn.overworld.xyz/k49lv3f90remnuqln1i8xt9p.mp3"
  );
}

---

Editing

Use the edit() method to modify a SupAudio. This returns an editing cursor that supports transformations and effects. After queueing up edits on the cursor, call cursor.render() to get a new SupAudio with the changes applied.

function main() {
  const audio = sup.input.audio;
  if (!audio) return "Please attach an audio file";

  const cursor = audio.edit();

  // Time modifications
  cursor.trimStart(1.5); // Remove first 1.5 seconds
  cursor.trimEnd(1.0); // Remove last second
  cursor.padStart(0.5); // Add 0.5 seconds silence at start
  cursor.padEnd(1.0); // Add 1 second silence at end
  cursor.fadeIn(1.0); // Fade in over 1 second
  cursor.fadeOut(1.0); // Fade out over 1 second
  cursor.reverse(); // Reverse audio

  // Audio adjustments
  cursor.changeSpeed(1.5);
  cursor.changeTempo(1.25);
  cursor.changePitch(100);
  cursor.changeVolume(2);
  cursor.normalize();

  // Effects
  cursor.reverb(50, {
    roomScale: 75,
    stereoDepth: 50,
    preDelay: 20,
  });
  cursor.echo(0.5, 0.3, {
    delay: 0.1,
    decay: 0.5,
  });
  cursor.chorus(0.6, 0.4, {
    speed: 1.5,
    depth: 2,
  });

  return cursor.render();
}

Basic adjustments

• trimStart(seconds: number)

  • Removes audio from the start

• trimEnd(seconds: number)

  • Removes audio from the end

• padStart(seconds: number)

  • Adds silence at the start

• padEnd(seconds: number)

  • Adds silence at the end

• fadeIn(seconds: number)

  • Fades in the audio

• fadeOut(seconds: number)

  • Fades out the audio

• reverse()

  • Reverses the audio

• changeSpeed(factor: number)

  • Changes playback speed (0.01-5)

• changeTempo(factor: number)

  • Changes tempo without altering pitch (0.01-5)

• changePitch(change: number)

  • Changes pitch (-2000 to 2000 cents)

• changeVolume(gain: number)

  • Changes volume (-20 to 20 dB)

• normalize()

  • Normalizes audio levels

Effects

• reverb(reverberance: number, options: object)

  • Adds reverb effect

  options: {
    hfDamping?: number;   // 0-100
    roomScale?: number;   // 0-100
    stereoDepth?: number; // 0-100
    preDelay?: number;    // 0-200ms
    wetGain?: number;     // -10 to 10dB
  }

• echo(gainIn: number, gainOut: number, options: object)

  • Adds echo effect

  options: {
    delay?: number; // >0 seconds
    decay?: number; // 0-1
  }

• chorus(gainIn: number, gainOut: number, options: object)

  • Adds chorus effect

  options: {
    delay?: number;  // >0 seconds
    decay?: number;  // 0-1
    speed?: number;  // 0.1-5 Hz
    depth?: number;  // 0-10
  }

Combining Audio

Use mixWith() to overlay multiple on top of each other, or combineWith() to concatenate them. Call render() to get the final result.

function main() {
  const audio1 = sup.input.audio;
  const audio2 = sup.audio("track2.mp3");    // track2.mp3 uploaded as an asset

  const cursor = audio1.edit();

  // Mix tracks together
  cursor.mixWith(audio2);

  // Or concatenate tracks
  cursor.combineWith(audio2);

  return cursor.render();   // Returns a SupAudio
}