crunker

Crunker provides several example use-cases to demonstrate how to apply the library in different environments (client-side vs. server-side) and for different purposes (audio manipulation vs. beat building).

Each sub-directory in the examples/ folder contains full source code and instructions for local execution. For quick visual reference, you can use the hosted live demos:

• Audio from Client: Demonstrates client-side audio processing.
• Audio from Server: Demonstrates server-side audio processing.
• Beat Builder: Demonstrates using Crunker to construct rhythmic patterns.

You can install Crunker using either yarn or npm.

yarn add crunker

npm install crunker

The project provides an ESM (ECMAScript Modules) build of crunker. This build is configured via Webpack to output a module-based library located at dist/crunker.esm.js. This version is intended for use in environments that support native ES modules.

// The resulting build produces:
// Path: dist/crunker.esm.js
// Format: ESM Module

Trim an AudioBuffer to a specific range. You can optionally apply a fade-in at the start and a fade-out at the end to prevent audible clicks.

/**
 * @param {AudioBuffer} buffer - The audio buffer to be trimmed.
 * @param {number} start - Starting second.
 * @param {number} end - Ending second.
 * @param {number} [fadeIn=0] - Seconds for fade-in.
 * @param {number} [fadeOut=0] - Seconds for fade-out.
 * @returns {Promise<AudioBuffer>} 
 */
crunker.sliceAudio(buffer, start, end, fadeIn, fadeOut);

Add silence to an AudioBuffer at the beginning, the end, or any specified point.

// buffer: The AudioBuffer to pad
// padStart: Boolean or position
// seconds: Duration of silence
crunker.padAudio(buffer, padStart, seconds);

Starts playing the provided AudioBuffer in the background.

// Returns the HTMLAudioElement
crunker.play(buffer);

Concatenate multiple AudioBuffer objects in the specified order. This appends the audio files one after another.

crunker.concatAudio(arrayOfBuffers)
  .then((concatenated) => {
    // concatenated is a single AudioBuffer
  });

Convert an AudioBuffer into a downloadable format.

IMPORTANT: The MIME type provided (e.g., 'audio/mp3') does not change the actual file encoding; the output will always be a WAVE file under the hood.

// Returns an object: { blob, element, url }
crunker.export(buffer, 'audio/mp3')
  .then((output) => {
    console.log(output.url);
    document.body.append(output.element);
  });

Execute a callback function if the user's browser does not support the Web Audio API.

crunker.notSupported(() => {
  console.error('Web Audio API is not supported in this browser.');
});

Use fetchAudio() to load one or more audio files from URLs or file objects. It returns a Promise that resolves to an array of AudioBuffer objects in the order they were requested.

// Fetching from URLs
crunker.fetchAudio('/song.mp3', '/another-song.mp3')
  .then((buffers) => {
    // buffers is [AudioBuffer, AudioBuffer]
  });

// Fetching from File objects (e.g., from an <input type="file">)
const onFileInputChange = async (target) => {
  const buffers = await crunker.fetchAudio(...target.files, '/voice.mp3');
};

Trigger an automatic download of an exported audio blob.

// filename should NOT include the extension (e.g., use 'mysong', not 'mysong.mp3')
crunker.download(output.blob, 'my-awesome-song');

Initialize a new instance of Crunker. You can optionally provide a configuration object with a sampleRate key. If omitted, it defaults to the sample rate of the internal AudioContext used by the device.

let crunker = new Crunker();

// With custom sample rate
let crunker = new Crunker({ sampleRate: 44100 });